@endo/compartment-mapper 1.5.0 → 1.6.1

package/src/types/internal.d.ts

@@ -1,12 +1,14 @@
 /**
- * @module Internal types of the compartment mapper that need not be visible to
+ * Internal types of the compartment mapper that need not be visible to
  * consumers.
+ *
+ * @module
  */
-import type { ImportHook, ImportNowHook } from 'ses';
+import type { ImportHook, ImportNowHook, StaticModuleType } 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,9 +16,8 @@ export type LinkOptions = {
     parserForLanguage?: ParserForLanguage;
     moduleTransforms?: ModuleTransforms;
     syncModuleTransforms?: SyncModuleTransforms;
-    archiveOnly?: boolean;
     __native__?: boolean;
-} & ExecuteOptions;
+} & ArchiveOnlyOption & ExecuteOptions;
 export type LinkResult = {
     compartment: Compartment;
     compartments: Record<string, Compartment>;
@@ -25,12 +26,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;
@@ -44,8 +53,8 @@ export type ImportNowHookMaker = (params: {
     packageName: string;
     parse: ParseFn | AsyncParseFn;
     compartments: Record<string, Compartment>;
+    shouldDeferError: ShouldDeferError;
     attenuators?: never;
-    shouldDeferError?: never;
 }) => ImportNowHook;
 /**
  * The value returned by `makeMapParsers()`
@@ -72,15 +81,16 @@ export type ChooseModuleDescriptorParams = {
     /** All compartments */
     compartments: Record<string, Compartment>;
     packageSources: CompartmentSources;
-    /** Function to compute SHA-512 hash */
-    computeSha512?: HashFn;
     readPowers: ReadPowers | ReadFn;
-    sourceMapHook?: SourceMapHook;
     /**
-     * Function returning a set of module names (scoped to the compartment) whose
-     * parser is not using heuristics to determine imports.
+     * Whether to embed a sourceURL in applicable compiled sources.
+     * Should be false for archives and bundles, but true for runtime.
      */
-    strictlyRequiredForCompartment: (compartmentName: string) => Set<string>;
+    sourceMapHook?: SourceMapHook;
+    strictlyRequiredForCompartment: StrictlyRequiredFn;
+} & ComputeSha512Option & ArchiveOnlyOption;
+type ShouldDeferErrorOption = {
+    shouldDeferError: ShouldDeferError;
 };
 type SyncChooseModuleDescriptorOperators = {
     /**
@@ -93,8 +103,6 @@ type SyncChooseModuleDescriptorOperators = {
      * a `ParseResult`
      */
     parse: ParseFn;
-    /** Should be omitted */
-    shouldDeferError?: never;
 };
 /**
  * Operators for `chooseModuleDescriptor` representing asynchronous operation.
@@ -110,16 +118,11 @@ export type AsyncChooseModuleDescriptorOperators = {
      * a `ParseResult`
      */
     parse: AsyncParseFn | ParseFn;
-    /**
-     * A function that returns `true` if the language returned by `parse` should
-     * defer errors.
-     */
-    shouldDeferError: (language: Language) => boolean;
 };
 /**
  * Either synchronous or asynchronous operators for `chooseModuleDescriptor`.
  */
-export type ChooseModuleDescriptorOperators = AsyncChooseModuleDescriptorOperators | SyncChooseModuleDescriptorOperators;
+export type ChooseModuleDescriptorOperators = ShouldDeferErrorOption & (AsyncChooseModuleDescriptorOperators | SyncChooseModuleDescriptorOperators);
 /**
  * The agglomeration of things that the `chooseModuleDescriptor` generator can
  * yield.
@@ -137,8 +140,6 @@ export type FindRedirectParams = {
     compartmentDescriptors: Record<string, CompartmentDescriptor>;
     compartments: Record<string, Compartment>;
     absoluteModuleSpecifier: string;
-    /** Location of the compartment descriptor's package. */
-    packageLocation: string;
 };
 /**
  * Options for `makeMapParsers()`
@@ -158,5 +159,91 @@ 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;
+    }>;
+    module?: string;
+    browser?: Record<string, string> | string;
+    main?: string;
+    [k: string]: unknown;
+}
+/**
+ * Function returning a set of module names (scoped to the compartment) whose
+ * parser is not using heuristics to determine imports.
+ */
+export type StrictlyRequiredFn = (compartmentName: string) => Set<string>;
+/**
+ * Function which decides whether to throw an error immediately upon failing to
+ * load a module or defer to execution time.
+ *
+ * @returns A phony `StaticModuleType` which throws when executed
+ */
+export type DeferErrorFn = (
+/**
+ * The module specifier that failed to load
+ */
+specifier: string, 
+/**
+ * The error that was thrown
+ */
+error: Error) => StaticModuleType;
 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

