@openrewrite/rewrite 8.66.0 → 8.66.2

package/src/javascript/templating/rewrite.ts

@@ -0,0 +1,229 @@
+/*
+ * Copyright 2025 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.
+ * You may obtain a copy of the License at
+ * <p>
+ * https://docs.moderne.io/licensing/moderne-source-available-license
+ * <p>
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import {Cursor, ExecutionContext, Recipe} from '../..';
+import {J} from '../../java';
+import {RewriteRule, RewriteConfig} from './types';
+import {Pattern, MatchResult} from './pattern';
+import {Template} from './template';
+
+/**
+ * Implementation of a replacement rule.
+ */
+class RewriteRuleImpl implements RewriteRule {
+    constructor(
+        private readonly before: Pattern[],
+        private readonly after: Template | ((match: MatchResult) => Template),
+        private readonly where?: (node: J, cursor: Cursor) => boolean | Promise<boolean>,
+        private readonly whereNot?: (node: J, cursor: Cursor) => boolean | Promise<boolean>
+    ) {
+    }
+
+    async tryOn(cursor: Cursor, node: J): Promise<J | undefined> {
+        for (const pattern of this.before) {
+            // Pass cursor to pattern.match() for context-aware capture constraints
+            const match = await pattern.match(node, cursor);
+            if (match) {
+                // Evaluate context predicates after structural match
+                if (this.where) {
+                    const whereResult = await this.where(node, cursor);
+                    if (!whereResult) {
+                        continue; // Pattern matched but context doesn't, try next pattern
+                    }
+                }
+
+                if (this.whereNot) {
+                    const whereNotResult = await this.whereNot(node, cursor);
+                    if (whereNotResult) {
+                        continue; // Pattern matched but context is excluded, try next pattern
+                    }
+                }
+
+                // Apply transformation
+                let result: J | undefined;
+
+                if (typeof this.after === 'function') {
+                    // Call the function to get a template, then apply it
+                    const template = this.after(match);
+                    result = await template.apply(cursor, node, match);
+                } else {
+                    // Use template.apply() as before
+                    result = await this.after.apply(cursor, node, match);
+                }
+
+                if (result) {
+                    return result;
+                }
+            }
+        }
+
+        // Return undefined if no patterns match or all context checks failed
+        return undefined;
+    }
+
+    andThen(next: RewriteRule): RewriteRule {
+        const first = this;
+        return new (class extends RewriteRuleImpl {
+            constructor() {
+                // Pass empty patterns and a function that will never be called
+                // since we override tryOn
+                super([], () => undefined as unknown as Template);
+            }
+
+            async tryOn(cursor: Cursor, node: J): Promise<J | undefined> {
+                const firstResult = await first.tryOn(cursor, node);
+                if (firstResult !== undefined) {
+                    const secondResult = await next.tryOn(cursor, firstResult);
+                    return secondResult ?? firstResult;
+                }
+                return undefined;
+            }
+        })();
+    }
+
+    orElse(alternative: RewriteRule): RewriteRule {
+        const first = this;
+        return new (class extends RewriteRuleImpl {
+            constructor() {
+                // Pass empty patterns and a function that will never be called
+                // since we override tryOn
+                super([], () => undefined as unknown as Template);
+            }
+
+            async tryOn(cursor: Cursor, node: J): Promise<J | undefined> {
+                const firstResult = await first.tryOn(cursor, node);
+                if (firstResult !== undefined) {
+                    return firstResult;
+                }
+                return await alternative.tryOn(cursor, node);
+            }
+        })();
+    }
+}
+
+/**
+ * Creates a replacement rule using a capture context and configuration.
+ *
+ * @param builderFn Function that takes a capture context and returns before/after configuration
+ * @returns A replacement rule that can be applied to AST nodes
+ *
+ * @example
+ * // Single pattern
+ * const swapOperands = rewrite(() => {
+ *     const { left, right } = { left: capture(), right: capture() };
+ *     return {
+ *         before: pattern`${left} + ${right}`,
+ *         after: template`${right} + ${left}`
+ *     };
+ * });
+ *
+ * @example
+ * // Multiple patterns
+ * const normalizeComparisons = rewrite(() => {
+ *     const { left, right } = { left: capture(), right: capture() };
+ *     return {
+ *         before: [
+ *             pattern`${left} == ${right}`,
+ *             pattern`${left} === ${right}`
+ *         ],
+ *         after: template`${left} === ${right}`
+ *     };
+ * });
+ *
+ * @example
+ * // Using in a visitor - IMPORTANT: use `|| node` to handle undefined when no match
+ * class MyVisitor extends JavaScriptVisitor<any> {
+ *     override async visitBinary(binary: J.Binary, p: any): Promise<J | undefined> {
+ *         const rule = rewrite(() => ({
+ *             before: pattern`${capture('a')} + ${capture('b')}`,
+ *             after: template`${capture('b')} + ${capture('a')}`
+ *         }));
+ *         // tryOn() returns undefined if no pattern matches, so always use || node
+ *         return await rule.tryOn(this.cursor, binary) || binary;
+ *     }
+ * }
+ */
+export function rewrite(
+    builderFn: () => RewriteConfig
+): RewriteRule {
+    const config = builderFn();
+
+    // Ensure we have valid before and after properties
+    if (!config.before || !config.after) {
+        throw new Error('Builder function must return an object with before and after properties');
+    }
+
+    return new RewriteRuleImpl(
+        Array.isArray(config.before) ? config.before : [config.before],
+        config.after,
+        config.where,
+        config.whereNot
+    );
+}
+
+/**
+ * Creates a RewriteRule from a Recipe by using its editor visitor.
+ *
+ * This allows recipes to be used in the same chaining pattern as other rewrite rules,
+ * enabling composition with `andThen()`.
+ *
+ * @param recipe The recipe whose editor will be used to transform nodes
+ * @param ctx The execution context to pass to the recipe's editor
+ * @returns A RewriteRule that applies the recipe's editor to nodes
+ *
+ * @example
+ * ```typescript
+ * class MyRecipe extends Recipe {
+ *     name = "my.recipe";
+ *     displayName = "My Recipe";
+ *     description = "Transforms code.";
+ *
+ *     async editor(): Promise<TreeVisitor<any, ExecutionContext>> {
+ *         return new MyVisitor();
+ *     }
+ * }
+ *
+ * // In a visitor:
+ * override async visitBinary(binary: J.Binary, p: ExecutionContext): Promise<J | undefined> {
+ *     const rule1 = rewrite(() => ({
+ *         before: pattern`${capture('a')} + ${capture('b')}`,
+ *         after: template`${capture('b')} + ${capture('a')}`
+ *     }));
+ *
+ *     const rule2 = fromRecipe(new MyRecipe(), p);
+ *
+ *     // Chain the pattern-based rule with the recipe
+ *     const combined = rule1.andThen(rule2);
+ *     return await combined.tryOn(this.cursor, binary) || binary;
+ * }
+ * ```
+ */
+export const fromRecipe = (recipe: Recipe, ctx: ExecutionContext): RewriteRule => {
+    return new (class extends RewriteRuleImpl {
+        constructor() {
+            // Pass empty patterns and a function that will never be called
+            // since we override tryOn
+            super([], () => undefined as unknown as Template);
+        }
+
+        async tryOn(cursor: Cursor, tree: J): Promise<J | undefined> {
+            const visitor = await recipe.editor();
+            const result = await visitor.visit<J>(tree, ctx, cursor);
+
+            // Return undefined if the visitor didn't change the node
+            return result !== tree ? result : undefined;
+        }
+    })();
+}

