@openrewrite/rewrite 8.66.1 → 8.66.2

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

@@ -1,5 +1,8 @@
 import { Cursor, Tree } from '../..';
-import { J } from '../../java';
+import { J, Type } from '../../java';
+import type { Pattern } from "./pattern";
+import type { Template } from "./template";
+import type { CaptureValue, RawCode } from "./capture";
 /**
  * Options for variadic captures that match zero or more nodes in a sequence.
  */
@@ -13,6 +16,18 @@ export interface VariadicOptions {
      */
     max?: number;
 }
+/**
+ * Constraint function for captures.
+ * The cursor parameter is always provided with a defined value, but functions can
+ * choose to accept it or not (TypeScript allows functions with fewer parameters).
+ *
+ * For non-variadic captures: use ConstraintFunction<T> where T is the node type
+ * For variadic captures: use ConstraintFunction<T[]> where T[] is the array type
+ *
+ * When used with variadic captures, the cursor points to the nearest common parent
+ * of the captured elements.
+ */
+export type ConstraintFunction<T> = (node: T, cursor: Cursor) => boolean;
 /**
  * Options for the capture function.
  *
@@ -20,11 +35,53 @@ export interface VariadicOptions {
  * 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[]
+ *
+ * The constraint function can optionally receive a cursor parameter to perform
+ * context-aware validation during pattern matching.
  */
 export interface CaptureOptions<T = any> {
     name?: string;
     variadic?: boolean | VariadicOptions;
-    constraint?: (node: T) => boolean;
+    /**
+     * Optional constraint function that validates whether a captured node should be accepted.
+     * The function always receives:
+     * - node: The captured node (or array of nodes for variadic captures)
+     * - cursor: A cursor at the captured node's position (always defined)
+     *
+     * Functions can choose to accept just the node parameter if they don't need the cursor.
+     *
+     * @param node The captured node to validate
+     * @param cursor Cursor at the captured node's position
+     * @returns true if the capture should be accepted, false otherwise
+     *
+     * @example
+     * ```typescript
+     * // Simple node validation (cursor parameter ignored)
+     * capture<J.Literal>('size', {
+     *     constraint: (node) => typeof node.value === 'number' && node.value > 100
+     * })
+     *
+     * // Context-aware validation (using cursor)
+     * capture<J.MethodInvocation>('method', {
+     *     constraint: (node, cursor) => {
+     *         if (!node.name.simpleName.startsWith('get')) return false;
+     *         const cls = cursor.firstEnclosing(isClassDeclaration);
+     *         return cls?.name.simpleName === 'ApiController';
+     *     }
+     * })
+     * ```
+     */
+    constraint?: ConstraintFunction<T>;
+    /**
+     * Type annotation for this capture. When provided, the template engine will generate
+     * a preamble declaring the capture identifier with this type annotation, allowing
+     * the TypeScript parser/compiler to produce a properly type-attributed AST.
+     *
+     * Can be specified as:
+     * - A string type annotation (e.g., "boolean", "string", "number")
+     * - A Type instance from the AST (the type will be inferred from the Type)
+     */
+    type?: string | Type;
 }
 /**
  * Capture specification for pattern matching.
@@ -39,14 +96,14 @@ export interface CaptureOptions<T = any> {
  * 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
+ * - A bare `pattern`${capture()}`` will structurally match ANY expression
+ * - Pattern structure determines matching: `pattern`foo(${capture()})`` only matches `foo()` calls with one arg
  * - 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 });
+ * const args = capture({ variadic: true });
  * pattern`foo(${args})`  // Matches: foo(), foo(a), foo(a, b, c)
  * ```
  */
@@ -67,8 +124,9 @@ export interface Capture<T = any> {
      * 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.
+     * The constraint function can optionally receive a cursor for context-aware validation.
      */
-    getConstraint?(): ((node: T) => boolean) | undefined;
+    getConstraint?(): ConstraintFunction<T> | undefined;
 }
 /**
  * Non-capturing pattern match specification.
@@ -102,8 +160,9 @@ export interface Capture<T = any> {
  *
  * @example
  * // Variadic any - match zero or more without capturing
+ * const first = any();
  * const rest = any({ variadic: true });
- * const pat = pattern`bar(${capture('first')}, ${rest})`
+ * const pat = pattern`bar(${first}, ${rest})`
  *
  * @example
  * // With constraints - validate but don't capture
@@ -130,7 +189,7 @@ export interface Any<T = any> {
      * 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;
+    getConstraint?(): ConstraintFunction<T> | undefined;
 }
 /**
  * Template parameter specification for template-only parameter substitution.
@@ -192,16 +251,79 @@ export interface PatternOptions {
      * @default true (lenient matching enabled for backward compatibility)
      */
     lenientTypeMatching?: boolean;
