feat(module-source): expose AST-based CJS parser

Exposes AST-based parser for CJS, as well as an `analyzeCjs` function from the `analyzer.js` subpath export.

`CjsModuleSource` is also exported from the main entry point.

Author: boneskull

.changeset/open-mammals-scream.md

@@ -0,0 +1,5 @@
+---
+'@endo/module-source': minor
+---
+
+Exposes AST-based parser for CJS, as well as an `analyzeCjs` function from the `analyzer.js` subpath export.

packages/module-source/README.md

@@ -83,6 +83,16 @@ That is, the XS native `bindings` will be translated to `imports`, `exports`,
 and `reexports` getters.
 This form of `ModuleSource` ignores all options.
 
+## CommonJS-Specific Variant
+
+In the default/Node variant of `@endo/module-source`, a `CjsModuleSource`
+constructor provides a similar interface for CommonJS modules. It accepts the
+same options as `ModuleSource` and produces a `CjsModuleSourceRecord` object
+containing the analysis data plus a pre-built functor source string.
+
+Note: the `xs` condition currently provides only `ModuleSource`;
+`CjsModuleSource` is not available under `xs`.
+
 ## Bug Disclosure
 
 Please help us practice coordinated security bug disclosure, by using the

packages/module-source/analyzer.js

@@ -2,3 +2,4 @@
 export * from './src/external.types.js';
 
 export { analyzeModule } from './src/analyzer.js';
+export { analyzeCjs } from './src/cjs-analyzer.js';

packages/module-source/index.js

@@ -2,3 +2,4 @@
 export * from './src/external.types.js';
 
 export { ModuleSource } from './src/module-source.js';
+export { CjsModuleSource } from './src/cjs-module-source.js';

packages/module-source/src/cjs-analyzer.js

@@ -0,0 +1,51 @@
+/**
+ * Low-level module analysis primitives for CJS.
+ *
+ * {@link analyzeCjs} 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 makeCjsModulePlugins from './cjs-babel-plugin.js';
+import { buildCjsFunctorSource, buildCjsModuleRecord } from './cjs-functor.js';
+import { createCjsSourceOptions } from './source-options.js';
+
+/**
+ * @import {AnalysisOptions} from './types/analyzer.js'
+ * @import {CjsAnalysisContext} from './types/cjs-analyzer.js'
+ */
+
+/**
+ * Creates a fresh CJS analysis context for a single module parse.
+ *
+ * @param {AnalysisOptions} [options]
+ * @returns {CjsAnalysisContext}
+ */
+
+export const analyzeCjs = (options = {}) => {
+  const { allowHidden = false } = options;
+  const sourceOptions = createCjsSourceOptions({ allowHidden });
+  const { analyzePlugin, transformPlugin } =
+    makeCjsModulePlugins(sourceOptions);
+
+  return {
+    analyzePass: analyzePlugin,
+    transformPass: transformPlugin,
+
+    buildRecord(generatedCode, location) {
+      const functorSource = buildCjsFunctorSource(
+        generatedCode,
+        sourceOptions,
+        location,
+      );
+      return buildCjsModuleRecord(sourceOptions, functorSource);
+    },
+  };
+};