@openrewrite/rewrite 8.67.0-20251104-084009 → 8.67.0-20251104-114312

package/src/javascript/templating/template.ts

@@ -0,0 +1,326 @@
+/*
+ * 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 {TemplateOptions, TemplateParameter, Capture} from './types';
+import {MatchResult} from './pattern';
+import {WRAPPERS_MAP_SYMBOL} from './utils';
+import {CAPTURE_NAME_SYMBOL} from './capture';
+import {TemplateEngine, Parameter} from './engine';
+
+/**
+ * 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 = {};
+
+    /**
+     * 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({
+     *         imports: ['import { isDate } from "util"'],
+     *         dependencies: { 'util': '^1.0.0' }
+     *     })
+     */
+    configure(options: TemplateOptions): Template {
+        this.options = { ...this.options, ...options };
+        return this;
+    }
+
+    /**
+     * 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'>): 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 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 instanceof MatchResult) {
+            // MatchResult - extract both bindings and wrappersMap
+            normalizedValues = values;
+            wrappersMap = (values as any)[WRAPPERS_MAP_SYMBOL]();
+        } else {
+            // Other Pick<Map> implementation
+            normalizedValues = values;
+        }
+
+        // Prefer 'context' over deprecated 'imports'
+        const contextStatements = this.options.context || this.options.imports || [];
+        return TemplateEngine.applyTemplate(
+            this.templateParts,
+            this.parameters,
+            cursor,
+            {
+                tree,
+                mode: JavaCoordinates.Mode.Replace
+            },
+            normalizedValues,
+            wrappersMap,
+            contextStatements,
+            this.options.dependencies || {}
+        );
+    }
+}
+
+/**
+ * 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`).
+ *
+ * @param strings The string parts of the template
+ * @param parameters The parameters between the string parts (Capture, Tree, or primitives)
+ * @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})`
+ */
+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};

package/src/javascript/templating/types.ts

