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

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

@@ -1,6 +1,6 @@
 import { Cursor, Tree } from '../..';
 import { J, Type } from '../../java';
-import type { MatchResult, Pattern } from "./pattern";
+import type { Pattern } from "./pattern";
 import type { Template } from "./template";
 import type { CaptureValue, RawCode } from "./capture";
 /**
@@ -251,6 +251,47 @@ 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.
@@ -451,4 +492,119 @@ export interface RewriteConfig {
      */
     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":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/javascript/templating/types.ts"],"names":[],"mappings":"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"}

package/dist/version.txt

@@ -1 +1 @@
-8.67.0-20251112-160335
+8.67.0-20251113-160321

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openrewrite/rewrite",
-  "version": "8.67.0-20251112-160335",
+  "version": "8.67.0-20251113-160321",
   "license": "Moderne Source Available License",
   "description": "OpenRewrite JavaScript.",
   "homepage": "https://github.com/openrewrite/rewrite",