@endo/compartment-mapper 1.6.3 → 2.1.0

package/src/node-modules.js

@@ -1,3 +1,4 @@
+/* eslint-disable no-underscore-dangle */
 /**
  * Provides functions for constructing a compartment map that has a
  * compartment descriptor corresponding to every reachable package from an
@@ -13,15 +14,16 @@
 
 /* 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 { assertPolicy } from './policy-format.js';
 import {
+  assertPolicy,
   ATTENUATORS_COMPARTMENT,
-  dependencyAllowedByPolicy,
-  getPolicyForPackage,
-} from './policy.js';
+  ENTRY_COMPARTMENT,
+  generateCanonicalName,
+} from './policy-format.js';
+import { dependencyAllowedByPolicy, makePackagePolicy } from './policy.js';
 import { unpackReadPowers } from './powers.js';
 import { search, searchDescriptor } from './search.js';
 import { GenericGraph, makeShortestPath } from './generic-graph.js';
@@ -41,8 +43,16 @@ import { GenericGraph, makeShortestPath } from './generic-graph.js';
  *   PackageDescriptor,
  *   ReadFn,
  *   ReadPowers,
- *   SomePackagePolicy,
  *   SomePolicy,
+ *   LogFn,
+ *   CompartmentModuleConfiguration,
+ *   PackageCompartmentDescriptor,
+ *   PackageCompartmentMapDescriptor,
+ *   ScopeDescriptor,
+ *   CanonicalName,
+ *   SomePackagePolicy,
+ *   PackageCompartmentDescriptorName,
+ *   PackageData,
  * } from './types.js'
  * @import {
  *   Graph,
@@ -54,21 +64,78 @@ import { GenericGraph, makeShortestPath } from './generic-graph.js';
  *   GraphPackagesOptions,
  *   LogicalPathGraph,
  *   PackageDetails,
+ *   FinalGraph,
+ *   CanonicalNameMap,
+ *   FinalNode,
+ TranslateGraphOptions,
  * } from './types/node-modules.js'
  */
 
-const { assign, create, keys, values, entries } = Object;
+const { assign, create, keys, values, entries, freeze } = Object;
 
 const decoder = new TextDecoder();
 
 // q, as in quote, for enquoting strings in error messages.
-const q = JSON.stringify;
+const { quote: q } = assert;
 
 /**
  * Default logger that does nothing.
  */
 const noop = () => {};
 