@@ -1,11 +1,13 @@
 /**
- * @module Internal types of the compartment mapper that need not be visible to
+ * Internal types of the compartment mapper that need not be visible to
  * consumers.
+ *
+ * @module
  */
 
 /* eslint-disable no-use-before-define */
 
-import type { ImportHook, ImportNowHook } from 'ses';
+import type { ImportHook, ImportNowHook, StaticModuleType } from 'ses';
 import type {
   CompartmentDescriptor,
   Language,
@@ -14,7 +16,6 @@ import type {
   ModuleDescriptor,
 } from './compartment-map-schema.js';
 import type {
-  HashFn,
   MaybeReadFn,
   MaybeReadNowFn,
   ReadFn,
@@ -22,10 +23,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,9 +48,9 @@ export type LinkOptions = {
   parserForLanguage?: ParserForLanguage;
   moduleTransforms?: ModuleTransforms;
   syncModuleTransforms?: SyncModuleTransforms;
-  archiveOnly?: boolean;
   __native__?: boolean;
-} & ExecuteOptions;
+} & ArchiveOnlyOption &
+  ExecuteOptions;
 
 export type LinkResult = {
   compartment: Compartment;
@@ -61,15 +66,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;
@@ -84,11 +101,11 @@ export type ImportNowHookMaker = (params: {
   packageName: string;
   parse: ParseFn | AsyncParseFn;
   compartments: Record<string, Compartment>;
+  shouldDeferError: ShouldDeferError;
   // Unlike analogous prameters of ImportHookMaker, the Compartment Mapper
   // ignores these two parameters, so they are expressly disallowed to avoid
   // confusion about whether they would be respected.
   attenuators?: never;
-  shouldDeferError?: never;
 }) => ImportNowHook;
 
 /**
@@ -118,15 +135,19 @@ export type ChooseModuleDescriptorParams = {
   /** All compartments */
   compartments: Record<string, Compartment>;
   packageSources: CompartmentSources;
-  /** Function to compute SHA-512 hash */
-  computeSha512?: HashFn;
   readPowers: ReadPowers | ReadFn;
-  sourceMapHook?: SourceMapHook;
   /**
-   * Function returning a set of module names (scoped to the compartment) whose
-   * parser is not using heuristics to determine imports.
+   * Whether to embed a sourceURL in applicable compiled sources.
+   * Should be false for archives and bundles, but true for runtime.
    */
-  strictlyRequiredForCompartment: (compartmentName: string) => Set<string>;
+  sourceMapHook?: SourceMapHook;
+
+  strictlyRequiredForCompartment: StrictlyRequiredFn;
+} & ComputeSha512Option &
+  ArchiveOnlyOption;
+
+type ShouldDeferErrorOption = {
+  shouldDeferError: ShouldDeferError;
 };
 
 type SyncChooseModuleDescriptorOperators = {
@@ -140,8 +161,6 @@ type SyncChooseModuleDescriptorOperators = {
    * a `ParseResult`
    */
   parse: ParseFn;
-  /** Should be omitted */
-  shouldDeferError?: never;
 };
 
 /**
@@ -158,19 +177,13 @@ export type AsyncChooseModuleDescriptorOperators = {
    * a `ParseResult`
    */
   parse: AsyncParseFn | ParseFn;
-  /**
-   * A function that returns `true` if the language returned by `parse` should
-   * defer errors.
-   */
-  shouldDeferError: (language: Language) => boolean;
 };
 
 /**
  * Either synchronous or asynchronous operators for `chooseModuleDescriptor`.
  */
-export type ChooseModuleDescriptorOperators =
-  | AsyncChooseModuleDescriptorOperators
-  | SyncChooseModuleDescriptorOperators;
+export type ChooseModuleDescriptorOperators = ShouldDeferErrorOption &
+  (AsyncChooseModuleDescriptorOperators | SyncChooseModuleDescriptorOperators);
 
 /**
  * The agglomeration of things that the `chooseModuleDescriptor` generator can
@@ -193,8 +206,6 @@ export type FindRedirectParams = {
   compartments: Record<string, Compartment>;
   /* A module specifier which is an absolute path. NOT a `file://` URL. */
   absoluteModuleSpecifier: string;
-  /** Location of the compartment descriptor's package. */
-  packageLocation: string;
 };
 
 /**
@@ -215,3 +226,105 @@ 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 }
+  >;
+  module?: string;
+  browser?: Record<string, string> | string;
+
+  main?: string;
+
+  [k: string]: unknown;
+}
+
+/**
+ * Function returning a set of module names (scoped to the compartment) whose
+ * parser is not using heuristics to determine imports.
+ */
+export type StrictlyRequiredFn = (compartmentName: string) => Set<string>;
+
+/**
+ * Function which decides whether to throw an error immediately upon failing to
+ * load a module or defer to execution time.
+ *
+ * @returns A phony `StaticModuleType` which throws when executed
+ */
+export type DeferErrorFn = (
+  /**
+   * The module specifier that failed to load
+   */
+  specifier: string,
+  /**
+   * The error that was thrown
+   */
+  error: Error,
+) => StaticModuleType;

