feat(jsii): enforce peer dependencies (#294)

Elad Ben-Israel · web-flow · commit 17539102383b · 2018-11-06T18:08:46.000+02:00
If a jsii module exposes a type from a dependency in it's public API, jsii now enforces that this dependency is also defined as a "peer" instead of a normal dependency. This tells npm that if a user of this module already installed a compatible verison of this dependency in their closure, npm will pick the one installed by the user (as a peer) instead of fetching another version. jsii will also flag these dependencies as "peer" in the jsii spec. At the moment, this won't have implications on generated language packages, but in environments that have support for peer dependencies, we should make sure the module's metadata reflects this idea as well. A utility called "jsii-fix-peers" is included. It will inspect .jsii and package.json and will add "peerDependencies" to package.json for all dependencies that have types in the public API. Related to aws/aws-cdk#979
diff --git a/package-lock.json b/package-lock.json
diff --git a/packages/jsii-calc-base/package.json b/packages/jsii-calc-base/package.json
@@ -34,6 +34,9 @@
   "dependencies": {
     "@scope/jsii-calc-base-of-base": "^0.7.8"
   },
+  "peerDependencies": {
+    "@scope/jsii-calc-base-of-base": "^0.7.8"
+  },
   "author": {
     "name": "Amazon Web Services",
     "url": "https://aws.amazon.com",
diff --git a/packages/jsii-calc-base/test/assembly.jsii b/packages/jsii-calc-base/test/assembly.jsii
@@ -9,6 +9,7 @@
   },
   "dependencies": {
     "@scope/jsii-calc-base-of-base": {
+      "peer": true,
       "targets": {
         "dotnet": {
           "namespace": "Amazon.JSII.Tests.CalculatorNamespace.BaseOfBaseNamespace",
@@ -102,5 +103,5 @@
     }
   },
   "version": "0.7.8",
-  "fingerprint": "G+ZeFV6LQWFdp9ZuDgqN4rS10q/JBHuy0Wo8qaTK/t8="
+  "fingerprint": "K1rAUs6WiQ5lF08T46B8v/5UL8T8Ot59e0Nc8rh2jiQ="
 }
diff --git a/packages/jsii-calc-lib/package.json b/packages/jsii-calc-lib/package.json
@@ -34,6 +34,9 @@
   "dependencies": {
     "@scope/jsii-calc-base": "^0.7.8"
   },
+  "peerDependencies": {
+    "@scope/jsii-calc-base": "^0.7.8"
+  },
   "author": {
     "name": "Amazon Web Services",
     "url": "https://aws.amazon.com",
diff --git a/packages/jsii-calc-lib/test/assembly.jsii b/packages/jsii-calc-lib/test/assembly.jsii
@@ -11,6 +11,7 @@
     "@scope/jsii-calc-base": {
       "dependencies": {
         "@scope/jsii-calc-base-of-base": {
+          "peer": true,
           "targets": {
             "dotnet": {
               "namespace": "Amazon.JSII.Tests.CalculatorNamespace.BaseOfBaseNamespace",
@@ -30,6 +31,7 @@
           "version": "0.7.8"
         }
       },
+      "peer": true,
       "targets": {
         "dotnet": {
           "namespace": "Amazon.JSII.Tests.CalculatorNamespace.BaseNamespace",
@@ -351,5 +353,5 @@
     }
   },
   "version": "0.7.8",
-  "fingerprint": "HzcyHys0b9gFmP4dogeIJmGE6GVtrSo/P0S54Vd/X8U="
+  "fingerprint": "ENH00UDSeTnXKpvD3/vp0k8zyd+KCHzc9QWB151/gM8="
 }
diff --git a/packages/jsii-calc/package.json b/packages/jsii-calc/package.json
@@ -35,6 +35,10 @@
     "@scope/jsii-calc-lib": "^0.7.8",
     "jsii-calc-bundled": "^0.7.8"
   },
+  "peerDependencies": {
+    "@scope/jsii-calc-base": "^0.7.8",
+    "@scope/jsii-calc-lib": "^0.7.8"
+  },
   "devDependencies": {
     "@types/node": "^8.10.37",
     "jsii": "^0.7.8",
diff --git a/packages/jsii-calc/test/assembly.jsii b/packages/jsii-calc/test/assembly.jsii
@@ -37,6 +37,7 @@
     "@scope/jsii-calc-base": {
       "dependencies": {
         "@scope/jsii-calc-base-of-base": {
+          "peer": true,
           "targets": {
             "dotnet": {
               "namespace": "Amazon.JSII.Tests.CalculatorNamespace.BaseOfBaseNamespace",
@@ -56,6 +57,7 @@
           "version": "0.7.8"
         }
       },
+      "peer": true,
       "targets": {
         "dotnet": {
           "namespace": "Amazon.JSII.Tests.CalculatorNamespace.BaseNamespace",
@@ -79,6 +81,7 @@
         "@scope/jsii-calc-base": {
           "dependencies": {
             "@scope/jsii-calc-base-of-base": {
+              "peer": true,
               "targets": {
                 "dotnet": {
                   "namespace": "Amazon.JSII.Tests.CalculatorNamespace.BaseOfBaseNamespace",
@@ -98,6 +101,7 @@
               "version": "0.7.8"
             }
           },
+          "peer": true,
           "targets": {
             "dotnet": {
               "namespace": "Amazon.JSII.Tests.CalculatorNamespace.BaseNamespace",
@@ -117,6 +121,7 @@
           "version": "0.7.8"
         }
       },
+      "peer": true,
       "targets": {
         "dotnet": {
           "namespace": "Amazon.JSII.Tests.CalculatorNamespace.LibNamespace",
@@ -3407,5 +3412,5 @@
     }
   },
   "version": "0.7.8",
-  "fingerprint": "jHSXTzCSZbwYMvLKpeZB6SE8hNgYgt9/2JF1ihM41SI="
+  "fingerprint": "Xn7Rk17rqR3AaMx3+ssxT0GR1sCWwz0OGC+C8QuLI3A="
 }
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc-base/dotnet/Amazon.JSII.Tests.CalculatorPackageId.BasePackageId/.jsii b/packages/jsii-pacmak/test/expected.jsii-calc-base/dotnet/Amazon.JSII.Tests.CalculatorPackageId.BasePackageId/.jsii
@@ -9,6 +9,7 @@
   },
   "dependencies": {
     "@scope/jsii-calc-base-of-base": {
+      "peer": true,
       "targets": {
         "dotnet": {
           "namespace": "Amazon.JSII.Tests.CalculatorNamespace.BaseOfBaseNamespace",
@@ -102,5 +103,5 @@
     }
   },
   "version": "0.7.8",
-  "fingerprint": "G+ZeFV6LQWFdp9ZuDgqN4rS10q/JBHuy0Wo8qaTK/t8="
+  "fingerprint": "K1rAUs6WiQ5lF08T46B8v/5UL8T8Ot59e0Nc8rh2jiQ="
 }
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc-lib/dotnet/Amazon.JSII.Tests.CalculatorPackageId.LibPackageId/.jsii b/packages/jsii-pacmak/test/expected.jsii-calc-lib/dotnet/Amazon.JSII.Tests.CalculatorPackageId.LibPackageId/.jsii
@@ -11,6 +11,7 @@
     "@scope/jsii-calc-base": {
       "dependencies": {
         "@scope/jsii-calc-base-of-base": {
+          "peer": true,
           "targets": {
             "dotnet": {
               "namespace": "Amazon.JSII.Tests.CalculatorNamespace.BaseOfBaseNamespace",
@@ -30,6 +31,7 @@
           "version": "0.7.8"
         }
       },
+      "peer": true,
       "targets": {
         "dotnet": {
           "namespace": "Amazon.JSII.Tests.CalculatorNamespace.BaseNamespace",
@@ -351,5 +353,5 @@
     }
   },
   "version": "0.7.8",
-  "fingerprint": "HzcyHys0b9gFmP4dogeIJmGE6GVtrSo/P0S54Vd/X8U="
+  "fingerprint": "ENH00UDSeTnXKpvD3/vp0k8zyd+KCHzc9QWB151/gM8="
 }
diff --git a/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/.jsii b/packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/.jsii
@@ -37,6 +37,7 @@
     "@scope/jsii-calc-base": {
       "dependencies": {
         "@scope/jsii-calc-base-of-base": {
+          "peer": true,
           "targets": {
             "dotnet": {
               "namespace": "Amazon.JSII.Tests.CalculatorNamespace.BaseOfBaseNamespace",
@@ -56,6 +57,7 @@
           "version": "0.7.8"
         }
       },
+      "peer": true,
       "targets": {
         "dotnet": {
           "namespace": "Amazon.JSII.Tests.CalculatorNamespace.BaseNamespace",
@@ -79,6 +81,7 @@
         "@scope/jsii-calc-base": {
           "dependencies": {
             "@scope/jsii-calc-base-of-base": {
+              "peer": true,
               "targets": {
                 "dotnet": {
                   "namespace": "Amazon.JSII.Tests.CalculatorNamespace.BaseOfBaseNamespace",
@@ -98,6 +101,7 @@
               "version": "0.7.8"
             }
           },
+          "peer": true,
           "targets": {
             "dotnet": {
               "namespace": "Amazon.JSII.Tests.CalculatorNamespace.BaseNamespace",
@@ -117,6 +121,7 @@
           "version": "0.7.8"
         }
       },
+      "peer": true,
       "targets": {
         "dotnet": {
           "namespace": "Amazon.JSII.Tests.CalculatorNamespace.LibNamespace",
@@ -3407,5 +3412,5 @@
     }
   },
   "version": "0.7.8",
-  "fingerprint": "jHSXTzCSZbwYMvLKpeZB6SE8hNgYgt9/2JF1ihM41SI="
+  "fingerprint": "Xn7Rk17rqR3AaMx3+ssxT0GR1sCWwz0OGC+C8QuLI3A="
 }
diff --git a/packages/jsii-spec/lib/spec.ts b/packages/jsii-spec/lib/spec.ts
@@ -153,6 +153,22 @@ export interface PackageVersion {
 
     /** Dependencies of this dependency */
     dependencies?: { [assembly: string]: PackageVersion };
+
+    /**
+     * Indicates if this dependency is a peer dependency or a normal dependency.
+     *
+     * Peer dependencies are expected to be explicitly defined by the user of
+     * this library instead of brought in as transitive dependencies.
+     *
+     * jsii enforces that if this module exports a type from a dependency, this
+     * dependency must be defined as a peer and not as a normal dependency.
+     * Otherwise, it would be impossible to safely use two versions of this
+     * dependency in a closure.
+     *
+     * @see https://github.com/awslabs/aws-cdk/issues/979
+     * @see https://nodejs.org/en/blog/npm/peer-dependencies/
+     */
+    peer?: boolean;
 }
 
 /**
diff --git a/packages/jsii/bin/jsii-fix-peers b/packages/jsii/bin/jsii-fix-peers
@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require('./jsii-fix-peers.js');
diff --git a/packages/jsii/bin/jsii-fix-peers.ts b/packages/jsii/bin/jsii-fix-peers.ts
@@ -0,0 +1,95 @@
+//
+// jsii-fix-peers
+//
+// Inspects the local .jsii file and adds "peerDependencies" to the local
+// package.json for all modules that include types that are referenced as part
+// of the current module's public API.
+//
+// This resolves all peer dependency warnings emitted by the jsii compiler.
+//
+
+// tslint:disable:no-console
+
+import fs = require('fs-extra');
+import spec = require('jsii-spec');
+
+fixPeers().catch(e => {
+  console.error(e.stack);
+  process.exit(1);
+});
+
+async function fixPeers() {
+  const jsiiFile = './.jsii';
+  const pkgFile = './package.json';
+
+  if (!(await fs.pathExists(jsiiFile))) {
+    throw new Error(`Cannot find '${jsiiFile}. Make sure to compile first`);
+  }
+
+  if (!(await fs.pathExists(pkgFile))) {
+    throw new Error(`Cannot find '${pkgFile}' in current working directory`);
+  }
+
+  const jsii = await fs.readJson(jsiiFile) as spec.Assembly;
+  const pkg = await fs.readJson(pkgFile);
+
+  // find all type references (FQNs) in the assembly.
+  const fqns = findAllFQNs(jsii);
+
+  let updated = false;
+
+  // read "dependencies" and "peerDependencies" from package.json
+  if (!pkg.peerDependencies) { pkg.peerDependencies = {}; }
+  const peers = pkg.peerDependencies;
+  const deps = pkg.dependencies || {};
+
+  // iterate over all FQNs and ensure that all referenced modules appear as peer dependencies
+  for (const fqn of fqns) {
+    const [ module, ] = fqn.split('.');
+    if (module === jsii.name) {
+      continue;
+    }
+
+    // verify that `module` exists in peerDependencies
+    if (module in peers) {
+      continue;
+    }
+
+    // fetch the module's version requirement from "dependencies" (we expect it to be there)
+    const dep = deps[module];
+    if (!dep) {
+      throw new Error(`Cannot find ${module} neither under "peerDependencies" nor "dependencies". Can't fix.`);
+    }
+
+    // fixing time! add this module to "peerDependencies"
+    peers[module] = dep;
+    console.log(`added ${module}@${dep} to "peerDependencies"`);
+    updated = true;
+  }
+
+  if (updated) {
+    await fs.writeJson(pkgFile, pkg, { spaces: 2 });
+  }
+}
+
+/**
+ * Looks up all { "fqn": "boom" } objects in a JSON tree.
+ * @param node Initial node (i.e. a JSII assembly)
+ * @param out Used by the recursive call to collect outputs
+ */
+function findAllFQNs(node: any, out = new Set<string>()) {
+  if (typeof(node) === 'object' && 'fqn' in node) {
+    out.add(node.fqn);
+  }
+
+  for (const key of Object.keys(node)) {
+    const value = node[key];
+    if (Array.isArray(value)) {
+      value.forEach(v => findAllFQNs(v, out));
+    } else if (typeof(value) === 'object') {
+      findAllFQNs(value, out);
+    }
+  }
+
+  return Array.from(out);
+}
diff --git a/packages/jsii/lib/assembler.ts b/packages/jsii/lib/assembler.ts
diff --git a/packages/jsii/lib/project-info.ts b/packages/jsii/lib/project-info.ts
diff --git a/packages/jsii/package.json b/packages/jsii/package.json
diff --git a/packages/jsii/test/test.negatives.ts b/packages/jsii/test/test.negatives.ts

Original file line number	Diff line number	Diff line change
`@@ -9,6 +9,7 @@`
`9`	`9`	`},`
`10`	`10`	`"dependencies": {`
`11`	`11`	`"@scope/jsii-calc-base-of-base": {`
	`12`	`+ "peer": true,`
`12`	`13`	`"targets": {`
`13`	`14`	`"dotnet": {`
`14`	`15`	`"namespace": "Amazon.JSII.Tests.CalculatorNamespace.BaseOfBaseNamespace",`
`@@ -102,5 +103,5 @@`
`102`	`103`	`}`
`103`	`104`	`},`
`104`	`105`	`"version": "0.7.8",`
`105`		`- "fingerprint": "G+ZeFV6LQWFdp9ZuDgqN4rS10q/JBHuy0Wo8qaTK/t8="`
	`106`	`+ "fingerprint": "K1rAUs6WiQ5lF08T46B8v/5UL8T8Ot59e0Nc8rh2jiQ="`
`106`	`107`	`}`