package/src/javascript/templating/template.ts

@@ -0,0 +1,414 @@
+/*
+ * Copyright 2025 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.
+ * You may obtain a copy of the License at
+ * <p>
+ * https://docs.moderne.io/licensing/moderne-source-available-license
+ * <p>
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import {Cursor, Tree} from '../..';
+import {J} from '../../java';
+import {Capture, Parameter, TemplateOptions, TemplateParameter} from './types';
+import {MatchResult} from './pattern';
+import {generateCacheKey, globalAstCache, WRAPPERS_MAP_SYMBOL} from './utils';
+import {CAPTURE_NAME_SYMBOL, RAW_CODE_SYMBOL} from './capture';
+import {TemplateEngine} from './engine';
+import {JS} from '..';
+
+/**
+ * Coordinates for template application.
+ */
+type JavaCoordinates = {
+    tree?: Tree;
+    loc?: JavaCoordinates.Location;
+    mode?: JavaCoordinates.Mode;
+};
+
+namespace JavaCoordinates {
+    // FIXME need to come up with the equivalent of `Space.Location` support
+    export type Location = 'EXPRESSION_PREFIX' | 'STATEMENT_PREFIX' | 'BLOCK_END';
+
+    export enum Mode {
+        Before,
+        After,
+        Replace,
+    }
+}
+
+/**
+ * Builder for creating templates programmatically.
+ * Use when template structure is not known at compile time.
+ *
+ * @example
+ * // Conditional construction
+ * const builder = Template.builder().code('function foo(x) {');
+ * if (needsValidation) {
+ *     builder.code('if (typeof x !== "number") throw new Error("Invalid");');
+ * }
+ * builder.code('return x * 2; }');
+ * const tmpl = builder.build();
+ *
+ * @example
+ * // Composition from fragments
+ * function createWrapper(innerBody: Capture): Template {
+ *     return Template.builder()
+ *         .code('function wrapper() { try { ')
+ *         .param(innerBody)
+ *         .code(' } catch(e) { console.error(e); } }')
+ *         .build();
+ * }
+ */
+export class TemplateBuilder {
+    private parts: string[] = [];
+    private params: TemplateParameter[] = [];
+
+    /**
+     * Adds a static string part to the template.
+     *
+     * @param str The string to add
+     * @returns This builder for chaining
+     */
+    code(str: string): this {
+        // If there are already params, we need to add an empty string before this
+        if (this.params.length > this.parts.length) {
+            this.parts.push('');
+        }
+        // Append to the last part or start a new one
+        if (this.parts.length === 0) {
+            this.parts.push(str);
+        } else {
+            this.parts[this.parts.length - 1] += str;
+        }
+        return this;
+    }
+
+    /**
+     * Adds a parameter to the template.
+     *
+     * @param value The parameter value (Capture, Tree, or primitive)
+     * @returns This builder for chaining
+     */
+    param(value: TemplateParameter): this {
+        // Ensure we have a part for after this parameter
+        if (this.parts.length === 0) {
+            this.parts.push('');
+        }
+        this.params.push(value);
+        // Add an empty string for the next part
+        this.parts.push('');
+        return this;
+    }
+
+    /**
+     * Builds the template from accumulated parts and parameters.
+     *
+     * @returns A Template instance
+     */
+    build(): Template {
+        // Ensure parts array is one longer than params array
+        while (this.parts.length <= this.params.length) {
+            this.parts.push('');
+        }
+
+        // Create a synthetic TemplateStringsArray
+        const templateStrings = this.parts.slice() as any;
+        templateStrings.raw = this.parts.slice();
+        Object.defineProperty(templateStrings, 'raw', {
+            value: this.parts.slice(),
+            writable: false
+        });
+
+        // Delegate to the template() function
+        return template(templateStrings, ...this.params);
+    }
+}
+
+/**
+ * Template for creating AST nodes.
+ *
+ * This class provides the public API for template generation.
+ * The actual templating logic is handled by the internal TemplateEngine.
+ *
+ * Templates can reference captures from patterns, and you can access properties
+ * of captured nodes using dot notation. This allows you to extract and insert
+ * specific subtrees from matched AST nodes.
+ *
+ * @example
+ * // Generate a literal AST node
+ * const result = template`2`.apply(cursor, coordinates);
+ *
+ * @example
+ * // Generate an AST node with a parameter
+ * const result = template`${capture()}`.apply(cursor, coordinates);
+ *
+ * @example
+ * // Access properties of captured nodes in templates
+ * const method = capture<J.MethodInvocation>('method');
+ * const pat = pattern`foo(${method})`;
+ * const tmpl = template`bar(${method.name})`; // Access the 'name' property
+ *
+ * const match = await pat.match(someNode);
+ * if (match) {
+ *     // The template will insert just the 'name' subtree from the captured method
+ *     const result = await tmpl.apply(cursor, someNode, match);
+ * }
+ *
+ * @example
+ * // Deep property access chains
+ * const method = capture<J.MethodInvocation>('method');
+ * template`console.log(${method.name.simpleName})` // Navigate multiple properties
+ *
+ * @example
+ * // Array element access
+ * const invocation = capture<J.MethodInvocation>('invocation');
+ * template`bar(${invocation.arguments.elements[0].element})` // Access array elements
+ */
+export class Template {
+    private options: TemplateOptions = {};
+    private _cachedTemplate?: J;
+
+    /**
+     * Creates a new builder for constructing templates programmatically.
+     *
+     * @returns A new TemplateBuilder instance
+     *
+     * @example
+     * const tmpl = Template.builder()
+     *     .code('function foo() {')
+     *     .code('return ')
+     *     .param(capture('value'))
+     *     .code('; }')
+     *     .build();
+     */
+    static builder(): TemplateBuilder {
+        return new TemplateBuilder();
+    }
+
+    /**
+     * Creates a new template.
+     *
+     * @param templateParts The string parts of the template
+     * @param parameters The parameters between the string parts
+     */
+    constructor(
+        private readonly templateParts: TemplateStringsArray,
+        private readonly parameters: Parameter[]
+    ) {
+    }
+
+    /**
+     * Configures this template with additional options.
+     *
+     * @param options Configuration options
+     * @returns This template for method chaining
+     *
+     * @example
+     * template`isDate(${capture('date')})`
+     *     .configure({
+     *         context: ['import { isDate } from "util"'],
+     *         dependencies: { 'util': '^1.0.0' }
+     *     })
+     */
+    configure(options: TemplateOptions): Template {
+        this.options = { ...this.options, ...options };
+        // Invalidate cache when configuration changes
+        this._cachedTemplate = undefined;
+        return this;
+    }
+
+    /**
+     * Gets the template tree for this template, using two-level caching:
+     * - Level 1: Instance cache (this._cachedTemplate) - fastest, no lookup needed
+     * - Level 2: Global cache (globalAstCache) - fast, shared across all templates
+     * - Level 3: TemplateEngine - slow, parses and processes the template
+     *
+     * Most parameters use placeholders that are replaced during application, so templates
+     * with the same structure share cached ASTs. However, raw() parameters are spliced at
+     * construction time, so their values must be included in the cache key.
+     *
+     * @returns The cached or newly computed template tree
+     * @internal
+     */
+    async getTemplateTree(): Promise<JS.CompilationUnit> {
+        // Level 1: Instance cache (fastest path)
+        if (this._cachedTemplate) {
+            return this._cachedTemplate as JS.CompilationUnit;
+        }
+
+        // Generate cache key for global lookup
+        // For raw() parameters, we need to include their code values in the key
+        // since they're spliced at construction time, not application time
+        const contextStatements = this.options.context || this.options.imports || [];
+        const parametersKey = this.parameters.map((p, i) => {
+            const value = p.value;
+            // Include raw code values in the cache key using the symbol
+            if (value && typeof value === 'object' && value[RAW_CODE_SYMBOL]) {
+                return `raw:${value.code}`;
+            }
+            return i.toString();
+        }).join(',');
+        const cacheKey = generateCacheKey(
+            this.templateParts,
+            parametersKey,
+            contextStatements,
+            this.options.dependencies || {}
+        );
+
+        // Level 2: Global cache (fast path - shared with Pattern)
+        const cached = globalAstCache.get(cacheKey);
+        if (cached) {
+            this._cachedTemplate = cached as JS.CompilationUnit;
+            return cached as JS.CompilationUnit;
+        }
+
+        // Level 3: Compute via TemplateEngine (slow path)
+        const result = await TemplateEngine.getTemplateTree(
+            this.templateParts,
+            this.parameters,
+            contextStatements,
+            this.options.dependencies || {}
+        ) as JS.CompilationUnit;
+
+        // Cache in both levels
+        globalAstCache.set(cacheKey, result);
+        this._cachedTemplate = result;
+
+        return result;
+    }
+
+    /**
+     * Applies this template and returns the resulting tree.
+     *
+     * @param cursor The cursor pointing to the current location in the AST
+     * @param tree Input tree
+     * @param values values for parameters in template
+     * @returns A Promise resolving to the generated AST node
+     */
+    async apply(cursor: Cursor, tree: J, values?: Map<Capture | string, J> | Pick<Map<string, J>, 'get'> | Record<string, J>): Promise<J | undefined> {
+        // Normalize the values map: convert any Capture keys to string keys
+        let normalizedValues: Pick<Map<string, J>, 'get'> | undefined;
+        let wrappersMap: Map<string, J.RightPadded<J> | J.RightPadded<J>[]> = new Map();
+
+        if (values instanceof MatchResult) {
+            // MatchResult - extract both bindings and wrappersMap
+            normalizedValues = values;
+            wrappersMap = (values as any)[WRAPPERS_MAP_SYMBOL]();
+        } else if (values instanceof Map) {
+            const normalized = new Map<string, J>();
+            for (const [key, value] of values.entries()) {
+                const stringKey = typeof key === 'string'
+                    ? key
+                    : ((key as any)[CAPTURE_NAME_SYMBOL] || key.getName());
+                normalized.set(stringKey, value);
+            }
+            normalizedValues = normalized;
+        } else if (values && typeof values === 'object') {
+            // Check if it's a Map-like object with 'get' method, or a plain object literal
+            if ('get' in values && typeof values.get === 'function') {
+                // Map-like object with get method
+                normalizedValues = values as Pick<Map<string, J>, 'get'>;
+            } else {
+                // Plain object literal - convert to Map
+                // Keys may be strings or Capture objects (via computed properties {[x]: value})
+                const normalized = new Map<string, J>();
+                for (const [key, value] of Object.entries(values)) {
+                    // If the key happens to be a stringified Capture (from computed properties),
+                    // it's already been converted to a string by JavaScript
+                    normalized.set(key, value);
+                }
+                normalizedValues = normalized;
+            }
+        }
+
+        // Use instance-level cache to get the template tree
+        const ast = await this.getTemplateTree();
+
+        // Delegate to TemplateEngine for placeholder substitution and application
+        return TemplateEngine.applyTemplateFromAst(
+            ast,
+            this.parameters,
+            cursor,
+            {
+                tree,
+                mode: JavaCoordinates.Mode.Replace
+            },
+            normalizedValues,
+            wrappersMap
+        );
+    }
+}
+
+/**
+ * Tagged template function for creating templates that generate AST nodes.
+ *
+ * Templates support property access on captures from patterns, allowing you to
+ * extract and insert specific subtrees from matched AST nodes. Use dot notation
+ * to navigate properties (e.g., `method.name`) or array bracket notation to
+ * access array elements (e.g., `args.elements[0].element`).
+ *
+ * Templates can also accept AST wrapper types directly:
+ * - J.RightPadded<T>: The element will be extracted and inserted
+ * - J.RightPadded<T>[]: Elements will be expanded in place
+ * - J.Container<T>: Elements will be expanded in place
+ *
+ * @param strings The string parts of the template
+ * @param parameters The parameters between the string parts (Capture, CaptureValue, TemplateParam, Tree, Tree[], J.RightPadded, J.RightPadded[], or J.Container)
+ * @returns A Template object that can be applied to generate AST nodes
+ *
+ * @example
+ * // Simple template with literal
+ * const tmpl = template`console.log("hello")`;
+ * const result = await tmpl.apply(cursor, node);
+ *
+ * @example
+ * // Template with capture - matches captured value from pattern
+ * const expr = capture('expr');
+ * const pat = pattern`foo(${expr})`;
+ * const tmpl = template`bar(${expr})`;
+ *
+ * const match = await pat.match(node);
+ * if (match) {
+ *     const result = await tmpl.apply(cursor, node, match);
+ * }
+ *
+ * @example
+ * // Property access on captures - extract subtrees
+ * const method = capture<J.MethodInvocation>('method');
+ * const pat = pattern`foo(${method})`;
+ * // Access the 'name' property of the captured method invocation
+ * const tmpl = template`bar(${method.name})`;
+ *
+ * @example
+ * // Deep property chains
+ * const method = capture<J.MethodInvocation>('method');
+ * template`console.log(${method.name.simpleName})`
+ *
+ * @example
+ * // Array element access
+ * const invocation = capture<J.MethodInvocation>('invocation');
+ * template`bar(${invocation.arguments.elements[0].element})`
+ *
+ * @example
+ * // Using J.RightPadded and J.Container directly
+ * const selectExpr = method.select;  // J.RightPadded<Expression>
+ * const args = method.arguments;      // J.Container<Expression>
+ * template`${selectExpr}.newMethod(${args})`
+ */
+export function template(strings: TemplateStringsArray, ...parameters: TemplateParameter[]): Template {
+    // Convert parameters to Parameter objects (no longer need to check for mutable tree property)
+    const processedParameters = parameters.map(param => {
+        // Just wrap each parameter value in a Parameter object
+        return {value: param};
+    });
+
+    return new Template(strings, processedParameters);
+}
+
+export type {JavaCoordinates};