@endo/compartment-mapper 1.5.0 → 1.6.1

package/src/capture-lite.d.ts

@@ -1,4 +1,4 @@
-export function captureFromMap(powers: ReadFn | ReadPowers, compartmentMap: CompartmentMapDescriptor, options?: CaptureLiteOptions | undefined): Promise<CaptureResult>;
+export function captureFromMap(powers: ReadFn | ReadPowers, compartmentMap: CompartmentMapDescriptor, options?: CaptureLiteOptions): Promise<CaptureResult>;
 import type { ReadFn } from './types.js';
 import type { ReadPowers } from './types.js';
 import type { CompartmentMapDescriptor } from './types.js';

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

@@ -1 +1 @@
-{"version":3,"file":"capture-lite.d.ts","sourceRoot":"","sources":["capture-lite.js"],"names":[],"mappings":"AAoFO,uCALI,MAAM,GAAG,UAAU,kBACnB,wBAAwB,6CAEtB,OAAO,CAAC,aAAa,CAAC,CAmElC;4BA9GS,YAAY;gCAAZ,YAAY;8CAAZ,YAAY;wCAAZ,YAAY;mCAAZ,YAAY"}
+{"version":3,"file":"capture-lite.d.ts","sourceRoot":"","sources":["capture-lite.js"],"names":[],"mappings":"AAsFO,uCALI,MAAM,GAAG,UAAU,kBACnB,wBAAwB,YACxB,kBAAkB,GAChB,OAAO,CAAC,aAAa,CAAC,CAmElC;4BA9GS,YAAY;gCAAZ,YAAY;8CAAZ,YAAY;wCAAZ,YAAY;mCAAZ,YAAY"}

package/src/capture-lite.js

@@ -1,5 +1,5 @@
 /**
- * @module
+ *
  * This module provides {@link captureFromMap}, which only "captures" the
  * compartment map descriptors and sources from a partially completed
  * compartment map--_without_ creating an archive. The resulting compartment map
@@ -25,6 +25,8 @@
  * contain original sources, so to import the archive with
  * `src/import-archive-lite.js`, you will need to provide the archive parsers
  * and entrain a runtime dependency on Babel.
+ *
+ * @module
  */
 
 /* eslint no-shadow: 0 */
@@ -123,7 +125,7 @@ export const captureFromMap = async (powers, compartmentMap, options = {}) => {
     searchSuffixes,
     entryCompartmentName,
     entryModuleSpecifier,
-    exitModuleImportHook: consolidatedExitModuleImportHook,
+    importHook: consolidatedExitModuleImportHook,
     sourceMapHook,
   });
   // Induce importHook to record all the necessary modules to import the given module specifier.

package/src/compartment-map.d.ts

@@ -1,6 +1,6 @@
 /** @type {(a: string, b: string) => number} */
 export const stringCompare: (a: string, b: string) => number;
 export function pathCompare(a: Array<string> | undefined, b: Array<string> | undefined): number;
-export function assertCompartmentMap(allegedCompartmentMap: unknown, url?: string | undefined): asserts allegedCompartmentMap is CompartmentMapDescriptor;
+export function assertCompartmentMap(allegedCompartmentMap: unknown, url?: string): asserts allegedCompartmentMap is CompartmentMapDescriptor;
 import type { CompartmentMapDescriptor } from './types.js';
 //# sourceMappingURL=compartment-map.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"compartment-map.d.ts","sourceRoot":"","sources":["compartment-map.js"],"names":[],"mappings":"AAYA,+CAA+C;AAE/C,4BAFW,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,MAAM,CAE2B;AAc/D,+BAHI,KAAK,CAAC,MAAM,CAAC,GAAG,SAAS,KACzB,KAAK,CAAC,MAAM,CAAC,GAAG,SAAS,UAqCnC;AA8ZM,4DALI,OAAO,6BAEL,QAAQ,qBAAqB,IAAI,wBAAwB,CA+BrE;8CArf2C,YAAY"}
+{"version":3,"file":"compartment-map.d.ts","sourceRoot":"","sources":["compartment-map.js"],"names":[],"mappings":"AAYA,+CAA+C;AAE/C,4BAFW,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,MAAM,CAE2B;AAc/D,+BAHI,KAAK,CAAC,MAAM,CAAC,GAAG,SAAS,KACzB,KAAK,CAAC,MAAM,CAAC,GAAG,SAAS,UAqCnC;AA8ZM,4DALI,OAAO,QACP,MAAM,GACJ,QAAQ,qBAAqB,IAAI,wBAAwB,CA+BrE;8CArf2C,YAAY"}

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

