@endo/compartment-mapper
Version:
The compartment mapper assembles Node applications in a sandbox
863 lines (163 loc) • 25.5 kB
JavaScript
/**
* External types of the compartment mapper.
*
* @module
*/
/* eslint-disable no-use-before-define */
/**
* Hook executed for each canonical name mentioned in policy but not found in the
* compartment map
*/
/**
* Data about a package provided by a {@link PackageDataHook}
*/
/**
* Hook executed with data about all packages found while crawling `node_modules`.
*
* Called once before `translateGraph`.
*/
/**
* Hook executed for each canonical name (corresponding to a package) in the
* `CompartmentMapDescriptor` with a list of canonical names of its
* dependencies.
*
* Can return partial updates to modify the dependencies set.
*
* Suggested use cases:
* - Adding dependencies based on policy
* - Removing dependencies based on policy
* - Filtering dependencies based on multiple criteria
*/
/**
* The `moduleSource` property value for {@link ModuleSourceHook}
*/
/**
* The `moduleSource` property value for {@link ModuleSourceHook} for a module
* on disk
*/
/**
* The `moduleSource` property value for {@link ModuleSourceHook} for an exit
* module (virtual)
*/
/**
* Hook executed when processing a module source.
*/
/**
* Hook executed for each canonical name with its connections (linked compartments).
*/
/**
* Hook executed during preloading when a compartment designated to be preloaded
* is already loaded.
*/
/**
* Set of options available in the context of code execution.
*
* May be used only as an intersection with other options types.
*/
/**
* Options having an optional `log` property.
*/
/**
* Options for `mapNodeModules()`
*/
/**
* An additional package location to include in the compartment map graph.
*
* This allows packages that are not reachable through the entry package's
* dependency graph to appear in the compartment map. A common use case is
* including a project root package when the entry point is a tool binary
* (e.g., webpack) inside `node_modules`.
*/
/**
* Hook options for `mapNodeModules()`
*/
/**
* Options for `captureFromMap()`
*/
/**
* Hook options for `captureFromMap()`
*/
/**
* Options bag containing a `preload` array.
*/
/**
* Options for `loadLocation()`
*/
/**
* Hook options for `loadLocation()`
*/
/**
* Options for `importLocation()` necessary (but not sufficient--see
* `ReadNowPowers`) for dynamic require support
*/
/**
* Options for `importLocation()` without dynamic require support
*/
// ////////////////////////////////////////////////////////////////////////////////
// Single Options
// ////////////////////////////////////////////////////////////////////////////////
// Common option groups:
// ////////////////////////////////////////////////////////////////////////////////
/**
* Result of `digestCompartmentMap()`
*/
/**
* The result of `captureFromMap`.
*/
/**
* The result of `makeArchiveCompartmentMap`
*/
/**
* The compartment mapper can capture the Sources for all loaded modules
* for bundling, archiving, or analysis.
*/
/**
* A hook for archiving that allows the caller to create a side-table or
* out-of-band reference for where the archive's sources originated,
* intended to assist debuggers.
* When making and importing an archive locally, `import-archive.js` can inject
* the original source location for compartment name and module specifier chosen
* by `archive.js.
*/
/**
* Result of a {@link ParseFn} or {@link AsyncParseFn}
*/
/**
* A synchronous module parsing function.
*
* @todo This and all parser-related types (including {@link ParseResult} should
* be moved into a separate package. `@endo/parser-pipeline` needs these types,
* and a package needing the types in `@endo/parser-pipeline` would then pull in
* `@endo/compartment-mapper` as a transitive dep and all _its_ transitive deps.
* Because {@link ParseResult} contains {@link FinalStaticModuleType} from
* `ses`, those types would want to be moved out of `ses` with it.
*/
/**
* An asynchronous module parsing function.
*/
/**
* Mapping of `Language` to synchronous {@link ParserImplementation}s only.
*
* Used when all parsers are known to be synchronous.
*/
/**
* Mapping of `Language` to {@link ParserImplementation
* ParserImplementations} or {@link AsyncParserImplementation}s.
*
* When any entry has `synchronous: false`, the pipeline uses the async
* trampoline.
*/
/**
* Generic logging function accepted by various functions.
*/
/**
* A string that represents a file URL.
*/
/**
* A function that renames compartments; used by `digestCompartmentMap()`.
*
* The default implementation uses {@link PackageCompartmentDescriptorName} as the key type.
*
* @returns Mapping from old compartment names to new compartment names
* @template NewName Key type
*/