+/**
+ * Default handler for unknown canonical names found in policy.
+ * Logs a warning when a canonical name from policy is not found in the compartment map.
+ *
+ * @param {object} params
+ * @param {CanonicalName} params.canonicalName
+ * @param {string} params.message
+ * @param {LogFn} params.log
+ */
+const defaultUnknownCanonicalNameHandler = ({
+  canonicalName,
+  message,
+  log,
+}) => {
+  log(`WARN: Invalid resource ${q(canonicalName)} in policy: ${message}`);
+};
+
+/**
+ * Default filter for package dependencies based on policy.
+ * Filters out dependencies not allowed by the package policy.
+ *
+ * **Note:** This filter is _only_ applied if a policy is provided.
+ *
+ * @param {object} params - The parameters object
+ * @param {CanonicalName} params.canonicalName - The canonical name of the package
+ * @param {Readonly<Set<CanonicalName>>} params.dependencies - The set of dependencies
+ * @param {LogFn} params.log - The logging function
+ * @param {SomePolicy} policy - The policy to check against
+ * @returns {Partial<{ dependencies: Set<CanonicalName> }> | void}
+ */
+const prePackageDependenciesFilter = (
+  { canonicalName, dependencies, log },
+  policy,
+) => {
+  const packagePolicy = makePackagePolicy(canonicalName, { policy });
+  if (!packagePolicy) {
+    return { dependencies };
+  }
+  const filteredDependencies = new Set(
+    [...dependencies].filter(dependency => {
+      const allowed = dependencyAllowedByPolicy(dependency, packagePolicy);
+      if (!allowed) {
+        log(
+          `Excluding dependency ${q(dependency)} of package ${q(canonicalName)} per policy`,
+        );
+      }
+      return allowed;
+    }),
+  );
+
+  return { dependencies: filteredDependencies };
+};
+
 /**
  * Given a relative path andd URL, return a fully qualified URL string.
  *
@@ -319,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.
@@ -368,7 +404,7 @@ const calculatePackageWeight = packageName => {
  * @param {LanguageOptions} languageOptions
  * @param {boolean} strict
  * @param {LogicalPathGraph} logicalPathGraph
- * @param {GraphPackageOptions} [options]
+ * @param {GraphPackageOptions} options
  * @returns {Promise<undefined>}
  */
 const graphPackage = async (
@@ -382,7 +418,12 @@ const graphPackage = async (
   languageOptions,
   strict,
   logicalPathGraph,
-  { commonDependencyDescriptors = {}, logicalPath = [], log = noop } = {},
+  {
+    commonDependencyDescriptors = {},
+    log = noop,
+    packageDependenciesHook,
+    policy,
+  } = {},
 ) => {
   if (graph[packageLocation] !== undefined) {
     // Returning the promise here would create a causal cycle and stall recursion.
@@ -397,7 +438,7 @@ const graphPackage = async (
     });
   }
 
-  const result = /** @type {Node} */ ({});
+  const result = /** @type {Node} */ ({ location: packageLocation });
   graph[packageLocation] = result;
 
   /** @type {Node['dependencyLocations']} */
@@ -461,7 +502,6 @@ const graphPackage = async (
 
   for (const dependencyName of [...allDependencies].sort()) {
     const optional = optionals.has(dependencyName);
-    const childLogicalPath = [...logicalPath, dependencyName];
     children.push(
       // Mutual recursion ahead:
       // eslint-disable-next-line no-use-before-define
@@ -477,10 +517,11 @@ const graphPackage = async (
         strict,
         logicalPathGraph,
         {
-          childLogicalPath,
           optional,
           commonDependencyDescriptors,
           log,
+          packageDependenciesHook,
+          policy,
         },
       ),
     );
@@ -505,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(
@@ -522,18 +567,21 @@ const graphPackage = async (
 
   const sourceDirname = basename(packageLocation);
 
-  assign(result, {
+  /** @type {Partial<Node>} */
+  const partialNode = {
     name,
-    path: logicalPath,
     label: `${name}${version ? `-v${version}` : ''}`,
     sourceDirname,
     explicitExports: exportsDescriptor !== undefined,
     externalAliases,
     internalAliases,
+    patterns,
     dependencyLocations,
     types,
     parsers,
-  });
+    packageDescriptor,
+  };
+  assign(result, partialNode);
 
   await Promise.all(
     values(result.externalAliases).map(async item => {
@@ -605,10 +653,11 @@ const gatherDependency = async (
   strict,
   logicalPathGraph,
   {
-    childLogicalPath = [],
     optional = false,
     commonDependencyDescriptors = {},
     log = noop,
+    packageDependenciesHook,
+    policy,
   } = {},
 ) => {
   const dependency = await findPackage(
@@ -617,6 +666,7 @@ const gatherDependency = async (
     packageLocation,
     name,
   );
+
   if (dependency === undefined) {
     // allow the dependency to be missing if optional
     if (optional || !strict) {
@@ -624,13 +674,10 @@ const gatherDependency = async (
     }
     throw Error(`Cannot find dependency ${name} for ${packageLocation}`);
   }
+
   dependencyLocations[name] = dependency.packageLocation;
 
-  logicalPathGraph.addEdge(
-    packageLocation,
-    dependency.packageLocation,
-    calculatePackageWeight(name),
-  );
+  logicalPathGraph.addEdge(packageLocation, dependency.packageLocation);
 
   await graphPackage(
     name,
@@ -645,8 +692,9 @@ const gatherDependency = async (
     logicalPathGraph,
     {
       commonDependencyDescriptors,
-      logicalPath: childLogicalPath,
       log,
+      packageDependenciesHook,
+      policy,
     },
   );
 };
@@ -669,7 +717,7 @@ const gatherDependency = async (
  * @param {LanguageOptions} languageOptions
  * @param {boolean} strict
  * @param {LogicalPathGraph} logicalPathGraph
- * @param {GraphPackagesOptions} [options]
+ * @param {GraphPackagesOptions} options
  * @returns {Promise<Graph>}
  */
 const graphPackages = async (
@@ -683,7 +731,7 @@ const graphPackages = async (
   languageOptions,
   strict,
   logicalPathGraph,
-  { log = noop } = {},
+  { log = noop, packageDependenciesHook, policy } = {},
 ) => {
   const memo = create(null);
   /**
@@ -749,6 +797,8 @@ const graphPackages = async (
     {
       commonDependencyDescriptors,
       log,
+      packageDependenciesHook,
+      policy,
     },
   );
   return graph;
@@ -763,19 +813,101 @@ const graphPackages = async (
  * @param {Graph} graph
  * @param {Set<string>} conditions - build conditions about the target environment
  * for selecting relevant exports, e.g., "browser" or "node".
- * @param {SomePolicy} [policy]
- * @returns {CompartmentMapDescriptor}
+ * @param {TranslateGraphOptions} [options]
+ * @returns {PackageCompartmentMapDescriptor}
  */
 const translateGraph = (
   entryPackageLocation,
   entryModuleSpecifier,
   graph,
   conditions,
-  policy,
+  { policy, log = noop, packageDependenciesHook } = {},
 ) => {
-  /** @type {CompartmentMapDescriptor['compartments']} */
+  /** @type {Record<PackageCompartmentDescriptorName, PackageCompartmentDescriptor>} */
   const compartments = create(null);
 
+  /**
+   * Execute package dependencies hooks: default first (if policy exists), then user-provided.
+   *
+   * @param {CanonicalName} label
+   * @param {Record<string, FileUrlString>} dependencyLocations
+   * @returns {Record<string, FileUrlString>}
+   */
+  const executePackageDependenciesHook = (label, dependencyLocations) => {
+    const dependencies = new Set(
+      values(dependencyLocations).map(
+        dependencyLocation => graph[dependencyLocation].label,
+      ),
+    );
+
+    const packageDependenciesHookInput = {
+      canonicalName: label,
+      dependencies: new Set(dependencies),
+      log,
+    };
+
+    // Call default filter first if policy exists
+    let packageDependenciesHookResult;
+    if (policy) {
+      packageDependenciesHookResult = prePackageDependenciesFilter(
+        packageDependenciesHookInput,
+        policy,
+      );
+    }
+
+    // Then call user-provided hook if it exists
+    if (packageDependenciesHook) {
+      const userResult = packageDependenciesHook(packageDependenciesHookInput);
+      // If user hook also returned a result, use it (overrides default)
+      if (userResult?.dependencies) {
+        packageDependenciesHookResult = userResult;
+      }
+    }
+
+    // if "dependencies" are in here, then something changed the list.
+    if (packageDependenciesHookResult?.dependencies) {
+      const size = packageDependenciesHookResult.dependencies.size;
+      if (typeof size === 'number' && size > 0) {
+        // because the list of dependencies contains canonical names, we need to lookup any new ones.
+        const nodesByCanonicalName = new Map(
+          entries(graph).map(([location, node]) => [
+            node.label,
+            {
+              ...node,
+              packageLocation: /** @type {FileUrlString} */ (location),
+            },
+          ]),
+        );
+
+        /** @type {typeof dependencyLocations} */
+        const newDependencyLocations = {};
+        try {
+          for (const label of packageDependenciesHookResult.dependencies) {
+            const { name, packageLocation } =
+              nodesByCanonicalName.get(label) ?? create(null);
+            if (name && packageLocation) {
+              newDependencyLocations[name] = packageLocation;
+            } else {
+              log(
+                `WARNING: packageDependencies hook returned unknown package with label ${q(label)}`,
+              );
+            }
+          }
+          return newDependencyLocations;
+        } catch {
+          log(
+            `WARNING: packageDependencies hook returned invalid value ${q(
+              packageDependenciesHookResult,
+            )}; using original dependencies`,
+          );
+        }
+      } else {
+        dependencyLocations = create(null);
+      }
+    }
+    return dependencyLocations;
+  };
+
   // For each package, build a map of all the external modules the package can
   // import from other packages.
   // The keys of this map are the full specifiers of those modules from the
@@ -785,36 +917,25 @@ const translateGraph = (
   // The full map includes every exported module from every dependencey
   // package and is a complete list of every external module that the
   // corresponding compartment can import.
-  for (const dependeeLocation of keys(graph).sort()) {
+  for (const dependeeLocation of /** @type {PackageCompartmentDescriptorName[]} */ (
+    keys(graph).sort()
+  )) {
     const {
       name,
-      path,
       label,
       sourceDirname,
-      dependencyLocations,
       internalAliases,
+      patterns,
       parsers,
       types,
+      packageDescriptor,
     } = graph[dependeeLocation];
-    /** @type {CompartmentDescriptor['modules']} */
+    /** @type {Record<string, CompartmentModuleConfiguration>} */
     const moduleDescriptors = create(null);
-    /** @type {CompartmentDescriptor['scopes']} */
+    /** @type {Record<string, ScopeDescriptor<PackageCompartmentDescriptorName>>} */
     const scopes = create(null);
 
-    /**
-     * List of all the compartments (by name) that this compartment can import from.
-     *
-     * @type {Set<string>}
-     */
-    const compartmentNames = new Set();
-    const packagePolicy = getPolicyForPackage(
-      {
-        isEntry: dependeeLocation === entryPackageLocation,
-        name,
-        path,
-      },
-      policy,
-    );
+    const packagePolicy = makePackagePolicy(label, { policy });
 
     /* c8 ignore next */
     if (policy && !packagePolicy) {
@@ -822,33 +943,50 @@ const translateGraph = (
       throw new TypeError('Unexpectedly falsy package policy');
     }
 
+    let dependencyLocations = graph[dependeeLocation].dependencyLocations;
+    dependencyLocations = executePackageDependenciesHook(
+      label,
+      dependencyLocations,
+    );
+
     /**
      * @param {string} dependencyName
-     * @param {string} packageLocation
+     * @param {PackageCompartmentDescriptorName} packageLocation
      */
     const digestExternalAliases = (dependencyName, packageLocation) => {
-      const { externalAliases, explicitExports, name, path } =
-        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,
-        // as in the case of browser field dependency replacements
+        // as in the case of browser field dependency replacements.
+        // note that policy still applies
         const localPath = join(dependencyName, exportPath);
-        if (
-          !policy ||
-          (packagePolicy &&
-            dependencyAllowedByPolicy(
-              {
-                name,
-                path,
-              },
-              packagePolicy,
-            ))
-        ) {
-          moduleDescriptors[localPath] = {
-            compartment: packageLocation,
-            module: targetPath,
-          };
+        // if we have policy, this has already been vetted
+        moduleDescriptors[localPath] = {
+          compartment: packageLocation,
+          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
@@ -864,7 +1002,6 @@ const translateGraph = (
     for (const dependencyName of keys(dependencyLocations).sort()) {
       const dependencyLocation = dependencyLocations[dependencyName];
       digestExternalAliases(dependencyName, dependencyLocation);
-      compartmentNames.add(dependencyLocation);
     }
     // digest own internal aliases
     for (const modulePath of keys(internalAliases).sort()) {
@@ -881,17 +1018,17 @@ const translateGraph = (
     }
 
     compartments[dependeeLocation] = {
+      version: packageDescriptor.version ? packageDescriptor.version : '',
       label,
       name,
-      path,
       location: dependeeLocation,
       sourceDirname,
       modules: moduleDescriptors,
       scopes,
+      ...(patterns.length > 0 ? { patterns } : {}),
       parsers,
       types,
       policy: /** @type {SomePackagePolicy} */ (packagePolicy),
-      compartments: compartmentNames,
     };
   }
 
@@ -900,7 +1037,7 @@ const translateGraph = (
     // https://github.com/endojs/endo/issues/2388
     tags: [...conditions],
     entry: {
-      compartment: entryPackageLocation,
+      compartment: /** @type {FileUrlString} */ (entryPackageLocation),
       module: entryModuleSpecifier,
     },
     compartments,
@@ -974,23 +1111,200 @@ const makeLanguageOptions = ({
     workspaceModuleLanguageForExtension,
   };
 };
+/**
+ * Creates a `Node` in `graph` corresponding to the "attenuators" Compartment.
+ *
+ * Only does so if `policy` is provided.
+ *
+ * @param {Graph} graph Graph
+ * @param {Node} entryNode Entry node of the grpah
+ * @param {SomePolicy} [policy]
+ * @throws If there's already a `Node` in `graph` for the "attenuators"
+ * Compartment
+ * @returns {void}
+ */
+const makeAttenuatorsNode = (graph, entryNode, policy) => {
+  if (policy) {
+    assertPolicy(policy);
+
+    assert(
+      graph[ATTENUATORS_COMPARTMENT] === undefined,
+      `${q(ATTENUATORS_COMPARTMENT)} is a reserved compartment name`,
+    );
+
+    graph[ATTENUATORS_COMPARTMENT] = {
+      ...entryNode,
+      internalAliases: {},
+      externalAliases: {},
+      packageDescriptor: { name: ATTENUATORS_COMPARTMENT },
+      name: ATTENUATORS_COMPARTMENT,
+    };
+  }
+};
+
+/**
+ * Transforms a `Graph` into a readonly `FinalGraph`, in preparation for
+ * conversion to a `CompartmentDescriptor`.
+ *
+ * @param {Graph} graph Graph
+ * @param {LogicalPathGraph} logicalPathGraph Logical path graph
+ * @param {FileUrlString} entryPackageLocation Entry package location
+ * @param {CanonicalNameMap} canonicalNameMap Mapping of canonical names to `Node` names (keys in `graph`)
+ * @returns {Readonly<FinalGraph>}
+ */
+const finalizeGraph = (
+  graph,
+  logicalPathGraph,
+  entryPackageLocation,
+  canonicalNameMap,
+) => {
+  const shortestPath = makeShortestPath(logicalPathGraph);
+
+  // neither the entry package nor the attenuators compartment have a path; omit
+  const {
+    [ATTENUATORS_COMPARTMENT]: attenuatorsNode,
+    [entryPackageLocation]: entryNode,
+    ...subgraph
+  } = graph;
+
+  /** @type {FinalGraph} */
+  const finalGraph = create(null);
+
+  /** @type {Readonly<FinalNode>} */
+  finalGraph[entryPackageLocation] = freeze({
+    ...entryNode,
+    label: generateCanonicalName({
+      isEntry: true,
+      path: [],
+    }),
+  });
+
+  canonicalNameMap.set(ENTRY_COMPARTMENT, entryPackageLocation);
+
+  if (attenuatorsNode) {
+    /** @type {Readonly<FinalNode>} */
+    finalGraph[ATTENUATORS_COMPARTMENT] = freeze({
+      ...attenuatorsNode,
+      label: generateCanonicalName({
+        name: ATTENUATORS_COMPARTMENT,
+        path: [],
+      }),
+    });
+  }
+
+  const subgraphEntries = /** @type {[FileUrlString, Node][]} */ (
+    entries(subgraph)
+  );
+
+  for (const [location, node] of subgraphEntries) {
+    const shortestLogicalPath = shortestPath(entryPackageLocation, location);
+
+    // the first element will always be the root package location; this is omitted from the path.
+    shortestLogicalPath.shift();
+
+    const path = shortestLogicalPath.map(location => graph[location].name);
+    const canonicalName = generateCanonicalName({ path });
+
+    /** @type {Readonly<FinalNode>} */
+    const finalNode = freeze({
+      ...node,
+      label: canonicalName,
+    });
+
+    canonicalNameMap.set(canonicalName, location);
+
+    finalGraph[location] = finalNode;
+  }
+
+  for (const node of values(finalGraph)) {
+    Object.freeze(node);
+  }
+
+  return freeze(finalGraph);
+};
+
+/**
+ * Returns an array of "issue" objects if any resources referenced in `policy`
+ * are unknown.
+ *
+ * @param {Set<CanonicalName>} canonicalNames Set of all known canonical names
+ * @param {SomePolicy} policy Policy to validate
+ * @returns {Array<{canonicalName: CanonicalName, message: string, path:
+ * string[], suggestion?: CanonicalName}>} Array of issue objects, or `undefined` if no issues were
+ * found
+ */
+const validatePolicyResources = (canonicalNames, policy) => {
+  /**
+   * Finds a suggestion for `badName` if it is a suffix of any
+   * canonical name in `canonicalNames`.
+   *
+   * @param {string} badName Unknown canonical name
+   * @returns {CanonicalName | undefined}
+   */
+  const findSuggestion = badName => {
+    for (const canonicalName of canonicalNames) {
+      if (canonicalName.endsWith(`>${badName}`)) {
+        return canonicalName;
+      }
+    }
+    return undefined;
+  };
+
+  /** @type {Array<{canonicalName: CanonicalName, message: string, path: string[], suggestion?: CanonicalName}>} */
+  const issues = [];
+  for (const [resourceName, resourcePolicy] of entries(
+    policy.resources ?? {},
+  )) {
+    if (!canonicalNames.has(resourceName)) {
+      const issueMessage = `Resource ${q(resourceName)} was not found`;
+      const suggestion = findSuggestion(resourceName);
+      const issue = {
+        canonicalName: resourceName,
+        message: issueMessage,
+        path: ['resources', resourceName],
+      };
+      if (suggestion) {
+        issue.suggestion = suggestion;
+      }
+      issues.push(issue);
+    }
+    if (typeof resourcePolicy?.packages === 'object') {
+      for (const packageName of keys(resourcePolicy.packages)) {
+        if (!canonicalNames.has(packageName)) {
+          const issueMessage = `Resource ${q(packageName)} from resource ${q(resourceName)} was not found`;
+          const suggestion = findSuggestion(packageName);
+          const issue = {
+            canonicalName: packageName,
+            message: issueMessage,
+            path: ['resources', resourceName, 'packages', packageName],
+          };
+          if (suggestion) {
+            issue.suggestion = suggestion;
+          }
+          issues.push(issue);
+        }
+      }
+    }
+  }
+
+  return issues;
+};
 
 /**
  * @param {ReadFn | ReadPowers<FileUrlString> | MaybeReadPowers<FileUrlString>} readPowers
- * @param {FileUrlString} packageLocation
+ * @param {FileUrlString} entryPackageLocation
  * @param {Set<string>} conditionsOption
  * @param {PackageDescriptor} packageDescriptor
- * @param {string} moduleSpecifier
+ * @param {string} entryModuleSpecifier
  * @param {CompartmentMapForNodeModulesOptions} [options]
- * @returns {Promise<CompartmentMapDescriptor>}
- * @deprecated Use {@link mapNodeModules} instead.
+ * @returns {Promise<PackageCompartmentMapDescriptor>}
  */
-export const compartmentMapForNodeModules = async (
+export const compartmentMapForNodeModules_ = async (
   readPowers,
-  packageLocation,
+  entryPackageLocation,
   conditionsOption,
   packageDescriptor,
-  moduleSpecifier,
+  entryModuleSpecifier,
   options = {},
 ) => {
   const {
@@ -999,6 +1313,9 @@ export const compartmentMapForNodeModules = async (
     policy,
     strict = false,
     log = noop,
+    unknownCanonicalNameHook,
+    packageDataHook,
+    packageDependenciesHook,
   } = options;
   const { maybeRead, canonical } = unpackReadPowers(readPowers);
   const languageOptions = makeLanguageOptions(options);
@@ -1021,7 +1338,7 @@ export const compartmentMapForNodeModules = async (
   const graph = await graphPackages(
     maybeRead,
     canonical,
-    packageLocation,
+    entryPackageLocation,
     conditions,
     packageDescriptor,
     dev || (conditions && conditions.has('development')),
@@ -1029,52 +1346,76 @@ export const compartmentMapForNodeModules = async (
     languageOptions,
     strict,
     logicalPathGraph,
-    { log },
+    { log, policy, packageDependenciesHook },
   );
 
-  if (policy) {
-    assertPolicy(policy);
-
-    assert(
-      graph[ATTENUATORS_COMPARTMENT] === undefined,
-      `${q(ATTENUATORS_COMPARTMENT)} is a reserved compartment name`,
-    );
+  makeAttenuatorsNode(graph, graph[entryPackageLocation], policy);
 
-    graph[ATTENUATORS_COMPARTMENT] = {
-      ...graph[packageLocation],
-      externalAliases: {},
-      label: ATTENUATORS_COMPARTMENT,
-      name: ATTENUATORS_COMPARTMENT,
-    };
-  }
+  /**
+   * @type {CanonicalNameMap}
+   */
+  const canonicalNameMap = new Map();
 
-  const shortestPath = makeShortestPath(logicalPathGraph);
-  // neither the entry package nor the attenuators compartment have a path; omit
-  const {
-    [ATTENUATORS_COMPARTMENT]: _,
-    [packageLocation]: __,
-    ...subgraph
-  } = graph;
+  const finalGraph = finalizeGraph(
+    graph,
+    logicalPathGraph,
+    entryPackageLocation,
+    canonicalNameMap,
+  );
 
-  for (const [location, node] of entries(subgraph)) {
-    const shortestLogicalPath = shortestPath(
-      packageLocation,
-      // entries() loses some type information
-      /** @type {FileUrlString} */ (location),
-    );
+  // if policy exists, cross-reference the policy "resources" against the list
+  // of known canonical names and fire the `unknownCanonicalName` hook for each
+  // unknown resource, if found
+  if (policy) {
+    const canonicalNames = new Set(canonicalNameMap.keys());
+    const issues = validatePolicyResources(canonicalNames, policy) ?? [];
+    // Call default handler first if policy exists
+    for (const { message, canonicalName, path, suggestion } of issues) {
+      const hookInput = {
+        canonicalName,
+        message,
+        path,
+        log,
+      };
+      if (suggestion) {
+        hookInput.suggestion = suggestion;
+      }
+      defaultUnknownCanonicalNameHandler(hookInput);
+      // Then call user-provided hook if it exists
+      if (unknownCanonicalNameHook) {
+        unknownCanonicalNameHook(hookInput);
+      }
+    }
+  }
 
-    // the first element will always be the root package location; this is omitted from the path.
-    shortestLogicalPath.shift();
-    node.path = shortestLogicalPath.map(location => graph[location].name);
-    log(`Canonical name for package at ${location}: ${node.path.join('>')}`);
+  // Fire packageData hook with all package data before translateGraph
+  if (packageDataHook) {
+    const packageData =
+      /** @type {Map<PackageCompartmentDescriptorName, PackageData>} */ (
+        new Map(
+          values(finalGraph).map(node => [
+            node.label,
+            {
+              name: node.name,
+              packageDescriptor: node.packageDescriptor,
+              location: node.location,
+              canonicalName: node.label,
+            },
+          ]),
+        )
+      );
+    packageDataHook({
+      packageData,
+      log,
+    });
   }
 
   const compartmentMap = translateGraph(
-    packageLocation,
-    moduleSpecifier,
-    graph,
+    entryPackageLocation,
+    entryModuleSpecifier,
+    finalGraph,
     conditions,
-    policy,
+    { policy, log, packageDependenciesHook },
   );
 
   return compartmentMap;
@@ -1089,12 +1430,21 @@ export const compartmentMapForNodeModules = async (
  * @param {ReadFn | ReadPowers<FileUrlString> | MaybeReadPowers<FileUrlString>} readPowers
  * @param {string} moduleLocation
  * @param {MapNodeModulesOptions} [options]
- * @returns {Promise<CompartmentMapDescriptor>}
+ * @returns {Promise<PackageCompartmentMapDescriptor>}
  */
 export const mapNodeModules = async (
   readPowers,
   moduleLocation,
-  { tags = new Set(), conditions = tags, log = noop, ...otherOptions } = {},
+  {
+    tags = new Set(),
+    conditions = tags,
+    log = noop,
+    unknownCanonicalNameHook,
+    packageDataHook,
+    packageDependenciesHook,
+    policy,
+    ...otherOptions
+  } = {},
 ) => {
   const {
     packageLocation,
@@ -1110,12 +1460,24 @@ export const mapNodeModules = async (
   assertPackageDescriptor(packageDescriptor);
   assertFileUrlString(packageLocation);
 
-  return compartmentMapForNodeModules(
+  return compartmentMapForNodeModules_(
     readPowers,
     packageLocation,
     conditions,
     packageDescriptor,
     moduleSpecifier,
-    { log, ...otherOptions },
+    {
+      log,
+      policy,
+      unknownCanonicalNameHook,
+      packageDependenciesHook,
+      packageDataHook,
+      ...otherOptions,
+    },
   );
 };
+
+/**
+ * @deprecated Use {@link mapNodeModules} instead.
+ */
+export const compartmentMapForNodeModules = compartmentMapForNodeModules_;