JavaScript: spawn Java RPC server for TS integration tests

[knutwannheden]

Motivation

Both rewrite-python and rewrite-csharp already ship a small test-only client that spawns org.openrewrite.maven.rpc.JavaRewriteRpc and talks to it over JSON-RPC. This gives those languages an easy way to drive real Java recipes (e.g. ChangeType, ChangeMethodName) from their native test runners — and, in production, lets a TS recipe delegate part of its work to a Java recipe.

rewrite-javascript did not have an equivalent. Adding it unblocks TS-side tests for Java-ported recipes — most immediately the dependency-management recipes on #7795, where the TS-side recipe files have been deleted in favor of Java recipes and the tests need to verify them through RPC. It also gives TS recipes a stable way to delegate to Java recipes that works identically in test (TS spawned the JVM) and production (Java spawned the TS server).

The key insight that keeps this small: RewriteRpc is already symmetric — when given a MessageConnection wired to a child process's stdio, the same class drives Java as a client. No new sender/receiver/codec logic needed; just the process lifecycle, classpath discovery, a vitest fixture for test ergonomics, and a small helper for the recipe-author surface.

Examples

Tests

The intended consumer API uses the vitest fixture from @openrewrite/rewrite/test/java-rpc:

import {describeJavaRpc, testJavaRpc} from "@openrewrite/rewrite/test/java-rpc";
import {RecipeSpec} from "@openrewrite/rewrite/test";
import {text} from "@openrewrite/rewrite/text";

describeJavaRpc("Java recipe via RPC", () => {
    testJavaRpc("FindAndReplace edits a parsed source", async ({javaRpc: _}) => {
        const spec = new RecipeSpec();
        spec.recipe = await prepareJavaRecipe(
            "org.openrewrite.text.FindAndReplace",
            {find: "Hello", replace: "Goodbye"},
        );
        await spec.rewriteRun({
            ...text("Hello, world!", "Goodbye, world!"),
            path: "greeting.txt",
        });
    });
});

testJavaRpc is a test.extend-based vitest API. The javaRpc fixture combines:

• A worker-scoped JavaRpcTestServer — one JVM per vitest worker, spawned lazily on first use, disposed on worker exit.
• A test-scoped wrapper that calls RewriteRpc.reset() before every test so each test starts with both Java-side and TS-side state cleared.

describeJavaRpc is a describe that auto-skips when no Java classpath is configured. No boilerplate beforeAll / afterAll per file.

TS recipes delegating to Java

prepareJavaRecipe(id, options?) resolves the active RewriteRpc via the static accessor and routes a PrepareRecipe request to whichever side hosts the Java implementation:

• in tests, the JVM spawned via the testJavaRpc fixture
• in production, the Java host that spawned dist/rpc/server.js

Same code, both topologies:

import {Recipe, ExecutionContext, TreeVisitor} from "@openrewrite/rewrite";
import {prepareJavaRecipe} from "@openrewrite/rewrite/rpc";

export class MigrateLegacyApi extends Recipe {
    readonly name = "org.openrewrite.javascript.MigrateLegacyApi";
    readonly displayName = "Migrate legacy API";
    readonly description = "...";

    async editor(): Promise<TreeVisitor<any, ExecutionContext>> {
        const renameType = await prepareJavaRecipe(
            "org.openrewrite.java.ChangeType",
            {oldFullyQualifiedTypeName: "legacy.Api", newFullyQualifiedTypeName: "modern.Api"},
        );
        return await renameType.editor();
    }
}

The RpcRecipe returned by prepareJavaRecipe already extends Recipe, so it composes naturally — as the editor of a check(usesType(...), ...) precondition, as a step inside a recipeList(), or assigned directly to RecipeSpec.recipe.

Top-level functions per Java recipe (downstream pattern)

For Java recipes that are commonly used as building blocks, the natural pattern is to expose a top-level function:

// e.g. src/javascript/recipes/dependencies.ts (to land on #7795)
export interface AddDependencyOptions {
    name: string;
    version: string;
    type?: "dependencies" | "devDependencies" | "peerDependencies" | "optionalDependencies";
}
export function addDependency(options: AddDependencyOptions): Promise<Recipe> {
    return prepareJavaRecipe("org.openrewrite.javascript.AddDependency", options);
}

