fix(module-source): address review comments on type definitions

- Remove `extends SourceMapHookDetails` from `TransformSourceParams`;
  `source` is only available at the `sourceMapHook` call site, not in
  the options/state bag. Inline the optional `sourceUrl`/`sourceMapUrl`
  fields directly.
- Add `allowHidden?: boolean` to `TransformSourceParams` to match
  runtime usage in `babel-plugin.js`, removing the `@ts-expect-error`.
- Make `SourceMapObject.file` optional per Source Map v3 spec.
- Use full tuple `[name, false, undefined]` for `hoistedDecls.push()`
  instead of short `[name]`, removing the `@ts-expect-error`.
- Remove stale `@ts-expect-error` directives for `@babel/generator`
  options now recognized by `@types/babel__generator`.
- Enable `exactOptionalPropertyTypes: true`.
- Add missing `typedoc.json`.

Author: boneskull

packages/module-source/src/babel-plugin.js

@@ -219,8 +219,7 @@ function makeModulePlugins(options) {
               } else {
                 // Rewrite to be just name = value.
                 soften(id);
-                // @ts-expect-error - needs types
-                options.hoistedDecls.push([name]);
+                options.hoistedDecls.push([name, false, undefined]);
                 replacements.push(
                   t.expressionStatement(
                     t.assignmentExpression(
@@ -280,7 +279,6 @@ function makeModulePlugins(options) {
 
       const visitor = {
         Identifier(path) {
-          // @ts-expect-error - needs types
           if (options.allowHidden || allowedHiddens.has(path.node)) {
             return;
           }

packages/module-source/src/transform-analyze.js

@@ -6,13 +6,13 @@ import * as h from './hidden.js';
 import { createSourceOptions } from './source-options.js';
 import { buildFunctorSource, buildModuleRecord } from './functor.js';
 
-/** @import {Options} from './module-source.js' */
+/** @import {ModuleSourceOptions} from './types/module-source.js' */
 
 const makeCreateStaticRecord = transformSource =>
   /**
    *
    * @param {string} moduleSource
-   * @param {Options} options
+   * @param {ModuleSourceOptions} options
    */
   function createStaticRecord(
     moduleSource,

packages/module-source/src/transform-source.js

@@ -43,7 +43,7 @@ export const makeTransformSource = (makeModulePlugins, babel = null) => {
       options;
 
     const ast = parseBabel(source, {
-      sourceType,
+      ...(sourceType !== undefined ? { sourceType } : {}),
       tokens: true,
       createParenthesizedExpressions: true,
     });
@@ -57,7 +57,7 @@ export const makeTransformSource = (makeModulePlugins, babel = null) => {
         {
           sourceFileName: sourceMapUrl,
           sourceMaps: !!sourceMapHook,
-          // @ts-expect-error - undocumented??
+          // @ts-expect-error undocumented option
           inputSourceMap: sourceMap,
           experimental_preserveFormat: true,
           preserveFormat: true,

packages/module-source/src/types/module-source.ts

@@ -28,8 +28,8 @@ export type ModuleSourceRecord = Readonly<
  * **Do not confuse with `SourceMapHookDetails` type from `@endo/compartment-mapper`.**
  */
 export interface SourceMapHookDetails {
-  sourceUrl?: string;
-  sourceMapUrl?: string;
+  sourceUrl?: string | undefined;
+  sourceMapUrl?: string | undefined;
   source: string;
 }
 
@@ -43,7 +43,7 @@ export type SourceMapObject = {
   sourceRoot?: string | undefined;
   sourcesContent?: string[] | undefined;
   mappings: string;
-  file: string;
+  file?: string | undefined;
 };
 
 /**
@@ -60,11 +60,16 @@ export type SourceMapHook = (
 
 /**
  * A bulging bucket of options for `transformSource`.
+ *
+ * The `source` string is intentionally excluded: it belongs in
+ * {@link SourceMapHookDetails} and is only available inside
+ * `transformSource()` when invoking `sourceMapHook`, not when constructing
+ * the options/state bag.
  */
-export interface TransformSourceParams
-  extends GeneratorOptions,
-    SourceMapHookDetails {
-  sourceType: ParserOptions['sourceType'];
+export interface TransformSourceParams extends GeneratorOptions {
+  sourceType?: ParserOptions['sourceType'] | undefined;
+  sourceUrl?: string | undefined;
+  sourceMapUrl?: string | undefined;
   fixedExportMap: Record<string, any>;
   imports: Record<string, any>;
   exportAlls: string[];
@@ -75,14 +80,15 @@ export interface TransformSourceParams
   importDecls: string[];
   dynamicImport: { present: boolean };
   importMeta: { present: boolean };
-  sourceMapHook?: SourceMapHook;
+  sourceMapHook?: SourceMapHook | undefined;
+  allowHidden?: boolean | undefined;
 
   /**
    * This is either a string or a SourceMapV3 object, but it's used with an
    * undocumented option (`inputSourceMap` of `@babel/generator`), so might not
    * do anything at all.
    */
-  sourceMap?: unknown;
+  sourceMap?: unknown | undefined;
 }
 
 /**
@@ -97,8 +103,8 @@ export type PluginFactory = (params: { types: typeof babelTypes }) => {
  * Options for the `ModuleSource` constructor.
  */
 export interface ModuleSourceOptions {
-  sourceUrl?: string;
-  sourceMap?: string;
-  sourceMapUrl?: string;
-  sourceMapHook?: SourceMapHook;
+  sourceUrl?: string | undefined;
+  sourceMap?: string | undefined;
+  sourceMapUrl?: string | undefined;
+  sourceMapHook?: SourceMapHook | undefined;
 }

packages/module-source/tsconfig.json

@@ -12,5 +12,8 @@
   ],
   "exclude": [
     "**/*.d.ts"
-  ]
+  ],
+  "compilerOptions": {
+    "exactOptionalPropertyTypes": true
+  }
 }

packages/module-source/typedoc.json

@@ -0,0 +1,4 @@
+{
+  "extends": ["../../typedoc.base.json"],
+  "entryPoints": ["index.js", "shim.js"]
+}