docs(compartment-mapper): Add overview for every module

packages/compartment-mapper/src/archive-lite.js

@@ -1,3 +1,34 @@
+/**
+ * @file Provides functions to create an archive (zip file with a
+ * compartment-map.json) from a partially completed compartment map (it must
+ * mention all packages/compartments as well as inter-compartment references
+ * but does not contain an entry for every module reachable from its entry
+ * module) and the means to read them from the containing file system.
+ *
+ * These functions do not have a bias for any particular mapping, so you will
+ * need to use `mapNodeModules` from `@endo/compartment-map/node-modules.js` or
+ * a similar device to construct one.
+ *
+ * The default `parserForLanguage` mapping is empty.
+ * You will need to provide the `defaultParserForLanguage` from
+ * `@endo/compartment-mapper/import-parsers.js` or
+ * `@endo/compartment-mapper/archive-parsers.js`.
+ *
+ * If you use `@endo/compartment-mapper/archive-parsers.js`, the archive
+ * will contain pre-compiled ESM and CJS modules wrapped in a JSON
+ * envelope, suitable for use with the SES shim in any environment
+ * including a web page, without a client-side dependency on Babel.
+ *
+ * If you use `@endo/compartment-mapper/import-parsers.js`, the archive
+ * will contain original sources, so to import the archive with
+ * `src/import-archive-lite.js`, you will need to provide the archive parsers
+ * and entrain a runtime dependency on Babel.
+ *
+ * In fruition of https://github.com/endojs/endo/issues/400, we will be able to
+ * use original source archives on XS and Node.js, but not on the web until the
+ * web platform makes further progress on virtual module loaers.
+ */
+
 // @ts-check
 /* eslint no-shadow: 0 */
 

packages/compartment-mapper/src/archive-parsers.js

@@ -1,3 +1,10 @@
+/**
+ * @file Provides a set of default language behaviors (parsers) suitable for
+ * creating archives (zip files with a `compartment-map.json` and a file for
+ * each module) with pre-compiled sources.
+ *
+ * This module entrains a dependency upon the core of Babel.
+ */
 /** @import {ParserForLanguage} from './types.js' */
 
 import parserJson from './parse-json.js';

packages/compartment-mapper/src/archive.js

@@ -1,3 +1,19 @@
+/**
+ * @file Provides mechanisms for creating archives (zip files with a
+ * `compartmeent-map.json` and a file for every static dependency of an entry
+ * module).
+ *
+ * Uses the conventions of Node.js package managers and the `node_modules`.
+ * Archives will contain a copy for every physical copy of a package on disk,
+ * such that importing will construct a separate instance for each.
+ *
+ * These archives will contain pre-compiled ESM and CJS and this module
+ * entrains a dependency on the core of Babel.
+ *
+ * See `archive-lite.js` for a variation that does not depend on Babel
+ * for cases like XS native Compartments where pre-compilation is not
+ * necessary or where the dependency on Babel can be dererred to runtime.
+ */
 // @ts-check
 
 import { defaultParserForLanguage } from './archive-parsers.js';

packages/compartment-mapper/src/bundle-cjs.js

@@ -1,3 +1,4 @@
+/** @file Provides CommonJS support for `bundle.js`. */
 // @ts-nocheck
 /** quotes strings */
 const q = JSON.stringify;

packages/compartment-mapper/src/bundle-mjs.js

@@ -1,3 +1,5 @@
+/** @file Provides ESM support for `bundle.js`. */
+
 /** quotes strings */
 const q = JSON.stringify;
 

packages/compartment-mapper/src/compartment-map.js

@@ -1,3 +1,7 @@
+/**
+ * @file Validates a compartment map against its schema.
+ */
+
 // @ts-check
 /// <reference types="ses"/>
 

packages/compartment-mapper/src/extension.js

@@ -1,3 +1,7 @@
+/**
+ * @file Extracts the extension from a URL pathname.
+ */
+
 // @ts-check
 
 /**

packages/compartment-mapper/src/import-archive-lite.js

@@ -1,3 +1,18 @@
+/**
+ * @file Provides functions for evaluating the modules in an archive (a zip
+ * file with a `compartment-map.json` and a file for each module it contains.)
+ *
+ * These functions do not have a bias for any particular mapping, so you will
+ * need to use `mapNodeModules` from `@endo/compartment-map/node-modules.js` or
+ * a similar device to construct one.
+ *
+ * The default `parserForLanguage` mapping is empty.
+ * You will need to provide the `defaultParserForLanguage` from
+ * `@endo/compartment-mapper/import-parsers.js` or
+ * `@endo/compartment-mapper/archive-parsers.js`.
+ *
+ */
+
 // @ts-check
 /* eslint no-shadow: "off" */
 

packages/compartment-mapper/src/import-archive-parsers.js

@@ -1,3 +1,10 @@
+/**
+ * @file Provides a set of default language behaviors (parsers) suitable for
+ * evaluating archives (zip files with a `compartment-map.json` and a file for
+ * each module) with pre-compiled ESM and CommonJS.
+ *
+ * This module does not entrain a dependency on Babel.
+ */
 /** @import {ParserForLanguage} from './types.js' */
 
 import parserPreCjs from './parse-pre-cjs.js';

