@endo/compartment-mapper 1.6.2 → 2.0.0

package/src/types/internal.ts

@@ -13,15 +13,11 @@ import type {
   Language,
   LanguageForExtension,
   LanguageForModuleSpecifier,
-  ModuleDescriptor,
+  PackageCompartmentDescriptor,
+  PackageCompartmentDescriptors,
+  CompartmentModuleConfiguration,
+  PackageCompartmentDescriptorName,
 } from './compartment-map-schema.js';
-import type {
-  MaybeReadFn,
-  MaybeReadNowFn,
-  ReadFn,
-  ReadPowers,
-} from './powers.js';
-import type { DeferredAttenuatorsProvider } from './policy.js';
 import type {
   ArchiveOnlyOption,
   AsyncParseFn,
@@ -30,16 +26,30 @@ import type {
   ExecuteOptions,
   ExitModuleImportHookOption,
   ExitModuleImportNowHookOption,
+  FileUrlString,
+  ModuleSourceHook,
+  PackageConnectionsHook,
+  PreloadOption,
   LogOptions,
   ModuleTransforms,
   ParseFn,
   ParserForLanguage,
+  PolicyOption,
   SearchSuffixesOption,
   SourceMapHook,
   SourceMapHookOption,
   Sources,
   SyncModuleTransforms,
+  CompartmentsRenameFn,
 } from './external.js';
+import type { PackageDescriptor } from './node-modules.js';
+import type { DeferredAttenuatorsProvider } from './policy.js';
+import type {
+  MaybeReadFn,
+  MaybeReadNowFn,
+  ReadFn,
+  ReadPowers,
+} from './powers.js';
 
 export type LinkOptions = {
   resolve?: ResolveHook;
@@ -50,7 +60,8 @@ export type LinkOptions = {
   syncModuleTransforms?: SyncModuleTransforms;
   __native__?: boolean;
 } & ArchiveOnlyOption &
-  ExecuteOptions;
+  ExecuteOptions &
+  LogOptions;
 
 export type LinkResult = {
   compartment: Compartment;
@@ -76,11 +87,13 @@ export type MakeImportHookMakersOptions = {
   /**
    * For depositing captured compartment descriptors.
    */
-  compartmentDescriptors?: Record<string, CompartmentDescriptor>;
+  compartmentDescriptors?: PackageCompartmentDescriptors;
+  moduleSourceHook?: ModuleSourceHook | undefined;
 } & ComputeSha512Option &
   SearchSuffixesOption &
   ArchiveOnlyOption &
-  SourceMapHookOption;
+  SourceMapHookOption &
+  LogOptions;
 
 export type MakeImportHookMakerOptions = MakeImportHookMakersOptions &
   ExitModuleImportHookOption;
@@ -88,7 +101,7 @@ export type MakeImportNowHookMakerOptions = MakeImportHookMakersOptions &
   ExitModuleImportNowHookOption;
 
 export type ImportHookMaker = (params: {
-  packageLocation: string;
+  packageLocation: PackageCompartmentDescriptorName;
   packageName: string;
   attenuators: DeferredAttenuatorsProvider;
   parse: ParseFn | AsyncParseFn;
@@ -97,7 +110,7 @@ export type ImportHookMaker = (params: {
 }) => ImportHook;
 
 export type ImportNowHookMaker = (params: {
-  packageLocation: string;
+  packageLocation: PackageCompartmentDescriptorName;
   packageName: string;
   parse: ParseFn | AsyncParseFn;
   compartments: Record<string, Compartment>;
@@ -125,13 +138,13 @@ export type ChooseModuleDescriptorParams = {
   /** Module specifiers with each search suffix appended */
   candidates: string[];
   moduleSpecifier: string;
-  packageLocation: string;
+  packageLocation: FileUrlString;
   /** Compartment descriptor from the compartment map */
-  compartmentDescriptor: CompartmentDescriptor;
+  compartmentDescriptor: PackageCompartmentDescriptor;
   /** All compartment descriptors from the compartment map */
-  compartmentDescriptors: Record<string, CompartmentDescriptor>;
+  compartmentDescriptors: PackageCompartmentDescriptors;
   /** All module descriptors in same compartment */
-  moduleDescriptors: Record<string, ModuleDescriptor>;
+  moduleDescriptors: Record<string, CompartmentModuleConfiguration>;
   /** All compartments */
   compartments: Record<string, Compartment>;
   packageSources: CompartmentSources;
@@ -140,11 +153,13 @@ export type ChooseModuleDescriptorParams = {
    * Whether to embed a sourceURL in applicable compiled sources.
    * Should be false for archives and bundles, but true for runtime.
    */
-  sourceMapHook?: SourceMapHook;
+  sourceMapHook?: SourceMapHook | undefined;
+  moduleSourceHook?: ModuleSourceHook | undefined;
 
   strictlyRequiredForCompartment: StrictlyRequiredFn;
 } & ComputeSha512Option &
-  ArchiveOnlyOption;
+  ArchiveOnlyOption &
+  LogOptions;
 
 type ShouldDeferErrorOption = {
   shouldDeferError: ShouldDeferError;
@@ -262,6 +277,7 @@ export type SearchDescriptorOptions = LogOptions;
 /**
  * A power to read a package descriptor
  * @template T Format of package descriptor
+ * @deprecated Use {@link MaybeReadDescriptorFn} instead.
  */
 export type ReadDescriptorFn<T = PackageDescriptor> = (
   location: string,
@@ -275,37 +291,6 @@ 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.
@@ -328,3 +313,20 @@ export type DeferErrorFn = (
    */
   error: Error,
 ) => StaticModuleType;
+
+export type MakeLoadCompartmentsOptions = LogOptions &
+  PolicyOption &
+  PreloadOption;
+
+export type DigestCompartmentMapOptions<
+  OldCompartmentName extends string = FileUrlString,
+  NewCompartmentName extends string = PackageCompartmentDescriptorName,
+> = LogOptions & {
+  packageConnectionsHook?: PackageConnectionsHook | undefined;
+  renameCompartments?: CompartmentsRenameFn<
+    OldCompartmentName,
+    NewCompartmentName
+  >;
+};
+
+export type CaptureCompartmentMapOptions = DigestCompartmentMapOptions;

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

@@ -1,27 +1,79 @@
+import type { GenericGraph } from '../generic-graph.js';
+import type { CanonicalName, PackageCompartmentDescriptorName, PolicyOption } from '../types.js';
 import type { Language, LanguageForExtension } from './compartment-map-schema.js';
-import type { LogOptions } from './external.js';
-import type { PackageDescriptor } from './internal.js';
+import type { FileUrlString, LogOptions, PackageDependenciesHook } from './external.js';
+import type { LiteralUnion } from './typescript.js';
 export type CommonDependencyDescriptors = Record<string, {
     spec: string;
     alias: string;
 }>;
-export type GraphPackageOptions = {
-    preferredPackageLogicalPathMap?: Map<string, string[]>;
-    logicalPath?: string[];
+/**
+ * Options bag containing {@link CommonDependencyDescriptors} that will be added to
+ * _all_ packages in the graph.
+ */
+export type CommonDependencyDescriptorsOptions = {
+    /**
+     * Dependencies added to _all_ packages
+     */
     commonDependencyDescriptors?: CommonDependencyDescriptors;
-} & LogOptions;
-export type GraphPackagesOptions = LogOptions;
+};
+/**
+ * Options bag containing a {@link PackageDependenciesHook}
+ */
+export type PackageDependenciesHookOption = {
+    packageDependenciesHook?: PackageDependenciesHook | undefined;
+};
+/**
+ * Options for `graphPackage()`
+ */
+export type GraphPackageOptions = LogOptions & PolicyOption & PackageDependenciesHookOption & CommonDependencyDescriptorsOptions;
+/**
+ * Options for `graphPackages()`
+ */
+export type GraphPackagesOptions = LogOptions & PolicyOption & PackageDependenciesHookOption;
+/**
+ * Options for `gatherDependency()`
+ */
 export type GatherDependencyOptions = {
     childLogicalPath?: string[];
     /**
      * If `true` the dependency is optional
      */
     optional?: boolean;
+} & LogOptions & PackageDependenciesHookOption & PolicyOption & CommonDependencyDescriptorsOptions;
+/**
+ * The type of a `package.json` file containing relevant fields; used by `graphPackages` and its ilk
+ */
+export interface PackageDescriptor {
     /**
-     * Dependencies added to _all_ packages
+     * 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
      */
-    commonDependencyDescriptors?: CommonDependencyDescriptors;
-} & LogOptions;
+    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;
+}
+/**
+ * Value in {@link Graph}
+ */
 export interface Node {
     /**
      * Informative compartment label based on the package name and version (if available)
@@ -31,8 +83,7 @@ export interface Node {
      * Package name
      */
     name: string;
-    path: Array<string>;
-    logicalPath: Array<string>;
+    location: FileUrlString;
     /**
      * `true` if the package's {@link PackageDescriptor} has an `exports` field
      */
@@ -51,17 +102,37 @@ export interface Node {
      *
      * The values are the keys of other {@link Node Nodes} in the {@link Graph}.
      */
-    dependencyLocations: Record<string, string>;
+    dependencyLocations: Record<string, FileUrlString>;
     parsers: LanguageForExtension;
     types: Record<string, Language>;
+    packageDescriptor: PackageDescriptor;
+}
+/**
+ * A node in the graph that has been finalized, meaning it has a `label` and is
+ * ready for conversion into a `CompartmentDescriptor`.
+ */
+export interface FinalNode extends Node {
+    /**
+     * Canonical name of the package; used to identify it in policy
+     */
+    label: string;
 }
 /**
  * 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.
+ * consumed by tools like Node.js. This gets translated finally into a
+ * compartment map.
+ *
+ * Keys may either be a file URL string to a package or the special
+ * `<ATTENUATORS>` string.
+ */
+export type Graph = Record<LiteralUnion<'<ATTENUATORS>', FileUrlString>, Node>;
+/**
+ * A graph, but contains {@link FinalNode}s instead of {@link Node}s.
+ *
+ * A "final node" has a `label` prop.
  */
-export type Graph = Record<string, Node>;
+export type FinalGraph = Record<PackageCompartmentDescriptorName, Readonly<FinalNode>>;
 export interface LanguageOptions {
     commonjsLanguageForExtension: LanguageForExtension;
     moduleLanguageForExtension: LanguageForExtension;
@@ -73,7 +144,20 @@ export interface LanguageOptions {
  * Object result of `findPackage()`
  */
 export interface PackageDetails {
-    packageLocation: string;
+    packageLocation: FileUrlString;
     packageDescriptor: PackageDescriptor;
 }
+/**
+ * Specific type of {@link GenericGraph} that uses file URL strings for nodes;
+ * used by `mapNodeModules()` and its ilk.
+ */
+export type LogicalPathGraph = GenericGraph<FileUrlString>;
+/**
+ * Options for `translateGraph()`
+ */
+export type TranslateGraphOptions = LogOptions & PolicyOption & PackageDependenciesHookOption;
+/**
+ * Mapping to enable reverse-lookups of `CompartmentDescriptor`s from policy.
+ */
+export type CanonicalNameMap = Map<CanonicalName, PackageCompartmentDescriptorName>;
 //# sourceMappingURL=node-modules.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"node-modules.d.ts","sourceRoot":"","sources":["node-modules.ts"],"names":[],"mappings":"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"}

package/src/types/node-modules.ts

@@ -1,35 +1,115 @@
+import type { GenericGraph } from '../generic-graph.js';
+import type {
+  ATTENUATORS_COMPARTMENT,
+  ENTRY_COMPARTMENT,
+} from '../policy-format.js';
+import type {
+  CanonicalName,
+  CompartmentMapDescriptor,
+  PackageCompartmentDescriptorName,
+  PolicyOption,
+  SomePolicy,
+} from '../types.js';
 import type {
   Language,
   LanguageForExtension,
+  PackageCompartmentMapDescriptor,
 } from './compartment-map-schema.js';
-import type { LogOptions } from './external.js';
-import type { PackageDescriptor } from './internal.js';
+import type {
+  FileUrlString,
+  LogOptions,
+  PackageDependenciesHook,
+} from './external.js';
+import type { LiteralUnion } from './typescript.js';
 
 export type CommonDependencyDescriptors = Record<
   string,
   { spec: string; alias: string }
 >;
 
-export type GraphPackageOptions = {
-  preferredPackageLogicalPathMap?: Map<string, string[]>;
-  logicalPath?: string[];
+/**
+ * Options bag containing {@link CommonDependencyDescriptors} that will be added to
+ * _all_ packages in the graph.
+ */
+export type CommonDependencyDescriptorsOptions = {
+  /**
+   * Dependencies added to _all_ packages
+   */
   commonDependencyDescriptors?: CommonDependencyDescriptors;
-} & LogOptions;
+};
 
-export type GraphPackagesOptions = LogOptions;
+/**
+ * Options bag containing a {@link PackageDependenciesHook}
+ */
+export type PackageDependenciesHookOption = {
+  packageDependenciesHook?: PackageDependenciesHook | undefined;
+};
 
+/**
+ * Options for `graphPackage()`
+ */
+export type GraphPackageOptions = LogOptions &
+  PolicyOption &
+  PackageDependenciesHookOption &
+  CommonDependencyDescriptorsOptions;
+
+/**
+ * Options for `graphPackages()`
+ */
+export type GraphPackagesOptions = LogOptions &
+  PolicyOption &
+  PackageDependenciesHookOption;
+
+/**
+ * Options for `gatherDependency()`
+ */
 export type GatherDependencyOptions = {
   childLogicalPath?: string[];
   /**
    * If `true` the dependency is optional
    */
   optional?: boolean;
+} & LogOptions &
+  PackageDependenciesHookOption &
+  PolicyOption &
+  CommonDependencyDescriptorsOptions;
+
+/**
+ * The type of a `package.json` file containing relevant fields; used by `graphPackages` and its ilk
+ */
+export interface PackageDescriptor {
   /**
-   * Dependencies added to _all_ packages
+   * 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
    */
-  commonDependencyDescriptors?: CommonDependencyDescriptors;
-} & LogOptions;
+  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;
+}
+
+/**
+ * Value in {@link Graph}
+ */
 export interface Node {
   /**
    * Informative compartment label based on the package name and version (if available)
@@ -39,8 +119,7 @@ export interface Node {
    * Package name
    */
   name: string;
-  path: Array<string>;
-  logicalPath: Array<string>;
+  location: FileUrlString;
   /**
    * `true` if the package's {@link PackageDescriptor} has an `exports` field
    */
@@ -59,18 +138,43 @@ export interface Node {
    *
    * The values are the keys of other {@link Node Nodes} in the {@link Graph}.
    */
-  dependencyLocations: Record<string, string>;
+  dependencyLocations: Record<string, FileUrlString>;
   parsers: LanguageForExtension;
   types: Record<string, Language>;
+  packageDescriptor: PackageDescriptor;
+}
+
+/**
+ * A node in the graph that has been finalized, meaning it has a `label` and is
+ * ready for conversion into a `CompartmentDescriptor`.
+ */
+export interface FinalNode extends Node {
+  /**
+   * Canonical name of the package; used to identify it in policy
+   */
+  label: string;
 }
 
 /**
  * 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.
+ * consumed by tools like Node.js. This gets translated finally into a
+ * compartment map.
+ *
+ * Keys may either be a file URL string to a package or the special
+ * `<ATTENUATORS>` string.
+ */
+export type Graph = Record<LiteralUnion<'<ATTENUATORS>', FileUrlString>, Node>;
+
+/**
+ * A graph, but contains {@link FinalNode}s instead of {@link Node}s.
+ *
+ * A "final node" has a `label` prop.
  */
-export type Graph = Record<string, Node>;
+export type FinalGraph = Record<
+  PackageCompartmentDescriptorName,
+  Readonly<FinalNode>
+>;
 
 export interface LanguageOptions {
   commonjsLanguageForExtension: LanguageForExtension;
@@ -84,6 +188,27 @@ export interface LanguageOptions {
  * Object result of `findPackage()`
  */
 export interface PackageDetails {
-  packageLocation: string;
+  packageLocation: FileUrlString;
   packageDescriptor: PackageDescriptor;
 }
+
+/**
+ * Specific type of {@link GenericGraph} that uses file URL strings for nodes;
+ * used by `mapNodeModules()` and its ilk.
+ */
+export type LogicalPathGraph = GenericGraph<FileUrlString>;
+
+/**
+ * Options for `translateGraph()`
+ */
+export type TranslateGraphOptions = LogOptions &
+  PolicyOption &
+  PackageDependenciesHookOption;
+
+/**
+ * Mapping to enable reverse-lookups of `CompartmentDescriptor`s from policy.
+ */
+export type CanonicalNameMap = Map<
+  CanonicalName,
+  PackageCompartmentDescriptorName
+>;

package/src/types/policy-schema.d.ts

@@ -4,6 +4,7 @@
  *
  * @module
  */
+import type { WILDCARD_POLICY_VALUE } from '../policy-format.js';
 /**
  * An object representing a full attenuation definition.
  */
@@ -11,7 +12,7 @@ export type FullAttenuationDefinition = {
     /** The type of attenuation. */
     attenuate: string;
     /** The parameters for the attenuation. */
-    params: ImplicitAttenuationDefinition;
+    params?: ImplicitAttenuationDefinition;
 };
 /**
  * An array of any type representing an implicit attenuation definition.
@@ -30,7 +31,7 @@ export type UnifiedAttenuationDefinition = {
 /**
  * A type representing a wildcard policy, which can be 'any'.
  */
-export type WildcardPolicy = 'any';
+export type WildcardPolicy = typeof WILDCARD_POLICY_VALUE;
 /**
  * A type representing a property policy, which is a record of string keys and
  * boolean values
@@ -41,7 +42,7 @@ export type PropertyPolicy = Record<string, boolean>;
  * wildcard policy}, a property policy, `undefined`, or defined by an
  * attenuator
  */
-export type PolicyItem<T = void> = WildcardPolicy | PropertyPolicy | T;
+export type PolicyItem<T = void> = [T] extends [void] ? WildcardPolicy | PropertyPolicy : WildcardPolicy | PropertyPolicy | T;
 /**
  * An object representing a nested attenuation definition.
  */
@@ -50,19 +51,33 @@ export type NestedAttenuationDefinition = Record<string, AttenuationDefinition |
  * An object representing a base package policy.
  */
 export type PackagePolicy<PackagePolicyItem = void, GlobalsPolicyItem = void, BuiltinsPolicyItem = void, ExtraOptions = unknown> = {
-    /** The default attenuator. */
+    /**
+     * The default attenuator, if any.
+     */
     defaultAttenuator?: string | undefined;
-    /** The policy item for packages. */
+    /**
+     * The policy item for packages.
+     */
     packages?: PolicyItem<PackagePolicyItem> | undefined;
-    /** The policy item or full attenuation definition for globals. */
+    /**
+     * The policy item or full attenuation definition for globals.
+     */
     globals?: AttenuationDefinition | PolicyItem<GlobalsPolicyItem> | undefined;
-    /** The policy item or nested attenuation definition for builtins. */
+    /**
+     * The policy item or nested attenuation definition for builtins.
+     */
     builtins?: NestedAttenuationDefinition | PolicyItem<BuiltinsPolicyItem> | undefined;
-    /** Whether to disable global freeze. */
+    /**
+     * Whether to disable global freeze.
+     */
     noGlobalFreeze?: boolean | undefined;
-    /** Whether to allow dynamic imports */
+    /**
+     * Whether to allow dynamic imports
+     */
     dynamic?: boolean | undefined;
-    /** Any additional user-defined options can be added to the policy here */
+    /**
+     * Any additional user-defined options can be added to the policy here
+     */
     options?: ExtraOptions | undefined;
 };
 /**
@@ -79,5 +94,5 @@ export type Policy<PackagePolicyItem = void, GlobalsPolicyItem = void, BuiltinsP
 /** Any {@link Policy} */
 export type SomePolicy = Policy<any, any, any, any>;
 /** Any {@link PackagePolicy} */
-export type SomePackagePolicy = PackagePolicy<PolicyItem, PolicyItem, PolicyItem, unknown>;
+export type SomePackagePolicy = PackagePolicy<void, void, void, unknown>;
 //# sourceMappingURL=policy-schema.d.ts.map

package/src/types/policy-schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"policy-schema.d.ts","sourceRoot":"","sources":["policy-schema.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH;;GAEG;AACH,MAAM,MAAM,yBAAyB,GAAG;IACtC,+BAA+B;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,0CAA0C;IAC1C,MAAM,EAAE,6BAA6B,CAAC;CACvC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,6BAA6B,GAAG,CAAC,GAAG,EAAE,GAAG,GAAG,EAAE,CAAC,CAAC;AAE5D;;;GAGG;AACH,MAAM,MAAM,qBAAqB,GAC7B,yBAAyB,GACzB,6BAA6B,CAAC;AAClC,MAAM,MAAM,4BAA4B,GAAG;IACzC,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,MAAM,CAAC,EAAE,GAAG,EAAE,GAAG,SAAS,CAAC;CAC5B,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,KAAK,CAAC;AAEnC;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAErD;;;;GAIG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,GAAG,IAAI,IAAI,cAAc,GAAG,cAAc,GAAG,CAAC,CAAC;AAEvE;;GAEG;AACH,MAAM,MAAM,2BAA2B,GAAG,MAAM,CAC9C,MAAM,EACN,qBAAqB,GAAG,OAAO,CAChC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,aAAa,CACvB,iBAAiB,GAAG,IAAI,EACxB,iBAAiB,GAAG,IAAI,EACxB,kBAAkB,GAAG,IAAI,EACzB,YAAY,GAAG,OAAO,IACpB;IACF,8BAA8B;IAC9B,iBAAiB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,oCAAoC;IACpC,QAAQ,CAAC,EAAE,UAAU,CAAC,iBAAiB,CAAC,GAAG,SAAS,CAAC;IACrD,kEAAkE;IAClE,OAAO,CAAC,EAAE,qBAAqB,GAAG,UAAU,CAAC,iBAAiB,CAAC,GAAG,SAAS,CAAC;IAC5E,qEAAqE;IACrE,QAAQ,CAAC,EACL,2BAA2B,GAC3B,UAAU,CAAC,kBAAkB,CAAC,GAC9B,SAAS,CAAC;IACd,wCAAwC;IACxC,cAAc,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACrC,uCAAuC;IACvC,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC9B,0EAA0E;IAC1E,OAAO,CAAC,EAAE,YAAY,GAAG,SAAS,CAAC;CACpC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,MAAM,CAChB,iBAAiB,GAAG,IAAI,EACxB,iBAAiB,GAAG,IAAI,EACxB,kBAAkB,GAAG,IAAI,EACzB,YAAY,GAAG,OAAO,IACpB;IACF,8CAA8C;IAC9C,SAAS,EAAE,MAAM,CACf,MAAM,EACN,aAAa,CACX,iBAAiB,EACjB,iBAAiB,EACjB,kBAAkB,EAClB,YAAY,CACb,CACF,CAAC;IACF,8BAA8B;IAC9B,iBAAiB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,wCAAwC;IACxC,KAAK,CAAC,EACF,aAAa,CACX,iBAAiB,EACjB,iBAAiB,EACjB,kBAAkB,EAClB,YAAY,CACb,GACD,SAAS,CAAC;CACf,CAAC;AAEF,yBAAyB;AACzB,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;AAEpD,gCAAgC;AAChC,MAAM,MAAM,iBAAiB,GAAG,aAAa,CAC3C,UAAU,EACV,UAAU,EACV,UAAU,EACV,OAAO,CACR,CAAC"}
+{"version":3,"file":"policy-schema.d.ts","sourceRoot":"","sources":["policy-schema.ts"],"names":[],"mappings":"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"}