@endo/compartment-mapper 1.6.0 → 1.6.1

package/src/import-hook.js

@@ -1,11 +1,13 @@
 /**
- * @module Provides the implementation of each compartment's `importHook` when
+ * Provides the implementation of each compartment's `importHook` when
  * using `import.js`, `import-lite.js`, `archive.js`, or `archive-lite.js`.
  * However, `import-archive.js` and `import-archive-lite.js` use their own
  * variant.
  *
  * For building archives, these import hooks create a table of all the modules
  * in a "working set" of transitive dependencies.
+ *
+ * @module
  */
 
 /**
@@ -13,7 +15,8 @@
  *   ImportHook,
  *   ImportNowHook,
  *   RedirectStaticModuleInterface,
- *   StaticModuleType
+ *   StaticModuleType,
+ *   VirtualModuleSource
  * } from 'ses'
  * @import {
  *   CompartmentDescriptor,
@@ -22,7 +25,6 @@
  *   ChooseModuleDescriptorYieldables,
  *   ExitModuleImportHook,
  *   FindRedirectParams,
- *   HashFn,
  *   ImportHookMaker,
  *   ImportNowHookMaker,
  *   MakeImportHookMakerOptions,
@@ -31,9 +33,10 @@
  *   ParseResult,
  *   ReadFn,
  *   ReadPowers,
- *   SourceMapHook,
- *   Sources,
- *   ReadNowPowers
+ *   ReadNowPowers,
+ *   StrictlyRequiredFn,
+ *   CompartmentSources,
+ *   DeferErrorFn
  * } from './types.js'
  */
 
@@ -93,6 +96,32 @@ const nodejsConventionSearchSuffixes = [
   '/index.node',
 ];
 
