feat(evasive-transform): expose createEvasiveTransformPass for use with @endo/parser-pipeline

This exposes a new function, `createEvasiveTransformPass()`, which can be used with
`@endo/parser-pipeline` to unify AST parsing.

Refactored out some common code to maximize logic reuse.  Both the new function and the existing
`transformAst()` use the new `makeTransformCommentsVisitor()` to build the visitors for
`@babel/traverse`.

Author: boneskull

.changeset/itchy-meteors-cover.md

@@ -0,0 +1,5 @@
+---
+'@endo/evasive-transform': minor
+---
+
+Expose `createEvasiveTransformPass()` for use with `@endo/parser-pipeline`.

packages/evasive-transform/package.json

@@ -40,6 +40,7 @@
   "devDependencies": {
     "@babel/types": "~7.28.2",
     "@endo/ses-ava": "workspace:^",
+    "@types/babel__generator": "~7.27.0",
     "ava": "catalog:dev",
     "c8": "catalog:dev",
     "eslint": "catalog:dev",
@@ -74,6 +75,7 @@
   "dependencies": {
     "@babel/generator": "^7.28.3",
     "@babel/parser": "~7.28.3",
-    "@babel/traverse": "~7.28.3"
+    "@babel/traverse": "~7.28.3",
+    "@types/babel__traverse": "~7.28.0"
   }
 }

packages/evasive-transform/src/generate.js

@@ -17,17 +17,13 @@ const generator = /** @type {typeof import('@babel/generator')['default']} */ (
   babelGenerator.default || babelGenerator
 );
 
-/**
- * @typedef {NonNullable<import('@babel/generator').GeneratorOptions['inputSourceMap']>} SourceMapOption
- */
-
 /**
  * Options for {@link generateCode} with source map
  *
  * @typedef GenerateAstOptionsWithSourceMap
  * @property {string} [source]
  * @property {string} sourceUrl - If present, we will generate a source map
- * @property {SourceMapOption | undefined} [sourceMap] - If present, the generated source map will be a transform over the given source map.
+ * @property {object | string | undefined} [sourceMap] - If present, the generated source map will be a transform over the given source map.
  * @internal
  */
 