@@ -0,0 +1,300 @@
+/*
+ * 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';
+
+/**
+ * Options for variadic captures that match zero or more nodes in a sequence.
+ */
+export interface VariadicOptions {
+    /**
+     * Minimum number of nodes that must be matched (default: 0).
+     */
+    min?: number;
+
+    /**
+     * Maximum number of nodes that can be matched (default: unlimited).
+     */
+    max?: number;
+}
+
+/**
+ * Options for the capture function.
+ *
+ * The constraint function receives different parameter types depending on whether
+ * the capture is variadic:
+ * - For regular captures: constraint receives a single node of type T
+ * - For variadic captures: constraint receives an array of nodes of type T[]
+ */
+export interface CaptureOptions<T = any> {
+    name?: string;
+    variadic?: boolean | VariadicOptions;
+    constraint?: (node: T) => boolean;
+}
+
+/**
+ * Capture specification for pattern matching.
+ * Represents a placeholder in a template pattern that can capture a part of the AST.
+ *
+ * @template T The expected type of the captured AST node (for TypeScript autocomplete)
+ *
+ * @remarks
+ * **Important: Type Parameter is for IDE Support Only**
+ *
+ * The generic type parameter `<T>` provides IDE autocomplete and type checking in your code,
+ * but does NOT enforce any runtime constraints on what the capture will match.
+ *
+ * **Pattern Matching Behavior:**
+ * - A bare `pattern`${capture('x')}`` will structurally match ANY expression
+ * - Pattern structure determines matching: `pattern`foo(${capture('x')})`` only matches `foo()` calls
+ * - Use structural patterns to narrow matching scope before applying semantic validation
+ *
+ * **Variadic Captures:**
+ * Use `{ variadic: true }` to match zero or more nodes in a sequence:
+ * ```typescript
+ * const args = capture('args', { variadic: true });
+ * pattern`foo(${args})`  // Matches: foo(), foo(a), foo(a, b, c)
+ * ```
+ */
+export interface Capture<T = any> {
+    /**
+     * Gets the string name of this capture.
+     */
+    getName(): string;
+
+    /**
+     * Returns true if this is a variadic capture (matching zero or more nodes).
+     */
+    isVariadic(): boolean;
+
+    /**
+     * Returns the variadic options if this is a variadic capture, undefined otherwise.
+     */
+    getVariadicOptions(): VariadicOptions | undefined;
+
+    /**
+     * Gets the constraint function if this capture has one.
+     * For regular captures (T = Expression), constraint receives a single node.
+     * For variadic captures (T = Expression[]), constraint receives an array of nodes.
+     */
+    getConstraint?(): ((node: T) => boolean) | undefined;
+}
+
+/**
+ * Non-capturing pattern match specification.
+ * Represents a placeholder in a pattern that matches AST nodes without binding them to a name.
+ *
+ * Use `any()` when you need to match structure without caring about the specific values.
+ * The key difference from `Capture` is that `Any` cannot be used in templates - the TypeScript
+ * type system prevents this at compile time.
+ *
+ * @template T The expected type of the matched AST node (for TypeScript autocomplete and constraints)
+ *
+ * @remarks
+ * **Why Any<T> is Separate from Capture<T>:**
+ *
+ * Using a separate type provides compile-time safety:
+ * - `pattern`foo(${any()})`` - ✅ OK in patterns
+ * - `template`bar(${any()})`` - ❌ TypeScript error (Any<T> not assignable to template parameters)
+ *
+ * This prevents logical errors where you try to use a non-capturing match in a template.
+ *
+ * **Semantic Parallel with TypeScript's `any`:**
+ *
+ * Just as TypeScript's `any` type means "be permissive about types here",
+ * pattern matching's `any()` means "be permissive about values here":
+ * - TypeScript `any`: Accept any type, don't check it
+ * - Pattern `any()`: Match any value, don't bind it
+ *
+ * @example
+ * // Match without capturing
+ * const pat = pattern`foo(${any()})`
+ *
+ * @example
+ * // Variadic any - match zero or more without capturing
+ * const rest = any({ variadic: true });
+ * const pat = pattern`bar(${capture('first')}, ${rest})`
+ *
+ * @example
+ * // With constraints - validate but don't capture
+ * const numericArg = any<J.Literal>({
+ *     constraint: (node) => typeof node.value === 'number'
+ * });
+ * const pat = pattern`process(${numericArg})`
+ */
+export interface Any<T = any> {
+    /**
+     * Gets the internal identifier for this any pattern.
+     */
+    getName(): string;
+
+    /**
+     * Returns true if this is a variadic any (matching zero or more nodes).
+     */
+    isVariadic(): boolean;
+
+    /**
+     * Returns the variadic options if this is a variadic any, undefined otherwise.
+     */
+    getVariadicOptions(): VariadicOptions | undefined;
+
+    /**
+     * Gets the constraint function if this any pattern has one.
+     * For regular any (T = Expression), constraint receives a single node.
+     * For variadic any (T = Expression[]), constraint receives an array of nodes.
+     */
+    getConstraint?(): ((node: T) => boolean) | undefined;
+}
+
+/**
+ * Template parameter specification for template-only parameter substitution.
+ * Unlike Capture, TemplateParam does not support property access and is simpler.
+ *
+ * @template T The expected type of the parameter value (for TypeScript autocomplete only)
+ */
+export interface TemplateParam<T = any> {
+    /**
+     * The name of the parameter, used to look up the value in the values map.
+     */
+    readonly name: string;
+
+    /**
+     * Gets the string name of this parameter.
+     */
+    getName(): string;
+}
+
+/**
+ * Configuration options for patterns.
+ */
+export interface PatternOptions {
+    /**
+     * Declarations to provide type attribution context for the pattern.
+     * These can include import statements, type declarations, function declarations, or any
+     * other declarations needed for proper type information. They are prepended to the pattern
+     * when parsing to ensure proper type attribution.
+     *
+     * @example
+     * ```typescript
+     * pattern`forwardRef(${capture('comp')})`
+     *     .configure({
+     *         context: [
+     *             `import { forwardRef } from 'react'`,
+     *             `type MyType = { value: number }`
+     *         ]
+     *     })
+     * ```
+     */
+    context?: string[];
+
+    /**
+     * @deprecated Use `context` instead. This alias will be removed in a future version.
+     *
+     * Import statements to provide type attribution context.
+     * These are prepended to the pattern when parsing to ensure proper type information.
+     */
+    imports?: string[];
+
+    /**
+     * NPM dependencies required for import resolution and type attribution.
+     * Maps package names to version specifiers (e.g., { 'util': '^1.0.0' }).
+     * The template engine will create a package.json with these dependencies.
+     */
+    dependencies?: Record<string, string>;
+
+    /**
+     * When true, allows patterns without type annotations to match code with type annotations.
+     * This enables more flexible pattern matching during development or when full type attribution
+     * is not needed. When false, enforces strict type matching where both pattern and target must
+     * have matching type annotations.
+     *
+     * @default true (lenient matching enabled for backward compatibility)
+     */
+    lenientTypeMatching?: boolean;
+}
+
+/**
+ * Valid parameter types for template literals.
+ * - Capture: For pattern matching and reuse
+ * - CaptureValue: Result of property access or array operations on captures (e.g., capture.prop, capture[0], capture.slice(1))
+ * - Tree: AST nodes to be inserted directly
+ * - Tree[]: Arrays of AST nodes (from variadic capture operations like slice)
+ * - Primitives: Values to be converted to literals
+ */
+export type TemplateParameter = Capture | any | TemplateParam | Tree | Tree[] | string | number | boolean;
+
+/**
+ * Configuration options for templates.
+ */
+export interface TemplateOptions {
+    /**
+     * Declarations to provide type attribution context for the template.
+     * These can include import statements, type declarations, function declarations, or any
+     * other declarations needed for proper type information. They are prepended to the template
+     * when parsing to ensure proper type attribution.
+     *
+     * @example
+     * ```typescript
+     * template`console.log(${capture('value')})`
+     *     .configure({
+     *         context: [
+     *             `type MyType = { value: number }`,
+     *             `const console = { log: (x: any) => void 0 }`
+     *         ]
+     *     })
+     * ```
+     */
+    context?: string[];
+
+    /**
+     * @deprecated Use `context` instead. This alias will be removed in a future version.
+     *
+     * Import statements to provide type attribution context.
+     * These are prepended to the template when parsing to ensure proper type information.
+     */
+    imports?: string[];
+
+    /**
+     * NPM dependencies required for import resolution and type attribution.
+     * Maps package names to version specifiers (e.g., { 'util': '^1.0.0' }).
+     * The template engine will create a package.json with these dependencies.
+     */
+    dependencies?: Record<string, string>;
+}
+
+/**
+ * Represents a replacement rule that can match a pattern and apply a template.
+ */
+export interface RewriteRule {
+    /**
+     * Attempts to apply this rewrite rule to the given AST node.
+     *
+     * @param cursor The cursor context at the current position in the AST
+     * @param node The AST node to try matching and transforming
+     * @returns The transformed node if a pattern matched, or `undefined` if no pattern matched.
+     *          When using in a visitor, always use the `|| node` pattern to return the original
+     *          node when there's no match: `return await rule.tryOn(this.cursor, node) || node;`
+     */
+    tryOn(cursor: Cursor, node: J): Promise<J | undefined>;
+}
+
+/**
+ * Configuration for a replacement rule.
+ */
+export interface RewriteConfig {
+    before: any; // Pattern | Pattern[], but we'll import Pattern in rewrite.ts
+    after: any;  // Template, but we'll import Template in rewrite.ts
+}