lua-cli 3.15.3 → 3.16.0

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

@@ -1,1026 +0,0 @@
-/**
- * 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