@endo/compartment-mapper 1.6.3 → 2.1.0

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

@@ -5,76 +5,157 @@
  *
  * @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 { PatternDescriptor } from './pattern-replacement.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>>;
+    /**
+     * Wildcard patterns for dynamic module resolution within this compartment.
+     * `*` matches any substring including `/` (Node.js semantics).
+     * Stripped during digest/archiving - expanded patterns become concrete module entries.
+     */
+    patterns?: Array<PatternDescriptor>;
+    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' | 'link-pattern' | '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 +163,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 +186,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,238 @@
 
 /* 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 { PatternDescriptor } from './pattern-replacement.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>>;
+
+  /**
+   * Wildcard patterns for dynamic module resolution within this compartment.
+   * `*` matches any substring including `/` (Node.js semantics).
+   * Stripped during digest/archiving - expanded patterns become concrete module entries.
+   */
+  patterns?: Array<PatternDescriptor>;
+
+  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'
+  | 'link-pattern'
+  | '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 +248,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 +282,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;