@endo/compartment-mapper 1.3.1 → 1.5.0

package/src/bundle.js

@@ -1,17 +1,21 @@
-// @ts-check
 /* eslint no-shadow: 0 */
 
-/** @import {StaticModuleType} from 'ses' */
-
-/** @import {ArchiveOptions} from './types.js' */
-/** @import {CompartmentDescriptor} from './types.js' */
-/** @import {CompartmentSources} from './types.js' */
-/** @import {MaybeReadPowers} from './types.js' */
-/** @import {PrecompiledStaticModuleInterface} from 'ses' */
-/** @import {ReadFn} from './types.js' */
-/** @import {ReadPowers} from './types.js' */
-/** @import {Sources} from './types.js' */
-/** @import {WriteFn} from './types.js' */
+/**
+ * @import {
+ *   StaticModuleType,
+ *   PrecompiledStaticModuleInterface
+ * } from 'ses'
+ * @import {
+ *   ArchiveOptions,
+ *   CompartmentDescriptor,
+ *   CompartmentSources,
+ *   MaybeReadPowers,
+ *   ReadFn,
+ *   ReadPowers,
+ *   Sources,
+ *   WriteFn,
+ * } from './types.js'
+ */
 
 /**
  * @typedef {object} BundlerKit
@@ -113,8 +117,14 @@ const sortedModules = (
     const source = compartmentSources[compartmentName][moduleSpecifier];
     if (source !== undefined) {
       const { record, parser, deferredError, bytes } = source;
-      assert(parser !== undefined);
-      assert(bytes !== undefined);
+      assert(
+        bytes !== undefined,
+        `No bytes for ${moduleSpecifier} in ${compartmentName}`,
+      );
+      assert(
+        parser !== undefined,
+        `No parser for ${moduleSpecifier} in ${compartmentName}`,
+      );
       if (deferredError) {
         throw Error(
           `Cannot bundle: encountered deferredError ${deferredError}`,
@@ -231,6 +241,13 @@ export const makeBundle = async (readPowers, moduleLocation, options) => {
     sourceMapHook = undefined,
     parserForLanguage: parserForLanguageOption = {},
     languageForExtension: languageForExtensionOption = {},
+    commonjsLanguageForExtension: commonjsLanguageForExtensionOption = {},
+    moduleLanguageForExtension: moduleLanguageForExtensionOption = {},
+    workspaceLanguageForExtension: workspaceLanguageForExtensionOption = {},
+    workspaceCommonjsLanguageForExtension:
+      workspaceCommonjsLanguageForExtensionOption = {},
+    workspaceModuleLanguageForExtension:
+      workspaceModuleLanguageForExtensionOption = {},
   } = options || {};
   const conditions = new Set(conditionsOption);
 
@@ -244,6 +261,27 @@ export const makeBundle = async (readPowers, moduleLocation, options) => {
   const languageForExtension = Object.freeze(
     Object.assign(Object.create(null), languageForExtensionOption),
   );
+  const commonjsLanguageForExtension = Object.freeze(
+    Object.assign(Object.create(null), commonjsLanguageForExtensionOption),
+  );
+  const moduleLanguageForExtension = Object.freeze(
+    Object.assign(Object.create(null), moduleLanguageForExtensionOption),
+  );
+  const workspaceLanguageForExtension = Object.freeze(
+    Object.assign(Object.create(null), workspaceLanguageForExtensionOption),
+  );
+  const workspaceCommonjsLanguageForExtension = Object.freeze(
+    Object.assign(
+      Object.create(null),
+      workspaceCommonjsLanguageForExtensionOption,
+    ),
+  );
+  const workspaceModuleLanguageForExtension = Object.freeze(
+    Object.assign(
+      Object.create(null),
+      workspaceModuleLanguageForExtensionOption,
+    ),
+  );
 
   const {
     packageLocation,
@@ -262,7 +300,16 @@ export const makeBundle = async (readPowers, moduleLocation, options) => {
     conditions,
     packageDescriptor,
     moduleSpecifier,
-    { dev, commonDependencies },
+    {
+      dev,
+      commonDependencies,
+      languageForExtension,
+      commonjsLanguageForExtension,
+      moduleLanguageForExtension,
+      workspaceLanguageForExtension,
+      workspaceCommonjsLanguageForExtension,
+      workspaceModuleLanguageForExtension,
+    },
   );
 
   const {
@@ -287,7 +334,6 @@ export const makeBundle = async (readPowers, moduleLocation, options) => {
     makeImportHook,
     moduleTransforms,
     parserForLanguage,
-    languageForExtension,
   });
   await compartment.load(entryModuleSpecifier);
 

package/src/capture-lite.d.ts

@@ -1,7 +1,7 @@
-export function captureFromMap(powers: ReadFn | ReadPowers, compartmentMap: CompartmentMapDescriptor, options?: CaptureOptions | undefined): Promise<CaptureResult>;
+export function captureFromMap(powers: ReadFn | ReadPowers, compartmentMap: CompartmentMapDescriptor, options?: CaptureLiteOptions | undefined): Promise<CaptureResult>;
 import type { ReadFn } from './types.js';
 import type { ReadPowers } from './types.js';
 import type { CompartmentMapDescriptor } from './types.js';
-import type { CaptureOptions } from './types.js';
+import type { CaptureLiteOptions } from './types.js';
 import type { CaptureResult } from './types.js';
 //# sourceMappingURL=capture-lite.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"capture-lite.d.ts","sourceRoot":"","sources":["capture-lite.js"],"names":[],"mappings":"AAkQO,uCALI,MAAM,GAAG,UAAU,kBACnB,wBAAwB,yCAEtB,OAAO,CAAC,aAAa,CAAC,CAmElC;4BAlSyB,YAAY;gCACR,YAAY;8CACE,YAAY;oCACtB,YAAY;mCAIb,YAAY"}
+{"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"}

package/src/capture-lite.js

@@ -1,4 +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
@@ -24,27 +25,21 @@
  * 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
  */
 