packages/compartment-mapper/src/import-archive.js

@@ -1,3 +1,19 @@
+/**
+ * @file Provides functions for evaluating modules in an archive (a zip file
+ * with a `compartment-map.json` and a file for a module and each of its
+ * transitive dependencies.)
+ *
+ * These functions accept the URL of an entry module and find its transitive
+ * dependencies through the Node.js `node_modules` conventions.
+ *
+ * These functions use the default parsers in `import-archive-parsers.js`,
+ * which support only pre-compiled ESM and CommonJS.
+ *
+ * See `import-archive-lite.js` for functions that are not coupled to these
+ * parsers or the `node_modules` conventions without necessarily entraining a
+ * dependency on Babel.
+ */
+
 // @ts-check
 
 import { defaultParserForLanguage } from './import-archive-parsers.js';

packages/compartment-mapper/src/import-hook.js

@@ -1,3 +1,12 @@
+/**
+ * @file Provides the implementation of each compartment's `importHook` when using
+ * `import.js`, `import-lite.js`, `archive.js`, or `archive-lite.js`.
+ * However, `import-archive.js` and `import-archive-lite.js` use their own variant.
+ *
+ * For building archives, these import hooks create a table of all the modules
+ * in a "working set" of transitive dependencies.
+ */
+
 // @ts-check
 
 /** @import {ImportHook} from 'ses' */

packages/compartment-mapper/src/import-lite.js

@@ -1,3 +1,20 @@
+/**
+ * @file Provides functions for evaluating a module and its transitive
+ * dependencies given a partially completed compartment map.
+ * The compartment map needs to describe every reachable compartment, where to
+ * find modules in that compartment, and how to link modules between
+ * compartments, but does not need to capture a module descriptor for every
+ * module in the working set of transitive dependencies from the entry module.
+ *
+ * These functions do not have a bias for any particular mapping, so you will
+ * need to use `mapNodeModules` from `@endo/compartment-map/node-modules.js` or
+ * a similar device to construct one.
+ *
+ * The default `parserForLanguage` mapping is empty.
+ * You will need to provide the `defaultParserForLanguage` from
+ * `@endo/compartment-mapper/import-parsers.js` or similar.
+ */
+
 // @ts-check
 /* eslint no-shadow: "off" */
 

packages/compartment-mapper/src/import-parsers.js

@@ -1,3 +1,10 @@
+/**
+ * @file Provides a set of default language behaviors (parsers) suitable for
+ * evaluating modules that have not been pre-compiled.
+ *
+ * This module entrains a dependency upon the core of Babel.
+ */
+
 /** @import {ParserForLanguage} from './types.js' */
 
 import parserJson from './parse-json.js';

packages/compartment-mapper/src/import.js

@@ -1,3 +1,16 @@
+/**
+ * @file Provides functions for evaluating a module and its transitive
+ * dependencies given the URL of the entry module and assuming packages
+ * laid out according to the `node_modules` conventions.
+ *
+ * To import modules according to any other convention, use `import-lite.js`
+ * and provide a compartment map with a custom analog to `mapNodeModules` from
+ * `node-modules.js`.
+ *
+ * The default `parserForLanguage` is `import-parsers.js`, which is suitable
+ * for most cases.
+ */
+
 // @ts-check
 
 import { defaultParserForLanguage } from './import-parsers.js';

packages/compartment-mapper/src/infer-exports.js

@@ -1,3 +1,11 @@
+/**
+ * @file Provides functions needed by `node-modules.js` for building
+ * inter-compartment linkage according to the specifications in a
+ * `package.json` as laid out in the `node_modules` convention.
+ * These functions implement the behavior for a package's `"main"`,
+ * `"browser"`, `"imports"`, and `"exports"` properties in a `package.json`.
+ */
+
 // @ts-check
 
 /** @import {LanguageForExtension} from './types.js' */

packages/compartment-mapper/src/json.js

@@ -1,3 +1,4 @@
+/** @file Annotates JSON parse exceptions with the location of the source. */
 // @ts-check
 
 /**

packages/compartment-mapper/src/link.js

@@ -1,3 +1,12 @@
+/**
+ * @file Provides the linking behavior shared by all Compartment Mapper workflows.
+ * This involves creating and configuring compartments according to the
+ * specifications in a compartment map, and is suitable for compartment maps
+ * that just outline the locations of compartments and their inter-linkage and
+ * also compartment maps that include every module descriptor in the transitive
+ * dependencies of their entry module.
+ */
+
 // @ts-check
 
 /** @import {ModuleMapHook} from 'ses' */
