@openrewrite/rewrite 8.66.1 → 8.66.3

package/dist/javascript/templating/pattern.js

@@ -26,13 +26,13 @@ exports.pattern = pattern;
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-const immer_1 = require("immer");
-const java_1 = require("../../java");
-const index_1 = require("../index");
-const uuid_1 = require("../../uuid");
+const __1 = require("../..");
 const capture_1 = require("./capture");
 const comparator_1 = require("./comparator");
 const utils_1 = require("./utils");
+const engine_1 = require("./engine");
+const print_1 = require("../../print");
+const index_1 = require("../index");
 /**
  * Builder for creating patterns programmatically.
  * Use when pattern structure is not known at compile time.
@@ -85,7 +85,7 @@ class PatternBuilder {
     /**
      * Adds a capture to the pattern.
      *
-     * @param value The capture object (Capture or Any) or string name
+     * @param value The capture object (Capture, Any, or RawCode) or string name
      * @returns This builder for chaining
      */
     capture(value) {
@@ -93,7 +93,7 @@ class PatternBuilder {
         if (this.parts.length === 0) {
             this.parts.push('');
         }
-        // Convert string to Capture if needed
+        // Convert string to Capture if needed, or use value as-is for RawCode
         const captureObj = typeof value === 'string' ? new capture_1.CaptureImpl(value) : value;
         this.captures.push(captureObj);
         // Add an empty string for the next part
@@ -154,12 +154,25 @@ class Pattern {
      * 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 (can be Capture or Any)
+     * @param captures The captures between the string parts (can be Capture, Any, or RawCode)
      */
     constructor(templateParts, captures) {
         this.templateParts = templateParts;
         this.captures = captures;
         this._options = {};
+        this.unnamedCaptureMapping = new Map();
+        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.getName();
+                if (name && name.startsWith('unnamed_')) {
+                    this.unnamedCaptureMapping.set(name, `_${unnamedIndex}`);
+                    unnamedIndex++;
+                }
+            }
+        }
     }
     /**
      * Configures this pattern with additional options.
@@ -168,25 +181,98 @@ class Pattern {
      * @returns This pattern for method chaining
      *
      * @example
-     * pattern`isDate(${capture('date')})`
+     * pattern`forwardRef((${props}, ${ref}) => ${body})`
      *     .configure({
-     *         imports: ['import { isDate } from \"util\"'],
-     *         dependencies: { 'util': '^1.0.0' }
+     *         context: ['import { forwardRef } from "react"'],
+     *         dependencies: {'@types/react': '^18.0.0'}
      *     })
      */
     configure(options) {
         this._options = Object.assign(Object.assign({}, this._options), options);
+        // Invalidate cache when configuration changes
+        this._cachedAstPattern = undefined;
         return this;
     }
+    /**
+     * Gets the AST pattern for this pattern, using two-level caching:
+     * 1. Instance-level cache (fastest - this pattern instance)
+     * 2. Global LRU cache (fast - shared across pattern instances with same code)
+     * 3. Compute via TemplateProcessor (slow - parse and process)
+     *
+     * @returns The cached or newly computed pattern AST
+     * @internal
+     */
+    getAstPattern() {
+        return __awaiter(this, void 0, void 0, function* () {
+            // Level 1: Instance cache (fastest path)
+            if (this._cachedAstPattern) {
+                return this._cachedAstPattern;
+            }
+            // Generate cache key for global lookup
+            // Include raw code values in the key since they affect the generated AST
+            const contextStatements = this._options.context || this._options.imports || [];
+            const capturesKey = this.captures.map(c => {
+                if (c instanceof capture_1.RawCode || (c && typeof c === 'object' && c[capture_1.RAW_CODE_SYMBOL])) {
+                    return `raw:${c.code}`;
+                }
+                return c.getName();
+            }).join(',');
+            const cacheKey = (0, utils_1.generateCacheKey)(this.templateParts, capturesKey, contextStatements, this._options.dependencies || {});
+            // Level 2: Global cache (fast path - shared with Template)
+            const cached = utils_1.globalAstCache.get(cacheKey);
+            if (cached) {
+                this._cachedAstPattern = cached;
+                return cached;
+            }
+            // Level 3: Compute via TemplateEngine (slow path)
+            const result = yield engine_1.TemplateEngine.getPatternTree(this.templateParts, this.captures, contextStatements, this._options.dependencies || {});
+            // Cache in both levels
+            utils_1.globalAstCache.set(cacheKey, result);
+            this._cachedAstPattern = result;
+            return result;
+        });
+    }
     /**
      * Creates a matcher for this pattern against a specific AST node.
      *
      * @param ast The AST node to match against
-     * @returns A Matcher object
+     * @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 });
+     * ```
      */
-    match(ast) {
+    match(ast, cursor, options) {
         return __awaiter(this, void 0, void 0, function* () {
-            const matcher = new Matcher(this, ast);
+            // Three-level precedence: call > pattern > global
+            const debugEnabled = (options === null || options === void 0 ? void 0 : 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 = yield this.matchWithExplanation(ast, cursor);
+                yield this.logMatchResult(ast, cursor, result);
+                if (result.matched) {
+                    // result.result is the MatchResult class instance
+                    return result.result;
+                }
+                else {
+                    return undefined;
+                }
+            }
+            // Fast path - no debug
+            const matcher = new Matcher(this, ast, cursor);
             const success = yield matcher.matches();
             if (!success) {
                 return undefined;
@@ -196,8 +282,245 @@ class Pattern {
             return new MatchResult(new Map(storage));
         });
     }
+    /**
+     * Formats and logs the match result to stderr.
+     * @private
+     */
+    logMatchResult(ast, cursor, result) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const patternSource = this.getPatternSource();
+            const patternId = `Pattern #${this.patternId}`;
+            const nodeKind = ast.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 = [];
+            // Print the target tree being matched
+            let treeStr;
+            try {
+                const printer = print_1.TreePrinters.printer(index_1.JS.Kind.CompilationUnit);
+                treeStr = yield 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.storage;
+                    if (storage && storage.size > 0) {
+                        for (const [name, value] of storage) {
+                            const extractedValue = result.result.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
+     */
+    compactPath(path) {
+        const compacted = [];
+        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 = [];
+            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
+     */
+    getPatternSource() {
+        // 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 capture_1.RawCode || (cap && typeof cap === 'object' && cap[capture_1.RAW_CODE_SYMBOL])) {
+                    source += '${raw(...)}';
+                    continue;
+                }
+                // Show capture name or placeholder
+                const name = cap[capture_1.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
+     */
+    formatCapturedValue(value) {
+        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
+     */
+    formatSingleValue(value) {
+        if (!value || typeof value !== 'object') {
+            return String(value);
+        }
+        const kind = value.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);
+     * }
+     */
+    matchWithExplanation(ast, cursor, debugOptions) {
+        return __awaiter(this, void 0, void 0, function* () {
+            // Default to full debug logging if not specified
+            const options = Object.assign({ enabled: true, logComparison: true, logConstraints: true }, debugOptions);
+            const matcher = new Matcher(this, ast, cursor, options);
+            const success = yield matcher.matches();
+            if (success) {
+                // Match succeeded - return MatchResult with debug info
+                const storage = matcher.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()
+                };
+            }
+        });
+    }
 }
 exports.Pattern = Pattern;
+Pattern.nextPatternId = 1;
 /**
  * Result of a successful pattern match containing captured values.
  *
@@ -291,12 +614,19 @@ class Matcher {
      *
      * @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(pattern, ast) {
+    constructor(pattern, ast, cursor, debugOptions) {
         this.pattern = pattern;
         this.ast = ast;
         // Unified storage: holds J for scalar captures, J.RightPadded<J>[] or J[] for variadic captures
         this.storage = new Map();
+        this.debugLog = [];
+        this.currentPath = [];
+        // If no cursor provided, create one at the ast root so constraints can navigate up
+        this.cursor = cursor !== null && cursor !== void 0 ? cursor : new __1.Cursor(ast, undefined);
+        this.debugOptions = debugOptions !== null && debugOptions !== void 0 ? debugOptions : {};
     }
     /**
      * Checks if the pattern matches the AST node.
@@ -306,10 +636,7 @@ class Matcher {
     matches() {
         return __awaiter(this, void 0, void 0, function* () {
             if (!this.patternAst) {
-                // Prefer 'context' over deprecated 'imports'
-                const contextStatements = this.pattern.options.context || this.pattern.options.imports || [];
-                const templateProcessor = new TemplateProcessor(this.pattern.templateParts, this.pattern.captures, contextStatements, this.pattern.options.dependencies || {});
-                this.patternAst = yield templateProcessor.toAstPattern();
+                this.patternAst = yield this.pattern.getAstPattern();
             }
             return this.matchNode(this.patternAst, this.ast);
         });
@@ -350,6 +677,70 @@ class Matcher {
         // Scalar element
         return value;
     }
+    /**
+     * 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
+     */
+    log(level, scope, message, data) {
+        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
+     */
+    setExplanation(reason, expected, actual, details) {
+        // 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
+     */
+    pushPath(name) {
+        this.currentPath.push(name);
+    }
+    /**
+     * Pops the last path component from the current path.
+     * Part of Layer 1 (Core Instrumentation).
+     */
+    popPath() {
+        this.currentPath.pop();
+    }
     /**
      * Matches a pattern node against a target node.
      *
@@ -359,67 +750,105 @@ class Matcher {
      */
     matchNode(pattern, target) {
         return __awaiter(this, void 0, void 0, function* () {
-            var _a;
-            // Check if pattern is a capture placeholder
-            if (utils_1.PlaceholderUtils.isCapture(pattern)) {
-                return this.handleCapture(pattern, target);
-            }
-            // Check if nodes have the same kind
-            if (pattern.kind !== target.kind) {
-                return false;
-            }
-            // Use the pattern matching comparator with configured lenient type matching
-            // Default to true for backward compatibility with existing patterns
+            var _a, _b, _c;
+            // Always delegate to the comparator visitor, which handles:
+            // - Capture detection and constraint evaluation
+            // - Kind checking
+            // - Deep structural comparison
+            // This centralizes all matching logic in one place
             const lenientTypeMatching = (_a = this.pattern.options.lenientTypeMatching) !== null && _a !== void 0 ? _a : true;
-            const comparator = new comparator_1.PatternMatchingComparator({
-                handleCapture: (p, t) => this.handleCapture(p, t),
-                handleVariadicCapture: (p, ts, ws) => this.handleVariadicCapture(p, ts, ws),
+            // Factory pattern: instantiate debug or production comparator
+            // Zero cost in production - DebugPatternMatchingComparator is never instantiated
+            const matcherCallbacks = {
+                handleCapture: (capture, t, w) => this.handleCapture(capture, t, w),
+                handleVariadicCapture: (capture, ts, ws) => this.handleVariadicCapture(capture, ts, ws),
                 saveState: () => this.saveState(),
-                restoreState: (state) => this.restoreState(state)
-            }, lenientTypeMatching);
-            return yield comparator.compare(pattern, target);
+                restoreState: (state) => this.restoreState(state),
+                // Debug callbacks (Layer 1) - grouped together, always present or absent
+                debug: this.debugOptions.enabled ? {
+                    log: (level, scope, message, data) => this.log(level, scope, message, data),
+                    setExplanation: (reason, expected, actual, details) => this.setExplanation(reason, expected, actual, details),
+                    getExplanation: () => this.explanation,
+                    restoreExplanation: (explanation) => { this.explanation = explanation; },
+                    clearExplanation: () => { this.explanation = undefined; },
+                    pushPath: (name) => this.pushPath(name),
+                    popPath: () => this.popPath()
+                } : undefined
+            };
+            const comparator = this.debugOptions.enabled
+                ? new comparator_1.DebugPatternMatchingComparator(matcherCallbacks, lenientTypeMatching)
+                : new comparator_1.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
+            const result = yield 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 = ((_b = pattern.kind) === null || _b === void 0 ? void 0 : _b.split('.').pop()) || 'unknown';
+                const targetKind = ((_c = target.kind) === null || _c === void 0 ? void 0 : _c.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
      */
     saveState() {
-        return new Map(this.storage);
+        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
      */
     restoreState(state) {
+        // 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);
+        }
     }
     /**
      * Handles a capture placeholder.
      *
-     * @param pattern The pattern node
+     * @param capture The pattern node capture
      * @param target The target node
      * @param wrapper Optional wrapper containing the target (for preserving markers)
      * @returns true if the capture is successful, false otherwise
      */
-    handleCapture(pattern, target, wrapper) {
-        var _a, _b;
-        const captureName = utils_1.PlaceholderUtils.getCaptureName(pattern);
+    handleCapture(capture, target, wrapper) {
+        var _a;
+        const captureName = capture.captureName;
         if (!captureName) {
             return false;
         }
-        // Find the original capture object to get constraint and capturing flag
-        const captureObj = this.pattern.captures.find(c => c.getName() === captureName);
-        const constraint = (_a = captureObj === null || captureObj === void 0 ? void 0 : captureObj.getConstraint) === null || _a === void 0 ? void 0 : _a.call(captureObj);
-        // Apply constraint if present
-        if (constraint && !constraint(target)) {
-            return false;
-        }
+        // Find the original capture object to get capturing flag
+        // Note: Constraints are now evaluated in PatternMatchingComparator where cursor is correctly positioned
+        // Filter out RawCode since it doesn't have getName()
+        const captureObj = this.pattern.captures.find(c => !(c instanceof capture_1.RawCode || (c && typeof c === 'object' && c[capture_1.RAW_CODE_SYMBOL])) &&
+            c.getName() === captureName);
         // Only store the binding if this is a capturing placeholder
-        const capturing = (_b = captureObj === null || captureObj === void 0 ? void 0 : captureObj[capture_1.CAPTURE_CAPTURING_SYMBOL]) !== null && _b !== void 0 ? _b : true;
+        const capturing = (_a = captureObj === null || captureObj === void 0 ? void 0 : captureObj[capture_1.CAPTURE_CAPTURING_SYMBOL]) !== null && _a !== void 0 ? _a : true;
         if (capturing) {
             // Store wrapper if available (preserves markers), otherwise store element
             this.storage.set(captureName, wrapper !== null && wrapper !== void 0 ? wrapper : target);
@@ -429,26 +858,24 @@ class Matcher {
     /**
      * Handles a variadic capture placeholder.
      *
-     * @param pattern The pattern node (the variadic capture)
+     * @param capture The pattern node capture (the variadic capture)
      * @param targets The target nodes that were matched
      * @param wrappers Optional wrappers to preserve markers
      * @returns true if the capture is successful, false otherwise
      */
-    handleVariadicCapture(pattern, targets, wrappers) {
-        var _a, _b;
-        const captureName = utils_1.PlaceholderUtils.getCaptureName(pattern);
+    handleVariadicCapture(capture, targets, wrappers) {
+        var _a;
+        const captureName = capture.captureName;
         if (!captureName) {
             return false;
         }
-        // Find the original capture object to get constraint and capturing flag
-        const captureObj = this.pattern.captures.find(c => c.getName() === captureName);
-        const constraint = (_a = captureObj === null || captureObj === void 0 ? void 0 : captureObj.getConstraint) === null || _a === void 0 ? void 0 : _a.call(captureObj);
-        // Apply constraint if present - for variadic captures, constraint receives the array of elements
-        if (constraint && !constraint(targets)) {
-            return false;
-        }
+        // Find the original capture object to get capturing flag
+        // Note: Constraints are now evaluated in PatternMatchingComparator where cursor is correctly positioned
+        // Filter out RawCode since it doesn't have getName()
+        const captureObj = this.pattern.captures.find(c => !(c instanceof capture_1.RawCode || (c && typeof c === 'object' && c[capture_1.RAW_CODE_SYMBOL])) &&
+            c.getName() === captureName);
         // Only store the binding if this is a capturing placeholder
-        const capturing = (_b = captureObj === null || captureObj === void 0 ? void 0 : captureObj[capture_1.CAPTURE_CAPTURING_SYMBOL]) !== null && _b !== void 0 ? _b : true;
+        const capturing = (_a = captureObj === null || captureObj === void 0 ? void 0 : captureObj[capture_1.CAPTURE_CAPTURING_SYMBOL]) !== null && _a !== void 0 ? _a : true;
         if (capturing) {
             // Store the richest representation: wrappers if available, otherwise elements
             if (wrappers && wrappers.length > 0) {
@@ -460,222 +887,66 @@ class Matcher {
         }
         return true;
     }
-}
-/**
- * Processor for template strings.
- * Converts a template string with captures into an AST pattern.
- */
-class TemplateProcessor {
     /**
-     * Creates a new template processor.
+     * Gets the debug log entries collected during matching.
+     * Part of Layer 2 (Public API).
      *
-     * @param templateParts The string parts of the template
-     * @param captures The captures between the string parts (can be Capture or Any)
-     * @param contextStatements Context declarations (imports, types, etc.) to prepend for type attribution
-     * @param dependencies NPM dependencies for type attribution
+     * @returns The debug log entries, or undefined if debug wasn't enabled
      */
-    constructor(templateParts, captures, contextStatements = [], dependencies = {}) {
-        this.templateParts = templateParts;
-        this.captures = captures;
-        this.contextStatements = contextStatements;
-        this.dependencies = dependencies;
+    getDebugLog() {
+        return this.debugOptions.enabled ? [...this.debugLog] : undefined;
     }
     /**
-     * Converts the template to an AST pattern.
+     * Gets the explanation for why the match failed.
+     * Part of Layer 2 (Public API).
      *
-     * @returns A Promise resolving to the AST pattern
+     * @returns The match explanation, or undefined if match succeeded or no explanation available
      */
-    toAstPattern() {
-        return __awaiter(this, void 0, void 0, function* () {
-            // Combine template parts and placeholders
-            const templateString = this.buildTemplateString();
-            // Use cache to get or parse the compilation unit
-            const cu = yield utils_1.templateCache.getOrParse(templateString, this.captures, this.contextStatements, this.dependencies);
-            // Extract the relevant part of the AST
-            return this.extractPatternFromAst(cu);
-        });
+    getExplanation() {
+        return this.explanation;
     }
-    /**
-     * Builds a template string with placeholders for captures.
-     * If the template looks like a block pattern, wraps it in a function.
-     *
-     * @returns The template string
-     */
-    buildTemplateString() {
-        let result = '';
-        for (let i = 0; i < this.templateParts.length; i++) {
-            result += this.templateParts[i];
-            if (i < this.captures.length) {
-                const capture = this.captures[i];
-                // Use symbol to access capture name without triggering Proxy
-                const captureName = capture[capture_1.CAPTURE_NAME_SYMBOL] || capture.getName();
-                result += utils_1.PlaceholderUtils.createCapture(captureName, undefined);
-            }
-        }
-        // Check if this looks like a block pattern (starts with { and contains statement keywords)
-        const trimmed = result.trim();
-        if (trimmed.startsWith('{') && trimmed.endsWith('}')) {
-            // Check for statement keywords that indicate this is a block, not an object literal
-            const hasStatementKeywords = /\b(return|if|for|while|do|switch|try|throw|break|continue|const|let|var|function|class)\b/.test(result);
-            if (hasStatementKeywords) {
-                // Wrap in a function to ensure it parses as a block
-                return `function __PATTERN__() ${result}`;
-            }
-        }
-        return result;
-    }
-    /**
-     * Extracts the pattern from the parsed AST.
-     *
-     * @param cu The compilation unit
-     * @returns The extracted pattern
-     */
-    extractPatternFromAst(cu) {
-        var _a, _b;
-        // Skip context statements to get to the actual pattern code
-        const patternStatementIndex = this.contextStatements.length;
-        // Check if we have any statements at the pattern index
-        if (!cu.statements || patternStatementIndex >= cu.statements.length) {
-            // If there's no statement at the index, but we have exactly one statement
-            // and it's a block, it might be the pattern itself (e.g., pattern`{ ... }`)
-            if (cu.statements && cu.statements.length === 1 && cu.statements[0].element.kind === java_1.J.Kind.Block) {
-                return this.attachCaptureMarkers(cu.statements[0].element);
-            }
-            throw new Error(`No statement found at index ${patternStatementIndex} in compilation unit with ${((_a = cu.statements) === null || _a === void 0 ? void 0 : _a.length) || 0} statements`);
-        }
-        // Extract the relevant part of the AST based on the template content
-        const firstStatement = cu.statements[patternStatementIndex].element;
-        let extracted;
-        // Check if this is our wrapper function for block patterns
-        if (firstStatement.kind === java_1.J.Kind.MethodDeclaration) {
-            const method = firstStatement;
-            if (((_b = method.name) === null || _b === void 0 ? void 0 : _b.simpleName) === '__PATTERN__' && method.body) {
-                // Extract the block from the wrapper function
-                extracted = method.body;
-            }
-            else {
-                extracted = firstStatement;
-            }
-        }
-        else if (firstStatement.kind === index_1.JS.Kind.ExpressionStatement) {
-            // If the first statement is an expression statement, extract the expression
-            extracted = firstStatement.expression;
-        }
-        else {
-            // Otherwise, return the statement itself
-            extracted = firstStatement;
-        }
-        // Attach CaptureMarkers to capture identifiers
-        return this.attachCaptureMarkers(extracted);
-    }
-    /**
-     * Attaches CaptureMarkers to capture identifiers in the AST.
-     * This allows efficient capture detection without string parsing.
-     *
-     * @param ast The AST to process
-     * @returns The AST with CaptureMarkers attached
-     */
-    attachCaptureMarkers(ast) {
-        const visited = new Set();
-        return (0, immer_1.produce)(ast, draft => {
-            this.visitAndAttachMarkers(draft, visited);
-        });
-    }
-    /**
-     * Recursively visits AST nodes and attaches CaptureMarkers to capture identifiers.
-     * For statement-level captures (identifiers in ExpressionStatement), the marker
-     * is attached to the ExpressionStatement itself rather than the nested identifier.
-     *
-     * @param node The node to visit
-     * @param visited Set of already visited nodes to avoid cycles
-     */
-    visitAndAttachMarkers(node, visited) {
-        var _a, _b, _c;
-        if (!node || typeof node !== 'object' || visited.has(node)) {
-            return;
-        }
-        // Mark as visited to avoid cycles
-        visited.add(node);
-        // Check if this is an ExpressionStatement containing a capture identifier
-        // For statement-level captures, we attach the marker to the ExpressionStatement itself
-        if (node.kind === index_1.JS.Kind.ExpressionStatement &&
-            ((_a = node.expression) === null || _a === void 0 ? void 0 : _a.kind) === java_1.J.Kind.Identifier &&
-            ((_b = node.expression.simpleName) === null || _b === void 0 ? void 0 : _b.startsWith(utils_1.PlaceholderUtils.CAPTURE_PREFIX))) {
-            const captureInfo = utils_1.PlaceholderUtils.parseCapture(node.expression.simpleName);
-            if (captureInfo) {
-                // Initialize markers on the ExpressionStatement
-                if (!node.markers) {
-                    node.markers = { kind: 'org.openrewrite.marker.Markers', id: (0, uuid_1.randomId)(), markers: [] };
-                }
-                if (!node.markers.markers) {
-                    node.markers.markers = [];
-                }
-                // Find the original capture object to get variadic options
-                const captureObj = this.captures.find(c => c.getName() === captureInfo.name);
-                const variadicOptions = captureObj === null || captureObj === void 0 ? void 0 : captureObj.getVariadicOptions();
-                // Add CaptureMarker to the ExpressionStatement
-                node.markers.markers.push(new utils_1.CaptureMarker(captureInfo.name, variadicOptions));
-            }
-        }
-        // For non-statement captures (expressions), attach marker to the identifier
-        else if (node.kind === java_1.J.Kind.Identifier && ((_c = node.simpleName) === null || _c === void 0 ? void 0 : _c.startsWith(utils_1.PlaceholderUtils.CAPTURE_PREFIX))) {
-            const captureInfo = utils_1.PlaceholderUtils.parseCapture(node.simpleName);
-            if (captureInfo) {
-                // Initialize markers if needed
-                if (!node.markers) {
-                    node.markers = { kind: 'org.openrewrite.marker.Markers', id: (0, uuid_1.randomId)(), markers: [] };
-                }
-                if (!node.markers.markers) {
-                    node.markers.markers = [];
-                }
-                // Find the original capture object to get variadic options
-                const captureObj = this.captures.find(c => c.getName() === captureInfo.name);
-                const variadicOptions = captureObj === null || captureObj === void 0 ? void 0 : captureObj.getVariadicOptions();
-                // Add CaptureMarker with variadic options if available
-                node.markers.markers.push(new utils_1.CaptureMarker(captureInfo.name, variadicOptions));
-            }
-        }
-        // Recursively visit all properties
-        for (const key in node) {
-            if (node.hasOwnProperty(key)) {
-                const value = node[key];
-                if (Array.isArray(value)) {
-                    value.forEach(item => this.visitAndAttachMarkers(item, visited));
-                }
-                else if (typeof value === 'object' && value !== null) {
-                    this.visitAndAttachMarkers(value, visited);
-                }
-            }
-        }
+}
+// Implementation
+function pattern(stringsOrOptions, ...captures) {
+    // Check if first arg is TemplateStringsArray (direct usage)
+    if (Array.isArray(stringsOrOptions) && 'raw' in stringsOrOptions) {
+        // Direct usage: pattern`...`
+        return createPattern(stringsOrOptions, captures, {});
     }
+    // Options usage: pattern({ ... })`...`
+    const options = stringsOrOptions;
+    return (strings, ...caps) => {
+        return createPattern(strings, caps, options);
+    };
 }
 /**
- * Tagged template function for creating patterns.
- *
- * @param strings The string parts of the template
- * @param captures The captures between the string parts (Capture, Any, or string names)
- * @returns A Pattern object
- *
- * @example
- * // Using the same capture multiple times for repeated patterns
- * const expr = capture('expr');
- * const redundantOr = pattern`${expr} || ${expr}`;
- *
- * @example
- * // Using any() for non-capturing matches
- * const pat = pattern`foo(${any()})`;
+ * Internal helper to create a Pattern instance.
+ * @private
  */
-function pattern(strings, ...captures) {
+function createPattern(strings, captures, options) {
     const capturesByName = captures.reduce((map, c) => {
+        // Skip raw code - it's not a capture
+        if (c instanceof capture_1.RawCode || (typeof c === 'object' && c && c[capture_1.RAW_CODE_SYMBOL])) {
+            return map;
+        }
         const capture = typeof c === "string" ? new capture_1.CaptureImpl(c) : c;
         // Use symbol to get internal name without triggering Proxy
         const name = capture[capture_1.CAPTURE_NAME_SYMBOL] || capture.getName();
         return map.set(name, capture);
     }, new Map());
-    return new Pattern(strings, captures.map(c => {
+    const pat = new Pattern(strings, captures.map(c => {
+        // Return raw code as-is
+        if (c instanceof capture_1.RawCode || (typeof c === 'object' && c && c[capture_1.RAW_CODE_SYMBOL])) {
+            return c;
+        }
         // Use symbol to get internal name without triggering Proxy
         const name = typeof c === "string" ? c : (c[capture_1.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;
 }
 //# sourceMappingURL=pattern.js.map