feat(module-source): expose createModuleSourcePasses()

[boneskull]

This exposes a new function, createModuleSourcePasses for use with @endo/parser-pipeline.

Changes to existing code should be considered a pure refactor (or at least that was the aim).

• Refactored code for reuse between createModuleSourcePasses (see functor.js, source-options.js).
• Fixes quite a few type problems, including incorrect types for SourceMapHook and SourceMapDetails.
• Adds other types where things were obvious or involve public APIs

[boneskull]

Warning

This PR is part of a stack and targets branch boneskull/ast-service, not master.
DO NOT MERGE until feat(parser-pipeline): create @endo/parser-pipeline #3158 is merged into master.

📚 Pull Request Stack

• branch: master
  • feat(parser-pipeline): create @endo/parser-pipeline #3158 - branch: boneskull/ast-service
    • feat(module-source): expose createModuleSourcePasses() #3159 - branch: boneskull/module-source-pipeline (this PR)
      • create Babel-based AST parser for CommonJS sources #3162 - branch: boneskull/cjs-ast-parser
      • feat(evasive-transform): expose createEvasiveTransformPass for use with @endo/parser-pipeline #3161 - branch: boneskull/evasive-pipeline

---

Managed by gh-stack

[changeset-bot]

⚠️ No Changeset found

Latest commit: 9d57d5e

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[Copilot]

Pull request overview

This PR exposes a new public API, createModuleSourcePasses(), from @endo/module-source for consumption by @endo/parser-pipeline, while refactoring shared module-source logic (source-options + functor/record building) and tightening source map typing/flow between module-source, parser-pipeline, and compartment-mapper.

Changes:

• Added createModuleSourcePasses() with analyzer/transform visitors + buildRecord() for parser-pipeline integration.
• Refactored shared state + record construction into createSourceOptions() and buildFunctorSource() / buildModuleRecord().
• Updated source map hook flow so parser-pipeline receives raw source map objects (with compartment-mapper wrapping/stringifying for the public hook), plus added/updated public types and tests.

Reviewed changes

Copilot reviewed 18 out of 20 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
yarn.lock	Adds Babel-related type packages to the lockfile.
packages/parser-pipeline/src/composed-parser.js	Switches sourceMapHook callsite to pass raw source map objects.
packages/module-source/tsconfig.json	Adjusts include globs and excludes .d.ts files.
packages/module-source/test/visitor-passes.test.js	Adds tests for the new createModuleSourcePasses() API.
packages/module-source/test/module-source.test.js	Removes now-unneeded @ts-expect-error on source map hook details.
packages/module-source/test/_benchmark-babel-plugin.js	Reuses shared createSourceOptions() for benchmarks.
packages/module-source/src/visitor-passes.js	Implements createModuleSourcePasses() API.
packages/module-source/src/types/visitor-passes.ts	Adds exported TypeScript types for the new API.
packages/module-source/src/types/module-source.ts	Adds exported types for module-source options + source maps.
packages/module-source/src/transform-source.js	Refactors visitor extraction + improves source map emission gating.
packages/module-source/src/transform-analyze.js	Refactors to shared helpers for options + record construction.
packages/module-source/src/source-options.js	Introduces shared mutable state bag creation + visitor extraction.
packages/module-source/src/module-source.js	Simplifies ModuleSource construction by copying from frozen record.
packages/module-source/src/functor.js	Centralizes functor source + record assembly/freezing.
packages/module-source/src/external.types.js	Adds runtime-empty module for type-only re-exports.
packages/module-source/src/external.types.d.ts	Re-exports public types from the package.
packages/module-source/src/babel-plugin.js	Adds type imports/docs and a couple TS suppression annotations.
packages/module-source/package.json	Adds Babel generator/traverse type deps.
packages/module-source/index.js	Re-exports public types + createModuleSourcePasses().
packages/compartment-mapper/src/types/external.ts	Introduces ParseSourceMapHook and updates parse option typing.

Comments suppressed due to low confidence (1)

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

• This file still imports the JSDoc type Options from ./module-source.js, but that typedef was removed in this PR in favor of ModuleSourceOptions from ./types/module-source.js. With checkJs enabled, this will cause a broken type import and downstream type errors. Update the import and the @param annotation to reference ModuleSourceOptions (or an equivalent exported type) instead.

/** @import {Options} from './module-source.js' */

const makeCreateStaticRecord = transformSource =>
  /**
   *
   * @param {string} moduleSource
   * @param {Options} options
   */

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.