@openrewrite/rewrite 8.67.0-20251119-160338 → 8.67.0-20251120-075051

package/src/javascript/remove-import.ts

@@ -6,16 +6,16 @@ import {ElementRemovalFormatter} from "../java/formatting-utils";
 
 /**
  * @param visitor The visitor to add the import removal to
- * @param target Either the module name (e.g., 'fs') to remove specific members from,
- *               or the name of the import to remove entirely
+ * @param module The module name (e.g., 'fs', 'react') to remove imports from
  * @param member Optionally, the specific member to remove from the import.
- *               If not specified, removes the import matching `target`.
+ *               If not specified, removes all unused imports from the module.
  *               Special values:
- *               - 'default': Removes the default import from the target module if unused,
+ *               - 'default': Removes the default import from the module if unused,
  *                 regardless of its local name (e.g., `import React from 'react'`)
+ *               - '*': Removes the namespace import if unused (e.g., `import * as fs from 'fs'`)
  *
  * @example
- * // Remove a named import if unused
+ * // Remove a specific named import if unused
  * maybeRemoveImport(visitor, 'fs', 'readFile');
  *
  * @example
@@ -23,16 +23,20 @@ import {ElementRemovalFormatter} from "../java/formatting-utils";
  * maybeRemoveImport(visitor, 'react', 'default');
  *
  * @example
- * // Remove an import by name if unused (no module specified)
- * maybeRemoveImport(visitor, 'fs');
+ * // Remove all unused imports from 'react' module
+ * maybeRemoveImport(visitor, 'react');
+ *
+ * @example
+ * // Remove namespace import if unused
+ * maybeRemoveImport(visitor, 'fs', '*');
  */