package/src/types/node-modules.d.ts

@@ -0,0 +1,79 @@
+import type { Language, LanguageForExtension } from './compartment-map-schema.js';
+import type { LogOptions } from './external.js';
+import type { PackageDescriptor } from './internal.js';
+export type CommonDependencyDescriptors = Record<string, {
+    spec: string;
+    alias: string;
+}>;
+export type GraphPackageOptions = {
+    preferredPackageLogicalPathMap?: Map<string, string[]>;
+    logicalPath?: string[];
+    commonDependencyDescriptors?: CommonDependencyDescriptors;
+} & LogOptions;
+export type GraphPackagesOptions = LogOptions;
+export type GatherDependencyOptions = {
+    childLogicalPath?: string[];
+    /**
+     * If `true` the dependency is optional
+     */
+    optional?: boolean;
+    /**
+     * Dependencies added to _all_ packages
+     */
+    commonDependencyDescriptors?: CommonDependencyDescriptors;
+} & LogOptions;
+export interface Node {
+    /**
+     * Informative compartment label based on the package name and version (if available)
+     */
+    label: string;
+    /**
+     * Package name
+     */
+    name: string;
+    path: Array<string>;
+    logicalPath: Array<string>;
+    /**
+     * `true` if the package's {@link PackageDescriptor} has an `exports` field
+     */
+    explicitExports: boolean;
+    internalAliases: Record<string, string>;
+    externalAliases: Record<string, string>;
+    /**
+     * The name of the original package's parent directory, for reconstructing
+     * a sourceURL that is likely to converge with the original location in an IDE.
+     */
+    sourceDirname: string;
+    /**
+     * 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;
+     * i.e. the URL that was used as the key of graph).
+     *
+     * The values are the keys of other {@link Node Nodes} in the {@link Graph}.
+     */
+    dependencyLocations: Record<string, string>;
+    parsers: LanguageForExtension;
+    types: Record<string, Language>;
+}
+/**
+ * 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.
+ */
+export type Graph = Record<string, Node>;
+export interface LanguageOptions {
+    commonjsLanguageForExtension: LanguageForExtension;
+    moduleLanguageForExtension: LanguageForExtension;
+    workspaceCommonjsLanguageForExtension: LanguageForExtension;
+    workspaceModuleLanguageForExtension: LanguageForExtension;
+    languages: Set<string>;
+}
+/**
+ * Object result of `findPackage()`
+ */
+export interface PackageDetails {
+    packageLocation: string;
+    packageDescriptor: PackageDescriptor;
+}
+//# sourceMappingURL=node-modules.d.ts.map

