@endo/compartment-mapper 1.0.0 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@endo/compartment-mapper",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "The compartment mapper assembles Node applications in a sandbox",
   "keywords": [
     "node",
@@ -38,18 +38,18 @@
     "build:types": "tsc --build tsconfig.build.json",
     "clean:types": "git clean -f '*.d.ts*'",
     "cover": "c8 ava",
-    "lint": "yarn lint:types && yarn lint:js",
+    "lint": "yarn lint:types && yarn lint:eslint",
     "lint-fix": "eslint --fix .",
-    "lint:js": "eslint .",
+    "lint:eslint": "eslint .",
     "lint:types": "tsc",
     "prettier-fixtures": "prettier --write --with-node-modules './test/fixtures-*/**/*.*js'",
     "test": "ava"
   },
   "dependencies": {
-    "@endo/cjs-module-analyzer": "^1.0.0",
-    "@endo/static-module-record": "^1.0.0",
-    "@endo/zip": "^1.0.0",
-    "ses": "^1.0.0"
+    "@endo/cjs-module-analyzer": "^1.0.1",
+    "@endo/static-module-record": "^1.0.2",
+    "@endo/zip": "^1.0.1",
+    "ses": "^1.1.0"
   },
   "devDependencies": {
     "ava": "^5.3.0",
@@ -61,7 +61,7 @@
     "eslint-plugin-eslint-comments": "^3.1.2",
     "eslint-plugin-import": "^2.29.0",
     "prettier": "^3.0.0",
-    "typescript": "~5.2.2"
+    "typescript": "~5.3.3"
   },
   "files": [
     "LICENSE*",
@@ -97,7 +97,7 @@
     "timeout": "2m"
   },
   "typeCoverage": {
-    "atLeast": 85.78
+    "atLeast": 86.14
   },
-  "gitHead": "6aa22009bf8128575c446aebceb0f9a01459d165"
+  "gitHead": "373f9eebab66c94ed42350473c90fb25e6054f0a"
 }

package/src/bundle-cjs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bundle-cjs.d.ts","sourceRoot":"","sources":["bundle-cjs.js"],"names":[],"mappings":";;IA+CE;;;;;;;;;;;;MAsBC;;;AArDH,8BA2Ba"}
+{"version":3,"file":"bundle-cjs.d.ts","sourceRoot":"","sources":["bundle-cjs.js"],"names":[],"mappings":";;IAuDE;;;;;;;;;;;;MAsBC;;;AA7DH,8BAmCa"}

package/src/bundle-cjs.js