+    /**
+     * Enable debug logging for this pattern.
+     * When enabled, all match attempts will log detailed information to stderr,
+     * including the AST path traversed, mismatches encountered, and captured values.
+     *
+     * Can be overridden at the match() call level.
+     * Global debug can be enabled via PATTERN_DEBUG=true environment variable.
+     *
+     * Precedence: match() call > pattern configure() > PATTERN_DEBUG env var
+     *
+     * @default undefined (inherits from environment or match() call)
+     *
+     * @example
+     * ```typescript
+     * // Pattern-level debug
+     * const pat = pattern({ debug: true })`console.log(${value})`;
+     *
+     * // Disable debug for a noisy pattern when global debug is on
+     * const noisyPat = pattern({ debug: false })`import ${x} from ${y}`;
+     * ```
+     */
+    debug?: boolean;
+}
+/**
+ * Options for individual match() calls.
+ */
+export interface MatchOptions {
+    /**
+     * Enable debug logging for this specific match() call.
+     * Overrides pattern-level debug setting and global PATTERN_DEBUG env var.
+     *
+     * @example
+     * ```typescript
+     * // Debug just this call
+     * const match = await pattern.match(node, cursor, { debug: true });
+     *
+     * // Disable debug for this call even if pattern or global debug is on
+     * const match = await pattern.match(node, cursor, { debug: false });
+     * ```
+     */
+    debug?: 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))
+ * - TemplateParam: For standalone template parameters
+ * - RawCode: For inserting literal code strings at construction time
  * - 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
+ * - J.RightPadded<any>: Wrapper containing an element with markers (element will be extracted)
+ * - J.RightPadded<any>[]: Array of wrappers (elements will be expanded)
+ * - J.Container<any>: Container with elements (elements will be expanded)
+ *
+ * Note: Primitive values (string, number, boolean) are NOT supported in template literals.
+ * Use raw() for inserting code strings, or Template.builder() API for programmatic construction.
  */
-export type TemplateParameter = Capture | any | TemplateParam | Tree | Tree[] | string | number | boolean;
+export type TemplateParameter = Capture | CaptureValue | TemplateParam | RawCode | Tree | Tree[] | J.RightPadded<any> | J.RightPadded<any>[] | J.Container<any>;
+/**
+ * Parameter specification for template generation (internal).
+ * Represents a placeholder in a template that will be replaced with a parameter value.
+ * This is the internal wrapper used by the template engine.
+ *
+ * Note: The value is typed as `any` rather than `TemplateParameter` to allow flexible
+ * internal handling without excessive type guards. The public API (template function)
+ * constrains inputs to `TemplateParameter`, providing type safety at the API boundary.
+ */
+export interface Parameter {
+    /**
+     * The value to substitute into the template.
+     */
+    value: any;
+}
 /**
  * Configuration options for templates.
  */
