@openrewrite/rewrite 8.91.1 → 8.91.2

package/src/javascript/scope.ts

@@ -0,0 +1,338 @@
+/*
+ * Copyright 2025 the original author or authors.
+ * <p>
+ * Licensed under the Moderne Source Available License (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * <p>
+ * https://docs.moderne.io/licensing/moderne-source-available-license
+ * <p>
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import {Cursor, isTree} from "../tree";
+import {J} from "../java";
+import {JS} from "./tree";
+// scope.ts sits below the visitor, so this stays type-only.
+import type {JavaScriptVisitor} from "./visitor";
+
+/** The names code at some position can reach unqualified. */
+export interface Scope {
+    /** Whether this scope or one enclosing it binds `name`. */
+    declares(name: string): boolean;
+
+    names(): ReadonlySet<string>;
+}
+
+/**
+ * What the code at `cursor` can name: what every enclosing scope binds, plus the declarations that
+ * hoist into those scopes from blocks that do not enclose it. Where a declaration's shape leaves its
+ * reach unreadable the answer counts it rather than miss it, so a name reported here may not truly
+ * reach the cursor.
+ */
+export function scopeOf(cursor: Cursor): Scope {
+    let resolved: Set<string> | undefined;
+    const names = () => resolved ??= namesInScope(cursor);
+    return {declares: name => names().has(name), names};
+}
+
+/**
+ * Every name the file declares, wherever it sits. A binding the whole file shares is referenced from
+ * sites that are not known when it is named, so it has to steer clear of every name that could
+ * shadow it at one of them.
+ */
+export function namesDeclaredIn(cu: JS.CompilationUnit): ReadonlySet<string> {
+    return namesDeclaredWithin(cu.statements, cu);
+}
+
+/** As {@link namesDeclaredIn}, over one subtree, for a binding shared across only that much of a file. */
+export function namesDeclaredWithin(node: unknown, cacheKey: object = node as object): ReadonlySet<string> {
+    const cached = declared.get(cacheKey);
+    if (cached) {
+        return cached;
+    }
+
+    const names = new Set<string>();
+    const collect = (node: any): boolean => {
+        declarationNames(node).forEach(name => names.add(name));
+        if (node.kind !== J.Kind.ClassDeclaration) {
+            return true;
+        }
+        // A member's name is not one the file binds, though the code inside one still declares names.
+        for (const member of (node as J.ClassDeclaration).body?.statements ?? []) {
+            const element = unwrap(member);
+            walk(element, node => node === element || collect(node));
+        }
+        return false;
+    };
+    walk(node, collect);
+
+    declared.set(cacheKey, names);
+    return names;
+}
+
+/**
+ * Every name a binding pattern introduces. `member` is the property a name takes its value from,
+ * which only a name an object pattern binds directly has: anything deeper reads a property of a
+ * property, an array element is chosen by position, and a rest name gathers what nothing claimed.
+ */
+export function bindingNames(pattern: J | undefined): { name: string; member?: string }[] {
+    switch (pattern?.kind) {
+        case J.Kind.Identifier: {
+            const simpleName = (pattern as J.Identifier).simpleName;
+            return simpleName ? [{name: simpleName}] : [];
+        }
+        case JS.Kind.Spread:
+            return bindingNames((pattern as JS.Spread).expression);
+        case JS.Kind.ArrayBindingPattern:
+            return unnamedMembers((pattern as JS.ArrayBindingPattern).elements.elements
+                .flatMap(element => bindingNames(unwrap(element))));
+        case JS.Kind.ObjectBindingPattern:
+            return (pattern as JS.ObjectBindingPattern).bindings.elements
+                .flatMap(element => bindingNames(unwrap(element)));
+        case JS.Kind.BindingElement: {
+            const element = pattern as JS.BindingElement;
+            if (element.name?.kind !== J.Kind.Identifier) {
+                return unnamedMembers(bindingNames(element.name as J));
+            }
+            const name = (element.name as J.Identifier).simpleName;
+            const propertyName = unwrap(element.propertyName);
+            return [{
+                name,
+                member: propertyName?.kind === J.Kind.Identifier ? (propertyName as J.Identifier).simpleName : name
+            }];
+        }
+        default:
+            return [];
+    }
+}
+
+function unnamedMembers(bound: { name: string }[]): { name: string }[] {
+    return bound.map(({name}) => ({name}));
+}
+
+function namesInScope(cursor: Cursor): Set<string> {
+    const names = new Set<string>();
+    for (let c: Cursor | undefined = cursor; c; c = c.parent) {
+        for (const name of frameBindings(c.value, c.parent?.value)) {
+            names.add(name);
+        }
+    }
+    return names;
+}
+
+/** What one node on the cursor path binds, `parent` being the node it hangs from. */
+function frameBindings(node: any, parent: any): string[] {
+    switch (node?.kind) {
+        case JS.Kind.CompilationUnit: {
+            const statements = (node as JS.CompilationUnit).statements;
+            return [...declaredNames(statements), ...hoistedNames(statements)];
+        }
+        case J.Kind.Block:
+            // A class body holds members, which are reached through an instance rather than by name.
+            return parent?.kind === J.Kind.ClassDeclaration ? [] : declaredNames((node as J.Block).statements);
+        case J.Kind.MethodDeclaration: {
+            const method = node as J.MethodDeclaration;
+            // A function expression is the only function whose own name its body reaches: a
+            // declaration's name belongs to the enclosing block, a method's to an instance.
+            const self = parent?.kind === JS.Kind.StatementExpression ? bindingNames(method.name) : [];
+            return [
+                ...self.map(bound => bound.name),
+                ...declaredNames(method.parameters.elements),
+                ...hoistedNames(method.body)
+            ];
+        }
+        case J.Kind.Lambda: {
+            const lambda = node as J.Lambda;
+            return [...declaredNames(lambda.parameters.parameters), ...hoistedNames(lambda.body)];
+        }
+        case J.Kind.ClassDeclaration:
+            return bindingNames((node as J.ClassDeclaration).name).map(bound => bound.name);
+        case J.Kind.TryCatch:
+            return declaredNames([(node as J.Try.Catch).parameter.tree]);
+        case J.Kind.ForLoop:
+            return declaredNames((node as J.ForLoop).control.init);
+        case J.Kind.ForEachLoop:
+            return declaredNames([(node as J.ForEachLoop).control.variable]);
+        case JS.Kind.ForInLoop:
+            return declaredNames([(node as JS.ForInLoop).control.variable]);
+        default:
+            return [];
+    }
+}
+
+/** The names statements declare directly in the scope holding them. */
+function declaredNames(statements: any[]): string[] {
+    return statements.flatMap(statement => declarationNames(unwrap(statement)));
+}
+
+function declarationNames(statement: any): string[] {
+    switch (statement?.kind) {
+        case JS.Kind.Import:
+            return importNames(statement as JS.Import);
+        case J.Kind.VariableDeclarations:
+            return (statement as J.VariableDeclarations).variables
+                .flatMap(variable => bindingNames(unwrap(variable)?.name))
+                .map(bound => bound.name);
+        case JS.Kind.ScopedVariableDeclarations:
+            return declaredNames((statement as JS.ScopedVariableDeclarations).variables);
+        case J.Kind.MethodDeclaration:
+            return bindingNames((statement as J.MethodDeclaration).name).map(bound => bound.name);
+        case J.Kind.ClassDeclaration:
+            return bindingNames((statement as J.ClassDeclaration).name).map(bound => bound.name);
+        case JS.Kind.NamespaceDeclaration:
+            return bindingNames(unwrap((statement as JS.NamespaceDeclaration).name)).map(bound => bound.name);
+        case JS.Kind.TypeDeclaration:
+            return bindingNames(unwrap((statement as JS.TypeDeclaration).name)).map(bound => bound.name);
+        case J.Kind.Case:
+            // The cases of a switch share the block it opens, so each one's declarations bind in all.
+            return declaredNames((statement as J.Case).statements.elements);
+        default:
+            return [];
+    }
+}
+
+/** The names an import binds, which for an aliased or namespace specifier is the alias. */
+function importNames(jsImport: JS.Import): string[] {
+    const importClause = jsImport.importClause;
+    if (!importClause) {
+        return [];
+    }
+    const names = bindingNames(unwrap(importClause.name)).map(bound => bound.name);
+    const namedBindings = importClause.namedBindings;
+    if (namedBindings?.kind === JS.Kind.NamedImports) {
+        for (const element of (namedBindings as JS.NamedImports).elements.elements) {
+            const specifier = unwrap(element);
+            if (specifier?.kind === JS.Kind.ImportSpecifier) {
+                names.push(...aliasedName((specifier as JS.ImportSpecifier).specifier));
+            }
+        }
+    } else {
+        names.push(...aliasedName(namedBindings));
+    }
+    return names;
+}
+
+function aliasedName(specifier: J | undefined): string[] {
+    const name = specifier?.kind === JS.Kind.Alias ? (specifier as JS.Alias).alias : specifier;
+    return bindingNames(name).map(bound => bound.name);
+}
+
+const blockScoped = new Set(['let', 'const', 'using']);
+
+// A walk of an immutable subtree has one answer, so it runs once. Keyed on the subtree itself, a
+// replaced one is walked afresh: every call site in a function asks what that body hoists, and every
+// import added to a file asks what that file declares.
+const hoisted = new WeakMap<object, string[]>();
+const declared = new WeakMap<object, ReadonlySet<string>>();
+
+/**
+ * The names blocks under `scope` hoist out to it. A `var` or function declaration reaches the whole
+ * function it sits in, so one nested in a block is in scope outside that block; only a `let`, `const`
+ * or `using` keyword says otherwise.
+ */
+function hoistedNames(scope: any): string[] {
+    if (typeof scope !== 'object' || scope === null) {
+        return [];
+    }
+    const cached = hoisted.get(scope);
+    if (cached) {
+        return cached;
+    }
+
+    const names: string[] = [];
+    const collect = (node: any): boolean => {
+        switch (node.kind) {
+            case J.Kind.MethodDeclaration:
+                names.push(...declarationNames(node));
+                return false;
+            case J.Kind.VariableDeclarations:
+            case JS.Kind.ScopedVariableDeclarations:
+                if (!((node.modifiers ?? []) as J.Modifier[]).some(m => blockScoped.has(m.keyword!))) {
+                    names.push(...declarationNames(node));
+                }
+                return false;
+            case J.Kind.TryCatch:
+                // A catch parameter carries no keyword to read, and binds only in the catch block.
+                walk((node as J.Try.Catch).body, collect);
+                return false;
+            case JS.Kind.StatementExpression:
+                // A function or class used as an expression names itself for its own body alone.
+                return false;
+            case J.Kind.Lambda:
+            case J.Kind.ClassDeclaration:
+                return false;
+            default:
+                return true;
+        }
+    };
+    walk(scope, collect);
+    hoisted.set(scope, names);
+    return names;
+}
+
+/** Visits every LST node under `node`, leaving a subtree unvisited where `visit` returns false. */
+export function walk(node: unknown, visit: (node: any) => boolean): void {
+    if (Array.isArray(node)) {
+        node.forEach(child => walk(child, visit));
+        return;
+    }
+    const kind = (node as any)?.kind;
+    if (kind === J.Kind.RightPadded || kind === J.Kind.LeftPadded) {
+        walk((node as J.RightPadded<any>).element, visit);
+    } else if (kind === J.Kind.Container) {
+        walk((node as J.Container<any>).elements, visit);
+    } else if (isTree(node) && visit(node)) {
+        // Markers hang off a node rather than being part of the code it holds.
+        Object.entries(node).forEach(([key, value]) => key !== 'markers' && walk(value, visit));
+    }
+}
+
+/** The element a padding wrapper holds, or the node itself. */
+function unwrap(node: any): any {
+    return node?.kind === J.Kind.RightPadded || node?.kind === J.Kind.LeftPadded ? unwrap(node.element) : node;
+}
+
+/** `cursor` is protected on `TreeVisitor` and these APIs are free functions, so reaching it takes a cast. */
+export function cursorOf(visitor: JavaScriptVisitor<any>): Cursor | undefined {
+    return (visitor as unknown as {cursor?: Cursor}).cursor;
+}
+
+/** The compilation unit a cursor sits in, or the one a visitor is currently positioned in. */
+export function compilationUnitOf(from: Cursor | JavaScriptVisitor<any>): JS.CompilationUnit | undefined {
+    const cursor = from instanceof Cursor ? from : cursorOf(from);
+    return cursor?.firstEnclosing((v): v is JS.CompilationUnit => v?.kind === JS.Kind.CompilationUnit);
+}
+
+/** `preferred`, or the first `preferred_N` that `isTaken` rejects, so a new name never shadows one in scope. */
+export function deconflict(preferred: string, isTaken: (name: string) => boolean): string {
+    if (!isTaken(preferred)) {
+        return preferred;
+    }
+    for (let suffix = 1; ; suffix++) {
+        const candidate = `${preferred}_${suffix}`;
+        if (!isTaken(candidate)) {
+            return candidate;
+        }
+    }
+}
+
+/**
+ * The `J.VariableDeclarations` a statement declares — itself for a bare `const x = …`, one per
+ * declarator for `const a = …, b = …`, which the parser wraps in a `JS.ScopedVariableDeclarations`
+ * instead.
+ */
+export function declarationsOf(statement: J | undefined): J.VariableDeclarations[] {
+    if (statement?.kind === J.Kind.VariableDeclarations) {
+        return [statement as J.VariableDeclarations];
+    }
+    if (statement?.kind === JS.Kind.ScopedVariableDeclarations) {
+        return (statement as JS.ScopedVariableDeclarations).variables
+            .map(v => v.element)
+            .filter((v): v is J.VariableDeclarations => v?.kind === J.Kind.VariableDeclarations);
+    }
+    return [];
+}