-// @ts-check
 /* eslint no-shadow: 0 */
 
-/** @import {ReadFn} from './types.js' */
-/** @import {ReadPowers} from './types.js' */
-/** @import {CompartmentMapDescriptor} from './types.js' */
-/** @import {CaptureOptions} from './types.js' */
-/** @import {Sources} from './types.js' */
-/** @import {CompartmentDescriptor} from './types.js' */
-/** @import {ModuleDescriptor} from './types.js' */
-/** @import {CaptureResult} from './types.js' */
+/**
+ * @import {
+ *   CaptureLiteOptions,
+ *   CaptureResult,
+ *   CompartmentMapDescriptor,
+ *   ReadFn,
+ *   ReadPowers,
+ *   Sources,
+ * } from './types.js'
+ */
 
-import {
-  assertCompartmentMap,
-  pathCompare,
-  stringCompare,
-} from './compartment-map.js';
 import {
   exitModuleImportHookMaker,
   makeImportHookMaker,
@@ -53,158 +48,11 @@ import { link } from './link.js';
 import { resolve } from './node-module-specifier.js';
 import { detectAttenuators } from './policy.js';
 import { unpackReadPowers } from './powers.js';
+import { digestCompartmentMap } from './digest.js';
 
-const { freeze, assign, create, fromEntries, entries, keys } = Object;
-
-/**
- * We attempt to produce compartment maps that are consistent regardless of
- * whether the packages were originally laid out on disk for development or
- * production, and other trivia like the fully qualified path of a specific
- * installation.
- *
- * Naming compartments for the self-ascribed name and version of each Node.js
- * package is insufficient because they are not guaranteed to be unique.
- * Dependencies do not necessarilly come from the npm registry and may be
- * for example derived from fully qualified URL's or Github org and project
- * names.
- * Package managers are also not required to fully deduplicate the hard
- * copy of each package even when they are identical resources.
- * Duplication is undesirable, but we elect to defer that problem to solutions
- * in the package managers, as the alternative would be to consistently hash
- * the original sources of the packages themselves, which may not even be
- * available much less pristine for us.
- *
- * So, instead, we use the lexically least path of dependency names, delimited
- * by hashes.
- * The compartment maps generated by the ./node-modules.js tooling pre-compute
- * these traces for our use here.
- * We sort the compartments lexically on their self-ascribed name and version,
- * and use the lexically least dependency name path as a tie-breaker.
- * The dependency path is logical and orthogonal to the package manager's
- * actual installation location, so should be orthogonal to the vagaries of the
- * package manager's deduplication algorithm.
- *
- * @param {Record<string, CompartmentDescriptor>} compartments
- * @returns {Record<string, string>} map from old to new compartment names.
- */
-const renameCompartments = compartments => {
-  /** @type {Record<string, string>} */
-  const compartmentRenames = create(null);
-  let index = 0;
-  let prev = '';
-
-  // The sort below combines two comparators to avoid depending on sort
-  // stability, which became standard as recently as 2019.
-  // If that date seems quaint, please accept my regards from the distant past.
-  // We are very proud of you.
-  const compartmentsByPath = Object.entries(compartments)
-    .map(([name, compartment]) => ({
-      name,
-      path: compartment.path,
-      label: compartment.label,
-    }))
-    .sort((a, b) => {
-      if (a.label === b.label) {
-        assert(a.path !== undefined && b.path !== undefined);
-        return pathCompare(a.path, b.path);
-      }
-      return stringCompare(a.label, b.label);
-    });
-
-  for (const { name, label } of compartmentsByPath) {
-    if (label === prev) {
-      compartmentRenames[name] = `${label}-n${index}`;
-      index += 1;
-    } else {
-      compartmentRenames[name] = label;
-      prev = label;
-      index = 1;
-    }
-  }
-  return compartmentRenames;
-};
-
-/**
- * @param {Record<string, CompartmentDescriptor>} compartments
- * @param {Sources} sources
- * @param {Record<string, string>} compartmentRenames
- */
-const translateCompartmentMap = (compartments, sources, compartmentRenames) => {
-  const result = create(null);
-  for (const compartmentName of keys(compartmentRenames)) {
-    const compartment = compartments[compartmentName];
-    const { name, label, retained, policy } = compartment;
-    if (retained) {
-      // rename module compartments
-      /** @type {Record<string, ModuleDescriptor>} */
-      const modules = create(null);
-      const compartmentModules = compartment.modules;
-      if (compartment.modules) {
-        for (const name of keys(compartmentModules).sort()) {
-          const module = compartmentModules[name];
-          if (module.compartment !== undefined) {
-            modules[name] = {
-              ...module,
-              compartment: compartmentRenames[module.compartment],
-            };
-          } else {
-            modules[name] = module;
-          }
-        }
-      }
-
-      // integrate sources into modules
-      const compartmentSources = sources[compartmentName];
-      if (compartmentSources) {
-        for (const name of keys(compartmentSources).sort()) {
-          const source = compartmentSources[name];
-          const { location, parser, exit, sha512, deferredError } = source;
-          if (location !== undefined) {
-            modules[name] = {
-              location,
-              parser,
-              sha512,
-            };
-          } else if (exit !== undefined) {
-            modules[name] = {
-              exit,
-            };
-          } else if (deferredError !== undefined) {
-            modules[name] = {
-              deferredError,
-            };
-          }
-        }
-      }
+const { freeze, assign, create } = Object;
 
-      result[compartmentRenames[compartmentName]] = {
-        name,
-        label,
-        location: compartmentRenames[compartmentName],
-        modules,
-        policy,
-        // `scopes`, `types`, and `parsers` are not necessary since every
-        // loadable module is captured in `modules`.
-      };
-    }
-  }
-
-  return result;
-};
-
-/**
- * @param {Sources} sources
- * @param {Record<string, string>} compartmentRenames
- * @returns {Sources}
- */
-const renameSources = (sources, compartmentRenames) => {
-  return fromEntries(
-    entries(sources).map(([name, compartmentSources]) => [
-      compartmentRenames[name],
-      compartmentSources,
-    ]),
-  );
-};
+const defaultCompartment = Compartment;
 
 /**
  * @param {CompartmentMapDescriptor} compartmentMap
@@ -213,67 +61,43 @@ const renameSources = (sources, compartmentRenames) => {
  */
 const captureCompartmentMap = (compartmentMap, sources) => {
   const {
-    compartments,
-    entry: { compartment: entryCompartmentName, module: entryModuleSpecifier },
-  } = compartmentMap;
-
-  const compartmentRenames = renameCompartments(compartments);
-  const captureCompartments = translateCompartmentMap(
-    compartments,
-    sources,
+    compartmentMap: captureCompartmentMap,
+    sources: captureSources,
+    newToOldCompartmentNames,
     compartmentRenames,
-  );
-  const captureEntryCompartmentName = compartmentRenames[entryCompartmentName];
-  const captureSources = renameSources(sources, compartmentRenames);
-
-  const captureCompartmentMap = {
-    // TODO graceful migration from tags to conditions
-    // https://github.com/endojs/endo/issues/2388
-    tags: [],
-    entry: {
-      compartment: captureEntryCompartmentName,
-      module: entryModuleSpecifier,
-    },
-    compartments: captureCompartments,
-  };
-
-  // Cross-check:
-  // We assert that we have constructed a valid compartment map, not because it
-  // might not be, but to ensure that the assertCompartmentMap function can
-  // accept all valid compartment maps.
-  assertCompartmentMap(captureCompartmentMap);
-
+    oldToNewCompartmentNames,
+  } = digestCompartmentMap(compartmentMap, sources);
   return {
     captureCompartmentMap,
     captureSources,
     compartmentRenames,
+    newToOldCompartmentNames,
+    oldToNewCompartmentNames,
   };
 };
 
 /**
  * @param {ReadFn | ReadPowers} powers
  * @param {CompartmentMapDescriptor} compartmentMap
- * @param {CaptureOptions} [options]
+ * @param {CaptureLiteOptions} [options]
  * @returns {Promise<CaptureResult>}
  */
 export const captureFromMap = async (powers, compartmentMap, options = {}) => {
   const {
     moduleTransforms,
+    syncModuleTransforms,
     modules: exitModules = {},
     searchSuffixes = undefined,
     importHook: exitModuleImportHook = undefined,
     policy = undefined,
     sourceMapHook = undefined,
     parserForLanguage: parserForLanguageOption = {},
-    languageForExtension: languageForExtensionOption = {},
+    Compartment = defaultCompartment,
   } = options;
 
   const parserForLanguage = freeze(
     assign(create(null), parserForLanguageOption),
   );
-  const languageForExtension = freeze(
-    assign(create(null), languageForExtensionOption),
-  );
 
   const { read, computeSha512 } = unpackReadPowers(powers);
 
@@ -288,6 +112,7 @@ export const captureFromMap = async (powers, compartmentMap, options = {}) => {
   const consolidatedExitModuleImportHook = exitModuleImportHookMaker({
     modules: exitModules,
     exitModuleImportHook,
+    entryCompartmentName,
   });
 
   const makeImportHook = makeImportHookMaker(read, entryCompartmentName, {
@@ -306,9 +131,10 @@ export const captureFromMap = async (powers, compartmentMap, options = {}) => {
     resolve,
     makeImportHook,
     moduleTransforms,
+    syncModuleTransforms,
     parserForLanguage,
-    languageForExtension,
     archiveOnly: true,
+    Compartment,
   });
   await compartment.load(entryModuleSpecifier);
   if (policy) {

package/src/compartment-map.d.ts

@@ -1,5 +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 import("./types.js").CompartmentMapDescriptor;
+export function assertCompartmentMap(allegedCompartmentMap: unknown, url?: string | undefined): 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":"AAWA,+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;AAuZM,4DALI,OAAO,6BAEL,QAAQ,qBAAqB,IAAI,OAAO,YAAY,EAAE,wBAAwB,CA+B1F"}
+{"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"}

package/src/compartment-map.js

@@ -1,8 +1,9 @@
 /* Validates a compartment map against its schema. */
 
-// @ts-check
 import { assertPackagePolicy } from './policy-format.js';
 
+/** @import {CompartmentMapDescriptor} from './types.js' */
+
 // TODO convert to the new `||` assert style.
 // Deferred because this file pervasively uses simple template strings rather than
 // template strings tagged with `assert.details` (aka `X`), and uses
@@ -107,7 +108,7 @@ const assertConditions = (conditions, url) => {
  * @param {string} url
  */
 const assertCompartmentModule = (allegedModule, path, url) => {
-  const { compartment, module, ...extra } = allegedModule;
+  const { compartment, module, retained, ...extra } = allegedModule;
   assertEmptyObject(
     extra,
     `${path} must not have extra properties, got ${q({
@@ -125,6 +126,13 @@ const assertCompartmentModule = (allegedModule, path, url) => {
     'string',
     `${path}.module must be a string, got ${q(module)} in ${q(url)}`,
   );
+  if (retained !== undefined) {
+    assert.typeof(
+      retained,
+      'boolean',
+      `${path}.retained must be a boolean, got ${q(retained)} in ${q(url)}`,
+    );
+  }
 };
 
 /**
@@ -464,7 +472,7 @@ const assertEntry = (allegedEntry, url) => {
 /**
  * @param {unknown} allegedCompartmentMap
  * @param {string} [url]
- * @returns {asserts allegedCompartmentMap is import('./types.js').CompartmentMapDescriptor}
+ * @returns {asserts allegedCompartmentMap is CompartmentMapDescriptor}
  */
 
 export const assertCompartmentMap = (

package/src/digest.d.ts

@@ -0,0 +1,5 @@
+export function digestCompartmentMap(compartmentMap: CompartmentMapDescriptor, sources: Sources): DigestResult;
+import type { CompartmentMapDescriptor } from './types.js';
+import type { Sources } from './types.js';
+import type { DigestResult } from './types.js';
+//# sourceMappingURL=digest.d.ts.map

package/src/digest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"digest.d.ts","sourceRoot":"","sources":["digest.js"],"names":[],"mappings":"AAwLO,qDAJI,wBAAwB,WACxB,OAAO,GACL,YAAY,CAoDxB;8CA3NS,YAAY;6BAAZ,YAAY;kCAAZ,YAAY"}