@endo/compartment-mapper 1.6.3 → 2.1.0

package/src/import.d.ts

@@ -2,10 +2,10 @@
  * @overload
  * @param {ReadNowPowers} readPowers
  * @param {string} moduleLocation
- * @param {SyncArchiveOptions} options
+ * @param {SyncLoadLocationOptions} options
  * @returns {Promise<Application>}
  */
-export function loadLocation(readPowers: ReadNowPowers, moduleLocation: string, options: SyncArchiveOptions): Promise<Application>;
+export function loadLocation(readPowers: ReadNowPowers, moduleLocation: string, options: SyncLoadLocationOptions): Promise<Application>;
 /**
  * @overload
  * @param {ReadFn | ReadPowers} readPowers
@@ -37,7 +37,7 @@ export function importLocation(readPowers: ReadNowPowers, moduleLocation: string
  */
 export function importLocation(readPowers: ReadPowers | ReadFn, moduleLocation: string, options?: ImportLocationOptions | undefined): Promise<SomeObject>;
 import type { ReadNowPowers } from './types.js';
-import type { SyncArchiveOptions } from './types.js';
+import type { SyncLoadLocationOptions } from './types.js';
 import type { Application } from './types.js';
 import type { ReadFn } from './types.js';
 import type { ReadPowers } from './types.js';

package/src/import.d.ts.map

@@ -1 +1 @@
-{"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"}
+{"version":3,"file":"import.d.ts","sourceRoot":"","sources":["import.js"],"names":[],"mappings":";;;;;;;AAkDG,yCACQ,aAAa,kBACb,MAAM,WACN,uBAAuB,GACrB,OAAO,CAAC,WAAW,CAAC,CAChC;;;;;;;;AAGE,yCACQ,MAAM,GAAG,UAAU,kBACnB,MAAM,8CAEJ,OAAO,CAAC,WAAW,CAAC,CAChC;;;;;;;;;;;AAkEE,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;mCAxHS,YAAY;6CAAZ,YAAY;iCAAZ,YAAY;4BAAZ,YAAY;gCAAZ,YAAY;yCAAZ,YAAY;+CAAZ,YAAY;gCAAZ,YAAY;2CAAZ,YAAY"}

package/src/import.js

@@ -18,26 +18,25 @@
  *   Application,
  *   SyncImportLocationOptions,
  *   ImportLocationOptions,
- *   SyncArchiveOptions,
  *   LoadLocationOptions,
  *   SomeObject,
  *   ReadNowPowers,
- *   ArchiveOptions,
  *   ReadFn,
  *   ReadPowers,
+ SyncLoadLocationOptions,
  * } from './types.js'
  */
 
+import { loadFromMap } from './import-lite.js';
 import { defaultParserForLanguage } from './import-parsers.js';
 import { mapNodeModules } from './node-modules.js';