package/src/javascript/templating/bindings.ts

@@ -16,36 +16,6 @@
 import {J, Type} from '../../java';
 import {JavaScriptVisitor} from '../visitor';
 import {Cursor} from '../../tree';
-import {ModuleBinding} from './types';
-
-/**
- * Whether the template's dependencies bring a workspace that could resolve `module`.
- */
-export function isResolvable(module: string, dependencies: Record<string, string>): boolean {
-    const segments = module.split('/');
-    const pkg = module.startsWith('@') ? segments.slice(0, 2).join('/') : segments[0];
-    return Object.prototype.hasOwnProperty.call(dependencies, pkg);
-}
-
-/**
- * What a declared binding's name is parsed against, ahead of the template and so out of its output.
- * An import is what carries attribution, and costs a module resolution to get it; a declaration
- * names the binding for a module no workspace could have resolved anyway.
- */
-export function bindingContextStatement(name: string, binding: ModuleBinding, dependencies: Record<string, string>): string {
-    if (!isResolvable(binding.module, dependencies)) {
-        return binding.typeOnly ? `type ${name} = any;` : `declare const ${name}: any;`;
-    }
-    const type = binding.typeOnly ? 'type ' : '';
-    if (binding.member === '*') {
-        return `import ${type}* as ${name} from '${binding.module}';`;
-    }
-    if (binding.member === undefined || binding.member === 'default') {
-        return `import ${type}${name} from '${binding.module}';`;
-    }
-    const specifier = binding.member === name ? name : `${binding.member} as ${name}`;
-    return `import ${type}{${specifier}} from '${binding.module}';`;
-}
 
 /**
  * Renames the identifiers a template uses for its declared bindings to the names the file

package/src/javascript/templating/comparator.ts

@@ -85,6 +85,17 @@ class CaptureMapImpl implements CaptureMap {
     }
 }
 
+/** A capture found in a pattern, and the target node it binds to. */
+interface CaptureAt {
+    marker: CaptureMarker;
+    target: J;
+}
+
+/** Parentheses that `JavaScriptSemanticComparatorVisitor.unwrap()` sees through. */
+function isParenthesized(j: any): boolean {
+    return j?.kind === J.Kind.Parentheses || j?.kind === J.Kind.ControlParentheses;
+}
+
 /**
  * A comparator for pattern matching that is lenient about optional properties.
  * Allows patterns without type annotations to match actual code with type annotations.
@@ -112,33 +123,59 @@ export class PatternMatchingComparator extends JavaScriptSemanticComparatorVisit
         };
     }
 
+    /** The capture this pattern node stands for, paired with the target node it should bind to. */
+    protected captureAt(j: Tree, p: J): CaptureAt | undefined {
+        const marker = PlaceholderUtils.getCaptureMarker(j as J);
+        return marker ? {marker, target: p} : this.captureBehindParentheses(j, p);
+    }
+
+    /** The marker `attachCaptureMarkers` moved onto a parenthesized capture's `J.RightPadded`, which `unwrap()` skips past. */
+    private captureBehindParentheses(j: Tree, p: J): CaptureAt | undefined {
+        let pattern: any = j;
+        let target: any = p;
+        while (isParenthesized(pattern)) {
+            const padded = pattern.tree as J.RightPadded<J> | undefined;
+            if (!padded) {
+                return undefined;
+            }
+            target = isParenthesized(target) ? target.tree.element : target;
+            const marker = PlaceholderUtils.getCaptureMarker(padded);
+            if (marker) {
+                return {marker, target: target as J};
+            }
+            pattern = padded.element;
+        }
+        return undefined;
+    }
+
     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)
         // Note: targetCursor will be pushed by parent's visit() method after this check
