fix(compartment-mapper): remove unused type from ModuleSourceHookModuleSource

- Removes unused `ModuleSourceHook`'s "error" module source type.
- Adds tests for specific behavior around exit modules
- Fix a JSDoc import

Author: boneskull

.changeset/whole-schools-rescue.md

@@ -0,0 +1,5 @@
+---
+'@endo/compartment-mapper': patch
+---
+
+Remove unused "error" `ModuleSourceHookModuleSource` type.

packages/compartment-mapper/src/import-hook.js

@@ -41,7 +41,8 @@
  *   CompartmentModuleConfiguration,
  *   LogOptions,
  *   CanonicalName,
- *   LocalModuleSource
+ *   LocalModuleSource,
+ *   ModuleSourceHook,
  * } from './types.js'
  */
 
@@ -262,7 +263,7 @@ const nominateCandidates = (moduleSpecifier, searchSuffixes) => {
  *
  * Preprocesses the fields for the hook.
  *
- * @param {import('./types.js').ModuleSourceHook | undefined} moduleSourceHook Hook function
+ * @param {ModuleSourceHook | undefined} moduleSourceHook Hook function
  * @param {LocalModuleSource} moduleSource Original `LocalModuleSource` object
  * @param {CanonicalName} canonicalName Canonical name of the compartment/package
  * @param {LogOptions} options Options

packages/compartment-mapper/src/types/external.ts

@@ -98,17 +98,30 @@ export type PackageDependenciesHook = (params: {
  * The `moduleSource` property value for {@link ModuleSourceHook}
  */
 export type ModuleSourceHookModuleSource =
-  | {
-      location: FileUrlString;
-      language: Language;
-      bytes: Uint8Array;
-      imports?: string[] | undefined;
-      exports?: string[] | undefined;
-      reexports?: string[] | undefined;
-      sha512?: string | undefined;
-    }
-  | { error: string }
-  | { exit: string };
+  | ModuleSourceHookFileModuleSource
+  | ModuleSourceHookExitModuleSource;
+
+/**
+ * The `moduleSource` property value for {@link ModuleSourceHook} for a module
+ * on disk
+ */
+export type ModuleSourceHookFileModuleSource = {
+  location: FileUrlString;
+  language: Language;
+  bytes: Uint8Array;
+  imports?: string[] | undefined;
+  exports?: string[] | undefined;
+  reexports?: string[] | undefined;
+  sha512?: string | undefined;
+};
+
+/**
+ * The `moduleSource` property value for {@link ModuleSourceHook} for an exit
+ * module (virtual)
+ */
+export type ModuleSourceHookExitModuleSource = {
+  exit: string;
+};
 
 /**
  * Hook executed when processing a module source.

packages/compartment-mapper/test/fixtures-module-source-hook/README.md

@@ -0,0 +1,18 @@
+# fixtures-module-source-hook
+
+Fixtures for testing the behavior of `moduleSourceHook` when called against various project configurations.
+
+## `app-implicit` — Implicit (Transitive) Dependency
+
+Tests what happens when a package imports a dependency it does _not_ directly declare in its own `package.json`—a transitive dependency that's only reachable through an intermediary.
+
+```mermaid
+graph TD
+    app-implicit -- "declares dependency" --> dependency-a
+    dependency-a -- "declares dependency" --> dependency-b
+    app-implicit -. "imports (implicit)" .-> dependency-b
+```
+
+`app-implicit` declares `dependency-a` as a direct dependency, and `dependency-a` in turn declares `dependency-b`. However, `app-implicit`'s `index.js` imports from `dependency-b` directly—a package it does not list in its own `dependencies`. In a flat `node_modules` layout (as used by these fixtures), `dependency-b` is resolvable despite not being a direct dependency.
+
+The expectation is that `dependency-b` is loaded as an exit module from `app-implicit`.