@endo/compartment-mapper 1.6.3 → 2.1.0

package/src/digest.d.ts

@@ -1,5 +1,25 @@
-export function digestCompartmentMap(compartmentMap: CompartmentMapDescriptor, sources: Sources): DigestResult;
-import type { CompartmentMapDescriptor } from './types.js';
+/**
+ * @template {string} [OldCompartmentName=FileUrlString]
+ * @template {string} [NewCompartmentName=PackageCompartmentDescriptorName]
+ * @overload
+ * @param {PackageCompartmentMapDescriptor} compartmentMap
+ * @param {Sources} sources
+ * @param {DigestCompartmentMapOptions<OldCompartmentName, NewCompartmentName>} [options]
+ * @returns {DigestResult<OldCompartmentName, NewCompartmentName>}
+ */
+export function digestCompartmentMap<OldCompartmentName extends string = `file://${string}`, NewCompartmentName extends string = PackageCompartmentDescriptorName>(compartmentMap: PackageCompartmentMapDescriptor, sources: Sources, options?: DigestCompartmentMapOptions<OldCompartmentName, NewCompartmentName> | undefined): DigestResult<OldCompartmentName, NewCompartmentName>;
+/**
+ * @overload
+ * @param {PackageCompartmentMapDescriptor} compartmentMap
+ * @param {Sources} sources
+ * @param {DigestCompartmentMapOptions<FileUrlString, PackageCompartmentDescriptorName>} [options]
+ * @returns {DigestResult<FileUrlString, PackageCompartmentDescriptorName>}
+ */
+export function digestCompartmentMap(compartmentMap: PackageCompartmentMapDescriptor, sources: Sources, options?: DigestCompartmentMapOptions<`file://${string}`, PackageCompartmentDescriptorName> | undefined): DigestResult<FileUrlString, PackageCompartmentDescriptorName>;
+import type { PackageCompartmentDescriptorName } from './types.js';
+import type { PackageCompartmentMapDescriptor } from './types.js';
 import type { Sources } from './types.js';
+import type { DigestCompartmentMapOptions } from './types.js';
 import type { DigestResult } from './types.js';
+import type { FileUrlString } from './types.js';
 //# sourceMappingURL=digest.d.ts.map

package/src/digest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"digest.d.ts","sourceRoot":"","sources":["digest.js"],"names":[],"mappings":"AAqLO,qDAJI,wBAAwB,WACxB,OAAO,GACL,YAAY,CAoDxB;8CAxNS,YAAY;6BAAZ,YAAY;kCAAZ,YAAY"}
+{"version":3,"file":"digest.d.ts","sourceRoot":"","sources":["digest.js"],"names":[],"mappings":";;;;;;;;;AAiQG,qCA5JoB,kBAAkB,SAA5B,MAAQ,uBACE,kBAAkB,SAA5B,MAAQ,qDA4JV,+BAA+B,WAC/B,OAAO,8FAEL,aAAa,kBAAkB,EAAE,kBAAkB,CAAC,CAChE;;;;;;;;AAGE,qDACQ,+BAA+B,WAC/B,OAAO,4GAEL,aAAa,aAAa,EAAE,gCAAgC,CAAC,CACzE;sDAlPS,YAAY;qDAAZ,YAAY;6BAAZ,YAAY;iDAAZ,YAAY;kCAAZ,YAAY;mCAAZ,YAAY"}

package/src/digest.js

@@ -8,18 +8,41 @@
 
 /**
  * @import {
- *   CompartmentDescriptor,
- *   CompartmentMapDescriptor,
+ *   DigestedCompartmentDescriptors,
  *   DigestResult,
- *   ModuleDescriptor,
+ *   PackageCompartmentDescriptors,
+ *   PackageCompartmentMapDescriptor,
+ *   ModuleConfiguration,
  *   Sources,
+ *   ExitModuleConfiguration,
+ *   FileModuleConfiguration,
+ *   ErrorModuleConfiguration,
+ *   DigestedCompartmentMapDescriptor,
+ *   DigestedCompartmentDescriptor,
+ *   DigestCompartmentMapOptions,
+ *   PackageCompartmentDescriptor,
+ *   PackageCompartmentDescriptorName,
+ *   CompartmentModuleConfiguration,
+ *   CanonicalName,
+ *   CompartmentsRenameFn,
+ FileUrlString,
  * } from './types.js'
  */
 