package/src/types/node-modules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-modules.d.ts","sourceRoot":"","sources":["node-modules.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,QAAQ,EACR,oBAAoB,EACrB,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAEvD,MAAM,MAAM,2BAA2B,GAAG,MAAM,CAC9C,MAAM,EACN;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAChC,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,8BAA8B,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IACvD,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,2BAA2B,CAAC,EAAE,2BAA2B,CAAC;CAC3D,GAAG,UAAU,CAAC;AAEf,MAAM,MAAM,oBAAoB,GAAG,UAAU,CAAC;AAE9C,MAAM,MAAM,uBAAuB,GAAG;IACpC,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B;;OAEG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;OAEG;IACH,2BAA2B,CAAC,EAAE,2BAA2B,CAAC;CAC3D,GAAG,UAAU,CAAC;AAEf,MAAM,WAAW,IAAI;IACnB;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACpB,WAAW,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC3B;;OAEG;IACH,eAAe,EAAE,OAAO,CAAC;IACzB,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC;;;OAGG;IACH,aAAa,EAAE,MAAM,CAAC;IACtB;;;;;;OAMG;IACH,mBAAmB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5C,OAAO,EAAE,oBAAoB,CAAC;IAC9B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;CACjC;AAED;;;;;GAKG;AACH,MAAM,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;AAEzC,MAAM,WAAW,eAAe;IAC9B,4BAA4B,EAAE,oBAAoB,CAAC;IACnD,0BAA0B,EAAE,oBAAoB,CAAC;IACjD,qCAAqC,EAAE,oBAAoB,CAAC;IAC5D,mCAAmC,EAAE,oBAAoB,CAAC;IAC1D,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,eAAe,EAAE,MAAM,CAAC;IACxB,iBAAiB,EAAE,iBAAiB,CAAC;CACtC"}

package/src/types/node-modules.ts

@@ -0,0 +1,89 @@
+import type {
+  Language,
+  LanguageForExtension,
+} from './compartment-map-schema.js';
+import type { LogOptions } from './external.js';
+import type { PackageDescriptor } from './internal.js';
+
+export type CommonDependencyDescriptors = Record<
+  string,
+  { spec: string; alias: string }
+>;
+
+export type GraphPackageOptions = {
+  preferredPackageLogicalPathMap?: Map<string, string[]>;
+  logicalPath?: string[];
+  commonDependencyDescriptors?: CommonDependencyDescriptors;
+} & LogOptions;
+
+export type GraphPackagesOptions = LogOptions;
+
+export type GatherDependencyOptions = {
+  childLogicalPath?: string[];
+  /**
+   * If `true` the dependency is optional
+   */
+  optional?: boolean;
+  /**
+   * Dependencies added to _all_ packages
+   */
+  commonDependencyDescriptors?: CommonDependencyDescriptors;
+} & LogOptions;
+
+export interface Node {
+  /**
+   * Informative compartment label based on the package name and version (if available)
+   */
+  label: string;
+  /**
+   * Package name
+   */
+  name: string;
+  path: Array<string>;
+  logicalPath: Array<string>;
+  /**
+   * `true` if the package's {@link PackageDescriptor} has an `exports` field
+   */
+  explicitExports: boolean;
+  internalAliases: Record<string, string>;
+  externalAliases: Record<string, string>;
+  /**
+   * The name of the original package's parent directory, for reconstructing
+   * a sourceURL that is likely to converge with the original location in an IDE.
+   */
+  sourceDirname: string;
+  /**
+   * 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;
+   * i.e. the URL that was used as the key of graph).
+   *
+   * The values are the keys of other {@link Node Nodes} in the {@link Graph}.
+   */
+  dependencyLocations: Record<string, string>;
+  parsers: LanguageForExtension;
+  types: Record<string, Language>;
+}
+
+/**
+ * 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.
+ */
+export type Graph = Record<string, Node>;
+
+export interface LanguageOptions {
+  commonjsLanguageForExtension: LanguageForExtension;
+  moduleLanguageForExtension: LanguageForExtension;
+  workspaceCommonjsLanguageForExtension: LanguageForExtension;
+  workspaceModuleLanguageForExtension: LanguageForExtension;
+  languages: Set<string>;
+}
+
+/**
+ * Object result of `findPackage()`
+ */
+export interface PackageDetails {
+  packageLocation: string;
+  packageDescriptor: PackageDescriptor;
+}