@@ -252,12 +374,237 @@ export interface RewriteRule {
      *          node when there's no match: `return await rule.tryOn(this.cursor, node) || node;`
      */
     tryOn(cursor: Cursor, node: J): Promise<J | undefined>;
+    /**
+     * Chains this rule with another rule, creating a composite rule that applies both transformations sequentially.
+     *
+     * The resulting rule:
+     * 1. First applies this rule to the input node
+     * 2. If this rule matches and transforms the node, applies the next rule to the result
+     * 3. If the next rule returns undefined (no match), keeps the result from the first rule
+     * 4. If this rule returns undefined (no match), returns undefined without trying the next rule
+     *
+     * @param next The rule to apply after this rule
+     * @returns A new RewriteRule that applies both rules in sequence
+     *
+     * @example
+     * ```typescript
+     * const rule1 = rewrite(() => {
+     *     const { a, b } = { a: capture(), b: capture() };
+     *     return {
+     *         before: pattern`${a} + ${b}`,
+     *         after: template`${b} + ${a}`
+     *     };
+     * });
+     *
+     * const rule2 = rewrite(() => ({
+     *     before: pattern`${capture('x')} + 1`,
+     *     after: template`${capture('x')}++`
+     * }));
+     *
+     * const combined = rule1.andThen(rule2);
+     * // Will first swap operands, then if result matches "x + 1", change to "x++"
+     * ```
+     */
+    andThen(next: RewriteRule): RewriteRule;
+    /**
+     * Creates a composite rule that tries this rule first, and if it doesn't match, tries an alternative rule.
+     *
+     * The resulting rule:
+     * 1. First applies this rule to the input node
+     * 2. If this rule matches and transforms the node, returns the result
+     * 3. If this rule returns undefined (no match), tries the alternative rule on the original node
+     *
+     * @param alternative The rule to try if this rule doesn't match
+     * @returns A new RewriteRule that tries both rules with fallback behavior
+     *
+     * @example
+     * ```typescript
+     * // Try specific pattern first, fall back to general pattern
+     * const specific = rewrite(() => ({
+     *     before: pattern`foo(${capture('x')}, 0)`,
+     *     after: template`bar(${capture('x')})`
+     * }));
+     *
+     * const general = rewrite(() => ({
+     *     before: pattern`foo(${capture('x')}, ${capture('y')})`,
+     *     after: template`baz(${capture('x')}, ${capture('y')})`
+     * }));
+     *
+     * const combined = specific.orElse(general);
+     * // Will try specific pattern first, if no match, try general pattern
+     * ```
+     */
+    orElse(alternative: RewriteRule): RewriteRule;
 }
 /**
  * Configuration for a replacement rule.
  */
 export interface RewriteConfig {
-    before: any;
-    after: any;
+    before: Pattern | Pattern[];
+    after: Template | ((match: MatchResult) => Template);
+    /**
+     * Optional context predicate that must evaluate to true for the transformation to be applied.
+     * Evaluated after the pattern matches structurally but before applying the template.
+     * Provides access to both the matched node and the cursor for context inspection.
+     *
+     * @param node The matched AST node
+     * @param cursor The cursor at the matched node, providing access to ancestors and context
+     * @returns true if the transformation should be applied, false otherwise
+     *
+     * @example
+     * ```typescript
+     * rewrite(() => ({
+     *     before: pattern`await ${_('promise')}`,
+     *     after: template`await ${_('promise')}.catch(handleError)`,
+     *     where: (node, cursor) => {
+     *         // Only apply inside async functions
+     *         const method = cursor.firstEnclosing((n: any): n is J.MethodDeclaration =>
+     *             n.kind === J.Kind.MethodDeclaration
+     *         );
+     *         return method?.modifiers.some(m => m.type === 'async') || false;
+     *     }
+     * }));
+     * ```
+     */
+    where?: (node: J, cursor: Cursor) => boolean | Promise<boolean>;
+    /**
+     * Optional context predicate that must evaluate to false for the transformation to be applied.
+     * Evaluated after the pattern matches structurally but before applying the template.
+     * Provides access to both the matched node and the cursor for context inspection.
+     *
+     * @param node The matched AST node
+     * @param cursor The cursor at the matched node, providing access to ancestors and context
+     * @returns true if the transformation should NOT be applied, false if it should proceed
+     *
+     * @example
+     * ```typescript
+     * rewrite(() => ({
+     *     before: pattern`await ${_('promise')}`,
+     *     after: template`await ${_('promise')}.catch(handleError)`,
+     *     whereNot: (node, cursor) => {
+     *         // Don't apply inside try-catch blocks
+     *         return cursor.firstEnclosing((n: any): n is J.Try =>
+     *             n.kind === J.Kind.Try
+     *         ) !== undefined;
+     *     }
+     * }));
+     * ```
+     */
+    whereNot?: (node: J, cursor: Cursor) => boolean | Promise<boolean>;
+}
+/**
+ * Options for debugging pattern matching.
+ * Used in Layer 1 (Core Instrumentation) to control debug output.
+ */
+export interface DebugOptions {
+    /**
+     * Enable detailed logging during pattern matching.
+     */
+    enabled?: boolean;
+    /**
+     * Log structural comparison steps.
+     */
+    logComparison?: boolean;
+    /**
+     * Log constraint evaluation.
+     */
+    logConstraints?: boolean;
+}
+/**
+ * A single debug log entry collected during pattern matching.
+ * Part of Layer 1 (Core Instrumentation).
+ */
+export interface DebugLogEntry {
+    /**
+     * Severity level of the log entry.
+     */
+    level: 'trace' | 'debug' | 'info' | 'warn';
+    /**
+     * The scope/category of the log entry.
+     */
+    scope: 'matching' | 'comparison' | 'constraint';
+    /**
+     * Path in the AST where this log entry was generated.
+     */
+    path: string[];
+    /**
+     * Human-readable message.
+     */
+    message: string;
+    /**
+     * Optional data associated with this log entry.
+     */
+    data?: any;
+}
+/**
+ * Detailed explanation of why a pattern failed to match.
+ * Built by Layer 1 (Core Instrumentation) and exposed by Layer 2 (API).
+ */
+export interface MatchExplanation {
+    /**
+     * The reason for the match failure.
+     */
+    reason: 'structural-mismatch' | 'constraint-failed' | 'type-mismatch' | 'kind-mismatch' | 'value-mismatch' | 'array-length-mismatch';
+    /**
+     * Path in the AST where the failure occurred (e.g., ['select', 'name']).
+     */
+    path: string[];
+    /**
+     * Human-readable description of what was expected.
+     */
+    expected: string;
+    /**
+     * Human-readable description of what was actually found.
+     */
+    actual: string;
+    /**
+     * For constraint failures, details about which constraints failed.
+     */
+    constraintFailures?: Array<{
+        captureName: string;
+        actualValue: any;
+        error?: string;
+    }>;
+    /**
+     * Additional context about the failure.
+     */
+    details?: string;
+}
+/**
+ * Interface for accessing captured nodes from a successful pattern match.
+ * Part of the public API.
+ */
+export interface MatchResult {
+    /**
+     * Get a captured node by name or by Capture object.
+     *
+     * @param capture The capture name (string) or Capture object
+     * @returns The captured node(s), or undefined if not found
+     */
+    get(capture: string): any;
+    get<T>(capture: Capture<T>): T | undefined;
+}
+/**
+ * Result of a pattern match attempt with debug information.
+ * Part of Layer 2 (Public API).
+ */
+export interface MatchAttemptResult {
+    /**
+     * Whether the pattern matched successfully.
+     */
+    matched: boolean;
+    /**
+     * If matched, the match result with captured nodes. Undefined if not matched.
+     * Use `result.get('captureName')` or `result.get(captureObject)` to access captures.
+     */
+    result?: MatchResult;
+    /**
+     * If not matched, explanation of why. Undefined if matched.
+     */
+    explanation?: MatchExplanation;
+    /**
+     * Debug log entries collected during matching (if debug was enabled).
+     */
+    debugLog?: DebugLogEntry[];
 }
 //# sourceMappingURL=types.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/javascript/templating/types.ts"],"names":[],"mappings":"AAeA,OAAO,EAAC,MAAM,EAAE,IAAI,EAAC,MAAM,OAAO,CAAC;AACnC,OAAO,EAAC,CAAC,EAAC,MAAM,YAAY,CAAC;AAE7B;;GAEG;AACH,MAAM,WAAW,eAAe;IAC5B;;OAEG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC,GAAG,GAAG;IACnC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,OAAO,GAAG,eAAe,CAAC;IACrC,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC;CACrC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,OAAO,CAAC,CAAC,GAAG,GAAG;IAC5B;;OAEG;IACH,OAAO,IAAI,MAAM,CAAC;IAElB;;OAEG;IACH,UAAU,IAAI,OAAO,CAAC;IAEtB;;OAEG;IACH,kBAAkB,IAAI,eAAe,GAAG,SAAS,CAAC;IAElD;;;;OAIG;IACH,aAAa,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,GAAG,SAAS,CAAC;CACxD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,MAAM,WAAW,GAAG,CAAC,CAAC,GAAG,GAAG;IACxB;;OAEG;IACH,OAAO,IAAI,MAAM,CAAC;IAElB;;OAEG;IACH,UAAU,IAAI,OAAO,CAAC;IAEtB;;OAEG;IACH,kBAAkB,IAAI,eAAe,GAAG,SAAS,CAAC;IAElD;;;;OAIG;IACH,aAAa,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,GAAG,SAAS,CAAC;CACxD;AAED;;;;;GAKG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC,GAAG,GAAG;IAClC;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;OAEG;IACH,OAAO,IAAI,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC3B;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IAEnB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IAEnB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEtC;;;;;;;OAOG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;CACjC;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,iBAAiB,GAAG,OAAO,GAAG,GAAG,GAAG,aAAa,GAAG,IAAI,GAAG,IAAI,EAAE,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAE1G;;GAEG;AACH,MAAM,WAAW,eAAe;IAC5B;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IAEnB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IAEnB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACzC;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IACxB;;;;;;;;OAQG;IACH,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;CAC1D;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC1B,MAAM,EAAE,GAAG,CAAC;IACZ,KAAK,EAAE,GAAG,CAAC;CACd"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/javascript/templating/types.ts"],"names":[],"mappings":"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"}

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