@@ -1,5 +1,5 @@
-export function parseArchive(archiveBytes: Uint8Array, archiveLocation?: string | undefined, options?: ParseArchiveOptions | undefined): Promise<Application>;
-export function loadArchive(readPowers: ReadFn | ReadPowers, archiveLocation: string, options?: ParseArchiveOptions | undefined): Promise<Application>;
+export function parseArchive(archiveBytes: Uint8Array, archiveLocation?: string, options?: ParseArchiveOptions): Promise<Application>;
+export function loadArchive(readPowers: ReadFn | ReadPowers, archiveLocation: string, options?: LoadArchiveOptions): Promise<Application>;
 export function importArchive(readPowers: ReadFn | ReadPowers, archiveLocation: string, options: LoadArchiveOptions): Promise<SomeObject>;
 import type { ParseArchiveOptions } from './types.js';
 import type { Application } from './types.js';

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

@@ -1 +1 @@
-{"version":3,"file":"import-archive-lite.d.ts","sourceRoot":"","sources":["import-archive-lite.js"],"names":[],"mappings":"AAoPO,2CALI,UAAU,oFAGR,OAAO,CAAC,WAAW,CAAC,CAiKhC;AAQM,wCALI,MAAM,GAAG,UAAU,mBACnB,MAAM,8CAEJ,OAAO,CAAC,WAAW,CAAC,CAwBhC;AAQM,0CALI,MAAM,GAAG,UAAU,mBACnB,MAAM,WACN,kBAAkB,GAChB,OAAO,CAAC,UAAU,CAAC,CAK/B;yCAxZS,YAAY;iCAAZ,YAAY;4BAAZ,YAAY;gCAAZ,YAAY;wCAAZ,YAAY;gCAAZ,YAAY"}
+{"version":3,"file":"import-archive-lite.d.ts","sourceRoot":"","sources":["import-archive-lite.js"],"names":[],"mappings":"AAsPO,2CALI,UAAU,oBACV,MAAM,YACN,mBAAmB,GACjB,OAAO,CAAC,WAAW,CAAC,CAiKhC;AAQM,wCALI,MAAM,GAAG,UAAU,mBACnB,MAAM,YACN,kBAAkB,GAChB,OAAO,CAAC,WAAW,CAAC,CAwBhC;AAQM,0CALI,MAAM,GAAG,UAAU,mBACnB,MAAM,WACN,kBAAkB,GAChB,OAAO,CAAC,UAAU,CAAC,CAK/B;yCAxZS,YAAY;iCAAZ,YAAY;4BAAZ,YAAY;gCAAZ,YAAY;wCAAZ,YAAY;gCAAZ,YAAY"}

package/src/import-archive-lite.js

@@ -1,5 +1,5 @@
 /**
- * @module Provides functions for evaluating the modules in an archive (a zip
+ * Provides functions for evaluating the modules in an archive (a zip
  * file with a `compartment-map.json` and a file for each module it contains.)
  *
  * These functions do not have a bias for any particular mapping, so you will
@@ -10,6 +10,8 @@
  * You will need to provide the `defaultParserForLanguage` from
  * `@endo/compartment-mapper/import-parsers.js` or
  * `@endo/compartment-mapper/archive-parsers.js`.
+ *
+ * @module
  */
 
 /* eslint no-shadow: "off" */

package/src/import-archive.d.ts

