Improve bower2buck instructions

Instead of requiring a target, default to //polygerrit-ui/...; this
package and subpackages have several bower_components rules, and
using all of them is most likely to produce all the existing rules in
lib/js/BUCK.

Rewrite instructions in lib/js/BUCK so they are more copy-and-
pasteable. Add instructions to the generated new BUCK file on how to
merge with an existing BUCK file.

Normalize the existing package names so there's less delta on each
diff.

Change-Id: I5f46d4d06d6aaacf40c9a7771eec6e85710093e1

lib/js/BUCK

@@ -28,10 +28,12 @@ npm_binary(
   repository = GERRIT,
 )
 
-# To add a new Bower component dependency:
+# ## Adding Bower component dependencies
+#
+# 1. Add a dummy bower_component rule to this file, specifying the semantic
+#    version you want to use. The actual version will be filled in by Bower,
+#    after evaluating the full dependency tree.
 #
-# 1. Add a dummy bower_component rule to this file, specifying the version you
-#    want to use:
 #      bower_component(
 #        name = 'somepackage',
 #        package = 'someauthor/somepackage',
@@ -40,28 +42,35 @@ npm_binary(
 #        license = 'DO_NOT_DISTRIBUTE'
 #      )
 #
-# 2. Add your bower_component as a dep to a bower_components rule:
+# 2. Add your bower_component as a dep to a bower_components rule.
+#
 #      bower_components(
-#        name = 'my_components',
+#        name = 'polygerrit_components',
 #        deps = [
 #          '//lib/js:foo',
 #          '//lib/js:somepackage',  # NEW
 #        ],
 #      )
 #
-# 3. Run bower2buck.py:
-#      buck run //tools/js:bower2buck.py -o newbuck //path/to:my_components
+# 3. Run bower2buck.py.
+#
+#      buck run //tools/js:bower2buck -- -o /tmp/newbuck
 #
 # 4. Use your favorite diff tool to merge the output in newbuck with this file.
-#    bower2buck.py reevaluates semantic versions and may upgrade some packages,
-#    so you may need to make changes beyond the new component that was added.
+#    bower2buck reevaluates semantic versions and may upgrade some packages, so
+#    you may need to make changes beyond the new component that was added.
 #
-# 5. Make sure to specify licenses for all new packages. You may need to define
-#    new licenses in lib/BUCK.
+#      meld /tmp/newbuck lib/js/BUCK
+#
+#
+# ## Updating Bower component dependencies
+#
+# Use the same procedure as for adding dependencies, except just change the
+# version number of the existing bower_component rather than adding a new rule.
 
 bower_component(
   name = 'iron-a11y-keys',
-  package = 'PolymerElements/iron-a11y-keys',
+  package = 'polymerelements/iron-a11y-keys',
   version = '1.0.3',
   deps = [
     ':iron-a11y-keys-behavior',
@@ -73,7 +82,7 @@ bower_component(
 
 bower_component(
   name = 'iron-a11y-keys-behavior',
-  package = 'PolymerElements/iron-a11y-keys-behavior',
+  package = 'polymerelements/iron-a11y-keys-behavior',
   version = '1.0.8',
   deps = [':polymer'],
   license = 'polymer',
@@ -82,7 +91,7 @@ bower_component(
 
 bower_component(
   name = 'iron-ajax',
-  package = 'PolymerElements/iron-ajax',
+  package = 'polymerelements/iron-ajax',
   version = '1.1.0',
   deps = [
     ':polymer',
@@ -94,7 +103,7 @@ bower_component(
 
 bower_component(
   name = 'iron-input',
-  package = 'PolymerElements/iron-input',
+  package = 'polymerelements/iron-input',
   version = '1.0.6',
   deps = [
     ':iron-validatable-behavior',
@@ -106,7 +115,7 @@ bower_component(
 
 bower_component(
   name = 'iron-meta',
-  package = 'PolymerElements/iron-meta',
+  package = 'polymerelements/iron-meta',
   version = '1.1.1',
   deps = [':polymer'],
   license = 'polymer',
@@ -115,7 +124,7 @@ bower_component(
 
 bower_component(
   name = 'iron-test-helpers',
-  package = 'PolymerElements/iron-test-helpers',
+  package = 'polymerelements/iron-test-helpers',
   version = '1.0.6',
   semver = '~1.0.6',
   deps = [':polymer'],
@@ -125,7 +134,7 @@ bower_component(
 
 bower_component(
   name = 'iron-validatable-behavior',
-  package = 'PolymerElements/iron-validatable-behavior',
+  package = 'polymerelements/iron-validatable-behavior',
   version = '1.0.5',
   deps = [
     ':iron-meta',
@@ -145,7 +154,7 @@ bower_component(
 
 bower_component(
   name = 'polymer',
-  package = 'Polymer/polymer',
+  package = 'polymer/polymer',
   version = '1.2.2',
   deps = [':webcomponentsjs'],
   license = 'polymer',
@@ -163,7 +172,7 @@ bower_component(
 
 bower_component(
   name = 'test-fixture',
-  package = 'PolymerElements/test-fixture',
+  package = 'polymerelements/test-fixture',
   version = '1.0.3',
   semver = '^1.0.0',
   license = 'DO_NOT_DISTRIBUTE',

tools/js/bower2buck.py

@@ -34,9 +34,38 @@ from tools import util
 BUCK_ENV = dict(os.environ)
 BUCK_ENV['NO_BUCKD'] = '1'
 
+HEADER = """\
+include_defs('//lib/js.defs')
+
+# AUTOGENERATED BY BOWER2BUCK
+#
+# This file should be merged with an existing BUCK file containing these rules.
+#
+# This comment SHOULD NOT be copied to the existing BUCK file, and you should
+# leave alone any non-bower_component contents of the file.
+#
+# Generally, the following attributes SHOULD be copied from this file to the
+# existing BUCK file:
+#  - package: the normalized package name
+#  - version: the exact version number
+#  - deps: direct dependencies of the package
+#  - sha1: a hash of the package contents
+#
+# The following fields SHOULD NOT be copied to the existing BUCK file:
+#  - semver: manually-specified semantic version, not included in autogenerated
+#    output.
+#
+# The following fields require SPECIAL HANDLING:
+#  - license: all licenses in this file are specified as TODO. You must replace
+#    this text with one of the existing licenses defined in lib/BUCK, or
+#    define a new one if necessary. Leave existing licenses alone.
+
+"""
+
 
 def usage():
-  print('Usage: %s -o <outfile> //path/to:bower_components_rule' % sys.argv[0],
+  print(('Usage: %s -o <outfile> [//path/to:bower_components_rule...]'
+         % sys.argv[0]),
         file=sys.stderr)
   return 1
 
@@ -76,18 +105,18 @@ class Rule(object):
     return '\n'.join(lines)
 
 
-def build_bower_json(target, buck_out):
-  name = target[target.find(':')+1:]
+def build_bower_json(targets, buck_out):
   bower_json = collections.OrderedDict()
-  bower_json['name'] = name
+  bower_json['name'] = 'bower2buck-output'
   bower_json['version'] = '0.0.0'
   bower_json['description'] = 'Auto-generated bower.json for dependency management'
   bower_json['private'] = True
   bower_json['dependencies'] = {}
 
-  deps = subprocess.check_output([
-      'buck', 'query', '-v', '0',
-      "filter('__download_bower', deps(%s))" % target], env=BUCK_ENV)
+  deps = subprocess.check_output(
+      ['buck', 'query', '-v', '0',
+       "filter('__download_bower', deps(%s))" % '+'.join(targets)],
+      env=BUCK_ENV)
   deps = deps.replace('__download_bower', '__bower_version').split()
   subprocess.check_call(['buck', 'build'] + deps, env=BUCK_ENV)
 
@@ -157,18 +186,19 @@ def main(args):
   opts.add_option('-o', help='output file location')
   opts, args = opts.parse_args()
 
-  if len(args) != 1 or not args[0].startswith('//') or not opts.o:
+  if not opts.o or not all(a.startswith('//') for a in args):
     return usage()
   outfile = os.path.abspath(opts.o)
   buck_out = find_buck_out()
 
-  target = args[0]
-  bower_json_path = build_bower_json(target, buck_out)
+  targets = args if args else ['//polygerrit-ui/...']
+  bower_json_path = build_bower_json(targets, buck_out)
   os.chdir(os.path.dirname(bower_json_path))
   packages = get_packages(bower_json_path)
   rules = collect_rules(packages)
 
   with open(outfile, 'w') as f:
+    f.write(HEADER)
     for _, r in sorted(rules.iteritems()):
       f.write('\n\n%s' % r.to_rule(packages))