@@ -1,7 +1,6 @@
 import { J } from '../../java';
-import { JS } from '../index';
-import { Marker } from '../../markers';
-import { VariadicOptions, Capture, Any } from './types';
+import { Marker, Markers } from '../../markers';
+import { ConstraintFunction, VariadicOptions } from './types';
 /**
  * Internal storage value type for pattern match captures.
  * - J: Scalar captures without wrapper (fallback)
@@ -15,25 +14,42 @@ export type CaptureStorageValue = J | J.RightPadded<J> | J[] | J.RightPadded<J>[
  */
 export declare const WRAPPERS_MAP_SYMBOL: unique symbol;
 /**
- * Cache for compiled templates and patterns.
- * Stores parsed ASTs to avoid expensive re-parsing and dependency resolution.
+ * Shared wrapper function name used by both patterns and templates.
+ * Using the same name allows cache sharing when pattern and template code is identical.
  */
-export declare class TemplateCache {
+export declare const WRAPPER_FUNCTION_NAME = "__WRAPPER__";
+/**
+ * Simple LRU (Least Recently Used) cache implementation using Map's insertion order.
+ * JavaScript Map maintains insertion order, so the first entry is the oldest.
+ *
+ * Used by both Pattern and Template caching to provide bounded memory usage.
+ */
+export declare class LRUCache<K, V> {
+    private maxSize;
     private cache;
-    /**
-     * Generates a cache key from template string, captures, and options.
-     */
-    private generateKey;
-    /**
-     * Gets a cached compilation unit or creates and caches a new one.
-     */
-    getOrParse(templateString: string, captures: (Capture | Any<any>)[], contextStatements: string[], dependencies: Record<string, string>): Promise<JS.CompilationUnit>;
-    /**
-     * Clears the cache.
-     */
+    constructor(maxSize: number);
+    get(key: K): V | undefined;
+    set(key: K, value: V): void;
     clear(): void;
 }
-export declare const templateCache: TemplateCache;
+/**
+ * Shared global LRU cache for both pattern and template ASTs.
+ * When pattern and template code is identical, they share the same cached AST.
+ * This mirrors JavaTemplate's unified approach in the Java implementation.
+ * Bounded to 100 entries using LRU eviction.
+ */
+export declare const globalAstCache: LRUCache<string, J>;
+/**
+ * Generates a cache key for template/pattern processing.
+ * Used by both Pattern and Template for consistent cache key generation.
+ *
+ * @param templateParts The template string parts
+ * @param itemsKey String representing the captures/parameters (comma-separated)
+ * @param contextStatements Context declarations
+ * @param dependencies NPM dependencies
+ * @returns A cache key string
+ */
+export declare function generateCacheKey(templateParts: string[] | TemplateStringsArray, itemsKey: string, contextStatements: string[], dependencies: Record<string, string>): string;
 /**
  * Marker that stores capture metadata on pattern AST nodes.
  * This avoids the need to parse capture names from identifiers during matching.
@@ -41,9 +57,10 @@ export declare const templateCache: TemplateCache;
 export declare class CaptureMarker implements Marker {
     readonly captureName: string;
     readonly variadicOptions?: VariadicOptions | undefined;
+    readonly constraint?: ConstraintFunction<any> | undefined;
     readonly kind = "org.openrewrite.javascript.CaptureMarker";
     readonly id: string;
-    constructor(captureName: string, variadicOptions?: VariadicOptions | undefined);
+    constructor(captureName: string, variadicOptions?: VariadicOptions | undefined, constraint?: ConstraintFunction<any> | undefined);
 }
 /**
  * Utility class for managing placeholder naming and parsing.
@@ -59,20 +76,15 @@ export declare class PlaceholderUtils {
      * @returns true if the node is a capture placeholder, false otherwise
      */
     static isCapture(node: J): boolean;
-    /**
-     * 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;
     /**
      * 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;
+    static getCaptureMarker(node: {
+        markers: Markers;
+    }): CaptureMarker | undefined;
     /**
      * Parses a capture placeholder to extract name and type constraint.
      *
@@ -97,22 +109,27 @@ export declare class PlaceholderUtils {
      * @param node The node to check
      * @returns true if the node has a variadic CaptureMarker, false otherwise
      */
-    static isVariadicCapture(node: J): boolean;
+    static isVariadicCapture(node: {
+        markers: Markers;
+    }): boolean;
     /**
      * 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;
+    static getVariadicOptions(node: {
+        markers: Markers;
+    }): VariadicOptions | 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.
+     * Extracts the relevant AST node from a wrapper function.
+     * Used by both pattern and template processors to intelligently extract
+     * code from `function __WRAPPER__() { code }` wrappers.
      *
-     * @param stmt The statement to check
-     * @returns The unwrapped capture identifier, or the original statement if not wrapped
+     * @param lastStatement The last statement from the compilation unit
+     * @param contextName Context name for error messages (e.g., 'Pattern', 'Template')
+     * @returns The extracted AST node
      */
-    static unwrapStatementCapture(stmt: J): J;
+    static extractFromWrapper(lastStatement: J, contextName: string): J;
 }
 //# sourceMappingURL=utils.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../src/javascript/templating/utils.ts"],"names":[],"mappings":"AAeA,OAAO,EAAC,CAAC,EAAC,MAAM,YAAY,CAAC;AAC7B,OAAO,EAAC,EAAE,EAAC,MAAM,UAAU,CAAC;AAG5B,OAAO,EAAC,MAAM,EAAC,MAAM,eAAe,CAAC;AAErC,OAAO,EAAC,eAAe,EAAE,OAAO,EAAE,GAAG,EAAC,MAAM,SAAS,CAAC;AAEtD;;;;;;GAMG;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,GAAG,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC;AAElF;;GAEG;AACH,eAAO,MAAM,mBAAmB,eAAwB,CAAC;AAEzD;;;GAGG;AACH,qBAAa,aAAa;IACtB,OAAO,CAAC,KAAK,CAAyC;IAEtD;;OAEG;IACH,OAAO,CAAC,WAAW;IAqBnB;;OAEG;IACG,UAAU,CACZ,cAAc,EAAE,MAAM,EACtB,QAAQ,EAAE,CAAC,OAAO,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,EAChC,iBAAiB,EAAE,MAAM,EAAE,EAC3B,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACrC,OAAO,CAAC,EAAE,CAAC,eAAe,CAAC;IA8B9B;;OAEG;IACH,KAAK,IAAI,IAAI;CAGhB;AAGD,eAAO,MAAM,aAAa,eAAsB,CAAC;AAEjD;;;GAGG;AACH,qBAAa,aAAc,YAAW,MAAM;aAKpB,WAAW,EAAE,MAAM;aACnB,eAAe,CAAC,EAAE,eAAe;IALrD,QAAQ,CAAC,IAAI,8CAA8C;IAC3D,QAAQ,CAAC,EAAE,SAAc;gBAGL,WAAW,EAAE,MAAM,EACnB,eAAe,CAAC,EAAE,eAAe,YAAA;CAGxD;AAED;;;GAGG;AACH,qBAAa,gBAAgB;IACzB,MAAM,CAAC,QAAQ,CAAC,cAAc,aAAa;IAC3C,MAAM,CAAC,QAAQ,CAAC,kBAAkB,oBAAoB;IAEtD;;;;;OAKG;IACH,MAAM,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC,GAAG,OAAO;IAUlC;;;;;OAKG;IACH,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,CAAC,GAAG,MAAM,GAAG,SAAS;IAWlD;;;;;OAKG;IACH,MAAM,CAAC,gBAAgB,CAAC,IAAI,EAAE,CAAC,GAAG,aAAa,GAAG,SAAS;IAS3D;;;;;OAKG;IACH,MAAM,CAAC,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,cAAc,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAuBzF;;;;;;OAMG;IACH,MAAM,CAAC,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,cAAc,CAAC,EAAE,MAAM,GAAG,MAAM;IAOnE;;;;;OAKG;IACH,MAAM,CAAC,iBAAiB,CAAC,IAAI,EAAE,CAAC,GAAG,OAAO;IAS1C;;;;;OAKG;IACH,MAAM,CAAC,kBAAkB,CAAC,IAAI,EAAE,CAAC,GAAG,eAAe,GAAG,SAAS;IAS/D;;;;;;;OAOG;IACH,MAAM,CAAC,sBAAsB,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC;CAc5C"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../src/javascript/templating/utils.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAC,CAAC,EAAC,MAAM,YAAY,CAAC;AAE7B,OAAO,EAAC,MAAM,EAAE,OAAO,EAAC,MAAM,eAAe,CAAC;AAE9C,OAAO,EAAC,kBAAkB,EAAE,eAAe,EAAC,MAAM,SAAS,CAAC;AAE5D;;;;;;GAMG;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,GAAG,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC;AAElF;;GAEG;AACH,eAAO,MAAM,mBAAmB,eAAwB,CAAC;AAEzD;;;GAGG;AACH,eAAO,MAAM,qBAAqB,gBAAgB,CAAC;AAEnD;;;;;GAKG;AACH,qBAAa,QAAQ,CAAC,CAAC,EAAE,CAAC;IAGV,OAAO,CAAC,OAAO;IAF3B,OAAO,CAAC,KAAK,CAAmB;gBAEZ,OAAO,EAAE,MAAM;IAGnC,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,SAAS;IAU1B,GAAG,CAAC,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI;IAiB3B,KAAK,IAAI,IAAI;CAGhB;AAED;;;;;GAKG;AACH,eAAO,MAAM,cAAc,qBAA+B,CAAC;AAE3D;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC5B,aAAa,EAAE,MAAM,EAAE,GAAG,oBAAoB,EAC9C,QAAQ,EAAE,MAAM,EAChB,iBAAiB,EAAE,MAAM,EAAE,EAC3B,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACrC,MAAM,CAOR;AAED;;;GAGG;AACH,qBAAa,aAAc,YAAW,MAAM;aAKpB,WAAW,EAAE,MAAM;aACnB,eAAe,CAAC,EAAE,eAAe;aACjC,UAAU,CAAC,EAAE,kBAAkB,CAAC,GAAG,CAAC;IANxD,QAAQ,CAAC,IAAI,8CAA8C;IAC3D,QAAQ,CAAC,EAAE,SAAc;gBAGL,WAAW,EAAE,MAAM,EACnB,eAAe,CAAC,EAAE,eAAe,YAAA,EACjC,UAAU,CAAC,EAAE,kBAAkB,CAAC,GAAG,CAAC,YAAA;CAG3D;AAED;;;GAGG;AACH,qBAAa,gBAAgB;IACzB,MAAM,CAAC,QAAQ,CAAC,cAAc,aAAa;IAC3C,MAAM,CAAC,QAAQ,CAAC,kBAAkB,oBAAoB;IAEtD;;;;;OAKG;IACH,MAAM,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC,GAAG,OAAO;IAUlC;;;;;OAKG;IACH,MAAM,CAAC,gBAAgB,CAAC,IAAI,EAAE;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,GAAG,aAAa,GAAG,SAAS;IAS9E;;;;;OAKG;IACH,MAAM,CAAC,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,cAAc,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAuBzF;;;;;;OAMG;IACH,MAAM,CAAC,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,cAAc,CAAC,EAAE,MAAM,GAAG,MAAM;IAOnE;;;;;OAKG;IACH,MAAM,CAAC,iBAAiB,CAAC,IAAI,EAAE;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO;IAS7D;;;;;OAKG;IACH,MAAM,CAAC,kBAAkB,CAAC,IAAI,EAAE;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,GAAG,eAAe,GAAG,SAAS;IASlF;;;;;;;;OAQG;IACH,MAAM,CAAC,kBAAkB,CAAC,aAAa,EAAE,CAAC,EAAE,WAAW,EAAE,MAAM,GAAG,CAAC;CA0CtE"}