@endo/compartment-mapper 1.6.3 → 2.1.0

package/src/link.js

@@ -13,28 +13,39 @@
 /**
  * @import {ModuleMapHook} from 'ses'
  * @import {
- *   CompartmentDescriptor,
- *   CompartmentMapDescriptor,
  *   ImportNowHookMaker,
  *   LinkOptions,
  *   LinkResult,
- *   ModuleDescriptor,
  *   ParseFn,
  *   AsyncParseFn,
  *   ParserForLanguage,
  *   ParserImplementation,
  *   ShouldDeferError,
+ *   ScopeDescriptor,
+ *   CompartmentModuleConfiguration,
+ *   PackageCompartmentMapDescriptor,
+ *   FileUrlString,
+ *   PackageCompartmentDescriptor,
+ *   FileCompartmentMapDescriptor,
+ *   FileCompartmentDescriptor,
+ *   FileModuleConfiguration,
  * } from './types.js'
+ * @import {SubpathReplacer} from './types/pattern-replacement.js'
  */
 
 import { makeMapParsers } from './map-parser.js';
 import { resolve as resolveFallback } from './node-module-specifier.js';
 import {
-  ATTENUATORS_COMPARTMENT,
   attenuateGlobals,
-  enforceModulePolicy,
+  enforcePolicyByModule,
   makeDeferredAttenuatorsProvider,
 } from './policy.js';
+import { ATTENUATORS_COMPARTMENT } from './policy-format.js';
+import {
+  isCompartmentModuleConfiguration,
+  isExitModuleConfiguration,
+} from './guards.js';
+import { makeMultiSubpathReplacer } from './pattern-replacement.js';
 
 const { assign, create, entries, freeze } = Object;
 const { hasOwnProperty } = Object.prototype;
@@ -47,17 +58,17 @@ const { allSettled } = Promise;
  */
 const promiseAllSettled = allSettled.bind(Promise);
 
-const defaultCompartment = Compartment;
-
-// q, as in quote, for strings in error messages.
-const q = JSON.stringify;
+const DefaultCompartment = Compartment;
 
 /**
+ * TODO: can we just use `Object.hasOwn` instead?
  * @param {Record<string, unknown>} object
  * @param {string} key
  * @returns {boolean}
  */
 const has = (object, key) => apply(hasOwnProperty, object, [key]);