-export function maybeRemoveImport(visitor: JavaScriptVisitor<any>, target: string, member?: string) {
+export function maybeRemoveImport(visitor: JavaScriptVisitor<any>, module: string, member?: string) {
     for (const v of visitor.afterVisit || []) {
-        if (v instanceof RemoveImport && v.target === target && v.member === member) {
+        if (v instanceof RemoveImport && v.module === module && v.member === member) {
             return;
         }
     }
-    visitor.afterVisit.push(new RemoveImport(target, member));
+    visitor.afterVisit.push(new RemoveImport(module, member));
 }
 
 // Type alias for RightPadded elements to simplify type signatures
@@ -45,15 +49,15 @@ type RightPaddedElement<T extends J> = {
 
 export class RemoveImport<P> extends JavaScriptVisitor<P> {
     /**
-     * @param target Either the module name (e.g., 'fs') to remove specific members from,
-     *               or the name of the import to remove entirely
+     * @param module The module name (e.g., 'fs', 'react') to remove imports from
      * @param member Optionally, the specific member to remove from the import.
-     *               If not specified, removes the import matching `target`.
+     *               If not specified, removes all unused imports from the module.
      *               Special values:
-     *               - 'default': Removes the default import from the target module if unused,
+     *               - 'default': Removes the default import from the module if unused,
      *                 regardless of its local name
+     *               - '*': Removes the namespace import if unused
      */
-    constructor(readonly target: string,
+    constructor(readonly module: string,
                 readonly member?: string) {
         super();
     }
@@ -245,7 +249,7 @@ export class RemoveImport<P> extends JavaScriptVisitor<P> {
                 const name = identifier.simpleName;
 
                 // Check if we should remove this default import
-                let shouldRemove = false;
+                let shouldRemove: boolean;
                 if (this.member === 'default') {
                     // Special case: member 'default' means remove any default import from the target module if unused
                     shouldRemove = !usedIdentifiers.has(name) && !usedTypes.has(name);
@@ -425,22 +429,17 @@ export class RemoveImport<P> extends JavaScriptVisitor<P> {
      * Check if the module name matches the target module
      */
     private matchesTargetModule(moduleName: string): boolean {
-        return this.member === undefined ? moduleName === this.target : moduleName === this.target;
+        return moduleName === this.module;
     }
 
     /**
      * Check if an identifier should be removed based on usage
      */
     private shouldRemoveIdentifier(name: string, usedIdentifiers: Set<string>, usedTypes: Set<string>): boolean {
-        // If member is specified, we're removing a specific member
-        if (this.member !== undefined) {
-            // Only remove if the identifier is not used
-            return !usedIdentifiers.has(name) && !usedTypes.has(name);
-        } else {
-            // We're removing based on the target name
-            // Check if the name matches and is not used
-            return this.target === name && !usedIdentifiers.has(name) && !usedTypes.has(name);
-        }
+        // For CommonJS and import-equals-require, we're removing the entire import
+        // if the identifier is not used (member is typically undefined for these cases,
+        // or we're checking if a specific binding is used)
+        return !usedIdentifiers.has(name) && !usedTypes.has(name);
     }
 
     private async processNamedImports(
@@ -681,40 +680,32 @@ export class RemoveImport<P> extends JavaScriptVisitor<P> {
         usedIdentifiers: Set<string>,
         usedTypes: Set<string>
     ): boolean {
-        // If member is specified, we're removing a specific member from a module
+        // If member is specified, we're removing a specific member from the module
         if (this.member !== undefined) {
             // Only remove if this is the specific member we're looking for
             if (this.member !== name) {
                 return false;
             }
-        } else {
-            // If no member specified, we're removing based on the import name itself
-            if (this.target !== name) {
-                return false;
-            }
         }
+        // If no member specified, we're removing all unused imports from the module
+        // So we check if this particular import is unused
 
         // Check if it's used
         return !(usedIdentifiers.has(name) || usedTypes.has(name));
     }
 
     private isTargetModule(jsImport: JS.Import): boolean {
-        // If member is specified, we're looking for imports from a specific module
-        if (this.member !== undefined) {
-            const moduleSpecifier = jsImport.moduleSpecifier?.element;
-            if (!moduleSpecifier || moduleSpecifier.kind !== J.Kind.Literal) {
-                return false;
-            }
-
-            const literal = moduleSpecifier as J.Literal;
-            const moduleName = literal.value?.toString().replace(/['"`]/g, '');
-
-            // Match the module name
-            return moduleName === this.target;
+        // Always check if the import is from the specified module
+        const moduleSpecifier = jsImport.moduleSpecifier?.element;
+        if (!moduleSpecifier || moduleSpecifier.kind !== J.Kind.Literal) {
+            return false;
         }
 
-        // If no member specified, we process all imports to check their names
-        return true;
+        const literal = moduleSpecifier as J.Literal;
+        const moduleName = literal.value?.toString().replace(/['"`]/g, '');
+
+        // Match the module name
+        return moduleName === this.module;
     }
 
     /**

package/src/javascript/templating/capture.ts

@@ -15,7 +15,7 @@
  */
 import {Cursor} from '../..';
 import {J, Type} from '../../java';
-import {Any, Capture, CaptureOptions, ConstraintFunction, TemplateParam, VariadicOptions} from './types';
+import {Any, Capture, CaptureConstraintContext, CaptureOptions, ConstraintFunction, TemplateParam, VariadicOptions} from './types';
 
 /**
  * Combines multiple constraints with AND logic.
@@ -30,8 +30,8 @@ import {Any, Capture, CaptureOptions, ConstraintFunction, TemplateParam, Variadi
  *     )
  * });
  */
-export function and<T>(...constraints: ((node: T, cursor?: Cursor) => boolean)[]): (node: T, cursor?: Cursor) => boolean {
-    return (node: T, cursor?: Cursor) => constraints.every(c => c(node, cursor));
+export function and<T>(...constraints: ConstraintFunction<T>[]): ConstraintFunction<T> {
+    return (node: T, context: CaptureConstraintContext) => constraints.every(c => c(node, context));
 }
 
 /**
@@ -46,8 +46,8 @@ export function and<T>(...constraints: ((node: T, cursor?: Cursor) => boolean)[]
  *     )
  * });
  */
-export function or<T>(...constraints: ((node: T, cursor?: Cursor) => boolean)[]): (node: T, cursor?: Cursor) => boolean {
-    return (node: T, cursor?: Cursor) => constraints.some(c => c(node, cursor));
+export function or<T>(...constraints: ConstraintFunction<T>[]): ConstraintFunction<T> {
+    return (node: T, context: CaptureConstraintContext) => constraints.some(c => c(node, context));
 }
 
 /**
@@ -59,8 +59,8 @@ export function or<T>(...constraints: ((node: T, cursor?: Cursor) => boolean)[])
  *     constraint: not((node) => typeof node.value === 'string')
  * });
  */
-export function not<T>(constraint: (node: T, cursor?: Cursor) => boolean): (node: T, cursor?: Cursor) => boolean {
-    return (node: T, cursor?: Cursor) => !constraint(node, cursor);
+export function not<T>(constraint: ConstraintFunction<T>): ConstraintFunction<T> {
+    return (node: T, context: CaptureConstraintContext) => !constraint(node, context);
 }
 
 // Symbol to access the internal capture name without triggering Proxy

package/src/javascript/templating/comparator.ts

@@ -18,7 +18,8 @@ import {J} from '../../java';
 import {JS} from '../index';
 import {JavaScriptSemanticComparatorVisitor} from '../comparator';
 import {CaptureMarker, CaptureStorageValue, PlaceholderUtils} from './utils';
-import {DebugLogEntry, MatchExplanation} from './types';
+import {Capture, CaptureConstraintContext, CaptureMap, DebugLogEntry, MatchExplanation} from './types';
+import {CAPTURE_NAME_SYMBOL} from './capture';
 
 /**
  * Debug callbacks for pattern matching.
@@ -62,6 +63,28 @@ export interface MatcherCallbacks {
     debug?: DebugCallbacks;
 }
 
+/**
+ * Implementation of CaptureMap that wraps the capture storage.
+ * Provides read-only access to previously matched captures.
+ */
+class CaptureMapImpl implements CaptureMap {
+    constructor(private readonly storage: Map<string, CaptureStorageValue>) {}
+
+    get<T>(capture: Capture<T>): T | undefined;
+    get(capture: string): any;
+    get(capture: Capture | string): any {
+        // Use symbol to get internal name without triggering Proxy
+        const name = typeof capture === 'string' ? capture : ((capture as any)[CAPTURE_NAME_SYMBOL] || capture.getName());
+        return this.storage.get(name);
+    }
+
+    has(capture: Capture | string): boolean {
+        // Use symbol to get internal name without triggering Proxy
+        const name = typeof capture === 'string' ? capture : ((capture as any)[CAPTURE_NAME_SYMBOL] || capture.getName());
+        return this.storage.has(name);
+    }
+}
+
 /**
  * A comparator for pattern matching that is lenient about optional properties.
  * Allows patterns without type annotations to match actual code with type annotations.
@@ -76,6 +99,19 @@ export class PatternMatchingComparator extends JavaScriptSemanticComparatorVisit
         super(lenientTypeMatching);
     }
 
+    /**
+     * Builds the constraint context with the cursor and current captures.
+     * @param cursor The cursor to include in the context
+     * @returns The constraint context for evaluating capture constraints
+     */
+    protected buildConstraintContext(cursor: Cursor): CaptureConstraintContext {
+        const state = this.matcher.saveState();
+        return {
+            cursor,
+            captures: new CaptureMapImpl(state.storage)
+        };
+    }
+
     override async visit<R extends J>(j: Tree, p: J, parent?: Cursor): Promise<R | undefined> {
         // Check if the pattern node is a capture - this handles unwrapped captures
         // (Wrapped captures in J.RightPadded are handled by visitRightPadded override)
@@ -91,12 +127,15 @@ export class PatternMatchingComparator extends JavaScriptSemanticComparatorVisit
                 : new Cursor(p);
             this.targetCursor = cursorAtCapturedNode;
             try {
-                // Evaluate constraint with cursor at the captured node (always defined)
+                // Evaluate constraint with context (cursor + previous captures)
                 // Skip constraint for variadic captures - they're evaluated in matchSequence with the full array
-                if (captureMarker.constraint && !captureMarker.variadicOptions && !captureMarker.constraint(p, cursorAtCapturedNode)) {
-                    const captureName = captureMarker.captureName || 'unnamed';
-                    const targetKind = (p as any).kind || 'unknown';
-                    return this.constraintFailed(captureName, targetKind) as R;
+                if (captureMarker.constraint && !captureMarker.variadicOptions) {
+                    const context = this.buildConstraintContext(cursorAtCapturedNode);
+                    if (!captureMarker.constraint(p, context)) {
+                        const captureName = captureMarker.captureName || 'unnamed';
+                        const targetKind = (p as any).kind || 'unknown';
+                        return this.constraintFailed(captureName, targetKind) as R;
+                    }
                 }
 
                 const success = this.matcher.handleCapture(captureMarker, p, undefined);
@@ -164,7 +203,7 @@ export class PatternMatchingComparator extends JavaScriptSemanticComparatorVisit
             try {
                 // Evaluate constraint with cursor at the captured node (always defined)
                 // Skip constraint for variadic captures - they're evaluated in matchSequence with the full array
-                if (captureMarker.constraint && !captureMarker.variadicOptions && !captureMarker.constraint(targetElement as J, cursorAtCapturedNode)) {
+                if (captureMarker.constraint && !captureMarker.variadicOptions && !captureMarker.constraint(targetElement as J, this.buildConstraintContext(cursorAtCapturedNode))) {
                     const captureName = captureMarker.captureName || 'unnamed';
                     const targetKind = (targetElement as any).kind || 'unknown';
                     return this.constraintFailed(captureName, targetKind);
@@ -604,7 +643,7 @@ export class PatternMatchingComparator extends JavaScriptSemanticComparatorVisit
                 // The targetCursor points to the parent container (always defined in container matching)
                 if (captureMarker.constraint) {
                     const cursor = this.targetCursor || new Cursor(targetElements[0]);
-                    if (!captureMarker.constraint(capturedElements as any, cursor)) {
+                    if (!captureMarker.constraint(capturedElements as any, this.buildConstraintContext(cursor))) {
                         continue; // Try next consumption amount
                     }
                 }
@@ -868,7 +907,7 @@ export class DebugPatternMatchingComparator extends PatternMatchingComparator {
             try {
                 if (captureMarker.constraint && !captureMarker.variadicOptions) {
                     this.debug.log('debug', 'constraint', `Evaluating constraint for capture: ${captureMarker.captureName}`);
-                    const constraintResult = captureMarker.constraint(p, cursorAtCapturedNode);
+                    const constraintResult = captureMarker.constraint(p, this.buildConstraintContext(cursorAtCapturedNode));
                     if (!constraintResult) {
                         this.debug.log('info', 'constraint', `Constraint failed for capture: ${captureMarker.captureName}`);
                         this.debug.setExplanation('constraint-failed', `Capture ${captureMarker.captureName} with valid constraint`, `Constraint failed for ${(p as any).kind}`, `Constraint evaluation returned false`);
@@ -965,7 +1004,7 @@ export class DebugPatternMatchingComparator extends PatternMatchingComparator {
             try {
                 if (captureMarker.constraint && !captureMarker.variadicOptions) {
                     this.debug.log('debug', 'constraint', `Evaluating constraint for wrapped capture: ${captureMarker.captureName}`);
-                    const constraintResult = captureMarker.constraint(targetElement as J, cursorAtCapturedNode);
+                    const constraintResult = captureMarker.constraint(targetElement as J, this.buildConstraintContext(cursorAtCapturedNode));
                     if (!constraintResult) {
                         this.debug.log('info', 'constraint', `Constraint failed for wrapped capture: ${captureMarker.captureName}`);
                         this.debug.setExplanation('constraint-failed', `Capture ${captureMarker.captureName} with valid constraint`, `Constraint failed for ${(targetElement as any).kind}`, `Constraint evaluation returned false`);
@@ -1316,7 +1355,7 @@ export class DebugPatternMatchingComparator extends PatternMatchingComparator {
                 if (captureMarker.constraint) {
                     this.debug.log('debug', 'constraint', `Evaluating variadic constraint for capture: ${captureMarker.captureName} (${capturedElements.length} elements)`);
                     const cursor = this.targetCursor || new Cursor(targetElements[0]);
-                    const constraintResult = captureMarker.constraint(capturedElements as any, cursor);
+                    const constraintResult = captureMarker.constraint(capturedElements as any, this.buildConstraintContext(cursor));
                     if (!constraintResult) {
                         this.debug.log('info', 'constraint', `Variadic constraint failed for capture: ${captureMarker.captureName}`);
                         continue;

package/src/javascript/templating/pattern.ts

@@ -15,7 +15,17 @@
  */
 import {Cursor} from '../..';
 import {J} from '../../java';
-import {Any, Capture, DebugLogEntry, DebugOptions, MatchAttemptResult, MatchExplanation, MatchOptions, PatternOptions, MatchResult as IMatchResult} from './types';
+import {
+    Any,
+    Capture,
+    DebugLogEntry,
+    DebugOptions,
+    MatchAttemptResult,
+    MatchExplanation,
+    MatchOptions,
+    MatchResult as IMatchResult,
+    PatternOptions
+} from './types';
 import {CAPTURE_CAPTURING_SYMBOL, CAPTURE_NAME_SYMBOL, CaptureImpl, RAW_CODE_SYMBOL, RawCode} from './capture';
 import {DebugPatternMatchingComparator, MatcherCallbacks, MatcherState, PatternMatchingComparator} from './comparator';
 import {CaptureMarker, CaptureStorageValue, generateCacheKey, globalAstCache, WRAPPERS_MAP_SYMBOL} from './utils';
@@ -190,7 +200,7 @@ export class Pattern {
      *     })
      */
     configure(options: PatternOptions): Pattern {
-        this._options = {...this._options, ...options};
+        this._options = { ...this._options, ...options };
         // Invalidate cache when configuration changes
         this._cachedAstPattern = undefined;
         return this;
@@ -252,23 +262,22 @@ export class Pattern {
     /**
      * Creates a matcher for this pattern against a specific AST node.
      *
-     * @param ast The AST node to match against
-     * @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 tree The AST node to match against
+     * @param cursor Cursor at the node's position in a larger tree. Used for context-aware
+     *               capture constraints to navigate to parent nodes.
      * @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);
+     * const match = await pattern.match(node, cursor);
      *
      * // Debug this specific call
      * const match = await pattern.match(node, cursor, { debug: true });
      * ```
      */
-    async match(ast: J, cursor?: Cursor, options?: MatchOptions): Promise<MatchResult | undefined> {
+    async match(tree: J, cursor: Cursor, options?: MatchOptions): Promise<MatchResult | undefined> {
         // Three-level precedence: call > pattern > global
         const debugEnabled =
             options?.debug !== undefined
@@ -279,8 +288,8 @@ export class Pattern {
 
         if (debugEnabled) {
             // Use matchWithExplanation and log the result
-            const result = await this.matchWithExplanation(ast, cursor);
-            await this.logMatchResult(ast, cursor, result);
+            const result = await this.matchWithExplanation(tree, cursor);
+            await this.logMatchResult(tree, cursor, result);
 
             if (result.matched) {
                 // result.result is the MatchResult class instance
@@ -291,7 +300,7 @@ export class Pattern {
         }
 
         // Fast path - no debug
-        const matcher = new Matcher(this, ast, cursor);
+        const matcher = new Matcher(this, tree, cursor);
         const success = await matcher.matches();
         if (!success) {
             return undefined;
@@ -305,10 +314,10 @@ export class Pattern {
      * Formats and logs the match result to stderr.
      * @private
      */
-    private async logMatchResult(ast: J, cursor: Cursor | undefined, result: MatchAttemptResult): Promise<void> {
+    private async logMatchResult(tree: J, cursor: Cursor | undefined, result: MatchAttemptResult): Promise<void> {
         const patternSource = this.getPatternSource();
         const patternId = `Pattern #${this.patternId}`;
-        const nodeKind = (ast as any).kind || 'unknown';
+        const nodeKind = (tree 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
@@ -324,7 +333,7 @@ export class Pattern {
         let treeStr: string;
         try {
             const printer = TreePrinters.printer(JS.Kind.CompilationUnit);
-            treeStr = await printer.print(ast);
+            treeStr = await printer.print(tree);
         } catch (e) {
             treeStr = '(tree printing unavailable)';
         }
@@ -508,15 +517,15 @@ export class Pattern {
      * - 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 tree The AST node to match against
+     * @param cursor 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);
+     * const attempt = await pat.matchWithExplanation(node, cursor);
      * if (attempt.matched) {
      *     console.log('Matched!');
      *     console.log('Captured x:', attempt.result.get('x'));
@@ -526,8 +535,8 @@ export class Pattern {
      * }
      */
     async matchWithExplanation(
-        ast: J,
-        cursor?: Cursor,
+        tree: J,
+        cursor: Cursor,
         debugOptions?: DebugOptions
     ): Promise<MatchAttemptResult> {
         // Default to full debug logging if not specified
@@ -538,7 +547,7 @@ export class Pattern {
             ...debugOptions
         };
 
-        const matcher = new Matcher(this, ast, cursor, options);
+        const matcher = new Matcher(this, tree, cursor, options);
         const success = await matcher.matches();
 
         if (success) {
@@ -671,17 +680,16 @@ 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 cursor 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.cursor = cursor;
         this.debugOptions = debugOptions ?? {};
     }
 

package/src/javascript/templating/rewrite.ts

@@ -57,10 +57,10 @@ class RewriteRuleImpl implements RewriteRule {
                 if (typeof this.after === 'function') {
                     // Call the function to get a template, then apply it
                     const template = this.after(match);
-                    result = await template.apply(cursor, node, match);
+                    result = await template.apply(node, cursor, { values: match });
                 } else {
                     // Use template.apply() as before
-                    result = await this.after.apply(cursor, node, match);
+                    result = await this.after.apply(node, cursor, { values: match });
                 }
 
                 if (result) {

package/src/javascript/templating/template.ts

@@ -15,7 +15,7 @@
  */
 import {Cursor, Tree} from '../..';
 import {J} from '../../java';
-import {Capture, Parameter, TemplateOptions, TemplateParameter} from './types';
+import {ApplyOptions, Parameter, TemplateOptions, TemplateParameter} from './types';
 import {MatchResult} from './pattern';
 import {generateCacheKey, globalAstCache, WRAPPERS_MAP_SYMBOL} from './utils';
 import {CAPTURE_NAME_SYMBOL, RAW_CODE_SYMBOL} from './capture';
@@ -174,6 +174,18 @@ export class Template {
     private options: TemplateOptions = {};
     private _cachedTemplate?: J;
 
+    /**
+     * Creates a new template.
+     *
+     * @param templateParts The string parts of the template
+     * @param parameters The parameters between the string parts
+     */
+    constructor(
+        private readonly templateParts: TemplateStringsArray,
+        private readonly parameters: Parameter[]
+    ) {
+    }
+
     /**
      * Creates a new builder for constructing templates programmatically.
      *
@@ -191,18 +203,6 @@ export class Template {
         return new TemplateBuilder();
     }
 
-    /**
-     * Creates a new template.
-     *
-     * @param templateParts The string parts of the template
-     * @param parameters The parameters between the string parts
-     */
-    constructor(
-        private readonly templateParts: TemplateStringsArray,
-        private readonly parameters: Parameter[]
-    ) {
-    }
-
     /**
      * Configures this template with additional options.
      *
@@ -217,7 +217,7 @@ export class Template {
      *     })
      */
     configure(options: TemplateOptions): Template {
-        this.options = { ...this.options, ...options };
+        this.options = {...this.options, ...options};
         // Invalidate cache when configuration changes
         this._cachedTemplate = undefined;
         return this;
@@ -236,7 +236,7 @@ export class Template {
      * @returns The cached or newly computed template tree
      * @internal
      */
-    async getTemplateTree(): Promise<JS.CompilationUnit> {
+    private async getTemplateTree(): Promise<JS.CompilationUnit> {
         // Level 1: Instance cache (fastest path)
         if (this._cachedTemplate) {
             return this._cachedTemplate as JS.CompilationUnit;
@@ -286,12 +286,30 @@ export class Template {
     /**
      * Applies this template and returns the resulting tree.
      *
+     * @param tree Input tree to transform
      * @param cursor The cursor pointing to the current location in the AST
-     * @param tree Input tree
-     * @param values values for parameters in template
+     * @param options Optional configuration including values for parameters
      * @returns A Promise resolving to the generated AST node
+     *
+     * @example
+     * ```typescript
+     * // Simple application without values
+     * const result = await tmpl.apply(node, cursor);
+     *
+     * // With values from pattern match
+     * const match = await pat.match(node, cursor);
+     * const result = await tmpl.apply(node, cursor, { values: match });
+     *
+     * // With explicit values
+     * const result = await tmpl.apply(node, cursor, {
+     *     values: { x: someNode, y: anotherNode }
+     * });
+     * ```
      */
-    async apply(cursor: Cursor, tree: J, values?: Map<Capture | string, J> | Pick<Map<string, J>, 'get'> | Record<string, J>): Promise<J | undefined> {
+    async apply(tree: J, cursor: Cursor, options?: ApplyOptions): Promise<J | undefined> {
+        // Extract values from options
+        const values = options?.values;
+
         // 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();