feat(module-source): fix types, expose analyzer.js subpath

.changeset/ripe-showers-remain.md

@@ -0,0 +1,9 @@
+---
+'@endo/module-source': minor
+---
+
+Fixes the type of `SourceMapHook` and introduces proper `.ts` type sources checked by `tsc`. Types that were previously inlined as JSDoc typedefs (`SourceMapHook`, `SourceMapHookDetails`, `SourceMapObject`, `ModuleSourceOptions`, `TransformSourceParams`) are now defined in `src/types/module-source.ts` and re-exported from the package root via a new `src/external.types.d.ts` entry.
+
+Adds a `./analyzer.js` subpath export with `analyzeModule(options?)`. The returned context object exposes `analyzePass` and `transformPass` (plain `{ visitor }` objects) and a `buildRecord()` function. This is the primitive that `@endo/parser-pipeline` uses to drive module analysis; it is also used internally by the `ModuleSource` constructor, so the exported API is not specific to the pipeline.
+
+Removes the `PluginFactory` abstraction and `visitorFromPlugin` helper: Babel plugins now return plain `{ visitor }` objects directly, with `@babel/types` imported at module scope.

packages/module-source/analyzer.js

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

packages/module-source/index.js

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

packages/module-source/package.json

@@ -24,9 +24,17 @@
   "exports": {
     ".": {
       "xs": "./src-xs/index.js",
+      "types": "./index.d.ts",
       "default": "./index.js"
     },
-    "./shim.js": "./shim.js",
+    "./shim.js": {
+      "types": "./src/shim.types.d.ts",
+      "default": "./shim.js"
+    },
+    "./analyzer.js": {
+      "types": "./analyzer.d.ts",
+      "default": "./analyzer.js"
+    },
     "./package.json": "./package.json"
   },
   "scripts": {
@@ -51,6 +59,8 @@
   },
   "devDependencies": {
     "@endo/ses-ava": "workspace:^",
+    "@types/babel__generator": "~7.27.0",
+    "@types/babel__traverse": "~7.28.0",
     "ava": "catalog:dev",
     "babel-eslint": "^10.1.0",
     "benchmark": "^2.1.4",
@@ -84,8 +94,25 @@
             "^@endo/module-source(?:/.*)?$"
           ]
         }
+      ],
+      "jsdoc/check-tag-names": [
+        "error",
+        {
+          "definedTags": [
+            "privateRemarks"
+          ]
+        }
       ]
     },
+    "overrides": [
+      {
+        "files": "**/*.ts",
+        "rules": {
+          "vars-on-top": "off",
+          "no-var": "off"
+        }
+      }
+    ],
     "ignorePatterns": [
       "test/fixtures/"
     ]

packages/module-source/src/analyzer.js

@@ -0,0 +1,48 @@
+/**
+ * Low-level module analysis primitives for ESM.
+ *
+ * {@link analyzeModule} returns a per-parse context object
+ * holding plain `{ visitor }` objects and a `buildRecord` function.
+ *
+ * Consumers are responsible for:
+ * 1. Traversing the AST with `ctx.analyzePass.visitor`.
+ * 2. Traversing the (mutated) AST with `ctx.transformPass.visitor`.
+ * 3. Generating code.
+ * 4. Calling `ctx.buildRecord(code, location)` to produce the module record.
+ *
+ * @module
+ */
+
+/**
+ * @import {ModuleAnalysisContext, AnalysisOptions} from './types/analyzer.js'
+ */
+
+import makeModulePlugins from './babel-plugin.js';
+import { createSourceOptions } from './source-options.js';
+import { buildFunctorSource, buildModuleRecord } from './functor.js';
+
+/**
+ * Creates a fresh ESM analysis context for a single module parse.
+ *
+ * @param {AnalysisOptions} [options]
+ * @returns {ModuleAnalysisContext}
+ */
+export const analyzeModule = (options = {}) => {
+  const { allowHidden = false } = options;
+  const sourceOptions = createSourceOptions({ allowHidden });
+  const { analyzePlugin, transformPlugin } = makeModulePlugins(sourceOptions);
+
+  return {
+    analyzePass: analyzePlugin,
+    transformPass: transformPlugin,
+
+    buildRecord(generatedCode, location) {
+      const functorSource = buildFunctorSource(
+        generatedCode,
+        sourceOptions,
+        location,
+      );
+      return buildModuleRecord(sourceOptions, functorSource);
+    },
+  };
+};