+// q, as in quote, for strings in error messages.
+const { quote: q } = assert;
 
 /**
  * For a full, absolute module specifier like "dependency",
@@ -89,11 +100,11 @@ const trimModuleSpecifierPrefix = (moduleSpecifier, prefix) => {
  * Any module specifier with an absolute prefix should be captured by
  * the `moduleMap` or `moduleMapHook`.
  *
- * @param {CompartmentDescriptor} compartmentDescriptor
+ * @param {FileCompartmentDescriptor|PackageCompartmentDescriptor} compartmentDescriptor
  * @param {Record<string, Compartment>} compartments
- * @param {string} compartmentName
- * @param {Record<string, ModuleDescriptor>} moduleDescriptors
- * @param {Record<string, ModuleDescriptor>} scopeDescriptors
+ * @param {FileUrlString} compartmentName
+ * @param {Record<string, FileModuleConfiguration|CompartmentModuleConfiguration>} moduleDescriptors
+ * @param {Record<string, ScopeDescriptor<FileUrlString>>} scopeDescriptors
  * @returns {ModuleMapHook | undefined}
  */
 const makeModuleMapHook = (
@@ -103,9 +114,16 @@ 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;
+
   /**
-   * @param {string} moduleSpecifier
-   * @returns {string | object | undefined}
+   * @type {ModuleMapHook}
    */
   const moduleMapHook = moduleSpecifier => {
     compartmentDescriptor.retained = true;
@@ -114,39 +132,90 @@ const makeModuleMapHook = (
     if (moduleDescriptor !== undefined) {
       moduleDescriptor.retained = true;
 
+      if (isExitModuleConfiguration(moduleDescriptor)) {
+        return undefined;
+      }
       // "foreignCompartmentName" refers to the compartment which
       // may differ from the current compartment
-      const {
-        compartment: foreignCompartmentName = compartmentName,
-        module: foreignModuleSpecifier,
-        exit,
-      } = moduleDescriptor;
-      if (exit !== undefined) {
-        return undefined; // fall through to import hook
+      if (isCompartmentModuleConfiguration(moduleDescriptor)) {
+        const {
+          compartment: foreignCompartmentName = compartmentName,
+          module: foreignModuleSpecifier,
+        } = moduleDescriptor;
+        if (foreignModuleSpecifier !== undefined) {
+          // archive goes through foreignModuleSpecifier for local modules too
+          if (!moduleSpecifier.startsWith('./')) {
+            // This code path seems to only be reached on subsequent imports of the same specifier in the same compartment.
+            // The check should be redundant and is only left here out of abundance of caution.
+            enforcePolicyByModule(moduleSpecifier, compartmentDescriptor, {
+              exit: false,
+              errorHint:
+                'This check should not be reachable. If you see this error, please file an issue.',
+            });
+          }
+
+          const foreignCompartment = compartments[foreignCompartmentName];
+          if (foreignCompartment === undefined) {
+            throw Error(
+              `Cannot import from missing compartment ${q(
+                foreignCompartmentName,
+              )}}`,
+            );
+          }
+          // actual module descriptor
+          return {
+            compartment: foreignCompartment,
+            namespace: foreignModuleSpecifier,
+          };
+        }
       }
-      if (foreignModuleSpecifier !== undefined) {
-        // archive goes through foreignModuleSpecifier for local modules too
-        if (!moduleSpecifier.startsWith('./')) {
-          // This code path seems to only be reached on subsequent imports of the same specifier in the same compartment.
-          // The check should be redundant and is only left here out of abundance of caution.
-          enforceModulePolicy(moduleSpecifier, compartmentDescriptor, {
-            exit: false,
-            errorHint:
-              'This check should not be reachable. If you see this error, please file an issue.',
-          });
+    }
+
+    // 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',
+        };
 
-        const foreignCompartment = compartments[foreignCompartmentName];
-        if (foreignCompartment === undefined) {
+        // 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 from missing compartment ${q(
-              foreignCompartmentName,
-            )}}`,
+            `Cannot import module specifier ${q(moduleSpecifier)} from missing compartment ${q(targetCompartmentName)}`,
           );
         }
         return {
-          compartment: foreignCompartment,
-          namespace: foreignModuleSpecifier,
+          compartment: targetCompartment,
+          namespace: resolvedPath,
         };
       }
     }
@@ -178,7 +247,7 @@ const makeModuleMapHook = (
           );
         }
 
-        enforceModulePolicy(scopePrefix, compartmentDescriptor, {
+        enforcePolicyByModule(scopePrefix, compartmentDescriptor, {
           exit: false,
           errorHint: `Blocked in linking. ${q(
             moduleSpecifier,
@@ -198,7 +267,9 @@ const makeModuleMapHook = (
           retained: true,
           compartment: foreignCompartmentName,
           module: foreignModuleSpecifier,
+          __createdBy: 'link',
         };
+        // actual module descriptor
         return {
           compartment: foreignCompartment,
           namespace: foreignModuleSpecifier,
@@ -236,16 +307,10 @@ const impossibleImportNowHookMaker = () => {
  * - Passes the given globals and external modules into the root compartment
  *   only.
  *
- * @param {CompartmentMapDescriptor} compartmentMap
+ * @param {PackageCompartmentMapDescriptor|FileCompartmentMapDescriptor} compartmentMap
  * @param {LinkOptions} options
  * @returns {LinkResult} the root compartment of the compartment DAG
  */
-
-/**
- * @param {CompartmentMapDescriptor} compartmentMap
- * @param {LinkOptions} options
- * @returns {LinkResult}
- */
 export const link = (
   { entry, compartments: compartmentDescriptors },
   options,
@@ -262,7 +327,7 @@ export const link = (
     __shimTransforms__ = [],
     __native__ = false,
     archiveOnly = false,
-    Compartment = defaultCompartment,
+    Compartment = DefaultCompartment,
   } = options;
 
   const { compartment: entryCompartmentName } = entry;
@@ -291,9 +356,14 @@ export const link = (
     syncModuleTransforms,
   });
 
-  for (const [compartmentName, compartmentDescriptor] of entries(
-    compartmentDescriptors,
-  )) {
+  const compartmentDescriptorEntries =
+    /** @type {[FileUrlString, PackageCompartmentDescriptor|FileCompartmentDescriptor][]} */ (
+      entries(compartmentDescriptors)
+    );
+  for (const [
+    compartmentName,
+    compartmentDescriptor,
+  ] of compartmentDescriptorEntries) {
     const {
       location,
       name,
@@ -418,7 +488,7 @@ export const link = (
 };
 
 /**
- * @param {CompartmentMapDescriptor} compartmentMap
+ * @param {PackageCompartmentMapDescriptor} compartmentMap
  * @param {LinkOptions} options
  * @deprecated Use {@link link}.
  */

package/src/node-modules.d.ts

@@ -1,12 +1,13 @@
 export function basename(location: string): string;
-export function compartmentMapForNodeModules(readPowers: ReadFn | ReadPowers<FileUrlString> | MaybeReadPowers<FileUrlString>, packageLocation: FileUrlString, conditionsOption: Set<string>, packageDescriptor: PackageDescriptor, moduleSpecifier: string, options?: CompartmentMapForNodeModulesOptions): Promise<CompartmentMapDescriptor>;
-export function mapNodeModules(readPowers: ReadFn | ReadPowers<FileUrlString> | MaybeReadPowers<FileUrlString>, moduleLocation: string, { tags, conditions, log, ...otherOptions }?: MapNodeModulesOptions): Promise<CompartmentMapDescriptor>;
+export function compartmentMapForNodeModules_(readPowers: ReadFn | ReadPowers<FileUrlString> | MaybeReadPowers<FileUrlString>, entryPackageLocation: FileUrlString, conditionsOption: Set<string>, packageDescriptor: PackageDescriptor, entryModuleSpecifier: string, options?: CompartmentMapForNodeModulesOptions): Promise<PackageCompartmentMapDescriptor>;
+export function mapNodeModules(readPowers: ReadFn | ReadPowers<FileUrlString> | MaybeReadPowers<FileUrlString>, moduleLocation: string, { tags, conditions, log, unknownCanonicalNameHook, packageDataHook, packageDependenciesHook, policy, ...otherOptions }?: MapNodeModulesOptions): Promise<PackageCompartmentMapDescriptor>;
+export function compartmentMapForNodeModules(readPowers: ReadFn | ReadPowers<FileUrlString> | MaybeReadPowers<FileUrlString>, entryPackageLocation: FileUrlString, conditionsOption: Set<string>, packageDescriptor: PackageDescriptor, entryModuleSpecifier: string, options?: CompartmentMapForNodeModulesOptions): Promise<PackageCompartmentMapDescriptor>;
 import type { ReadFn } from './types.js';
 import type { FileUrlString } 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 { PackageCompartmentMapDescriptor } from './types.js';
 import type { MapNodeModulesOptions } 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":"AAyHO,mCAHI,MAAM,GACJ,MAAM,CAYlB;AAw1BM,yDATI,MAAM,GAAG,WAAW,aAAa,CAAC,GAAG,gBAAgB,aAAa,CAAC,mBACnE,aAAa,oBACb,GAAG,CAAC,MAAM,CAAC,qBACX,iBAAiB,mBACjB,MAAM,YACN,mCAAmC,GACjC,OAAO,CAAC,wBAAwB,CAAC,CAgG7C;AAaM,2CALI,MAAM,GAAG,WAAW,aAAa,CAAC,GAAG,gBAAgB,aAAa,CAAC,kBACnE,MAAM,+CACN,qBAAqB,GACnB,OAAO,CAAC,wBAAwB,CAAC,CA6B7C;4BAnjCS,YAAY;mCAAZ,YAAY;gCAAZ,YAAY;qCAAZ,YAAY;uCAAZ,YAAY;yDAAZ,YAAY;8CAAZ,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"}