@endo/compartment-mapper 1.3.1 → 1.5.0

package/README.md

@@ -204,6 +204,8 @@ does not exist, to the `index.js` file in the directory with the same name.
 > `fetch` global, in conjunction with usable values for `import.meta.url` in
 > ECMAScript modules or `__dirname` and `__filename` in CommonJS modules.
 
+## Language Extensions
+
 Officially beginning with Node.js 14, Node.js treats `.mjs` files as ECMAScript
 modules and `.cjs` files as CommonJS modules.
 The `.js` extension indicates a CommonJS module by default, to maintain
@@ -211,30 +213,6 @@ backward compatibility.
 However, packages that have a `type` property that explicitly says `module`
 will treat a `.js` file as an ECMAScript module.
 
-This unforunately conflicts with packages written to work with the ECMAScript
-module system emulator in the `esm` package on npm, which allows every file
-with the `js` extension to be an ECMAScript module that presents itself to
-Node.js as a CommonJS module.
-To overcome such obstacles, the compartment mapper will accept a non-standard
-`parsers` property in `package.json` that maps file extensions, specifically
-`js` to the corresponding language name, one of `mjs` for ECMAScript modules,
-`cjs` for CommonJS modules, and `json` for JSON modules.
-All other language names are reserved and the defaults for files with the
-extensions `cjs`, `mjs`, `json`, `text`, and `bytes` default to the language of
-the same name unless overridden.
-JSON modules export a default object resulting from the conventional JSON.parse
-of the module's UTF-8 encoded bytes.
-Text modules export a default string from the module's UTF-8 encoded bytes.
-Bytes modules export a default ArrayBuffer capturing the module's bytes.
-If compartment mapper sees `parsers`, it ignores `type`, so these can
-contradict where using the `esm` emulator requires.
-
-```json
-{
-  "parsers": {"js": "mjs"}
-}
-```
-
 Many Node.js applications using CommonJS modules expect to be able to `require`
 a JSON file like `package.json`.
 The compartment mapper supports loading JSON modules from any type of module.
@@ -252,9 +230,54 @@ As of Node.js 14, Node does not support loading ECMAScript modules from
 CommonJS modules, so using this feature may limit compatibility with the
 Node.js platform.
 
-> TODO A future version may introduce language plugins, so a package may state
-> that files with a particular extension are either parsed or linked with
-> another module.
+The compartment mapper supports language plugins.
+The languages supported by default are:
+
+- `mjs` for ECMAScript modules,
+- `cjs` for CommonJS modules,
+- `json` for JSON modules,
+- `text` for UTF-8 encoded text files,
+- `bytes` for any file, exporting a `Uint8Array` as `default`,
+- `pre-mjs-json` for pre-compiled ECMAScript modules captured as JSON in
+  archives, and
+- `pre-cjs-json` for pre-compiled CommonJS modules captured as JSON in
+  archives.
+
+The compartment mapper accepts extensions to this set of languages with
+the `parserForLanguage` option supported by many functions.
+See `src/types/external.ts` for the type and expected behavior for
+parsers.
+
+These language identifiers are keys for the `moduleTransforms` and
+`syncModuleTransforms` options, which may map each language to a transform
+function.
+The language identifiers are also the values for a `languageForExtension`,
+`moduleLanguageForExtension`, and `commonjsLanguageForExtension` options to
+configure additional extension-to-language mappings for a module and its
+transitive dependencies.
+
+For any package that has `type` set to `"module"` in its `package.json`,
+`moduleLangaugeForExtension` will precede `languageForExtension`.
+Packages with `type` set to `"commonjs"` or simply not set,
+`commonjsLanguageForExtension` will precede `languageForExtension`.
+This provides an hook for mapping TypeScript's `.ts` to either `.cts` or
+`.mts`.
+
+The analogous `workspaceLanguageForExtension`,
+`workspaceCommonjsLanguageForExtension`, and
+`workspaceModuleLanguageForExtension` options apply more specifically for
+packages that are not under a `node_modules` directory, indicating that they
+are in the set of linked workspaces and have not been built or published to
+npm.
+
+In the scope any given package, the `parsers` property in `package.json` may
+override the extension-to-language mapping.
+
+```json
+{
+  "parsers": { "png": "bytes" }
+}
+```
 
 > TODO
 >
