@openrewrite/rewrite 8.66.0 → 8.66.1

package/src/javascript/templating/utils.ts

@@ -0,0 +1,284 @@
+/*
+ * 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 {J} from '../../java';
+import {JS} from '../index';
+import {JavaScriptParser} from '../parser';
+import {DependencyWorkspace} from '../dependency-workspace';
+import {Marker} from '../../markers';
+import {randomId} from '../../uuid';
+import {VariadicOptions, Capture, Any} from './types';
+
+/**
+ * Internal storage value type for pattern match captures.
+ * - J: Scalar captures without wrapper (fallback)
+ * - J.RightPadded<J>: Scalar captures with wrapper (preserves trailing markers like semicolons)
+ * - J[]: Variadic captures without wrapper metadata
+ * - J.RightPadded<J>[]: Variadic captures with wrapper metadata (preserves markers like commas)
+ */
+export type CaptureStorageValue = J | J.RightPadded<J> | J[] | J.RightPadded<J>[];
+
+/**
+ * Symbol to access wrappersMap without exposing it as public API
+ */
+export const WRAPPERS_MAP_SYMBOL = Symbol('wrappersMap');
+
+/**
+ * Cache for compiled templates and patterns.
+ * Stores parsed ASTs to avoid expensive re-parsing and dependency resolution.
+ */
+export class TemplateCache {
+    private cache = new Map<string, JS.CompilationUnit>();
+
+    /**
+     * Generates a cache key from template string, captures, and options.
+     */
+    private generateKey(
+        templateString: string,
+        captures: (Capture | Any<any>)[],
+        contextStatements: string[],
+        dependencies: Record<string, string>
+    ): string {
+        // Use the actual template string (with placeholders) as the primary key
+        const templateKey = templateString;
+
+        // Capture names
+        const capturesKey = captures.map(c => c.getName()).join(',');
+
+        // Context statements
+        const contextKey = contextStatements.join(';');
+
+        // Dependencies
+        const depsKey = JSON.stringify(dependencies || {});
+
+        return `${templateKey}::${capturesKey}::${contextKey}::${depsKey}`;
+    }
+
+    /**
+     * Gets a cached compilation unit or creates and caches a new one.
+     */
+    async getOrParse(
+        templateString: string,
+        captures: (Capture | Any<any>)[],
+        contextStatements: string[],
+        dependencies: Record<string, string>
+    ): Promise<JS.CompilationUnit> {
+        const key = this.generateKey(templateString, captures, contextStatements, dependencies);
+
+        let cu = this.cache.get(key);
+        if (cu) {
+            return cu;
+        }
+
+        // Create workspace if dependencies are provided
+        // DependencyWorkspace has its own cache, so multiple templates with
+        // the same dependencies will automatically share the same workspace
+        let workspaceDir: string | undefined;
+        if (dependencies && Object.keys(dependencies).length > 0) {
+            workspaceDir = await DependencyWorkspace.getOrCreateWorkspace(dependencies);
+        }
+
+        // Prepend context statements for type attribution context
+        const fullTemplateString = contextStatements.length > 0
+            ? contextStatements.join('\n') + '\n' + templateString
+            : templateString;
+
+        // Parse and cache (workspace only needed during parsing)
+        const parser = new JavaScriptParser({relativeTo: workspaceDir});
+        const parseGenerator = parser.parse({text: fullTemplateString, sourcePath: 'template.ts'});
+        cu = (await parseGenerator.next()).value as JS.CompilationUnit;
+
+        this.cache.set(key, cu);
+        return cu;
+    }
+
+    /**
+     * Clears the cache.
+     */
+    clear(): void {
+        this.cache.clear();
+    }
+}
+
+// Global cache instance
+export const templateCache = new TemplateCache();
+
+/**
+ * Marker that stores capture metadata on pattern AST nodes.
+ * This avoids the need to parse capture names from identifiers during matching.
+ */
+export class CaptureMarker implements Marker {
+    readonly kind = 'org.openrewrite.javascript.CaptureMarker';
+    readonly id = randomId();
+
+    constructor(
+        public readonly captureName: string,
+        public readonly variadicOptions?: VariadicOptions
+    ) {
+    }
+}
+
+/**
+ * Utility class for managing placeholder naming and parsing.
+ * Centralizes all logic related to capture placeholders.
+ */
+export class PlaceholderUtils {
+    static readonly CAPTURE_PREFIX = '__capt_';
+    static readonly PLACEHOLDER_PREFIX = '__PLACEHOLDER_';
+
+    /**
+     * Checks if a node is a capture placeholder.
+     *
+     * @param node The node to check
+     * @returns true if the node is a capture placeholder, false otherwise
+     */
+    static isCapture(node: J): boolean {
+        // Check for CaptureMarker first (efficient)
+        for (const marker of node.markers.markers) {
+            if (marker instanceof CaptureMarker) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    /**
+     * Gets the capture name from a node with a CaptureMarker.
+     *
+     * @param node The node to extract capture name from
+     * @returns The capture name, or null if not a capture
+     */
+    static getCaptureName(node: J): string | undefined {
+        // Check for CaptureMarker
+        for (const marker of node.markers.markers) {
+            if (marker instanceof CaptureMarker) {
+                return marker.captureName;
+            }
+        }
+
+        return undefined;
+    }
+
+    /**
+     * Gets the CaptureMarker from a node, if present.
+     *
+     * @param node The node to check
+     * @returns The CaptureMarker or undefined
+     */
+    static getCaptureMarker(node: J): CaptureMarker | undefined {
+        for (const marker of node.markers.markers) {
+            if (marker instanceof CaptureMarker) {
+                return marker;
+            }
+        }
+        return undefined;
+    }
+
+    /**
+     * Parses a capture placeholder to extract name and type constraint.
+     *
+     * @param identifier The identifier string to parse
+     * @returns Object with name and optional type constraint, or null if not a valid capture
+     */
+    static parseCapture(identifier: string): { name: string; typeConstraint?: string } | null {
+        if (!identifier.startsWith(this.CAPTURE_PREFIX)) {
+            return null;
+        }
+
+        // Handle unnamed captures: "__capt_unnamed_N__"
+        if (identifier.startsWith(`${this.CAPTURE_PREFIX}unnamed_`)) {
+            const match = identifier.match(/__capt_(unnamed_\d+)__/);
+            return match ? {name: match[1]} : null;
+        }
+
+        // Handle all other captures (including any()): "__capt_name__" or "__capt_name_type__"
+        const match = identifier.match(/__capt_([^_]+(?:_\d+)?)(?:_([^_]+))?__/);
+        if (!match) {
+            return null;
+        }
+
+        return {
+            name: match[1],
+            typeConstraint: match[2]
+        };
+    }
+
+    /**
+     * Creates a capture placeholder string.
+     *
+     * @param name The capture name
+     * @param typeConstraint Optional type constraint
+     * @returns The formatted placeholder string
+     */
+    static createCapture(name: string, typeConstraint?: string): string {
+        // Always use CAPTURE_PREFIX - the capturing flag is used internally for binding behavior
+        return typeConstraint
+            ? `${this.CAPTURE_PREFIX}${name}_${typeConstraint}__`
+            : `${this.CAPTURE_PREFIX}${name}__`;
+    }
+
+    /**
+     * Checks if a capture marker indicates a variadic capture.
+     *
+     * @param node The node to check
+     * @returns true if the node has a variadic CaptureMarker, false otherwise
+     */
+    static isVariadicCapture(node: J): boolean {
+        for (const marker of node.markers.markers) {
+            if (marker instanceof CaptureMarker && marker.variadicOptions) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    /**
+     * Gets the variadic options from a capture marker.
+     *
+     * @param node The node to extract variadic options from
+     * @returns The VariadicOptions, or undefined if not a variadic capture
+     */
+    static getVariadicOptions(node: J): VariadicOptions | undefined {
+        for (const marker of node.markers.markers) {
+            if (marker instanceof CaptureMarker) {
+                return marker.variadicOptions;
+            }
+        }
+        return undefined;
+    }
+
+    /**
+     * Checks if a statement is an ExpressionStatement wrapping a capture identifier.
+     * When a capture placeholder appears in statement position, the parser wraps it as
+     * an ExpressionStatement. This method unwraps it to get the identifier.
+     *
+     * @param stmt The statement to check
+     * @returns The unwrapped capture identifier, or the original statement if not wrapped
+     */
+    static unwrapStatementCapture(stmt: J): J {
+        // Check if it's an ExpressionStatement containing a capture identifier
+        if (stmt.kind === JS.Kind.ExpressionStatement) {
+            const exprStmt = stmt as JS.ExpressionStatement;
+            if (exprStmt.expression?.kind === J.Kind.Identifier) {
+                const identifier = exprStmt.expression as J.Identifier;
+                // Check if this is a capture placeholder
+                if (identifier.simpleName?.startsWith(this.CAPTURE_PREFIX)) {
+                    return identifier;
+                }
+            }
+        }
+        return stmt;
+    }
+}

package/dist/javascript/templating.d.ts

@@ -1,265 +0,0 @@
-import { Cursor, Tree } from '..';
-import { J } from '../java';
-/**
- * Capture specification for pattern matching.
- * Represents a placeholder in a template pattern that can capture a part of the AST.
- */
-export interface Capture {
-    /**
-     * The name of the capture, used to retrieve the captured node later.
-     */
-    name: string;
-}
-/**
- * Creates a capture specification for use in template patterns.
- *
- * @param name Optional name for the capture. If not provided, an auto-generated name is used.
- * @returns A Capture object
- *
- * @example
- * // Named inline captures
- * const pattern = pattern`${capture('left')} + ${capture('right')}`;
- *
- * // Unnamed captures
- * const {left, right} = {left: capture(), right: capture()};
- * const pattern = pattern`${left} + ${right}`;
- *
- * // Repeated patterns using the same capture
- * const expr = capture('expr');
- * const redundantOr = pattern`${expr} || ${expr}`;
- */
-export declare function capture(name?: string): Capture;
-export declare namespace capture {
-    var nextUnnamedId: number;
-}
-/**
- * Concise alias for `capture`. Works well for inline captures in patterns and templates.
- *
- * @param name Optional name for the capture. If not provided, an auto-generated name is used.
- * @returns A Capture object
- *
- * @example
- * // Inline captures with _ alias
- * pattern`isDate(${_('dateArg')})`
- * template`${_('dateArg')} instanceof Date`
- */
-export declare const _: typeof capture;
-/**
- * Configuration options for patterns.
- */
-export interface PatternOptions {
-    /**
-     * 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>;
-}
-/**
- * Represents a pattern that can be matched against AST nodes.
- */
-export declare class Pattern {
-    readonly templateParts: TemplateStringsArray;
-    readonly captures: Capture[];
-    private _options;
-    /**
-     * Gets the configuration options for this pattern.
-     * @readonly
-     */
-    get options(): Readonly<PatternOptions>;
-    /**
-     * Creates a new pattern from template parts and captures.
-     *
-     * @param templateParts The string parts of the template
-     * @param captures The captures between the string parts
-     */
-    constructor(templateParts: TemplateStringsArray, captures: Capture[]);
-    /**
-     * Configures this pattern with additional options.
-     *
-     * @param options Configuration options
-     * @returns This pattern for method chaining
-     *
-     * @example
-     * pattern`isDate(${capture('date')})`
-     *     .configure({
-     *         imports: ['import { isDate } from "util"'],
-     *         dependencies: { 'util': '^1.0.0' }
-     *     })
-     */
-    configure(options: PatternOptions): Pattern;
-    /**
-     * Creates a matcher for this pattern against a specific AST node.
-     *
-     * @param ast The AST node to match against
-     * @returns A Matcher object
-     */
-    match(ast: J): Promise<MatchResult | undefined>;
-}
-export declare class MatchResult implements Pick<Map<string, J>, "get"> {
-    private readonly bindings;
-    constructor(bindings?: Map<string, J>);
-    get(capture: Capture | string): J | undefined;
-}
-/**
- * Tagged template function for creating patterns.
- *
- * @param strings The string parts of the template
- * @param captures The captures between the string parts
- * @returns A Pattern object
- *
- * @example
- * // Using the same capture multiple times for repeated patterns
- * const expr = capture('expr');
- * const redundantOr = pattern`${expr} || ${expr}`;
- */
-export declare function pattern(strings: TemplateStringsArray, ...captures: (Capture | string)[]): Pattern;
-/**
- * Valid parameter types for template literals.
- * - Capture: For pattern matching and reuse
- * - Tree: AST nodes to be inserted directly
- * - Primitives: Values to be converted to literals
- */
-export type TemplateParameter = Capture | Tree | string | number | boolean;
-/**
- * Configuration options for templates.
- */
-export interface TemplateOptions {
-    /**
-     * 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>;
-}
-/**
- * Template for creating AST nodes.
- *
- * This class provides the public API for template generation.
- * The actual templating logic is handled by the internal TemplateEngine.
- *
- * @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);
- */
-export declare class Template {
-    private readonly templateParts;
-    private readonly parameters;
-    private options;
-    /**
-     * Creates a new template.
-     *
-     * @param templateParts The string parts of the template
-     * @param parameters The parameters between the string parts
-     */
-    constructor(templateParts: TemplateStringsArray, 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;
-    /**
-     * 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
-     */
-    apply(cursor: Cursor, tree: J, values?: Pick<Map<string, J>, 'get'>): Promise<J | undefined>;
-}
-export declare function template(strings: TemplateStringsArray, ...parameters: TemplateParameter[]): Template;
-/**
- * Parameter specification for template generation.
- * Represents a placeholder in a template that will be replaced with a parameter value.
- */
-interface Parameter {
-    /**
-     * The value to substitute into the template.
-     */
-    value: any;
-}
-/**
- * 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: Pattern | Pattern[];
-    after: Template;
-}
-/**
- * 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(() => ({
- *     before: pattern`${"left"} + ${"right"}`,
- *     after: template`${"right"} + ${"left"}`
- * }));
- *
- * @example
- * // Multiple patterns
- * const normalizeComparisons = rewrite(() => ({
- *     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 declare function rewrite(builderFn: () => RewriteConfig): RewriteRule;
-export {};
-//# sourceMappingURL=templating.d.ts.map

package/dist/javascript/templating.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"templating.d.ts","sourceRoot":"","sources":["../../src/javascript/templating.ts"],"names":[],"mappings":"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"}