Document mappings.json format.

README.md

@@ -489,6 +489,53 @@ node scripts/generate-markdown-table.js
 
 ## Contributing
 
+
+### mappings.json format
+
+The `mappings.json` file contains an array of entries with the following format:
+
+```ts
+interface Mapping {
+  /**
+    The globals based API that this module and export replace.
+   */
+  global: string;
+
+  /**
+    The module to import.
+   */
+  module: string;
+
+  /**
+    The export name from the module.
+   */
+  export: string;
+
+  /**
+    `true` if this module / export combination has been deprecated.
+   */
+  deprecated: boolean;
+
+  /**
+    The recommended `localName` to use for a given module/export. Only present
+    when a name other than the value for `export` should be used.
+
+    This is useful for things like ember-modules-codemod or eslint-plugin-ember
+    so that they can provide a nice suggested import for a given global path usage.
+   */
+  localName?: string;
+
+  /**
+    When this mapping is deprecated it may include a replacement module/export which
+    should be used instead.
+  */
+  replacement?: {
+    module: string;
+    export: string;
+  }
+}
+```
+
 ### Module Changes
 
 If you want to change how globals are mapped into modules, you will find

mappings.json

@@ -74,7 +74,7 @@
     "global": "Ember.Array",
     "module": "@ember/array",
     "export": "default",
-    "localName": "Array",
+    "localName": "EmberArray",
     "deprecated": false
   },
   {
@@ -263,7 +263,7 @@
     "global": "Ember.Error",
     "module": "@ember/error",
     "export": "default",
-    "localName": "Error",
+    "localName": "EmberError",
     "deprecated": false
   },
   {
@@ -294,7 +294,7 @@
     "global": "Ember.Map",
     "module": "@ember/map",
     "export": "default",
-    "localName": "Map",
+    "localName": "EmberMap",
     "deprecated": false
   },
   {
@@ -308,7 +308,7 @@
     "global": "Ember.Object",
     "module": "@ember/object",
     "export": "default",
-    "localName": "Object",
+    "localName": "EmberObject",
     "deprecated": false
   },
   {
@@ -2484,4 +2484,4 @@
     "export": "resolve",
     "deprecated": false
   }
-]
+]

reserved.json

@@ -36,7 +36,6 @@
   "Atomics",
   "DataView",
   "JSON",
-  "Promise",
   "Generator",
   "GeneratorFunction",
   "Reflect",

scripts/reformat-mappings.js

@@ -0,0 +1,46 @@
+const fs = require('fs');
+const mappings = require('../mappings');
+const reserved = require('../reserved');
+const { compare } = require('./shared');
+
+function sortByModuleAndExport(mappingA, mappingB) {
+  if (mappingA.module === mappingB.module) {
+    // ensure default exports sort higher within a package
+    let aExport = mappingA.export === 'default' ? '' : mappingA.export;
+    let bExport = mappingB.export === 'default' ? '' : mappingB.export;
+    return compare(aExport || '', bExport || '');
+  }
+
+  return compare(mappingA.module, mappingB.module);
+}
+
+let updated = mappings.sort(sortByModuleAndExport).map(mapping => {
+  let localName = mapping.localName || mapping.export;
+
+  // ensure localName is set when a reserved word collides
+  if (reserved.includes(localName)) {
+    localName = 'Ember' + localName;
+  }
+
+  // remove localName when it matches export
+  if (localName === mapping.export) {
+    localName = undefined;
+  }
+
+  // return a new object so that all of the properties in the JSON
+  // are in the same order
+  let ret = {
+    global: mapping.global,
+    module: mapping.module,
+    export: mapping.export,
+    localName,
+    deprecated: !!mapping.deprecated,
+    replacement: mapping.replacement,
+  };
+
+  return ret;
+});
+
+fs.writeFileSync('mappings.json', JSON.stringify(updated, null, 2) + '\n', {
+  encoding: 'utf-8',
+});

tests/validate-mapping-format.test.js

@@ -0,0 +1,22 @@
+const mappings = require('../mappings.json');
+
+for (let mapping of mappings) {
+  describe('Validate mapping format', () => {
+    test(`${mapping.global} - ${mapping.module} - ${mapping.export}`, () => {
+      expect(mapping.global).toMatch(/.+/);
+      expect(mapping.module).toMatch(/.+/);
+      expect(mapping.export).toMatch(/.+/);
+      expect([true, false]).toContain(mapping.deprecated);
+
+      if ('localName' in mapping) {
+        // when present ensure it is a valid string
+        expect(mapping.localName).toMatch(/.+/);
+      }
+
+      if ('replacement' in mapping) {
+        expect(mapping.replacement.module).toMatch(/.+/);
+        expect(mapping.replacement.export).toMatch(/.+/);
+      }
+    });
+  });
+}