@@ -34,7 +34,15 @@ const runtime = function wrapCjsFunctor(num) {
       .filter(k => moduleCells[k] === undefined)
       .map(k => (moduleCells[k] = cell(k, cModule.exports[k])));
     // Update the star cell from all cells.
-    const starExports = Object.create(null);
+    const starExports = Object.create(null, {
+      // Make this appear like an ESM module namespace object.
+      [Symbol.toStringTag]: {
+        value: 'Module',
+        writable: false,
+        enumerable: false,
+        configurable: false,
+      },
+    });
     Object.keys(moduleCells)
       .filter(k => k !== '*')
       .map(k => Object.defineProperty(starExports, k, moduleCells[k]));

package/src/bundle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bundle.d.ts","sourceRoot":"","sources":["bundle.js"],"names":[],"mappings":"AA4KO,iCAXI,MAAM,kBACN,MAAM;;;;yBAKN,MAAM;;;gBAGJ,QAAQ,MAAM,CAAC,CAqJ3B;AASM,mCANI,OAAO,QACP,MAAM,kBACN,MAAM,kBACN,MAAM,4EAahB;0BA/Ua,OAAO,KAAK,EAAE,WAAW;+CACzB,OAAO,KAAK,EAAE,gCAAgC;mCAC9C,OAAO,YAAY,EAAE,oBAAoB;oCACzC,OAAO,YAAY,EAAE,qBAAqB;iCAC1C,OAAO,YAAY,EAAE,kBAAkB;qBACvC,OAAO,YAAY,EAAE,MAAM;+BAC3B,OAAO,YAAY,EAAE,gBAAgB;sBACrC,OAAO,YAAY,EAAE,OAAO;sBAC5B,OAAO,YAAY,EAAE,OAAO;6BAC5B,OAAO,YAAY,EAAE,cAAc"}
+{"version":3,"file":"bundle.d.ts","sourceRoot":"","sources":["bundle.js"],"names":[],"mappings":"AA4KO,iCAXI,MAAM,kBACN,MAAM;;;;yBAKN,MAAM;;;gBAGJ,QAAQ,MAAM,CAAC,CA8J3B;AASM,mCANI,OAAO,QACP,MAAM,kBACN,MAAM,kBACN,MAAM,4EAahB;0BAxVa,OAAO,KAAK,EAAE,WAAW;+CACzB,OAAO,KAAK,EAAE,gCAAgC;mCAC9C,OAAO,YAAY,EAAE,oBAAoB;oCACzC,OAAO,YAAY,EAAE,qBAAqB;iCAC1C,OAAO,YAAY,EAAE,kBAAkB;qBACvC,OAAO,YAAY,EAAE,MAAM;+BAC3B,OAAO,YAAY,EAAE,gBAAgB;sBACrC,OAAO,YAAY,EAAE,OAAO;sBAC5B,OAAO,YAAY,EAAE,OAAO;6BAC5B,OAAO,YAAY,EAAE,cAAc"}

package/src/bundle.js

@@ -302,7 +302,16 @@ ${''.concat(...modules.map(m => m.bundlerKit.getCells()))}\
 
 ${''.concat(...modules.map(m => m.bundlerKit.getReexportsWiring()))}\
 
-  const namespaces = cells.map(cells => Object.freeze(Object.create(null, cells)));
+const namespaces = cells.map(cells => Object.freeze(Object.create(null, {
+    ...cells,
+    // Make this appear like an ESM module namespace object.
+    [Symbol.toStringTag]: {
+      value: 'Module',
+      writable: false,
+      enumerable: false,
+      configurable: false,
+    },
+  })));
 
   for (let index = 0; index < namespaces.length; index += 1) {
     cells[index]['*'] = cell('*', namespaces[index]);

package/src/import.d.ts

@@ -1,7 +1,7 @@
 /** @type {Record<string, ParserImplementation>} */
 export const parserForLanguage: Record<string, ParserImplementation>;
 export function loadLocation(readPowers: ReadFn | ReadPowers, moduleLocation: string, options?: import("./types.js").ArchiveOptions | undefined): Promise<Application>;
-export function importLocation(readPowers: ReadFn | ReadPowers, moduleLocation: string, options?: (import("./types.js").ExecuteOptions & import("./types.js").ArchiveOptions) | undefined): Promise<object>;
+export function importLocation(readPowers: ReadFn | ReadPowers, moduleLocation: string, options?: (import("./types.js").ExecuteOptions & import("./types.js").ArchiveOptions) | undefined): Promise<import('./types.js').SomeObject>;
 export type Application = import('./types.js').Application;
 export type ArchiveOptions = import('./types.js').ArchiveOptions;
 export type ExecuteFn = import('./types.js').ExecuteFn;

package/src/import.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"import.d.ts","sourceRoot":"","sources":["import.js"],"names":[],"mappings":"AA0BA,mDAAmD;AACnD,gCADW,OAAO,MAAM,EAAE,oBAAoB,CAAC,CAO7C;AAQK,yCALI,MAAM,GAAG,UAAU,kBACnB,MAAM,8DAEJ,QAAQ,WAAW,CAAC,CAwEhC;AASM,2CANI,MAAM,GAAG,UAAU,kBACnB,MAAM,sGAEJ,QAAQ,MAAM,CAAC,CAU3B;0BA5Ha,OAAO,YAAY,EAAE,WAAW;6BAChC,OAAO,YAAY,EAAE,cAAc;wBACnC,OAAO,YAAY,EAAE,SAAS;6BAC9B,OAAO,YAAY,EAAE,cAAc;mCACnC,OAAO,YAAY,EAAE,oBAAoB;qBACzC,OAAO,YAAY,EAAE,MAAM;yBAC3B,OAAO,YAAY,EAAE,UAAU"}
+{"version":3,"file":"import.d.ts","sourceRoot":"","sources":["import.js"],"names":[],"mappings":"AA0BA,mDAAmD;AACnD,gCADW,OAAO,MAAM,EAAE,oBAAoB,CAAC,CAO7C;AAQK,yCALI,MAAM,GAAG,UAAU,kBACnB,MAAM,8DAEJ,QAAQ,WAAW,CAAC,CAwEhC;AASM,2CANI,MAAM,GAAG,UAAU,kBACnB,MAAM,sGAEJ,QAAQ,OAAO,YAAY,EAAE,UAAU,CAAC,CAUpD;0BA5Ha,OAAO,YAAY,EAAE,WAAW;6BAChC,OAAO,YAAY,EAAE,cAAc;wBACnC,OAAO,YAAY,EAAE,SAAS;6BAC9B,OAAO,YAAY,EAAE,cAAc;mCACnC,OAAO,YAAY,EAAE,oBAAoB;qBACzC,OAAO,YAAY,EAAE,MAAM;yBAC3B,OAAO,YAAY,EAAE,UAAU"}

package/src/import.js

@@ -115,7 +115,7 @@ export const loadLocation = async (readPowers, moduleLocation, options) => {
  * @param {ReadFn | ReadPowers} readPowers
  * @param {string} moduleLocation
  * @param {ExecuteOptions & ArchiveOptions} [options]
- * @returns {Promise<object>} the object of the imported modules exported
+ * @returns {Promise<import('./types.js').SomeObject>} the object of the imported modules exported
  * names.
  */
 export const importLocation = async (

package/src/link.d.ts

@@ -18,5 +18,5 @@ export type CompartmentDescriptor = import('./types.js').CompartmentDescriptor;
 export type CompartmentMapDescriptor = import('./types.js').CompartmentMapDescriptor;
 export type DeferredAttenuatorsProvider = import('./types.js').DeferredAttenuatorsProvider;
 export type LinkOptions = import('./types.js').LinkOptions;
-export type ERef<T_1> = any;
+export type ERef<T_1> = import('@endo/eventual-send').ERef<T>;
 //# sourceMappingURL=link.d.ts.map

package/src/link.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"link.d.ts","sourceRoot":"","sources":["link.js"],"names":[],"mappings":"AA+IO,iDAPI,OAAO,MAAM,EAAE,QAAQ,CAAC,8BACxB,OAAO,MAAM,EAAE,MAAM,CAAC,qBAEtB,OAAO,MAAM,EAAE,oBAAoB,CAAC,qBACpC,gBAAgB,GACd,OAAO,CA0BnB;AAmKM,sEAHI,wBAAwB,wIACxB,WAAW;;;;;EA0IrB;AAMM,yCAHI,wBAAwB,WACxB,WAAW,eAGqB;4BAvd7B,OAAO,KAAK,EAAE,aAAa;0BAC3B,OAAO,KAAK,EAAE,WAAW;sBACzB,OAAO,YAAY,EAAE,OAAO;mCAC5B,OAAO,YAAY,EAAE,oBAAoB;+BACzC,OAAO,YAAY,EAAE,gBAAgB;+BACrC,OAAO,YAAY,EAAE,gBAAgB;uBACrC,OAAO,YAAY,EAAE,QAAQ;+BAC7B,OAAO,YAAY,EAAE,gBAAgB;oCACrC,OAAO,YAAY,EAAE,qBAAqB;uCAC1C,OAAO,YAAY,EAAE,wBAAwB;0CAC7C,OAAO,YAAY,EAAE,2BAA2B;0BAChD,OAAO,YAAY,EAAE,WAAW"}
+{"version":3,"file":"link.d.ts","sourceRoot":"","sources":["link.js"],"names":[],"mappings":"AA+IO,iDAPI,OAAO,MAAM,EAAE,QAAQ,CAAC,8BACxB,OAAO,MAAM,EAAE,MAAM,CAAC,qBAEtB,OAAO,MAAM,EAAE,oBAAoB,CAAC,qBACpC,gBAAgB,GACd,OAAO,CA0BnB;AAmKM,sEAHI,wBAAwB,wIACxB,WAAW;;;;;EA0IrB;AAMM,yCAHI,wBAAwB,WACxB,WAAW,eAGqB;4BAvd7B,OAAO,KAAK,EAAE,aAAa;0BAC3B,OAAO,KAAK,EAAE,WAAW;sBACzB,OAAO,YAAY,EAAE,OAAO;mCAC5B,OAAO,YAAY,EAAE,oBAAoB;+BACzC,OAAO,YAAY,EAAE,gBAAgB;+BACrC,OAAO,YAAY,EAAE,gBAAgB;uBACrC,OAAO,YAAY,EAAE,QAAQ;+BAC7B,OAAO,YAAY,EAAE,gBAAgB;oCACrC,OAAO,YAAY,EAAE,qBAAqB;uCAC1C,OAAO,YAAY,EAAE,wBAAwB;0CAC7C,OAAO,YAAY,EAAE,2BAA2B;0BAChD,OAAO,YAAY,EAAE,WAAW;wBACpB,OAAO,qBAAqB,EAAE,IAAI,CAAC,CAAC,CAAC"}

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

@@ -1 +1 @@
-{"version":3,"file":"node-modules.d.ts","sourceRoot":"","sources":["node-modules.js"],"names":[],"mappings":"AAisBO,yDAXI,MAAM,GAAG,UAAU,GAAG,eAAe,mBACrC,MAAM,QACN,IAAI,MAAM,CAAC,qBACX,MAAM,mBACN,MAAM;;yBAGN,MAAM;aACN,MAAM;gBACJ,QAAQ,wBAAwB,CAAC,CA+C7C;uBA3uBa,OAAO,YAAY,EAAE,QAAQ;qBAC7B,OAAO,YAAY,EAAE,MAAM;0BAC3B,OAAO,YAAY,EAAE,WAAW;0BAChC,OAAO,YAAY,EAAE,WAAW;uCAChC,OAAO,YAAY,EAAE,wBAAwB;+BAC7C,OAAO,YAAY,EAAE,gBAAgB;8BACrC,OAAO,YAAY,EAAE,eAAe;oCACpC,OAAO,YAAY,EAAE,qBAAqB;yBAC1C,OAAO,YAAY,EAAE,UAAU;8BAC/B,OAAO,YAAY,EAAE,eAAe;;;;;;;oBAQrC,OAAO,MAAM,EAAE,IAAI,CAAC;;WAKnB,MAAM;UACN,MAAM;UACN,MAAM,MAAM,CAAC;iBACb,MAAM,MAAM,CAAC;qBACb,OAAO;qBACP,OAAO,MAAM,EAAE,MAAM,CAAC;qBACtB,OAAO,MAAM,EAAE,MAAM,CAAC;;;;;yBACtB,OAAO,MAAM,EAAE,MAAM,CAAC;;;;;aAEtB,OAAO,MAAM,EAAE,QAAQ,CAAC;;;;;WAExB,OAAO,MAAM,EAAE,QAAQ,CAAC;;0CAKzB,OAAO,MAAM,EAAE;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAC,CAAC;iDA+E/C,MAAM,KACJ,QAAQ,MAAM,CAAC"}
+{"version":3,"file":"node-modules.d.ts","sourceRoot":"","sources":["node-modules.js"],"names":[],"mappings":"AAwsBO,yDAXI,MAAM,GAAG,UAAU,GAAG,eAAe,mBACrC,MAAM,QACN,IAAI,MAAM,CAAC,qBACX,MAAM,mBACN,MAAM;;yBAGN,MAAM;aACN,MAAM;gBACJ,QAAQ,wBAAwB,CAAC,CA+C7C;uBAlvBa,OAAO,YAAY,EAAE,QAAQ;qBAC7B,OAAO,YAAY,EAAE,MAAM;0BAC3B,OAAO,YAAY,EAAE,WAAW;0BAChC,OAAO,YAAY,EAAE,WAAW;uCAChC,OAAO,YAAY,EAAE,wBAAwB;+BAC7C,OAAO,YAAY,EAAE,gBAAgB;8BACrC,OAAO,YAAY,EAAE,eAAe;oCACpC,OAAO,YAAY,EAAE,qBAAqB;yBAC1C,OAAO,YAAY,EAAE,UAAU;8BAC/B,OAAO,YAAY,EAAE,eAAe;;;;;;;oBAQrC,OAAO,MAAM,EAAE,IAAI,CAAC;;WAKnB,MAAM;UACN,MAAM;UACN,MAAM,MAAM,CAAC;iBACb,MAAM,MAAM,CAAC;qBACb,OAAO;qBACP,OAAO,MAAM,EAAE,MAAM,CAAC;qBACtB,OAAO,MAAM,EAAE,MAAM,CAAC;;;;;yBACtB,OAAO,MAAM,EAAE,MAAM,CAAC;;;;;aAEtB,OAAO,MAAM,EAAE,QAAQ,CAAC;;;;;WAExB,OAAO,MAAM,EAAE,QAAQ,CAAC;;0CAKzB,OAAO,MAAM,EAAE;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAC,CAAC;iDA+E/C,MAAM,KACJ,QAAQ,MAAM,CAAC"}

package/src/node-modules.js

@@ -42,18 +42,18 @@
  * @typedef {Record<string, {spec: string, alias: string}>} CommonDependencyDescriptors
  */
 
+import { pathCompare } from './compartment-map.js';
 import { inferExportsAndAliases } from './infer-exports.js';
-import { searchDescriptor } from './search.js';
 import { parseLocatedJson } from './json.js';
-import { unpackReadPowers } from './powers.js';
+import { join } from './node-module-specifier.js';
+import { assertPolicy } from './policy-format.js';
 import {
-  getPolicyForPackage,
   ATTENUATORS_COMPARTMENT,
   dependencyAllowedByPolicy,
+  getPolicyForPackage,
 } from './policy.js';
-import { join } from './node-module-specifier.js';
-import { pathCompare } from './compartment-map.js';
-import { assertPolicy } from './policy-format.js';
+import { unpackReadPowers } from './powers.js';
+import { searchDescriptor } from './search.js';
 
 const { assign, create, keys, values } = Object;
 
@@ -566,7 +566,7 @@ const graphPackages = async (
  * @param {Graph} graph
  * @param {Set<string>} tags - build tags about the target environment
  * for selecting relevant exports, e.g., "browser" or "node".
- * @param {object|undefined} policy
+ * @param {import('./types.js').Policy} [policy]
  * @returns {CompartmentMapDescriptor}
  */
 const translateGraph = (
@@ -612,6 +612,12 @@ const translateGraph = (
       policy,
     );
 
+    /* c8 ignore next */
+    if (policy && !packagePolicy) {
+      // this should never happen
+      throw new TypeError('Unexpectedly falsy package policy');
+    }
+
     /**
      * @param {string} dependencyName
      * @param {string} packageLocation
@@ -626,13 +632,14 @@ const translateGraph = (
         const localPath = join(dependencyName, exportPath);
         if (
           !policy ||
-          dependencyAllowedByPolicy(
-            {
-              name,
-              path,
-            },
-            packagePolicy,
-          )
+          (packagePolicy &&
+            dependencyAllowedByPolicy(
+              {
+                name,
+                path,
+              },
+              packagePolicy,
+            ))
         ) {
           moduleDescriptors[localPath] = {
             compartment: packageLocation,

package/src/policy-format.d.ts

@@ -1,9 +1,7 @@
-export function policyLookupHelper(packagePolicy: object, field: string, itemName: string): boolean | object;
-export function isAllowingEverything(policyValue: any): boolean;
-export function isAttenuationDefinition(potentialDefinition: AttenuationDefinition): boolean;
-export function getAttenuatorFromDefinition(attenuationDefinition: AttenuationDefinition): UnifiedAttenuationDefinition;
-export function assertPackagePolicy(allegedPackagePolicy: unknown, path: string, url?: string | undefined): void;
-export function assertPolicy(allegedPolicy: unknown): void;
-export type AttenuationDefinition = import('./types.js').AttenuationDefinition;
-export type UnifiedAttenuationDefinition = import('./types.js').UnifiedAttenuationDefinition;
+export function policyLookupHelper(packagePolicy: import('./types.js').PackagePolicy, field: 'builtins' | 'globals' | 'packages', itemName: string): boolean | import('./types.js').AttenuationDefinition;
+export function isAllowingEverything(policyValue: unknown): policyValue is "any";
+export function isAttenuationDefinition(allegedDefinition: unknown): allegedDefinition is import("./types.js").AttenuationDefinition;
+export function getAttenuatorFromDefinition(attenuationDefinition: import('./types.js').AttenuationDefinition): import('./types.js').UnifiedAttenuationDefinition;
+export function assertPackagePolicy(allegedPackagePolicy: unknown, path: string, url?: string | undefined): asserts allegedPackagePolicy is import("./types.js").PackagePolicy<void, void, void> | undefined;
+export function assertPolicy(allegedPolicy: unknown): asserts allegedPolicy is import("./types.js").Policy<void, void, void> | undefined;
 //# sourceMappingURL=policy-format.d.ts.map

package/src/policy-format.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"policy-format.d.ts","sourceRoot":"","sources":["policy-format.js"],"names":[],"mappings":"AAqBO,kDALI,MAAM,SACN,MAAM,YACN,MAAM,GACJ,OAAO,GAAG,MAAM,CAqB5B;AAQM,kDAHI,GAAG,GACD,OAAO,CAGmB;AAOhC,6DAHI,qBAAqB,GACnB,OAAO,CAQnB;AAOM,mEAHI,qBAAqB,GACnB,4BAA4B,CAuBxC;AAyBM,0DALI,OAAO,QACP,MAAM,6BAEJ,IAAI,CA0DhB;AAOM,4CAHI,OAAO,GACL,IAAI,CAgChB;oCA9Ma,OAAO,YAAY,EAAE,qBAAqB;2CAC1C,OAAO,YAAY,EAAE,4BAA4B"}
+{"version":3,"file":"policy-format.d.ts","sourceRoot":"","sources":["policy-format.js"],"names":[],"mappings":"AAsBO,kDALI,OAAO,YAAY,EAAE,aAAa,SAClC,UAAU,GAAC,SAAS,GAAC,UAAU,YAC/B,MAAM,GACJ,OAAO,GAAG,OAAO,YAAY,EAAE,qBAAqB,CAyBhE;AAQM,kDAHI,OAAO,wBAIqB;AAOhC,2DAHI,OAAO,mEAUjB;AAOM,mEAHI,OAAO,YAAY,EAAE,qBAAqB,GACxC,OAAO,YAAY,EAAE,4BAA4B,CAuB7D;AA0CM,0DALI,OAAO,QACP,MAAM,8HA4DhB;AAUM,4CAHI,OAAO,sFAiCjB"}

package/src/policy-format.js

@@ -1,8 +1,5 @@
 // @ts-check
 
-/** @typedef {import('./types.js').AttenuationDefinition} AttenuationDefinition */
-/** @typedef {import('./types.js').UnifiedAttenuationDefinition} UnifiedAttenuationDefinition */
-
 const { entries, keys } = Object;
 const { isArray } = Array;
 const q = JSON.stringify;
@@ -10,14 +7,18 @@ const q = JSON.stringify;
 const ATTENUATOR_KEY = 'attenuate';
 const ATTENUATOR_PARAMS_KEY = 'params';
 const WILDCARD_POLICY_VALUE = 'any';
-const POLICY_FIELDS_LOOKUP = ['builtins', 'globals', 'packages'];
+const POLICY_FIELDS_LOOKUP = /** @type {const} */ ([
+  'builtins',
+  'globals',
+  'packages',
+]);
 
 /**
  *
- * @param {object} packagePolicy
- * @param {string} field
+ * @param {import('./types.js').PackagePolicy} packagePolicy
+ * @param {'builtins'|'globals'|'packages'} field
  * @param {string} itemName
- * @returns {boolean | object}
+ * @returns {boolean | import('./types.js').AttenuationDefinition}
  */
 export const policyLookupHelper = (packagePolicy, field, itemName) => {
   if (!POLICY_FIELDS_LOOKUP.includes(field)) {
@@ -34,38 +35,43 @@ export const policyLookupHelper = (packagePolicy, field, itemName) => {
   if (packagePolicy[field] === WILDCARD_POLICY_VALUE) {
     return true;
   }
-  if (packagePolicy[field][itemName]) {
-    return packagePolicy[field][itemName];
+
+  const value = /** @type {import('./types.js').AttenuationDefinition} */ (
+    packagePolicy[field]
+  );
+  if (itemName in value) {
+    return value[itemName];
   }
   return false;
 };
 
 /**
- * Checks if the policy value is set to wildcard to allow everything
+ * Type guard; checks if the policy value is set to the wildcard value to allow everything
  *
- * @param {any} policyValue
- * @returns {boolean}
+ * @param {unknown} policyValue
+ * @returns {policyValue is import('./types.js').WildcardPolicy}
  */
 export const isAllowingEverything = policyValue =>
   policyValue === WILDCARD_POLICY_VALUE;
 
 /**
- *
- * @param {AttenuationDefinition} potentialDefinition
- * @returns {boolean}
+ * Type guard for `AttenuationDefinition`
+ * @param {unknown} allegedDefinition
+ * @returns {allegedDefinition is import('./types.js').AttenuationDefinition}
  */
-export const isAttenuationDefinition = potentialDefinition => {
-  return (
-    (typeof potentialDefinition === 'object' &&
-      typeof potentialDefinition[ATTENUATOR_KEY] === 'string') || // object with attenuator name
-    isArray(potentialDefinition) // params for default attenuator
+export const isAttenuationDefinition = allegedDefinition => {
+  return Boolean(
+    (allegedDefinition &&
+      typeof allegedDefinition === 'object' &&
+      typeof allegedDefinition[ATTENUATOR_KEY] === 'string') || // object with attenuator name
+      isArray(allegedDefinition), // params for default attenuator
   );
 };
 
 /**
  *
- * @param {AttenuationDefinition} attenuationDefinition
- * @returns {UnifiedAttenuationDefinition}
+ * @param {import('./types.js').AttenuationDefinition} attenuationDefinition
+ * @returns {import('./types.js').UnifiedAttenuationDefinition}
  */
 export const getAttenuatorFromDefinition = attenuationDefinition => {
   if (!isAttenuationDefinition(attenuationDefinition)) {
@@ -90,28 +96,45 @@ export const getAttenuatorFromDefinition = attenuationDefinition => {
   }
 };
 
+// TODO: should be a type guard
 const isRecordOf = (item, predicate) => {
   if (typeof item !== 'object' || item === null || isArray(item)) {
     return false;
   }
   return entries(item).every(([key, value]) => predicate(value, key));
 };
+
+/**
+ * Type guard for `boolean`
+ * @param {unknown} item
+ * @returns {item is boolean}
+ */
 const isBoolean = item => typeof item === 'boolean';
+
+// TODO: should be a type guard
 const predicateOr =
   (...predicates) =>
   item =>
     predicates.some(p => p(item));
+
+/**
+ * @param {unknown} item
+ * @returns {item is import('./types.js').PolicyItem}
+ */
 const isPolicyItem = item =>
   item === undefined ||
   item === WILDCARD_POLICY_VALUE ||
   isRecordOf(item, isBoolean);
 
 /**
+ * This asserts (i.e., throws) that `allegedPackagePolicy` is a valid `PackagePolicy`.
+ *
+ * Mild-mannered during the day, but fights crime at night as a type guard.
  *
- * @param {unknown} allegedPackagePolicy
- * @param {string} path
- * @param {string} [url]
- * @returns {void}
+ * @param {unknown} allegedPackagePolicy - Alleged `PackagePolicy` to test
+ * @param {string} path - Path in the `Policy` object; used for error messages only
+ * @param {string} [url] - URL of the policy file; used for error messages only
+ * @returns {asserts allegedPackagePolicy is import('./types.js').PackagePolicy|undefined}
  */
 export const assertPackagePolicy = (allegedPackagePolicy, path, url) => {
   if (allegedPackagePolicy === undefined) {
@@ -172,9 +195,12 @@ export const assertPackagePolicy = (allegedPackagePolicy, path, url) => {
 };
 
 /**
+ * This asserts (i.e., throws) that `allegedPolicy` is a valid `Policy`
+ *
+ * It also moonlights as a type guard.
  *
- * @param {unknown} allegedPolicy
- * @returns {void}
+ * @param {unknown} allegedPolicy - Alleged `Policy` to test
+ * @returns {asserts allegedPolicy is import('./types.js').Policy|undefined}
  */
 export const assertPolicy = allegedPolicy => {
   if (allegedPolicy === undefined) {

package/src/policy.d.ts

@@ -2,19 +2,24 @@
  * Const string to identify the internal attenuators compartment
  */
 export const ATTENUATORS_COMPARTMENT: "<ATTENUATORS>";
-export function detectAttenuators(policy: object): Array<string>;
-export function dependencyAllowedByPolicy(namingKit: PackageNamingKit, packagePolicy: any): boolean;
-export function getPolicyForPackage(namingKit: PackageNamingKit, policy: object | undefined): object | undefined;
-export function makeDeferredAttenuatorsProvider(compartments: Record<string, Compartment>, compartmentDescriptors: Record<string, CompartmentDescriptor>): DeferredAttenuatorsProvider;
-export function attenuateGlobals(globalThis: object, globals: object, packagePolicy: object, attenuators: DeferredAttenuatorsProvider, pendingJobs: Array<Promise<any>>, name?: string): void;
-export function enforceModulePolicy(specifier: string, compartmentDescriptor: import('./types.js').CompartmentDescriptor, info?: object): void;
-export function attenuateModuleHook(specifier: string, originalModuleRecord: ThirdPartyStaticModuleInterface, policy: object, attenuators: DeferredAttenuatorsProvider): Promise<ThirdPartyStaticModuleInterface>;
-export type PackageNamingKit = import('./types.js').PackageNamingKit;
-export type AttenuationDefinition = import('./types.js').AttenuationDefinition;
-export type FullAttenuationDefinition = import('./types.js').FullAttenuationDefinition;
-export type ImplicitAttenuationDefinition = import('./types.js').ImplicitAttenuationDefinition;
-export type Attenuator = import('./types.js').Attenuator;
-export type DeferredAttenuatorsProvider = import('./types.js').DeferredAttenuatorsProvider;
-export type CompartmentDescriptor = import('./types.js').CompartmentDescriptor;
-export type ThirdPartyStaticModuleInterface = import('ses').ThirdPartyStaticModuleInterface;
+export function detectAttenuators(policy?: import("./types.js").Policy<void, void, void> | undefined): Array<string>;
+export function dependencyAllowedByPolicy(namingKit: import('./types.js').PackageNamingKit, packagePolicy: import('./types.js').PackagePolicy): boolean;
+export function getPolicyForPackage(namingKit: import('./types.js').PackageNamingKit, policy?: import("./types.js").Policy<void, void, void> | undefined): any;
+export function makeDeferredAttenuatorsProvider(compartments: Record<string, Compartment>, compartmentDescriptors: Record<string, import('./types.js').CompartmentDescriptor>): import('./types.js').DeferredAttenuatorsProvider;
+export function attenuateGlobals(globalThis: object, globals: object, packagePolicy: import('./types.js').PackagePolicy, attenuators: import('./types.js').DeferredAttenuatorsProvider, pendingJobs: Array<Promise<any>>, name?: string): void;
+export function enforceModulePolicy(specifier: string, compartmentDescriptor: import('./types.js').CompartmentDescriptor, { exit, errorHint }?: EnforceModulePolicyOptions | undefined): void;
+export function attenuateModuleHook(specifier: string, originalModuleRecord: import('ses').ThirdPartyStaticModuleInterface, policy: import('./types.js').PackagePolicy, attenuators: import('./types.js').DeferredAttenuatorsProvider): Promise<import('ses').ThirdPartyStaticModuleInterface>;
+/**
+ * Options for {@link enforceModulePolicy }
+ */
+export type EnforceModulePolicyOptions = {
+    /**
+     * - Whether it is an exit module
+     */
+    exit?: boolean | undefined;
+    /**
+     * - Error hint message
+     */
+    errorHint?: string | undefined;
+};
 //# sourceMappingURL=policy.d.ts.map

package/src/policy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["policy.js"],"names":[],"mappings":"AAsBA;;GAEG;AACH,sDAAuD;AA0ChD,0CAHI,MAAM,GACJ,MAAM,MAAM,CAAC,CAezB;AA0BM,qDAJI,gBAAgB,iBAChB,GAAG,GACD,OAAO,CASnB;AASM,+CAJI,gBAAgB,UAChB,MAAM,GAAC,SAAS,GACd,MAAM,GAAC,SAAS,CAsB5B;AAgDM,8DAJI,OAAO,MAAM,EAAE,WAAW,CAAC,0BAC3B,OAAO,MAAM,EAAE,qBAAqB,CAAC,GACnC,2BAA2B,CA2CvC;AAmDM,6CARI,MAAM,WACN,MAAM,iBACN,MAAM,eACN,2BAA2B,eAC3B,mBAAc,SACd,MAAM,GACJ,IAAI,CAgDhB;AAeM,+CAJI,MAAM,yBACN,OAAO,YAAY,EAAE,qBAAqB,SAC1C,MAAM,QAgChB;AA+CM,+CANI,MAAM,wBACN,+BAA+B,UAC/B,MAAM,eACN,2BAA2B,GACzB,QAAQ,+BAA+B,CAAC,CAyBpD;+BAzba,OAAO,YAAY,EAAE,gBAAgB;oCACrC,OAAO,YAAY,EAAE,qBAAqB;wCAC1C,OAAO,YAAY,EAAE,yBAAyB;4CAC9C,OAAO,YAAY,EAAE,6BAA6B;yBAClD,OAAO,YAAY,EAAE,UAAU;0CAC/B,OAAO,YAAY,EAAE,2BAA2B;oCAChD,OAAO,YAAY,EAAE,qBAAqB;8CAE1C,OAAO,KAAK,EAAE,+BAA+B"}
+{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["policy.js"],"names":[],"mappings":"AAYA;;GAEG;AACH,sDAAuD;AAkDhD,uGAFM,MAAM,MAAM,CAAC,CAezB;AA0BM,qDAJI,OAAO,YAAY,EAAE,gBAAgB,iBACrC,OAAO,YAAY,EAAE,aAAa,GAChC,OAAO,CASnB;AA0BM,+CAHI,OAAO,YAAY,EAAE,gBAAgB,2EAuB/C;AAsDM,8DAJI,OAAO,MAAM,EAAE,WAAW,CAAC,0BAC3B,OAAO,MAAM,EAAE,OAAO,YAAY,EAAE,qBAAqB,CAAC,GACxD,OAAO,YAAY,EAAE,2BAA2B,CA2C5D;AAoDM,6CARI,MAAM,WACN,MAAM,iBACN,OAAO,YAAY,EAAE,aAAa,eAClC,OAAO,YAAY,EAAE,2BAA2B,eAChD,mBAAc,SACd,MAAM,GACJ,IAAI,CAgDhB;AA2BM,+CAJI,MAAM,yBACN,OAAO,YAAY,EAAE,qBAAqB,sEAiCpD;AAgDM,+CANI,MAAM,wBACN,OAAO,KAAK,EAAE,+BAA+B,UAC7C,OAAO,YAAY,EAAE,aAAa,eAClC,OAAO,YAAY,EAAE,2BAA2B,GAC9C,QAAQ,OAAO,KAAK,EAAE,+BAA+B,CAAC,CAyBlE"}

package/src/policy.js

@@ -1,20 +1,10 @@
 // @ts-check
 
-/** @typedef {import('./types.js').PackageNamingKit} PackageNamingKit */
-/** @typedef {import('./types.js').AttenuationDefinition} AttenuationDefinition */
-/** @typedef {import('./types.js').FullAttenuationDefinition} FullAttenuationDefinition */
-/** @typedef {import('./types.js').ImplicitAttenuationDefinition} ImplicitAttenuationDefinition */
-/** @typedef {import('./types.js').Attenuator} Attenuator */
-/** @typedef {import('./types.js').DeferredAttenuatorsProvider} DeferredAttenuatorsProvider */
-/** @typedef {import('./types.js').CompartmentDescriptor} CompartmentDescriptor */
-// get StaticModuleRecord from the ses package's types
-/** @typedef {import('ses').ThirdPartyStaticModuleInterface} ThirdPartyStaticModuleInterface */
-
 import {
-  policyLookupHelper,
-  isAttenuationDefinition,
   getAttenuatorFromDefinition,
   isAllowingEverything,
+  isAttenuationDefinition,
+  policyLookupHelper,
 } from './policy-format.js';
 
 const { create, entries, values, assign, keys, freeze } = Object;
@@ -46,8 +36,15 @@ const selectiveCopy = (from, to, list) => {
   return to;
 };
 
+/**
+ * Parses an attenuation definition for attenuator names
+ *
+ * Note: this function is recursive
+ * @param {string[]} attenuators - List of attenuator names; may be mutated
+ * @param {import('./types.js').AttenuationDefinition|import('./types.js').Policy} policyFragment
+ */
 const collectAttenuators = (attenuators, policyFragment) => {
-  if (policyFragment.attenuate) {
+  if ('attenuate' in policyFragment) {
     attenuators.push(policyFragment.attenuate);
   }
   for (const value of values(policyFragment)) {
@@ -58,11 +55,12 @@ const collectAttenuators = (attenuators, policyFragment) => {
 };
 
 const attenuatorsCache = new WeakMap();
+
 /**
  * Goes through policy and lists all attenuator specifiers used.
  * Memoization keyed on policy object reference
  *
- * @param {object} policy
+ * @param {import('./types.js').Policy} [policy]
  * @returns {Array<string>} attenuators
  */
 export const detectAttenuators = policy => {
@@ -83,7 +81,7 @@ export const detectAttenuators = policy => {
 /**
  * Generates a string identifying a package for policy lookup purposes.
  *
- * @param {PackageNamingKit} namingKit
+ * @param {import('./types.js').PackageNamingKit} namingKit
  * @returns {string}
  */
 const generateCanonicalName = ({ isEntry = false, name, path }) => {
@@ -97,11 +95,11 @@ const generateCanonicalName = ({ isEntry = false, name, path }) => {
 };
 
 /**
- * Verifies if a module identified by namingKit can be a dependency of a package per packagePolicy.
- * packagePolicy is required, when policy is not set, skipping needs to be handled by the caller.
+ * Verifies if a module identified by `namingKit` can be a dependency of a package per `packagePolicy`.
+ * `packagePolicy` is required, when policy is not set, skipping needs to be handled by the caller.
  *
- * @param {PackageNamingKit} namingKit
- * @param {any} packagePolicy
+ * @param {import('./types.js').PackageNamingKit} namingKit
+ * @param {import('./types.js').PackagePolicy} packagePolicy
  * @returns {boolean}
  */
 export const dependencyAllowedByPolicy = (namingKit, packagePolicy) => {
@@ -116,9 +114,26 @@ export const dependencyAllowedByPolicy = (namingKit, packagePolicy) => {
 /**
  * Returns the policy applicable to the canonicalName of the package
  *
- * @param {PackageNamingKit} namingKit - a key in the policy resources spec is derived frm these
- * @param {object|undefined} policy - user supplied policy
- * @returns {object|undefined} packagePolicy if policy was specified
+ * @overload
+ * @param {import('./types.js').PackageNamingKit} namingKit - a key in the policy resources spec is derived from these
+ * @param {import('./types.js').Policy} policy - user supplied policy
+ * @returns {import('./types.js').PackagePolicy} packagePolicy if policy was specified
+ */
+
+/**
+ * Returns `undefined`
+ *
+ * @overload
+ * @param {import('./types.js').PackageNamingKit} namingKit - a key in the policy resources spec is derived from these
+ * @param {import('./types.js').Policy} [policy] - user supplied policy
+ * @returns {import('./types.js').PackagePolicy|undefined} packagePolicy if policy was specified
+ */
+
+/**
+ * Returns the policy applicable to the canonicalName of the package
+ *
+ * @param {import('./types.js').PackageNamingKit} namingKit - a key in the policy resources spec is derived from these
+ * @param {import('./types.js').Policy} [policy] - user supplied policy
  */
 export const getPolicyForPackage = (namingKit, policy) => {
   if (!policy) {
@@ -142,8 +157,13 @@ export const getPolicyForPackage = (namingKit, policy) => {
   }
 };
 
+/**
+ * Get list of globals from package policy
+ * @param {import('./types.js').PackagePolicy} [packagePolicy]
+ * @returns {Array<string>}
+ */
 const getGlobalsList = packagePolicy => {
-  if (!packagePolicy.globals) {
+  if (!packagePolicy || !packagePolicy.globals) {
     return [];
   }
   return entries(packagePolicy.globals)
@@ -153,10 +173,11 @@ const getGlobalsList = packagePolicy => {
 
 const GLOBAL_ATTENUATOR = 'attenuateGlobals';
 const MODULE_ATTENUATOR = 'attenuateModule';
+
 /**
- *
- * @param {AttenuationDefinition} attenuationDefinition
- * @param {DeferredAttenuatorsProvider} attenuatorsProvider
+ * Imports attenuator per its definition and provider
+ * @param {import('./types.js').AttenuationDefinition} attenuationDefinition
+ * @param {import('./types.js').DeferredAttenuatorsProvider} attenuatorsProvider
  * @param {string} attenuatorExportName
  * @returns {Promise<Function>}
  */
@@ -183,10 +204,10 @@ const importAttenuatorForDefinition = async (
 };
 
 /**
- *
+ * Makes an async provider for attenuators
  * @param {Record<string, Compartment>} compartments
- * @param {Record<string, CompartmentDescriptor>} compartmentDescriptors
- * @returns {DeferredAttenuatorsProvider}
+ * @param {Record<string, import('./types.js').CompartmentDescriptor>} compartmentDescriptors
+ * @returns {import('./types.js').DeferredAttenuatorsProvider}
  */
 export const makeDeferredAttenuatorsProvider = (
   compartments,
@@ -210,7 +231,7 @@ export const makeDeferredAttenuatorsProvider = (
     /**
      *
      * @param {string} attenuatorSpecifier
-     * @returns {Promise<Attenuator>}
+     * @returns {Promise<import('./types.js').Attenuator>}
      */
     importAttenuator = async attenuatorSpecifier => {
       if (!attenuatorSpecifier) {
@@ -232,10 +253,11 @@ export const makeDeferredAttenuatorsProvider = (
 };
 
 /**
+ * Attenuates the `globalThis` object
  *
  * @param {object} options
- * @param {DeferredAttenuatorsProvider} options.attenuators
- * @param {AttenuationDefinition} options.attenuationDefinition
+ * @param {import('./types.js').DeferredAttenuatorsProvider} options.attenuators
+ * @param {import('./types.js').AttenuationDefinition} options.attenuationDefinition
  * @param {object} options.globalThis
  * @param {object} options.globals
  */
@@ -274,8 +296,8 @@ async function attenuateGlobalThis({
  *
  * @param {object} globalThis
  * @param {object} globals
- * @param {object} packagePolicy
- * @param {DeferredAttenuatorsProvider} attenuators
+ * @param {import('./types.js').PackagePolicy} packagePolicy
+ * @param {import('./types.js').DeferredAttenuatorsProvider} attenuators
  * @param {Array<Promise>} pendingJobs
  * @param {string} name
  * @returns {void}
@@ -328,37 +350,49 @@ export const attenuateGlobals = (
   freezeGlobalThisUnlessOptedOut();
 };
 
+/**
+ * @param {string} [errorHint]
+ * @returns {string}
+ */
 const diagnoseModulePolicy = errorHint => {
   if (!errorHint) {
     return '';
   }
   return ` (info: ${errorHint})`;
 };
+
+/**
+ * Options for {@link enforceModulePolicy}
+ * @typedef EnforceModulePolicyOptions
+ * @property {boolean} [exit] - Whether it is an exit module
+ * @property {string} [errorHint] - Error hint message
+ */
+
 /**
  * Throws if importing of the specifier is not allowed by the policy
  *
  * @param {string} specifier
  * @param {import('./types.js').CompartmentDescriptor} compartmentDescriptor
- * @param {object} [info]
+ * @param {EnforceModulePolicyOptions} [options]
  */
 export const enforceModulePolicy = (
   specifier,
   compartmentDescriptor,
-  info = {},
+  { exit, errorHint } = {},
 ) => {
   const { policy, modules, label } = compartmentDescriptor;
   if (!policy) {
     return;
   }
 
-  if (!info.exit) {
+  if (!exit) {
     if (!modules[specifier]) {
       throw Error(
         `Importing ${q(specifier)} in ${q(
           label,
         )} was not allowed by packages policy ${q(
           policy.packages,
-        )}${diagnoseModulePolicy(info.errorHint)}`,
+        )}${diagnoseModulePolicy(errorHint)}`,
       );
     }
     return;
@@ -368,18 +402,18 @@ export const enforceModulePolicy = (
     throw Error(
       `Importing ${q(specifier)} was not allowed by policy builtins:${q(
         policy.builtins,
-      )}${diagnoseModulePolicy(info.errorHint)}`,
+      )}${diagnoseModulePolicy(errorHint)}`,
     );
   }
 };
 
 /**
- *
+ * Attenuates a module
  * @param {object} options
- * @param {DeferredAttenuatorsProvider} options.attenuators
- * @param {AttenuationDefinition} options.attenuationDefinition
- * @param {ThirdPartyStaticModuleInterface} options.originalModuleRecord
- * @returns {Promise<ThirdPartyStaticModuleInterface>}
+ * @param {import('./types.js').DeferredAttenuatorsProvider} options.attenuators
+ * @param {import('./types.js').AttenuationDefinition} options.attenuationDefinition
+ * @param {import('ses').ThirdPartyStaticModuleInterface} options.originalModuleRecord
+ * @returns {Promise<import('ses').ThirdPartyStaticModuleInterface>}
  */
 async function attenuateModule({
   attenuators,
@@ -409,14 +443,15 @@ async function attenuateModule({
     },
   });
 }
+
 /**
  * Throws if importing of the specifier is not allowed by the policy
  *
  * @param {string} specifier - exit module name
- * @param {ThirdPartyStaticModuleInterface} originalModuleRecord - reference to the exit module
- * @param {object} policy - local compartment policy
- * @param {DeferredAttenuatorsProvider} attenuators - a key-value where attenuations can be found
- * @returns {Promise<ThirdPartyStaticModuleInterface>} - the attenuated module
+ * @param {import('ses').ThirdPartyStaticModuleInterface} originalModuleRecord - reference to the exit module
+ * @param {import('./types.js').PackagePolicy} policy - local compartment policy
+ * @param {import('./types.js').DeferredAttenuatorsProvider} attenuators - a key-value where attenuations can be found
+ * @returns {Promise<import('ses').ThirdPartyStaticModuleInterface>} - the attenuated module
  */
 export const attenuateModuleHook = async (
   specifier,

package/src/types.d.ts

@@ -112,7 +112,7 @@ export type Application = {
     import: ExecuteFn;
     sha512?: string | undefined;
 };
-export type ExecuteFn = (options?: ExecuteOptions | undefined) => Promise<object>;
+export type ExecuteFn = (options?: ExecuteOptions | undefined) => Promise<SomeObject>;
 export type SnapshotFn = () => Promise<Uint8Array>;
 export type ReadPowers = {
     read: ReadFn;
@@ -259,22 +259,101 @@ export type PackageNamingKit = {
     name: string;
     path: Array<string>;
 };
+/**
+ * An object representing a full attenuation definition.
+ */
 export type FullAttenuationDefinition = {
-    name: string;
-    params: Array<any>;
+    /**
+     * - The type of attenuation.
+     */
+    attenuate: string;
+    /**
+     * - The parameters for the attenuation.
+     */
+    params: ImplicitAttenuationDefinition;
 };
-export type ImplicitAttenuationDefinition = Array<any>;
-export type AttenuationDefinition = FullAttenuationDefinition | any[];
+/**
+ * An array of any type representing an implicit attenuation definition.
+ */
+export type ImplicitAttenuationDefinition = [any, ...any[]];
+/**
+ * A type representing an attenuation definition, which can be either a full or implicit definition.
+ */
+export type AttenuationDefinition = FullAttenuationDefinition | [any, ...any[]];
 export type UnifiedAttenuationDefinition = {
     displayName: string;
     specifier: string | null;
     params?: any[] | undefined;
 };
-export type Attenuator = {
-    attenuateGlobals?: Function | undefined;
-    attenuateModule?: Function | undefined;
+export type Attenuator<GlobalParams extends [any, ...any[]] = [any, ...any[]], ModuleParams extends [any, ...any[]] = [any, ...any[]]> = {
+    attenuateGlobals?: GlobalAttenuatorFn<GlobalParams> | undefined;
+    attenuateModule?: ModuleAttenuatorFn<ModuleParams, unknown, unknown> | undefined;
 };
+export type GlobalAttenuatorFn<Params extends [any, ...any[]] = [any, ...any[]]> = (params: Params, originalObject: Record<PropertyKey, any>, globalThis: Record<PropertyKey, any>) => void;
+export type ModuleAttenuatorFn<Params extends [any, ...any[]] = [any, ...any[]], T = unknown, U = T> = (params: Params, ns: T) => U;
 export type DeferredAttenuatorsProvider = {
     import: (attenuatorSpecifier: string | null) => Promise<Attenuator>;
 };
+/**
+ * A type representing a wildcard policy, which can be 'any'.
+ */
+export type WildcardPolicy = 'any';
+/**
+ * A type representing a property policy, which is a record of string keys and boolean values.
+ */
+export type PropertyPolicy = Record<string, boolean>;
+/**
+ * A type representing a policy item, which can be a {@link WildcardPolicy wildcard policy}, a property policy, `undefined`, or defined by an attenuator
+ */
+export type PolicyItem<T = void> = WildcardPolicy | PropertyPolicy | T;
+/**
+ * An object representing a nested attenuation definition.
+ */
+export type NestedAttenuationDefinition = Record<string, AttenuationDefinition | boolean>;
+/**
+ * An object representing a base package policy.
+ */
+export type PackagePolicy<PackagePolicyItem = void, GlobalsPolicyItem = void, BuiltinsPolicyItem = void> = {
+    /**
+     * - The default attenuator.
+     */
+    defaultAttenuator?: string | undefined;
+    /**
+     * - The policy item for packages.
+     */
+    packages?: PolicyItem<PackagePolicyItem> | undefined;
+    /**
+     * - The policy item or full attenuation definition for globals.
+     */
+    globals?: AttenuationDefinition | PolicyItem<GlobalsPolicyItem> | undefined;
+    /**
+     * - The policy item or nested attenuation definition for builtins.
+     */
+    builtins?: NestedAttenuationDefinition | PolicyItem<BuiltinsPolicyItem> | undefined;
+    /**
+     * - Whether to disable global freeze.
+     */
+    noGlobalFreeze?: boolean | undefined;
+};
+/**
+ * An object representing a base policy.
+ */
+export type Policy<PackagePolicyItem = void, GlobalsPolicyItem = void, BuiltinsPolicyItem = void> = {
+    /**
+     * - The package policies for the resources.
+     */
+    resources: Record<string, PackagePolicy<PackagePolicyItem, GlobalsPolicyItem, BuiltinsPolicyItem>>;
+    /**
+     * - The default attenuator.
+     */
+    defaultAttenuator?: string | undefined;
+    /**
+     * - The package policy for the entry.
+     */
+    entry?: PackagePolicy<PackagePolicyItem, GlobalsPolicyItem, BuiltinsPolicyItem> | undefined;
+};
+/**
+ * Any object. All objects. Not `null`, though.
+ */
+export type SomeObject = Record<PropertyKey, any>;
 //# sourceMappingURL=types.d.ts.map

package/src/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["types.js"],"names":[],"mappings":"oCAKc,OAAO,KAAK,EAAE,qBAAqB;8CACnC,OAAO,KAAK,EAAE,+BAA+B;yBAC7C,OAAO,KAAK,EAAE,UAAU;+BACxB,OAAO,KAAK,EAAE,gBAAgB;wBAC9B,OAAO,KAAK,EAAE,SAAS;;;;;;UAWvB,MAAM,MAAM,CAAC;WACb,eAAe;kBACf,OAAO,MAAM,EAAE,qBAAqB,CAAC;;;;;;;iBAQrC,MAAM;YACN,MAAM;;;;;;;;WASN,MAAM;;;;;;;;;;;UAGN,MAAM;cAGN,MAAM;;;;;;;aAIN,OAAO,MAAM,EAAE,gBAAgB,CAAC;YAChC,OAAO,MAAM,EAAE,eAAe,CAAC;;;;aAC/B,OAAO,MAAM,EAAE,QAAQ,CAAC;;;;WACxB,OAAO,MAAM,EAAE,QAAQ,CAAC;;;;YACxB,MAAM;;;;;;;kBAQN,MAAM;;;;;;;;;;;;;;;;;;;iBAiBN,MAAM;;;uBAKP,KAAK,GAAG,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,cAAc,GAAG,cAAc;;WAS1E,OAAO;cACP,UAAU;;iCAKb,MAAM,SACN,UAAU,KACR,QAAQ,IAAI,CAAC;;UAKZ,MAAM;;gCAKT,MAAM,KACJ,QAAQ,UAAU,CAAC;;;;qCAOrB,MAAM,KACJ,QAAQ,UAAU,GAAG,SAAS,CAAC;;;;;;qCASjC,MAAM,KACJ,QAAQ,MAAM,CAAC;6BAKjB,MAAM,GAAG,UAAU,KACjB,MAAM;;YAKL,SAAS;;;kEAOV,QAAQ,MAAM,CAAC;+BAKf,QAAQ,UAAU,CAAC;;UAKlB,MAAM;eACN,WAAW;;;;;;8BAQZ,UAAU,GAAG,MAAM;;UAMlB,MAAM;eACN,WAAW;mBACX,MAAM;;;WAKN,OAAO;;4CASV,MAAM,qBACN,MAAM,KACJ,MAAM;0CAKR,QAAQ,GAAG,SAAS,KAClB,OAAO;;qBAKN,MAAM;iBACN,MAAM;iBACN,2BAA2B;WAC3B,OAAO;sBACP,gBAAgB;kBAChB,OAAO,MAAM,EAAE,WAAW,CAAC;;wCAK9B,sBAAsB,KACpB,UAAU;;iBAKT,MAAM;YACN,MAAM;cACN,MAAM;YACN,MAAM;;wCAKT,MAAM,WACN,oBAAoB;;iBAKjB,MAAM;YACN,MAAM;cACN,MAAM;YACN,MAAM;;qDAKT,+BAA+B,KAC7B,MAAM;8BAKR,UAAU,aACV,MAAM,YACN,MAAM,mBACN,MAAM;;;;;kBAMJ,QAAQ;IACpB,KAAS,EAAE,UAAU,CAAC;IACtB,MAAU,EAAE,QAAQ,CAAC;IACrB,MAAU,EAAE,qBAAqB,CAAC;IAClC,SAAa,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;;;;;;sBAQS,OAAO;WACP,OAAO;;0DAKV,MAAM,mBACN,MAAM,KACJ,MAAM,GAAC,SAAS;+CAKlB,MAAM,KACJ,QAAQ,+BAA+B,GAAC,SAAS,CAAC;;;;;;;;;cAcjD,MAAM;;;;;;;;gCAUP,OAAO,MAAM,EAAE,oBAAoB,CAAC;;;oBAMnC,eAAe;uBACf,iBAAiB;;;;0BAMlB,cAAc,GAAG,gBAAgB;+BAIjC,OAAO,MAAM,EAAE,eAAe,CAAC;sCAKjC,UAAU,aACV,MAAM,YACN,MAAM,mBACN,MAAM;;kBAGJ,QAAQ;IAAC,KAAK,EAAE,UAAU,CAAC;IAAC,MAAM,EAAE,QAAQ,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAC,CAAC;sBASlE,OAAO,MAAM,EAAE,kBAAkB,CAAC;iCAIlC,OAAO,MAAM,EAAE,YAAY,CAAC;;;;;;;;;;;;;;;;;;;;;;;;WAiB3B,UAAU;YACV,QAAQ;;0DAKX,MAAM,mBACN,MAAM,kBACN,MAAM;;;;;aAQH,MAAM;;;;;;;;;;;;;UAgBN,MAAM;UACN,MAAM,MAAM,CAAC;;;UAKb,MAAM;YACN,MAAM,GAAG,CAAC;;4CAIX,MAAM,GAAG,CAAC;oCAIV,yBAAyB,QAAgC;;iBAKxD,MAAM;eACN,MAAM,GAAG,IAAI;;;;;;;;kCAYS,MAAM,GAAC,IAAI,KAAK,QAAQ,UAAU,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["types.js"],"names":[],"mappings":"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"}

package/src/types.js

@@ -146,7 +146,7 @@ export {};
 /**
  * @callback ExecuteFn
  * @param {ExecuteOptions} [options]
- * @returns {Promise<object>}
+ * @returns {Promise<SomeObject>}
  */
 
 /**
@@ -399,16 +399,19 @@ export {};
  */
 
 /**
+ * An object representing a full attenuation definition.
  * @typedef {object} FullAttenuationDefinition
- * @property {string} name
- * @property {Array<any>} params
+ * @property {string} attenuate - The type of attenuation.
+ * @property {ImplicitAttenuationDefinition} params - The parameters for the attenuation.
  */
 
 /**
- * @typedef {Array<any>} ImplicitAttenuationDefinition
+ * An array of any type representing an implicit attenuation definition.
+ * @typedef {[any, ...any[]]} ImplicitAttenuationDefinition
  */
 
 /**
+ * A type representing an attenuation definition, which can be either a full or implicit definition.
  * @typedef {FullAttenuationDefinition | ImplicitAttenuationDefinition} AttenuationDefinition
  */
 
@@ -420,12 +423,84 @@ export {};
  */
 
 /**
- * @typedef {object} Attenuator
- * @property {Function} [attenuateGlobals]
- * @property {Function} [attenuateModule]
+ * @template {[any, ...any[]]} [GlobalParams=[any, ...any[]]]
+ * @template {[any, ...any[]]} [ModuleParams=[any, ...any[]]]
+ * @typedef Attenuator
+ * @property {GlobalAttenuatorFn<GlobalParams>} [attenuateGlobals]
+ * @property {ModuleAttenuatorFn<ModuleParams>} [attenuateModule]
+ */
+
+/**
+ * @template {[any, ...any[]]} [Params=[any, ...any[]]]
+ * @callback GlobalAttenuatorFn
+ * @param {Params} params
+ * @param {Record<PropertyKey, any>} originalObject
+ * @param {Record<PropertyKey, any>} globalThis
+ * @returns {void}
+ * @todo Unsure if we can do much typing of `originalObject` and `globalThis` here.
+ */
+
+/**
+ * @template {[any, ...any[]]} [Params=[any, ...any[]]]
+ * @template [T=unknown]
+ * @template [U=T]
+ * @callback ModuleAttenuatorFn
+ * @param {Params} params
+ * @param {T} ns
+ * @returns {U}
  */
 
 /**
  * @typedef {object} DeferredAttenuatorsProvider
  * @property {(attenuatorSpecifier: string|null) => Promise<Attenuator>} import
  */
+
+/**
+ * A type representing a wildcard policy, which can be 'any'.
+ * @typedef {'any'} WildcardPolicy
+ */
+
+/**
+ * A type representing a property policy, which is a record of string keys and boolean values.
+ * @typedef {Record<string, boolean>} PropertyPolicy
+ */
+
+/**
+ * A type representing a policy item, which can be a {@link WildcardPolicy wildcard policy}, a property policy, `undefined`, or defined by an attenuator
+ * @template [T=void]
+ * @typedef {WildcardPolicy|PropertyPolicy|T} PolicyItem
+ */
+
+/**
+ * An object representing a nested attenuation definition.
+ * @typedef {Record<string, AttenuationDefinition | boolean>} NestedAttenuationDefinition
+ */
+
+/**
+ * An object representing a base package policy.
+ * @template [PackagePolicyItem=void]
+ * @template [GlobalsPolicyItem=void]
+ * @template [BuiltinsPolicyItem=void]
+ * @typedef {object} PackagePolicy
+ * @property {string} [defaultAttenuator] - The default attenuator.
+ * @property {PolicyItem<PackagePolicyItem>} [packages] - The policy item for packages.
+ * @property {PolicyItem<GlobalsPolicyItem>|AttenuationDefinition} [globals] - The policy item or full attenuation definition for globals.
+ * @property {PolicyItem<BuiltinsPolicyItem>|NestedAttenuationDefinition} [builtins] - The policy item or nested attenuation definition for builtins.
+ * @property {boolean} [noGlobalFreeze] - Whether to disable global freeze.
+ */
+
+/**
+ * An object representing a base policy.
+ * @template [PackagePolicyItem=void]
+ * @template [GlobalsPolicyItem=void]
+ * @template [BuiltinsPolicyItem=void]
+ * @typedef {object} Policy
+ * @property {Record<string, PackagePolicy<PackagePolicyItem, GlobalsPolicyItem, BuiltinsPolicyItem>>} resources - The package policies for the resources.
+ * @property {string} [defaultAttenuator] - The default attenuator.
+ * @property {PackagePolicy<PackagePolicyItem, GlobalsPolicyItem, BuiltinsPolicyItem>} [entry] - The package policy for the entry.
+ */
+
+/**
+ * Any object. All objects. Not `null`, though.
+ * @typedef {Record<PropertyKey, any>} SomeObject
+ */

package/types.d.ts

@@ -14,3 +14,6 @@ export {
 export { search } from './src/search.js';
 export { compartmentMapForNodeModules } from './src/node-modules.js';
 export { makeBundle, writeBundle } from './src/bundle.js';
+
+// eslint-disable-next-line import/export -- ESLint doesn't understand this
+export type * from './src/types.js';