-import { loadFromMap } from './import-lite.js';
 
 const { assign, create, freeze } = Object;
 
 /**
  * Add the default parserForLanguage option.
- * @param {ArchiveOptions} [options]
- * @returns {ArchiveOptions}
+ * @param {LoadLocationOptions} [options]
+ * @returns {LoadLocationOptions}
  */
 const assignParserForLanguage = (options = {}) => {
   const { parserForLanguage: parserForLanguageOption, ...rest } = options;
@@ -52,7 +51,7 @@ const assignParserForLanguage = (options = {}) => {
  * @overload
  * @param {ReadNowPowers} readPowers
  * @param {string} moduleLocation
- * @param {SyncArchiveOptions} options
+ * @param {SyncLoadLocationOptions} options
  * @returns {Promise<Application>}
  */
 
@@ -82,6 +81,7 @@ export const loadLocation = async (
     commonDependencies,
     policy,
     parserForLanguage,
+    log,
     languages,
     languageForExtension,
     commonjsLanguageForExtension,
@@ -89,6 +89,10 @@ export const loadLocation = async (
     workspaceLanguageForExtension,
     workspaceCommonjsLanguageForExtension,
     workspaceModuleLanguageForExtension,
+    unknownCanonicalNameHook,
+    packageDataHook,
+    packageDependenciesHook,
+    moduleSourceHook,
     ...otherOptions
   } = assignParserForLanguage(options);
   // conditions are not present in SyncArchiveOptions
@@ -107,9 +111,15 @@ export const loadLocation = async (
     workspaceCommonjsLanguageForExtension,
     workspaceModuleLanguageForExtension,
     languages,
+    log,
+    unknownCanonicalNameHook,
+    packageDataHook,
+    packageDependenciesHook,
   });
   return loadFromMap(readPowers, compartmentMap, {
     parserForLanguage,
+    log,
+    moduleSourceHook,
     ...otherOptions,
   });
 };

package/src/infer-exports.d.ts

@@ -1,7 +1,9 @@
-export function inferExportsEntries({ main, module, exports }: PackageDescriptor, conditions: Set<string>, types: LanguageForExtension): Generator<string[], void, any>;
+export function inferExportsEntries({ main, module, exports }: PackageDescriptor, conditions: Set<string>, types: LanguageForExtension): Generator<string[] | [string, string | null], 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;
+export function inferExportsAliasesAndPatterns(descriptor: PackageDescriptor, externalAliases: Node["externalAliases"], internalAliases: Node["internalAliases"], patterns: PatternDescriptor[], conditions: Set<string>, types: Record<string, string>, log: LogFn): void;
 import type { PackageDescriptor } from './types.js';
 import type { LanguageForExtension } from './types.js';
 import type { Node } from './types/node-modules.js';
+import type { PatternDescriptor } from './types/pattern-replacement.js';
+import type { LogFn } from './types/external.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":"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"}
+{"version":3,"file":"infer-exports.d.ts","sourceRoot":"","sources":["infer-exports.js"],"names":[],"mappings":"AAyLO,+DAPI,iBAAiB,cACjB,GAAG,CAAC,MAAM,CAAC,SAEX,oBAAoB,4DA2B9B;AAkBM,yCAPI,iBAAiB,cACjB,GAAG,CAAC,MAAM,CAAC,SAEX,oBAAoB,GAElB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAG8B;AAyD1D,2DARI,iBAAiB,mBACjB,IAAI,CAAC,iBAAiB,CAAC,mBACvB,IAAI,CAAC,iBAAiB,CAAC,YACvB,iBAAiB,EAAE,cACnB,GAAG,CAAC,MAAM,CAAC,SACX,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,OACtB,KAAK,QAsFf;uCArWyD,YAAY;0CAAZ,YAAY;0BAE7B,yBAAyB;uCAC9B,gCAAgC;2BAF5C,qBAAqB"}

package/src/infer-exports.js

@@ -10,12 +10,14 @@
 
 /**
  * @import {LanguageForExtension, PackageDescriptor} from './types.js'
- * @import {Node} from './types/node-modules.js'
+ * @import {LogFn} from './types/external.js'
+ * @import {Exports, Imports, Node} from './types/node-modules.js'
+ * @import {PatternDescriptor} from './types/pattern-replacement.js'
  */
 
-import { join, relativize } from './node-module-specifier.js';
+import { relativize } from './node-module-specifier.js';
 
-const { entries, fromEntries, assign } = Object;
+const { entries, fromEntries } = Object;
 const { isArray } = Array;
 
 /**
@@ -60,16 +62,23 @@ function* interpretBrowserField(name, browser, main = 'index.js') {
 
 /**
  * @param {string} name - the name of the referrer package.
- * @param {object} exports - the `exports` field from a package.json.
+ * @param {Exports} exports - the `exports` field from a package.json.
  * @param {Set<string>} conditions - build conditions about the target environment
  * for selecting relevant exports, e.g., "browser" or "node".
- * @yields {[string, string]}
- * @returns {Generator<[string, string]>}
+ * @param {LanguageForExtension} types - an object to populate
+ * with any recognized module's type, if implied by a tag.
+ * @yields {[string, string | null]}
+ * @returns {Generator<[string, string | null]>}
  */
-function* interpretExports(name, exports, conditions) {
+function* interpretExports(name, exports, conditions, types) {
+  // Null targets are exclusions (Node.js semantics).
+  if (exports === null) {
+    yield [name, null];
+    return;
+  }
   if (isArray(exports)) {
     for (const section of exports) {
-      const results = [...interpretExports(name, section, conditions)];
+      const results = [...interpretExports(name, section, conditions, types)];
       if (results.length > 0) {
         yield* results;
         break;
@@ -92,19 +101,71 @@ function* interpretExports(name, exports, conditions) {
       // eslint-disable-next-line no-continue
       continue; // or no-op
     } else if (key.startsWith('./') || key === '.') {
-      if (name === '.') {
-        yield* interpretExports(key, value, conditions);
-      } else {
-        yield* interpretExports(join(name, key), value, conditions);
-      }
+      yield* interpretExports(key, value, conditions, types);
     } else if (conditions.has(key)) {
-      yield* interpretExports(name, value, conditions);
+      if (types && key === 'import' && typeof value === 'string') {
+        // In this one case, the key "import" has carried a hint that the
+        // referenced module is an ECMASCript module, and that hint may be
+        // necessary to override whatever type might be inferred from the module
+        // specifier extension.
+        const spec = relativize(value);
+        types[spec] = 'mjs';
+      }
+      yield* interpretExports(name, value, conditions, types);
       // Take only the first matching tag.
       break;
     }
   }
 }
 
+/**
+ * Interprets the `imports` field from a package.json file.
+ * The imports field provides self-referencing subpath patterns that
+ * can be used to create private internal mappings.
+ *
+ * @param {Imports} imports - the `imports` field from a package.json.
+ * @param {Set<string>} conditions - build conditions about the target environment
+ * @param {LogFn} log
+ * @yields {[string, string | null]}
+ * @returns {Generator<[string, string | null]>}
+ */
+function* interpretImports(imports, conditions, log) {
+  if (Object(imports) !== imports || Array.isArray(imports)) {
+    throw Error(
+      `Cannot interpret package.json imports property, must be object, got ${imports}`,
+    );
+  }
+  for (const [key, value] of entries(imports)) {
+    // imports keys must start with '#'
+    if (!key.startsWith('#')) {
+      log(`Ignoring invalid imports key "${key}": must start with "#"`);
+      // eslint-disable-next-line no-continue
+      continue;
+    }
+    if (value === null) {
+      // Null targets are exclusions (Node.js semantics).
+      yield [key, null];
+    } else if (typeof value === 'string') {
+      yield [key, relativize(value)];
+    } else if (Object(value) === value && !isArray(value)) {
+      // Handle conditional imports
+      for (const [condition, target] of entries(value)) {
+        if (conditions.has(condition)) {
+          if (target === null) {
+            yield [key, null];
+          } else if (typeof target === 'string') {
+            yield [key, relativize(target)];
+          }
+          // Take only the first matching condition
+          break;
+        }
+      }
+    } else {
+      log(`Ignoring unsupported imports value for "${key}": ${typeof value}`);
+    }
+  }
+}
+
 /**
  * Given an unpacked `package.json`, generate a series of `[name, target]`
  * pairs to represent what this package exports. `name` is what the
@@ -120,7 +181,7 @@ function* interpretExports(name, exports, conditions) {
  * for selecting relevant exports, e.g., "browser" or "node".
  * @param {LanguageForExtension} types - an object to populate
  * with any recognized module's type, if implied by a tag.
- * @yields {[string, string]}
+ * @yields {[string, string | null]}
  */
 export const inferExportsEntries = function* inferExportsEntries(
   { main, module, exports },
@@ -141,7 +202,7 @@ export const inferExportsEntries = function* inferExportsEntries(
     yield ['.', relativize(main)];
   }
   if (exports !== undefined) {
-    yield* interpretExports('.', exports, conditions);
+    yield* interpretExports('.', exports, conditions, types);
   }
   // TODO Otherwise, glob 'files' for all '.js', '.cjs', and '.mjs' entry
   // modules, taking care to exclude node_modules.
@@ -167,27 +228,115 @@ export const inferExports = (descriptor, conditions, types) =>
   fromEntries(inferExportsEntries(descriptor, conditions, types));
 
 /**
+ * Determines if a key or value contains a wildcard pattern.
+ *
+ * @param {string} key
+ * @param {string | null} value
+ * @returns {boolean}
+ */
+const hasWildcard = (key, value) =>
+  key.includes('*') || (value?.includes('*') ?? false);
+
+/**
+ * Returns the number of `*` characters in a string.
+ *
+ * @param {string} str
+ * @returns {number}
+ */
+const countWildcards = str => (str.match(/\*/g) || []).length;
+
+/**
+ * Validates a wildcard pattern entry and logs warnings for invalid patterns.
+ * Returns true if the pattern is valid and should be used.
+ *
+ * @param {string} key
+ * @param {string} value
+ * @param {LogFn} log
+ * @returns {boolean}
+ */
+const validateWildcardPattern = (key, value, log) => {
+  const keyCount = countWildcards(key);
+  const valueCount = countWildcards(value);
+  if (keyCount > 1 || valueCount > 1) {
+    log(`Ignoring pattern with multiple wildcards "${key}": "${value}"`);
+    return false;
+  }
+  if (keyCount !== valueCount) {
+    log(
+      `Ignoring pattern with mismatched wildcard count "${key}" (${keyCount}) vs "${value}" (${valueCount})`,
+    );
+    return false;
+  }
+  return true;
+};
+
+/**
+ * Infers exports, internal aliases, and wildcard patterns from a package descriptor.
+ * Extracts wildcard patterns from the `exports` and `imports` fields.
  *
  * @param {PackageDescriptor} descriptor
  * @param {Node['externalAliases']} externalAliases
  * @param {Node['internalAliases']} internalAliases
+ * @param {PatternDescriptor[]} patterns - array to populate with wildcard patterns
  * @param {Set<string>} conditions
  * @param {Record<string, string>} types
+ * @param {LogFn} log
  */
-export const inferExportsAndAliases = (
+export const inferExportsAliasesAndPatterns = (
   descriptor,
   externalAliases,
   internalAliases,
+  patterns,
   conditions,
   types,
+  log,
 ) => {
-  const { name, type, main, module, exports, browser } = descriptor;
+  const { name, type, main, module, exports, imports, browser } = descriptor;
 
-  // collect externalAliases from exports and main/module
-  assign(
-    externalAliases,
-    fromEntries(inferExportsEntries(descriptor, conditions, types)),
-  );
+  // Process exports field - separate wildcards from concrete exports.
+  for (const [key, value] of inferExportsEntries(
+    descriptor,
+    conditions,
+    types,
+  )) {
+    if (value === null) {
+      // Null targets are exclusions.
+      // Only wildcard null targets need to be stored as patterns;
+      // concrete null targets are excluded by omission from aliases.
+      if (key.includes('*')) {
+        patterns.push({ from: key, to: null });
+      }
+      // eslint-disable-next-line no-continue
+      continue;
+    }
+    if (hasWildcard(key, value)) {
+      if (validateWildcardPattern(key, value, log)) {
+        patterns.push({ from: key, to: value });
+      }
+    } else {
+      externalAliases[key] = value;
+    }
+  }
+
+  // Process imports field (package self-referencing).
+  if (imports !== undefined) {
+    for (const [key, value] of interpretImports(imports, conditions, log)) {
+      if (value === null) {
+        if (key.includes('*')) {
+          patterns.push({ from: key, to: null });
+        }
+        // eslint-disable-next-line no-continue
+        continue;
+      }
+      if (hasWildcard(key, value)) {
+        if (validateWildcardPattern(key, value, log)) {
+          patterns.push({ from: key, to: value });
+        }
+      } else {
+        internalAliases[key] = value;
+      }
+    }
+  }
 
   // expose default module as package root
   // may be overwritten by browser field

package/src/link.d.ts

@@ -1,6 +1,7 @@
-export function link({ entry, compartments: compartmentDescriptors }: CompartmentMapDescriptor, options: LinkOptions): LinkResult;
-export function assemble(compartmentMap: CompartmentMapDescriptor, options: LinkOptions): Compartment;
-import type { CompartmentMapDescriptor } from './types.js';
+export function link({ entry, compartments: compartmentDescriptors }: PackageCompartmentMapDescriptor | FileCompartmentMapDescriptor, options: LinkOptions): LinkResult;
+export function assemble(compartmentMap: PackageCompartmentMapDescriptor, options: LinkOptions): Compartment;
+import type { PackageCompartmentMapDescriptor } from './types.js';
+import type { FileCompartmentMapDescriptor } from './types.js';
 import type { LinkOptions } from './types.js';
 import type { LinkResult } from './types.js';
 //# sourceMappingURL=link.d.ts.map

package/src/link.d.ts.map

@@ -1 +1 @@
-{"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"}
+{"version":3,"file":"link.d.ts","sourceRoot":"","sources":["link.js"],"names":[],"mappings":"AAyTO,sEAJI,+BAA+B,GAAC,4BAA4B,WAC5D,WAAW,GACT,UAAU,CAgLtB;AAOM,yCAJI,+BAA+B,WAC/B,WAAW,eAIqB;qDAhdjC,YAAY;kDAAZ,YAAY;iCAAZ,YAAY;gCAAZ,YAAY"}