@openrewrite/rewrite 8.67.0-20251112-160335 → 8.67.0-20251113-160321

package/src/javascript/templating/pattern.ts

@@ -15,11 +15,13 @@
  */
 import {Cursor} from '../..';
 import {J} from '../../java';
-import {Any, Capture, PatternOptions} from './types';
+import {Any, Capture, DebugLogEntry, DebugOptions, MatchAttemptResult, MatchExplanation, MatchOptions, PatternOptions, MatchResult as IMatchResult} from './types';
 import {CAPTURE_CAPTURING_SYMBOL, CAPTURE_NAME_SYMBOL, CaptureImpl, RAW_CODE_SYMBOL, RawCode} from './capture';
-import {PatternMatchingComparator} from './comparator';
+import {DebugPatternMatchingComparator, MatcherCallbacks, MatcherState, PatternMatchingComparator} from './comparator';
 import {CaptureMarker, CaptureStorageValue, generateCacheKey, globalAstCache, WRAPPERS_MAP_SYMBOL} from './utils';
 import {TemplateEngine} from './engine';
+import {TreePrinters} from '../../print';
+import {JS} from '../index';
 
 
 /**
@@ -119,6 +121,9 @@ export class PatternBuilder {
 export class Pattern {
     private _options: PatternOptions = {};
     private _cachedAstPattern?: J;
+    private static nextPatternId = 1;
+    private readonly patternId: number;
+    private readonly unnamedCaptureMapping = new Map<string, string>();
 
     /**
      * Gets the configuration options for this pattern.
@@ -156,6 +161,19 @@ export class Pattern {
         public readonly templateParts: TemplateStringsArray,
         public readonly captures: (Capture | Any<any> | RawCode)[]
     ) {
+        this.patternId = Pattern.nextPatternId++;
+
+        // Build mapping for unnamed captures (unnamed_N -> _X)
+        let unnamedIndex = 1;
+        for (const cap of captures) {
+            if (cap && typeof cap === 'object' && 'getName' in cap) {
+                const name = (cap as Capture<any> | Any<any>).getName();
+                if (name && name.startsWith('unnamed_')) {
+                    this.unnamedCaptureMapping.set(name, `_${unnamedIndex}`);
+                    unnamedIndex++;
+                }
+            }
+        }
     }
 
     /**
@@ -238,9 +256,41 @@ export class Pattern {
      * @param cursor Optional cursor at the node's position in a larger tree. Used for context-aware
      *               capture constraints to navigate to parent nodes. If omitted, a cursor will be
      *               created at the ast root, allowing constraints to navigate within the matched subtree.
+     * @param options Optional match options (e.g., debug flag)
      * @returns A MatchResult if the pattern matches, undefined otherwise
+     *
+     * @example
+     * ```typescript
+     * // Normal match
+     * const match = await pattern.match(node);
+     *
+     * // Debug this specific call
+     * const match = await pattern.match(node, cursor, { debug: true });
+     * ```
      */