@@ -494,6 +503,7 @@ export const link = (
 /**
  * @param {CompartmentMapDescriptor} compartmentMap
  * @param {LinkOptions} options
+ * @deprecated Use {@see link}.
  */
 export const assemble = (compartmentMap, options) =>
   link(compartmentMap, options).compartment;

packages/compartment-mapper/src/node-module-specifier.js

@@ -1,3 +1,9 @@
+/**
+ * @file Provides functions for interacting with Node.js module specifiers in
+ * their canonical form.
+ * This is a kind of path math that is platform-agnostic.
+ */
+
 // @ts-check
 
 // q, as in quote, for error messages.

packages/compartment-mapper/src/node-modules.js

@@ -1,3 +1,14 @@
+/**
+ * @file Provides functions for constructing a compartment map that has a
+ * compartment descriptor corresponding to every reachable package from an
+ * entry module and how to create links between them.
+ * The resulting compartment map does not describe individual modules but does
+ * capture every usable route between packages including those generalized by
+ * wildcard expansion.
+ * See {@link link} to expand a compartment map to capture module descriptors
+ * for transitive dependencies.
+ */
+
 // @ts-check
 /* eslint no-shadow: 0 */
 

packages/compartment-mapper/src/node-powers.js

@@ -1,3 +1,12 @@
+/**
+ * @file Provides adapters for Compartment Mapper I/O to the corresponding
+ * Node.js implementations of those behaviors.
+ *
+ * The Compartment Mapper generalizes its I/O interface to allow for a wide
+ * variety of I/O providers, but especially for reading and writing from
+ * virtualized file systems like zip files.
+ */
+
 // @ts-check
 
 /** @import {ReadPowers} from './types.js' */

packages/compartment-mapper/src/parse-archive-cjs.js

@@ -1,3 +1,8 @@
+/**
+ * @file Provides language behavior for analyzing, pre-compiling, and storing
+ * CommonJS modules for an archive.
+ */
+
 // @ts-check
 
 import { analyzeCommonJS } from '@endo/cjs-module-analyzer';

packages/compartment-mapper/src/parse-archive-mjs.js

@@ -1,3 +1,7 @@
+/**
+ * @file Provides language behavior for analyzing, pre-compiling, and storing
+ * ESM modules for an archive.
+ */
 // @ts-check
 
 import { StaticModuleRecord } from '@endo/static-module-record';

packages/compartment-mapper/src/parse-bytes.js

@@ -1,3 +1,8 @@
+/**
+ * @file Provides rudimentary support for treating an arbitrary file as a
+ * module that exports the bytes of that file.
+ */
+
 // @ts-check
 
 /**

packages/compartment-mapper/src/parse-cjs-shared-export-wrapper.js

@@ -1,3 +1,9 @@
+/**
+ * @file Provides shared functionality for {@link parse-cjs.js} and {@link
+ * parse-archive-cjs.js} toward importing or archiving CommonJS as a virtual
+ * module source.
+ */
+
 // @ts-check
 
 /** @import {ReadFn} from './types.js' */

packages/compartment-mapper/src/parse-cjs.js

@@ -1,3 +1,8 @@
+/**
+ * @file Provides language behavior (parser) for importing CommonJS as a
+ * virtual module source.
+ */
+
 // @ts-check
 
 import { analyzeCommonJS } from '@endo/cjs-module-analyzer';

packages/compartment-mapper/src/parse-json.js

@@ -1,3 +1,7 @@
+/**
+ * @file Provides language support for importing JSON modules.
+ */
+
 // @ts-check
 
 import { parseLocatedJson } from './json.js';

packages/compartment-mapper/src/parse-mjs.js

@@ -1,3 +1,5 @@
+/** @file Provides language behavior (a parser) for importing ESM. */
+
 // @ts-check
 
 import { StaticModuleRecord } from '@endo/static-module-record';

packages/compartment-mapper/src/parse-pre-cjs.js

@@ -1,3 +1,10 @@
+/**
+ * @file Provides language-specific behavior for importing pre-compiled CommonJS.
+ * Pre-compiled CommonJS is a module in JSON format that describes its imports,
+ * exports, and source to execute in the presence of `require`, `module`, and
+ * `exports`.
+ */
+
 // @ts-check
 
 import { parseLocatedJson } from './json.js';

packages/compartment-mapper/src/parse-pre-mjs.js

@@ -1,3 +1,10 @@
+/**
+ * @file Provides language-specific behaviors for importing pre-compiled ESM.
+ * Pre-compiling or translating ESM from a module to a script with a
+ * calling-convention is necessary to prepare an archive so that it can be
+ * imported by the SES shim without entraining a dependency on Babel.
+ */
+
 // @ts-check
 
 import { parseLocatedJson } from './json.js';

packages/compartment-mapper/src/parse-text.js

@@ -1,3 +1,9 @@
+/**
+ * @file Provides language-behaviors for importing a module as a document that
+ * exports itself as a string based on a UTF-8 interpretation of the module's
+ * text.
+ */
+
 // @ts-check
 
 /**

packages/compartment-mapper/src/policy-format.js

@@ -1,3 +1,8 @@
+/**
+ * @file Provides functions for enforcing compartment-map linkage and global
+ * variable policies for each compartment.
+ */
+
 // @ts-check
 
 /** @import {SomePackagePolicy} from './types.js' */

packages/compartment-mapper/src/policy.js

@@ -1,3 +1,7 @@
+/**
+ * @file Provides mechanisms for interacting with Compartment Map runtime policies.
+ */
+
 // @ts-check
 
 import {