-        const captureMarker = PlaceholderUtils.getCaptureMarker(j)!;
-        if (captureMarker) {
+        const capture = this.captureAt(j, p);
+        if (capture) {
+            const {marker: captureMarker, target} = capture;
 
             // Push targetCursor to position it at the captured node for constraint evaluation
             // Only create cursor if targetCursor was initialized (meaning user provided one)
             const savedTargetCursor = this.targetCursor;
             const cursorAtCapturedNode = this.targetCursor !== undefined
-                ? new Cursor(p, this.targetCursor)
-                : new Cursor(p);
+                ? new Cursor(target, this.targetCursor)
+                : new Cursor(target);
             this.targetCursor = cursorAtCapturedNode;
             try {
                 // 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) {
                     const context = this.buildConstraintContext(cursorAtCapturedNode);
-                    if (!captureMarker.constraint(p, context)) {
+                    if (!captureMarker.constraint(target, context)) {
                         const captureName = captureMarker.captureName || 'unnamed';
-                        const targetKind = (p as any).kind || 'unknown';
+                        const targetKind = (target as any).kind || 'unknown';
                         return this.constraintFailed(captureName, targetKind) as R;
                     }
                 }
 
-                const success = this.matcher.handleCapture(captureMarker, p, undefined);
+                const success = this.matcher.handleCapture(captureMarker, target, undefined);
                 if (!success) {
                     const captureName = captureMarker.captureName || 'unnamed';
                     return this.captureConflict(captureName) as R;
@@ -896,26 +933,27 @@ export class DebugPatternMatchingComparator extends PatternMatchingComparator {
     }
 
     override async visit<R extends J>(j: Tree, p: J, parent?: Cursor): Promise<R | undefined> {
-        const captureMarker = PlaceholderUtils.getCaptureMarker(j)!;
-        if (captureMarker) {
+        const capture = this.captureAt(j, p);
+        if (capture) {
+            const {marker: captureMarker, target} = capture;
             const savedTargetCursor = this.targetCursor;
             const cursorAtCapturedNode = this.targetCursor !== undefined
-                ? new Cursor(p, this.targetCursor)
-                : new Cursor(p);
+                ? new Cursor(target, this.targetCursor)
+                : new Cursor(target);
             this.targetCursor = cursorAtCapturedNode;
             try {
                 if (captureMarker.constraint && !captureMarker.variadicOptions) {
                     this.debug.log('debug', 'constraint', `Evaluating constraint for capture: ${captureMarker.captureName}`);
-                    const constraintResult = captureMarker.constraint(p, this.buildConstraintContext(cursorAtCapturedNode));
+                    const constraintResult = captureMarker.constraint(target, 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`);
+                        this.debug.setExplanation('constraint-failed', `Capture ${captureMarker.captureName} with valid constraint`, `Constraint failed for ${(target as any).kind}`, `Constraint evaluation returned false`);
                         return this.abort(j) as R;
                     }
                     this.debug.log('debug', 'constraint', `Constraint passed for capture: ${captureMarker.captureName}`);
                 }
 
-                const success = this.matcher.handleCapture(captureMarker, p, undefined);
+                const success = this.matcher.handleCapture(captureMarker, target, undefined);
                 if (!success) {
                     return this.abort(j) as R;
                 }

package/src/javascript/templating/engine.ts

@@ -28,6 +28,14 @@ import {isExpression, isStatement} from '../parser-utils';
 import {randomId} from '../../uuid';
 import ts from "typescript";
 import {DependencyWorkspace} from "../dependency-workspace";
+import {ModuleScopeBinding, moduleScopeBindings} from '../add-import';
+import {walk} from '../scope';
+import {isIdentifier} from '../../java';
+
+/** A module a template's context binds, and whether the parse resolved it well enough to attribute. */
+export interface ContextBinding extends ModuleScopeBinding {
+    attributed: boolean;
+}
 import {Parameter} from "./types";
 
 /**
@@ -90,11 +98,13 @@ export function setTemplateSourceFileCache(cache?: Map<string, ts.SourceFile>):
 // from one compile to the next; see `JavaScriptParser.parse`.
 const templateParsers: Map<string, JavaScriptParser> = new Map();
 
-function templateParser(workspaceDir?: string): JavaScriptParser {
-    const key = workspaceDir ?? "";
+function templateParser(workspaceDir?: string, types?: string[]): JavaScriptParser {
+    // `types` changes what the compiler loads, so parsers cannot be shared across differing sets.
+    // An empty list loads nothing where absence loads the defaults, so the two encode apart.
+    const key = `${workspaceDir ?? ""}::${JSON.stringify(types ?? null)}`;
     let parser = templateParsers.get(key);
     if (!parser) {
-        parser = new JavaScriptParser({relativeTo: workspaceDir, sourceFileCache: templateSourceFileCache});
+        parser = new JavaScriptParser({relativeTo: workspaceDir, sourceFileCache: templateSourceFileCache, types});
         templateParsers.set(key, parser);
     }
     return parser;
@@ -115,7 +125,8 @@ class TemplateCache {
         templateString: string,
         captures: (Capture | Any)[],
         contextStatements: string[],
-        dependencies: Record<string, string>
+        dependencies: Record<string, string>,
+        types: string[] | undefined
     ): string {
         // Use the actual template string (with placeholders) as the primary key
         const templateKey = templateString;
@@ -129,7 +140,7 @@ class TemplateCache {
         // Dependencies
         const depsKey = JSON.stringify(dependencies || {});
 
-        return `${templateKey}::${capturesKey}::${contextKey}::${depsKey}`;
+        return `${templateKey}::${capturesKey}::${contextKey}::${depsKey}::${JSON.stringify(types ?? null)}`;
     }
 
     /**
@@ -139,9 +150,10 @@ class TemplateCache {
         templateString: string,
         captures: (Capture | Any)[],
         contextStatements: string[],
-        dependencies: Record<string, string>
+        dependencies: Record<string, string>,
+        types?: string[]
     ): Promise<JS.CompilationUnit> {
-        const key = this.generateKey(templateString, captures, contextStatements, dependencies);
+        const key = this.generateKey(templateString, captures, contextStatements, dependencies, types);
 
         let cu = this.cache.get(key);
         if (cu) {
@@ -163,7 +175,7 @@ class TemplateCache {
 
         // Parse and cache (workspace only needed during parsing)
         // Use templateSourceFileCache if configured for ~3.2x speedup on dependency file parsing
-        const parser = templateParser(workspaceDir);
+        const parser = templateParser(workspaceDir, types);
         const parseGenerator = parser.parse({text: fullTemplateString, sourcePath: 'template.tsx'});
         cu = (await parseGenerator.next()).value as JS.CompilationUnit;
 
@@ -208,34 +220,62 @@ export class TemplateEngine {
      * @param dependencies NPM dependencies for type attribution
      * @returns A Promise resolving to the extracted template AST
      */
-    static async getTemplateTree(
+    /** The template parsed with its context, which is what gives its code types to attribute against. */
+    private static async parseWithContext(
         templateParts: TemplateStringsArray,
         parameters: Parameter[],
-        contextStatements: string[] = [],
-        dependencies: Record<string, string> = {}
-    ): Promise<J> {
-        // Generate type preamble for captures/parameters with types
+        contextStatements: string[],
+        dependencies: Record<string, string>,
+        types: string[] | undefined
+    ): Promise<JS.CompilationUnit> {
+        // A capture's declared type reaches the parse as a declaration, so it belongs with context.
         const preamble = TemplateEngine.parameterPreamble(parameters);
-
-        // Build the template string with parameter placeholders
         const templateString = TemplateEngine.buildTemplateString(templateParts, parameters);
-
-        // Add preamble to context statements (so they're skipped during extraction)
         const contextWithPreamble = preamble.length > 0
             ? [...contextStatements, ...preamble]
             : contextStatements;
+        return templateCache.getOrParse(templateString, [], contextWithPreamble, dependencies, types);
+    }
 
-        // Use cache to get or parse the compilation unit
-        const cu = await templateCache.getOrParse(
-            templateString,
-            [],
-            contextWithPreamble,
-            dependencies
-        );
+    /**
+     * The modules the template's context binds, for the caller to bind in the file being edited.
+     * An `import` or `require` states one; anything else — a `declare`, a helper signature — types
+     * the template without asking for a binding.
+     */
+    static async getContextBindings(
+        templateParts: TemplateStringsArray,
+        parameters: Parameter[],
+        contextStatements: string[] = [],
+        dependencies: Record<string, string> = {},
+        types?: string[]
+    ): Promise<ContextBinding[]> {
+        const cu = await TemplateEngine.parseWithContext(templateParts, parameters, contextStatements, dependencies, types);
+        // The template's own code is the last statement, so everything ahead of it is context.
+        const context = {...cu, statements: cu.statements.slice(0, -1)};
+        const attributed = new Set<string>();
+        walk(context.statements, node => {
+            if (isIdentifier(node) && (node.type !== undefined || node.fieldType !== undefined)) {
+                attributed.add(node.simpleName);
+            }
+            return true;
+        });
+        return moduleScopeBindings(context)
+            .filter(b => b.module !== undefined)
+            .map(b => ({...b, attributed: attributed.has(b.name)}));
+    }
+
+    static async getTemplateTree(
+        templateParts: TemplateStringsArray,
+        parameters: Parameter[],
+        contextStatements: string[] = [],
+        dependencies: Record<string, string> = {},
+        types?: string[]
+    ): Promise<J> {
+        const cu = await TemplateEngine.parseWithContext(templateParts, parameters, contextStatements, dependencies, types);
 
         // Check if there are any statements
         if (!cu.statements || cu.statements.length === 0) {
-            throw new Error(`Failed to parse template code (no statements):\n${templateString}`);
+            throw new Error(`Failed to parse template code (no statements):\n${TemplateEngine.buildTemplateString(templateParts, parameters)}`);
         }
 
         // The template code is always the last statement (after context + preamble)
@@ -263,7 +303,7 @@ export class TemplateEngine {
      * @returns A Promise resolving to the generated AST node
      */
     static async applyTemplateFromAst(
-        ast: JS.CompilationUnit,
+        ast: J,
         parameters: Parameter[],
         cursor: Cursor,
         coordinates: JavaCoordinates,
@@ -490,7 +530,8 @@ export class TemplateEngine {
         templateParts: TemplateStringsArray,
         captures: (Capture | Any | RawCode)[],
         contextStatements: string[] = [],
-        dependencies: Record<string, string> = {}
+        dependencies: Record<string, string> = {},
+        types?: string[]
     ): Promise<J> {
         const preamble = TemplateEngine.capturePreamble(captures);
 
@@ -531,7 +572,8 @@ export class TemplateEngine {
             templateString,
             actualCaptures,
             contextWithPreamble,
-            dependencies
+            dependencies,
+            types
         );
 
         // Check if there are any statements