@endo/compartment-mapper 1.6.3 → 2.0.0

package/src/types/canonical-name.ts

@@ -0,0 +1,151 @@
+/**
+ * Fairly exhaustive, excruciatingly pedantic _type-level_ helpers for
+ * representing and validating **Canonical Names** and npm package names.
+ *
+ * A {@link CanonicalName | Canonical Name} is a string containing one or more
+ * npm package names (scoped or unscoped) delimited by a `>` character.
+ *
+ * The following rules about npm package names are enforced:
+ *
+ * - ✅ Length > 0
+ * - ✅ Can contain hyphens
+ * - ✅ No leading `.` or `_`
+ * - ✅ No spaces
+ * - ✅ No `~)('!*` characters
+ *
+ * The following rules are not enforced:
+ *
+ * - ❌ All lowercase - Not feasible due to recursion limits & legacy package
+ *   names
+ * - ❌ Not a reserved name - unmaintainable list of node builtin module names
+ * - ❌ Length ≤ 214 - Not feasible due to recursion limits & legacy package
+ *   names
+ *
+ * "Legacy" package names may contain uppercase letters and be longer than 214
+ * characters.
+ *
+ * @module
+ * @see {@link https://www.npmjs.com/package/validate-npm-package-name}
+ */
+
+/**
+ * Characters that are explicitly forbidden in npm package names. These include:
+ * ` `, `~`, `)`, `(`, `'`, `!`, `*`
+ *
+ * We check each one individually because TypeScript's template literal types
+ * can detect if a string contains a specific substring.
+ *
+ * Returns `true` if the string contains a forbidden character, `false`
+ * otherwise.
+ */
+type ContainsForbiddenChar<S extends string> = S extends
+  | `${string} ${string}`
+  | `${string}~${string}`
+  | `${string})${string}`
+  | `${string}(${string}`
+  | `${string}'${string}`
+  | `${string}!${string}`
+  | `${string}*${string}`
+  ? true
+  : false;
+
+/**
+ * Validates that a string doesn't start with `.` or `_`.
+ *
+ * Returns `true` if the string doesn't start with `.` or `_`, `false`
+ * otherwise.
+ */
+type HasValidStart<S extends string> = S extends `.${string}` | `_${string}`
+  ? false
+  : true;
+
+/**
+ * Validates that a string is non-empty.
+ *
+ * Returns `true` if the string is non-empty, `false` otherwise.
+ */
+type IsNonEmpty<S extends string> = S extends '' ? false : true;
+
+/**
+ * Combines all validation checks for a package name segment.
+ *
+ * Returns `true` if the string passes all checks, `false` otherwise.
+ */
+type IsValidPackageNameSegment<S extends string> =
+  IsNonEmpty<S> extends false
+    ? false
+    : HasValidStart<S> extends false
+      ? false
+      : ContainsForbiddenChar<S> extends true
+        ? false
+        : true;
+
+// ============================================================================
+// Scoped and Unscoped Package Names
+// ============================================================================
+
+/** A scoped npm package name, like "@scope/pkg" */
+export type ScopedPackageName<S extends string = string> =
+  S extends `@${infer Scope}/${infer Name}`
+    ? IsValidPackageNameSegment<Scope> extends true
+      ? IsValidPackageNameSegment<Name> extends true
+        ? S
+        : never
+      : never
+    : never;
+
+/**
+ * An unscoped npm package name.
+ *
+ * Must pass all validation checks and must not contain a `/` (which would
+ * indicate a scoped package or a subpath).
+ *
+ * Note: Package names containing uppercase letters are technically invalid per
+ * npm rules, but they exist in the wild. TypeScript cannot reliably validate
+ * case at the type level, so we don't enforce this.
+ */
+export type UnscopedPackageName<S extends string = string> =
+  S extends `${string}/${string}`
+    ? never
+    : IsValidPackageNameSegment<S> extends true
+      ? S
+      : never;
+
+/**
+ * A scoped or unscoped npm package name.
+ */
+export type NpmPackageName<S extends string = string> =
+  S extends `@${string}/${string}`
+    ? ScopedPackageName<S>
+    : UnscopedPackageName<S>;
+
+/**
+ * Split a string on `>`—the canonical name delimiter—into a tuple of segments.
+ */
+export type SplitOnDelimiter<S extends string> =
+  S extends `${infer Head}>${infer Tail}`
+    ? [Head, ...SplitOnDelimiter<Tail>]
+    : [S];
+
+/**
+ * Validate that every element in a tuple of strings is a valid npm package
+ * name.
+ */
+export type AllValidPackageNames<Parts extends readonly string[]> =
+  Parts extends [
+    infer Head extends string,
+    ...infer Tail extends readonly string[],
+  ]
+    ? NpmPackageName<Head> extends never
+      ? never
+      : AllValidPackageNames<Tail>
+    : Parts;
+
+/**
+ * A Canonical Name string comprised of one or more npm package names separated
+ * by `>` (e.g., `foo`, `@scope/foo>bar`, `foo>@scope/bar>baz`).
+ *
+ * When given a string literal type, invalid shapes narrow to `never`.
+ */
+export type CanonicalName<S extends string = string> =
+  AllValidPackageNames<SplitOnDelimiter<S>> extends never ? never : S;

