@openrewrite/rewrite 8.66.1 → 8.66.3

package/src/javascript/templating/template.ts

@@ -15,11 +15,12 @@
  */
 import {Cursor, Tree} from '../..';
 import {J} from '../../java';
-import {TemplateOptions, TemplateParameter, Capture} from './types';
+import {Capture, Parameter, TemplateOptions, TemplateParameter} from './types';
 import {MatchResult} from './pattern';
-import {WRAPPERS_MAP_SYMBOL} from './utils';
-import {CAPTURE_NAME_SYMBOL} from './capture';
-import {TemplateEngine, Parameter} from './engine';
+import {generateCacheKey, globalAstCache, WRAPPERS_MAP_SYMBOL} from './utils';
+import {CAPTURE_NAME_SYMBOL, RAW_CODE_SYMBOL} from './capture';
+import {TemplateEngine} from './engine';
+import {JS} from '..';
 
 /**
  * Coordinates for template application.
@@ -171,6 +172,7 @@ export class TemplateBuilder {
  */
 export class Template {
     private options: TemplateOptions = {};
+    private _cachedTemplate?: J;
 
     /**
      * Creates a new builder for constructing templates programmatically.
@@ -210,15 +212,77 @@ export class Template {
      * @example
      * template`isDate(${capture('date')})`
      *     .configure({
-     *         imports: ['import { isDate } from "util"'],
+     *         context: ['import { isDate } from "util"'],
      *         dependencies: { 'util': '^1.0.0' }
      *     })
      */
     configure(options: TemplateOptions): Template {
         this.options = { ...this.options, ...options };
+        // Invalidate cache when configuration changes
+        this._cachedTemplate = undefined;
         return this;
     }
 
+    /**
+     * Gets the template tree for this template, using two-level caching:
+     * - Level 1: Instance cache (this._cachedTemplate) - fastest, no lookup needed
+     * - Level 2: Global cache (globalAstCache) - fast, shared across all templates
+     * - Level 3: TemplateEngine - slow, parses and processes the template
+     *
+     * Most parameters use placeholders that are replaced during application, so templates
+     * with the same structure share cached ASTs. However, raw() parameters are spliced at
+     * construction time, so their values must be included in the cache key.
+     *
+     * @returns The cached or newly computed template tree
+     * @internal
+     */
+    async getTemplateTree(): Promise<JS.CompilationUnit> {
+        // Level 1: Instance cache (fastest path)
+        if (this._cachedTemplate) {
+            return this._cachedTemplate as JS.CompilationUnit;
+        }
+
+        // Generate cache key for global lookup
+        // For raw() parameters, we need to include their code values in the key
+        // since they're spliced at construction time, not application time
+        const contextStatements = this.options.context || this.options.imports || [];
+        const parametersKey = this.parameters.map((p, i) => {
+            const value = p.value;
+            // Include raw code values in the cache key using the symbol
+            if (value && typeof value === 'object' && value[RAW_CODE_SYMBOL]) {
+                return `raw:${value.code}`;
+            }
+            return i.toString();
+        }).join(',');
+        const cacheKey = generateCacheKey(
+            this.templateParts,
+            parametersKey,
+            contextStatements,
+            this.options.dependencies || {}
+        );
+
+        // Level 2: Global cache (fast path - shared with Pattern)
+        const cached = globalAstCache.get(cacheKey);
+        if (cached) {
+            this._cachedTemplate = cached as JS.CompilationUnit;
+            return cached as JS.CompilationUnit;
+        }
+
+        // Level 3: Compute via TemplateEngine (slow path)
+        const result = await TemplateEngine.getTemplateTree(
+            this.templateParts,
+            this.parameters,
+            contextStatements,
+            this.options.dependencies || {}
+        ) as JS.CompilationUnit;
+
+        // Cache in both levels
+        globalAstCache.set(cacheKey, result);
+        this._cachedTemplate = result;
+
+        return result;
+    }
+
     /**
      * Applies this template and returns the resulting tree.
      *
@@ -227,12 +291,16 @@ export class Template {
      * @param values values for parameters in template
      * @returns A Promise resolving to the generated AST node
      */
-    async apply(cursor: Cursor, tree: J, values?: Map<Capture | string, J> | Pick<Map<string, J>, 'get'>): Promise<J | undefined> {
+    async apply(cursor: Cursor, tree: J, values?: Map<Capture | string, J> | Pick<Map<string, J>, 'get'> | Record<string, J>): Promise<J | undefined> {
         // Normalize the values map: convert any Capture keys to string keys
         let normalizedValues: Pick<Map<string, J>, 'get'> | undefined;
         let wrappersMap: Map<string, J.RightPadded<J> | J.RightPadded<J>[]> = new Map();
 
-        if (values instanceof Map) {
+        if (values instanceof MatchResult) {
+            // MatchResult - extract both bindings and wrappersMap
+            normalizedValues = values;
+            wrappersMap = (values as any)[WRAPPERS_MAP_SYMBOL]();
+        } else if (values instanceof Map) {
             const normalized = new Map<string, J>();
             for (const [key, value] of values.entries()) {
                 const stringKey = typeof key === 'string'
@@ -241,19 +309,30 @@ export class Template {
                 normalized.set(stringKey, value);
             }
             normalizedValues = normalized;
-        } else if (values instanceof MatchResult) {
-            // MatchResult - extract both bindings and wrappersMap
-            normalizedValues = values;
-            wrappersMap = (values as any)[WRAPPERS_MAP_SYMBOL]();
-        } else {
-            // Other Pick<Map> implementation
-            normalizedValues = values;
+        } else if (values && typeof values === 'object') {
+            // Check if it's a Map-like object with 'get' method, or a plain object literal
+            if ('get' in values && typeof values.get === 'function') {
+                // Map-like object with get method
+                normalizedValues = values as Pick<Map<string, J>, 'get'>;
+            } else {
+                // Plain object literal - convert to Map
+                // Keys may be strings or Capture objects (via computed properties {[x]: value})
+                const normalized = new Map<string, J>();
+                for (const [key, value] of Object.entries(values)) {
+                    // If the key happens to be a stringified Capture (from computed properties),
+                    // it's already been converted to a string by JavaScript
+                    normalized.set(key, value);
+                }
+                normalizedValues = normalized;
+            }
         }
 
-        // Prefer 'context' over deprecated 'imports'
-        const contextStatements = this.options.context || this.options.imports || [];
-        return TemplateEngine.applyTemplate(
-            this.templateParts,
+        // Use instance-level cache to get the template tree
+        const ast = await this.getTemplateTree();
+
+        // Delegate to TemplateEngine for placeholder substitution and application
+        return TemplateEngine.applyTemplateFromAst(
+            ast,
             this.parameters,
             cursor,
             {
@@ -261,9 +340,7 @@ export class Template {
                 mode: JavaCoordinates.Mode.Replace
             },
             normalizedValues,
-            wrappersMap,
-            contextStatements,
-            this.options.dependencies || {}
+            wrappersMap
         );
     }
 }
@@ -276,8 +353,13 @@ export class Template {
  * to navigate properties (e.g., `method.name`) or array bracket notation to
  * access array elements (e.g., `args.elements[0].element`).
  *
+ * Templates can also accept AST wrapper types directly:
+ * - J.RightPadded<T>: The element will be extracted and inserted
+ * - J.RightPadded<T>[]: Elements will be expanded in place
+ * - J.Container<T>: Elements will be expanded in place
+ *
  * @param strings The string parts of the template
- * @param parameters The parameters between the string parts (Capture, Tree, or primitives)
+ * @param parameters The parameters between the string parts (Capture, CaptureValue, TemplateParam, Tree, Tree[], J.RightPadded, J.RightPadded[], or J.Container)
  * @returns A Template object that can be applied to generate AST nodes
  *
  * @example
@@ -312,6 +394,12 @@ export class Template {
  * // Array element access
  * const invocation = capture<J.MethodInvocation>('invocation');
  * template`bar(${invocation.arguments.elements[0].element})`
+ *
+ * @example
+ * // Using J.RightPadded and J.Container directly
+ * const selectExpr = method.select;  // J.RightPadded<Expression>
+ * const args = method.arguments;      // J.Container<Expression>
+ * template`${selectExpr}.newMethod(${args})`
  */
 export function template(strings: TemplateStringsArray, ...parameters: TemplateParameter[]): Template {
     // Convert parameters to Parameter objects (no longer need to check for mutable tree property)

package/src/javascript/templating/types.ts

@@ -14,7 +14,10 @@
  * limitations under the License.
  */
 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.
@@ -31,6 +34,19 @@ 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.
  *
@@ -38,11 +54,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;
 }
 
 /**
@@ -58,14 +116,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)
  * ```
  */
@@ -89,8 +147,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;
 }
 
 /**
@@ -125,8 +184,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
@@ -156,7 +216,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;
 }
 
 /**
@@ -224,17 +284,83 @@ 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 | 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 type TemplateParameter = Capture | any | TemplateParam | Tree | Tree[] | string | number | boolean;
+export interface Parameter {
+    /**
+     * The value to substitute into the template.
+     */
+    value: any;
+}
 
 /**
  * Configuration options for templates.
@@ -289,12 +415,260 @@ 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; // Pattern | Pattern[], but we'll import Pattern in rewrite.ts
-    after: any;  // Template, but we'll import Template in rewrite.ts
+    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[];
 }