@endo/compartment-mapper 1.5.0 → 1.6.1

package/src/node-modules.js

@@ -1,5 +1,5 @@
 /**
- * @module Provides functions for constructing a compartment map that has a
+ * Provides functions for constructing a compartment map that has a
  * compartment descriptor corresponding to every reachable package from an
  * entry module and how to create links between them.
  * The resulting compartment map does not describe individual modules but does
@@ -7,6 +7,8 @@
  * wildcard expansion.
  * See {@link link} to expand a compartment map to capture module descriptors
  * for transitive dependencies.
+ *
+ * @module
  */
 
 /* eslint no-shadow: 0 */
@@ -17,57 +19,27 @@
  *   CompartmentDescriptor,
  *   CompartmentMapDescriptor,
  *   CompartmentMapForNodeModulesOptions,
- *   Language,
  *   LanguageForExtension,
  *   MapNodeModulesOptions,
  *   MaybeReadFn,
  *   MaybeReadPowers,
- *   ModuleDescriptor,
+ *   PackageDescriptor,
+ *   ReadDescriptorFn,
  *   ReadFn,
  *   ReadPowers,
- *   ScopeDescriptor,
  *   SomePackagePolicy,
  *   SomePolicy,
  * } from './types.js'
- */
-
-/**
- * The graph is an intermediate object model that the functions of this module
- * build by exploring the `node_modules` tree dropped by tools like npm and
- * consumed by tools like Node.js.
- * This gets translated finally into a compartment map.
- *
- * @typedef {Record<string, Node>} Graph
- */
-
-/**
- * @typedef {object} Node
- * @property {string} label
- * @property {string} name
- * @property {Array<string>} path
- * @property {Array<string>} logicalPath
- * @property {boolean} explicitExports
- * @property {Record<string, string>} internalAliases
- * @property {Record<string, string>} externalAliases
- * @property {Record<string, string>} dependencyLocations - from module name to
- * location in storage.
- * @property {LanguageForExtension} parsers - the parser for
- * modules based on their extension.
- * @property {Record<string, Language>} types - the parser for specific
- * modules.
- */
-
-/**
- * @typedef {object} LanguageOptions
- * @property {LanguageForExtension} commonjsLanguageForExtension
- * @property {LanguageForExtension} moduleLanguageForExtension
- * @property {LanguageForExtension} workspaceCommonjsLanguageForExtension
- * @property {LanguageForExtension} workspaceModuleLanguageForExtension
- * @property {Set<string>} languages
- */
-
-/**
- * @typedef {Record<string, {spec: string, alias: string}>} CommonDependencyDescriptors
+ * @import {
+ *   Graph,
+ *   Node,
+ *   LanguageOptions,
+ *   CommonDependencyDescriptors,
+ *   GatherDependencyOptions,
+ *   GraphPackageOptions,
+ *   GraphPackagesOptions,
+ *   PackageDetails,
+ * } from './types/node-modules.js'
  */
 
 import { pathCompare } from './compartment-map.js';
