feat(bundle-source): Special case for development condition (#2375)

## Description

From `bundle-source`, a bundle cannot currently take on a dependency on
any of the packages entrained by `devDependencies` in the `package.json`
of the entry package. This change (indirectly) enables a bundle to
capture dev dependencies by providing the flag `--condition development`
from the [`-C` flag introduced in
#2373](#2373)

### Security Considerations

None.

### Scaling Considerations

None.

### Documentation Considerations

- NEWS
- README
- USAGE

### Testing Considerations

Existing tests adjusted to exercise the new condition instead of the
explicit `dev` flag.

### Compatibility Considerations

Backward-compatibility verified by running tests before and after
switching from the explicit `dev` flag to a `development` condition in
the compartment mapper.

No integration test provided, but can be manually verified by bundling a
package that relies on a devDependency and providing `-C development`.

### Upgrade Considerations

None.

packages/bundle-source/NEWS.md

@@ -13,6 +13,8 @@
 - Adds a no-cache, bundle-to-stdout mode.
 - Adds a `-C,--condition` command flag to specify export/import conditions like
   `"development"` or `"browser"`.
+- The `-C development` condition now provides access to `devDependencies` in
+  the `package.json` of the entry package of a bundle.
 
 # v3.2.1 (2024-03-20)
 

packages/bundle-source/README.md

@@ -29,6 +29,19 @@ by the `moduleFormat` below.
 The resulting bundle is suitable for use with `@endo/import-bundle`.
 The default format is of a bundle is `"endoZipBase64"`.
 
+## Conditions
+
+Node.js introduced [conditions](https://nodejs.org/api/packages.html#conditional-exports).
+The `--condition` and `-C` flags accordingly influence `bundle-source` module
+resolution decisions.
+
+The `browser` condition additionally implies the selection of the `browser`
+entry instead of `main` in `package.json`, if not overridden by explicit
+`exports`.
+
+The `development` condition additionally implies that the bundle may import
+`devDependencies` from the package containing the entry module.
+
 ## Source maps
 
 With the `moduleFormat` of `endoZipBase64`, the bundler can generate source

packages/bundle-source/src/main.js

@@ -12,6 +12,7 @@ bundle-source [-Tft] <entry.js>
 bundle-source [-Tft] --cache-js|--cache-json <cache/> (<entry.js> <bundle-name>)*
   -f,--format endoZipBase64*|nestedEvaluate|getExport
   -C,--condition <condition> (browser, node, development, &c)
+  -C development (to access devDependencies)
   -T,--no-transforms`;
 
 const options = /** @type {const} */ ({

packages/compartment-mapper/NEWS.md

@@ -24,6 +24,9 @@ User-visible changes to the compartment mapper:
 - Adds JSON module support to `makeBundle`.
 - Aliases and deprecates `tags` in favor of `conditions` to align with Node.js
   terminology.
+- `mapNodeModules` now infers that it should include `devDependencies` from
+  the entry package from the presence of `"development"` in `conditions`,
+  if the `dev` option is abseent.
 
 # 0.9.0 (2023-08-07)
 

packages/compartment-mapper/src/node-modules.js

@@ -277,7 +277,7 @@ const inferParsers = (
  * @param {string} packageDetails.packageLocation
  * @param {object} packageDetails.packageDescriptor
  * @param {Set<string>} conditions
- * @param {boolean} dev
+ * @param {boolean | undefined} dev
  * @param {CommonDependencyDescriptors} commonDependencyDescriptors
  * @param {Map<string, Array<string>>} preferredPackageLogicalPathMap
  * @param {Array<string>} logicalPath
@@ -342,7 +342,7 @@ const graphPackage = async (
   for (const name of Object.keys(optionalDependencies)) {
     optionals.add(name);
   }
-  if (dev) {
+  if (dev !== undefined && dev !== null ? dev : conditions.has('development')) {
     assign(allDependencies, devDependencies);
   }
 
@@ -524,7 +524,7 @@ const gatherDependency = async (
  * @param {Set<string>} conditions
  * @param {object} mainPackageDescriptor - the parsed contents of the main
  * package.json, which was already read when searching for the package.json.
- * @param {boolean} dev - whether to use devDependencies from this package (and
+ * @param {boolean|undefined} dev - whether to use devDependencies from this package (and
  * only this package).
  * @param {Record<string,string>} [commonDependencies] - dependencies to be added to all packages
  */
@@ -757,7 +757,7 @@ export const compartmentMapForNodeModules = async (
   moduleSpecifier,
   options = {},
 ) => {
-  const { dev = false, commonDependencies, policy } = options;
+  const { dev = undefined, commonDependencies, policy } = options;
   const { maybeRead, canonical } = unpackReadPowers(readPowers);
   const graph = await graphPackages(
     maybeRead,
@@ -815,7 +815,7 @@ export const mapNodeModules = async (
   const {
     tags = new Set(),
     conditions = tags,
-    dev = false,
+    dev = undefined,
     commonDependencies,
     policy,
   } = options;

packages/compartment-mapper/test/app.agar-make.js

@@ -30,7 +30,7 @@ const mitt = err =>
   });
 
 writeArchive(write, readPowers, archiveFixture, fixture, {
-  dev: true,
+  conditions: new Set(['development']),
   modules: {
     builtin: true,
   },

packages/compartment-mapper/test/integrity.test.js

@@ -15,7 +15,7 @@ test('extracting an archive with a superfluous file', async t => {
     modules: {
       builtin: null,
     },
-    dev: true,
+    conditions: new Set(['development']),
   });
 
   const reader = new ZipReader(validBytes);
@@ -46,7 +46,7 @@ test('extracting an archive with a missing file', async t => {
     modules: {
       builtin: null,
     },
-    dev: true,
+    conditions: new Set(['development']),
   });
 
   const reader = new ZipReader(validBytes);
@@ -77,7 +77,7 @@ test('extracting an archive with an inconsistent hash', async t => {
     modules: {
       builtin: null,
     },
-    dev: true,
+    conditions: new Set(['development']),
   });
 
   const reader = new ZipReader(validBytes);
@@ -114,7 +114,7 @@ test('extracting an archive with an inconsistent compartment map hash', async t
       modules: {
         builtin: null,
       },
-      dev: true,
+      conditions: new Set(['development']),
     });
 
   const { sha512: verifiedSha512 } = await parseArchive(

packages/compartment-mapper/test/main.test.js

@@ -156,7 +156,7 @@ test('no transitive dev dependencies', async t => {
         readPowers,
         noTransitiveDevDepencenciesFixture,
         {
-          dev: true,
+          conditions: new Set(['development']),
         },
       );
       await application.import({

packages/compartment-mapper/test/scaffold.js

@@ -129,9 +129,8 @@ export function scaffold(
     await setup();
 
     const application = await loadLocation(readPowers, fixture, {
-      dev: true,
       policy,
-      conditions,
+      conditions: new Set(['development', ...(conditions || [])]),
       searchSuffixes,
       commonDependencies,
       ...additionalOptions,
@@ -154,8 +153,7 @@ export function scaffold(
       policy,
       modules,
       Compartment,
-      dev: true,
-      conditions,
+      conditions: new Set(['development', ...(conditions || [])]),
       searchSuffixes,
       commonDependencies,
       ...additionalOptions,
@@ -171,9 +169,8 @@ export function scaffold(
 
       const archive = await makeArchive(readPowers, fixture, {
         modules,
-        dev: true,
         policy,
-        conditions,
+        conditions: new Set(['development', ...(conditions || [])]),
         searchSuffixes,
         commonDependencies,
         ...additionalOptions,
@@ -208,9 +205,8 @@ export function scaffold(
       // Zip files support an arbitrary length prefix.
       const archive = await makeArchive(readPowers, fixture, {
         modules,
-        dev: true,
         policy,
-        conditions,
+        conditions: new Set(['development', ...(conditions || [])]),
         searchSuffixes,
         commonDependencies,
         ...additionalOptions,
@@ -253,9 +249,8 @@ export function scaffold(
 
       await writeArchive(fakeWrite, readPowers, 'app.agar', fixture, {
         modules: { builtin: true },
-        dev: true,
         policy,
-        conditions,
+        conditions: new Set(['development', ...(conditions || [])]),
         searchSuffixes,
         commonDependencies,
         ...additionalOptions,
@@ -307,8 +302,7 @@ export function scaffold(
       await writeArchive(fakeWrite, readPowers, 'app.agar', fixture, {
         policy,
         modules,
-        dev: true,
-        conditions,
+        conditions: new Set(['development', ...(conditions || [])]),
         searchSuffixes,
         commonDependencies,
         sourceMapHook,
@@ -344,17 +338,15 @@ export function scaffold(
       const expectedSha512 = await hashLocation(readPowers, fixture, {
         modules,
         Compartment,
-        dev: true,
-        conditions,
+        conditions: new Set(['development', ...(conditions || [])]),
         searchSuffixes,
         commonDependencies,
         ...additionalOptions,
       });
 
       const archiveBytes = await makeArchive(readPowers, fixture, {
         modules,
-        dev: true,
-        conditions,
+        conditions: new Set(['development', ...(conditions || [])]),
         searchSuffixes,
         commonDependencies,
         ...additionalOptions,
@@ -366,8 +358,7 @@ export function scaffold(
         'memory:app.agar',
         {
           modules,
-          dev: true,
-          conditions,
+          conditions: new Set(['development', ...(conditions || [])]),
           computeSha512,
           expectedSha512,
           ...additionalOptions,
@@ -384,17 +375,15 @@ export function scaffold(
       const expectedSha512 = await hashLocation(readPowers, fixture, {
         modules,
         Compartment,
-        dev: true,
-        conditions,
+        conditions: new Set(['development', ...(conditions || [])]),
         searchSuffixes,
         commonDependencies,
         ...additionalOptions,
       });
 
       const archive = await makeArchive(readPowers, fixture, {
         modules,
-        dev: true,
-        conditions,
+        conditions: new Set(['development', ...(conditions || [])]),
         searchSuffixes,
         commonDependencies,
         ...additionalOptions,