@endo/compartment-mapper 2.0.0 → 2.1.0

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,15 +62,20 @@ 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".
  * @param {LanguageForExtension} types - an object to populate
  * with any recognized module's type, if implied by a tag.
- * @yields {[string, string]}
- * @returns {Generator<[string, string]>}
+ * @yields {[string, string | null]}
+ * @returns {Generator<[string, string | null]>}
  */
 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, types)];
@@ -94,11 +101,7 @@ function* interpretExports(name, exports, conditions, types) {
       // eslint-disable-next-line no-continue
       continue; // or no-op
     } else if (key.startsWith('./') || key === '.') {
-      if (name === '.') {
-        yield* interpretExports(key, value, conditions, types);
-      } else {
-        yield* interpretExports(join(name, key), value, conditions, types);
-      }
+      yield* interpretExports(key, value, conditions, types);
     } else if (conditions.has(key)) {
       if (types && key === 'import' && typeof value === 'string') {
         // In this one case, the key "import" has carried a hint that the
@@ -115,6 +118,54 @@ function* interpretExports(name, exports, conditions, types) {
   }
 }
 
+/**
+ * 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
@@ -130,7 +181,7 @@ function* interpretExports(name, exports, conditions, types) {
  * 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 },
@@ -177,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;
+
+  // 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;
+    }
+  }
 
-  // collect externalAliases from exports and main/module
-  assign(
-    externalAliases,
-    fromEntries(inferExportsEntries(descriptor, conditions, types)),
-  );
+  // 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.map

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

package/src/link.js

@@ -29,8 +29,8 @@
  *   FileCompartmentMapDescriptor,
  *   FileCompartmentDescriptor,
  *   FileModuleConfiguration,
- *   MakeModuleMapHookOptions,
  * } from './types.js'
+ * @import {SubpathReplacer} from './types/pattern-replacement.js'
  */
 
 import { makeMapParsers } from './map-parser.js';
@@ -45,6 +45,7 @@ import {
   isCompartmentModuleConfiguration,
   isExitModuleConfiguration,
 } from './guards.js';
+import { makeMultiSubpathReplacer } from './pattern-replacement.js';
 
 const { assign, create, entries, freeze } = Object;
 const { hasOwnProperty } = Object.prototype;
@@ -101,7 +102,7 @@ const trimModuleSpecifierPrefix = (moduleSpecifier, prefix) => {
  *
  * @param {FileCompartmentDescriptor|PackageCompartmentDescriptor} compartmentDescriptor
  * @param {Record<string, Compartment>} compartments
- * @param {string} compartmentName
+ * @param {FileUrlString} compartmentName
  * @param {Record<string, FileModuleConfiguration|CompartmentModuleConfiguration>} moduleDescriptors
  * @param {Record<string, ScopeDescriptor<FileUrlString>>} scopeDescriptors
  * @returns {ModuleMapHook | undefined}
@@ -113,6 +114,14 @@ const makeModuleMapHook = (
   moduleDescriptors,
   scopeDescriptors,
 ) => {
+  // Build pattern matcher once per compartment if patterns exist.
+  const { patterns } = /** @type {Partial<PackageCompartmentDescriptor>} */ (
+    compartmentDescriptor
+  );
+  /** @type {SubpathReplacer | null} */
+  const matchPattern =
+    patterns && patterns.length > 0 ? makeMultiSubpathReplacer(patterns) : null;
+
   /**
    * @type {ModuleMapHook}
    */
@@ -162,6 +171,55 @@ const makeModuleMapHook = (
       }
     }
 
+    // Check patterns for wildcard matches (before scopes).
+    // Patterns may resolve within the same compartment (internal patterns)
+    // or to a foreign compartment (dependency export patterns).
+    if (matchPattern) {
+      const match = matchPattern(moduleSpecifier);
+      if (match !== null) {
+        const { result: resolvedPath, compartment: foreignCompartmentName } =
+          match;
+
+        // Null result means the specifier is explicitly excluded.
+        if (resolvedPath === null) {
+          throw Error(
+            `Cannot find module ${q(moduleSpecifier)} — excluded by null target pattern in ${q(compartmentName)}`,
+          );
+        }
+        const targetCompartmentName =
+          /** @type {FileUrlString} */
+          (foreignCompartmentName || compartmentName);
+
+        // Write back to moduleDescriptors for caching, archival, and
+        // policy enforcement. The write-back must precede the policy
+        // check because enforcePolicyByModule verifies the specifier
+        // exists in compartmentDescriptor.modules (the same object).
+        moduleDescriptors[moduleSpecifier] = {
+          retained: true,
+          compartment: targetCompartmentName,
+          module: resolvedPath,
+          __createdBy: 'link-pattern',
+        };
+
+        // Policy enforcement for pattern-matched modules
+        enforcePolicyByModule(moduleSpecifier, compartmentDescriptor, {
+          exit: false,
+          errorHint: `Pattern matched in compartment ${q(compartmentName)}: module specifier ${q(moduleSpecifier)} mapped to ${q(resolvedPath)}`,
+        });
+
+        const targetCompartment = compartments[targetCompartmentName];
+        if (targetCompartment === undefined) {
+          throw Error(
+            `Cannot import module specifier ${q(moduleSpecifier)} from missing compartment ${q(targetCompartmentName)}`,
+          );
+        }
+        return {
+          compartment: targetCompartment,
+          namespace: resolvedPath,
+        };
+      }
+    }
+
     // Search for a scope that shares a prefix with the requested module
     // specifier.
     // This might be better with a trie, but only a benchmark on real-world
@@ -299,7 +357,7 @@ export const link = (
   });
 
   const compartmentDescriptorEntries =
-    /** @type {[string, PackageCompartmentDescriptor|FileCompartmentDescriptor][]} */ (
+    /** @type {[FileUrlString, PackageCompartmentDescriptor|FileCompartmentDescriptor][]} */ (
       entries(compartmentDescriptors)
     );
   for (const [

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

@@ -1 +1 @@
-{"version":3,"file":"node-modules.d.ts","sourceRoot":"","sources":["node-modules.js"],"names":[],"mappings":"AA4LO,mCAHI,MAAM,GACJ,MAAM,CAYlB;AAqlCM,0DARI,MAAM,GAAG,WAAW,aAAa,CAAC,GAAG,gBAAgB,aAAa,CAAC,wBACnE,aAAa,oBACb,GAAG,CAAC,MAAM,CAAC,qBACX,iBAAiB,wBACjB,MAAM,YACN,mCAAmC,GACjC,OAAO,CAAC,+BAA+B,CAAC,CA0HpD;AAaM,2CALI,MAAM,GAAG,WAAW,aAAa,CAAC,GAAG,gBAAgB,aAAa,CAAC,kBACnE,MAAM,2HACN,qBAAqB,GACnB,OAAO,CAAC,+BAA+B,CAAC,CA6CpD;AAhLM,yDARI,MAAM,GAAG,WAAW,aAAa,CAAC,GAAG,gBAAgB,aAAa,CAAC,wBACnE,aAAa,oBACb,GAAG,CAAC,MAAM,CAAC,qBACX,iBAAiB,wBACjB,MAAM,YACN,mCAAmC,GACjC,OAAO,CAAC,+BAA+B,CAAC,CA0HpD;4BA51CS,YAAY;mCAAZ,YAAY;gCAAZ,YAAY;qCAAZ,YAAY;uCAAZ,YAAY;yDAAZ,YAAY;qDAAZ,YAAY;2CAAZ,YAAY"}
+{"version":3,"file":"node-modules.d.ts","sourceRoot":"","sources":["node-modules.js"],"names":[],"mappings":"AA4LO,mCAHI,MAAM,GACJ,MAAM,CAYlB;AA+kCM,0DARI,MAAM,GAAG,WAAW,aAAa,CAAC,GAAG,gBAAgB,aAAa,CAAC,wBACnE,aAAa,oBACb,GAAG,CAAC,MAAM,CAAC,qBACX,iBAAiB,wBACjB,MAAM,YACN,mCAAmC,GACjC,OAAO,CAAC,+BAA+B,CAAC,CA0HpD;AAaM,2CALI,MAAM,GAAG,WAAW,aAAa,CAAC,GAAG,gBAAgB,aAAa,CAAC,kBACnE,MAAM,2HACN,qBAAqB,GACnB,OAAO,CAAC,+BAA+B,CAAC,CA6CpD;AAhLM,yDARI,MAAM,GAAG,WAAW,aAAa,CAAC,GAAG,gBAAgB,aAAa,CAAC,wBACnE,aAAa,oBACb,GAAG,CAAC,MAAM,CAAC,qBACX,iBAAiB,wBACjB,MAAM,YACN,mCAAmC,GACjC,OAAO,CAAC,+BAA+B,CAAC,CA0HpD;4BAt1CS,YAAY;mCAAZ,YAAY;gCAAZ,YAAY;qCAAZ,YAAY;uCAAZ,YAAY;yDAAZ,YAAY;qDAAZ,YAAY;2CAAZ,YAAY"}

package/src/node-modules.js

@@ -14,7 +14,7 @@
 
 /* eslint no-shadow: 0 */
 
-import { inferExportsAndAliases } from './infer-exports.js';
+import { inferExportsAliasesAndPatterns } from './infer-exports.js';
 import { parseLocatedJson } from './json.js';
 import { join } from './node-module-specifier.js';
 import {
@@ -386,37 +386,6 @@ const inferParsers = (descriptor, location, languageOptions) => {
   return { ...commonjsLanguageForExtension, ...packageLanguageForExtension };
 };
 
-/**
- * This returns the "weight" of a package name, which is used when determining
- * the shortest path.
- *
- * It is an analogue of the `pathCompare` function.
- *
- * The weight is calculated as follows:
- *
- * 1. The {@link String.length length} of the package name contributes a fixed
- *    value of `0x10000` per character. This is because the `pathCompare`
- *    algorithm first compares strings by length and only evaluates code unit
- *    values if the lengths of two strings are equal. `0x10000` is one (1)
- *    greater than the maximum value that {@link String.charCodeAt charCodeAt}
- *    can return (`0xFFFF`), which guarantees longer strings will have higher
- *    weights.
- * 2. Each character in the package name contributes its UTF-16 code unit value
- *    (`0x0` thru `0xFFFF`) to the total. This is the same operation used when
- *    comparing two strings using comparison operators.
- * 3. The total weight is the sum of 1. and 2.
- *
- * @param {string} packageName - Name of package to calculate weight for.
- * @returns {number} Numeric weight
- */
-const calculatePackageWeight = packageName => {
-  let totalCodeValue = packageName.length * 65536; // each character contributes 65536
-  for (let i = 0; i < packageName.length; i += 1) {
-    totalCodeValue += packageName.charCodeAt(i);
-  }
-  return totalCodeValue;
-};
-
 /**
  * `graphPackage` and {@link gatherDependency} are mutually recursive functions that
  * gather the metadata for a package and its transitive dependencies.
@@ -577,13 +546,17 @@ const graphPackage = async (
   const externalAliases = {};
   /** @type {Node['internalAliases']} */
   const internalAliases = {};
+  /** @type {Node['patterns']} */
+  const patterns = [];
 
-  inferExportsAndAliases(
+  inferExportsAliasesAndPatterns(
     packageDescriptor,
     externalAliases,
     internalAliases,
+    patterns,
     conditions,
     types,
+    log,
   );
 
   const parsers = inferParsers(
@@ -602,6 +575,7 @@ const graphPackage = async (
     explicitExports: exportsDescriptor !== undefined,
     externalAliases,
     internalAliases,
+    patterns,
     dependencyLocations,
     types,
     parsers,
@@ -703,11 +677,7 @@ const gatherDependency = async (
 
   dependencyLocations[name] = dependency.packageLocation;
 
-  logicalPathGraph.addEdge(
-    packageLocation,
-    dependency.packageLocation,
-    calculatePackageWeight(name),
-  );
+  logicalPathGraph.addEdge(packageLocation, dependency.packageLocation);
 
   await graphPackage(
     name,
@@ -955,6 +925,7 @@ const translateGraph = (
       label,
       sourceDirname,
       internalAliases,
+      patterns,
       parsers,
       types,
       packageDescriptor,
@@ -983,7 +954,11 @@ const translateGraph = (
      * @param {PackageCompartmentDescriptorName} packageLocation
      */
     const digestExternalAliases = (dependencyName, packageLocation) => {
-      const { externalAliases, explicitExports } = graph[packageLocation];
+      const {
+        externalAliases,
+        explicitExports,
+        patterns: dependencyPatterns,
+      } = graph[packageLocation];
       for (const exportPath of keys(externalAliases).sort()) {
         const targetPath = externalAliases[exportPath];
         // dependency name may be different from package's name,
@@ -996,6 +971,24 @@ const translateGraph = (
           module: targetPath,
         };
       }
+      // Propagate export patterns from dependencies.
+      // Each dependency pattern like "./features/*.js" -> "./src/features/*.js"
+      // becomes "dep/features/*.js" -> "./src/features/*.js" on the dependee,
+      // resolving within the dependency's compartment.
+      if (dependencyPatterns) {
+        for (const { from, to } of dependencyPatterns) {
+          // Only propagate export patterns (starting with "./"), not
+          // import patterns (starting with "#") which are internal.
+          if (from.startsWith('./') || from === '.') {
+            const externalFrom = join(dependencyName, from);
+            patterns.push({
+              from: externalFrom,
+              to,
+              compartment: packageLocation,
+            });
+          }
+        }
+      }
       // if the exports field is not present, then all modules must be accessible
       if (!explicitExports) {
         scopes[dependencyName] = {
@@ -1032,6 +1025,7 @@ const translateGraph = (
       sourceDirname,
       modules: moduleDescriptors,
       scopes,
+      ...(patterns.length > 0 ? { patterns } : {}),
       parsers,
       types,
       policy: /** @type {SomePackagePolicy} */ (packagePolicy),

package/src/pattern-replacement.d.ts

@@ -0,0 +1,6 @@
+export function assertMatchingWildcardCount(pattern: string, replacement: string): void;
+export function makeMultiSubpathReplacer(mapping: PatternDescriptor[] | SubpathMapping): SubpathReplacer;
+import type { PatternDescriptor } from './types/pattern-replacement.js';
+import type { SubpathMapping } from './types/pattern-replacement.js';
+import type { SubpathReplacer } from './types/pattern-replacement.js';
+//# sourceMappingURL=pattern-replacement.d.ts.map

package/src/pattern-replacement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pattern-replacement.d.ts","sourceRoot":"","sources":["pattern-replacement.js"],"names":[],"mappings":"AA6BO,qDAJI,MAAM,eACN,MAAM,QAWhB;AAwFM,kDAHI,iBAAiB,EAAE,GAAG,cAAc,GAClC,eAAe,CA0E3B;uCAtLS,gCAAgC;oCAAhC,gCAAgC;qCAAhC,gCAAgC"}