@endo/compartment-mapper 1.4.0 → 1.6.0

package/src/types/external.ts

@@ -11,8 +11,8 @@ import type {
   Transform,
 } from 'ses';
 import type {
-  CompartmentMapDescriptor,
   CompartmentDescriptor,
+  CompartmentMapDescriptor,
   Language,
   LanguageForExtension,
 } from './compartment-map-schema.js';
@@ -29,6 +29,7 @@ export type ExecuteOptions = Partial<{
   __shimTransforms__: Array<Transform>;
   attenuations: Record<string, object>;
   Compartment: typeof Compartment;
+  __native__: boolean;
 }> &
   ModulesOption &
   ExitModuleImportHookOption;
@@ -38,6 +39,7 @@ export type ParseArchiveOptions = Partial<{
   computeSha512: HashFn;
   computeSourceLocation: ComputeSourceLocationHook;
   computeSourceMapLocation: ComputeSourceMapLocationHook;
+  __native__: boolean;
 }> &
   ModulesOption &
   CompartmentOption &
@@ -46,8 +48,23 @@ export type ParseArchiveOptions = Partial<{
 
 export type LoadArchiveOptions = ParseArchiveOptions;
 
+/**
+ * Options having an optional `log` property.
+ */
+export interface LogOptions {
+  /**
+   * A logger (for logging)
+   */
+  log?: LogFn;
+}
+
+/**
+ * Options for `mapNodeModules()`
+ */
 export type MapNodeModulesOptions = MapNodeModulesOptionsOmitPolicy &
-  PolicyOption;
+  PolicyOption &
+  LogOptions;
+
 type MapNodeModulesOptionsOmitPolicy = Partial<{
   /** @deprecated renamed `conditions` to be consistent with Node.js */
   tags: Set<string>;
@@ -67,6 +84,13 @@ type MapNodeModulesOptionsOmitPolicy = Partial<{
    * of having the `"development"` condition.
    */
   dev: boolean;
+  /**
+   * Indicates that the node_modules tree should fail to map if it does not
+   * strictly reach every expected package.
+   * By default, unreachable packages are simply omitted from the map,
+   * which defers some errors to when modules load.
+   */
+  strict: boolean;
   /** Dependencies to make reachable from any package */
   commonDependencies: Record<string, string>;
   /** Maps extensions to languages for all packages, like `txt` to `text` */
@@ -106,7 +130,8 @@ export type CompartmentMapForNodeModulesOptions = Omit<
 
 export type CaptureLiteOptions = ImportingOptions &
   LinkingOptions &
-  PolicyOption;
+  PolicyOption &
+  LogOptions;
 
 export type ArchiveLiteOptions = SyncOrAsyncArchiveOptions &
   ModuleTransformsOption &
@@ -122,25 +147,67 @@ export type SyncArchiveLiteOptions = SyncOrAsyncArchiveOptions &
 export type ArchiveOptions = Omit<MapNodeModulesOptions, 'language'> &
   ArchiveLiteOptions;
 
+export type BundleOptions = ArchiveOptions & {
+  /**
+   * Format of the bundle for purposes of importing modules from the surrounding
+   * environment.
+   * The default can be CommonJS or ESM but depends on neither `require` nor `import`
+   * for external modules, but errors early if the entrained modules need to import
+   * a host module.
+   * Specifying `cjs` makes `require` available for modules outside the bundle
+   * (exits to the import graph).
+   */
+  format?: 'cjs';
+  /**
+   * Evaluates individual module functors in-place so stack traces represent
+   * original source locations better.
+   * The resulting script cannot be used on a web page with a no-unsafe-eval
+   * Content Security Policy.
+   */
+  useEvaluate?: boolean;
+  /**
+   * A prefix for the sourceURL comment in each module format that supports
+   * sourceURL comments.
+   * Requires `useEvaluate` for effect.
+   */
+  sourceUrlPrefix?: string;
+};
+
 export type SyncArchiveOptions = Omit<MapNodeModulesOptions, 'languages'> &
   SyncArchiveLiteOptions;
 
 /**
  * Options for `loadLocation()`
  */
-export type LoadLocationOptions = ArchiveOptions & SyncArchiveOptions;
+export type LoadLocationOptions = ArchiveOptions &
+  SyncArchiveOptions &
+  LogOptions;
 
 /**
  * Options for `importLocation()` necessary (but not sufficient--see
  * `ReadNowPowers`) for dynamic require support
  */
-export type SyncImportLocationOptions = SyncArchiveOptions & ExecuteOptions;
+export type SyncImportLocationOptions = SyncArchiveOptions &
+  ExecuteOptions &
+  LogOptions;
 
-export type ImportLocationOptions = ArchiveOptions & ExecuteOptions;
+/**
+ * Options for `importLocation()` without dynamic require support
+ */
+export type ImportLocationOptions = ArchiveOptions &
+  ExecuteOptions &
+  LogOptions;
 
 // ////////////////////////////////////////////////////////////////////////////////
 // Single Options
 
+export type ComputeSha512Option = {
+  /**
+   * For computing integrity hashes for module descriptors based on captured sources.
+   */
+  computeSha512?: HashFn;
+};
+
 export type SearchSuffixesOption = {
   /**
    * Suffixes to search if the unmodified specifier is not found. Pass `[]` to
@@ -162,10 +229,18 @@ export type ModulesOption = {
 };
 
 export type ExitModuleImportHookOption = {
+  /**
+   * For obtaining module descriptors for modules that must be provided
+   * by the eventual runtime execution environment, asynchronously.
+   */
   importHook?: ExitModuleImportHook;
 };
 
 export type ExitModuleImportNowHookOption = {
+  /**
+   * For obtaining module descriptors for modules that must be provided
+   * by the eventual runtime execution environment, synchronusly.
+   */
   importNowHook?: ExitModuleImportNowHook;
 };
 
@@ -185,6 +260,34 @@ export type SyncModuleTransformsOption = {
   syncModuleTransforms?: SyncModuleTransforms;
 };
 
+export type ArchiveOnlyOption = {
+  /**
+   * Whether to prepare to create an archive or script bundle for execution
+   * elsewhere or elsewhen, as opposed to preparing to execute immediately.
+   *
+   * This has several practical effects.
+   *
+   * Archives expect to exit to potentially different host modules than the current
+   * host, but cannot instantiate those modules.
+   * For example, when preparing a bundle for execution in Node.js from within a
+   * web page, exiting to `node:fs` is appropriate but cannot be instantiated.
+   * So, the import hook will make a note of the exit and provide a stub module
+   * that throws an error if it is imported.
+   *
+   * Also, importing a module graph off a local medium immediately should
+   * inject a fully qualified source location into the module source,
+   * but sources loaded for an archive must not capture the original source
+   * location, but give the runtime an opportunity to inject a sourceURL.
+   *
+   * Also, the linker does not apply attenuations to the global environment
+   * if it is preparing to write an archive or script bundle.
+   *
+   * This option does not generally surface to users, but is set by the scenario,
+   * off for `importLocation`, on for `makeArchive` and `makeScript`.
+   */
+  archiveOnly?: boolean;
+};
+
 export type PolicyOption = {
   policy?: any;
 };
@@ -221,12 +324,52 @@ type LinkingOptions = ParserForLanguageOption &
 // ////////////////////////////////////////////////////////////////////////////////
 
 /**
- * The result of `captureFromMap`.
+ * Result of `digestCompartmentMap()`
  */
-export type CaptureResult = {
-  captureCompartmentMap: CompartmentMapDescriptor;
-  captureSources: Sources;
+export interface DigestResult {
+  /**
+   * Normalized `CompartmentMapDescriptor`
+   */
+  compartmentMap: CompartmentMapDescriptor;
+
+  /**
+   * Sources found in the `CompartmentMapDescriptor`
+   */
+  sources: Sources;
+
+  /**
+   * A record of renamed {@link CompartmentDescriptor CompartmentDescriptors}
+   * from _new_ to _original_ name
+   */
+  newToOldCompartmentNames: Record<string, string>;
+
+  /**
+   * A record of renamed {@link CompartmentDescriptor CompartmentDescriptors}
+   * from _original_ to _new_ name
+   */
+  oldToNewCompartmentNames: Record<string, string>;
+
+  /**
+   * Alias for `newToOldCompartmentNames`
+   * @deprecated Use {@link newToOldCompartmentNames} instead.
+   */
   compartmentRenames: Record<string, string>;
+}
+
+/**
+ * The result of `captureFromMap`.
+ */
+export type CaptureResult = Omit<DigestResult, 'compartmentMap' | 'sources'> & {
+  captureCompartmentMap: DigestResult['compartmentMap'];
+  captureSources: DigestResult['sources'];
+};
+
+/**
+ * The result of `makeArchiveCompartmentMap`
+ */
+export type ArchiveResult = Omit<DigestResult, 'compartmentMap' | 'sources'> & {
+  archiveCompartmentMap: DigestResult['compartmentMap'];
+  archiveSources: DigestResult['sources'];
 };
 
 /**
@@ -240,10 +383,29 @@ export type CompartmentSources = Record<string, ModuleSource>;
 export type ModuleSource = Partial<{
   /** module loading error deferred to later stage */
   deferredError: string;
-  /** package-relative location */
+  /**
+   * package-relative location.
+   * Not suitable for capture in an archive or bundle since it varies from host
+   * to host and would frustrate integrity hash checks.
+   */
   location: string;
   /** fully qualified location */
   sourceLocation: string;
+  /**
+   * directory name of the original source.
+   * This is safe to capture in a compartment map because it is _unlikely_ to
+   * vary between hosts.
+   * Package managers tend to drop a package in a consistently named location.
+   * If entry package is in a workspace, git enforces consistency.
+   * If entry package is the root of a repository, we rely on the developer
+   * to name the package consistently and suffer an inconsistent integrity hash
+   * otherwise.
+   * We do not currently capture this property in a compartment map because the
+   * schema validator currently (2024) deployed to Agoric blockchains does not
+   * tolerate compartment maps with unknown properties.
+   * https://github.com/endojs/endo/issues/2671
+   */
+  sourceDirname: string;
   bytes: Uint8Array;
   /** in lowercase base-16 (hexadecimal) */
   sha512: string;
@@ -353,7 +515,8 @@ type ParseArguments = [
     sourceMapUrl: string;
     readPowers: ReadFn | ReadPowers;
     compartmentDescriptor: CompartmentDescriptor;
-  }>,
+  }> &
+    ArchiveOnlyOption,
 ];
 
 /**
@@ -377,3 +540,8 @@ export type ParseFn = { isSyncParser?: true } & ((
  * ParserImplementations}
  */
 export type ParserForLanguage = Record<Language | string, ParserImplementation>;
+
+/**
+ * Generic logging function accepted by various functions.
+ */
+export type LogFn = (message: string, ...args: any[]) => void;

package/src/types/internal.d.ts

@@ -4,9 +4,9 @@
  */
 import type { ImportHook, ImportNowHook } from 'ses';
 import type { CompartmentDescriptor, Language, LanguageForExtension, LanguageForModuleSpecifier, ModuleDescriptor } from './compartment-map-schema.js';
-import type { HashFn, MaybeReadFn, MaybeReadNowFn, ReadFn, ReadPowers } from './powers.js';
+import type { MaybeReadFn, MaybeReadNowFn, ReadFn, ReadPowers } from './powers.js';
 import type { DeferredAttenuatorsProvider } from './policy.js';
-import type { AsyncParseFn, CompartmentSources, ExecuteOptions, ExitModuleImportNowHook, ModuleTransforms, ParseFn, ParserForLanguage, SearchSuffixesOption, SourceMapHook, SourceMapHookOption, Sources, SyncModuleTransforms } from './external.js';
+import type { ArchiveOnlyOption, AsyncParseFn, CompartmentSources, ComputeSha512Option, ExecuteOptions, ExitModuleImportHookOption, ExitModuleImportNowHookOption, LogOptions, ModuleTransforms, ParseFn, ParserForLanguage, SearchSuffixesOption, SourceMapHook, SourceMapHookOption, Sources, SyncModuleTransforms } from './external.js';
 export type LinkOptions = {
     resolve?: ResolveHook;
     makeImportHook: ImportHookMaker;
@@ -14,8 +14,8 @@ export type LinkOptions = {
     parserForLanguage?: ParserForLanguage;
     moduleTransforms?: ModuleTransforms;
     syncModuleTransforms?: SyncModuleTransforms;
-    archiveOnly?: boolean;
-} & ExecuteOptions;
+    __native__?: boolean;
+} & ArchiveOnlyOption & ExecuteOptions;
 export type LinkResult = {
     compartment: Compartment;
     compartments: Record<string, Compartment>;
@@ -24,12 +24,20 @@ export type LinkResult = {
 };
 export type ResolveHook = (importSpecifier: string, referrerSpecifier: string) => string;
 export type ShouldDeferError = (language: Language | undefined) => boolean;
-export type MakeImportNowHookMakerOptions = Partial<{
-    sources: Sources;
-    compartmentDescriptors: Record<string, CompartmentDescriptor>;
-    computeSha512: HashFn;
-    exitModuleImportNowHook: ExitModuleImportNowHook;
-}> & SearchSuffixesOption & SourceMapHookOption;
+export type MakeImportHookMakersOptions = {
+    entryCompartmentName: string;
+    entryModuleSpecifier: string;
+    /**
+     * For depositing captured sources.
+     */
+    sources?: Sources;
+    /**
+     * For depositing captured compartment descriptors.
+     */
+    compartmentDescriptors?: Record<string, CompartmentDescriptor>;
+} & ComputeSha512Option & SearchSuffixesOption & ArchiveOnlyOption & SourceMapHookOption;
+export type MakeImportHookMakerOptions = MakeImportHookMakersOptions & ExitModuleImportHookOption;
+export type MakeImportNowHookMakerOptions = MakeImportHookMakersOptions & ExitModuleImportNowHookOption;
 export type ImportHookMaker = (params: {
     packageLocation: string;
     packageName: string;
@@ -71,16 +79,18 @@ export type ChooseModuleDescriptorParams = {
     /** All compartments */
     compartments: Record<string, Compartment>;
     packageSources: CompartmentSources;
-    /** Function to compute SHA-512 hash */
-    computeSha512?: HashFn;
     readPowers: ReadPowers | ReadFn;
+    /**
+     * Whether to embed a sourceURL in applicable compiled sources.
+     * Should be false for archives and bundles, but true for runtime.
+     */
     sourceMapHook?: SourceMapHook;
     /**
      * Function returning a set of module names (scoped to the compartment) whose
      * parser is not using heuristics to determine imports.
      */
     strictlyRequiredForCompartment: (compartmentName: string) => Set<string>;
-};
+} & ComputeSha512Option & ArchiveOnlyOption;
 type SyncChooseModuleDescriptorOperators = {
     /**
      * A function that reads a file, returning its binary contents _or_
@@ -157,5 +167,68 @@ export type MakeMapParsersOptions = {
      */
     syncModuleTransforms?: SyncModuleTransforms;
 };
+/**
+ * Options for `search()`
+ */
+export type SearchOptions = LogOptions;
+/**
+ * Object fulfilled from `search()`
+ */
+export interface SearchResult {
+    packageLocation: string;
+    packageDescriptorLocation: string;
+    packageDescriptorText: string;
+    moduleSpecifier: string;
+}
+/**
+ * Object fulfilled from `searchDescriptor()`
+ *
+ * @template T The datatype; may be a {@link PackageDescriptor}, blob, string, etc.
+ */
+export interface SearchDescriptorResult<T> {
+    data: T;
+    directory: string;
+    location: string;
+    packageDescriptorLocation: string;
+}
+/**
+ * Options for `searchDescriptor()`
+ */
+export type SearchDescriptorOptions = LogOptions;
+/**
+ * A power to read a package descriptor
+ * @template T Format of package descriptor
+ */
+export type ReadDescriptorFn<T = PackageDescriptor> = (location: string) => Promise<T>;
+/**
+ * A power to _maybe_ read a package descriptor
+ * @template T Format of package descriptor
+ */
+export type MaybeReadDescriptorFn<T = PackageDescriptor> = (location: string) => Promise<T | undefined>;
+/**
+ * The type of a `package.json` file containing relevant fields; used by `graphPackages` and its ilk
+ */
+export interface PackageDescriptor {
+    /**
+     * TODO: In reality, this is optional, but `graphPackage` does not consider it to be. This will need to be fixed once support for "anonymous" packages lands; see https://github.com/endojs/endo/pull/2664
+     */
+    name: string;
+    version?: string;
+    /**
+     * TODO: Update with proper type when this field is handled.
+     */
+    exports?: unknown;
+    type?: 'module' | 'commonjs';
+    dependencies?: Record<string, string>;
+    devDependencies?: Record<string, string>;
+    peerDependencies?: Record<string, string>;
+    optionalDependencies?: Record<string, string>;
+    bundleDependencies?: string[];
+    peerDependenciesMeta?: Record<string, {
+        optional?: boolean;
+        [k: string]: unknown;
+    }>;
+    [k: string]: unknown;
+}
 export {};
 //# sourceMappingURL=internal.d.ts.map

package/src/types/internal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"internal.d.ts","sourceRoot":"","sources":["internal.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"internal.d.ts","sourceRoot":"","sources":["internal.ts"],"names":[],"mappings":"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"}

package/src/types/internal.ts

@@ -14,7 +14,6 @@ import type {
   ModuleDescriptor,
 } from './compartment-map-schema.js';
 import type {
-  HashFn,
   MaybeReadFn,
   MaybeReadNowFn,
   ReadFn,
@@ -22,10 +21,14 @@ import type {
 } from './powers.js';
 import type { DeferredAttenuatorsProvider } from './policy.js';
 import type {
+  ArchiveOnlyOption,
   AsyncParseFn,
   CompartmentSources,
+  ComputeSha512Option,
   ExecuteOptions,
-  ExitModuleImportNowHook,
+  ExitModuleImportHookOption,
+  ExitModuleImportNowHookOption,
+  LogOptions,
   ModuleTransforms,
   ParseFn,
   ParserForLanguage,
@@ -43,8 +46,9 @@ export type LinkOptions = {
   parserForLanguage?: ParserForLanguage;
   moduleTransforms?: ModuleTransforms;
   syncModuleTransforms?: SyncModuleTransforms;
-  archiveOnly?: boolean;
-} & ExecuteOptions;
+  __native__?: boolean;
+} & ArchiveOnlyOption &
+  ExecuteOptions;
 
 export type LinkResult = {
   compartment: Compartment;
@@ -60,15 +64,27 @@ export type ResolveHook = (
 
 export type ShouldDeferError = (language: Language | undefined) => boolean;
 
-export type MakeImportNowHookMakerOptions = Partial<{
-  sources: Sources;
-  compartmentDescriptors: Record<string, CompartmentDescriptor>;
-  computeSha512: HashFn;
-  exitModuleImportNowHook: ExitModuleImportNowHook;
-}> &
+export type MakeImportHookMakersOptions = {
+  entryCompartmentName: string;
+  entryModuleSpecifier: string;
+  /**
+   * For depositing captured sources.
+   */
+  sources?: Sources;
+  /**
+   * For depositing captured compartment descriptors.
+   */
+  compartmentDescriptors?: Record<string, CompartmentDescriptor>;
+} & ComputeSha512Option &
   SearchSuffixesOption &
+  ArchiveOnlyOption &
   SourceMapHookOption;
 
+export type MakeImportHookMakerOptions = MakeImportHookMakersOptions &
+  ExitModuleImportHookOption;
+export type MakeImportNowHookMakerOptions = MakeImportHookMakersOptions &
+  ExitModuleImportNowHookOption;
+
 export type ImportHookMaker = (params: {
   packageLocation: string;
   packageName: string;
@@ -117,16 +133,19 @@ export type ChooseModuleDescriptorParams = {
   /** All compartments */
   compartments: Record<string, Compartment>;
   packageSources: CompartmentSources;
-  /** Function to compute SHA-512 hash */
-  computeSha512?: HashFn;
   readPowers: ReadPowers | ReadFn;
+  /**
+   * Whether to embed a sourceURL in applicable compiled sources.
+   * Should be false for archives and bundles, but true for runtime.
+   */
   sourceMapHook?: SourceMapHook;
   /**
    * Function returning a set of module names (scoped to the compartment) whose
    * parser is not using heuristics to determine imports.
    */
   strictlyRequiredForCompartment: (compartmentName: string) => Set<string>;
-};
+} & ComputeSha512Option &
+  ArchiveOnlyOption;
 
 type SyncChooseModuleDescriptorOperators = {
   /**
@@ -214,3 +233,78 @@ export type MakeMapParsersOptions = {
    */
   syncModuleTransforms?: SyncModuleTransforms;
 };
+
+/**
+ * Options for `search()`
+ */
+export type SearchOptions = LogOptions;
+
+/**
+ * Object fulfilled from `search()`
+ */
+export interface SearchResult {
+  packageLocation: string;
+  packageDescriptorLocation: string;
+  packageDescriptorText: string;
+  moduleSpecifier: string;
+}
+
+/**
+ * Object fulfilled from `searchDescriptor()`
+ *
+ * @template T The datatype; may be a {@link PackageDescriptor}, blob, string, etc.
+ */
+export interface SearchDescriptorResult<T> {
+  data: T;
+  directory: string;
+  location: string;
+  packageDescriptorLocation: string;
+}
+
+/**
+ * Options for `searchDescriptor()`
+ */
+export type SearchDescriptorOptions = LogOptions;
+
+/**
+ * A power to read a package descriptor
+ * @template T Format of package descriptor
+ */
+export type ReadDescriptorFn<T = PackageDescriptor> = (
+  location: string,
+) => Promise<T>;
+
+/**
+ * A power to _maybe_ read a package descriptor
+ * @template T Format of package descriptor
+ */
+export type MaybeReadDescriptorFn<T = PackageDescriptor> = (
+  location: string,
+) => Promise<T | undefined>;
+
+/**
+ * The type of a `package.json` file containing relevant fields; used by `graphPackages` and its ilk
+ */
+export interface PackageDescriptor {
+  /**
+   * TODO: In reality, this is optional, but `graphPackage` does not consider it to be. This will need to be fixed once support for "anonymous" packages lands; see https://github.com/endojs/endo/pull/2664
+   */
+  name: string;
+  version?: string;
+  /**
+   * TODO: Update with proper type when this field is handled.
+   */
+  exports?: unknown;
+  type?: 'module' | 'commonjs';
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+  peerDependencies?: Record<string, string>;
+  optionalDependencies?: Record<string, string>;
+  bundleDependencies?: string[];
+  peerDependenciesMeta?: Record<
+    string,
+    { optional?: boolean; [k: string]: unknown }
+  >;
+
+  [k: string]: unknown;
+}