@@ -1,5 +1,5 @@
-export function parseArchive(archiveBytes: Uint8Array, archiveLocation?: string | undefined, options?: Options | undefined): Promise<Application>;
-export function loadArchive(readPowers: import("@endo/zip").ReadFn | ReadPowers, archiveLocation: string, options?: import("./types.js").ParseArchiveOptions | undefined): Promise<Application>;
+export function parseArchive(archiveBytes: Uint8Array, archiveLocation?: string, options?: Options): Promise<Application>;
+export function loadArchive(readPowers: import("@endo/zip").ReadFn | ReadPowers, archiveLocation: string, options?: LoadArchiveOptions): Promise<Application>;
 export function importArchive(readPowers: import("@endo/zip").ReadFn | ReadPowers, archiveLocation: string, options: ExecuteOptions & LoadArchiveOptions): Promise<object>;
 export type CompartmentConstructor = typeof Compartment;
 export type Options = {
@@ -14,8 +14,8 @@ export type Options = {
 };
 import type { Application } from './types.js';
 import type { ReadPowers } from './types.js';
-import type { ExecuteOptions } from './types.js';
 import type { LoadArchiveOptions } from './types.js';
+import type { ExecuteOptions } from './types.js';
 import type { HashFn } from './types.js';
 import type { ExitModuleImportHook } from './types.js';
 import type { ComputeSourceLocationHook } from './types.js';

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

@@ -1 +1 @@
-{"version":3,"file":"import-archive.d.ts","sourceRoot":"","sources":["import-archive.js"],"names":[],"mappings":"AA6EO,2CALI,UAAU,wEAGR,OAAO,CAAC,WAAW,CAAC,CAW9B;AAQI,wCALI,OAAO,WAAW,EAAE,MAAM,GAAG,UAAU,mBACvC,MAAM,mEAEJ,OAAO,CAAC,WAAW,CAAC,CAO9B;AAQI,0CALI,OAAO,WAAW,EAAE,MAAM,GAAG,UAAU,mBACvC,MAAM,WACN,cAAc,GAAG,kBAAkB,GACjC,OAAO,CAAC,MAAM,CAAC,CAOzB;qCArEW,OAAO,WAAW;;;;;;;;;;;iCAhBtB,YAAY;gCAAZ,YAAY;oCAAZ,YAAY;wCAAZ,YAAY;4BAAZ,YAAY;0CAAZ,YAAY;+CAAZ,YAAY;kDAAZ,YAAY;uCAAZ,YAAY"}
+{"version":3,"file":"import-archive.d.ts","sourceRoot":"","sources":["import-archive.js"],"names":[],"mappings":"AA+EO,2CALI,UAAU,oBACV,MAAM,YACN,OAAO,GACL,OAAO,CAAC,WAAW,CAAC,CAW9B;AAQI,wCALI,OAAO,WAAW,EAAE,MAAM,GAAG,UAAU,mBACvC,MAAM,YACN,kBAAkB,GAChB,OAAO,CAAC,WAAW,CAAC,CAO9B;AAQI,0CALI,OAAO,WAAW,EAAE,MAAM,GAAG,UAAU,mBACvC,MAAM,WACN,cAAc,GAAG,kBAAkB,GACjC,OAAO,CAAC,MAAM,CAAC,CAOzB;qCArEW,OAAO,WAAW;;;;;;;;;;;iCAhBtB,YAAY;gCAAZ,YAAY;wCAAZ,YAAY;oCAAZ,YAAY;4BAAZ,YAAY;0CAAZ,YAAY;+CAAZ,YAAY;kDAAZ,YAAY;uCAAZ,YAAY"}

package/src/import-archive.js

@@ -1,5 +1,5 @@
 /**
- * @module Provides functions for evaluating modules in an archive (a zip file
+ * Provides functions for evaluating modules in an archive (a zip file
  * with a `compartment-map.json` and a file for a module and each of its
  * transitive dependencies.)
  *
@@ -12,6 +12,8 @@
  * See `import-archive-lite.js` for functions that are not coupled to these
  * parsers or the `node_modules` conventions without necessarily entraining a
  * dependency on Babel.
+ *
+ * @module
  */
 
 /**

package/src/import-hook.d.ts

@@ -6,32 +6,19 @@
  * @param {MakeImportNowHookMakerOptions} options
  * @returns {ImportNowHookMaker}
  */
-export function makeImportNowHookMaker(readPowers: ReadNowPowers, baseLocation: string, { sources, compartmentDescriptors, computeSha512, searchSuffixes, sourceMapHook, exitModuleImportNowHook, }: MakeImportNowHookMakerOptions): ImportNowHookMaker;
+export function makeImportNowHookMaker(readPowers: ReadNowPowers, baseLocation: string, { sources, compartmentDescriptors, computeSha512, searchSuffixes, archiveOnly, sourceMapHook, importNowHook: exitModuleImportNowHook, }: MakeImportNowHookMakerOptions): ImportNowHookMaker;
 export function exitModuleImportHookMaker({ modules, exitModuleImportHook, entryCompartmentName, }: {
     modules?: Record<string, any> | undefined;
     exitModuleImportHook?: ExitModuleImportHook | undefined;
     entryCompartmentName: string;
 }): ExitModuleImportHook | undefined;
-export function makeImportHookMaker(readPowers: ReadFn | ReadPowers, baseLocation: string, { sources, compartmentDescriptors, archiveOnly, computeSha512, searchSuffixes, sourceMapHook, entryCompartmentName, entryModuleSpecifier, exitModuleImportHook, }: {
-    sources?: Sources | undefined;
-    compartmentDescriptors?: Record<string, CompartmentDescriptor> | undefined;
-    archiveOnly?: boolean | undefined;
-    computeSha512?: HashFn | undefined;
-    searchSuffixes?: string[] | undefined;
-    entryCompartmentName: string;
-    entryModuleSpecifier: string;
-    exitModuleImportHook?: ExitModuleImportHook | undefined;
-    sourceMapHook?: SourceMapHook | undefined;
-}): ImportHookMaker;
+export function makeImportHookMaker(readPowers: ReadFn | ReadPowers, baseLocation: string, { sources, compartmentDescriptors, archiveOnly, computeSha512, searchSuffixes, sourceMapHook, entryCompartmentName, entryModuleSpecifier, importHook: exitModuleImportHook, }: MakeImportHookMakerOptions): ImportHookMaker;
 import type { ReadNowPowers } from './types.js';
 import type { MakeImportNowHookMakerOptions } from './types.js';
 import type { ImportNowHookMaker } from './types.js';
 import type { ExitModuleImportHook } from './types.js';
 import type { ReadFn } from './types.js';
 import type { ReadPowers } from './types.js';
-import type { Sources } from './types.js';
-import type { CompartmentDescriptor } from './types.js';
-import type { HashFn } from './types.js';
-import type { SourceMapHook } from './types.js';
+import type { MakeImportHookMakerOptions } from './types.js';
 import type { ImportHookMaker } from './types.js';
 //# sourceMappingURL=import-hook.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"import-hook.d.ts","sourceRoot":"","sources":["import-hook.js"],"names":[],"mappings":"AA2lBA;;;;;;;GAOG;AACH,mDALW,aAAa,gBACb,MAAM,+GACN,6BAA6B,GAC3B,kBAAkB,CAuJ9B;AA5jBM,oGALJ;IAAqC,OAAO;IACN,oBAAoB;IACnC,oBAAoB,EAAnC,MAAM;CACd,GAAU,oBAAoB,GAAC,SAAS,CA8B1C;AA4MM,gDApBI,MAAM,GAAC,UAAU,gBACjB,MAAM,qKAEd;IAA0B,OAAO;IACuB,sBAAsB;IACpD,WAAW;IACZ,aAAa;IACN,cAAc;IAOtB,oBAAoB,EAApC,MAAM;IACU,oBAAoB,EAApC,MAAM;IACyB,oBAAoB;IAC3B,aAAa;CAC7C,GAAU,eAAe,CAuL3B;mCAtjBS,YAAY;mDAAZ,YAAY;wCAAZ,YAAY;0CAAZ,YAAY;4BAAZ,YAAY;gCAAZ,YAAY;6BAAZ,YAAY;2CAAZ,YAAY;4BAAZ,YAAY;mCAAZ,YAAY;qCAAZ,YAAY"}
+{"version":3,"file":"import-hook.d.ts","sourceRoot":"","sources":["import-hook.js"],"names":[],"mappings":"AAkoBA;;;;;;;GAOG;AACH,mDALW,aAAa,gBACb,MAAM,2IACN,6BAA6B,GAC3B,kBAAkB,CAkN9B;AAnoBM,oGALJ;IAAqC,OAAO;IACN,oBAAoB;IACnC,oBAAoB,EAAnC,MAAM;CACd,GAAU,oBAAoB,GAAC,SAAS,CA8B1C;AAiPM,gDALI,MAAM,GAAC,UAAU,gBACjB,MAAM,iLACN,0BAA0B,GACxB,eAAe,CA8J3B;mCAzlBS,YAAY;mDAAZ,YAAY;wCAAZ,YAAY;0CAAZ,YAAY;4BAAZ,YAAY;gCAAZ,YAAY;gDAAZ,YAAY;qCAAZ,YAAY"}

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,17 +25,18 @@
  *   ChooseModuleDescriptorYieldables,
  *   ExitModuleImportHook,
  *   FindRedirectParams,
- *   HashFn,
  *   ImportHookMaker,
  *   ImportNowHookMaker,
+ *   MakeImportHookMakerOptions,
  *   MakeImportNowHookMakerOptions,
  *   ModuleDescriptor,
  *   ParseResult,
  *   ReadFn,
  *   ReadPowers,
- *   SourceMapHook,
- *   Sources,
- *   ReadNowPowers
+ *   ReadNowPowers,
+ *   StrictlyRequiredFn,
+ *   CompartmentSources,
+ *   DeferErrorFn
  * } from './types.js'
  */
 