-import { pathCompare } from '@endo/path-compare';
-import { assertCompartmentMap, stringCompare } from './compartment-map.js';
+import {
+  assertDigestedCompartmentMap,
+  stringCompare,
+} from './compartment-map.js';
+import {
+  isErrorModuleSource,
+  isExitModuleSource,
+  isLocalModuleSource,
+} from './guards.js';
 
-const { create, fromEntries, entries, keys } = Object;
+const { create, fromEntries, entries, keys, values } = Object;
+const { quote: q } = assert;
+
+const noop = () => {};
 
 /**
  * We attempt to produce compartment maps that are consistent regardless of
@@ -49,71 +72,94 @@ const { create, fromEntries, entries, keys } = Object;
  * 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.
+ * @type {CompartmentsRenameFn<FileUrlString, PackageCompartmentDescriptorName>}
  */
-const renameCompartments = compartments => {
-  /** @type {Record<string, string>} */
+const defaultRenameCompartments = compartments => {
+  /** @type {Record<FileUrlString, PackageCompartmentDescriptorName>} */
   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;
-    }
+  const comaprtmentNamesToLabel =
+    /** @type {Array<{name: FileUrlString, label: PackageCompartmentDescriptorName}>} */ (
+      Object.entries(compartments)
+        .map(([name, compartment]) => ({
+          name,
+          label: compartment.label,
+        }))
+        .sort((a, b) => stringCompare(a.label, b.label))
+    );
+
+  for (const { name, label } of comaprtmentNamesToLabel) {
+    compartmentRenames[name] = label;
   }
   return compartmentRenames;
 };
 
 /**
- * @param {Record<string, CompartmentDescriptor>} compartments
+ * @template {string} [OldCompartmentName=FileUrlString]
+ * @template {string} [NewCompartmentName=PackageCompartmentDescriptorName]
+ * @overload
+ * @param {PackageCompartmentDescriptors} compartmentDescriptors
  * @param {Sources} sources
- * @param {Record<string, string>} compartmentRenames
+ * @param {Record<OldCompartmentName, NewCompartmentName>} compartmentRenames
+ * @param {DigestCompartmentMapOptions<OldCompartmentName, NewCompartmentName>} [options]
+ * @returns {DigestedCompartmentDescriptors}
  */