@@ -83,13 +55,18 @@ import {
 import { unpackReadPowers } from './powers.js';
 import { search, searchDescriptor } from './search.js';
 
-const { assign, create, keys, values } = Object;
+const { assign, create, keys, values, entries } = Object;
 
 const decoder = new TextDecoder();
 
 // q, as in quote, for enquoting strings in error messages.
 const q = JSON.stringify;
 
+/**
+ * Default logger that does nothing.
+ */
+const noop = () => {};
+
 /**
  * @param {string} rel - a relative URL
  * @param {string} abs - a fully qualified URL
@@ -99,12 +76,16 @@ const resolveLocation = (rel, abs) => {
   return new URL(rel, abs).toString();
 };
 
+// Exported for testing:
 /**
  * @param {string} location
  * @returns {string}
  */
-const basename = location => {
-  const { pathname } = new URL(location);
+export const basename = location => {
+  let { pathname } = new URL(location);
+  if (pathname.endsWith('/')) {
+    pathname = pathname.slice(0, -1);
+  }
   const index = pathname.lastIndexOf('/');
   if (index < 0) {
     return pathname;
@@ -145,27 +126,103 @@ const readDescriptorWithMemo = async (memo, maybeRead, packageLocation) => {
 };
 
 /**
- * @callback ReadDescriptorFn
+ * Compares `logicalPath` to the current best logical path in `preferredPackageLogicalPathMap` for `packageLocation`.
+ *
+ * If no current best path exists, it returns `logicalPath`.
+ *
+ * @template {string[]} T
+ * @template {string[]} U
+ * @param {T} logicalPath
  * @param {string} packageLocation
- * @returns {Promise<object>}
+ * @param {Map<string, U>} preferredPackageLogicalPathMap
+ * @returns {T|U}
  */
+const currentBestLogicalPath = (
+  logicalPath,
+  packageLocation,
+  preferredPackageLogicalPathMap,
+) => {
+  const theCurrentBest = preferredPackageLogicalPathMap.get(packageLocation);
+  if (theCurrentBest === undefined) {
+    return logicalPath;
+  }
+  return pathCompare(logicalPath, theCurrentBest) < 0
+    ? logicalPath
+    : theCurrentBest;
+};
+
+/**
+ * Updates the shortest paths in a subgraph of `graph` starting with `packageLocation`.
+ *
+ * This should be called upon the second (and each subsequent) visit to a graph node.
+ *
+ * @param {Graph} graph Graph
+ * @param {string} packageLocation Location of the package to start with
+ * @param {string[]} logicalPath Current path parts of the same package
+ * @param {Map<string, string[]>} [preferredPackageLogicalPathMap] Mapping of shortest known paths for each package location
+ * @returns {void}
+ */
+const updateShortestPaths = (
+  graph,
+  packageLocation,
+  logicalPath,
+  preferredPackageLogicalPathMap = new Map(),
+) => {
+  const node = graph[packageLocation];
+  if (!node) {
+    throw new ReferenceError(
+      `Cannot find package at ${packageLocation} in graph`,
+    );
+  }
+
+  const bestLogicalPath = currentBestLogicalPath(
+    logicalPath,
+    packageLocation,
+    preferredPackageLogicalPathMap,
+  );
+
+  if (bestLogicalPath === logicalPath) {
+    preferredPackageLogicalPathMap.set(packageLocation, bestLogicalPath);
+
+    for (const name of keys(node.dependencyLocations).sort()) {
+      const packageLocation = node.dependencyLocations[name];
+      if (!packageLocation) {
+        // "should never happen"
+        throw new ReferenceError(
+          `Expected graph node ${q(node.name)} to contain a dependency location for ${q(name)}`,
+        );
+      }
+      updateShortestPaths(
+        graph,
+        packageLocation,
+        [...logicalPath, name],
+        preferredPackageLogicalPathMap,
+      );
+    }
+  }
 
+  // a path length of 0 means the node represents the eventual entry compartment.
+  // we do not want to mess with that path.
+  if (node.path.length && node.path !== bestLogicalPath) {
+    node.path = bestLogicalPath;
+  }
+
+  return undefined;
+};
 /**
- * findPackage behaves as Node.js to find third-party modules by searching
+ * `findPackage` behaves as Node.js to find third-party modules by searching
  * parent to ancestor directories for a `node_modules` directory that contains
  * the name.
+ *
  * Node.js does not actually require these to be packages, but in practice,
- * these are the locations that pakcage managers drop a package so Node.js can
+ * these are the locations that package managers drop a package so Node.js can
  * find it efficiently.
  *
  * @param {ReadDescriptorFn} readDescriptor
  * @param {CanonicalFn} canonical
  * @param {string} directory
  * @param {string} name
- * @returns {Promise<{
- *   packageLocation: string,
- *   packageDescriptor: object,
- * } | undefined>}
+ * @returns {Promise<PackageDetails|undefined>}
  */
 const findPackage = async (readDescriptor, canonical, directory, name) => {
   await null;
@@ -198,6 +255,7 @@ const findPackage = async (readDescriptor, canonical, directory, name) => {
   }
 };
 
+/** @satisfies {LanguageForExtension} */
 const defaultLanguageForExtension = /** @type {const} */ ({
   mjs: 'mjs',
   cjs: 'cjs',
@@ -205,15 +263,19 @@ const defaultLanguageForExtension = /** @type {const} */ ({
   text: 'text',
   bytes: 'bytes',
 });
+
+/** @satisfies {LanguageForExtension} */
 const defaultCommonjsLanguageForExtension = /** @type {const} */ ({
   js: 'cjs',
 });
+
+/** @satisfies {LanguageForExtension} */
 const defaultModuleLanguageForExtension = /** @type {const} */ ({
   js: 'mjs',
 });
 
 /**
- * @param {object} descriptor
+ * @param {PackageDescriptor} descriptor
  * @param {string} location
  * @param {LanguageOptions} languageOptions
  * @returns {Record<string, string>}
@@ -278,7 +340,7 @@ const inferParsers = (descriptor, location, languageOptions) => {
 };
 
 /**
- * graphPackage and gatherDependency are mutually recursive functions that
+ * `graphPackage` and {@link gatherDependency} are mutually recursive functions that
  * gather the metadata for a package and its transitive dependencies.
  * The keys of the graph are the locations of the package descriptors.
  * The metadata include a label (which is informative and not necessarily
@@ -289,16 +351,12 @@ const inferParsers = (descriptor, location, languageOptions) => {
  * @param {ReadDescriptorFn} readDescriptor
  * @param {CanonicalFn} canonical
  * @param {Graph} graph
- * @param {object} packageDetails
- * @param {string} packageDetails.packageLocation
- * @param {object} packageDetails.packageDescriptor
+ * @param {PackageDetails} packageDetails
  * @param {Set<string>} conditions
  * @param {boolean | undefined} dev
- * @param {CommonDependencyDescriptors} commonDependencyDescriptors
  * @param {LanguageOptions} languageOptions
  * @param {boolean} strict
- * @param {Map<string, Array<string>>} preferredPackageLogicalPathMap
- * @param {Array<string>} logicalPath
+ * @param {GraphPackageOptions} options
  * @returns {Promise<undefined>}
  */
 const graphPackage = async (
@@ -309,34 +367,56 @@ const graphPackage = async (
   { packageLocation, packageDescriptor },
   conditions,
   dev,
-  commonDependencyDescriptors,
   languageOptions,
   strict,
-  preferredPackageLogicalPathMap = new Map(),
-  logicalPath = [],
+  {
+    commonDependencyDescriptors = {},
+    preferredPackageLogicalPathMap = new Map(),
+    logicalPath = [],
+    log = noop,
+  } = {},
 ) => {
   if (graph[packageLocation] !== undefined) {
+    updateShortestPaths(
+      graph,
+      packageLocation,
+      logicalPath,
+      preferredPackageLogicalPathMap,
+    );
+
     // Returning the promise here would create a causal cycle and stall recursion.
     return undefined;
   }
 
   if (packageDescriptor.name !== name) {
-    console.warn(
-      `Package named ${q(
-        name,
-      )} does not match location ${packageLocation} got (${q(
-        packageDescriptor.name,
-      )})`,
-    );
+    log('Package name does not match location', {
+      name,
+      packageDescriptorName: packageDescriptor.name,
+      packageLocation,
+    });
   }
 
-  const result = {};
-  graph[packageLocation] = /** @type {Node} */ (result);
+  const result = /** @type {Node} */ ({});
+  graph[packageLocation] = result;
 
-  /** @type {Record<string, string>} */
+  /** @type {Node['dependencyLocations']} */
   const dependencyLocations = {};
+  /** @type {ReturnType<typeof gatherDependency>[]} */
   const children = [];
+
+  /**
+   * A set containing dependency names which are considered "optional"
+   */
   const optionals = new Set();
+
+  /**
+   * Contains the names of _all_ dependencies
+   *
+   * @type {Set<string>}
+   */
+  const allDependencies = new Set();
+
+  // these are fields from package.json containing dependencies
   const {
     dependencies = {},
     peerDependencies = {},
@@ -345,32 +425,40 @@ const graphPackage = async (
     optionalDependencies = {},
     devDependencies = {},
   } = packageDescriptor;
-  const allDependencies = {};
-  for (const [name, descriptor] of Object.entries(
-    commonDependencyDescriptors,
-  )) {
+
+  for (const [name, descriptor] of entries(commonDependencyDescriptors)) {
     if (Object(descriptor) === descriptor) {
-      const { spec } = descriptor;
-      allDependencies[name] = spec;
+      allDependencies.add(name);
     }
   }
-  assign(allDependencies, dependencies);
-  assign(allDependencies, peerDependencies);
-  for (const [name, meta] of Object.entries(peerDependenciesMeta)) {
+
+  // only consider devDependencies if dev flag is true
+  for (const name of keys({
+    ...dependencies,
+    ...peerDependencies,
+    ...bundleDependencies,
+    ...optionalDependencies,
+    ...(dev ? devDependencies : {}),
+  })) {
+    allDependencies.add(name);
+  }
+
+  // for historical reasons, some packages omit peerDependencies and only
+  // use the peerDependenciesMeta field (because there was no way to define
+  // an "optional" peerDependency prior to npm v7). this is plainly wrong,
+  // but not exactly rare, either
+  for (const [name, meta] of entries(peerDependenciesMeta)) {
     if (Object(meta) === meta && meta.optional) {
       optionals.add(name);
+      allDependencies.add(name);
     }
   }
-  assign(allDependencies, bundleDependencies);
-  assign(allDependencies, optionalDependencies);
-  for (const name of Object.keys(optionalDependencies)) {
+
+  for (const name of keys(optionalDependencies)) {
     optionals.add(name);
   }
-  if (dev) {
-    assign(allDependencies, devDependencies);
-  }
 
-  for (const name of keys(allDependencies).sort()) {
+  for (const name of [...allDependencies].sort()) {
     const optional = optionals.has(name);
     const childLogicalPath = [...logicalPath, name];
     children.push(
@@ -387,17 +475,24 @@ const graphPackage = async (
         preferredPackageLogicalPathMap,
         languageOptions,
         strict,
-        childLogicalPath,
-        optional,
-        commonDependencyDescriptors,
+        {
+          childLogicalPath,
+          optional,
+          commonDependencyDescriptors,
+          log,
+        },
       ),
     );
   }
 
   const { version = '', exports: exportsDescriptor } = packageDescriptor;
-  /** @type {Record<string, Language>} */
+  /** @type {Node['types']} */
   const types = {};
 
+  /**
+   * @param {string} path
+   * @returns {Promise<PackageDescriptor>}
+   */
   const readDescriptorUpwards = async path => {
     const location = resolveLocation(path, packageLocation);
     // readDescriptor coming from above is memoized, so this is not awfully slow
@@ -405,9 +500,9 @@ const graphPackage = async (
     return data;
   };
 
-  /** @type {Record<string, string>} */
+  /** @type {Node['externalAliases']} */
   const externalAliases = {};
-  /** @type {Record<string, string>} */
+  /** @type {Node['internalAliases']} */
   const internalAliases = {};
 
   inferExportsAndAliases(
@@ -424,10 +519,13 @@ const graphPackage = async (
     languageOptions,
   );
 
-  Object.assign(result, {
+  const sourceDirname = basename(packageLocation);
+
+  assign(result, {
     name,
     path: logicalPath,
     label: `${name}${version ? `-v${version}` : ''}`,
+    sourceDirname,
     explicitExports: exportsDescriptor !== undefined,
     externalAliases,
     internalAliases,
@@ -448,7 +546,7 @@ const graphPackage = async (
   await Promise.all(children);
 
   // handle commonDependencyDescriptors package aliases
-  for (const [name, { alias }] of Object.entries(commonDependencyDescriptors)) {
+  for (const [name, { alias }] of entries(commonDependencyDescriptors)) {
     // update the dependencyLocations to point to the common dependency
     const targetLocation = dependencyLocations[name];
     if (targetLocation === undefined) {
@@ -479,6 +577,8 @@ const graphPackage = async (
 };
 
 /**
+ * Adds information for the dependency of the package at `packageLocation` to the `graph` object.
+ *
  * @param {ReadDescriptorFn} readDescriptor
  * @param {CanonicalFn} canonical
  * @param {Graph} graph - the partially build graph.
@@ -488,10 +588,9 @@ const graphPackage = async (
  * @param {Set<string>} conditions
  * @param {Map<string, Array<string>>} preferredPackageLogicalPathMap
  * @param {LanguageOptions} languageOptions
- * @param {boolean} strict
- * @param {Array<string>} [childLogicalPath]
- * @param {boolean} [optional] - whether the dependency is optional
- * @param {object} [commonDependencyDescriptors] - dependencies to be added to all packages
+ * @param {boolean} strict - If `true`, a missing dependency will throw an exception
+ * @param {GatherDependencyOptions} options
+ * @returns {Promise<void>}
  */
 const gatherDependency = async (
   readDescriptor,
@@ -504,9 +603,12 @@ const gatherDependency = async (
   preferredPackageLogicalPathMap,
   languageOptions,
   strict,
-  childLogicalPath = [],
-  optional = false,
-  commonDependencyDescriptors = undefined,
+  {
+    childLogicalPath = [],
+    optional = false,
+    commonDependencyDescriptors = {},
+    log = noop,
+  } = {},
 ) => {
   const dependency = await findPackage(
     readDescriptor,
@@ -522,15 +624,20 @@ const gatherDependency = async (
     throw Error(`Cannot find dependency ${name} for ${packageLocation}`);
   }
   dependencyLocations[name] = dependency.packageLocation;
-  const theCurrentBest = preferredPackageLogicalPathMap.get(
+
+  const bestLogicalPath = currentBestLogicalPath(
+    childLogicalPath,
     dependency.packageLocation,
+    preferredPackageLogicalPathMap,
   );
-  if (pathCompare(childLogicalPath, theCurrentBest) < 0) {
+
+  if (bestLogicalPath === childLogicalPath) {
     preferredPackageLogicalPathMap.set(
       dependency.packageLocation,
-      childLogicalPath,
+      bestLogicalPath,
     );
   }
+
   await graphPackage(
     name,
     readDescriptor,
@@ -539,34 +646,35 @@ const gatherDependency = async (
     dependency,
     conditions,
     false,
-    commonDependencyDescriptors,
     languageOptions,
     strict,
-    preferredPackageLogicalPathMap,
-    childLogicalPath,
+    {
+      commonDependencyDescriptors,
+      preferredPackageLogicalPathMap,
+      logicalPath: childLogicalPath,
+      log,
+    },
   );
 };
 
 /**
- * graphPackages returns a graph whose keys are nominally URLs, one per
- * package, with values that are label: (an informative Compartment name, built
- * as ${name}@${version}), dependencies: (a list of URLs), and exports: (an
- * object whose keys are the thing being imported, and the values are the names
- * of the matching module, relative to the containing package's root, that is,
- * the URL that was used as the key of graph).
- * The URLs in dependencies will all exist as other keys of graph.
+ * Resolves with a {@link Graph} representing the packages for which
+ * {@link CompartmentDescriptor CompartmentDescriptors} will be created.
  *
  * @param {MaybeReadFn} maybeRead
  * @param {CanonicalFn} canonical
  * @param {string} packageLocation - location of the main package.
  * @param {Set<string>} conditions
- * @param {object} mainPackageDescriptor - the parsed contents of the main
- * package.json, which was already read when searching for the package.json.
- * @param {boolean|undefined} dev - whether to use devDependencies from this package (and
- * only this package).
- * @param {Record<string,string>} commonDependencies - dependencies to be added to all packages
+ * @param {PackageDescriptor} mainPackageDescriptor - the parsed contents of the
+ * main `package.json`, which was already read when searching for the
+ * `package.json`.
+ * @param {boolean|undefined} dev - whether to use devDependencies from this
+ * package (and only this package).
+ * @param {Record<string,string>} commonDependencies - dependencies to be added
+ * to all packages
  * @param {LanguageOptions} languageOptions
  * @param {boolean} strict
+ * @param {GraphPackagesOptions} options
  */
 const graphPackages = async (
   maybeRead,
@@ -578,11 +686,12 @@ const graphPackages = async (
   commonDependencies,
   languageOptions,
   strict,
+  { log = noop } = {},
 ) => {
   const memo = create(null);
   /**
    * @param {string} packageLocation
-   * @returns {Promise<object>}
+   * @returns {Promise<PackageDescriptor>}
    */
   const readDescriptor = packageLocation =>
     readDescriptorWithMemo(memo, maybeRead, packageLocation);
@@ -608,7 +717,7 @@ const graphPackages = async (
   /** @type {CommonDependencyDescriptors} */
   const commonDependencyDescriptors = {};
   const packageDescriptorDependencies = packageDescriptor.dependencies || {};
-  for (const [alias, dependencyName] of Object.entries(commonDependencies)) {
+  for (const [alias, dependencyName] of entries(commonDependencies)) {
     const spec = packageDescriptorDependencies[dependencyName];
     if (spec === undefined) {
       throw Error(
@@ -633,16 +742,19 @@ const graphPackages = async (
     },
     conditions,
     dev,
-    commonDependencyDescriptors,
     languageOptions,
     strict,
+    {
+      commonDependencyDescriptors,
+      log,
+    },
   );
   return graph;
 };
 
 /**
- * translateGraph converts the graph returned by graph packages (above) into a
- * compartment map.
+ * `translateGraph` converts the graph returned by graph packages (above) into a
+ * {@link CompartmentMapDescriptor compartment map}.
  *
  * @param {string} entryPackageLocation
  * @param {string} entryModuleSpecifier
@@ -659,8 +771,8 @@ const translateGraph = (
   conditions,
   policy,
 ) => {
-  /** @type {Record<string, CompartmentDescriptor>} */
-  const compartments = Object.create(null);
+  /** @type {CompartmentMapDescriptor['compartments']} */
+  const compartments = create(null);
 
   // For each package, build a map of all the external modules the package can
   // import from other packages.
@@ -676,15 +788,16 @@ const translateGraph = (
       name,
       path,
       label,
+      sourceDirname,
       dependencyLocations,
       internalAliases,
       parsers,
       types,
     } = graph[dependeeLocation];
-    /** @type {Record<string, ModuleDescriptor>} */
-    const moduleDescriptors = Object.create(null);
-    /** @type {Record<string, ScopeDescriptor>} */
-    const scopes = Object.create(null);
+    /** @type {CompartmentDescriptor['modules']} */
+    const moduleDescriptors = create(null);
+    /** @type {CompartmentDescriptor['scopes']} */
+    const scopes = create(null);
 
     /**
      * List of all the compartments (by name) that this compartment can import from.
@@ -770,6 +883,7 @@ const translateGraph = (
       name,
       path,
       location: dependeeLocation,
+      sourceDirname,
       modules: moduleDescriptors,
       scopes,
       parsers,
@@ -843,10 +957,10 @@ const makeLanguageOptions = ({
   };
 
   const languages = new Set([
-    ...Object.values(moduleLanguageForExtension),
-    ...Object.values(commonjsLanguageForExtension),
-    ...Object.values(workspaceModuleLanguageForExtension),
-    ...Object.values(workspaceCommonjsLanguageForExtension),
+    ...values(moduleLanguageForExtension),
+    ...values(commonjsLanguageForExtension),
+    ...values(workspaceModuleLanguageForExtension),
+    ...values(workspaceCommonjsLanguageForExtension),
     ...additionalLanguages,
   ]);
 
@@ -863,10 +977,11 @@ const makeLanguageOptions = ({
  * @param {ReadFn | ReadPowers | MaybeReadPowers} readPowers
  * @param {string} packageLocation
  * @param {Set<string>} conditionsOption
- * @param {object} packageDescriptor
+ * @param {PackageDescriptor} packageDescriptor
  * @param {string} moduleSpecifier
  * @param {CompartmentMapForNodeModulesOptions} [options]
  * @returns {Promise<CompartmentMapDescriptor>}
+ * @deprecated Use {@link mapNodeModules} instead.
  */
 export const compartmentMapForNodeModules = async (
   readPowers,
@@ -881,6 +996,7 @@ export const compartmentMapForNodeModules = async (
     commonDependencies = {},
     policy,
     strict = false,
+    log = noop,
   } = options;
   const { maybeRead, canonical } = unpackReadPowers(readPowers);
   const languageOptions = makeLanguageOptions(options);
@@ -902,6 +1018,7 @@ export const compartmentMapForNodeModules = async (
     commonDependencies,
     languageOptions,
     strict,
+    { log },
   );
 
   if (policy) {
@@ -932,6 +1049,11 @@ export const compartmentMapForNodeModules = async (
 };
 
 /**
+ * Creates a {@link CompartmentMapDescriptor} from the module at
+ * `moduleLocation`, considering dependencies found in `node_modules`.
+ *
+ * Locates the {@link PackageDescriptor} for the module at `moduleLocation`
+ *
  * @param {ReadFn | ReadPowers | MaybeReadPowers} readPowers
  * @param {string} moduleLocation
  * @param {MapNodeModulesOptions} [options]
@@ -940,20 +1062,17 @@ export const compartmentMapForNodeModules = async (
 export const mapNodeModules = async (
   readPowers,
   moduleLocation,
-  options = {},
+  { tags = new Set(), conditions = tags, log = noop, ...otherOptions } = {},
 ) => {
-  const { tags = new Set(), conditions = tags, ...otherOptions } = options;
-
   const {
     packageLocation,
     packageDescriptorText,
     packageDescriptorLocation,
     moduleSpecifier,
-  } = await search(readPowers, moduleLocation);
+  } = await search(readPowers, moduleLocation, { log });
 
-  const packageDescriptor = parseLocatedJson(
-    packageDescriptorText,
-    packageDescriptorLocation,
+  const packageDescriptor = /** @type {PackageDescriptor} */ (
+    parseLocatedJson(packageDescriptorText, packageDescriptorLocation)
   );
 
   return compartmentMapForNodeModules(
@@ -962,6 +1081,6 @@ export const mapNodeModules = async (
     conditions,
     packageDescriptor,
     moduleSpecifier,
-    otherOptions,
+    { log, ...otherOptions },
   );
 };