+/**
+ * Returns `true` if `absoluteModuleSpecifier` is within the path `compartmentLocation`.
+ * @param {string} absoluteModudeSpecifier Absolute path to module specifier
+ * @param {string} compartmentLocation Absolute path to compartment location
+ * @returns {boolean}
+ */
+const isLocationWithinCompartment = (
+  absoluteModudeSpecifier,
+  compartmentLocation,
+) => absoluteModudeSpecifier.startsWith(compartmentLocation);
+
+/**
+ * Computes the relative path to a module from its compartment location (including a leading `./`)
+ *
+ * @param {string} absoluteModuleSpecifier Absolute path (not URL) to a module specifier
+ * @param {string} compartmentLocation Absolute path to compartment location
+ * @returns {string} Redirect static module interface; the `specifier` prop of this value _must_ be a relative path with leading `./`
+ */
+const relativeSpecifier = (absoluteModuleSpecifier, compartmentLocation) => {
+  assert(
+    isLocationWithinCompartment(absoluteModuleSpecifier, compartmentLocation),
+    `Module specifier location "${absoluteModuleSpecifier}" does not start with compartment location "${compartmentLocation}"`,
+  );
+  return `./${absoluteModuleSpecifier.substring(compartmentLocation.length)}`;
+};
+
 /**
  * Given a module specifier which is an absolute path, attempt to match it with
  * an existing compartment; return a {@link RedirectStaticModuleInterface} if found.
@@ -106,12 +135,9 @@ const findRedirect = ({
   compartmentDescriptors,
   compartments,
   absoluteModuleSpecifier,
-  packageLocation,
 }) => {
-  const moduleSpecifierLocation = new URL(
-    absoluteModuleSpecifier,
-    packageLocation,
-  ).href;
+  const moduleSpecifierLocation = new URL(absoluteModuleSpecifier, 'file:')
+    .href;
 
   // a file:// URL string
   let someLocation = new URL('./', moduleSpecifierLocation).href;
@@ -137,7 +163,7 @@ const findRedirect = ({
       // is a dependency of the compartment descriptor
       if (compartmentDescriptor.compartments.has(location)) {
         return {
-          specifier: absoluteModuleSpecifier,
+          specifier: relativeSpecifier(moduleSpecifierLocation, location),
           compartment: compartments[location],
         };
       }
@@ -158,7 +184,7 @@ const findRedirect = ({
           },
         );
         return {
-          specifier: absoluteModuleSpecifier,
+          specifier: relativeSpecifier(moduleSpecifierLocation, location),
           compartment: compartments[location],
         };
       }
@@ -402,6 +428,54 @@ function* chooseModuleDescriptor(
   return undefined;
 }
 
+/**
+ * Creates a `deferError` function which decides whether to throw immediately or
+ * at execution time.
+ *
+ * @param {StrictlyRequiredFn} strictlyRequiredForCompartment
+ * @param {string} packageLocation
+ * @param {CompartmentSources} packageSources
+ * @returns {DeferErrorFn}
+ */
+const makeDeferError = (
+  strictlyRequiredForCompartment,
+  packageLocation,
+  packageSources,
+) => {
+  /**
+   * @param {string} specifier
+   * @param {Error} error - error to throw on execute
+   * @returns {StaticModuleType}
+   */
+  const deferError = (specifier, error) => {
+    // strictlyRequired is populated with imports declared by modules whose parser is not using heuristics to figure
+    // out imports. We're guaranteed they're reachable. If the same module is imported and required, it will not
+    // defer, because importing from esm makes it strictly required.
+    // Note that ultimately a situation may arise, with exit modules, where the module never reaches importHook but
+    // its imports do. In that case the notion of strictly required is no longer boolean, it's true,false,noidea.
+    if (strictlyRequiredForCompartment(packageLocation).has(specifier)) {
+      throw error;
+    }
+    // Return a place-holder that'd throw an error if executed
+    // This allows cjs parser to more eagerly find calls to require
+    // - if parser identified a require call that's a local function, execute will never be called
+    // - if actual required module is missing, the error will happen anyway - at execution time
+    const record = freeze({
+      imports: [],
+      exports: [],
+      execute: () => {
+        throw error;
+      },
+    });
+    packageSources[specifier] = {
+      deferredError: error.message,
+    };
+
+    return record;
+  };
+  return deferError;
+};
+
 /**
  * @param {ReadFn|ReadPowers} readPowers
  * @param {string} baseLocation
@@ -461,37 +535,11 @@ export const makeImportHookMaker = (
     const { modules: moduleDescriptors = create(null) } = compartmentDescriptor;
     compartmentDescriptor.modules = moduleDescriptors;
 
-    /**
-     * @param {string} specifier
-     * @param {Error} error - error to throw on execute
-     * @returns {StaticModuleType}
-     */
-    const deferError = (specifier, error) => {
-      // strictlyRequired is populated with imports declared by modules whose parser is not using heuristics to figure
-      // out imports. We're guaranteed they're reachable. If the same module is imported and required, it will not
-      // defer, because importing from esm makes it strictly required.
-      // Note that ultimately a situation may arise, with exit modules, where the module never reaches importHook but
-      // its imports do. In that case the notion of strictly required is no longer boolean, it's true,false,noidea.
-      if (strictlyRequiredForCompartment(packageLocation).has(specifier)) {
-        throw error;
-      }
-      // Return a place-holder that'd throw an error if executed
-      // This allows cjs parser to more eagerly find calls to require
-      // - if parser identified a require call that's a local function, execute will never be called
-      // - if actual required module is missing, the error will happen anyway - at execution time
-      const record = freeze({
-        imports: [],
-        exports: [],
-        execute: () => {
-          throw error;
-        },
-      });
-      packageSources[specifier] = {
-        deferredError: error.message,
-      };
-
-      return record;
-    };
+    const deferError = makeDeferError(
+      strictlyRequiredForCompartment,
+      packageLocation,
+      packageSources,
+    );
 
     /** @type {ImportHook} */
     const importHook = async moduleSpecifier => {
@@ -639,7 +687,55 @@ export function makeImportNowHookMaker(
     packageName: _packageName,
     parse,
     compartments,
+    shouldDeferError,
   }) => {
+    const deferError = makeDeferError(
+      strictlyRequiredForCompartment,
+      packageLocation,
+      sources,
+    );
+
+    /**
+     * Attempt to load the moduleSpecifier via an {@link ExitModuleImportNowHook}, if one exists.
+     *
+     * If it doesn't exist, then throw an exception.
+     * @param {string} moduleSpecifier
+     * @param {CompartmentDescriptor} compartmentDescriptor
+     * @returns {VirtualModuleSource}
+     */
+    const importExitModuleOrFail = (moduleSpecifier, compartmentDescriptor) => {
+      if (exitModuleImportNowHook) {
+        // This hook is responsible for ensuring that the moduleSpecifier
+        // actually refers to an exit module.
+        const exitRecord = exitModuleImportNowHook(
+          moduleSpecifier,
+          packageLocation,
+        );
+        if (exitRecord) {
+          // It'd be nice to check the policy before importing it, but we can only throw a policy error if the
+          // hook returns something. Otherwise, we need to fall back to the 'cannot find' error below.
+          enforceModulePolicy(moduleSpecifier, compartmentDescriptor, {
+            exit: true,
+            errorHint: `Blocked in loading. ${q(
+              moduleSpecifier,
+            )} was not in the compartment map and an attempt was made to load it as a builtin`,
+          });
+          return exitRecord;
+        }
+        throw Error(
+          `Cannot find external module ${q(
+            moduleSpecifier,
+          )} in package at ${packageLocation}`,
+        );
+      } else {
+        throw Error(
+          `Cannot find external module ${q(
+            moduleSpecifier,
+          )} from package at ${packageLocation}; try providing an importNowHook`,
+        );
+      }
+    };
+
     if (!('isSyncParser' in parse)) {
       return function impossibleTransformImportNowHook() {
         throw new Error(
@@ -684,70 +780,79 @@ export function makeImportNowHookMaker(
 
     /** @type {ImportNowHook} */
     const importNowHook = moduleSpecifier => {
-      if (isAbsolute(moduleSpecifier)) {
-        const record = findRedirect({
-          compartmentDescriptor,
-          compartmentDescriptors,
-          compartments,
-          absoluteModuleSpecifier: moduleSpecifier,
-          packageLocation,
-        });
-        if (record) {
-          return record;
-        }
-      }
+      try {
+        // many dynamically-required specifiers will be absolute paths owing to use of `require.resolve()` and `path.resolve()`
+        if (isAbsolute(moduleSpecifier)) {
+          const record = findRedirect({
+            compartmentDescriptor,
+            compartmentDescriptors,
+            compartments,
+            absoluteModuleSpecifier: moduleSpecifier,
+          });
+          if (record) {
+            return record;
+          }
 
-      const candidates = nominateCandidates(moduleSpecifier, searchSuffixes);
-
-      const record = syncTrampoline(
-        chooseModuleDescriptor,
-        {
-          candidates,
-          compartmentDescriptor,
-          compartmentDescriptors,
-          compartments,
-          computeSha512,
-          moduleDescriptors,
-          moduleSpecifier,
-          packageLocation,
-          packageSources,
-          readPowers,
-          archiveOnly,
-          sourceMapHook,
-          strictlyRequiredForCompartment,
-        },
-        {
-          maybeRead: maybeReadNow,
-          parse,
-        },
-      );
+          // if and only if the module specifier is within the compartment can we
+          // make it a relative specifier. the following conditional avoids a try/catch
+          // since `relativeSpecifier` will throw if this condition is not met
+          if (
+            isLocationWithinCompartment(
+              moduleSpecifier,
+              compartmentDescriptor.location,
+            )
+          ) {
+            moduleSpecifier = relativeSpecifier(
+              moduleSpecifier,
+              compartmentDescriptor.location,
+            );
+          }
+        } else if (
+          moduleSpecifier !== '.' &&
+          !moduleSpecifier.startsWith('./')
+        ) {
+          // could be a builtin, which means we should not bother bouncing on the trampoline to find it.
+          return importExitModuleOrFail(moduleSpecifier, compartmentDescriptor);
+        }
 
-      if (record) {
-        return record;
-      }
+        // we might have an absolute path here, but it might be within the compartment, so
+        // we will try to find it.
+        const candidates = nominateCandidates(moduleSpecifier, searchSuffixes);
 
-      if (exitModuleImportNowHook) {
-        // This hook is responsible for ensuring that the moduleSpecifier
-        // actually refers to an exit module.
-        const exitRecord = exitModuleImportNowHook(
-          moduleSpecifier,
-          packageLocation,
+        const record = syncTrampoline(
+          chooseModuleDescriptor,
+          {
+            candidates,
+            compartmentDescriptor,
+            compartmentDescriptors,
+            compartments,
+            computeSha512,
+            moduleDescriptors,
+            moduleSpecifier,
+            packageLocation,
+            packageSources,
+            readPowers,
+            archiveOnly,
+            sourceMapHook,
+            strictlyRequiredForCompartment,
+          },
+          {
+            maybeRead: maybeReadNow,
+            parse,
+            shouldDeferError,
+          },
         );
 
-        if (!exitRecord) {
-          throw new Error(`Could not import module: ${q(moduleSpecifier)}`);
+        if (record) {
+          return record;
         }
 
-        return exitRecord;
+        // at this point, we haven't found the module by guessing, so we'll try the importer-of-last-resort
+        return importExitModuleOrFail(moduleSpecifier, compartmentDescriptor);
+      } catch (err) {
+        return deferError(moduleSpecifier, err);
       }
-
-      throw new Error(
-        `Could not import module: ${q(
-          moduleSpecifier,
-        )}; try providing an importNowHook`,
-      );
     };
-
     return importNowHook;
   };
   return makeImportNowHook;

package/src/import-lite.d.ts

@@ -14,7 +14,7 @@ export function loadFromMap(readPowers: ReadNowPowers, compartmentMap: Compartme
  * @returns {Promise<Application>}
  */
 export function loadFromMap(readPowers: ReadFn | ReadPowers, compartmentMap: CompartmentMapDescriptor, opts?: ImportLocationOptions | undefined): Promise<Application>;
-export function importFromMap(readPowers: ReadFn | ReadPowers, compartmentMap: CompartmentMapDescriptor, options?: ImportLocationOptions | undefined): Promise<SomeObject>;
+export function importFromMap(readPowers: ReadFn | ReadPowers, compartmentMap: CompartmentMapDescriptor, options?: ImportLocationOptions): Promise<SomeObject>;
 import type { ReadNowPowers } from './types.js';
 import type { CompartmentMapDescriptor } from './types.js';
 import type { SyncImportLocationOptions } from './types.js';

package/src/import-lite.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"import-lite.d.ts","sourceRoot":"","sources":["import-lite.js"],"names":[],"mappings":";;;;;;;AAuEG,wCACQ,aAAa,kBACb,wBAAwB,iDAEtB,OAAO,CAAC,WAAW,CAAC,CAChC;;;;;;;;AAGE,wCACQ,MAAM,GAAG,UAAU,kBACnB,wBAAwB,6CAEtB,OAAO,CAAC,WAAW,CAAC,CAChC;AA4JM,0CANI,MAAM,GAAG,UAAU,kBACnB,wBAAwB,gDAEtB,OAAO,CAAC,UAAU,CAAC,CAU/B;mCAxNS,YAAY;8CAAZ,YAAY;+CAAZ,YAAY;iCAAZ,YAAY;4BAAZ,YAAY;gCAAZ,YAAY;2CAAZ,YAAY;gCAAZ,YAAY"}
+{"version":3,"file":"import-lite.d.ts","sourceRoot":"","sources":["import-lite.js"],"names":[],"mappings":";;;;;;;AAyEG,wCACQ,aAAa,kBACb,wBAAwB,iDAEtB,OAAO,CAAC,WAAW,CAAC,CAChC;;;;;;;;AAGE,wCACQ,MAAM,GAAG,UAAU,kBACnB,wBAAwB,6CAEtB,OAAO,CAAC,WAAW,CAAC,CAChC;AA4JM,0CANI,MAAM,GAAG,UAAU,kBACnB,wBAAwB,YACxB,qBAAqB,GACnB,OAAO,CAAC,UAAU,CAAC,CAU/B;mCAxNS,YAAY;8CAAZ,YAAY;+CAAZ,YAAY;iCAAZ,YAAY;4BAAZ,YAAY;gCAAZ,YAAY;2CAAZ,YAAY;gCAAZ,YAAY"}

package/src/import-lite.js

@@ -1,5 +1,5 @@
 /**
- * @module Provides functions for evaluating a module and its transitive
+ * Provides functions for evaluating a module and its transitive
  * dependencies given a partially completed compartment map.
  * The compartment map needs to describe every reachable compartment, where to
  * find modules in that compartment, and how to link modules between
@@ -13,6 +13,8 @@
  * The default `parserForLanguage` mapping is empty.
  * You will need to provide the `defaultParserForLanguage` from
  * `@endo/compartment-mapper/import-parsers.js` or similar.
+ *
+ * @module
  */
 
 /* eslint no-shadow: "off" */

package/src/import.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"import.d.ts","sourceRoot":"","sources":["import.js"],"names":[],"mappings":";;;;;;;AAiDG,yCACQ,aAAa,kBACb,MAAM,WACN,kBAAkB,GAChB,OAAO,CAAC,WAAW,CAAC,CAChC;;;;;;;;AAGE,yCACQ,MAAM,GAAG,UAAU,kBACnB,MAAM,8CAEJ,OAAO,CAAC,WAAW,CAAC,CAChC;;;;;;;;;;;AAuDE,2CACQ,aAAa,kBACb,MAAM,WACN,yBAAyB,GACvB,OAAO,CAAC,UAAU,CAAC,CAE/B;;;;;;;;;;;AAKE,2CACQ,UAAU,GAAC,MAAM,kBACjB,MAAM,gDAEJ,OAAO,CAAC,UAAU,CAAC,CAE/B;mCA7GS,YAAY;wCAAZ,YAAY;iCAAZ,YAAY;4BAAZ,YAAY;gCAAZ,YAAY;yCAAZ,YAAY;+CAAZ,YAAY;gCAAZ,YAAY;2CAAZ,YAAY"}
+{"version":3,"file":"import.d.ts","sourceRoot":"","sources":["import.js"],"names":[],"mappings":";;;;;;;AAmDG,yCACQ,aAAa,kBACb,MAAM,WACN,kBAAkB,GAChB,OAAO,CAAC,WAAW,CAAC,CAChC;;;;;;;;AAGE,yCACQ,MAAM,GAAG,UAAU,kBACnB,MAAM,8CAEJ,OAAO,CAAC,WAAW,CAAC,CAChC;;;;;;;;;;;AAuDE,2CACQ,aAAa,kBACb,MAAM,WACN,yBAAyB,GACvB,OAAO,CAAC,UAAU,CAAC,CAE/B;;;;;;;;;;;AAKE,2CACQ,UAAU,GAAC,MAAM,kBACjB,MAAM,gDAEJ,OAAO,CAAC,UAAU,CAAC,CAE/B;mCA7GS,YAAY;wCAAZ,YAAY;iCAAZ,YAAY;4BAAZ,YAAY;gCAAZ,YAAY;yCAAZ,YAAY;+CAAZ,YAAY;gCAAZ,YAAY;2CAAZ,YAAY"}

package/src/import.js

@@ -1,5 +1,5 @@
 /**
- * @module Provides functions for evaluating a module and its transitive
+ * Provides functions for evaluating a module and its transitive
  * dependencies given the URL of the entry module and assuming packages laid
  * out according to the `node_modules` conventions.
  *
@@ -9,6 +9,8 @@
  *
  * The default `parserForLanguage` is `import-parsers.js`, which is suitable
  * for most cases.
+ *
+ * @module
  */
 
 /**

package/src/infer-exports.d.ts

@@ -1,9 +1,7 @@
-export function inferExportsEntries({ main, module, exports }: {
-    main: string;
-    module?: string | undefined;
-    exports?: object;
-}, conditions: Set<string>, types: LanguageForExtension): Generator<string[], void, any>;
-export function inferExports(descriptor: object, conditions: Set<string>, types: LanguageForExtension): Record<string, string>;
-export function inferExportsAndAliases(descriptor: any, externalAliases: any, internalAliases: any, conditions: any, types: any): void;
+export function inferExportsEntries({ main, module, exports }: PackageDescriptor, conditions: Set<string>, types: LanguageForExtension): Generator<string[], void, any>;
+export function inferExports(descriptor: PackageDescriptor, conditions: Set<string>, types: LanguageForExtension): Record<string, string>;
+export function inferExportsAndAliases(descriptor: PackageDescriptor, externalAliases: Node["externalAliases"], internalAliases: Node["internalAliases"], conditions: Set<string>, types: Record<string, string>): void;
+import type { PackageDescriptor } from './types.js';
 import type { LanguageForExtension } from './types.js';
+import type { Node } from './types/node-modules.js';
 //# sourceMappingURL=infer-exports.d.ts.map

package/src/infer-exports.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"infer-exports.d.ts","sourceRoot":"","sources":["infer-exports.js"],"names":[],"mappings":"AAqHO,+DATJ;IAAkC,IAAI,EAA9B,MAAM;IACqB,MAAM;IACN,OAAO,GAAlC,MAAM;CACd,cAAQ,GAAG,CAAC,MAAM,CAAC,SAEX,oBAAoB,kCA2B9B;AAkBM,yCAPI,MAAM,cACN,GAAG,CAAC,MAAM,CAAC,SAEX,oBAAoB,GAElB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAG8B;AAE1D,uIA2CN;0CApMuC,YAAY"}
+{"version":3,"file":"infer-exports.d.ts","sourceRoot":"","sources":["infer-exports.js"],"names":[],"mappings":"AA4HO,+DAPI,iBAAiB,cACjB,GAAG,CAAC,MAAM,CAAC,SAEX,oBAAoB,kCA2B9B;AAkBM,yCAPI,iBAAiB,cACjB,GAAG,CAAC,MAAM,CAAC,SAEX,oBAAoB,GAElB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAG8B;AAU1D,mDANI,iBAAiB,mBACjB,IAAI,CAAC,iBAAiB,CAAC,mBACvB,IAAI,CAAC,iBAAiB,CAAC,cACvB,GAAG,CAAC,MAAM,CAAC,SACX,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,QA6ChC;uCAhNyD,YAAY;0CAAZ,YAAY;0BAC/C,yBAAyB"}

package/src/infer-exports.js

@@ -1,12 +1,17 @@
 /**
- * @module Provides functions needed by `node-modules.js` for building
+ * Provides functions needed by `node-modules.js` for building
  * inter-compartment linkage according to the specifications in a
  * `package.json` as laid out in the `node_modules` convention.
  * These functions implement the behavior for a package's `"main"`,
  * `"browser"`, `"imports"`, and `"exports"` properties in a `package.json`.
+ *
+ * @module
  */
 
-/** @import {LanguageForExtension} from './types.js' */
+/**
+ * @import {LanguageForExtension, PackageDescriptor} from './types.js'
+ * @import {Node} from './types/node-modules.js'
+ */
 
 import { join, relativize } from './node-module-specifier.js';
 
@@ -81,7 +86,12 @@ function* interpretExports(name, exports, conditions) {
     );
   }
   for (const [key, value] of entries(exports)) {
-    if (key.startsWith('./') || key === '.') {
+    // "./" is explicitly an invalid key, but that doesn't
+    // stop people from trying to use it.
+    if (key === './') {
+      // eslint-disable-next-line no-continue
+      continue; // or no-op
+    } else if (key.startsWith('./') || key === '.') {
       if (name === '.') {
         yield* interpretExports(key, value, conditions);
       } else {
@@ -105,10 +115,7 @@ function* interpretExports(name, exports, conditions) {
  * There may be multiple pairs for a single `name`, but they will be yielded in
  * ascending priority order, and the caller should use the last one that exists.
  *
- * @param {object} packageDescriptor - the parsed body of a package.json file.
- * @param {string} packageDescriptor.main
- * @param {string} [packageDescriptor.module]
- * @param {object} [packageDescriptor.exports]
+ * @param {PackageDescriptor} packageDescriptor - the parsed body of a package.json file.
  * @param {Set<string>} conditions - build conditions about the target environment
  * for selecting relevant exports, e.g., "browser" or "node".
  * @param {LanguageForExtension} types - an object to populate
@@ -149,7 +156,7 @@ export const inferExportsEntries = function* inferExportsEntries(
  * The values are the corresponding module specifiers in the dependency
  * package's module map, like `./index.js`.
  *
- * @param {object} descriptor - the parsed body of a package.json file.
+ * @param {PackageDescriptor} descriptor - the parsed body of a package.json file.
  * @param {Set<string>} conditions - build conditions about the target environment
  * for selecting relevant exports, e.g., "browser" or "node".
  * @param {LanguageForExtension} types - an object to populate
@@ -159,6 +166,14 @@ export const inferExportsEntries = function* inferExportsEntries(
 export const inferExports = (descriptor, conditions, types) =>
   fromEntries(inferExportsEntries(descriptor, conditions, types));
 
+/**
+ *
+ * @param {PackageDescriptor} descriptor
+ * @param {Node['externalAliases']} externalAliases
+ * @param {Node['internalAliases']} internalAliases
+ * @param {Set<string>} conditions
+ * @param {Record<string, string>} types
+ */
 export const inferExportsAndAliases = (
   descriptor,
   externalAliases,

package/src/link.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"link.d.ts","sourceRoot":"","sources":["link.js"],"names":[],"mappings":"AAsPO,sEAJI,wBAAwB,WACxB,WAAW,GACT,UAAU,CA0KtB;AAOM,yCAJI,wBAAwB,WACxB,WAAW,eAIqB;8CA9YjC,YAAY;iCAAZ,YAAY;gCAAZ,YAAY"}
+{"version":3,"file":"link.d.ts","sourceRoot":"","sources":["link.js"],"names":[],"mappings":"AAwPO,sEAJI,wBAAwB,WACxB,WAAW,GACT,UAAU,CA2KtB;AAOM,yCAJI,wBAAwB,WACxB,WAAW,eAIqB;8CA/YjC,YAAY;iCAAZ,YAAY;gCAAZ,YAAY"}

package/src/link.js

@@ -1,11 +1,13 @@
 /**
- * @module Provides the linking behavior shared by all Compartment Mapper
+ * Provides the linking behavior shared by all Compartment Mapper
  * workflows.
  * This involves creating and configuring compartments according to the
  * specifications in a compartment map, and is suitable for compartment maps
  * that just outline the locations of compartments and their inter-linkage and
  * also compartment maps that include every module descriptor in the transitive
  * dependencies of their entry module.
+ *
+ * @module
  */
 
 /**
@@ -344,6 +346,7 @@ export const link = (
       packageName: name,
       parse,
       compartments,
+      shouldDeferError,
     });
 
     const moduleMapHook = makeModuleMapHook(

package/src/map-parser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"map-parser.d.ts","sourceRoot":"","sources":["map-parser.js"],"names":[],"mappings":"AA6SO,+FAHI,qBAAqB,GACnB,YAAY,CA+CxB;2CAvUS,YAAY;kCAAZ,YAAY"}
+{"version":3,"file":"map-parser.d.ts","sourceRoot":"","sources":["map-parser.js"],"names":[],"mappings":"AA2VO,+FAHI,qBAAqB,GACnB,YAAY,CA+CxB;2CAnXS,YAAY;kCAAZ,YAAY"}

package/src/map-parser.js

@@ -1,6 +1,8 @@
 /**
- * @module Exports {@link makeMapParsers}, which creates a function which matches a
+ * Exports {@link makeMapParsers}, which creates a function which matches a
  * module to a parser based on reasons.
+ *
+ * @module
  */
 
 /**
@@ -46,6 +48,48 @@ const has = (object, key) => apply(hasOwnProperty, object, [key]);
  */
 const extensionImpliesLanguage = extension => extension !== 'js';
 
+/**
+ * Produces a `parser` that parses the content of a module according to the
+ * corresponding module language, given the extension of the module specifier
+ * and the configuration of the containing compartment. We do not yet support
+ * import assertions and we do not have a mechanism for validating the MIME type
+ * of the module content against the language implied by the extension or file
+ * name.
+ *
+ * @overload
+ * @param {true} preferSynchronous
+ * @param {Record<string, string>} languageForExtension - maps a file extension
+ * to the corresponding language.
+ * @param {Record<string, string>} languageForModuleSpecifier - In a rare case,
+ * the type of a module is implied by package.json and should not be inferred
+ * from its extension.
+ * @param {ParserForLanguage} parserForLanguage
+ * @param {ModuleTransforms} moduleTransforms
+ * @param {SyncModuleTransforms} syncModuleTransforms
+ * @returns {ParseFn}
+ */
+
+/**
+ * Produces a `parser` that parses the content of a module according to the
+ * corresponding module language, given the extension of the module specifier
+ * and the configuration of the containing compartment. We do not yet support
+ * import assertions and we do not have a mechanism for validating the MIME type
+ * of the module content against the language implied by the extension or file
+ * name.
+ *
+ * @overload
+ * @param {false} preferSynchronous
+ * @param {Record<string, string>} languageForExtension - maps a file extension
+ * to the corresponding language.
+ * @param {Record<string, string>} languageForModuleSpecifier - In a rare case,
+ * the type of a module is implied by package.json and should not be inferred
+ * from its extension.
+ * @param {ParserForLanguage} parserForLanguage
+ * @param {ModuleTransforms} moduleTransforms
+ * @param {SyncModuleTransforms} syncModuleTransforms
+ * @returns {AsyncParseFn}
+ */
+
 /**
  * Produces a `parser` that parses the content of a module according to the
  * corresponding module language, given the extension of the module specifier
@@ -259,10 +303,12 @@ function mapParsers(
   languageForExtension,
   languageForModuleSpecifier,
   parserForLanguage,
-  moduleTransforms = {},
-  syncModuleTransforms = {},
-  preferSynchronous = false,
+  moduleTransforms,
+  syncModuleTransforms,
+  preferSynchronous,
 ) {
+  moduleTransforms = moduleTransforms || {};
+  syncModuleTransforms = syncModuleTransforms || {};
   const languageForExtensionEntries = [];
   const problems = [];
   for (const [extension, language] of entries(languageForExtension)) {
@@ -276,7 +322,7 @@ function mapParsers(
     throw Error(`No parser available for language: ${problems.join(', ')}`);
   }
   return makeExtensionParser(
-    preferSynchronous,
+    /** @type {any} */ (preferSynchronous),
     fromEntries(languageForExtensionEntries),
     languageForModuleSpecifier,
     parserForLanguage,

package/src/node-module-specifier.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"node-module-specifier.d.ts","sourceRoot":"","sources":["node-module-specifier.js"],"names":[],"mappings":"AAwDO,8BAJI,MAAM,YACN,MAAM,GACJ,MAAM,CAiClB;AAeM,2BAJI,MAAM,QACN,MAAM,GACJ,MAAM,CA6BlB;AAaM,iCALI,MAAM,GAEJ,MAAM,CAclB"}
+{"version":3,"file":"node-module-specifier.d.ts","sourceRoot":"","sources":["node-module-specifier.js"],"names":[],"mappings":"AA0DO,8BAJI,MAAM,YACN,MAAM,GACJ,MAAM,CAiClB;AAeM,2BAJI,MAAM,QACN,MAAM,GACJ,MAAM,CA6BlB;AAaM,iCALI,MAAM,GAEJ,MAAM,CAclB"}