-const translateCompartmentMap = (compartments, sources, compartmentRenames) => {
+/**
+ * @overload
+ * @param {PackageCompartmentDescriptors} compartmentDescriptors
+ * @param {Sources} sources
+ * @param {Record<FileUrlString, PackageCompartmentDescriptorName>} compartmentRenames
+ * @param {DigestCompartmentMapOptions} [options]
+ * @returns {DigestedCompartmentDescriptors}
+ */
+
+/**
+ * @template {string} [OldCompartmentName=FileUrlString]
+ * @template {string} [NewCompartmentName=PackageCompartmentDescriptorName]
+ * @param {PackageCompartmentDescriptors} compartmentDescriptors
+ * @param {Sources} sources
+ * @param {Record<OldCompartmentName, NewCompartmentName>} compartmentRenames
+ * @param {DigestCompartmentMapOptions<OldCompartmentName, NewCompartmentName>} [options]
+ */
+const translateCompartmentMap = (
+  compartmentDescriptors,
+  sources,
+  compartmentRenames,
+  { packageConnectionsHook, log = noop } = {},
+) => {
   const result = create(null);
   for (const compartmentName of keys(compartmentRenames)) {
-    const compartment = compartments[compartmentName];
-    const { name, label, retained: compartmentRetained, policy } = compartment;
+    /** @type {PackageCompartmentDescriptor} */
+    const compartmentDescriptor = compartmentDescriptors[compartmentName];
+    const {
+      name,
+      label,
+      retained: compartmentRetained,
+      policy,
+    } = compartmentDescriptor;
+    /** @type {Record<string, PackageCompartmentDescriptorName>} */
+    const renamedModuleConfigurations = {};
     if (compartmentRetained) {
       // rename module compartments
-      /** @type {Record<string, ModuleDescriptor>} */
+      /** @type {Record<string, ModuleConfiguration>} */
       const modules = create(null);
-      const compartmentModules = compartment.modules;
-      if (compartment.modules) {
+      const compartmentModules = compartmentDescriptor.modules;
+      if (compartmentDescriptor.modules) {
         for (const name of keys(compartmentModules).sort()) {
           const { retained: moduleRetained, ...retainedModule } =
             compartmentModules[name];
           if (moduleRetained) {
             if (retainedModule.compartment !== undefined) {
+              /** @type {CompartmentModuleConfiguration} */
               modules[name] = {
                 ...retainedModule,
                 compartment: compartmentRenames[retainedModule.compartment],
               };
+              renamedModuleConfigurations[name] = retainedModule.compartment;
             } else {
               modules[name] = retainedModule;
             }
@@ -126,25 +172,40 @@ const translateCompartmentMap = (compartments, sources, compartmentRenames) => {
       if (compartmentSources) {
         for (const name of keys(compartmentSources).sort()) {
           const source = compartmentSources[name];
-          const { location, parser, exit, sha512, deferredError } = source;
-          if (location !== undefined) {
+          if (isLocalModuleSource(source)) {
+            const { location, parser, sha512 } = source;
+            /** @type {FileModuleConfiguration} */
             modules[name] = {
               location,
               parser,
-              sha512,
+              ...(sha512 !== undefined && { sha512 }),
+              __createdBy: 'digest',
             };
-          } else if (exit !== undefined) {
+          } else if (isExitModuleSource(source)) {
+            const { exit } = source;
+            /** @type {ExitModuleConfiguration} */
             modules[name] = {
               exit,
+              __createdBy: 'digest',
             };
-          } else if (deferredError !== undefined) {
+          } else if (isErrorModuleSource(source)) {
+            const { deferredError } = source;
+            /** @type {ErrorModuleConfiguration} */
             modules[name] = {
               deferredError,
+              __createdBy: 'digest',
             };
+          } else {
+            throw new TypeError(
+              `Unexpected source type for compartment ${compartmentName} module ${name}: ${q(
+                source,
+              )}`,
+            );
           }
         }
       }
 
+      /** @type {DigestedCompartmentDescriptor} */
       result[compartmentRenames[compartmentName]] = {
         name,
         label,
@@ -154,6 +215,23 @@ const translateCompartmentMap = (compartments, sources, compartmentRenames) => {
         // `scopes`, `types`, and `parsers` are not necessary since every
         // loadable module is captured in `modules`.
       };
+
+      const links = /** @type {Set<CanonicalName>} */ (
+        values(modules).reduce((acc, moduleDescriptorConfig) => {
+          if ('compartment' in moduleDescriptorConfig) {
+            acc.add(moduleDescriptorConfig.compartment);
+          }
+          return acc;
+        }, new Set())
+      );
+
+      if (packageConnectionsHook) {
+        packageConnectionsHook({
+          canonicalName: label,
+          connections: links,
+          log,
+        });
+      }
     }
   }
 
@@ -175,26 +253,53 @@ const renameSources = (sources, compartmentRenames) => {
 };
 
 /**
- * @param {CompartmentMapDescriptor} compartmentMap
+ * @template {string} [OldCompartmentName=FileUrlString]
+ * @template {string} [NewCompartmentName=PackageCompartmentDescriptorName]
+ * @overload
+ * @param {PackageCompartmentMapDescriptor} compartmentMap
+ * @param {Sources} sources
+ * @param {DigestCompartmentMapOptions<OldCompartmentName, NewCompartmentName>} [options]
+ * @returns {DigestResult<OldCompartmentName, NewCompartmentName>}
+ */
+
+/**
+ * @overload
+ * @param {PackageCompartmentMapDescriptor} compartmentMap
  * @param {Sources} sources
- * @returns {DigestResult}
+ * @param {DigestCompartmentMapOptions<FileUrlString, PackageCompartmentDescriptorName>} [options]
+ * @returns {DigestResult<FileUrlString, PackageCompartmentDescriptorName>}
  */
-export const digestCompartmentMap = (compartmentMap, sources) => {
+
+/**
+ * @template {string} [OldCompartmentName=FileUrlString]
+ * @template {string} [NewCompartmentName=PackageCompartmentDescriptorName]
+ * @param {PackageCompartmentMapDescriptor} compartmentMap
+ * @param {Sources} sources
+ * @param {DigestCompartmentMapOptions<OldCompartmentName, NewCompartmentName>} [options]
+ */
+export const digestCompartmentMap = (
+  compartmentMap,
+  sources,
+  { packageConnectionsHook, log = noop, renameCompartments } = {},
+) => {
   const {
     compartments,
     entry: { compartment: entryCompartmentName, module: entryModuleSpecifier },
   } = compartmentMap;
 
-  const oldToNewCompartmentNames = renameCompartments(compartments);
+  const renameCompartmentsFn = renameCompartments ?? defaultRenameCompartments;
+  const oldToNewCompartmentNames = renameCompartmentsFn(compartments);
   const digestCompartments = translateCompartmentMap(
     compartments,
     sources,
     oldToNewCompartmentNames,
+    { packageConnectionsHook, log },
   );
   const digestEntryCompartmentName =
     oldToNewCompartmentNames[entryCompartmentName];
   const digestSources = renameSources(sources, oldToNewCompartmentNames);
 
+  /** @type {DigestedCompartmentMapDescriptor} */
   const digestCompartmentMap = {
     // TODO graceful migration from tags to conditions
     // https://github.com/endojs/endo/issues/2388
@@ -210,8 +315,18 @@ export const digestCompartmentMap = (compartmentMap, sources) => {
   // 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(digestCompartmentMap);
+  try {
+    assertDigestedCompartmentMap(digestCompartmentMap);
+  } catch (err) {
+    throw new TypeError(
+      `Invalid compartment map; ${JSON.stringify(
+        digestCompartmentMap,
+      )}:\n${err.message}`,
+      { cause: err },
+    );
+  }
 
+  /** @type {Record<NewCompartmentName, OldCompartmentName>} */
   const newToOldCompartmentNames = fromEntries(
     entries(oldToNewCompartmentNames).map(([oldName, newName]) => [
       newName,
@@ -219,14 +334,22 @@ export const digestCompartmentMap = (compartmentMap, sources) => {
     ]),
   );
 
-  /** @type {DigestResult} */
-  const digestResult = {
+  if (renameCompartments === defaultRenameCompartments) {
+    /** @type {DigestResult} */
+    return {
+      compartmentMap: digestCompartmentMap,
+      sources: digestSources,
+      oldToNewCompartmentNames,
+      newToOldCompartmentNames,
+      compartmentRenames: newToOldCompartmentNames,
+    };
+  }
+  /** @type {DigestResult<OldCompartmentName, NewCompartmentName>} */
+  return {
     compartmentMap: digestCompartmentMap,
     sources: digestSources,
     oldToNewCompartmentNames,
     newToOldCompartmentNames,
     compartmentRenames: newToOldCompartmentNames,
   };
-
-  return digestResult;
 };

package/src/generic-graph.d.ts

@@ -1,11 +1,10 @@
 /**
- * @template [T=string] The type of nodes in the graph
+ * A generic graph implementation.
  *
- * A generic graph implementation with edge weights.
- *
- * Edge weights are assumed to be non-negative numbers (including `Infinity`)
+ * @template {GenericGraphNode} [T=string] The type of nodes in the graph. If
+ * `T` is not a string, relative paths will be compared by coercion to strings.
  */
-export class GenericGraph<T = string> {
+export class GenericGraph<T extends GenericGraphNode = string> {
     /**
      * Returns a shallow copy of the `Set` of nodes in the graph.
      */
@@ -31,23 +30,6 @@ export class GenericGraph<T = string> {
      * @returns {Set<T>|undefined}
      */
     adjacent(node: T): Set<T> | undefined;
-    /**
-     * Sets the weight of the given edge between `source` and `target`.
-     *
-     * @param {T} source Source node
-     * @param {T} target Target node
-     * @param {number} weight New edge weight
-     * @returns {this}
-     */
-    setEdgeWeight(source: T, target: T, weight: number): this;
-    /**
-     * Gets the weight of the given edge between `source` and `target`.
-     *
-     * @param {T} source Source node
-     * @param {T} target Target node
-     * @returns {number} Edge weight from source to target
-     */
-    getEdgeWeight(source: T, target: T): number;
     /**
      * Adds an edge from the `source` node to `target` node.
      *
@@ -58,10 +40,9 @@ export class GenericGraph<T = string> {
      *
      * @param {T} source Source node
      * @param {T} target Target node
-     * @param {number} weight Edge weight from source to target
      * @returns {this} This graph instance
      */
-    addEdge(source: T, target: T, weight: number): this;
+    addEdge(source: T, target: T): this;
     /**
      * Removes the edge from the `source` node to `target` node.
      * Does not remove the nodes themselves.
@@ -80,5 +61,6 @@ export class GenericGraph<T = string> {
     hasEdge(source: T, target: T): boolean;
     #private;
 }
-export function makeShortestPath<T = string>(graph: GenericGraph<T>): (source: NoInfer<T>, target: NoInfer<T>) => [T, T, ...T[]];
+export function makeShortestPath<T extends GenericGraphNode = string>(graph: GenericGraph<T>): (source: NoInfer<T>, target: NoInfer<T>) => [T, T, ...T[]];
+import type { GenericGraphNode } from './types/generic-graph.js';
 //# sourceMappingURL=generic-graph.d.ts.map

package/src/generic-graph.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generic-graph.d.ts","sourceRoot":"","sources":["generic-graph.js"],"names":[],"mappings":"AAoHA;;;;;;GAMG;AACH,0BANc,CAAC;IA+Bb;;OAEG;IACH,oBAEC;IAED;;;;;;OAMG;IACH,cAHW,CAAC,GACC,IAAI,CAUhB;IAED;;;;;OAKG;IACH,iBAHW,CAAC,GACC,IAAI,CAShB;IAED;;;;OAIG;IACH,eAHW,CAAC,GACC,GAAG,CAAC,CAAC,CAAC,GAAC,SAAS,CAI5B;IAED;;;;;;;OAOG;IACH,sBALW,CAAC,UACD,CAAC,UACD,MAAM,GACJ,IAAI,CAWhB;IAED;;;;;;OAMG;IACH,sBAJW,CAAC,UACD,CAAC,GACC,MAAM,CAUlB;IAED;;;;;;;;;;;;OAYG;IACH,gBALW,CAAC,UACD,CAAC,UACD,MAAM,GACJ,IAAI,CAWhB;IAED;;;;;;;OAOG;IACH,mBAJW,CAAC,UACD,CAAC,GACC,IAAI,CAKhB;IAED;;;;;OAKG;IACH,gBAJW,CAAC,UACD,CAAC,GACC,OAAO,CAInB;;CACF;AA6DM,iCAHO,CAAC,kBACJ,YAAY,CAAC,CAAC,CAAC,YAIb,OAAO,CAAC,CAAC,CAAC,UACV,OAAO,CAAC,CAAC,CAAC,KACR,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAO5B"}
+{"version":3,"file":"generic-graph.d.ts","sourceRoot":"","sources":["generic-graph.js"],"names":[],"mappings":"AAsIA;;;;;GAKG;AACH,0BAHiC,CAAC,SAArB,gBAAkB;IAsB7B;;OAEG;IACH,oBAEC;IAED;;;;;;OAMG;IACH,cAHW,CAAC,GACC,IAAI,CAUhB;IAED;;;;;OAKG;IACH,iBAHW,CAAC,GACC,IAAI,CAShB;IAED;;;;OAIG;IACH,eAHW,CAAC,GACC,GAAG,CAAC,CAAC,CAAC,GAAC,SAAS,CAI5B;IAED;;;;;;;;;;;OAWG;IACH,gBAJW,CAAC,UACD,CAAC,GACC,IAAI,CAUhB;IAED;;;;;;;OAOG;IACH,mBAJW,CAAC,UACD,CAAC,GACC,IAAI,CAKhB;IAED;;;;;OAKG;IACH,gBAJW,CAAC,UACD,CAAC,GACC,OAAO,CAInB;;CACF;AAwDM,iCAH0B,CAAC,SAArB,gBAAkB,kBACpB,YAAY,CAAC,CAAC,CAAC,YAOb,OAAO,CAAC,CAAC,CAAC,UACV,OAAO,CAAC,CAAC,CAAC,KACR,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAW5B;sCAvToD,0BAA0B"}