feat(compartment-mapper): expose findUnknownCanonicalNames

Expose `findUnknownCanonicalNames()` from new export `@endo/compartment-mapper/policy.js`.

Should be used _after_ `captureFromMap` when called without policy, since unknown canonical names are not emitted by the `UnknownCanonicalNameHook` unless a policy is present.

Author: boneskull

.changeset/cozy-bushes-allow.md

@@ -0,0 +1,5 @@
+---
+'@endo/compartment-mapper': minor
+---
+
+Expose `findUnknownCanonicalNames()` from new export `@endo/compartment-mapper/policy.js`.

packages/compartment-mapper/policy.js

@@ -0,0 +1,4 @@
+// eslint-disable-next-line import/export -- just types
+export * from './src/types-external.js';
+
+export { findUnknownCanonicalNames } from './src/policy.js';

packages/compartment-mapper/src/node-modules.js

@@ -23,7 +23,11 @@ import {
   ENTRY_COMPARTMENT,
   generateCanonicalName,
 } from './policy-format.js';
-import { dependencyAllowedByPolicy, makePackagePolicy } from './policy.js';
+import {
+  dependencyAllowedByPolicy,
+  makePackagePolicy,
+  findUnknownCanonicalNames,
+} from './policy.js';
 import { unpackReadPowers } from './powers.js';
 import { search, searchDescriptor } from './search.js';
 import { GenericGraph, makeShortestPath } from './generic-graph.js';
@@ -1268,16 +1272,16 @@ const finalizeGraph = (
 };
 
 /**
- * Returns an array of "issue" objects if any resources referenced in `policy`
- * are unknown.
+ * Returns an array of issue objects for each unknown canonical name referenced
+ * in `policy`, using the precomputed `unknownSet` to drive the check.
  *
  * @param {Set<CanonicalName>} canonicalNames Set of all known canonical names
  * @param {SomePolicy} policy Policy to validate
+ * @param {Set<CanonicalName>} unknownSet Set of unknown canonical names from {@link findUnknownCanonicalNames}
  * @returns {Array<{canonicalName: CanonicalName, message: string, path:
- * string[], suggestion?: CanonicalName}>} Array of issue objects, or `undefined` if no issues were
- * found
+ * string[], suggestion?: CanonicalName}>} Array of issue objects
  */