Consumers compose these as recipes or as recipe-list steps:

export class MigrateToLodashEs extends Recipe {
    async recipeList(): Promise<Recipe[]> {
        return [
            await removeDependency({name: "lodash"}),
            await addDependency({name: "lodash-es", version: "^4.17.21"}),
        ];
    }
}

This PR ships only the prepareJavaRecipe primitive — wrapper functions for specific recipes belong with the recipes they wrap and will land on #7795.

Setup

./gradlew :rewrite-javascript:generateTestClasspath   # explicit
./gradlew :rewrite-javascript:test                    # implicit — npmTest now depends on it

./gradlew :rewrite-javascript:npmTest is wired to depend on generateTestClasspath, mirroring the existing C# setup. Devs running npx vitest directly still need to invoke the Gradle task once (or use REWRITE_JAVASCRIPT_CLASSPATH to override).

Summary

• New :rewrite-javascript:generateTestClasspath Gradle task writes the runtime + test classpath to rewrite-javascript/rewrite/test-classpath.txt (gitignored). Adds testRuntimeOnly(project(":rewrite-maven")) so JavaRewriteRpc's main class is included.
• :rewrite-javascript:npmTest now depends on generateTestClasspath, so the standard Gradle test entry point picks up the RPC tests automatically.
• New rewrite-javascript/rewrite/src/rpc/java-rpc-client.ts:
  • JavaRpcTestServer.start(opts?) spawns java -cp <classpath> org.openrewrite.maven.rpc.JavaRewriteRpc, wraps stdio in a vscode-jsonrpc MessageConnection, and constructs a RewriteRpc against it.
  • reset() delegates to RewriteRpc.reset(); dispose() ends the connection, waits with a grace period before SIGKILL.
  • Forwards Java stderr line-by-line with a [Java RPC] prefix; detects early JVM exit and surfaces it rather than letting the first request hang.
  • findTestClasspath() checks REWRITE_JAVASCRIPT_CLASSPATH then walks for test-classpath.txt.
• New RewriteRpc.reset() method mirroring Java's pattern: send Reset to the remote and clear local caches. The existing inbound Reset handler still only clears local — no recursion.
• New rewrite-javascript/rewrite/src/rpc/java-recipe.ts — prepareJavaRecipe(id, options?) helper for TS recipes that delegate to a Java recipe. Exported from @openrewrite/rewrite/rpc.
• New rewrite-javascript/rewrite/src/test/java-rpc.ts — testJavaRpc + describeJavaRpc vitest fixture, exposed as the @openrewrite/rewrite/test/java-rpc subpath export. Worker-scoped JVM, per-test reset, auto-skip when no classpath.
• Smoke test at rewrite-javascript/rewrite/test/rpc/java-recipe-via-rpc.test.ts exercising both the direct (javaRpc.rpc.prepareRecipe) and recipe-author (prepareJavaRecipe) surfaces against org.openrewrite.text.FindAndReplace end-to-end.
• Short "Java RPC Integration Tests" section in rewrite-javascript/rewrite/CLAUDE.md.

Out of scope: wrapper functions / classes for specific Java recipes (addDependency, changeType, etc.) — those land with the recipes themselves.

Test plan

• ./gradlew :rewrite-javascript:generateTestClasspath produces rewrite-javascript/rewrite/test-classpath.txt.
• ./gradlew :rewrite-javascript:npmTest auto-runs generateTestClasspath first.
• Smoke test passes against a real Java JVM (npx vitest run test/rpc/java-recipe-via-rpc.test.ts).
• Full test/rpc/ suite still green (43 tests, 1 pre-existing skipped).
• npm run typecheck is clean.
• Test skips with a helpful warning when classpath is absent (REWRITE_JAVASCRIPT_CLASSPATH= rm -f test-classpath.txt && npx vitest run test/rpc/java-recipe-via-rpc.test.ts).
• No orphan java ... JavaRewriteRpc processes after a test run.