@endo/compartment-mapper 1.5.0 → 1.6.1

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" */
@@ -169,7 +171,7 @@ export const loadFromMap = async (readPowers, compartmentMap, options = {}) => {
         archiveOnly: false,
         entryCompartmentName,
         entryModuleSpecifier,
-        exitModuleImportHook: compartmentExitModuleImportHook,
+        importHook: compartmentExitModuleImportHook,
       },
     );
 
@@ -188,9 +190,11 @@ export const loadFromMap = async (readPowers, compartmentMap, options = {}) => {
         /** @type {ReadNowPowers} */ (readPowers),
         entryCompartmentName,
         {
+          entryCompartmentName,
+          entryModuleSpecifier,
           compartmentDescriptors: compartmentMap.compartments,
           searchSuffixes,
-          exitModuleImportNowHook,
+          importNowHook: exitModuleImportNowHook,
         },
       );
       ({ compartment, pendingJobsPromise } = link(compartmentMap, {

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"}

package/src/node-module-specifier.js

@@ -1,7 +1,9 @@
 /**
- * @module Provides functions for interacting with Node.js module specifiers in
+ * Provides functions for interacting with Node.js module specifiers in
  * their canonical form.
  * This is a kind of path math that is platform-agnostic.
+ *
+ * @module
  */
 
 // q, as in quote, for error messages.

package/src/node-modules.d.ts

@@ -1,54 +1,11 @@
-export function compartmentMapForNodeModules(readPowers: ReadFn | ReadPowers | MaybeReadPowers, packageLocation: string, conditionsOption: Set<string>, packageDescriptor: object, moduleSpecifier: string, options?: CompartmentMapForNodeModulesOptions | undefined): Promise<CompartmentMapDescriptor>;
-export function mapNodeModules(readPowers: ReadFn | ReadPowers | MaybeReadPowers, moduleLocation: string, options?: MapNodeModulesOptions | undefined): Promise<CompartmentMapDescriptor>;
-/**
- * The graph is an intermediate object model that the functions of this module
- * build by exploring the `node_modules` tree dropped by tools like npm and
- * consumed by tools like Node.js.
- * This gets translated finally into a compartment map.
- */
-export type Graph = Record<string, Node>;
-export type Node = {
-    label: string;
-    name: string;
-    path: Array<string>;
-    logicalPath: Array<string>;
-    explicitExports: boolean;
-    internalAliases: Record<string, string>;
-    externalAliases: Record<string, string>;
-    /**
-     * - from module name to
-     * location in storage.
-     */
-    dependencyLocations: Record<string, string>;
-    /**
-     * - the parser for
-     * modules based on their extension.
-     */
-    parsers: LanguageForExtension;
-    /**
-     * - the parser for specific
-     * modules.
-     */
-    types: Record<string, Language>;
-};
-export type LanguageOptions = {
-    commonjsLanguageForExtension: LanguageForExtension;
-    moduleLanguageForExtension: LanguageForExtension;
-    workspaceCommonjsLanguageForExtension: LanguageForExtension;
-    workspaceModuleLanguageForExtension: LanguageForExtension;
-    languages: Set<string>;
-};
-export type CommonDependencyDescriptors = Record<string, {
-    spec: string;
-    alias: string;
-}>;
-export type ReadDescriptorFn = (packageLocation: string) => Promise<object>;
+export function basename(location: string): string;
+export function compartmentMapForNodeModules(readPowers: ReadFn | ReadPowers | MaybeReadPowers, packageLocation: string, conditionsOption: Set<string>, packageDescriptor: PackageDescriptor, moduleSpecifier: string, options?: CompartmentMapForNodeModulesOptions): Promise<CompartmentMapDescriptor>;
+export function mapNodeModules(readPowers: ReadFn | ReadPowers | MaybeReadPowers, moduleLocation: string, { tags, conditions, log, ...otherOptions }?: MapNodeModulesOptions): Promise<CompartmentMapDescriptor>;
 import type { ReadFn } from './types.js';
 import type { ReadPowers } from './types.js';
 import type { MaybeReadPowers } from './types.js';
+import type { PackageDescriptor } from './types.js';
 import type { CompartmentMapForNodeModulesOptions } from './types.js';
 import type { CompartmentMapDescriptor } from './types.js';
 import type { MapNodeModulesOptions } from './types.js';
-import type { LanguageForExtension } from './types.js';
-import type { Language } from './types.js';
 //# sourceMappingURL=node-modules.d.ts.map

package/src/node-modules.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"node-modules.d.ts","sourceRoot":"","sources":["node-modules.js"],"names":[],"mappings":"AAs2BO,yDARI,MAAM,GAAG,UAAU,GAAG,eAAe,mBACrC,MAAM,oBACN,GAAG,CAAC,MAAM,CAAC,qBACX,MAAM,mBACN,MAAM,8DAEJ,OAAO,CAAC,wBAAwB,CAAC,CA+D7C;AAQM,2CALI,MAAM,GAAG,UAAU,GAAG,eAAe,kBACrC,MAAM,gDAEJ,OAAO,CAAC,wBAAwB,CAAC,CA6B7C;;;;;;;oBA/5BY,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC;;WAKnB,MAAM;UACN,MAAM;UACN,KAAK,CAAC,MAAM,CAAC;iBACb,KAAK,CAAC,MAAM,CAAC;qBACb,OAAO;qBACP,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;qBACtB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;;;;;yBACtB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;;;;;aAEtB,oBAAoB;;;;;WAEpB,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC;;;kCAMxB,oBAAoB;gCACpB,oBAAoB;2CACpB,oBAAoB;yCACpB,oBAAoB;eACpB,GAAG,CAAC,MAAM,CAAC;;0CAIZ,MAAM,CAAC,MAAM,EAAE;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAC,CAAC;iDA+E/C,MAAM,KACJ,OAAO,CAAC,MAAM,CAAC;4BAvHlB,YAAY;gCAAZ,YAAY;qCAAZ,YAAY;yDAAZ,YAAY;8CAAZ,YAAY;2CAAZ,YAAY;0CAAZ,YAAY;8BAAZ,YAAY"}
+{"version":3,"file":"node-modules.d.ts","sourceRoot":"","sources":["node-modules.js"],"names":[],"mappings":"AAmFO,mCAHI,MAAM,GACJ,MAAM,CAYlB;AA43BM,yDATI,MAAM,GAAG,UAAU,GAAG,eAAe,mBACrC,MAAM,oBACN,GAAG,CAAC,MAAM,CAAC,qBACX,iBAAiB,mBACjB,MAAM,YACN,mCAAmC,GACjC,OAAO,CAAC,wBAAwB,CAAC,CAkE7C;AAaM,2CALI,MAAM,GAAG,UAAU,GAAG,eAAe,kBACrC,MAAM,+CACN,qBAAqB,GACnB,OAAO,CAAC,wBAAwB,CAAC,CA0B7C;4BA9hCS,YAAY;gCAAZ,YAAY;qCAAZ,YAAY;uCAAZ,YAAY;yDAAZ,YAAY;8CAAZ,YAAY;2CAAZ,YAAY"}