-const validatePolicyResources = (canonicalNames, policy) => {
+const validatePolicyResources = (canonicalNames, policy, unknownSet) => {
   /**
    * Finds a suggestion for `badName` if it is a suffix of any
    * canonical name in `canonicalNames`.
@@ -1299,7 +1303,7 @@ const validatePolicyResources = (canonicalNames, policy) => {
   for (const [resourceName, resourcePolicy] of entries(
     policy.resources ?? {},
   )) {
-    if (!canonicalNames.has(resourceName)) {
+    if (unknownSet.has(resourceName)) {
       const issueMessage = `Resource ${q(resourceName)} was not found`;
       const suggestion = findSuggestion(resourceName);
       const issue = {
@@ -1314,7 +1318,7 @@ const validatePolicyResources = (canonicalNames, policy) => {
     }
     if (typeof resourcePolicy?.packages === 'object') {
       for (const packageName of keys(resourcePolicy.packages)) {
-        if (!canonicalNames.has(packageName)) {
+        if (unknownSet.has(packageName)) {
           const issueMessage = `Resource ${q(packageName)} from resource ${q(resourceName)} was not found`;
           const suggestion = findSuggestion(packageName);
           const issue = {
@@ -1471,8 +1475,19 @@ export const compartmentMapForNodeModules_ = async (
   // 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) ?? [];
+    const knownCanonicalNames = new Set(canonicalNameMap.keys());
+    const unknownCanonicalNames = findUnknownCanonicalNames(
+      knownCanonicalNames,
+      policy,
+    );
+    const issues =
+      unknownCanonicalNames.size > 0
+        ? validatePolicyResources(
+            knownCanonicalNames,
+            policy,
+            unknownCanonicalNames,
+          )
+        : [];
     // Call default handler first if policy exists
     for (const { message, canonicalName, path, suggestion } of issues) {
       const hookInput = {

packages/compartment-mapper/src/policy.js

@@ -557,3 +557,35 @@ export const attenuateModuleHook = async (
     originalModuleRecord,
   });
 };
+
+/**
+ * Returns the set of canonical names referenced in `policy` that do not exist
+ * in the provided `canonicalNames` set.
+ *
+ * @param {Set<CanonicalName>} canonicalNames Set of all known canonical names
+ * @param {SomePolicy} policy Policy to inspect
+ * @returns {Set<CanonicalName>} Set of unknown canonical names found in the policy
+ */
+
+export const findUnknownCanonicalNames = (canonicalNames, policy) => {
+  /** @type {Set<CanonicalName>} */
+  const unknown = new Set();
+  for (const [resourceName, resourcePolicy] of entries(
+    policy.resources ?? {},
+  )) {
+    if (!canonicalNames.has(resourceName)) {
+      unknown.add(resourceName);
+    }
+    if (
+      resourcePolicy?.packages &&
+      typeof resourcePolicy.packages === 'object'
+    ) {
+      for (const packageName of keys(resourcePolicy.packages)) {
+        if (!canonicalNames.has(packageName)) {
+          unknown.add(packageName);
+        }
+      }
+    }
+  }
+  return unknown;
+};

packages/compartment-mapper/test/policy.test.js

@@ -8,7 +8,7 @@ import {
   ATTENUATORS_COMPARTMENT,
   ENTRY_COMPARTMENT,
 } from '../src/policy-format.js';
-import { makePackagePolicy } from '../src/policy.js';
+import { makePackagePolicy, findUnknownCanonicalNames } from '../src/policy.js';
 
 function combineAssertions(...assertionFunctions) {
   return async (...args) => {
@@ -633,3 +633,81 @@ test('makePackagePolicy() - empty resources object returns empty package policy'
 
   t.deepEqual(result, {});
 });
+
+test('findUnknownCanonicalNames() - returns empty set when all names are known', t => {
+  const known = new Set(['alice', 'alice>carol']);
+  const testPolicy = {
+    entry: {},
+    resources: {
+      alice: {
+        packages: { 'alice>carol': true },
+      },
+    },
+  };
+
+  const result = findUnknownCanonicalNames(known, testPolicy);
+
+  t.deepEqual(result, new Set());
+});
+
+test('findUnknownCanonicalNames() - detects unknown top-level resource names', t => {
+  const known = new Set(['alice']);
+  const testPolicy = {
+    entry: {},
+    resources: {
+      alice: {},
+      ghost: {},
+    },
+  };
+
+  const result = findUnknownCanonicalNames(known, testPolicy);
+
+  t.deepEqual(result, new Set(['ghost']));
+});
+
+test('findUnknownCanonicalNames() - detects unknown names nested in packages', t => {
+  const known = new Set(['alice', 'bob']);
+  const testPolicy = {
+    entry: {},
+    resources: {
+      alice: {
+        packages: {
+          bob: true,
+          'alice>nobody': true,
+        },
+      },
+    },
+  };
+
+  const result = findUnknownCanonicalNames(known, testPolicy);
+
+  t.deepEqual(result, new Set(['alice>nobody']));
+});
+
+test('findUnknownCanonicalNames() - deduplicates names referenced multiple times', t => {
+  const known = new Set(['alice']);
+  const testPolicy = {
+    entry: {},
+    resources: {
+      alice: {
+        packages: { ghost: true },
+      },
+      ghost: {
+        packages: { ghost: true },
+      },
+    },
+  };
+
+  const result = findUnknownCanonicalNames(known, testPolicy);
+
+  t.deepEqual(result, new Set(['ghost']));
+});
+
+test('findUnknownCanonicalNames() - returns empty set for policy with no resources', t => {
+  const known = new Set(['alice']);
+  const testPolicy = { entry: {} };
+
+  const result = findUnknownCanonicalNames(known, testPolicy);
+
+  t.deepEqual(result, new Set());
+});