@@ -305,6 +328,20 @@ These will be appended to each module from the archive, for debugging purposes.
 The `@endo/bundle-source` and `@endo/import-bundle` tools integrate source maps
 for an end-to-end debugging experience.
 
+# XS (experimental)
+
+The Compartment Mapper can use native XS `Compartment` and `ModuleSource` under
+certain conditions:
+
+1. The application must be an XS script that was compiled with the `xs`
+  package condition.
+  This causes `ses`, `@endo/module-source`, and `@endo/import-bundle` to
+  provide slightly different implementations that can fall through to native
+  behavior.
+2. The application must opt-in with the `__native__: true` option on any
+  of the compartment mapper methods that import modules like `importLocation`
+  and `importArchive`.
+
 # Design
 
 Each of the workflows the compartment mapper executes a portion of one sequence

package/archive-lite.d.ts

@@ -1,2 +1,3 @@
+export * from "./src/types-external.js";
 export { makeArchiveFromMap, makeAndHashArchiveFromMap, writeArchiveFromMap, mapFromMap, hashFromMap } from "./src/archive-lite.js";
 //# sourceMappingURL=archive-lite.d.ts.map

package/archive-lite.js

@@ -1,3 +1,6 @@
+// eslint-disable-next-line import/export -- just types
+export * from './src/types-external.js';
+
 export {
   makeArchiveFromMap,
   makeAndHashArchiveFromMap,

package/archive-parsers.d.ts

@@ -1,2 +1,3 @@
+export * from "./src/types-external.js";
 export { defaultParserForLanguage } from "./src/archive-parsers.js";
 //# sourceMappingURL=archive-parsers.d.ts.map

package/archive-parsers.js

@@ -1 +1,4 @@
+// eslint-disable-next-line import/export -- just types
+export * from './src/types-external.js';
+
 export { defaultParserForLanguage } from './src/archive-parsers.js';

package/archive.d.ts

@@ -1,2 +1,3 @@
+export * from "./src/types-external.js";
 export { makeArchive, makeAndHashArchive, writeArchive, mapLocation, hashLocation } from "./src/archive.js";
 //# sourceMappingURL=archive.d.ts.map

package/archive.js

@@ -1,3 +1,6 @@
+// eslint-disable-next-line import/export -- just types
+export * from './src/types-external.js';
+
 export {
   makeArchive,
   makeAndHashArchive,

package/bundle.d.ts

@@ -1,2 +1,3 @@
+export * from "./src/types-external.js";
 export { makeBundle, writeBundle } from "./src/bundle.js";
 //# sourceMappingURL=bundle.d.ts.map

package/bundle.js

@@ -1 +1,4 @@
+// eslint-disable-next-line import/export -- just types
+export * from './src/types-external.js';
+
 export { makeBundle, writeBundle } from './src/bundle.js';

package/capture-lite.d.ts

@@ -1,2 +1,3 @@
+export * from "./src/types-external.js";
 export { captureFromMap } from "./src/capture-lite.js";
 //# sourceMappingURL=capture-lite.d.ts.map

package/capture-lite.js

@@ -1 +1,4 @@
+// eslint-disable-next-line import/export -- just types
+export * from './src/types-external.js';
+
 export { captureFromMap } from './src/capture-lite.js';

package/import-archive-all-parsers.d.ts

@@ -0,0 +1,2 @@
+export { defaultParserForLanguage } from "./src/import-archive-all-parsers.js";
+//# sourceMappingURL=import-archive-all-parsers.d.ts.map

package/import-archive-all-parsers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"import-archive-all-parsers.d.ts","sourceRoot":"","sources":["import-archive-all-parsers.js"],"names":[],"mappings":""}

package/import-archive-all-parsers.js

@@ -0,0 +1 @@
+export { defaultParserForLanguage } from './src/import-archive-all-parsers.js';

package/import-archive-lite.d.ts

@@ -1,2 +1,3 @@
+export * from "./src/types-external.js";
 export { parseArchive, loadArchive, importArchive } from "./src/import-archive-lite.js";
 //# sourceMappingURL=import-archive-lite.d.ts.map

package/import-archive-lite.js

@@ -1,3 +1,6 @@
+// eslint-disable-next-line import/export -- just types
+export * from './src/types-external.js';
+
 export {
   parseArchive,
   loadArchive,

package/import-archive-parsers.d.ts

@@ -1,2 +1,3 @@
+export * from "./src/types-external.js";
 export { defaultParserForLanguage } from "./src/import-archive-parsers.js";
 //# sourceMappingURL=import-archive-parsers.d.ts.map

package/import-archive-parsers.js

@@ -1 +1,4 @@
+// eslint-disable-next-line import/export -- just types
+export * from './src/types-external.js';
+
 export { defaultParserForLanguage } from './src/import-archive-parsers.js';

package/import-archive.d.ts

@@ -1,2 +1,3 @@
+export * from "./src/types-external.js";
 export { parseArchive, loadArchive, importArchive } from "./src/import-archive.js";
 //# sourceMappingURL=import-archive.d.ts.map

package/import-archive.js

@@ -1,3 +1,6 @@
+// eslint-disable-next-line import/export -- just types
+export * from './src/types-external.js';
+
 export {
   parseArchive,
   loadArchive,

package/import-lite.d.ts

@@ -1,2 +1,3 @@
+export * from "./src/types-external.js";
 export { loadFromMap, importFromMap } from "./src/import-lite.js";
 //# sourceMappingURL=import-lite.d.ts.map

package/import-lite.js

@@ -1 +1,4 @@
+// eslint-disable-next-line import/export -- just types
+export * from './src/types-external.js';
+
 export { loadFromMap, importFromMap } from './src/import-lite.js';

package/import-parsers.d.ts

@@ -1,2 +1,3 @@
+export * from "./src/types-external.js";
 export { defaultParserForLanguage } from "./src/import-parsers.js";
 //# sourceMappingURL=import-parsers.d.ts.map

package/import-parsers.js

@@ -1 +1,4 @@
+// eslint-disable-next-line import/export -- just types
+export * from './src/types-external.js';
+
 export { defaultParserForLanguage } from './src/import-parsers.js';

package/import.d.ts

@@ -1,2 +1,3 @@
+export * from "./src/types-external.js";
 export { loadLocation, importLocation } from "./src/import.js";
 //# sourceMappingURL=import.d.ts.map

package/import.js

@@ -1 +1,4 @@
+// eslint-disable-next-line import/export -- just types
+export * from './src/types-external.js';
+
 export { loadLocation, importLocation } from './src/import.js';

package/index.d.ts

@@ -1,3 +1,4 @@
+export * from "./src/types-external.js";
 export { search } from "./src/search.js";
 export { compartmentMapForNodeModules } from "./src/node-modules.js";
 export { loadLocation, importLocation } from "./src/import.js";

package/index.js

@@ -1,4 +1,6 @@
-// @ts-check
+// eslint-disable-next-line import/export -- just types
+export * from './src/types-external.js';
+
 export { loadLocation, importLocation } from './src/import.js';
 export {
   makeArchive,

package/node-modules.d.ts

@@ -1,2 +1,3 @@
+export * from "./src/types-external.js";
 export { mapNodeModules } from "./src/node-modules.js";
 //# sourceMappingURL=node-modules.d.ts.map

package/node-modules.js

@@ -1 +1,4 @@
+// eslint-disable-next-line import/export -- just types
+export * from './src/types-external.js';
+
 export { mapNodeModules } from './src/node-modules.js';

package/node-powers.d.ts

@@ -1,2 +1,3 @@
+export * from "./src/types-external.js";
 export { makeReadPowers, makeWritePowers, makeReadNowPowers, makeNodeReadPowers, makeNodeWritePowers } from "./src/node-powers.js";
 //# sourceMappingURL=node-powers.d.ts.map

package/node-powers.js

@@ -1,3 +1,6 @@
+// eslint-disable-next-line import/export -- just types
+export * from './src/types-external.js';
+
 export {
   makeReadPowers,
   makeWritePowers,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@endo/compartment-mapper",
-  "version": "1.3.1",
+  "version": "1.5.0",
   "description": "The compartment mapper assembles Node applications in a sandbox",
   "keywords": [
     "node",
@@ -21,12 +21,8 @@
   },
   "type": "module",
   "main": "./index.js",
-  "types": "./types.d.ts",
   "exports": {
-    ".": {
-      "types": "./types.d.ts",
-      "default": "./index.js"
-    },
+    ".": "./index.js",
     "./import.js": "./import.js",
     "./import-lite.js": "./import-lite.js",
     "./import-parsers.js": "./import-parsers.js",
@@ -36,7 +32,12 @@
     "./capture-lite.js": "./capture-lite.js",
     "./import-archive.js": "./import-archive.js",
     "./import-archive-lite.js": "./import-archive-lite.js",
-    "./import-archive-parsers.js": "./import-archive-parsers.js",
+    "./import-archive-parsers.js": {
+      "xs": "./import-archive-all-parsers.js",
+      "node": "./import-archive-all-parsers.js",
+      "default": "./import-archive-parsers.js"
+    },
+    "./import-archive-all-parsers.js": "./import-archive-all-parsers.js",
     "./bundle.js": "./bundle.js",
     "./node-powers.js": "./node-powers.js",
     "./node-modules.js": "./node-modules.js",
@@ -55,11 +56,11 @@
     "test": "ava"
   },
   "dependencies": {
-    "@endo/cjs-module-analyzer": "^1.0.8",
-    "@endo/module-source": "^1.1.1",
-    "@endo/trampoline": "^1.0.2",
-    "@endo/zip": "^1.0.8",
-    "ses": "^1.9.1"
+    "@endo/cjs-module-analyzer": "^1.0.9",
+    "@endo/module-source": "^1.2.0",
+    "@endo/trampoline": "^1.0.3",
+    "@endo/zip": "^1.0.9",
+    "ses": "^1.11.0"
   },
   "devDependencies": {
     "ava": "^6.1.3",
@@ -70,8 +71,8 @@
     "eslint-config-prettier": "^9.1.0",
     "eslint-plugin-eslint-comments": "^3.2.0",
     "eslint-plugin-import": "^2.29.1",
-    "prettier": "^3.2.5",
-    "typescript": "~5.6.2"
+    "prettier": "^3.3.3",
+    "typescript": "~5.6.3"
   },
   "files": [
     "./*.d.ts",
@@ -113,5 +114,5 @@
   "typeCoverage": {
     "atLeast": 86.14
   },
-  "gitHead": "c242c28a68d1af29475150e44b5f3e9d0feda8cd"
+  "gitHead": "e0683e0bfdbfc84351af332c9e78813d7b67ef89"
 }

package/src/archive-lite.d.ts

@@ -1,20 +1,18 @@
-export function makeArchiveCompartmentMap(compartmentMap: CompartmentMapDescriptor, sources: Sources): {
-    archiveCompartmentMap: CompartmentMapDescriptor;
-    archiveSources: Sources;
-};
-export function makeAndHashArchiveFromMap(powers: ReadFn | ReadPowers, compartmentMap: CompartmentMapDescriptor, options?: ArchiveOptions | undefined): Promise<{
+export function makeArchiveCompartmentMap(compartmentMap: CompartmentMapDescriptor, sources: Sources): ArchiveResult;
+export function makeAndHashArchiveFromMap(powers: ReadFn | ReadPowers, compartmentMap: CompartmentMapDescriptor, options?: ArchiveLiteOptions | undefined): Promise<{
     bytes: Uint8Array;
     sha512?: string;
 }>;
-export function makeArchiveFromMap(powers: ReadFn | ReadPowers, compartmentMap: CompartmentMapDescriptor, options?: ArchiveOptions | undefined): Promise<Uint8Array>;
-export function mapFromMap(powers: ReadFn | ReadPowers, compartmentMap: CompartmentMapDescriptor, options?: ArchiveOptions | undefined): Promise<Uint8Array>;
-export function hashFromMap(powers: HashPowers, compartmentMap: CompartmentMapDescriptor, options?: ArchiveOptions | undefined): Promise<string>;
-export function writeArchiveFromMap(write: WriteFn, readPowers: ReadFn | ReadPowers, archiveLocation: string, compartmentMap: CompartmentMapDescriptor, options?: ArchiveOptions | undefined): Promise<void>;
+export function makeArchiveFromMap(powers: ReadFn | ReadPowers, compartmentMap: CompartmentMapDescriptor, options?: ArchiveLiteOptions | undefined): Promise<Uint8Array>;
+export function mapFromMap(powers: ReadFn | ReadPowers, compartmentMap: CompartmentMapDescriptor, options?: ArchiveLiteOptions | undefined): Promise<Uint8Array>;
+export function hashFromMap(powers: HashPowers, compartmentMap: CompartmentMapDescriptor, options?: ArchiveLiteOptions | undefined): Promise<string>;
+export function writeArchiveFromMap(write: WriteFn, readPowers: ReadFn | ReadPowers, archiveLocation: string, compartmentMap: CompartmentMapDescriptor, options?: ArchiveLiteOptions | undefined): Promise<void>;
 import type { CompartmentMapDescriptor } from './types.js';
 import type { Sources } from './types.js';
+import type { ArchiveResult } from './types.js';
 import type { ReadFn } from './types.js';
 import type { ReadPowers } from './types.js';
-import type { ArchiveOptions } from './types.js';
+import type { ArchiveLiteOptions } from './types.js';
 import type { HashPowers } from './types.js';
 import type { WriteFn } from './types.js';
 //# sourceMappingURL=archive-lite.d.ts.map

package/src/archive-lite.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"archive-lite.d.ts","sourceRoot":"","sources":["archive-lite.js"],"names":[],"mappings":"AA2QO,0DAJI,wBAAwB,WACxB,OAAO,GACL;IAAC,qBAAqB,EAAE,wBAAwB,CAAC;IAAC,cAAc,EAAE,OAAO,CAAA;CAAC,CAmCtF;AA6GM,kDALI,MAAM,GAAG,UAAU,kBACnB,wBAAwB,yCAEtB,OAAO,CAAC;IAAC,KAAK,EAAE,UAAU,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAC,CAAC,CAmBzD;AAQM,2CALI,MAAM,GAAG,UAAU,kBACnB,wBAAwB,yCAEtB,OAAO,CAAC,UAAU,CAAC,CAS/B;AAQM,mCALI,MAAM,GAAG,UAAU,kBACnB,wBAAwB,yCAEtB,OAAO,CAAC,UAAU,CAAC,CAS/B;AAQM,oCALI,UAAU,kBACV,wBAAwB,yCAEtB,OAAO,CAAC,MAAM,CAAC,CAU3B;AASM,2CANI,OAAO,cACP,MAAM,GAAG,UAAU,mBACnB,MAAM,kBACN,wBAAwB,uDAgBlC;8CA1c2C,YAAY;6BAM7B,YAAY;4BAJb,YAAY;gCAER,YAAY;oCAPR,YAAY;gCAQhB,YAAY;6BAEf,YAAY"}
+{"version":3,"file":"archive-lite.d.ts","sourceRoot":"","sources":["archive-lite.js"],"names":[],"mappings":"AAmHO,0DAJI,wBAAwB,WACxB,OAAO,GACL,aAAa,CAiBzB;AAyGM,kDALI,MAAM,GAAG,UAAU,kBACnB,wBAAwB,6CAEtB,OAAO,CAAC;IAAC,KAAK,EAAE,UAAU,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAC,CAAC,CAmBzD;AAQM,2CALI,MAAM,GAAG,UAAU,kBACnB,wBAAwB,6CAEtB,OAAO,CAAC,UAAU,CAAC,CAS/B;AAQM,mCALI,MAAM,GAAG,UAAU,kBACnB,wBAAwB,6CAEtB,OAAO,CAAC,UAAU,CAAC,CAS/B;AAQM,oCALI,UAAU,kBACV,wBAAwB,6CAEtB,OAAO,CAAC,MAAM,CAAC,CAU3B;AASM,2CANI,OAAO,cACP,MAAM,GAAG,UAAU,mBACnB,MAAM,kBACN,wBAAwB,2DAgBlC;8CApRS,YAAY;6BAAZ,YAAY;mCAAZ,YAAY;4BAAZ,YAAY;gCAAZ,YAAY;wCAAZ,YAAY;gCAAZ,YAAY;6BAAZ,YAAY"}