lua-cli 3.12.1 → 3.13.0

package/dist/compiler/utils/reference-resolver.js

@@ -0,0 +1,1030 @@
+/**
+ * Primitive Reference Resolver
+ *
+ * Statically resolves a TypeScript expression that is expected to yield an
+ * array of primitive instances (e.g. `mcpServers: [luaDocsMcpServer, ...more]`)
+ * into a list of named references (`ResolvedRef[]`), without executing user
+ * code.
+ *
+ * ## Supported expression shapes
+ *
+ * - Inline:         `[new LuaMCPServer({...}), foo]`
+ * - Variable ref:   `const servers = [...]; mcpServers: servers`
+ * - Spread:         `[...base, new LuaMCPServer({...})]`
+ * - Cross-file:     `import servers from './servers'; mcpServers: servers`
+ * - Re-export:      `export { servers } from './impl'`
+ * - Barrel chains:  `export * from './servers'` + same-name imports
+ * - Path aliases:   `@shared/tools`, `~/lib/tools`, etc. (via tsconfig paths)
+ * - Property read:  `const all = { mcp: [...] }; mcpServers: all.mcp`
+ * - Identifier chains: `const a = inner; const b = a; mcpServers: b`
+ *
+ * ## Result shape (Babel's `path.evaluate()` convention)
+ *
+ *     { confident: true; value: ResolvedRef[] }
+ *   | { confident: false; value: ResolvedRef[]; deopt: Node; reason: string;
+ *       ruleId: 'lua/unresolved-primitive-ref' }
+ *
+ * The `deopt` field pinpoints the AST node that defeated resolution so the
+ * compiler can emit an actionable `file:line:col` diagnostic. Partial results
+ * (`value`) are returned even on deopt so the compiler can emit whatever was
+ * resolvable up to the unknown shape.
+ *
+ * ## Resolution strategy
+ *
+ * 1. **AST fast path** (primary). Traverse ArrayLiteralExpression, follow
+ *    Identifiers to their VariableDeclaration (same-file or via ImportDeclaration
+ *    → getModuleSpecifierSourceFile()), recursively expand spreads. This is
+ *    the idiomatic ts-morph pattern (see ts-morph issue #644 — manual iteration
+ *    is ~1000x faster than getExportedDeclarations() because it doesn't trigger
+ *    full symbol binding). Files are added to the project on demand via
+ *    `addSourceFileAtPath()` as the walk discovers them.
+ * 2. **Symbol fallback** (only when fast path exhausts). Uses
+ *    `getAliasedSymbol()` + `symbol.getDeclarations()[0]` to handle exotic
+ *    re-export chains the manual walk can't follow.
+ *
+ * ## Escape hatch
+ *
+ * A leading `/* @lua-ignore-ref *\/` comment on the expression silences the
+ * deopt diagnostic for users who intentionally construct the array dynamically.
+ *
+ * ## Why we don't evaluate code
+ *
+ * Earlier iterations used `ts-evaluator` to sandbox-evaluate array expressions.
+ * That path loses the link to the compile-time identifier (it yields runtime
+ * `.name` strings, not the class/variable name needed for import resolution)
+ * and adds a sandboxed-RCE surface (cf. CVE-2023-45133 in Babel). The AST
+ * approach covers every case the evaluator did, cheaper and safer.
+ */
+import { Node, } from 'ts-morph';
+import { resolveModuleSpecifier, getProjectRootDir, } from './path-resolver.js';
+// =============================================================================
+// PUBLIC API
+// =============================================================================
+/**
+ * Resolve an expression node that represents an array of primitive references.
+ *
+ * Typical usage from a plugin/traverser:
+ *
+ *     const prop = configObj.getProperty('mcpServers');
+ *     const init = (prop as PropertyAssignment).getInitializer();
+ *     const result = resolveArrayRefs(init, { project });
+ *     if (!result.confident) { log.warn(reportDeopt(result, 'mcpServers')); }
+ *     const refs = result.value;
+ *
+ * @param expression - The expression node whose value is expected to be an
+ *   array of primitive instances. Typically the initializer of a
+ *   `skills` / `tools` / `mcpServers` property.
+ * @param ctx - Resolver context carrying the project and optional logger.
+ * @returns An `EvaluationResult` — confident + full value on success,
+ *   confident:false + partial value + deopt node on unknown shapes.
+ */
+export function resolveArrayRefs(expression, ctx) {
+    if (!expression) {
+        // A missing expression is not a user error (absent property); confident empty.
+        return { confident: true, value: [] };
+    }
+    // Honor the escape hatch: any `/* @lua-ignore-ref */` comment on or
+    // leading into this expression means "trust me, don't diagnose this".
+    if (hasIgnoreRefPragma(expression)) {
+        ctx.log?.('  [@lua-ignore-ref] skipping resolution by user request');
+        return { confident: true, value: [] };
+    }
+    // Derive rootDir: explicit ctx wins, then the Compiler-registered
+    // value on the Project, then process.cwd() as a last-resort fallback
+    // (matches pre-refactor behavior for ad-hoc test callers).
+    const rootDir = ctx.rootDir ??
+        getProjectRootDir(ctx.project) ??
+        process.cwd();
+    const state = {
+        project: ctx.project,
+        rootDir,
+        visited: ctx.visited ?? new Set(),
+        log: ctx.log ?? (() => { }),
+        slowPathHits: 0,
+    };
+    const value = [];
+    resolveArrayExpression(expression, value, state);
+    // Slow-path telemetry — opt-in via SMOKE_DEBUG. If this is ever >0 for
+    // a fixture that the resolver should handle via the fast path, that's
+    // a sign the fast path regressed or the shape is unexpected.
+    if (state.slowPathHits > 0 && process.env.SMOKE_DEBUG) {
+        state.log(`[resolver] followSymbolInFile slow-path hits: ${state.slowPathHits}`);
+    }
+    if (state.deopt) {
+        return {
+            confident: false,
+            value,
+            deopt: state.deopt.node,
+            reason: state.deopt.reason,
+            ruleId: 'lua/unresolved-primitive-ref',
+        };
+    }
+    return { confident: true, value };
+}
+/**
+ * Format an `EvaluationResult.deopt` as a SARIF-style diagnostic string
+ * for `log.warn()`. Includes the rule id, file:line:col, reason, and a
+ * remediation hint pointing the user at the escape hatch.
+ *
+ * Call sites log this rather than constructing the string inline so every
+ * resolver deopt surfaces with the same shape.
+ */
+export function reportDeopt(result, propertyName) {
+    const deopt = result.deopt;
+    const sourceFile = deopt.getSourceFile();
+    const filePath = sourceFile.getFilePath();
+    const { line, column } = sourceFile.getLineAndColumnAtPos(deopt.getStart());
+    const snippet = truncate(deopt.getText(), 60);
+    return (`[${result.ruleId}] ${filePath}:${line}:${column}\n` +
+        `  could not statically resolve "${propertyName}": ${result.reason}\n` +
+        `  at: \`${snippet}\`\n` +
+        `  hint: inline the array, export the value as a plain array literal, ` +
+        `or add a leading /* @lua-ignore-ref */ comment to silence`);
+}
+/**
+ * Format a SARIF-style diagnostic that isn't anchored on an AST node we
+ * parsed directly (e.g. "tried to find a tool in this file and the
+ * plugin returned nothing"). For node-anchored deopts, use
+ * `reportDeopt()` instead — it produces richer output.
+ *
+ * All resolver/traverser warnings should flow through either this
+ * helper or `reportDeopt`, so every line the user sees has a rule id
+ * and follows the same shape.
+ */
+export function formatSarifWarning(args) {
+    const loc = args.line !== undefined && args.column !== undefined
+        ? `${args.filePath}:${args.line}:${args.column}`
+        : args.filePath;
+    const hintLine = args.hint ? `\n  hint: ${args.hint}` : '';
+    return `[${args.ruleId}] ${loc}\n  ${args.message}${hintLine}`;
+}
+// =============================================================================
+// ARRAY EXPRESSION WALK
+// =============================================================================
+/**
+ * Resolve an expression that's expected to be an array of primitive refs.
+ *
+ * Dispatches on node kind: ArrayLiteral → iterate elements; Identifier →
+ * follow the reference chain; anything else → deopt with a pinpointing reason.
+ *
+ * Mutates `out` with resolved refs and `state.deopt` on failure.
+ */
+function resolveArrayExpression(node, out, state) {
+    // Direct array literal: iterate elements.
+    if (Node.isArrayLiteralExpression(node)) {
+        for (const element of node.getElements()) {
+            resolveArrayElement(element, out, state);
+            if (state.deopt)
+                return; // stop at first deopt — we have a pinpoint
+        }
+        return;
+    }
+    // Identifier: follow to declaration, then recurse into its initializer.
+    if (Node.isIdentifier(node)) {
+        const decl = followIdentifier(node, state);
+        if (!decl) {
+            // Fall back to the default-import-of-array shape:
+            //   // target.ts
+            //   export default [new LuaMCPServer(...), ...];
+            //   // consumer.ts
+            //   import servers from './target';
+            //   mcpServers: servers;
+            // There's no `const servers = ...` to hand back as a declaration;
+            // instead, locate the default export expression and recurse into it.
+            const defaultExpr = followDefaultImportToExpression(node, state);
+            if (defaultExpr) {
+                resolveArrayExpression(defaultExpr, out, state);
+                return;
+            }
+            state.deopt = state.deopt ?? {
+                node,
+                reason: `cannot resolve identifier "${node.getText()}" to a declaration in the project`,
+            };
+            return;
+        }
+        // Class/function declarations aren't arrays — a user writing
+        // `mcpServers: MyClass` is malformed; pinpoint it.
+        if (!Node.isVariableDeclaration(decl)) {
+            state.deopt = state.deopt ?? {
+                node,
+                reason: `identifier "${node.getText()}" resolves to a ${decl.getKindName()}, not an array`,
+            };
+            return;
+        }
+        const init = decl.getInitializer();
+        if (!init) {
+            state.deopt = state.deopt ?? {
+                node,
+                reason: `identifier "${node.getText()}" resolves to a declaration with no initializer`,
+            };
+            return;
+        }
+        resolveArrayExpression(init, out, state);
+        return;
+    }
+    // Parenthesized / type-asserted / as-const: unwrap and recurse.
+    if (Node.isParenthesizedExpression(node)) {
+        resolveArrayExpression(node.getExpression(), out, state);
+        return;
+    }
+    if (Node.isAsExpression(node) || Node.isTypeAssertion(node) || Node.isSatisfiesExpression(node)) {
+        resolveArrayExpression(node.getExpression(), out, state);
+        return;
+    }
+    // Property access: `all.mcp` where `all` is an object literal.
+    if (Node.isPropertyAccessExpression(node)) {
+        const value = resolvePropertyAccess(node, state);
+        if (!value) {
+            state.deopt = state.deopt ?? {
+                node,
+                reason: `property access "${node.getText()}" does not resolve to a static array`,
+            };
+            return;
+        }
+        resolveArrayExpression(value, out, state);
+        return;
+    }
+    // Array concat expressions like `a.concat(b)` or `[...a, ...b]` route
+    // through ArrayLiteral (the spread case above) or deopt here.
+    if (Node.isCallExpression(node)) {
+        state.deopt = state.deopt ?? {
+            node,
+            reason: `call expression "${truncate(node.getText(), 40)}" cannot be statically resolved to an array`,
+        };
+        return;
+    }
+    state.deopt = state.deopt ?? {
+        node,
+        reason: `unsupported expression kind ${node.getKindName()}`,
+    };
+}
+/**
+ * Resolve a single element within an ArrayLiteralExpression.
+ *
+ * Handles:
+ * - `new X({...})` → ResolvedRef pointing at the inline NewExpression
+ * - `foo` (Identifier) → follow to declaration, decide if it's a ref or an array
+ * - `...foo` (Spread) → recurse into the spread expression as an array
+ * - Anything else → deopt
+ */
+function resolveArrayElement(element, out, state) {
+    // Unwrap parens / assertions first.
+    let node = element;
+    while (Node.isParenthesizedExpression(node) ||
+        Node.isAsExpression(node) ||
+        Node.isTypeAssertion(node) ||
+        Node.isSatisfiesExpression(node)) {
+        node = node.getExpression();
+    }
+    // Spread: `...foo` — resolve as an array expression.
+    if (Node.isSpreadElement(node)) {
+        resolveArrayExpression(node.getExpression(), out, state);
+        return;
+    }
+    // Inline `new X({...})` — record with identifier = class name.
+    //
+    // Two legitimate interpretations depending on the caller:
+    //   1. Tool-class pattern (SkillPlugin's `tools: [new GetUserDataTool()]`):
+    //      the class name is imported from another project file and we
+    //      need `sourceFile` to point at that file so `ToolPlugin.detect()`
+    //      can find `export class GetUserDataTool` there.
+    //   2. Primitive-registration pattern (AgentTraverser's
+    //      `mcpServers: [new LuaMCPServer({...})]`): the class name is
+    //      external/generic (LuaMCPServer lives in the `lua-cli` package)
+    //      and the actual primitive is the inline NewExpression itself,
+    //      so `sourceFile` stays the consumer's file and AgentTraverser
+    //      emits a deopt diagnostic (see `newExpression && !declaration`).
+    //
+    // Distinguishing them: try to follow the class identifier to a local
+    // ClassDeclaration. If we find one in a real project source file, we
+    // record it — that tells downstream plugins to look in the target
+    // file. If the declaration lives in a `.d.ts` / `node_modules` file
+    // (e.g. `LuaMCPServer` resolving to `lua-cli`'s ambient class via
+    // TS's aliased-symbol lookup), we treat it as external and keep the
+    // old permissive shape so AgentTraverser's `newExpression &&
+    // !declaration` deopt path still fires. Without this guard, inline
+    // primitive-registration cases (`mcpServers: [new LuaMCPServer(...)]`)
+    // would silently bind to the ambient class declaration and then
+    // silently fail to detect any primitive downstream.
+    if (Node.isNewExpression(node)) {
+        const classExpr = node.getExpression();
+        const className = classExpr.getText();
+        if (Node.isIdentifier(classExpr)) {
+            const decl = followIdentifier(classExpr, state);
+            if (decl && Node.isClassDeclaration(decl)) {
+                const declFile = decl.getSourceFile();
+                const isProjectFile = !declFile.isDeclarationFile() && !declFile.isInNodeModules();
+                if (isProjectFile) {
+                    out.push({
+                        identifierName: className,
+                        sourceFile: declFile,
+                        declaration: decl,
+                        newExpression: node,
+                        viaDefaultImport: isDefaultImportBinding(classExpr),
+                    });
+                    return;
+                }
+            }
+        }
+        out.push({
+            identifierName: className,
+            sourceFile: node.getSourceFile(),
+            newExpression: node,
+        });
+        return;
+    }
+    // `foo` — follow to declaration.
+    if (Node.isIdentifier(node)) {
+        // Record whether this identifier is a consumer-side default-import
+        // binding (`import whatever from './target'`). Propagated onto every
+        // ref produced below so downstream plugin.detect() matching can
+        // prefer the target's default export — the consumer's local name is
+        // arbitrary and won't line up with any exportName on the target side.
+        const viaDefaultImport = isDefaultImportBinding(node);
+        const decl = followIdentifier(node, state);
+        if (!decl) {
+            // Fallback: the identifier IS an import, but the target uses an
+            // inline `export default defineX({...})` / `export default new X({...})`
+            // pattern that doesn't bind to a named declaration. We can still
+            // report the reference because the plugin's `detect()` will walk the
+            // target file and find the inline primitive by itself.
+            const fileLevelRef = findFileLevelImport(node, state);
+            if (fileLevelRef) {
+                out.push(fileLevelRef);
+                return;
+            }
+            state.deopt = state.deopt ?? {
+                node,
+                reason: `cannot resolve identifier "${node.getText()}" to a declaration in the project`,
+            };
+            return;
+        }
+        // If the declaration IS a class/function (like `new` used as a var), treat as ref.
+        if (Node.isClassDeclaration(decl) || Node.isFunctionDeclaration(decl)) {
+            out.push({
+                identifierName: node.getText(),
+                sourceFile: decl.getSourceFile(),
+                declaration: decl,
+                viaDefaultImport,
+            });
+            return;
+        }
+        const init = decl.getInitializer();
+        if (!init) {
+            // Exported as type-only / ambient → not a primitive we can compile.
+            state.deopt = state.deopt ?? {
+                node,
+                reason: `identifier "${node.getText()}" has no initializer`,
+            };
+            return;
+        }
+        // Variable points at another array — this is a pass-through, recurse.
+        if (Node.isArrayLiteralExpression(init)) {
+            resolveArrayExpression(init, out, state);
+            return;
+        }
+        // Variable points at another identifier — keep following.
+        if (Node.isIdentifier(init)) {
+            resolveArrayElement(init, out, state);
+            return;
+        }
+        // Variable points at a `new X({...})` — leaf ref.
+        if (Node.isNewExpression(init)) {
+            out.push({
+                identifierName: node.getText(),
+                sourceFile: decl.getSourceFile(),
+                declaration: decl,
+                newExpression: init,
+                viaDefaultImport,
+            });
+            return;
+        }
+        // Variable points at a `defineX({...})` call — also a leaf ref.
+        if (Node.isCallExpression(init)) {
+            out.push({
+                identifierName: node.getText(),
+                sourceFile: decl.getSourceFile(),
+                declaration: decl,
+                viaDefaultImport,
+            });
+            return;
+        }
+        // Any other initializer (property access, complex expression) — treat
+        // as an opaque leaf ref. Plugins downstream will attempt detection.
+        // We take the name as authoritative; if the plugin can't match it we
+        // fall back to a warning, not a silent drop.
+        out.push({
+            identifierName: node.getText(),
+            sourceFile: decl.getSourceFile(),
+            declaration: decl,
+            viaDefaultImport,
+        });
+        return;
+    }
+    // Property access as an element (e.g. `registry.auth`) — resolve.
+    if (Node.isPropertyAccessExpression(node)) {
+        const value = resolvePropertyAccess(node, state);
+        if (!value) {
+            state.deopt = state.deopt ?? {
+                node,
+                reason: `property access "${node.getText()}" does not resolve to a primitive`,
+            };
+            return;
+        }
+        resolveArrayElement(value, out, state);
+        return;
+    }
+    state.deopt = state.deopt ?? {
+        node,
+        reason: `unsupported array element kind ${node.getKindName()}`,
+    };
+}
+// =============================================================================
+// IDENTIFIER → DECLARATION RESOLUTION
+// =============================================================================
+/**
+ * Follow an Identifier to the VariableDeclaration/ClassDeclaration/
+ * FunctionDeclaration it ultimately refers to.
+ *
+ * Order of attempts (cheapest first; matches ts-morph issue #644 guidance):
+ *
+ * 1. Same-file variable declaration (O(1) symbol-table lookup).
+ * 2. Same-file class/function declaration.
+ * 3. Follow an `import` to the target SourceFile, then:
+ *    - Named export in that file (or a variable with the same name)
+ *    - Re-export chain (`export { x } from './y'`, `export * from './y'`)
+ *    - Default export matching the imported default binding
+ * 4. Symbol-based fallback (`getAliasedSymbol`) — only if the manual
+ *    walk exhausted. This is the slow path (triggers TS binding) but
+ *    covers exotic cases the manual walk doesn't model.
+ *
+ * Cycle detection: we mark `<filePath>#<identifier>` in `state.visited`
+ * before recursing across files. A revisit short-circuits to undefined
+ * rather than looping — the caller emits a deopt with a clear reason.
+ */
+function followIdentifier(node, state) {
+    const name = node.getText();
+    const sourceFile = node.getSourceFile();
+    const visitKey = `${sourceFile.getFilePath()}#${name}`;
+    if (state.visited.has(visitKey)) {
+        state.log(`  cycle detected following ${visitKey}; stopping walk`);
+        return undefined;
+    }
+    state.visited.add(visitKey);
+    // Step 1: same-file variable.
+    const localVar = sourceFile.getVariableDeclaration(name);
+    if (localVar)
+        return localVar;
+    // Step 2: same-file class/function.
+    const localClass = sourceFile.getClass(name);
+    if (localClass)
+        return localClass;
+    const localFn = sourceFile.getFunction(name);
+    if (localFn)
+        return localFn;
+    // Step 3: imports.
+    const viaImport = followImport(name, sourceFile, state);
+    if (viaImport)
+        return viaImport;
+    // Step 4: symbol fallback — only reached when the manual walk exhausts.
+    // Intentionally last because it triggers full TS binding.
+    return followSymbol(node, state);
+}
+/**
+ * When `node` is a default-imported identifier (`import servers from './x'`),
+ * return the expression on the right-hand side of that file's
+ * `export default ...`, so the array walk can recurse into it.
+ *
+ * Handles the case the declaration-based path can't:
+ *   // target.ts
+ *   export default [a, b];
+ * There's no `VariableDeclaration` named `servers` here — the export
+ * assignment's expression is the array itself, and we have to hand the
+ * whole expression back to the caller so it can iterate the elements.
+ *
+ * Returns undefined when the identifier isn't a default import, or when
+ * the target uses `export default someIdentifier` (already handled by
+ * `resolveDefaultInFile` → declaration path) or is otherwise opaque.
+ */
+function followDefaultImportToExpression(node, state) {
+    const name = node.getText();
+    const sourceFile = node.getSourceFile();
+    for (const importDecl of sourceFile.getImportDeclarations()) {
+        const defaultImport = importDecl.getDefaultImport();
+        if (!defaultImport || defaultImport.getText() !== name)
+            continue;
+        const target = loadImportTarget(importDecl, state, sourceFile.getFilePath());
+        if (!target)
+            return undefined;
+        for (const assign of target.getExportAssignments()) {
+            if (assign.isExportEquals())
+                continue;
+            return assign.getExpression();
+        }
+        return undefined;
+    }
+    return undefined;
+}
+/**
+ * Locate the target SourceFile for an imported identifier without requiring
+ * an intermediary declaration on that side. Used for the common pattern:
+ *
+ *     // target.ts
+ *     export default defineJob({ ... });
+ *     // consumer.ts
+ *     import syncJob from './target';
+ *     jobs: [syncJob];
+ *
+ * There's no `const syncJob = ...` on the target side, so `followIdentifier`
+ * can't produce a declaration — but we still know which file holds the
+ * primitive and what name the consumer used. The caller's plugin will walk
+ * that file with its own `detect()` and find the inline primitive.
+ */
+function findFileLevelImport(node, state) {
+    const name = node.getText();
+    const sourceFile = node.getSourceFile();
+    for (const importDecl of sourceFile.getImportDeclarations()) {
+        const defaultImport = importDecl.getDefaultImport();
+        const matchesDefault = defaultImport?.getText() === name;
+        const matchesNamed = importDecl
+            .getNamedImports()
+            .some((n) => (n.getAliasNode()?.getText() ?? n.getName()) === name);
+        if (!matchesDefault && !matchesNamed)
+            continue;
+        const target = loadImportTarget(importDecl, state, sourceFile.getFilePath());
+        if (!target)
+            return undefined;
+        return {
+            identifierName: name,
+            sourceFile: target,
+            viaDefaultImport: matchesDefault,
+        };
+    }
+    return undefined;
+}
+/**
+ * Find a same-named ImportDeclaration and resolve into the target file.
+ *
+ * Handles:
+ * - `import foo from './x'` (default)
+ * - `import { foo } from './x'` (named)
+ * - `import { foo as bar } from './x'` (named w/ alias)
+ *
+ * Namespace imports (`import * as ns from './x'`) aren't resolved here
+ * — a bare `ns` identifier can't stand in for a primitive array; the
+ * only meaningful use is `ns.foo`, which is resolved in
+ * `resolvePropertyAccess` via `followNamespaceImport`.
+ *
+ * After locating the import, loads the target file into the project
+ * on demand and recurses inside it via `resolveInFile()`.
+ */
+function followImport(name, sourceFile, state) {
+    for (const importDecl of sourceFile.getImportDeclarations()) {
+        // Default: `import foo from './x'`
+        const defaultImport = importDecl.getDefaultImport();
+        if (defaultImport && defaultImport.getText() === name) {
+            const targetFile = loadImportTarget(importDecl, state, sourceFile.getFilePath());
+            if (!targetFile)
+                return undefined;
+            return resolveDefaultInFile(targetFile, state);
+        }
+        // Named: `import { foo } from './x'` or `import { foo as bar } from './x'`
+        for (const named of importDecl.getNamedImports()) {
+            const localBinding = named.getAliasNode()?.getText() ?? named.getName();
+            if (localBinding !== name)
+                continue;
+            const remoteName = named.getName(); // the name as exported by target
+            const targetFile = loadImportTarget(importDecl, state, sourceFile.getFilePath());
+            if (!targetFile)
+                return undefined;
+            return resolveInFile(remoteName, targetFile, state);
+        }
+    }
+    return undefined;
+}
+/**
+ * Load the SourceFile that an `import` or `export ... from` declaration
+ * points at, using the ts-morph built-in resolver where it works, and
+ * falling back to the project's tsconfig `paths` aliases + relative FS
+ * resolution otherwise.
+ *
+ * Works uniformly for `ImportDeclaration` and `ExportDeclaration` because
+ * both expose `getModuleSpecifierSourceFile()` / `getModuleSpecifierValue()`
+ * (ExportDeclaration returns undefined when there's no `from` clause).
+ *
+ * Files discovered this way are added to the project lazily so the rest
+ * of the resolver (and downstream plugins) can use them as first-class
+ * SourceFiles.
+ */
+function loadImportTarget(decl, state, fromFile) {
+    // Fast path: ts-morph already figured it out.
+    const viaTsMorph = decl.getModuleSpecifierSourceFile();
+    if (viaTsMorph)
+        return viaTsMorph;
+    // Slow path: shared resolveModuleSpecifier in utils/path-resolver.ts
+    // — the same helper AgentTraverser uses, so drift between the two
+    // sites (previously a real concern) is impossible.
+    const specifier = decl.getModuleSpecifierValue();
+    if (!specifier)
+        return undefined; // bare `export { x }` with no source
+    const resolved = resolveModuleSpecifier(specifier, fromFile, state.rootDir);
+    if (!resolved)
+        return undefined;
+    try {
+        const existing = state.project.getSourceFile(resolved);
+        if (existing)
+            return existing;
+        return state.project.addSourceFileAtPath(resolved);
+    }
+    catch (err) {
+        state.log(`  failed to load ${resolved}: ${String(err)}`);
+        return undefined;
+    }
+}
+/**
+ * Resolve an `export { x } from './y'` / `export * from './y'` /
+ * same-file declaration named `name` in the given file.
+ *
+ * Walks the re-export graph breadth-first until it finds the underlying
+ * declaration. Guarded by `state.visited` against cyclic re-exports.
+ */
+function resolveInFile(name, sourceFile, state) {
+    const visitKey = `${sourceFile.getFilePath()}#${name}`;
+    if (state.visited.has(visitKey))
+        return undefined;
+    state.visited.add(visitKey);
+    // Same-file declaration wins.
+    const local = sourceFile.getVariableDeclaration(name)
+        ?? sourceFile.getClass(name)
+        ?? sourceFile.getFunction(name);
+    if (local)
+        return local;
+    // Re-exports with a module specifier: `export { x } from './y'`,
+    // `export { x as y } from './z'`, `export * from './y'`, `export * as ns from './y'`.
+    for (const exp of sourceFile.getExportDeclarations()) {
+        if (!exp.getModuleSpecifierValue())
+            continue;
+        const target = loadImportTarget(exp, state, sourceFile.getFilePath());
+        if (!target)
+            continue;
+        const matched = findInNamedExports(exp, name);
+        if (matched) {
+            return resolveInFile(matched, target, state);
+        }
+        // `export * from './y'` — ts-morph models this as an ExportDeclaration
+        // with a module specifier, no named exports, and no namespace export.
+        // Recurse to search the target exhaustively.
+        const isWildcard = exp.getNamedExports().length === 0 && !exp.getNamespaceExport();
+        if (isWildcard) {
+            const viaWildcard = resolveInFile(name, target, state);
+            if (viaWildcard)
+                return viaWildcard;
+        }
+    }
+    // Re-exports without a module specifier: `export { x }` (rebind within
+    // the same file, possibly with a rename).
+    for (const exp of sourceFile.getExportDeclarations()) {
+        if (exp.getModuleSpecifierValue())
+            continue;
+        const matched = findInNamedExports(exp, name);
+        if (matched) {
+            return resolveInFile(matched, sourceFile, state);
+        }
+    }
+    // Chase symbol as a last resort — expensive, but handles exotic barrels.
+    const symbolResult = followSymbolInFile(name, sourceFile, state);
+    if (symbolResult)
+        return symbolResult;
+    return undefined;
+}
+/**
+ * Find the `default` export in a file. Typical shapes:
+ *   export default foo          → VariableDeclaration for `foo`
+ *   export default new X({...}) → synthesized VariableDeclaration? No — return undefined
+ *                                 and let the caller handle it (we don't manufacture decls).
+ *   export default function X() → FunctionDeclaration
+ *   export default class X {}   → ClassDeclaration
+ *
+ * Returns undefined for inline `export default <expr>` patterns that don't
+ * bind to a named declaration — those cases bubble up as a deopt with a
+ * clear message upstream.
+ */
+function resolveDefaultInFile(sourceFile, state) {
+    for (const assign of sourceFile.getExportAssignments()) {
+        if (assign.isExportEquals())
+            continue;
+        const expr = assign.getExpression();
+        if (Node.isIdentifier(expr)) {
+            return resolveInFile(expr.getText(), sourceFile, state);
+        }
+        // `export default new X(...)` / `export default defineX(...)` —
+        // the caller has to treat the whole file as the unit.
+        return undefined;
+    }
+    // `export default function X()` / `export default class X {}`
+    for (const cls of sourceFile.getClasses()) {
+        if (cls.isDefaultExport())
+            return cls;
+    }
+    for (const fn of sourceFile.getFunctions()) {
+        if (fn.isDefaultExport())
+            return fn;
+    }
+    // Re-export-as-default:
+    //     export { foo as default } from './other'
+    //     export { foo as default }              (same-file, equivalent to
+    //                                             `export default foo`)
+    // These don't show up as ExportAssignments or `isDefaultExport()`
+    // declarations — they're ExportDeclarations with a spec aliased to
+    // `default`. Without this branch the walk falls back to
+    // `findFileLevelImport`, which lands on the barrel file instead of
+    // the ultimate source, and plugin.detect() emits a spurious
+    // `lua/missing-primitive-declaration` on a file that legitimately
+    // has no primitive in it.
+    for (const exp of sourceFile.getExportDeclarations()) {
+        for (const spec of exp.getNamedExports()) {
+            const alias = spec.getAliasNode()?.getText();
+            if (alias !== 'default')
+                continue;
+            const remoteName = spec.getName();
+            const moduleSpecifier = exp.getModuleSpecifierValue();
+            if (moduleSpecifier) {
+                // Cross-file: `export { foo as default } from './other'`
+                const target = loadImportTarget(exp, state, sourceFile.getFilePath());
+                if (!target)
+                    return undefined;
+                return resolveInFile(remoteName, target, state);
+            }
+            // Same-file: `export { foo as default }` without a `from` clause
+            return resolveInFile(remoteName, sourceFile, state);
+        }
+    }
+    return undefined;
+}
+/**
+ * Return the name (as written in the source module) that a named export
+ * specifier maps to, or undefined if this declaration doesn't export `name`.
+ *
+ *     export { foo }        → findInNamedExports(_, 'foo') = 'foo'
+ *     export { foo as bar } → findInNamedExports(_, 'bar') = 'foo'
+ *
+ * The returned name is used to recurse into the source module because
+ * that's what THAT module exports, not the alias used here.
+ */
+function findInNamedExports(exp, name) {
+    for (const spec of exp.getNamedExports()) {
+        const localName = spec.getAliasNode()?.getText() ?? spec.getName();
+        if (localName === name)
+            return spec.getName();
+    }
+    return undefined;
+}
+// =============================================================================
+// SYMBOL FALLBACK (slow path)
+// =============================================================================
+/**
+ * Last-resort identifier resolution via the TypeChecker's symbol graph.
+ * Handles re-export shapes the manual walk above doesn't model (e.g. some
+ * exotic `export type` + `export` combinations, declaration-merging barrels).
+ *
+ * Expensive — triggers full symbol binding — so we only reach it when the
+ * cheaper paths above have returned undefined. See ts-morph issue #644.
+ */
+function followSymbol(node, state) {
+    try {
+        const symbol = node.getSymbol();
+        if (!symbol)
+            return undefined;
+        const aliased = symbol.isAlias()
+            ? node.getSourceFile().getProject().getTypeChecker().getAliasedSymbol(symbol) ?? symbol
+            : symbol;
+        for (const decl of aliased.getDeclarations()) {
+            if (Node.isVariableDeclaration(decl) || Node.isClassDeclaration(decl) || Node.isFunctionDeclaration(decl)) {
+                return decl;
+            }
+        }
+    }
+    catch (err) {
+        state.log(`  symbol fallback failed: ${String(err)}`);
+    }
+    return undefined;
+}
+/**
+ * Symbol fallback keyed by file + name rather than an existing Identifier
+ * node. Used when chasing re-exports that point at a name that's declared
+ * further down the graph than our manual walk can follow.
+ */
+function followSymbolInFile(name, sourceFile, state) {
+    // Count every invocation of this slow path, not just ones that
+    // succeed — the point of the telemetry is to know how often we hit
+    // `getExportedDeclarations`, which triggers full TS binding and is
+    // ~1000x slower than the AST-based walks above. Surfaced by
+    // `resolveArrayRefs` under SMOKE_DEBUG.
+    state.slowPathHits++;
+    try {
+        const exportedMap = sourceFile.getExportedDeclarations();
+        const decls = exportedMap.get(name);
+        if (!decls)
+            return undefined;
+        for (const decl of decls) {
+            if (Node.isVariableDeclaration(decl) || Node.isClassDeclaration(decl) || Node.isFunctionDeclaration(decl)) {
+                return decl;
+            }
+        }
+    }
+    catch (err) {
+        state.log(`  symbol-in-file fallback failed for ${name}: ${String(err)}`);
+    }
+    return undefined;
+}
+// =============================================================================
+// PROPERTY ACCESS RESOLUTION
+// =============================================================================
+/**
+ * Resolve `a.b` where `a` is a same-file object literal, an imported object
+ * literal, or a namespace import (`import * as ns from './x'`), and `b` is
+ * a known property / named export. Returns the value node (typically an
+ * ArrayLiteralExpression) so the caller can recurse into it.
+ *
+ * Deep chains like `a.b.c` are handled recursively.
+ *
+ * Namespace imports are handled here — `followImport` can't express them
+ * because `ns` has no backing VariableDeclaration. From the resolver's
+ * point of view, `ns.foo` is equivalent to `import { foo } from './x'`,
+ * so we short-circuit to looking up `foo` in the target file's scope and
+ * returning its initializer. The returned node lives in the target file,
+ * so any identifiers inside it resolve in the right scope on recursion.
+ */
+function resolvePropertyAccess(node, state) {
+    if (!Node.isPropertyAccessExpression(node))
+        return undefined;
+    const propertyName = node.getName();
+    const objectExpr = node.getExpression();
+    // Namespace-import short-circuit: `ns.foo` where `ns` came from
+    // `import * as ns from './x'`. Look `foo` up as a named export on the
+    // target file and return its initializer directly.
+    if (Node.isIdentifier(objectExpr)) {
+        const namespaceTarget = followNamespaceImport(objectExpr, state);
+        if (namespaceTarget) {
+            const decl = resolveInFile(propertyName, namespaceTarget, state);
+            if (decl && Node.isVariableDeclaration(decl)) {
+                return decl.getInitializer();
+            }
+            // Class/function export under a namespace isn't a valid object-literal
+            // base — fall through to deopt at the call site.
+            return undefined;
+        }
+    }
+    // Resolve the object part.
+    let objectNode = objectExpr;
+    if (Node.isIdentifier(objectExpr)) {
+        const decl = followIdentifier(objectExpr, state);
+        // Only VariableDeclarations have initializers; class/function
+        // declarations can't back an object-literal property chain.
+        objectNode = decl && Node.isVariableDeclaration(decl) ? decl.getInitializer() : undefined;
+    }
+    else if (Node.isPropertyAccessExpression(objectExpr)) {
+        objectNode = resolvePropertyAccess(objectExpr, state);
+    }
+    if (!objectNode || !Node.isObjectLiteralExpression(objectNode)) {
+        return undefined;
+    }
+    const prop = objectNode.getProperty(propertyName);
+    if (!prop || !Node.isPropertyAssignment(prop))
+        return undefined;
+    return prop.getInitializer();
+}
+/**
+ * If `identifier` is the local binding of an `import * as ns from './x'`
+ * declaration, return the target SourceFile. Otherwise undefined.
+ *
+ * Narrowly scoped helper for `resolvePropertyAccess` — namespace imports
+ * outside a property-access context would just deopt (you can't register
+ * a primitive array as `mcpServers: ns` since `ns` is a module object,
+ * not an array), so this is the only place it needs to exist.
+ */
+function followNamespaceImport(identifier, state) {
+    const name = identifier.getText();
+    const sourceFile = identifier.getSourceFile();
+    for (const importDecl of sourceFile.getImportDeclarations()) {
+        const ns = importDecl.getNamespaceImport();
+        if (!ns || ns.getText() !== name)
+            continue;
+        return loadImportTarget(importDecl, state, sourceFile.getFilePath());
+    }
+    return undefined;
+}
+/**
+ * Return true when `identifier` is the local binding of a default import
+ * (`import whatever from './target'`). Used to mark resulting `ResolvedRef`s
+ * so downstream plugin.detect() matching can prefer the target's default
+ * export — the consumer-side binding name is arbitrary and uncorrelated
+ * with any exportName on the target side.
+ */
+function isDefaultImportBinding(identifier) {
+    const name = identifier.getText();
+    const sourceFile = identifier.getSourceFile();
+    for (const importDecl of sourceFile.getImportDeclarations()) {
+        const defaultImport = importDecl.getDefaultImport();
+        if (defaultImport && defaultImport.getText() === name)
+            return true;
+    }
+    return false;
+}
+// =============================================================================
+// ESCAPE HATCH
+// =============================================================================
+/**
+ * Check for a `/* @lua-ignore-ref *\/` pragma on the node or its enclosing
+ * property assignment / array element. Matches the spirit of `@ts-ignore`
+ * and `eslint-disable-next-line` — a small, stable string users can write
+ * in source to opt out of this particular static check without silencing
+ * everything else.
+ *
+ * Accepts all of these placements:
+ *
+ *     // @lua-ignore-ref               (leading line comment)
+ *     mcpServers: buildDynamically()
+ *
+ *     mcpServers: /* @lua-ignore-ref *\/ buildDynamically()   (inline block)
+ *
+ *     mcpServers: buildDynamically()   // @lua-ignore-ref   (trailing line)
+ *
+ *     mcpServers: buildDynamically()   /* @lua-ignore-ref *\/   (trailing block)
+ *
+ *     /** @lua-ignore-ref *\/          (JSDoc-style leading)
+ *     mcpServers: buildDynamically()
+ *
+ * We can't rely on `getLeadingCommentRanges()` alone because ts-morph
+ * doesn't surface inline block comments between a `:` and the expression
+ * (they're parsed as trivia the scanner drops). Instead we inspect the
+ * raw source slice on both sides of each candidate node — leading trivia
+ * via `FullStart..Start`, trailing trivia via `End..(next sibling's
+ * FullStart or parent End)` — which covers every placement a user who
+ * read the "ESLint-style" description would naturally reach for.
+ */
+// Match the pragma only when it appears inside a real comment delimiter, so
+// a plain mention in surrounding prose — e.g. `// TODO: consider @lua-ignore-ref
+// here instead` in some far-away line that happens to end up in the same
+// trivia slice — doesn't accidentally disable the check. The `\b` after the
+// pragma name also prevents matching something like `@lua-ignore-refactor`.
+// The `\*?` after `/*` lets JSDoc-style `/** @lua-ignore-ref */` also match
+// — that's many users' reflex for "tool-recognized comment" and costs us
+// nothing to support.
+const IGNORE_REF_PRAGMA_REGEX = /(?:\/\*\*?|\/\/)\s*@lua-ignore-ref\b/;
+function hasIgnoreRefPragma(node) {
+    // Leading trivia slice: [FullStart, Start). Captures comments on the
+    // line(s) before a node or in the trivia between `:` and the node.
+    const leadingSliceHasPragma = (candidate) => {
+        if (!candidate)
+            return false;
+        const sourceText = candidate.getSourceFile().getFullText();
+        const slice = sourceText.slice(candidate.getFullStart(), candidate.getStart());
+        return IGNORE_REF_PRAGMA_REGEX.test(slice);
+    };
+    // Trailing trivia slice: [End, nextBoundary). `nextBoundary` is the
+    // next sibling's FullStart if any (its FullStart includes all trivia
+    // up to itself, so the slice between us and it is our trailing
+    // trivia), otherwise the parent's End. This catches `// @lua-ignore-ref`
+    // written after the property value — a common user reflex from ESLint.
+    const trailingSliceHasPragma = (candidate) => {
+        if (!candidate)
+            return false;
+        const sourceText = candidate.getSourceFile().getFullText();
+        const end = candidate.getEnd();
+        let nextBoundary;
+        const parent = candidate.getParent();
+        if (parent) {
+            const siblings = parent.getChildren();
+            const idx = siblings.indexOf(candidate);
+            if (idx >= 0 && idx + 1 < siblings.length) {
+                nextBoundary = siblings[idx + 1].getFullStart();
+            }
+            else {
+                nextBoundary = parent.getEnd();
+            }
+        }
+        if (nextBoundary === undefined || nextBoundary <= end)
+            return false;
+        const slice = sourceText.slice(end, nextBoundary);
+        return IGNORE_REF_PRAGMA_REGEX.test(slice);
+    };
+    if (leadingSliceHasPragma(node))
+        return true;
+    if (leadingSliceHasPragma(node.getParent()))
+        return true;
+    if (trailingSliceHasPragma(node))
+        return true;
+    if (trailingSliceHasPragma(node.getParent()))
+        return true;
+    return false;
+}
+// =============================================================================
+// SMALL UTILITIES
+// =============================================================================
+function truncate(s, max) {
+    if (s.length <= max)
+        return s;
+    return s.slice(0, max - 1) + '…';
+}
+//# sourceMappingURL=reference-resolver.js.map