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

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

@@ -54,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}
@@ -63,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}
@@ -89,6 +89,7 @@ export const generate = (ast, options) => {
     {
       sourceFileName: sourceUrl,
       sourceMaps: Boolean(sourceUrl),
+      // @ts-expect-error - what is this, even
       inputSourceMap,
       retainLines: true,
       ...(source === undefined ? {} : { experimental_preserveFormat: true }),

packages/evasive-transform/src/index.js

@@ -123,3 +123,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 }),
+  };
+};

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

@@ -0,0 +1,51 @@
+import test from 'ava';
+import { parse } from '@babel/parser';
+import babelTraverse from '@babel/traverse';
+import babelGenerate from '@babel/generator';
+import { createEvasiveTransformPass } from '../src/transform-pass.js';
+
+const traverse = babelTraverse.default || babelTraverse;
+const generate = babelGenerate.default || babelGenerate;
+
+test('createEvasiveTransformPass returns a TransformPass', t => {
+  const pass = createEvasiveTransformPass();
+  t.is(typeof pass.visitor, 'object');
+  t.truthy(pass.visitor.enter);
+});
+
+test('evasive transform pass defangs import() in strings', t => {
+  const source = `const x = "import('foo')";`;
+  const ast = parse(source, { sourceType: 'module' });
+  const pass = createEvasiveTransformPass();
+  traverse(ast, pass.visitor);
+  const { code } = generate(ast);
+  t.false(code.includes(`import('foo')`));
+});
+
+test('evasive transform pass rewrites HTML comments', t => {
+  const source = `const x = 1; /* <!-- comment --> */`;
+  const ast = parse(source, { sourceType: 'module' });
+  const pass = createEvasiveTransformPass();
+  traverse(ast, pass.visitor);
+  const { code } = generate(ast);
+  t.false(code.includes('<!--'));
+});
+
+test('evasive transform pass respects elideComments option', t => {
+  const source = `/* some comment */ const x = 1;`;
+  const ast = parse(source, { sourceType: 'module' });
+  const pass = createEvasiveTransformPass({ elideComments: true });
+  traverse(ast, pass.visitor);
+  const { code } = generate(ast);
+  t.false(code.includes('some comment'));
+});
+
+test('evasive transform pass with onlyComments skips code transforms', t => {
+  const source = `const x = "import('foo')"; /* <!-- --> */`;
+  const ast = parse(source, { sourceType: 'module' });
+  const pass = createEvasiveTransformPass({ onlyComments: true });
+  traverse(ast, pass.visitor);
+  const { code } = generate(ast);
+  t.true(code.includes(`import('foo')`), 'string should not be modified');
+  t.false(code.includes('<!--'), 'comment should still be rewritten');
+});

packages/evasive-transform/tsconfig.json

@@ -1,13 +1,14 @@
 {
-  "extends": "../../tsconfig.eslint-base.json",
   "compilerOptions": {
     "allowJs": true,
-    "allowSyntheticDefaultImports": true
+    "allowSyntheticDefaultImports": true,
+    "stripInternal": true
   },
+  "extends": "../../tsconfig.eslint-base.json",
   "include": [
     "*.js",
     "*.ts",
     "src",
     "test"
   ]
-}
+}