[32] Refactor from "replacement processors" to "engines" & add AsyncLookaheadTransformEngine (#38)

* Refactor to "engines" from "replacement processors"
* Add codemod for engines
* Add async lookahead engine and related concurrency strategies
* prepublishOnly -> prepack
* added note re: contrived search strategy to ensure regex construction cost to regex callback benchmark strategy

Author: TomStrepsil

README.md

@@ -4,4 +4,9 @@ This directory contains migration codemods for breaking API changes.
 
 ## Available Codemods
 
-### v1 -> v2: [`replacement-callback-positional-to-context`](./transforms/v1-v2/README.md)
+### v1 -> v2: [two-step migration](./transforms/v1-v2/README.md)
+
+Run in order:
+
+1. `replacement-callback-positional-to-context` — migrates callback signatures from positional args to a context object
+2. `processor-to-engine` — renames processor classes to engines, moves `stopReplacingSignal`, strips dropped type parameters

codemods/README.md

@@ -6,6 +6,7 @@
   "type": "module",
   "scripts": {
     "codemod:replacement-callback-context": "jscodeshift -t transforms/v1-v2/replacement-callback-positional-to-context.js --parser=tsx --extensions=js,jsx,ts,tsx,mjs",
+    "codemod:processor-to-engine": "jscodeshift -t transforms/v1-v2/processor-to-engine.js --parser=tsx --extensions=js,jsx,ts,tsx,mjs",
     "test": "vitest run"
   },
   "devDependencies": {

codemods/package.json

@@ -1,4 +1,8 @@
-# `replacement-callback-positional-to-context`
+# v1 → v2 migration codemods
+
+Run these in order. Each transform is idempotent, so re-running a step that has already been applied is safe.
+
+## Step 1 — `replacement-callback-positional-to-context`
 
 Transforms replacement callback signatures from positional arguments to a context-object form.
 
@@ -16,8 +20,6 @@ replacement: (match, { matchIndex }) => `#${matchIndex}: ${match}`
 replacement: (match, { matchIndex, streamIndices }) => `${streamIndices[0]}-${streamIndices[1]}`
 ```
 
-## Usage
-
 Dry run:
 
 ```bash
@@ -30,15 +32,82 @@ Apply changes:
 npm run codemod:replacement-callback-context -- src
 ```
 
-Narrow by extensions if needed:
+### Notes
+
+- Only updates inline function/arrow callbacks under a `replacement` property.
+- Existing context-object signatures are left unchanged.
+- If the third positional arg is destructured inline (for example, `[startIndex, endIndex]`), the transform intentionally skips that callback for manual migration.
+- Non-standard callback signatures are skipped for safety and should be migrated manually.
+
+---
+
+## Step 2 — `processor-to-engine`
+
+Renames the deprecated processor classes to their engine equivalents, moves `stopReplacingSignal` from the adapter constructor into the engine options when the engine is inlined, and strips the now-dropped type parameter from adapter constructors.
+
+| Old | New |
+|---|---|
+| `StaticReplacementProcessor` | `SyncReplacementTransformEngine` |
+| `FunctionReplacementProcessor` | `SyncReplacementTransformEngine` |
+| `IterableFunctionReplacementProcessor` | `SyncReplacementTransformEngine` |
+| `AsyncFunctionReplacementProcessor` | `AsyncSerialReplacementTransformEngine` |
+| `AsyncIterableFunctionReplacementProcessor` | `AsyncSerialReplacementTransformEngine` |
+
+Before:
+
+```ts
+import { FunctionReplacementProcessor } from "replace-content-transformer";
+
+const engine = new FunctionReplacementProcessor({
+  searchStrategy,
+  replacement: (match, { matchIndex }) => `${matchIndex}: ${match}`,
+});
+
+const transformer = new ReplaceContentTransformer<Promise<string>>(engine, abortController.signal);
+```
+
+After:
+
+```ts
+import { SyncReplacementTransformEngine } from "replace-content-transformer";
+
+const engine = new SyncReplacementTransformEngine({
+  searchStrategy,
+  replacement: (match, { matchIndex }) => `${matchIndex}: ${match}`,
+});
+
+const transformer = new ReplaceContentTransformer(engine);
+```
+
+When the engine is constructed inline in the adapter call, `stopReplacingSignal` is moved automatically:
+
+```ts
+// Before
+const t = new ReplaceContentTransformer(
+  new FunctionReplacementProcessor({ searchStrategy, replacement }),
+  abortController.signal
+);
+
+// After
+const t = new ReplaceContentTransformer(
+  new SyncReplacementTransformEngine({ searchStrategy, replacement, stopReplacingSignal: abortController.signal })
+);
+```
+
+Dry run:
 
 ```bash
-npm run codemod:replacement-callback-context -- --extensions=ts,tsx "src/**/*.ts"
+npm run codemod:processor-to-engine -- --dry --print src
 ```
 
-## Notes
+Apply changes:
 
-- The transform only updates inline function/arrow callbacks under a `replacement` property.
-- Existing context-object signatures are left unchanged.
-- If the third positional arg is destructured inline (for example, `[startIndex, endIndex]`), the transform intentionally skips that callback for manual migration.
-- Non-standard callback signatures are skipped for safety and should be migrated manually.
+```bash
+npm run codemod:processor-to-engine -- src
+```
+
+### Notes
+
+- Aliased imports (`import { FunctionReplacementProcessor as FRP }`) are not renamed; update the alias and its usages manually.
+- When `stopReplacingSignal` is held in a variable and passed by reference (not inline), it cannot be moved automatically — TypeScript will surface the remaining mismatch as a type error.
+- If you previously used `AsyncFunctionReplacementProcessor` or `AsyncIterableFunctionReplacementProcessor` and want concurrent lookahead semantics, migrate to `AsyncLookaheadTransformEngine` manually; the codemod maps to the conservative `AsyncSerialReplacementTransformEngine` which preserves identical serial behaviour.

codemods/transforms/v1-v2/README.md

@@ -0,0 +1,154 @@
+/**
+ * Codemod: replacement processors -> transform engines (v1 -> v2)
+ *
+ * Run this AFTER replacement-callback-positional-to-context.
+ *
+ * Transforms:
+ *   1. Renames the five deprecated processor classes to their engine equivalents
+ *      in both `new` expressions and named import specifiers.
+ *   2. Deduplicates import specifiers when multiple processors map to the same
+ *      engine name (e.g. FunctionReplacementProcessor and StaticReplacementProcessor
+ *      both become SyncReplacementTransformEngine).
+ *   3. When an engine is constructed inline as the first argument of an adapter
+ *      constructor and a stopReplacingSignal is passed as the second argument,
+ *      moves the signal into the engine options object and removes it from the
+ *      adapter call.
+ *   4. Strips the now-dropped type parameter from adapter constructors
+ *      (e.g. new ReplaceContentTransformer<Promise<string>>(...)).
+ *
+ * Processor -> Engine mapping:
+ *   StaticReplacementProcessor            -> SyncReplacementTransformEngine
+ *   FunctionReplacementProcessor          -> SyncReplacementTransformEngine
+ *   IterableFunctionReplacementProcessor  -> SyncReplacementTransformEngine
+ *   AsyncFunctionReplacementProcessor     -> AsyncSerialReplacementTransformEngine
+ *   AsyncIterableFunctionReplacementProcessor -> AsyncSerialReplacementTransformEngine
+ *
+ * Limitations:
+ *   - Aliased imports (import { FunctionReplacementProcessor as FRP }) are not
+ *     renamed; the local alias and all its usages must be updated manually.
+ *   - When stopReplacingSignal is held in a variable rather than inlined,
+ *     it cannot be moved automatically; TypeScript will surface the remaining
+ *     mismatch after migration.
+ */
+
+const PROCESSOR_TO_ENGINE = new Map([
+  ["StaticReplacementProcessor", "SyncReplacementTransformEngine"],
+  ["FunctionReplacementProcessor", "SyncReplacementTransformEngine"],
+  ["IterableFunctionReplacementProcessor", "SyncReplacementTransformEngine"],
+  ["AsyncFunctionReplacementProcessor", "AsyncSerialReplacementTransformEngine"],
+  [
+    "AsyncIterableFunctionReplacementProcessor",
+    "AsyncSerialReplacementTransformEngine",
+  ],
+]);
+
+const ADAPTER_NAMES = new Set([
+  "ReplaceContentTransformer",
+  "AsyncReplaceContentTransformer",
+  "ReplaceContentTransform",
+  "AsyncReplaceContentTransform",
+]);
+
+function identifierName(node) {
+  return node?.type === "Identifier" ? node.name : null;
+}
+
+export default function processorToEngine(fileInfo, api) {
+  const j = api.jscodeshift;
+  const root = j(fileInfo.source);
+  let changed = false;
+
+  // 1. Rename processor import specifiers
+  root.find(j.ImportSpecifier).forEach((path) => {
+    const name = identifierName(path.node.imported);
+    if (!name) return;
+    const engineName = PROCESSOR_TO_ENGINE.get(name);
+    if (!engineName) return;
+
+    const isShorthand = path.node.local.name === name;
+    path.node.imported = j.identifier(engineName);
+    if (isShorthand) {
+      path.node.local = j.identifier(engineName);
+    }
+    changed = true;
+  });
+
+  // Deduplicate specifiers: multiple processors may collapse to the same engine name
+  root.find(j.ImportDeclaration).forEach((path) => {
+    const before = path.node.specifiers.length;
+    const seen = new Set();
+    path.node.specifiers = path.node.specifiers.filter((spec) => {
+      if (spec.type !== "ImportSpecifier") return true;
+      const key = `${identifierName(spec.imported)}:${spec.local.name}`;
+      if (seen.has(key)) return false;
+      seen.add(key);
+      return true;
+    });
+    if (path.node.specifiers.length !== before) changed = true;
+  });
+
+  // 2. Rename new XxxProcessor(...) expressions
+  root
+    .find(j.NewExpression, (node) => {
+      const name = identifierName(node.callee);
+      return name != null && PROCESSOR_TO_ENGINE.has(name);
+    })
+    .forEach((path) => {
+      path.node.callee = j.identifier(
+        PROCESSOR_TO_ENGINE.get(path.node.callee.name)
+      );
+      changed = true;
+    });
+
+  // 3. Move inline stopReplacingSignal from adapter 2nd arg into engine options
+  // Matches: new Adapter(new Engine({ ... }), signal)
+  // Produces: new Adapter(new Engine({ ..., stopReplacingSignal: signal }))
+  root
+    .find(j.NewExpression, (node) => {
+      const name = identifierName(node.callee);
+      return (
+        name != null &&
+        ADAPTER_NAMES.has(name) &&
+        node.arguments.length === 2 &&
+        node.arguments[0]?.type === "NewExpression"
+      );
+    })
+    .forEach((path) => {
+      const [engineNew, signalArg] = path.node.arguments;
+      const engineArgs = engineNew.arguments;
+
+      if (
+        engineArgs.length !== 1 ||
+        engineArgs[0].type !== "ObjectExpression"
+      ) {
+        return;
+      }
+
+      engineArgs[0].properties.push(
+        j.property(
+          "init",
+          j.identifier("stopReplacingSignal"),
+          signalArg
+        )
+      );
+      path.node.arguments = [engineNew];
+      changed = true;
+    });
+
+  // 4. Strip type parameters from adapter constructors
+  // e.g. new ReplaceContentTransformer<Promise<string>>(...) -> new ReplaceContentTransformer(...)
+  root
+    .find(j.NewExpression, (node) => {
+      const name = identifierName(node.callee);
+      return name != null && ADAPTER_NAMES.has(name) && node.typeParameters != null;
+    })
+    .forEach((path) => {
+      path.node.typeParameters = null;
+      changed = true;
+    });
+
+  if (!changed) return null;
+  return root.toSource();
+}
+
+export const parser = "tsx";