@@ -58,7 +54,7 @@ const generator = /** @type {typeof import('@babel/generator')['default']} */ (
 
 /**
  * Generates new code from a Babel AST; returns code and source map
- *@overload
+ * @overload
  * @param {import('@babel/types').File} ast - Babel "File" AST
  * @param {GenerateAstOptionsWithSourceMap} options - Options for the transform
  * @returns {TransformedResultWithSourceMap}
@@ -67,7 +63,7 @@ const generator = /** @type {typeof import('@babel/generator')['default']} */ (
 
 /**
  * Generates new code from a Babel AST; returns code only
- *@overload
+ * @overload
  * @param {import('@babel/types').File} ast - Babel "File" AST
  * @param {GenerateAstOptions} [options] - Options for the transform
  * @returns {TransformedResult}
@@ -93,6 +89,7 @@ export const generate = (ast, options) => {
     {
       sourceFileName: sourceUrl,
       sourceMaps: Boolean(sourceUrl),
+      // @ts-expect-error undocumented option
       inputSourceMap,
       retainLines: true,
       ...(source === undefined ? {} : { experimental_preserveFormat: true }),

packages/evasive-transform/src/index.js

@@ -6,7 +6,6 @@
 
 /**
  * @import {TransformedResult, TransformedResultWithSourceMap} from './generate.js'
- * @import {SourceMapOption} from './generate.js'
  */
 
 import { transformAst } from './transform-ast.js';
@@ -17,7 +16,7 @@ import { generate } from './generate.js';
  * Options for {@link evadeCensorSync}
  *
  * @typedef EvadeCensorOptions
- * @property {SourceMapOption | undefined} [sourceMap] - Original source map in JSON string or object form
+ * @property {object | string | undefined} [sourceMap] - Original source map in JSON string or object form
  * @property {string | undefined} [sourceUrl] - URL or filepath of the original source in `code`
  * @property {boolean | undefined} [elideComments] - Empties the comments but preserves interior newlines.
  * @property {import('./parse-ast.js').SourceType | undefined} [sourceType] - Module source type
@@ -128,3 +127,5 @@ export function evadeCensorSync(source, options) {
 export async function evadeCensor(source, options) {
   return evadeCensorSync(source, options);
 }
+
+export { createEvasiveTransformPass } from './transform-pass.js';

packages/evasive-transform/src/transform-ast.js

@@ -13,6 +13,11 @@ import {
   evadeRegexpLiteral,
 } from './transform-code.js';
 
+/**
+ * @import {Visitor} from '@babel/traverse'
+ * @import {Comment, CommentBlock, CommentLine, File} from '@babel/types'
+ */
+
 // TODO The following is sufficient on Node.js, but for compatibility with
 // `node -r esm`, we must use the pattern below.
 // Restore after https://github.com/Agoric/agoric-sdk/issues/8671.
@@ -38,13 +43,47 @@ const traverse = /** @type {typeof import('@babel/traverse')['default']} */ (
  * @property {boolean} [onlyComments]
  */
 
+/**
+ * Options for {@link makeTransformCommentsVisitor}
+ *
+ * @internal
+ * @typedef TransformCommentsVisitorOptions
+ * @property {(node: Comment|CommentBlock|CommentLine) => void} transformComment
+ * @property {boolean} [onlyComments]
+ */
+
+/**
+ * @param {TransformCommentsVisitorOptions} options
+ * @returns {Visitor}
+ */
+export const makeTransformCommentsVisitor = ({
+  transformComment,
+  onlyComments = false,
+}) => ({
+  enter(p) {
+    const { leadingComments, innerComments, trailingComments } = p.node;
+    if ('comments' in p.node) {
+      (p.node.comments || []).forEach(node => transformComment(node));
+    }
+    leadingComments?.forEach(node => transformComment(node));
+    innerComments?.forEach(node => transformComment(node));
+    trailingComments?.forEach(node => transformComment(node));
+    if (!onlyComments) {
+      evadeStrings(p);
+      evadeTemplates(p);
+      evadeRegexpLiteral(p);
+      evadeDecrementGreater(p);
+    }
+  },
+});
+
 /**
  * Performs transformations on the given AST
  *
  * This function mutates `ast`.
  *
  * @internal
- * @param {import('@babel/types').File} ast - AST, as generated by Babel
+ * @param {File} ast - AST, as generated by Babel
  * @param {TransformAstOptions} [opts]
  * @returns {void}
  */
@@ -53,26 +92,9 @@ export function transformAst(
   { elideComments = false, onlyComments = false } = {},
 ) {
   const transformComment = elideComments ? elideComment : evadeComment;
-  traverse(ast, {
-    enter(p) {
-      const { leadingComments, innerComments, trailingComments, type } = p.node;
-      // discriminated union
-      if ('comments' in p.node) {
-        (p.node.comments || []).forEach(node => transformComment(node));
-      }
-      // Rewrite all comments.
-      (leadingComments || []).forEach(node => transformComment(node));
-      if (type.startsWith('Comment')) {
-        transformComment(p.node);
-      }
-      (innerComments || []).forEach(node => transformComment(node));
-      (trailingComments || []).forEach(node => transformComment(node));
-      if (!onlyComments) {
-        evadeStrings(p);
-        evadeTemplates(p);
-        evadeRegexpLiteral(p);
-        evadeDecrementGreater(p);
-      }
-    },
+  const visitor = makeTransformCommentsVisitor({
+    transformComment,
+    onlyComments,
   });
+  traverse(ast, visitor);
 }

packages/evasive-transform/src/transform-code.js

@@ -1,3 +1,8 @@
+/**
+ * @import {BinaryExpression, Expression, Node, TemplateElement, TemplateLiteral} from '@babel/types'
+ * @import {NodePath} from '@babel/traverse'
+ */
+
 const evadeRegexp = /import\s*\(|<!--|-->/g;
 // The replacement collection for regexp patterns matching the evadeRegexp is only applied to the first matched character, so it is necessary for the regexpReplacements to be maintained together with the evadeRegexp.
 const regexpReplacements = {
@@ -11,8 +16,8 @@ const regexpReplacements = {
  * to sever references), updating the target's end position as if it had zero
  * length.
  *
- * @param {import('@babel/types').Node} target
- * @param {import('@babel/types').Node} src
+ * @param {Node} target
+ * @param {Node} src
  */
 const adoptStartFrom = (target, src) => {
   try {
@@ -37,9 +42,9 @@ const adoptStartFrom = (target, src) => {
 /**
  * Creates a BinaryExpression adding two expressions
  *
- * @param {import('@babel/types').Expression} left
+ * @param {Expression} left
  * @param {string} rightString
- * @returns {import('@babel/types').BinaryExpression}
+ * @returns {BinaryExpression}
  */
 const addStringToExpressions = (left, rightString) => ({
   type: 'BinaryExpression',
@@ -55,15 +60,15 @@ const addStringToExpressions = (left, rightString) => ({
  * Break up problematic substrings into concatenation expressions, e.g.
  * `"import("` -> `"im"+"port("`.
  *
- * @param {import('@babel/traverse').NodePath} p
+ * @param {NodePath} p
  */
 export const evadeStrings = p => {
   const { node } = p;
   if (node.type !== 'StringLiteral') {
     return;
   }
   const { value } = node;
-  /** @type {import('@babel/types').Expression | undefined} */
+  /** @type {Expression | undefined} */
   let expr;
   let lastIndex = 0;
   for (const match of value.matchAll(evadeRegexp)) {
@@ -85,10 +90,9 @@ export const evadeStrings = p => {
  * Break up problematic substrings in template literals with empty-string
  * expressions, e.g. `import(` -> `im${''}port(`.
  *
- * @param {import('@babel/traverse').NodePath} p
+ * @param {NodePath} p
  */
 export const evadeTemplates = p => {
-  /** @type {import('@babel/types').TemplateLiteral} */
   const node = p.node;
   // The transform is only meaning-preserving if not part of a
   // TaggedTemplateExpression, so these need to be excluded until a motivating
@@ -107,11 +111,14 @@ export const evadeTemplates = p => {
   // Check if any quasi needs transformation
   if (!quasis.some(quasi => quasi.value.raw.search(evadeRegexp) !== -1)) return;
 
-  /** @type {import('@babel/types').TemplateElement[]} */
+  /** @type {TemplateElement[]} */
   const newQuasis = [];
-  /** @type {import('@babel/types').Expression[]} */
+  /** @type {Expression[]} */
   const newExpressions = [];
 
+  /**
+   * @param {string} quasiValue
+   */
   const addQuasi = quasiValue => {
     // Insert empty expression to break the pattern
     newExpressions.push({
@@ -130,6 +137,7 @@ export const evadeTemplates = p => {
     });
   };
 
+  // eslint-disable-next-line @endo/restrict-comparison-operands
   for (let i = 0; i < quasis.length; i += 1) {
     const quasi = quasis[i];
     // We're not currently preserving raw vs. cooked literal data.
@@ -158,6 +166,7 @@ export const evadeTemplates = p => {
     }
 
     // Add original expression between quasis
+    // eslint-disable-next-line @endo/restrict-comparison-operands
     if (i < node.expressions.length) {
       // @ts-ignore whatever was there, must still be allowed.
       newExpressions.push(node.expressions[i]);
@@ -169,7 +178,7 @@ export const evadeTemplates = p => {
     newQuasis[newQuasis.length - 1].tail = true;
   }
 
-  /** @type {import('@babel/types').Node} */
+  /** @type {Node} */
   const replacement = {
     type: 'TemplateLiteral',
     quasis: newQuasis,
@@ -185,7 +194,7 @@ export const evadeTemplates = p => {
  *
  * `/import(/` -> `/im[p]ort(/`
  *
- * @param {import('@babel/traverse').NodePath} p
+ * @param {NodePath} p
  * @returns {void}
  */
 export const evadeRegexpLiteral = p => {
@@ -207,7 +216,7 @@ export const evadeRegexpLiteral = p => {
  * Prevents `-->` from appearing in output by transforming
  * `x-->y` to `(0,x--)>y`.
  *
- * @param {import('@babel/traverse').NodePath} p
+ * @param {NodePath} p
  * @returns {void}
  */
 export const evadeDecrementGreater = p => {

packages/evasive-transform/src/transform-pass-types.ts

@@ -0,0 +1,32 @@
+/**
+ * Types for `createEvasiveTransformPass`.
+ *
+ * @module
+ */
+
+import type { Visitor } from '@babel/traverse';
+
+/**
+ * A mutating transform pass that rewrites AST nodes in place.
+ *
+ * Matches the `TransformPass` interface from `@endo/parser-pipeline`.
+ */
+export interface TransformPass {
+  readonly visitor: Visitor;
+}
+
+/**
+ * Options for {@link createEvasiveTransformPass}.
+ */
+export interface CreateEvasiveTransformPassOptions {
+  /**
+   * Empties comments but preserves interior newlines.
+   */
+  elideComments?: boolean;
+
+  /**
+   * If true, limits transformation to comment contents, preserving code
+   * positions within each line.
+   */
+  onlyComments?: boolean;
+}

packages/evasive-transform/src/transform-pass.js

@@ -0,0 +1,32 @@
+/**
+ * Provides {@link createEvasiveTransformPass}, a {@link TransformPass} adapter
+ * for evasive transforms.
+ *
+ * @module
+ */
+
+/**
+ * @import {TransformPass, CreateEvasiveTransformPassOptions} from './transform-pass-types.js'
+ */
+
+import { evadeComment, elideComment } from './transform-comment.js';
+import { makeTransformCommentsVisitor } from './transform-ast.js';
+
+/**
+ * Creates a {@link TransformPass} compatible with `@endo/parser-pipeline` that
+ * applies SES censorship evasion transforms as AST mutations.
+ *
+ * The visitor applies the same transforms as {@link evadeCensorSync} but
+ * operates on an existing AST rather than parsing from source.
+ *
+ * @param {CreateEvasiveTransformPassOptions} [options]
+ * @returns {TransformPass}
+ */
+export const createEvasiveTransformPass = (options = {}) => {
+  const { elideComments = false, onlyComments = false } = options;
+  const transformComment = elideComments ? elideComment : evadeComment;
+
+  return {
+    visitor: makeTransformCommentsVisitor({ transformComment, onlyComments }),
+  };
+};