lookup: deprecate and rename "master" field to "head" (#848)

Patch the lookup object in memory for backwards-compatibility.

Author: targos

README.md

@@ -127,7 +127,7 @@ For syntax, see [lookup.json](./lib/lookup.json), the available attributes are:
 
 ```
 "npm": true                  Download the module from npm instead of github
-"master": true               Use the master branch
+"head": true                 Use the head of the default branch
 "prefix": "v"                Specify the prefix used in the module version.
 "flaky": true                Ignore failures
 "skip": true                 Completely skip the module

lib/lookup.js

@@ -12,7 +12,7 @@ function makeUrl(repo, spec, tags, prefix, sha) {
   let version;
   if (!spec)
     // Spec should already have defaulted to latest.
-    version = 'master';
+    version = 'HEAD';
   else if (tags[spec]) version = tags[spec];
   // Matches npm tags like 'latest' or 'next'.
   // `spec` must match one of `meta.versions` as npm info call passed.
@@ -30,7 +30,7 @@ function makeUrl(repo, spec, tags, prefix, sha) {
 
 function makeClone(repo, spec, tags, prefix) {
   let version;
-  if (!spec) version = 'master';
+  if (!spec) version = 'HEAD';
   else version = (prefix || '') + tags[spec];
   return {
     url: `${repo}.git`,
@@ -56,7 +56,27 @@ function getLookupTable(options) {
     if (typeof options.lookup === 'string') {
       name = path.resolve(process.cwd(), options.lookup);
     }
-    return require(name);
+    const lookup = require(name);
+
+    // Backwards-compatibility: replace "master" key with "head".
+    let warningEmitted = false;
+    for (const moduleName of Object.keys(lookup)) {
+      const moduleConfig = lookup[moduleName];
+      if (moduleConfig.master !== undefined) {
+        if (!warningEmitted) {
+          process.emitWarning(
+            'The "master" key in lookup entries is deprecated. Use "head" instead. ' +
+              `Found in "${name}" for module "${moduleName}".`,
+            'DeprecationWarning'
+          );
+          warningEmitted = true;
+        }
+        moduleConfig.head = moduleConfig.master;
+        delete moduleConfig.master;
+      }
+    }
+
+    return lookup;
   } catch (err) {
     return undefined;
   }
@@ -107,7 +127,7 @@ function resolve(context) {
         if (rep.useGitClone) {
           const { url, ref } = makeClone(
             getRepo(rep.repo, meta),
-            rep.master ? null : detail.fetchSpec,
+            rep.head ? null : detail.fetchSpec,
             meta['dist-tags'],
             rep.prefix
           );
@@ -121,12 +141,12 @@ function resolve(context) {
           context.module.raw = url;
           context.module.ref = ref;
         } else {
-          const gitHead = rep.master || rep.ignoreGitHead ? null : meta.gitHead;
+          const gitHead = rep.head || rep.ignoreGitHead ? null : meta.gitHead;
           const url = makeUrl(
             getRepo(rep.repo, meta),
-            rep.master ? null : detail.fetchSpec,
+            rep.head ? null : detail.fetchSpec,
             meta['dist-tags'],
-            rep.master ? null : rep.prefix,
+            rep.head ? null : rep.prefix,
             context.options.sha || rep.sha || gitHead
           );
           context.emit(

lib/lookup.json

@@ -84,7 +84,7 @@
   },
   "cheerio": {
     "skip": "win32",
-    "master": true,
+    "head": true,
     "maintainers": ["matthewmueller", "jugglinmike"]
   },
   "clinic": {
@@ -136,7 +136,7 @@
     "envVar": { "YARN_IGNORE_ENGINES": "true" },
     "prefix": "v",
     "flaky": ["win32", "rhel", "sles"],
-    "master": true,
+    "head": true,
     "expectFail": "fips",
     "maintainers": ["stefanpenner", "rwjblue", "Turbo87", "kellyselden"]
   },
@@ -300,7 +300,7 @@
     "maintainers": "substack"
   },
   "mkdirp": {
-    "master": true,
+    "head": true,
     "skip": true,
     "maintainers": "substack"
   },
@@ -447,7 +447,7 @@
   },
   "socket.io": {
     "maintainers": "rauchg",
-    "master": true
+    "head": true
   },
   "spawn-wrap": {
     "prefix": "v",
@@ -470,7 +470,7 @@
   "split2": {
     "prefix": "v",
     "maintainers": "mcollina",
-    "master": true
+    "head": true
   },
   "sqlite3": {
     "prefix": "v",
@@ -542,7 +542,7 @@
   },
   "vinyl-fs": {
     "prefix": "v",
-    "master": true,
+    "head": true,
     "maintainers": ["contra", "phated"],
     "skip": true
   },

test/fixtures/custom-lookup-log.json

@@ -1,7 +1,7 @@
 {
   "omg-i-pass": {
     "install": ["--extra-param"],
-    "master": true,
+    "head": true,
     "replace": true,
     "repo": "https://github.com/nodejs/citgm"
   }

test/test-lookup.js

@@ -20,9 +20,9 @@ test('lookup: makeUrl', (t) => {
 
   const sha = 'abc123';
 
-  let expected = `${repo}/archive/master.tar.gz`;
+  let expected = `${repo}/archive/HEAD.tar.gz`;
   let url = makeUrl(repo);
-  t.equal(url, expected, 'by default makeUrl should give a link to master');
+  t.equal(url, expected, 'by default makeUrl should give a link to HEAD');
 
   expected = `${repo}/archive/${tags.latest}.tar.gz`;
   url = makeUrl(repo, 'latest', tags);
@@ -171,7 +171,7 @@ test('lookup: module in table', (t) => {
   lookup(context);
   t.equals(
     context.module.raw,
-    'https://github.com/lodash/lodash/archive/master.tar.gz',
+    'https://github.com/lodash/lodash/archive/HEAD.tar.gz',
     'raw should be truthy if the module was in the list'
   );
   t.end();
@@ -404,7 +404,7 @@ test('lookup: logging', (t) => {
     {
       type: 'info',
       key: 'omg-i-pass lookup-replace',
-      msg: 'https://github.com/nodejs/citgm/archive/master.tar.gz'
+      msg: 'https://github.com/nodejs/citgm/archive/HEAD.tar.gz'
     },
     {
       type: 'verbose',