@openrewrite/rewrite 8.91.4 → 8.91.6

package/src/javascript/scope.ts

@@ -152,6 +152,69 @@ export function namesDeclaredWithin(node: unknown, cacheKey: object = node as ob
     return names;
 }
 
+/**
+ * The names `node` reads and nothing within it binds, so each one reaches a binding further out.
+ * A name its parent introduces rather than reads is not one, nor is a name an inner scope rebinds:
+ * that reference reads the rebinding.
+ */
+export function namesReferencedWithin(node: unknown, cacheKey: object = node as object): ReadonlySet<string> {
+    if (cacheKey === null || typeof cacheKey !== 'object') {
+        return noNames;
+    }
+    const cached = referenced.get(cacheKey);
+    if (cached) {
+        return cached;
+    }
+    const names = new Set<string>();
+    collectReferences(node, undefined, undefined, names);
+    referenced.set(cacheKey, names);
+    return names;
+}
+
+/** The scopes enclosing a node, innermost first, each paired with what {@link frameBindings} reads. */
+interface Frames {
+    node: unknown;
+    parent: unknown;
+    outer?: Frames;
+}
+
+/** Whether a scope between the name and where the walk began binds it. */
+function shadowed(scopes: Frames | undefined, name: string): boolean {
+    for (let scope = scopes; scope; scope = scope.outer) {
+        if (frameBindings(scope.node, scope.parent).has(name)) {
+            return true;
+        }
+    }
+    return false;
+}
+
+function collectReferences(node: unknown, parent: unknown, scopes: Frames | undefined, names: Set<string>): void {
+    if (Array.isArray(node)) {
+        node.forEach(child => collectReferences(child, parent, scopes, names));
+        return;
+    }
+    const kind = (node as { kind?: string } | undefined)?.kind;
+    if (kind === J.Kind.RightPadded || kind === J.Kind.LeftPadded) {
+        // A naming position reads against the tree parent, so padding forwards the one it was handed.
+        collectReferences((node as J.RightPadded<any>).element, parent, scopes, names);
+        return;
+    }
+    if (kind === J.Kind.Container) {
+        collectReferences((node as J.Container<any>).elements, parent, scopes, names);
+        return;
+    }
+    if (!isTree(node)) {
+        return;
+    }
+    const name = kind === J.Kind.Identifier ? (node as J.Identifier).simpleName : undefined;
+    if (name && reads(node as J.Identifier, parent) && !shadowed(scopes, name)) {
+        names.add(name);
+    }
+    const within = scopeKinds.has(kind!) ? {node, parent, outer: scopes} : scopes;
+    Object.entries(node as object).forEach(([key, value]) =>
+        key !== 'markers' && collectReferences(value, node, within, names));
+}
+
 /**
  * Every name a binding pattern introduces. `member` is the property a name takes its value from,
  * which only a name an object pattern binds directly has: anything deeper reads a property of a
@@ -213,8 +276,12 @@ function frameBindings(node: any, parent: any): ReadonlySet<string> {
     // A function expression is the only function whose own name its body reaches: a declaration's
     // name belongs to the enclosing block, a method's to an instance.
     if (node?.kind === J.Kind.MethodDeclaration && parent?.kind === JS.Kind.StatementExpression) {
-        const self = bindingNames((node as J.MethodDeclaration).name).map(bound => bound.name);
-        return new Set([...self, ...ownBindings(node)]);
+        let names = selfNamed.get(node);
+        if (!names) {
+            const self = bindingNames((node as J.MethodDeclaration).name).map(bound => bound.name);
+            selfNamed.set(node, names = new Set([...self, ...ownBindings(node)]));
+        }
+        return names;
     }
     return ownBindings(node);
 }
@@ -369,7 +436,9 @@ const blockScoped = new Set(['let', 'const', 'using']);
 const hoisted = new WeakMap<object, string[]>();
 const declared = new WeakMap<object, ReadonlySet<string>>();
 const used = new WeakMap<object, ReadonlySet<string>>();
+const referenced = new WeakMap<object, ReadonlySet<string>>();
 const frames = new WeakMap<object, ReadonlySet<string>>();
+const selfNamed = new WeakMap<object, ReadonlySet<string>>();
 
 /**
  * The names blocks under `scope` hoist out to it. A `var` or function declaration reaches the whole
@@ -496,19 +565,46 @@ export function isValueReference(cursor: Cursor, identifier: J.Identifier): bool
     while (c && isPadding(c.value)) {
         c = c.parent;
     }
-    const parent = c?.value as
-        { kind?: string; name?: unknown; key?: unknown; label?: unknown; select?: unknown } | undefined;
+    return references(identifier, c?.value);
+}
+
+/** The position half of {@link isValueReference}, against a parent already found. */
+function references(identifier: J.Identifier, parent: unknown): boolean {
+    const owner = parent as {
+        kind?: string; name?: unknown; key?: unknown; label?: unknown; select?: unknown;
+        propertyName?: unknown;
+    } | undefined;
 
     // A call names a member of whatever it selects from. With nothing selected there is no member,
     // and its `name` is a reference to the function being called.
-    if (parent?.kind === J.Kind.MethodInvocation && !parent.select) {
+    if (owner?.kind === J.Kind.MethodInvocation && !owner.select) {
         return true;
     }
 
+    // A binding element names the property it destructures and binds under `name`, so both slots
+    // name rather than reference.
+    if (owner?.kind === JS.Kind.BindingElement && holds(owner.propertyName, identifier)) {
+        return false;
+    }
+
     // A JSX attribute keeps its prop name on `key`; the three label-bearing nodes keep theirs on
     // `label`. Every other kind that names rather than references keeps it on `name`.
-    const named = parent?.kind === JS.Kind.JsxAttribute ? parent.key : (parent?.name ?? parent?.label);
-    return named !== identifier && (named as { element?: unknown } | undefined)?.element !== identifier;
+    return !holds(owner?.kind === JS.Kind.JsxAttribute ? owner.key : (owner?.name ?? owner?.label), identifier);
+}
+
+/** Whether a node slot, padded or not, is the identifier itself. */
+function holds(slot: unknown, identifier: J.Identifier): boolean {
+    return slot === identifier || (slot as { element?: unknown } | undefined)?.element === identifier;
+}
+
+/**
+ * As {@link references}, for a collector rather than a renamer: a shorthand property's name slot is
+ * also the value it reads, which a rename has to expand rather than follow.
+ */
+function reads(identifier: J.Identifier, parent: unknown): boolean {
+    const owner = parent as { kind?: string; initializer?: unknown } | undefined;
+    return (owner?.kind === JS.Kind.PropertyAssignment && owner.initializer === undefined) ||
+        references(identifier, parent);
 }
 
 function isPadding(value: unknown): boolean {

package/src/rpc/index.ts

@@ -33,7 +33,7 @@ export * from "./queue";
 export * from "../reference";
 export {RewriteRpc} from "./rewrite-rpc";
 export {RpcRecipe, RpcVisitor} from "./recipe";
-export {prepareJavaRecipe} from "./java-recipe";
+export {DelegatingRecipe, prepareJavaRecipe} from "./java-recipe";
 export {registerVisitor} from "./request/visitor-registry";
 
 RpcCodecs.registerCodec(TreeKind.Checksum, {

package/src/rpc/java-recipe.ts

@@ -1,5 +1,5 @@
 /*
- * Copyright 2025 the original author or authors.
+ * Copyright 2026 the original author or authors.
  * <p>
  * Licensed under the Moderne Source Available License (the "License");
  * you may not use this file except in compliance with the License.
@@ -15,23 +15,110 @@
  */
 import {RewriteRpc} from "./rewrite-rpc";
 import type {RpcRecipe} from "./recipe";
+import {Recipe, RecipeDescriptor, ScanningRecipe} from "../recipe";
+import {TreeVisitor} from "../visitor";
+import {ExecutionContext} from "../execution";
+import {SourceFile} from "../tree";
 
 /**
- * Prepare a Java recipe via the active {@link RewriteRpc} connection.
- *
- * Routes a `PrepareRecipe` request to whichever side hosts the Java
- * implementation:
- *  - in production, the Java host that spawned the TS server (`dist/rpc/server.js`);
- *  - in tests, the JVM spawned via `JavaRpcTestServer` (see
- *    `@openrewrite/rewrite/test/java-rpc`).
- *
- * The returned {@link RpcRecipe} extends `Recipe`, so it can be used directly
- * as a recipe — e.g. assigned to `RecipeSpec.recipe` — or composed inside a
- * larger TS recipe (as the editor of a `check(usesType(...), ...)`
- * precondition, or as a step in `recipeList()`).
- *
- * Top-level convenience functions for specific Java recipes (e.g.
- * `addDependency`, `changeType`) sit naturally on top of this primitive:
+ * A stand-in for a Java recipe, composable like any other recipe (a `recipeList()` entry, a
+ * `check(...)` gate, a `RecipeSpec.recipe`). The Java host resolves it by name: from `delegatesTo`
+ * when it prepares the enclosing recipe, or by class name when it gates a visitor, like a `RecipeRef`.
+ * Only when this process runs it itself (a test, a JS-hosted run) is it prepared over the active
+ * {@link RewriteRpc} connection, on first use.
+ */
+export class DelegatingRecipe extends ScanningRecipe<number> {
+    readonly name: string;
+    readonly displayName: string;
+    readonly description: string;
+    private delegate?: {rpc: RewriteRpc, recipe: Promise<RpcRecipe>};
+
+    constructor(readonly javaRecipeName: string,
+                readonly delegatesToOptions: Record<string, any>) {
+        super();
+        this.name = javaRecipeName;
+        this.displayName = javaRecipeName;
+        this.description = `Delegates to the Java recipe \`${javaRecipeName}\`.`;
+    }
+
+    // Local, with an empty recipe list: the host fills the subtree in, and recipeList() prepares the delegate.
+    async descriptor(): Promise<RecipeDescriptor> {
+        return {
+            name: this.name,
+            displayName: this.displayName,
+            instanceName: this.instanceName(),
+            description: this.description,
+            tags: this.tags,
+            estimatedEffortPerOccurrence: this.estimatedEffortPerOccurrence,
+            options: Object.entries(this.delegatesToOptions).map(([name, value]) => ({
+                name,
+                value,
+                displayName: name,
+                description: "",
+                required: false
+            })),
+            preconditions: [],
+            recipeList: [],
+            dataTables: this.dataTables,
+            maintainers: [],
+            contributors: [],
+            examples: []
+        };
+    }
+
+    async recipeList(): Promise<Recipe[]> {
+        return (await this.prepared()).recipeList();
+    }
+
+    initialValue(_ctx: ExecutionContext): number {
+        return 0;
+    }
+
+    async editorWithData(acc: number): Promise<TreeVisitor<any, ExecutionContext>> {
+        return (await this.prepared()).editorWithData(acc);
+    }
+
+    async scanner(acc: number): Promise<TreeVisitor<any, ExecutionContext>> {
+        return (await this.prepared()).scanner(acc);
+    }
+
+    async generate(acc: number, ctx: ExecutionContext): Promise<SourceFile[]> {
+        return (await this.prepared()).generate(acc, ctx);
+    }
+
+    async onComplete(ctx: ExecutionContext): Promise<void> {
+        if (this.delegate) {
+            await (await this.delegate.recipe).onComplete(ctx);
+        }
+    }
+
+    private prepared(): Promise<RpcRecipe> {
+        const rpc = RewriteRpc.get();
+        if (!rpc) {
+            throw new Error(
+                `Cannot run Java recipe "${this.javaRecipeName}": no active RewriteRpc connection.\n` +
+                "  • Tests: spawn one via JavaRpcTestServer.start() — see " +
+                "@openrewrite/rewrite/test/java-rpc.\n" +
+                "  • Production: the Java host provides one automatically when it " +
+                "loads the TS recipe artifact."
+            );
+        }
+        // Prepared once per connection; a failed prepare is dropped so the next use retries.
+        if (!this.delegate || this.delegate.rpc !== rpc) {
+            const recipe = rpc.prepareRecipe(this.javaRecipeName, this.delegatesToOptions);
+            this.delegate = {rpc, recipe};
+            recipe.catch(() => {
+                if (this.delegate?.recipe === recipe) {
+                    this.delegate = undefined;
+                }
+            });
+        }
+        return this.delegate.recipe;
+    }
+}
+
+/**
+ * Reference a Java recipe by name from a TS recipe:
  *
  * ```ts
  * export function addDependency(options: AddDependencyOptions): Promise<Recipe> {
@@ -39,26 +126,13 @@ import type {RpcRecipe} from "./recipe";
  * }
  * ```
  *
- * There is no in-process fallback by design: a Java recipe's editor is the
- * single source of truth — we don't reimplement editing recipes in TS. For
- * preconditions that need a graceful no-RPC fallback, use the {@link RecipeRef}
+ * There is no in-process fallback by design: a Java recipe's editor is the single source of
+ * truth. For preconditions that need a graceful no-RPC fallback, use the {@link RecipeRef}
  * pattern via `usesType` / `usesMethod`, which carries a `localVisitor`.
- *
- * @throws Error when no active {@link RewriteRpc} connection is registered.
  */
 export async function prepareJavaRecipe(
     id: string,
     options?: Record<string, any>,
-): Promise<RpcRecipe> {
-    const rpc = RewriteRpc.get();
-    if (!rpc) {
-        throw new Error(
-            `Cannot prepare Java recipe "${id}": no active RewriteRpc connection.\n` +
-            "  • Tests: spawn one via JavaRpcTestServer.start() — see " +
-            "@openrewrite/rewrite/test/java-rpc.\n" +
-            "  • Production: the Java host provides one automatically when it " +
-            "loads the TS recipe artifact."
-        );
-    }
-    return rpc.prepareRecipe(id, options);
+): Promise<DelegatingRecipe> {
+    return new DelegatingRecipe(id, options ?? {});
 }

package/src/rpc/request/prepare-recipe.ts

@@ -19,6 +19,7 @@ import {Recipe, RecipeDescriptor, ScanningRecipe} from "../../recipe";
 import {SnowflakeId} from "@akashrajpurohit/snowflake-id";
 import {Check, CheckArg, CompositePrecondition, RecipeRef} from "../../preconditions";
 import {RpcRecipe} from "../recipe";
+import {DelegatingRecipe} from "../java-recipe";
 import {TreeVisitor} from "../../visitor";
 import {ExecutionContext} from "../../execution";
 import {withMetrics} from "./metrics";
@@ -42,22 +43,10 @@ export class PrepareRecipe {
                     context.target = request.id;
                     const recipeCtor = marketplace.findRecipe(request.id);
                     if (!recipeCtor) {
-                        // A miss means the host owns this recipe (e.g. a sub-recipe that delegates to
-                        // a Java recipe, produced by prepareJavaRecipe — an RpcRecipe hosted on the peer
-                        // with no no-arg constructor to register here). Tell the host to resolve the id
-                        // locally via delegatesTo rather than failing with "Could not find recipe ...".
-                        const id = snowflake.generate();
-                        return {
-                            id: id,
-                            descriptor: PrepareRecipe.delegateDescriptor(request.id),
-                            editVisitor: `edit:${id}`,
-                            editPreconditions: [],
-                            scanPreconditions: [],
-                            delegatesTo: {
-                                recipeName: request.id,
-                                options: request.options ?? {}
-                            }
-                        };
+                        // A miss means the host owns this recipe (e.g. a Java-delegate child a host
+                        // re-prepares by name), so answer with a delegatesTo stand-in for it to resolve.
+                        return await PrepareRecipe.prepareInstance(new DelegatingRecipe(request.id, request.options ?? {}),
+                            snowflake, preparedRecipes, marketplace);
                     }
                     if (!recipeCtor[1]) {
                         throw new Error(`Recipe ${request.id} was installed without a constructor`);
@@ -70,44 +59,30 @@ export class PrepareRecipe {
     }
 
     /**
-     * Minimal stand-in descriptor for a recipe the host will resolve locally via
-     * {@link PrepareRecipeResponse.delegatesTo}. The host reads only `delegatesTo` for
-     * delegated recipes and ignores this descriptor, but the response type requires one.
-     */
-    private static delegateDescriptor(name: string): RecipeDescriptor {
-        return {
-            name: name,
-            displayName: name,
-            instanceName: name,
-            description: "",
-            tags: [],
-            estimatedEffortPerOccurrence: 5,
-            options: [],
-            preconditions: [],
-            recipeList: [],
-            dataTables: [],
-            maintainers: [],
-            contributors: [],
-            examples: []
-        };
-    }
-
-    /**
-     * Prepares a recipe instance and recursively its whole child tree, registering every node in
-     * {@code preparedRecipes} and returning the prepared response with {@code recipeList} populated,
-     * so the host builds the tree locally instead of a PrepareRecipe round-trip per child.
-     *
-     * Mirrors the C# server's PrepareInstance. Required options are validated as each node is
-     * prepared (covering the whole tree). A child hosted on the peer (an {@link RpcRecipe}, e.g. from
-     * prepareJavaRecipe) carries only {@code delegatesTo} for the host to resolve locally; every other
-     * child carries its own {@code recipeList}. Delegating recipes forward validation to the recipe
-     * they delegate to, so they are not validated here.
+     * Prepares a recipe and, recursively, its whole child tree, registering every node in
+     * {@code preparedRecipes}; the response carries {@code recipeList} so the host builds the tree
+     * without a PrepareRecipe round-trip per child (mirrors the C# server's PrepareInstance).
+     * Required options are validated per node. A stand-in for a host recipe (see {@link #delegatesTo})
+     * carries only {@code delegatesTo} and leaves validation to the host.
      */
     private static async prepareInstance(recipe: Recipe,
                                          snowflake: ReturnType<typeof SnowflakeId>,
                                          preparedRecipes: Map<String, Recipe>,
                                          marketplace: RecipeMarketplace): Promise<PrepareRecipeResponse> {
         const id = snowflake.generate();
+        const delegatesTo = PrepareRecipe.delegatesTo(recipe);
+        if (delegatesTo) {
+            // Registered so a peer that visits `edit:<id>` instead of honouring delegatesTo reaches it.
+            preparedRecipes.set(id, recipe);
+            return {
+                id: id,
+                descriptor: await recipe.descriptor(),
+                editVisitor: `edit:${id}`,
+                editPreconditions: [],
+                scanPreconditions: [],
+                delegatesTo
+            };
+        }
 
         const editPreconditions: Precondition[] = [];
         recipe = await PrepareRecipe.optimizePreconditions(recipe, "edit", editPreconditions);
@@ -117,13 +92,9 @@ export class PrepareRecipe {
         preparedRecipes.set(id, recipe);
 
         const descriptor = await recipe.descriptor();
-        const isDelegating = 'javaRecipeName' in recipe;
-
-        if (!isDelegating) {
-            for (const option of descriptor.options) {
-                if ((option.required ?? true) && option.value == null) {
-                    throw new Error(`Missing required option \`${option.name}\` for recipe \`${descriptor.name}\`.`);
-                }
+        for (const option of descriptor.options) {
+            if ((option.required ?? true) && option.value == null) {
+                throw new Error(`Missing required option \`${option.name}\` for recipe \`${descriptor.name}\`.`);
             }
         }
 
@@ -136,49 +107,43 @@ export class PrepareRecipe {
             scanPreconditions: scanPreconditions
         };
 
-        if (isDelegating) {
-            response.delegatesTo = {
-                recipeName: (recipe as any).javaRecipeName,
-                options: (recipe as any).delegatesToOptions ?? {}
-            };
-            return response;
-        }
-
         const childResponses: PrepareRecipeResponse[] = [];
         for (const child of await recipe.recipeList()) {
             if (child instanceof RpcRecipe) {
-                // Hosted on the peer: emit delegatesTo (its name + the options its parent set) so the
-                // host resolves it locally, matching how the by-name fallback used to resolve it.
-                const childId = snowflake.generate();
-                const childDescriptor = await child.descriptor();
+                // Already prepared on the host: hand it back by name with the options its parent set.
                 const options: Record<string, any> = {};
-                for (const option of childDescriptor.options) {
+                for (const option of (await child.descriptor()).options) {
                     if (option.value != null) {
                         options[option.name] = option.value;
                     }
                 }
-                childResponses.push({
-                    id: childId,
-                    descriptor: PrepareRecipe.delegateDescriptor(child.name),
-                    editVisitor: `edit:${childId}`,
-                    editPreconditions: [],
-                    scanPreconditions: [],
-                    delegatesTo: {recipeName: child.name, options}
-                });
-            } else {
-                // Register a child that was instantiated in recipeList() but never installed, so a peer
-                // that re-prepares children by name (rather than consuming recipeList) can still find it.
-                if (!marketplace.findRecipe(child.name)) {
-                    await marketplace.install(child.constructor as any, []);
-                }
-                childResponses.push(await PrepareRecipe.prepareInstance(child, snowflake, preparedRecipes, marketplace));
+                childResponses.push(await PrepareRecipe.prepareInstance(new DelegatingRecipe(child.name, options),
+                    snowflake, preparedRecipes, marketplace));
+                continue;
             }
+            // Register a child that was instantiated in recipeList() but never installed, so a peer
+            // that re-prepares children by name (rather than consuming recipeList) can still find it.
+            if (!PrepareRecipe.delegatesTo(child) && !marketplace.findRecipe(child.name)) {
+                await marketplace.install(child.constructor as any, []);
+            }
+            childResponses.push(await PrepareRecipe.prepareInstance(child, snowflake, preparedRecipes, marketplace));
         }
         response.recipeList = childResponses;
 
         return response;
     }
 
+    /**
+     * The Java recipe {@code recipe} stands in for, or {@code undefined} for a recipe this process
+     * runs itself. Duck-typed on the fields {@link DelegatingRecipe} declares, so a recipe package
+     * that loaded its own copy of this module is recognised too.
+     */
+    private static delegatesTo(recipe: any): {recipeName: string, options: Record<string, any>} | undefined {
+        return recipe != null && typeof recipe.javaRecipeName === "string" ?
+            {recipeName: recipe.javaRecipeName, options: {...(recipe.delegatesToOptions ?? {})}} :
+            undefined;
+    }
+
     /**
      * For preconditions that can be evaluated on the remote peer, let the remote peer
      * evaluate them and know that we will only have to do the visit work if the
@@ -246,13 +211,13 @@ export class PrepareRecipe {
             }
             return {op: condition.op, operands};
         }
-        // Common case: helpers like usesMethod / usesType return a lightweight
-        // RecipeRef so the recipe author can declare a precondition without
-        // firing an RPC at editor() time. The Java host's
-        // PreparedRecipeCache.instantiateVisitor constructs the named recipe
-        // via Jackson and uses its visitor.
-        if (condition instanceof RecipeRef) {
-            return {visitorName: condition.recipeName, visitorOptions: {...condition.options}};
+        // Common case: usesMethod / usesType return a lightweight RecipeRef, and
+        // prepareJavaRecipe a DelegatingRecipe, so a precondition is declared without
+        // firing an RPC at editor() time. The Java host's PreparedRecipeCache
+        // .instantiateVisitor constructs the named recipe via Jackson and uses its visitor.
+        const ref = condition instanceof RecipeRef ? condition : PrepareRecipe.delegatesTo(condition);
+        if (ref) {
+            return {visitorName: ref.recipeName, visitorOptions: {...ref.options}};
         }
         if (condition instanceof RpcRecipe) {
             return {visitorName: phase === "edit" ? condition.editVisitor : condition.scanVisitor!};

package/src/rpc/rewrite-rpc.ts

@@ -50,18 +50,11 @@ import {GetLanguages} from "./request/get-languages";
 
 export class RewriteRpc {
     /**
-     * Key for the active {@link RewriteRpc} connection on {@link globalThis}.
-     *
-     * It deliberately lives on `globalThis` rather than as a `static` field:
-     * a recipe package that bundles `@openrewrite/rewrite` (or resolves it from
-     * its own `node_modules`) loads a *separate copy* of this module, with its
-     * own class object and therefore its own statics. A `static` field set by
-     * the host would be invisible to such a copy, so `RewriteRpc.get()` (e.g.
-     * via `prepareJavaRecipe`) would return `undefined` and throw "no active
-     * RewriteRpc connection" — surfacing during `InstallRecipes` as the
-     * misleading "Ensure the constructor can be called without any arguments".
-     * {@link Symbol.for} resolves to the same symbol across every module copy,
-     * so all copies share the one active connection. See gh-7968.
+     * Key for the active {@link RewriteRpc} connection on {@link globalThis}. A recipe package that
+     * bundles `@openrewrite/rewrite` or resolves it from its own `node_modules` loads a separate copy
+     * of this module with its own class object and statics, so a `static` field set by the host would
+     * be invisible to it; {@link Symbol.for} resolves to the same symbol across every module copy, so
+     * all copies share the one active connection. See gh-7968.
      */
     private static readonly GLOBAL_KEY: symbol = Symbol.for("org.openrewrite.rpc.RewriteRpc.global");