@@ -92,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.
@@ -105,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;
@@ -136,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],
         };
       }
@@ -157,7 +184,7 @@ const findRedirect = ({
           },
         );
         return {
-          specifier: absoluteModuleSpecifier,
+          specifier: relativeSpecifier(moduleSpecifierLocation, location),
           compartment: compartments[location],
         };
       }
@@ -267,11 +294,13 @@ function* chooseModuleDescriptor(
     packageLocation,
     packageSources,
     readPowers,
+    archiveOnly,
     sourceMapHook,
     strictlyRequiredForCompartment,
   },
   { maybeRead, parse, shouldDeferError = () => false },
 ) {
+  const { sourceDirname } = compartmentDescriptor;
   for (const candidateSpecifier of candidates) {
     const candidateModuleDescriptor = moduleDescriptors[candidateSpecifier];
     if (candidateModuleDescriptor !== undefined) {
@@ -327,6 +356,7 @@ function* chooseModuleDescriptor(
           packageLocation,
           {
             readPowers,
+            archiveOnly,
             sourceMapHook:
               sourceMapHook &&
               (nextSourceMapObject => {
@@ -378,6 +408,7 @@ function* chooseModuleDescriptor(
       packageSources[candidateSpecifier] = {
         location: packageRelativeLocation,
         sourceLocation: moduleLocation,
+        sourceDirname,
         parser,
         bytes: transformedBytes,
         record: concreteRecord,
@@ -397,25 +428,58 @@ 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
- * @param {object} options
- * @param {Sources} [options.sources]
- * @param {Record<string, CompartmentDescriptor>} [options.compartmentDescriptors]
- * @param {boolean} [options.archiveOnly]
- * @param {HashFn} [options.computeSha512]
- * @param {Array<string>} [options.searchSuffixes] - Suffixes to search if the
- * unmodified specifier is not found.
- * Pass [] to emulate Node.js' strict behavior.
- * The default handles Node.js' CommonJS behavior.
- * Unlike Node.js, the Compartment Mapper lifts CommonJS up, more like a
- * bundler, and does not attempt to vary the behavior of resolution depending
- * on the language of the importing module.
- * @param {string} options.entryCompartmentName
- * @param {string} options.entryModuleSpecifier
- * @param {ExitModuleImportHook} [options.exitModuleImportHook]
- * @param {SourceMapHook} [options.sourceMapHook]
+ * @param {MakeImportHookMakerOptions} options
  * @returns {ImportHookMaker}
  */
 export const makeImportHookMaker = (
@@ -430,7 +494,7 @@ export const makeImportHookMaker = (
     sourceMapHook = undefined,
     entryCompartmentName,
     entryModuleSpecifier,
-    exitModuleImportHook = undefined,
+    importHook: exitModuleImportHook = undefined,
   },
 ) => {
   // Set of specifiers for modules (scoped to compartment) whose parser is not
@@ -471,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 => {
@@ -575,6 +613,7 @@ export const makeImportHookMaker = (
             packageLocation,
             packageSources,
             readPowers,
+            archiveOnly,
             sourceMapHook,
             strictlyRequiredForCompartment,
           },
@@ -617,8 +656,9 @@ export function makeImportNowHookMaker(
     compartmentDescriptors = create(null),
     computeSha512 = undefined,
     searchSuffixes = nodejsConventionSearchSuffixes,
+    archiveOnly = false,
     sourceMapHook = undefined,
-    exitModuleImportNowHook,
+    importNowHook: exitModuleImportNowHook = undefined,
   },
 ) {
   // Set of specifiers for modules (scoped to compartment) whose parser is not
@@ -647,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(
@@ -692,69 +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,
-          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;AA0JM,0CANI,MAAM,GAAG,UAAU,kBACnB,wBAAwB,gDAEtB,OAAO,CAAC,UAAU,CAAC,CAU/B;mCAtNS,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"}