@openrewrite/rewrite 8.66.1 → 8.66.3

package/src/javascript/format.ts

@@ -13,9 +13,9 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import {JS} from "./tree";
+import {isJavaScript, JS} from "./tree";
 import {JavaScriptVisitor} from "./visitor";
-import {Comment, J, Statement} from "../java";
+import {Comment, isJava, J, Statement} from "../java";
 import {Draft, produce} from "immer";
 import {Cursor, isScope, Tree} from "../tree";
 import {
@@ -28,16 +28,15 @@ import {
 } from "./style";
 import {produceAsync} from "../visitor";
 
-export async function maybeAutoFormat<J2 extends J, P>(before: J2, after: J2, p: P, stopAfter?: J, parent?: Cursor): Promise<J2> {
+export const maybeAutoFormat = async <J2 extends J, P>(before: J2, after: J2, p: P, stopAfter?: J, parent?: Cursor): Promise<J2> => {
     if (before !== after) {
         return autoFormat(after, p, stopAfter, parent);
     }
     return after;
 }
 
-export async function autoFormat<J2 extends J, P>(j: J2, p: P, stopAfter?: J, parent?: Cursor): Promise<J2> {
-    return await new AutoformatVisitor(stopAfter).visit(j, p, parent) as J2;
-}
+export const autoFormat = async <J2 extends J, P>(j: J2, p: P, stopAfter?: J, parent?: Cursor): Promise<J2> =>
+    (await new AutoformatVisitor(stopAfter).visit(j, p, parent) as J2);
 
 export class AutoformatVisitor<P> extends JavaScriptVisitor<P> {
     constructor(private stopAfter?: Tree) {
@@ -336,6 +335,13 @@ export class SpacesVisitor<P> extends JavaScriptVisitor<P> {
         });
     }
 
+    protected async visitPropertyAssignment(propertyAssignment: JS.PropertyAssignment, p: P): Promise<J | undefined> {
+        const pa = await super.visitPropertyAssignment(propertyAssignment, p) as JS.PropertyAssignment;
+        return produceAsync(pa, draft => {
+            draft.name.after.whitespace = this.style.other.beforePropertyNameValueSeparator ? " " : "";
+        });
+    }
+
     protected async visitSwitch(switchNode: J.Switch, p: P): Promise<J | undefined> {
         const ret = await super.visitSwitch(switchNode, p) as J.Switch;
         return produceAsync(ret, async draft => {
@@ -406,11 +412,13 @@ export class SpacesVisitor<P> extends JavaScriptVisitor<P> {
             const spacing = this.style.aroundOperators.unary;
 
             switch (draft.operator.element) {
+                case J.Unary.Type.Not:
+                    draft.expression.prefix.whitespace = this.style.aroundOperators.afterUnaryNotAndNotNull ? " " : "";
+                    break;
                 case J.Unary.Type.PreIncrement:
                 case J.Unary.Type.PreDecrement:
                 case J.Unary.Type.Negative:
                 case J.Unary.Type.Positive:
-                case J.Unary.Type.Not:
                 case J.Unary.Type.Complement:
                     draft.expression.prefix.whitespace = spacing ? " " : "";
                     break;
@@ -462,18 +470,18 @@ export class SpacesVisitor<P> extends JavaScriptVisitor<P> {
     }
 
     private async spaceBeforeLeftPaddedElement<T extends J>(left: J.LeftPadded<T>, spaceBeforePadding: boolean, spaceBeforeElement: boolean): Promise<J.LeftPadded<T>> {
-        return produceAsync(left, async draft => {
+        return (await produceAsync(left, async draft => {
             if (draft.before.comments.length == 0) {
                 draft.before.whitespace = spaceBeforePadding ? " " : "";
             }
             draft.element = await this.spaceBefore(left.element, spaceBeforeElement) as Draft<T>;
-        });
+        }))!;
     }
 
     private async spaceBeforeRightPaddedElement<T extends J>(right: J.RightPadded<T>, spaceBefore: boolean): Promise<J.RightPadded<T>> {
-        return produceAsync(right, async draft => {
+        return (await produceAsync(right, async draft => {
             draft.element = await this.spaceBefore(right.element, spaceBefore) as Draft<T>;
-        });
+        }))!;
     }
 
     private async spaceBefore<T extends J>(j: T, spaceBefore: boolean): Promise<T> {
@@ -639,7 +647,9 @@ export class WrappingAndBracesVisitor<P> extends JavaScriptVisitor<P> {
         const b = await super.visitBlock(block, p) as J.Block;
         return produce(b, draft => {
             if (!draft.end.whitespace.includes("\n") && (draft.statements.length == 0 || !draft.statements[draft.statements.length - 1].after.whitespace.includes("\n"))) {
-                draft.end = this.withNewlineSpace(draft.end);
+                if (this.cursor.parent?.value.kind !== J.Kind.NewClass) {
+                    draft.end = this.withNewlineSpace(draft.end);
+                }
             }
         });
     }
@@ -825,8 +835,8 @@ export class MinimumViableSpacingVisitor<P> extends JavaScriptVisitor<P> {
         const ret = await super.visitNewClass(newClass, p) as J.NewClass;
         return produce(ret, draft => {
             if (draft.class) {
-                if (draft.class.kind == JS.Kind.TypeTreeExpression) {
-                    this.ensureSpace((draft.class as Draft<JS.TypeTreeExpression>).prefix);
+                if (draft.class.kind == J.Kind.Identifier) {
+                    this.ensureSpace((draft.class as Draft<J.Identifier>).prefix);
                 }
             }
         });
@@ -925,28 +935,30 @@ export class BlankLinesVisitor<P> extends JavaScriptVisitor<P> {
         super();
     }
 
-    override async visit<R extends J>(tree: Tree, p: P, cursor?: Cursor): Promise<R | undefined> {
-        if (this.cursor?.getNearestMessage("stop") != null) {
-            return tree as R;
-        }
-        if (tree.kind === JS.Kind.CompilationUnit) {
-            const cu = produce(tree as JS.CompilationUnit, draft => {
+    protected async preVisit(tree: J, p: P): Promise<J | undefined> {
+        let ret = await super.preVisit(tree, p) as J;
+
+        if (ret.kind === JS.Kind.CompilationUnit) {
+            ret = produce(ret as JS.CompilationUnit, draft => {
                 if (draft.prefix.comments.length == 0) {
                     draft.prefix.whitespace = "";
                 }
             });
-            return super.visit(cu, p, cursor);
         }
-        if (tree.kind === JS.Kind.StatementExpression && (tree as JS.StatementExpression).statement.kind == J.Kind.MethodDeclaration) {
-            tree = produce(tree as JS.StatementExpression, draft => {
-                this.ensurePrefixHasNewLine(draft);
-            });
-        } else if (tree.kind === J.Kind.MethodDeclaration && this.cursor.value.kind != JS.Kind.StatementExpression
-            && (this.cursor.parent?.value.kind != JS.Kind.CompilationUnit || (this.cursor.parent?.value as JS.CompilationUnit).statements[0].element !== tree)) {
-            tree = produce(tree as J.MethodDeclaration, draft => {
+        if (ret.kind === J.Kind.MethodDeclaration
+            && this.cursor.parent?.parent?.parent?.value.kind === J.Kind.ClassDeclaration) {
+            ret = produce(ret as JS.StatementExpression, draft => {
                 this.ensurePrefixHasNewLine(draft);
             });
         }
+
+        return ret;
+    }
+
+    override async visit<R extends J>(tree: Tree, p: P, cursor?: Cursor): Promise<R | undefined> {
+        if (this.cursor?.getNearestMessage("stop") != null) {
+            return tree as R;
+        }
         return super.visit(tree, p, cursor);
     }
 
@@ -1018,7 +1030,7 @@ export class BlankLinesVisitor<P> extends JavaScriptVisitor<P> {
                     }
                     this.keepMaximumBlankLines(draft, this.style.keepMaximum.inCode);
                 }
-            } else if (parent?.kind === J.Kind.Block ||
+            } else if (parent?.kind === J.Kind.Block && grandparent?.kind !== J.Kind.NewClass ||
                       (parent?.kind === JS.Kind.CompilationUnit && (parent! as JS.CompilationUnit).statements[0].element.id != draft.id) ||
                       (parent?.kind === J.Kind.Case)) {
                 if (draft.kind != J.Kind.Case) {
@@ -1031,8 +1043,10 @@ export class BlankLinesVisitor<P> extends JavaScriptVisitor<P> {
     protected async visitBlock(block: J.Block, p: P): Promise<J.Block> {
         const b = await super.visitBlock(block, p) as J.Block;
         return produce(b, draft => {
-            if (!draft.end.whitespace.includes("\n")) {
-                draft.end.whitespace = draft.end.whitespace + "\n";
+            if (this.cursor.parent?.value.kind != J.Kind.NewClass) {
+                if (!draft.end.whitespace.includes("\n")) {
+                    draft.end.whitespace = draft.end.whitespace.replace(/[ \t]+$/, '') + "\n";
+                }
             }
         });
     }
@@ -1108,7 +1122,7 @@ export class TabsAndIndentsVisitor<P> extends JavaScriptVisitor<P> {
         let indentShouldIncrease =
             tree.kind === J.Kind.Block
             || this.cursor.parent?.parent?.parent?.value.kind == J.Kind.Case
-            || (tree.kind === JS.Kind.StatementExpression && (tree as JS.StatementExpression).statement.kind == J.Kind.MethodDeclaration);
+            || (tree.kind === JS.Kind.StatementExpression && (tree as JS.StatementExpression).statement.kind == J.Kind.MethodDeclaration && tree.prefix.whitespace.includes("\n"));
 
         const previousIndent = this.currentIndent;
 
@@ -1168,10 +1182,34 @@ export class TabsAndIndentsVisitor<P> extends JavaScriptVisitor<P> {
         if (this.cursor?.getNearestMessage("stop") != null) {
             return tree as R;
         }
-        return await super.visit(tree, p, parent) as R;
+
+        if (parent) {
+            this.cursor = new Cursor(tree, parent);
+            for (let c: Cursor | undefined = this.cursor; c != null; c = c.parent) {
+                let space: J.Space;
+                const v = c.value;
+                if (v.kind == J.Kind.RightPadded) {
+                    space = v.after;
+                } else if (v.kind == J.Kind.LeftPadded || v.kind == J.Kind.Container) {
+                    space = v.before;
+                } else if (isJava(v) || isJavaScript(v)) {
+                    space = v.prefix;
+                } else {
+                    continue;
+                }
+
+                const lastWhitespace = space.comments.length > 0 ? space.comments[space.comments.length - 1].suffix : space.whitespace;
+                const idx = lastWhitespace.lastIndexOf('\n');
+                if (idx !== -1) {
+                    c.messages.set("indentToUse", lastWhitespace.substring(idx + 1));
+                    break;
+                }
+            }
+        }
+        return await super.visit(tree, p) as R;
     }
 
-    public async visitLeftPadded<T extends J | J.Space | number | string | boolean>(left: J.LeftPadded<T>, p: P): Promise<J.LeftPadded<T>> {
+    public async visitLeftPadded<T extends J | J.Space | number | string | boolean>(left: J.LeftPadded<T>, p: P): Promise<J.LeftPadded<T> | undefined> {
         const ret = await super.visitLeftPadded(left, p);
         if (ret == undefined) {
             return ret;

package/src/javascript/index.ts

@@ -22,6 +22,7 @@ export * from "./markers";
 export * from "./preconditions";
 export * from "./templating/index";
 export * from "./method-matcher";
+export * from "./format";
 
 export * from "./add-import";
 export * from "./remove-import";

package/src/javascript/parser.ts

@@ -76,7 +76,7 @@ export class JavaScriptParser extends Parser {
     private readonly compilerOptions: ts.CompilerOptions;
     private readonly styles?: NamedStyles[];
     private oldProgram?: ts.Program;
-    private sourceFileCache?: Map<string, ts.SourceFile>;
+    private readonly sourceFileCache?: Map<string, ts.SourceFile>;
 
     constructor(
         {
@@ -612,13 +612,10 @@ export class JavaScriptParserVisitor {
         }
         for (let heritageClause of node.heritageClauses) {
             if (heritageClause.token == ts.SyntaxKind.ExtendsKeyword) {
-                return this.leftPadded<TypeTree>(this.prefix(heritageClause.getFirstToken()!), {
-                    kind: JS.Kind.TypeTreeExpression,
-                    id: randomId(),
-                    prefix: this.prefix(heritageClause.types[0]),
-                    markers: emptyMarkers,
-                    expression: this.visit(heritageClause.types[0])
-                } satisfies JS.TypeTreeExpression as JS.TypeTreeExpression);
+                return this.leftPadded<TypeTree>(
+                    this.prefix(heritageClause.getFirstToken()!),
+                    this.mapTypeTree(heritageClause.types[0])
+                );
             }
         }
         return undefined;
@@ -666,6 +663,33 @@ export class JavaScriptParserVisitor {
         return undefined;
     }
 
+    private mapTypeTree(node: ts.LeftHandSideExpression | ts.ExpressionWithTypeArguments | ts.Expression): TypeTree {
+        const expression = this.visit(node);
+
+        // Check if the expression is already a TypeTree
+        // J.Identifier, J.FieldAccess, J.ArrayType, and J.ParameterizedType all implement TypeTree
+        if (expression.kind === J.Kind.Identifier ||
+            expression.kind === J.Kind.FieldAccess ||
+            expression.kind === J.Kind.ArrayType ||
+            expression.kind === J.Kind.ParameterizedType) {
+            return expression as TypeTree;
+        }
+
+        // For expressions that don't implement TypeTree, wrap them in JS.TypeTreeExpression
+        // Transfer the prefix from the expression to the wrapper
+        const prefix = expression.prefix;
+        return {
+            kind: JS.Kind.TypeTreeExpression,
+            id: randomId(),
+            prefix: prefix,
+            markers: emptyMarkers,
+            expression: {
+                ...expression,
+                prefix: emptySpace
+            },
+        } satisfies JS.TypeTreeExpression as JS.TypeTreeExpression;
+    }
+
     visitNumericLiteral(node: ts.NumericLiteral): J.Literal {
         // Parse the numeric value from the text
         const text = node.text;
@@ -906,28 +930,25 @@ export class JavaScriptParserVisitor {
         let annotationType: NameTree | TypeTree;
         let _arguments: J.Container<Expression> | undefined = undefined;
 
-        if (ts.isCallExpression(node.expression)) {
+        if (ts.isCallExpression(node.expression) && node.expression.typeArguments) {
             annotationType = {
                 kind: JS.Kind.ExpressionWithTypeArguments,
                 id: randomId(),
                 prefix: emptySpace,
                 markers: emptyMarkers,
                 clazz: this.convert<J>(node.expression.expression) as Expression,
-                typeArguments: node.expression.typeArguments && this.mapTypeArguments(this.suffix(node.expression.expression), node.expression.typeArguments)
+                typeArguments: this.mapTypeArguments(this.suffix(node.expression.expression), node.expression.typeArguments)
             } satisfies JS.ExpressionWithTypeArguments as JS.ExpressionWithTypeArguments;
             _arguments = this.mapCommaSeparatedList(node.expression.getChildren(this.sourceFile).slice(-3))
+        } else if (ts.isCallExpression(node.expression)) {
+            annotationType = this.convert<J>(node.expression.expression) as Expression;
+            _arguments = this.mapCommaSeparatedList(node.expression.getChildren(this.sourceFile).slice(-3))
         } else if (ts.isIdentifier(node.expression)) {
             annotationType = this.convert(node.expression);
         } else if (ts.isPropertyAccessExpression(node.expression)) {
             annotationType = this.convert(node.expression);
         } else if (ts.isParenthesizedExpression(node.expression)) {
-            annotationType = {
-                kind: JS.Kind.TypeTreeExpression,
-                id: randomId(),
-                prefix: this.prefix(node.expression),
-                markers: emptyMarkers,
-                expression: this.convert(node.expression) as Expression
-            } satisfies JS.TypeTreeExpression as JS.TypeTreeExpression;
+            annotationType = this.mapTypeTree(node.expression);
         } else {
             return this.visitUnknown(node);
         }
@@ -1999,22 +2020,21 @@ export class JavaScriptParserVisitor {
                 id: randomId(),
                 prefix: this.prefix(node.expression),
                 markers: emptyMarkers,
-                class: {
-                    kind: JS.Kind.TypeTreeExpression,
-                    id: randomId(),
-                    prefix: emptySpace,
-                    markers: emptyMarkers,
-                    expression: this.visit(node.expression),
-                } satisfies JS.TypeTreeExpression as JS.TypeTreeExpression,
+                class: (() => {
+                    // For parameterized types, we need to handle the prefix differently
+                    const typeTree = this.mapTypeTree(node.expression);
+                    // If it's a TypeTreeExpression, clear the prefix since it was already set on the ParameterizedType
+                    if (typeTree.kind === JS.Kind.TypeTreeExpression) {
+                        return {
+                            ...typeTree,
+                            prefix: emptySpace
+                        };
+                    }
+                    return typeTree;
+                })(),
                 typeParameters: this.mapTypeArguments(this.prefix(this.findChildNode(node, ts.SyntaxKind.LessThanToken)!), node.typeArguments),
                 type: undefined
-            } satisfies J.ParameterizedType as J.ParameterizedType : {
-                kind: JS.Kind.TypeTreeExpression,
-                id: randomId(),
-                prefix: this.prefix(node.expression),
-                markers: emptyMarkers,
-                expression: this.visit(node.expression),
-            } satisfies JS.TypeTreeExpression as JS.TypeTreeExpression,
+            } satisfies J.ParameterizedType as J.ParameterizedType : this.mapTypeTree(node.expression),
             arguments: node.arguments ?
                 this.mapCommaSeparatedList(this.getParameterListNodes(node)) : {
                     ...emptyContainer<Expression>(),

package/src/javascript/templating/capture.ts

@@ -13,8 +13,9 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import {J} from '../../java';
-import {Capture, Any, TemplateParam, CaptureOptions, VariadicOptions} from './types';
+import {Cursor} from '../..';
+import {J, Type} from '../../java';
+import {Any, Capture, CaptureOptions, ConstraintFunction, TemplateParam, VariadicOptions} from './types';
 
 /**
  * Combines multiple constraints with AND logic.
@@ -29,8 +30,8 @@ import {Capture, Any, TemplateParam, CaptureOptions, VariadicOptions} from './ty
  *     )
  * });
  */
-export function and<T>(...constraints: ((node: T) => boolean)[]): (node: T) => boolean {
-    return (node: T) => constraints.every(c => c(node));
+export function and<T>(...constraints: ((node: T, cursor?: Cursor) => boolean)[]): (node: T, cursor?: Cursor) => boolean {
+    return (node: T, cursor?: Cursor) => constraints.every(c => c(node, cursor));
 }
 
 /**
@@ -45,8 +46,8 @@ export function and<T>(...constraints: ((node: T) => boolean)[]): (node: T) => b
  *     )
  * });
  */
-export function or<T>(...constraints: ((node: T) => boolean)[]): (node: T) => boolean {
-    return (node: T) => constraints.some(c => c(node));
+export function or<T>(...constraints: ((node: T, cursor?: Cursor) => boolean)[]): (node: T, cursor?: Cursor) => boolean {
+    return (node: T, cursor?: Cursor) => constraints.some(c => c(node, cursor));
 }
 
 /**
@@ -58,8 +59,8 @@ export function or<T>(...constraints: ((node: T) => boolean)[]): (node: T) => bo
  *     constraint: not((node) => typeof node.value === 'string')
  * });
  */
-export function not<T>(constraint: (node: T) => boolean): (node: T) => boolean {
-    return (node: T) => !constraint(node);
+export function not<T>(constraint: (node: T, cursor?: Cursor) => boolean): (node: T, cursor?: Cursor) => boolean {
+    return (node: T, cursor?: Cursor) => !constraint(node, cursor);
 }
 
 // Symbol to access the internal capture name without triggering Proxy
@@ -70,13 +71,18 @@ export const CAPTURE_VARIADIC_SYMBOL = Symbol('captureVariadic');
 export const CAPTURE_CONSTRAINT_SYMBOL = Symbol('captureConstraint');
 // Symbol to access capturing flag without triggering Proxy
 export const CAPTURE_CAPTURING_SYMBOL = Symbol('captureCapturing');
+// Symbol to access type information without triggering Proxy
+export const CAPTURE_TYPE_SYMBOL = Symbol('captureType');
+// Symbol to identify RawCode instances
+export const RAW_CODE_SYMBOL = Symbol('rawCode');
 
 export class CaptureImpl<T = any> implements Capture<T> {
     public readonly name: string;
     [CAPTURE_NAME_SYMBOL]: string;
     [CAPTURE_VARIADIC_SYMBOL]: VariadicOptions | undefined;
-    [CAPTURE_CONSTRAINT_SYMBOL]: ((node: T) => boolean) | undefined;
+    [CAPTURE_CONSTRAINT_SYMBOL]: ConstraintFunction<T> | undefined;
     [CAPTURE_CAPTURING_SYMBOL]: boolean;
+    [CAPTURE_TYPE_SYMBOL]: string | Type | undefined;
 
     constructor(name: string, options?: CaptureOptions<T>, capturing: boolean = true) {
         this.name = name;
@@ -99,6 +105,11 @@ export class CaptureImpl<T = any> implements Capture<T> {
         if (options?.constraint) {
             this[CAPTURE_CONSTRAINT_SYMBOL] = options.constraint;
         }
+
+        // Store type if provided
+        if (options?.type) {
+            this[CAPTURE_TYPE_SYMBOL] = options.type;
+        }
     }
 
     getName(): string {
@@ -113,13 +124,17 @@ export class CaptureImpl<T = any> implements Capture<T> {
         return this[CAPTURE_VARIADIC_SYMBOL];
     }
 
-    getConstraint(): ((node: T) => boolean) | undefined {
+    getConstraint(): ConstraintFunction<T> | undefined {
         return this[CAPTURE_CONSTRAINT_SYMBOL];
     }
 
     isCapturing(): boolean {
         return this[CAPTURE_CAPTURING_SYMBOL];
     }
+
+    getType(): string | Type | undefined {
+        return this[CAPTURE_TYPE_SYMBOL];
+    }
 }
 
 export class TemplateParamImpl<T = any> implements TemplateParam<T> {
@@ -291,9 +306,17 @@ function createCaptureProxy<T>(impl: CaptureImpl<T>): any {
             if (prop === CAPTURE_CAPTURING_SYMBOL) {
                 return target[CAPTURE_CAPTURING_SYMBOL];
             }
+            if (prop === CAPTURE_TYPE_SYMBOL) {
+                return target[CAPTURE_TYPE_SYMBOL];
+            }
+
+            // Support using Capture as object key via computed properties {[x]: value}
+            if (prop === Symbol.toPrimitive || prop === 'toString' || prop === 'valueOf') {
+                return () => target[CAPTURE_NAME_SYMBOL];
+            }
 
             // Allow methods to be called directly on the target
-            if (prop === 'getName' || prop === 'isVariadic' || prop === 'getVariadicOptions' || prop === 'getConstraint' || prop === 'isCapturing') {
+            if (prop === 'getName' || prop === 'isVariadic' || prop === 'getVariadicOptions' || prop === 'getConstraint' || prop === 'isCapturing' || prop === 'getType') {
                 return target[prop].bind(target);
             }
 
@@ -330,12 +353,12 @@ function createCaptureProxy<T>(impl: CaptureImpl<T>): any {
 
 // Overload 1: Options object with constraint (no variadic)
 export function capture<T = any>(
-    options: { name?: string; constraint: (node: T) => boolean } & { variadic?: never }
+    options: CaptureOptions<T> & { variadic?: never }
 ): Capture<T> & T;
 
 // Overload 2: Options object with variadic
 export function capture<T = any>(
-    options: { name?: string; variadic: true | VariadicOptions; constraint?: (nodes: T[]) => boolean; min?: number; max?: number }
+    options: { name?: string; variadic: true | VariadicOptions; constraint?: ConstraintFunction<T[]>; min?: number; max?: number }
 ): Capture<T[]> & T[];
 
 // Overload 3: Just a string name (simple named capture)
@@ -417,12 +440,12 @@ capture.nextUnnamedId = 1;
  */
 // Overload 1: Regular any with constraint (most specific - no variadic property)
 export function any<T = any>(
-    options: { constraint: (node: T) => boolean } & { variadic?: never }
+    options: { constraint: ConstraintFunction<T> } & { variadic?: never }
 ): Any<T> & T;
 
 // Overload 2: Variadic any with constraint
 export function any<T = any>(
-    options: { variadic: true | VariadicOptions; constraint?: (nodes: T[]) => boolean; min?: number; max?: number }
+    options: { variadic: true | VariadicOptions; constraint?: ConstraintFunction<T[]>; min?: number; max?: number }
 ): Any<T[]> & T[];
 
 // Overload 3: Catch-all for simple any without special options
@@ -489,6 +512,75 @@ export function param<T = any>(name?: string): TemplateParam<T> {
     return new TemplateParamImpl<T>(paramName);
 }
 
+/**
+ * Represents raw code that should be inserted verbatim into templates at construction time.
+ * This is useful for dynamic code generation where the code structure is determined at runtime.
+ */
+export class RawCode {
+    [RAW_CODE_SYMBOL] = true;
+
+    constructor(public readonly code: string) {}
+}
+
+/**
+ * Creates a raw code specification for inserting literal code strings into templates.
+ *
+ * Use `raw()` when you need to insert code that is generated dynamically (e.g., from recipe options,
+ * computed field names, or programmatic string manipulation) directly into a template at construction time.
+ *
+ * The string is spliced into the template before parsing, so it becomes part of the template's AST.
+ * This is different from `param()` or `capture()` which are placeholders replaced during application.
+ *
+ * @param code The code string to insert verbatim into the template
+ * @returns A RawCode object that will be spliced into the template
+ *
+ * @remarks
+ * **When to use `raw()` vs `param()` vs `capture()`:**
+ *
+ * - Use `raw()` when you have a **code string** to insert at **template construction time**
+ * - Use `param()` when you have an **AST node** to substitute at **template application time**
+ * - Use `capture()` when working with **pattern matching** and need to reference matched values
+ *
+ * **Safety Considerations:**
+ * - No validation is performed on the code string
+ * - The code must be syntactically valid at the position where it's inserted
+ * - Recipe authors are trusted to provide valid code
+ *
+ * @example
+ * // Recipe option determines the log level
+ * class MyRecipe extends Recipe {
+ *     @Option
+ *     logLevel: string = "info";
+ *
+ *     getVisitor() {
+ *         // Template constructed with dynamic method name
+ *         const replacement = template`logger.${raw(this.logLevel)}(${_('msg')})`;
+ *         // Produces: logger.info(...) or logger.warn(...) etc.
+ *     }
+ * }
+ *
+ * @example
+ * // Build object literal from collected field names
+ * const fields = ["userId", "timestamp", "status"];
+ * template`{ ${raw(fields.join(', '))} }`
+ * // Produces: { userId, timestamp, status }
+ *
+ * @example
+ * // Dynamic import path
+ * const modulePath = "./utils";
+ * template`import { helper } from ${raw(`'${modulePath}'`)}`
+ * // Produces: import { helper } from './utils'
+ *
+ * @example
+ * // Configurable operator
+ * const operator = ">=";
+ * template`${_('value')} ${raw(operator)} threshold`
+ * // Produces: value >= threshold
+ */
+export function raw(code: string): RawCode {
+    return new RawCode(code);
+}
+
 /**
  * Concise alias for `capture`. Works well for inline captures in patterns and templates.
  *