-    async match(ast: J, cursor?: Cursor): Promise<MatchResult | undefined> {
+    async match(ast: J, cursor?: Cursor, options?: MatchOptions): Promise<MatchResult | undefined> {
+        // Three-level precedence: call > pattern > global
+        const debugEnabled =
+            options?.debug !== undefined
+                ? options.debug  // 1. Explicit call-level (true OR false)
+                : (this._options.debug !== undefined
+                    ? this._options.debug  // 2. Explicit pattern-level
+                    : process.env.PATTERN_DEBUG === 'true');  // 3. Global
+
+        if (debugEnabled) {
+            // Use matchWithExplanation and log the result
+            const result = await this.matchWithExplanation(ast, cursor);
+            await this.logMatchResult(ast, cursor, result);
+
+            if (result.matched) {
+                // result.result is the MatchResult class instance
+                return result.result as MatchResult | undefined;
+            } else {
+                return undefined;
+            }
+        }
+
+        // Fast path - no debug
         const matcher = new Matcher(this, ast, cursor);
         const success = await matcher.matches();
         if (!success) {
@@ -250,6 +300,265 @@ export class Pattern {
         const storage = (matcher as any).storage;
         return new MatchResult(new Map(storage));
     }
+
+    /**
+     * Formats and logs the match result to stderr.
+     * @private
+     */
+    private async logMatchResult(ast: J, cursor: Cursor | undefined, result: MatchAttemptResult): Promise<void> {
+        const patternSource = this.getPatternSource();
+        const patternId = `Pattern #${this.patternId}`;
+        const nodeKind = (ast as any).kind || 'unknown';
+        // Format kind: extract short name (e.g., "org.openrewrite.java.tree.J$Binary" -> "J$Binary")
+        const shortKind = typeof nodeKind === 'string'
+            ? nodeKind.split('.').pop() || nodeKind
+            : nodeKind;
+
+        // First, log the pattern source
+        console.error(`[${patternId}] ${patternSource}`);
+
+        // Build the complete match result message
+        const lines: string[] = [];
+
+        // Print the target tree being matched
+        let treeStr: string;
+        try {
+            const printer = TreePrinters.printer(JS.Kind.CompilationUnit);
+            treeStr = await printer.print(ast);
+        } catch (e) {
+            treeStr = '(tree printing unavailable)';
+        }
+
+        if (result.matched) {
+            // Success case - result first, then tree, then captures
+            lines.push(`[${patternId}] ✅ SUCCESS matching against ${shortKind}:`);
+            treeStr.split('\n').forEach(line => lines.push(`[${patternId}]   ${line}`));
+
+            // Log captured values
+            if (result.result) {
+                const storage = (result.result as any).storage as Map<string, CaptureStorageValue>;
+                if (storage && storage.size > 0) {
+                    for (const [name, value] of storage) {
+                        const extractedValue = (result.result as any).extractElements(value);
+                        const valueStr = this.formatCapturedValue(extractedValue);
+                        const displayName = this.unnamedCaptureMapping.get(name) || name;
+                        lines.push(`[${patternId}]    Captured '${displayName}': ${valueStr}`);
+                    }
+                }
+            }
+        } else {
+            // Failure case - result first, then tree, then explanation
+            lines.push(`[${patternId}] ❌ FAILED matching against ${shortKind}:`);
+            treeStr.split('\n').forEach(line => lines.push(`[${patternId}]   ${line}`));
+
+            const explanation = result.explanation;
+            if (explanation) {
+                // Always show path, even if empty, to make it clear where the mismatch occurred
+                const compactedPath = this.compactPath(explanation.path);
+                const pathStr = compactedPath.length > 0 ? compactedPath.join(' → ') : '';
+                lines.push(`[${patternId}]    At path:  [${pathStr}]`);
+                lines.push(`[${patternId}]    Reason:   ${explanation.reason}`);
+                lines.push(`[${patternId}]    Expected: ${explanation.expected}`);
+                lines.push(`[${patternId}]    Actual:   ${explanation.actual}`);
+            }
+        }
+
+        // Single console.error call with all lines joined
+        console.error(lines.join('\n'));
+    }
+
+    /**
+     * Compacts array index navigations into the previous path element.
+     * For example: ['J$VariableDeclarations#variables', '0'] → ['J$VariableDeclarations#variables[0]']
+     * @private
+     */
+    private compactPath(path: string[]): string[] {
+        const compacted: string[] = [];
+        let i = 0;
+
+        while (i < path.length) {
+            const current = path[i];
+
+            // Check if current element is itself a numeric index
+            if (/^\d+$/.test(current)) {
+                // This is a bare numeric index - shouldn't normally happen
+                // If we have a previous element, append to it
+                if (compacted.length > 0) {
+                    compacted[compacted.length - 1] += `[${current}]`;
+                } else {
+                    // No previous element to attach to - this is an error in path construction
+                    // Skip it to avoid bare [0] in output
+                    console.warn(`Warning: Path starts with numeric index '${current}' - skipping`);
+                }
+                i++;
+                continue;
+            }
+
+            // Look ahead to collect consecutive numeric indices
+            let j = i + 1;
+            const indices: string[] = [];
+            while (j < path.length && /^\d+$/.test(path[j])) {
+                indices.push(path[j]);
+                j++;
+            }
+
+            // If we found numeric indices, append them to current element
+            if (indices.length > 0) {
+                compacted.push(current + indices.map(idx => `[${idx}]`).join(''));
+                i = j; // Skip the indices we just processed
+            } else {
+                compacted.push(current);
+                i++;
+            }
+        }
+
+        return compacted;
+    }
+
+    /**
+     * Gets the source code representation of this pattern for logging.
+     * @private
+     */
+    private getPatternSource(): string {
+        // Reconstruct pattern source from template parts
+        let source = '';
+        for (let i = 0; i < this.templateParts.length; i++) {
+            source += this.templateParts[i];
+            if (i < this.captures.length) {
+                const cap = this.captures[i];
+                // Skip raw code
+                if (cap instanceof RawCode || (cap && typeof cap === 'object' && (cap as any)[RAW_CODE_SYMBOL])) {
+                    source += '${raw(...)}';
+                    continue;
+                }
+                // Show capture name or placeholder
+                const name = (cap as any)[CAPTURE_NAME_SYMBOL];
+                if (cap && typeof cap === 'object' && name) {
+                    // Use mapped name for unnamed captures, or original name
+                    const displayName = this.unnamedCaptureMapping.get(name) || name;
+                    source += `\${${displayName}}`;
+                } else {
+                    source += '${...}';
+                }
+            }
+        }
+
+        return source;
+    }
+
+    /**
+     * Formats a captured value for logging.
+     * @private
+     */
+    private formatCapturedValue(value: any): string {
+        if (value === null) return 'null';
+        if (value === undefined) return 'undefined';
+
+        // Check if it's an array (variadic capture)
+        if (Array.isArray(value)) {
+            if (value.length === 0) return '[]';
+            const items = value.slice(0, 3).map(v => this.formatSingleValue(v));
+            const suffix = value.length > 3 ? `, ... (${value.length} total)` : '';
+            return `[${items.join(', ')}${suffix}]`;
+        }
+
+        return this.formatSingleValue(value);
+    }
+
+    /**
+     * Formats a single AST node for logging.
+     * @private
+     */
+    private formatSingleValue(value: any): string {
+        if (!value || typeof value !== 'object') {
+            return String(value);
+        }
+
+        const kind = (value as any).kind;
+        if (!kind) return String(value);
+
+        // Extract simple kind name (last segment)
+        const kindStr = kind.split('.').pop();
+
+        // For literals, show the value
+        if (kindStr === 'Literal' && value.value !== undefined) {
+            const litValue = typeof value.value === 'string'
+                ? `"${value.value}"`
+                : String(value.value);
+            return `${kindStr}(${litValue})`;
+        }
+
+        // For identifiers, show the name
+        if (kindStr === 'Identifier' && value.simpleName) {
+            return `${kindStr}(${value.simpleName})`;
+        }
+
+        // Default: just the kind
+        return kindStr;
+    }
+
+    /**
+     * Matches a pattern against an AST node with detailed debug information.
+     * Part of Layer 2 (Public API).
+     *
+     * This method always enables debug logging and returns detailed information about
+     * the match attempt, including:
+     * - Whether the pattern matched
+     * - Captured nodes (if matched)
+     * - Explanation of failure (if not matched)
+     * - Debug log entries showing the matching process
+     *
+     * @param ast The AST node to match against
+     * @param cursor Optional cursor at the node's position in a larger tree
+     * @param debugOptions Optional debug options (defaults to all logging enabled)
+     * @returns Detailed result with debug information
+     *
+     * @example
+     * const x = capture('x');
+     * const pat = pattern`console.log(${x})`;
+     * const attempt = await pat.matchWithExplanation(node);
+     * if (attempt.matched) {
+     *     console.log('Matched!');
+     *     console.log('Captured x:', attempt.result.get('x'));
+     * } else {
+     *     console.log('Failed:', attempt.explanation);
+     *     console.log('Debug log:', attempt.debugLog);
+     * }
+     */
+    async matchWithExplanation(
+        ast: J,
+        cursor?: Cursor,
+        debugOptions?: DebugOptions
+    ): Promise<MatchAttemptResult> {
+        // Default to full debug logging if not specified
+        const options: DebugOptions = {
+            enabled: true,
+            logComparison: true,
+            logConstraints: true,
+            ...debugOptions
+        };
+
+        const matcher = new Matcher(this, ast, cursor, options);
+        const success = await matcher.matches();
+
+        if (success) {
+            // Match succeeded - return MatchResult with debug info
+            const storage = (matcher as any).storage;
+            const matchResult = new MatchResult(new Map(storage));
+            return {
+                matched: true,
+                result: matchResult,
+                debugLog: matcher.getDebugLog()
+            };
+        } else {
+            // Match failed - return explanation
+            return {
+                matched: false,
+                explanation: matcher.getExplanation(),
+                debugLog: matcher.getDebugLog()
+            };
+        }
+    }
 }
 
 /**
@@ -277,18 +586,16 @@ export class Pattern {
  *     const capturedArgs = match.get(args);  // Returns J[] for variadic captures
  * }
  */
-export class MatchResult {
+export class MatchResult implements IMatchResult {
     constructor(
         private readonly storage: Map<string, CaptureStorageValue> = new Map()
     ) {
     }
 
-    // Overload: get with variadic Capture (array type) returns array
-    get<T>(capture: Capture<T[]>): T[] | undefined;
-    // Overload: get with regular Capture returns single value
+    // Overload: get with Capture returns value
     get<T>(capture: Capture<T>): T | undefined;
-    // Overload: get with string returns J
-    get(capture: string): J | undefined;
+    // Overload: get with string returns value
+    get(capture: string): any;
     // Implementation
     get(capture: Capture<any> | string): J | J[] | undefined {
         // Use symbol to get internal name without triggering Proxy
@@ -353,20 +660,29 @@ class Matcher {
     private readonly storage = new Map<string, CaptureStorageValue>();
     private patternAst?: J;
 
+    // Debug tracking (Layer 1: Core Instrumentation)
+    private readonly debugOptions: DebugOptions;
+    private readonly debugLog: DebugLogEntry[] = [];
+    private explanation?: MatchExplanation;
+    private readonly currentPath: string[] = [];
+
     /**
      * Creates a new matcher for a pattern against an AST node.
      *
      * @param pattern The pattern to match
      * @param ast The AST node to match against
      * @param cursor Optional cursor at the AST node's position
+     * @param debugOptions Optional debug options for instrumentation
      */
     constructor(
         private readonly pattern: Pattern,
         private readonly ast: J,
-        cursor?: Cursor
+        cursor?: Cursor,
+        debugOptions?: DebugOptions
     ) {
         // If no cursor provided, create one at the ast root so constraints can navigate up
         this.cursor = cursor ?? new Cursor(ast, undefined);
+        this.debugOptions = debugOptions ?? {};
     }
 
     private readonly cursor: Cursor;
@@ -422,6 +738,83 @@ class Matcher {
         return value as J;
     }
 
+    /**
+     * Logs a debug message if debugging is enabled.
+     * Part of Layer 1 (Core Instrumentation).
+     *
+     * @param level The severity level
+     * @param scope The scope/category
+     * @param message The message to log
+     * @param data Optional data to include
+     */
+    private log(
+        level: DebugLogEntry['level'],
+        scope: DebugLogEntry['scope'],
+        message: string,
+        data?: any
+    ): void {
+        if (!this.debugOptions.enabled) return;
+
+        // Filter by scope if specific logging is requested
+        if (scope === 'comparison' && !this.debugOptions.logComparison) return;
+        if (scope === 'constraint' && !this.debugOptions.logConstraints) return;
+
+        this.debugLog.push({
+            level,
+            scope,
+            path: [...this.currentPath],
+            message,
+            data
+        });
+    }
+
+    /**
+     * Sets the explanation for why the pattern match failed.
+     * Only sets the first failure (most relevant).
+     * Part of Layer 1 (Core Instrumentation).
+     *
+     * @param reason The reason for failure
+     * @param expected Human-readable description of what was expected
+     * @param actual Human-readable description of what was found
+     * @param details Optional additional context
+     */
+    private setExplanation(
+        reason: MatchExplanation['reason'],
+        expected: string,
+        actual: string,
+        details?: string
+    ): void {
+        // Only set the first failure (most relevant)
+        if (this.explanation) return;
+
+        this.explanation = {
+            reason,
+            path: [...this.currentPath],
+            expected,
+            actual,
+            details
+        };
+    }
+
+    /**
+     * Pushes a path component onto the current path.
+     * Used to track where in the AST tree we are during matching.
+     * Part of Layer 1 (Core Instrumentation).
+     *
+     * @param name The path component to push
+     */
+    private pushPath(name: string): void {
+        this.currentPath.push(name);
+    }
+
+    /**
+     * Pops the last path component from the current path.
+     * Part of Layer 1 (Core Instrumentation).
+     */
+    private popPath(): void {
+        this.currentPath.pop();
+    }
+
     /**
      * Matches a pattern node against a target node.
      *
@@ -436,34 +829,87 @@ class Matcher {
         // - Deep structural comparison
         // This centralizes all matching logic in one place
         const lenientTypeMatching = this.pattern.options.lenientTypeMatching ?? true;
-        const comparator = new PatternMatchingComparator({
-            handleCapture: (capture, t, w) => this.handleCapture(capture, t, w),
-            handleVariadicCapture: (capture, ts, ws) => this.handleVariadicCapture(capture, ts, ws),
+
+        // Factory pattern: instantiate debug or production comparator
+        // Zero cost in production - DebugPatternMatchingComparator is never instantiated
+        const matcherCallbacks: MatcherCallbacks = {
+            handleCapture: (capture: CaptureMarker, t: J, w?: J.RightPadded<J>) => this.handleCapture(capture, t, w),
+            handleVariadicCapture: (capture: CaptureMarker, ts: J[], ws?: J.RightPadded<J>[]) => this.handleVariadicCapture(capture, ts, ws),
             saveState: () => this.saveState(),
-            restoreState: (state) => this.restoreState(state)
-        }, lenientTypeMatching);
+            restoreState: (state) => this.restoreState(state),
+            // Debug callbacks (Layer 1) - grouped together, always present or absent
+            debug: this.debugOptions.enabled ? {
+                log: (level: DebugLogEntry['level'], scope: DebugLogEntry['scope'], message: string, data?: any) => this.log(level, scope, message, data),
+                setExplanation: (reason: MatchExplanation['reason'], expected: string, actual: string, details?: string) => this.setExplanation(reason, expected, actual, details),
+                getExplanation: () => this.explanation,
+                restoreExplanation: (explanation: MatchExplanation) => { this.explanation = explanation; },
+                clearExplanation: () => { this.explanation = undefined; },
+                pushPath: (name: string) => this.pushPath(name),
+                popPath: () => this.popPath()
+            } : undefined
+        };
+
+        const comparator = this.debugOptions.enabled
+            ? new DebugPatternMatchingComparator(matcherCallbacks, lenientTypeMatching)
+            : new PatternMatchingComparator(matcherCallbacks, lenientTypeMatching);
         // Pass cursors to allow constraints to navigate to root
         // Pattern cursor is undefined (pattern is the root), target cursor is provided by user
-        return await comparator.compare(pattern, target, undefined, this.cursor);
+        const result = await comparator.compare(pattern, target, undefined, this.cursor);
+
+        // If match failed and no explanation was set, provide a generic one
+        if (!result && this.debugOptions.enabled && !this.explanation) {
+            const patternKind = (pattern as any).kind?.split('.').pop() || 'unknown';
+            const targetKind = (target as any).kind?.split('.').pop() || 'unknown';
+            this.setExplanation(
+                'structural-mismatch',
+                `Pattern node of type ${patternKind}`,
+                `Target node of type ${targetKind}`,
+                'Nodes did not match structurally'
+            );
+        }
+
+        return result;
     }
 
     /**
-     * Saves the current state of storage for backtracking.
+     * Saves the current state for backtracking.
+     * Includes both capture storage AND debug state (explanation, log, path).
      *
      * @returns A snapshot of the current state
      */
-    private saveState(): Map<string, CaptureStorageValue> {
-        return new Map(this.storage);
+    private saveState(): MatcherState {
+        return {
+            storage: new Map(this.storage),
+            debugState: this.debugOptions.enabled ? {
+                explanation: this.explanation,
+                logLength: this.debugLog.length,
+                path: [...this.currentPath]
+            } : undefined
+        };
     }
 
     /**
      * Restores a previously saved state for backtracking.
+     * Restores both capture storage AND debug state.
      *
      * @param state The state to restore
      */
-    private restoreState(state: Map<string, CaptureStorageValue>): void {
+    private restoreState(state: MatcherState): void {
+        // Restore capture storage
         this.storage.clear();
-        state.forEach((value, key) => this.storage.set(key, value));
+        state.storage.forEach((value, key) => this.storage.set(key, value));
+
+        // Restore debug state if it was saved
+        if (state.debugState) {
+            // Restore explanation to the saved state
+            // This clears any explanations set during failed exploratory attempts (like pivot detection)
+            this.explanation = state.debugState.explanation;
+            // Truncate debug log to saved length (remove entries added during failed attempt)
+            this.debugLog.length = state.debugState.logLength;
+            // Restore path
+            this.currentPath.length = 0;
+            this.currentPath.push(...state.debugState.path);
+        }
     }
 
     /**
@@ -535,6 +981,26 @@ class Matcher {
 
         return true;
     }
+
+    /**
+     * Gets the debug log entries collected during matching.
+     * Part of Layer 2 (Public API).
+     *
+     * @returns The debug log entries, or undefined if debug wasn't enabled
+     */
+    getDebugLog(): DebugLogEntry[] | undefined {
+        return this.debugOptions.enabled ? [...this.debugLog] : undefined;
+    }
+
+    /**
+     * Gets the explanation for why the match failed.
+     * Part of Layer 2 (Public API).
+     *
+     * @returns The match explanation, or undefined if match succeeded or no explanation available
+     */
+    getExplanation(): MatchExplanation | undefined {
+        return this.explanation;
+    }
 }
 
 /**
@@ -558,7 +1024,53 @@ class Matcher {
  * const operator = '===';
  * const pat = pattern`x ${raw(operator)} y`;
  */
-export function pattern(strings: TemplateStringsArray, ...captures: (Capture | Any<any> | RawCode | string)[]): Pattern {
+/**
+ * Creates a pattern from a template literal (direct usage).
+ *
+ * @example
+ * ```typescript
+ * const pat = pattern`console.log(${x})`;
+ * ```
+ */
+export function pattern(strings: TemplateStringsArray, ...captures: (Capture | Any<any> | RawCode | string)[]): Pattern;
+
+/**
+ * Creates a pattern factory with options that returns a tagged template function.
+ *
+ * @example
+ * ```typescript
+ * const pat = pattern({ debug: true })`console.log(${x})`;
+ * ```
+ */
+export function pattern(options: PatternOptions): (strings: TemplateStringsArray, ...captures: (Capture | Any<any> | RawCode | string)[]) => Pattern;
+
+// Implementation
+export function pattern(
+    stringsOrOptions: TemplateStringsArray | PatternOptions,
+    ...captures: (Capture | Any<any> | RawCode | string)[]
+): Pattern | ((strings: TemplateStringsArray, ...captures: (Capture | Any<any> | RawCode | string)[]) => Pattern) {
+    // Check if first arg is TemplateStringsArray (direct usage)
+    if (Array.isArray(stringsOrOptions) && 'raw' in stringsOrOptions) {
+        // Direct usage: pattern`...`
+        return createPattern(stringsOrOptions as TemplateStringsArray, captures, {});
+    }
+
+    // Options usage: pattern({ ... })`...`
+    const options = stringsOrOptions as PatternOptions;
+    return (strings: TemplateStringsArray, ...caps: (Capture | Any<any> | RawCode | string)[]): Pattern => {
+        return createPattern(strings, caps, options);
+    };
+}
+
+/**
+ * Internal helper to create a Pattern instance.
+ * @private
+ */
+function createPattern(
+    strings: TemplateStringsArray,
+    captures: (Capture | Any<any> | RawCode | string)[],
+    options: PatternOptions
+): Pattern {
     const capturesByName = captures.reduce((map, c) => {
         // Skip raw code - it's not a capture
         if (c instanceof RawCode || (typeof c === 'object' && c && (c as any)[RAW_CODE_SYMBOL])) {
@@ -569,7 +1081,8 @@ export function pattern(strings: TemplateStringsArray, ...captures: (Capture | A
         const name = (capture as any)[CAPTURE_NAME_SYMBOL] || capture.getName();
         return map.set(name, capture);
     }, new Map<string, Capture | Any<any>>());
-    return new Pattern(strings, captures.map(c => {
+
+    const pat = new Pattern(strings, captures.map(c => {
         // Return raw code as-is
         if (c instanceof RawCode || (typeof c === 'object' && c && (c as any)[RAW_CODE_SYMBOL])) {
             return c as RawCode;
@@ -578,4 +1091,11 @@ export function pattern(strings: TemplateStringsArray, ...captures: (Capture | A
         const name = typeof c === "string" ? c : ((c as any)[CAPTURE_NAME_SYMBOL] || c.getName());
         return capturesByName.get(name)!;
     }));
+
+    // Apply options if provided
+    if (options && Object.keys(options).length > 0) {
+        pat.configure(options);
+    }
+
+    return pat;
 }