package/src/types/compartment-map-schema.d.ts

@@ -5,76 +5,150 @@
  *
  * @module
  */
+import type { ATTENUATORS_COMPARTMENT, ENTRY_COMPARTMENT } from '../policy-format.js';
+import type { CanonicalName } from './canonical-name.js';
+import type { FileUrlString } from './external.js';
 import type { SomePackagePolicy } from './policy-schema.js';
 import type { LiteralUnion } from './typescript.js';
+/**
+ * The type of a {@link CompartmentMapDescriptor.compartments} property.
+ */
+export type CompartmentDescriptors<T extends CompartmentDescriptor = CompartmentDescriptor, K extends string = string> = Record<K, T>;
 /**
  * A compartment map describes how to construct an application as a graph of
  * Compartments, each corresponding to Node.js style packaged modules.
  */
-export type CompartmentMapDescriptor = {
+export type CompartmentMapDescriptor<T extends CompartmentDescriptor = CompartmentDescriptor, Name extends string = string, EntryName extends string = Name> = {
     tags: Array<string>;
-    entry: EntryDescriptor;
-    compartments: Record<string, CompartmentDescriptor>;
+    entry: EntryDescriptor<EntryName>;
+    compartments: CompartmentDescriptors<T, Name>;
 };
+/**
+ * The type of a {@link PackageCompartmentMapDescriptor.compartments} property.
+ */
+export type PackageCompartmentDescriptors = CompartmentDescriptors<PackageCompartmentDescriptor, PackageCompartmentDescriptorName>;
+/**
+ * The {@link CompartmentDescriptor} type in the
+ * {@link PackageCompartmentMapDescriptor} returned by `mapNodeModules()`
+ */
+export type PackageCompartmentMapDescriptor = CompartmentMapDescriptor<PackageCompartmentDescriptor, PackageCompartmentDescriptorName, FileUrlString>;
+export interface FileCompartmentDescriptor extends CompartmentDescriptor<FileModuleConfiguration | CompartmentModuleConfiguration> {
+    location: FileUrlString;
+}
+export type FileCompartmentDescriptors = CompartmentDescriptors<FileCompartmentDescriptor>;
+export type FileCompartmentMapDescriptor = CompartmentMapDescriptor<FileCompartmentDescriptor>;
 /**
  * The entry descriptor of a compartment map denotes the root module of an
  * application and the compartment that contains it.
  */
-export type EntryDescriptor = {
-    compartment: string;
+export type EntryDescriptor<K extends string = string> = {
+    compartment: K;
     module: string;
 };
+/**
+ * Keys of {@link PackageCompartmentMapDescriptor.compartments}
+ */
+export type PackageCompartmentDescriptorName = LiteralUnion<typeof ATTENUATORS_COMPARTMENT, FileUrlString>;
+export interface PackageCompartmentDescriptor extends CompartmentDescriptor<CompartmentModuleConfiguration> {
+    label: LiteralUnion<typeof ATTENUATORS_COMPARTMENT | typeof ENTRY_COMPARTMENT, string>;
+    version: string;
+    location: PackageCompartmentDescriptorName;
+    name: LiteralUnion<typeof ATTENUATORS_COMPARTMENT | typeof ENTRY_COMPARTMENT, string>;
+    scopes: Record<string, ScopeDescriptor<PackageCompartmentDescriptorName>>;
+    sourceDirname: string;
+}
 /**
  * A compartment descriptor corresponds to a single Compartment
  * of an assembled Application and describes how to construct
  * one for a given library or application `package.json`.
  */
-export type CompartmentDescriptor = {
-    label: string;
-    /**
-     * name of the parent directory of the package from which the compartment is derived,
-     * for purposes of generating sourceURL comments that are most likely to unite with the original sources in an IDE workspace.
-     */
-    sourceDirname?: string;
-    /** shortest path of dependency names to this compartment */
-    path?: Array<string>;
+export interface CompartmentDescriptor<T extends ModuleConfiguration = ModuleConfiguration, U extends string = string> {
+    label: CanonicalName<U>;
     /**
      * the name of the originating package suitable for constructing a sourceURL
      * prefix that will match it to files in a developer workspace.
      */
     name: string;
+    modules: Record<string, T>;
+    scopes?: Record<string, ScopeDescriptor>;
+    /** language for extension */
+    parsers?: LanguageForExtension;
+    /** language for module specifier */
+    types?: LanguageForModuleSpecifier;
+    /** policy specific to compartment */
+    policy?: SomePackagePolicy;
     location: string;
+    /**
+     * name of the parent directory of the package from which the compartment is derived,
+     * for purposes of generating sourceURL comments that are most likely to unite with the original sources in an IDE workspace.
+     */
+    sourceDirname?: string;
     /**
      * whether this compartment was retained by any module in the solution. This
      * property should never appear in an archived compartment map.
      */
-    retained?: boolean;
-    modules: Record<string, ModuleDescriptor>;
-    scopes: Record<string, ScopeDescriptor>;
-    /** language for extension */
-    parsers: LanguageForExtension;
-    /** language for module specifier */
-    types: LanguageForModuleSpecifier;
-    /** policy specific to compartment */
+    retained?: true;
+}
+export type CompartmentDescriptorWithPolicy<T extends ModuleConfiguration = ModuleConfiguration> = Omit<CompartmentDescriptor<T>, 'policy'> & {
     policy: SomePackagePolicy;
-    /** List of compartment names this Compartment depends upon */
-    compartments: Set<string>;
 };
+/**
+ * A compartment descriptor digested by `digestCompartmentMap()`
+ */
+export interface DigestedCompartmentDescriptor extends CompartmentDescriptor<ModuleConfiguration> {
+    path: never;
+    retained: never;
+    scopes: never;
+    parsers: never;
+    types: never;
+    __createdBy: never;
+    sourceDirname: never;
+}
+export type DigestedCompartmentDescriptors = CompartmentDescriptors<DigestedCompartmentDescriptor>;
+export type DigestedCompartmentMapDescriptor = CompartmentMapDescriptor<DigestedCompartmentDescriptor>;
 /**
  * For every module explicitly mentioned in an `exports` field of a
- * `package.json`, there is a corresponding module descriptor.
+ * `package.json`, there is a corresponding `ModuleConfiguration`.
  */
-export type ModuleDescriptor = {
-    compartment?: string;
-    module?: string;
+export type ModuleConfiguration = ErrorModuleConfiguration | ExitModuleConfiguration | FileModuleConfiguration | CompartmentModuleConfiguration;
+export type ModuleConfigurationCreator = 'link' | 'transform' | 'import-hook' | 'digest' | 'node-modules';
+export interface BaseModuleConfiguration {
+    deferredError?: string;
+    retained?: true;
+    __createdBy?: ModuleConfigurationCreator;
+}
+export interface ErrorModuleConfiguration extends BaseModuleConfiguration {
+    deferredError: string;
+}
+/**
+ * This module configuration is a reference to another module in a a compartment descriptor (it may be the same compartment descriptor)
+ */
+export interface CompartmentModuleConfiguration extends BaseModuleConfiguration {
+    /**
+     * The name of the compartment that contains this module.
+     */
+    compartment: LiteralUnion<typeof ATTENUATORS_COMPARTMENT, FileUrlString>;
+    /**
+     * The module name within {@link CompartmentDescriptor.modules} of the
+     * `CompartmentDescriptor` referred to by {@link compartment}
+     */
+    module: string;
+}
+/**
+ * A module configuration representing an exit module
+ */
+export interface ExitModuleConfiguration extends BaseModuleConfiguration {
+    exit: string;
+}
+/**
+ * A module configuration representing a file on disk
+ */
+export interface FileModuleConfiguration extends BaseModuleConfiguration {
     location?: string;
-    parser?: Language;
+    parser: Language;
     /** in base 16, hex */
     sha512?: string;
-    exit?: string;
-    deferredError?: string;
-    retained?: boolean;
-};
+}
 /**
  * Scope descriptors link all names under a prefix to modules in another
  * compartment, like a wildcard.
@@ -82,8 +156,11 @@ export type ModuleDescriptor = {
  * in a `package.json` file, when that `package.json` file does not have
  * an explicit `exports` map.
  */
-export type ScopeDescriptor = {
-    compartment: string;
+export type ScopeDescriptor<T extends string = string> = {
+    /**
+     * A compartment name; not a `Compartment`.
+     */
+    compartment: T;
     module?: string;
 };
 /**
@@ -102,4 +179,6 @@ export type LanguageForExtension = Record<string, Language>;
  * Mapping of module specifier to {@link Language Languages}.
  */
 export type LanguageForModuleSpecifier = Record<string, Language>;
+export type ModuleConfigurationKind = 'file' | 'compartment' | 'exit' | 'error';
+export type ModuleConfigurationKindToType<T extends ModuleConfigurationKind> = T extends 'file' ? FileModuleConfiguration : T extends 'compartment' ? CompartmentModuleConfiguration : T extends 'exit' ? ExitModuleConfiguration : T extends 'error' ? ErrorModuleConfiguration : never;
 //# sourceMappingURL=compartment-map-schema.d.ts.map

package/src/types/compartment-map-schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compartment-map-schema.d.ts","sourceRoot":"","sources":["compartment-map-schema.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAEpD;;;GAGG;AACH,MAAM,MAAM,wBAAwB,GAAG;IACrC,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACpB,KAAK,EAAE,eAAe,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC,CAAC;CACrD,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC,KAAK,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,4DAA4D;IAC5D,IAAI,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACrB;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IAC1C,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IACxC,6BAA6B;IAC7B,OAAO,EAAE,oBAAoB,CAAC;IAC9B,oCAAoC;IACpC,KAAK,EAAE,0BAA0B,CAAC;IAClC,qCAAqC;IACrC,MAAM,EAAE,iBAAiB,CAAC;IAC1B,8DAA8D;IAC9D,YAAY,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CAC3B,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,QAAQ,CAAC;IAClB,sBAAsB;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,YAAY,CAAC,eAAe,EAAE,MAAM,CAAC,CAAC;AAE7D;;GAEG;AACH,MAAM,MAAM,eAAe,GACvB,KAAK,GACL,KAAK,GACL,MAAM,GACN,OAAO,GACP,MAAM,GACN,cAAc,GACd,cAAc,CAAC;AAEnB;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;AAE5D;;GAEG;AACH,MAAM,MAAM,0BAA0B,GAAG,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC"}
+{"version":3,"file":"compartment-map-schema.d.ts","sourceRoot":"","sources":["compartment-map-schema.ts"],"names":[],"mappings":"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"}

package/src/types/compartment-map-schema.ts

@@ -8,80 +8,229 @@
 
 /* eslint-disable no-use-before-define */
 
+import type {
+  ATTENUATORS_COMPARTMENT,
+  ENTRY_COMPARTMENT,
+} from '../policy-format.js';
+import type { CanonicalName } from './canonical-name.js';
+import type { FileUrlString } from './external.js';
 import type { SomePackagePolicy } from './policy-schema.js';
 import type { LiteralUnion } from './typescript.js';
 
+/**
+ * The type of a {@link CompartmentMapDescriptor.compartments} property.
+ */
+export type CompartmentDescriptors<
+  T extends CompartmentDescriptor = CompartmentDescriptor,
+  K extends string = string,
+> = Record<K, T>;
+
 /**
  * A compartment map describes how to construct an application as a graph of
  * Compartments, each corresponding to Node.js style packaged modules.
  */
-export type CompartmentMapDescriptor = {
+export type CompartmentMapDescriptor<
+  T extends CompartmentDescriptor = CompartmentDescriptor,
+  Name extends string = string,
+  EntryName extends string = Name,
+> = {
   tags: Array<string>;
-  entry: EntryDescriptor;
-  compartments: Record<string, CompartmentDescriptor>;
+  entry: EntryDescriptor<EntryName>;
+  compartments: CompartmentDescriptors<T, Name>;
 };
 
+/**
+ * The type of a {@link PackageCompartmentMapDescriptor.compartments} property.
+ */
+export type PackageCompartmentDescriptors = CompartmentDescriptors<
+  PackageCompartmentDescriptor,
+  PackageCompartmentDescriptorName
+>;
+
+/**
+ * The {@link CompartmentDescriptor} type in the
+ * {@link PackageCompartmentMapDescriptor} returned by `mapNodeModules()`
+ */
+export type PackageCompartmentMapDescriptor = CompartmentMapDescriptor<
+  PackageCompartmentDescriptor,
+  PackageCompartmentDescriptorName,
+  FileUrlString
+>;
+
+export interface FileCompartmentDescriptor
+  extends CompartmentDescriptor<
+    FileModuleConfiguration | CompartmentModuleConfiguration
+  > {
+  location: FileUrlString;
+}
+
+export type FileCompartmentDescriptors =
+  CompartmentDescriptors<FileCompartmentDescriptor>;
+
+export type FileCompartmentMapDescriptor =
+  CompartmentMapDescriptor<FileCompartmentDescriptor>;
+
 /**
  * The entry descriptor of a compartment map denotes the root module of an
  * application and the compartment that contains it.
  */
-export type EntryDescriptor = {
-  compartment: string;
+export type EntryDescriptor<K extends string = string> = {
+  compartment: K;
   module: string;
 };
 
+/**
+ * Keys of {@link PackageCompartmentMapDescriptor.compartments}
+ */
+export type PackageCompartmentDescriptorName = LiteralUnion<
+  typeof ATTENUATORS_COMPARTMENT,
+  FileUrlString
+>;
+
+export interface PackageCompartmentDescriptor
+  extends CompartmentDescriptor<CompartmentModuleConfiguration> {
+  label: LiteralUnion<
+    typeof ATTENUATORS_COMPARTMENT | typeof ENTRY_COMPARTMENT,
+    string
+  >;
+
+  version: string;
+
+  location: PackageCompartmentDescriptorName;
+
+  name: LiteralUnion<
+    typeof ATTENUATORS_COMPARTMENT | typeof ENTRY_COMPARTMENT,
+    string
+  >;
+
+  scopes: Record<string, ScopeDescriptor<PackageCompartmentDescriptorName>>;
+
+  sourceDirname: string;
+}
+
 /**
  * A compartment descriptor corresponds to a single Compartment
  * of an assembled Application and describes how to construct
  * one for a given library or application `package.json`.
  */
-export type CompartmentDescriptor = {
-  label: string;
-  /**
-   * name of the parent directory of the package from which the compartment is derived,
-   * for purposes of generating sourceURL comments that are most likely to unite with the original sources in an IDE workspace.
-   */
-  sourceDirname?: string;
-  /** shortest path of dependency names to this compartment */
-  path?: Array<string>;
+export interface CompartmentDescriptor<
+  T extends ModuleConfiguration = ModuleConfiguration,
+  U extends string = string,
+> {
+  label: CanonicalName<U>;
   /**
    * the name of the originating package suitable for constructing a sourceURL
    * prefix that will match it to files in a developer workspace.
    */
   name: string;
+  modules: Record<string, T>;
+  scopes?: Record<string, ScopeDescriptor>;
+  /** language for extension */
+  parsers?: LanguageForExtension;
+  /** language for module specifier */
+  types?: LanguageForModuleSpecifier;
+  /** policy specific to compartment */
+  policy?: SomePackagePolicy;
+
   location: string;
+  /**
+   * name of the parent directory of the package from which the compartment is derived,
+   * for purposes of generating sourceURL comments that are most likely to unite with the original sources in an IDE workspace.
+   */
+  sourceDirname?: string;
+
   /**
    * whether this compartment was retained by any module in the solution. This
    * property should never appear in an archived compartment map.
    */
-  retained?: boolean;
-  modules: Record<string, ModuleDescriptor>;
-  scopes: Record<string, ScopeDescriptor>;
-  /** language for extension */
-  parsers: LanguageForExtension;
-  /** language for module specifier */
-  types: LanguageForModuleSpecifier;
-  /** policy specific to compartment */
-  policy: SomePackagePolicy;
-  /** List of compartment names this Compartment depends upon */
-  compartments: Set<string>;
-};
+  retained?: true;
+}
+
+export type CompartmentDescriptorWithPolicy<
+  T extends ModuleConfiguration = ModuleConfiguration,
+> = Omit<CompartmentDescriptor<T>, 'policy'> & { policy: SomePackagePolicy };
+
+/**
+ * A compartment descriptor digested by `digestCompartmentMap()`
+ */
+export interface DigestedCompartmentDescriptor
+  extends CompartmentDescriptor<ModuleConfiguration> {
+  path: never;
+  retained: never;
+  scopes: never;
+  parsers: never;
+  types: never;
+  __createdBy: never;
+  sourceDirname: never;
+}
+
+export type DigestedCompartmentDescriptors =
+  CompartmentDescriptors<DigestedCompartmentDescriptor>;
+
+export type DigestedCompartmentMapDescriptor =
+  CompartmentMapDescriptor<DigestedCompartmentDescriptor>;
 
 /**
  * For every module explicitly mentioned in an `exports` field of a
- * `package.json`, there is a corresponding module descriptor.
+ * `package.json`, there is a corresponding `ModuleConfiguration`.
  */
-export type ModuleDescriptor = {
-  compartment?: string;
-  module?: string;
+export type ModuleConfiguration =
+  | ErrorModuleConfiguration
+  | ExitModuleConfiguration
+  | FileModuleConfiguration
+  | CompartmentModuleConfiguration;
+
+export type ModuleConfigurationCreator =
+  | 'link'
+  | 'transform'
+  | 'import-hook'
+  | 'digest'
+  | 'node-modules';
+
+export interface BaseModuleConfiguration {
+  deferredError?: string;
+
+  retained?: true;
+
+  __createdBy?: ModuleConfigurationCreator;
+}
+
+export interface ErrorModuleConfiguration extends BaseModuleConfiguration {
+  deferredError: string;
+}
+
+/**
+ * This module configuration is a reference to another module in a a compartment descriptor (it may be the same compartment descriptor)
+ */
+export interface CompartmentModuleConfiguration
+  extends BaseModuleConfiguration {
+  /**
+   * The name of the compartment that contains this module.
+   */
+  compartment: LiteralUnion<typeof ATTENUATORS_COMPARTMENT, FileUrlString>;
+  /**
+   * The module name within {@link CompartmentDescriptor.modules} of the
+   * `CompartmentDescriptor` referred to by {@link compartment}
+   */
+  module: string;
+}
+
+/**
+ * A module configuration representing an exit module
+ */
+export interface ExitModuleConfiguration extends BaseModuleConfiguration {
+  exit: string;
+}
+
+/**
+ * A module configuration representing a file on disk
+ */
+export interface FileModuleConfiguration extends BaseModuleConfiguration {
   location?: string;
-  parser?: Language;
+  parser: Language;
   /** in base 16, hex */
   sha512?: string;
-  exit?: string;
-  deferredError?: string;
-  retained?: boolean;
-};
+}
 
 /**
  * Scope descriptors link all names under a prefix to modules in another
@@ -90,8 +239,11 @@ export type ModuleDescriptor = {
  * in a `package.json` file, when that `package.json` file does not have
  * an explicit `exports` map.
  */
-export type ScopeDescriptor = {
-  compartment: string;
+export type ScopeDescriptor<T extends string = string> = {
+  /**
+   * A compartment name; not a `Compartment`.
+   */
+  compartment: T;
   module?: string;
 };
 
@@ -121,3 +273,16 @@ export type LanguageForExtension = Record<string, Language>;
  * Mapping of module specifier to {@link Language Languages}.
  */
 export type LanguageForModuleSpecifier = Record<string, Language>;
+
+export type ModuleConfigurationKind = 'file' | 'compartment' | 'exit' | 'error';
+
+export type ModuleConfigurationKindToType<T extends ModuleConfigurationKind> =
+  T extends 'file'
+    ? FileModuleConfiguration
+    : T extends 'compartment'
+      ? CompartmentModuleConfiguration
+      : T extends 'exit'
+        ? ExitModuleConfiguration
+        : T extends 'error'
+          ? ErrorModuleConfiguration
+          : never;