devsmind-mcp 2.3.0 → 3.0.0

package/dist/utils/ast.js

@@ -33,13 +33,84 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.AST_PARSEABLE_EXTENSIONS = void 0;
+exports.isAstParseable = isAstParseable;
+exports.normalizeFsPath = normalizeFsPath;
+exports.invalidateParsedFile = invalidateParsedFile;
 exports.parseNodeId = parseNodeId;
+exports.detectRtkEndpointAliases = detectRtkEndpointAliases;
+exports.detectRtkEndpointNodes = detectRtkEndpointNodes;
 exports.resolveConnectionsLocally = resolveConnectionsLocally;
+exports.locateNodeInFile = locateNodeInFile;
 exports.extractNodeFromFile = extractNodeFromFile;
+exports.enumerateFileCandidates = enumerateFileCandidates;
+exports.outlineFile = outlineFile;
+exports.listFileImports = listFileImports;
+exports.findTouchedSymbols = findTouchedSymbols;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const ts = __importStar(require("typescript"));
 const config_1 = require("./config");
+/**
+ * Extensions the TypeScript parser can read, and therefore the only ones where a symbol's exact
+ * span is knowable — live code extraction, AST edge resolution, and in-place editing are all
+ * limited to these. Every other indexed language falls back to regex reference matching.
+ *
+ * `.mjs`/`.cjs` are plain JavaScript and parse fine (TS understands both script kinds); they are
+ * listed for the same reason `.js` is. Template-based formats (`.vue`, `.svelte`) are NOT here —
+ * their files aren't valid JS, so the parser would choke on the markup.
+ */
+exports.AST_PARSEABLE_EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.vue', '.svelte']);
+/** Single-file-component formats: real JS, but only inside their `<script>` block. */
+const SFC_EXTENSIONS = new Set(['.vue', '.svelte']);
+/**
+ * For a single-file component, blank every character outside its `<script>` block(s) while
+ * preserving the file's exact length and line breaks. The parser then sees only JavaScript,
+ * yet every offset it reports still indexes the REAL file — which is what lets the rest of
+ * this module treat `.vue`/`.svelte` like any other source file. Other extensions pass through.
+ */
+function maskNonScript(text, filePath) {
+    if (!SFC_EXTENSIONS.has(path.extname(filePath).toLowerCase()))
+        return text;
+    const masked = text.replace(/[^\n]/g, ' ').split('');
+    const re = /<script\b[^>]*>([\s\S]*?)<\/script\s*>/gi;
+    for (let m = re.exec(text); m !== null; m = re.exec(text)) {
+        const innerStart = m.index + m[0].indexOf('>') + 1;
+        for (let i = 0; i < m[1].length; i++)
+            masked[innerStart + i] = text[innerStart + i];
+    }
+    return masked.join('');
+}
+/** Parse `text` as the JS/TS belonging to `filePath`, masking SFC markup first. */
+function parseText(filePath, text) {
+    const isSfc = SFC_EXTENSIONS.has(path.extname(filePath).toLowerCase());
+    return ts.createSourceFile(filePath, maskNonScript(text, filePath), ts.ScriptTarget.Latest, true, 
+    // An SFC's extension tells TS nothing; its <script> may be either language, and TS is a
+    // superset of JS, so parsing as TS reads both.
+    isSfc ? ts.ScriptKind.TS : undefined);
+}
+/** True when `filePath` can be parsed for exact symbol spans. */
+function isAstParseable(filePath) {
+    return exports.AST_PARSEABLE_EXTENSIONS.has(path.extname(filePath).toLowerCase());
+}
+/**
+ * Canonical form for COMPARING two filesystem paths — absolute, forward slashes, lower case.
+ *
+ * Windows reaches the same file through several spellings (`c:\x` vs `C:/x`), so any exact
+ * match against a stored path silently misses unless both sides are folded first. Comparison
+ * only: never write this back to disk or store it as a node's file_path.
+ */
+function normalizeFsPath(p) {
+    return path.resolve(p).replace(/\\/g, '/').toLowerCase();
+}
+/**
+ * Drop a file's cached AST. The cache is mtime-keyed, but mtime resolution is coarse enough
+ * that a write followed immediately by a read can still be served the pre-write tree, so a
+ * writer must invalidate explicitly rather than trust the timestamp to have moved.
+ */
+function invalidateParsedFile(filePath) {
+    sourceFileCache.delete(filePath);
+}
 /**
  * Parses a DevsMind node ID into constituent parts
  */
@@ -124,6 +195,8 @@ function getFileImports(sourceFile) {
  */
 function isDefinitionName(node) {
     const parent = node.parent;
+    /* istanbul ignore if -- defensive: every node from a tree parsed with setParentNodes=true
+       (see parseText) has a parent except the SourceFile itself, which is never an Identifier. */
     if (!parent)
         return false;
     // The declared name of a declaration (function foo, class Foo, const foo, param foo, foo() {} …)
@@ -343,6 +416,128 @@ function findRouteCall(sourceFile, method, arg) {
     ts.forEachChild(sourceFile, visit);
     return found;
 }
+/**
+ * Walks a source file for RTK Query endpoint definitions. Endpoint keys live inside
+ * `endpoints: (builder) => ({ ... })` — an ARROW FUNCTION BODY — so they are structurally
+ * invisible to the general declaration walk ({@link declarationsOverlapping}/`findNodeInAst`
+ * both explicitly stop at function-body boundaries, since a local const or a helper defined
+ * inside a function body is never a graph entity). RTK endpoints are the one exception to that
+ * rule this codebase knows about, which is why they need their own dedicated walk rather than
+ * being reachable by the general "find a declaration by name" machinery.
+ */
+function findRtkEndpointMatches(sourceFile) {
+    const results = [];
+    function findEndpointsObject(fnBody) {
+        const unwrap = (e) => ts.isParenthesizedExpression(e) ? unwrap(e.expression) : e;
+        if (ts.isBlock(fnBody)) {
+            for (const stmt of fnBody.statements) {
+                if (ts.isReturnStatement(stmt) && stmt.expression) {
+                    const expr = unwrap(stmt.expression);
+                    if (ts.isObjectLiteralExpression(expr))
+                        return expr;
+                }
+            }
+            return null;
+        }
+        const expr = unwrap(fnBody);
+        return ts.isObjectLiteralExpression(expr) ? expr : null;
+    }
+    function visit(node) {
+        if (ts.isCallExpression(node) &&
+            ts.isIdentifier(node.expression) &&
+            (node.expression.text === 'createApi' || node.expression.text === 'injectEndpoints') &&
+            node.arguments.length > 0 &&
+            ts.isObjectLiteralExpression(node.arguments[0])) {
+            const configObj = node.arguments[0];
+            for (const prop of configObj.properties) {
+                if (!ts.isPropertyAssignment(prop) ||
+                    !ts.isIdentifier(prop.name) ||
+                    prop.name.text !== 'endpoints' ||
+                    !(ts.isArrowFunction(prop.initializer) || ts.isFunctionExpression(prop.initializer)))
+                    continue;
+                const endpointsObj = findEndpointsObject(prop.initializer.body);
+                if (!endpointsObj)
+                    continue;
+                for (const epProp of endpointsObj.properties) {
+                    if (!(ts.isPropertyAssignment(epProp) || ts.isMethodDeclaration(epProp)) ||
+                        !(ts.isIdentifier(epProp.name) || ts.isStringLiteral(epProp.name)))
+                        continue;
+                    const epName = epProp.name.text;
+                    // `.query(...)` / `.mutation(...)` may appear either as `key: builder.query(...)`
+                    // (property assignment) or `key(builder) { return builder.query(...) }` (method) —
+                    // only the property-assignment shape is RTK Query's documented form, so that's all we
+                    // match; a method-shorthand endpoint falls through and simply isn't found.
+                    if (!ts.isPropertyAssignment(epProp) || !ts.isCallExpression(epProp.initializer))
+                        continue;
+                    const callExpr = epProp.initializer;
+                    if (!ts.isPropertyAccessExpression(callExpr.expression))
+                        continue;
+                    const method = callExpr.expression.name.text;
+                    if (method !== 'query' && method !== 'mutation')
+                        continue;
+                    results.push({ propNode: epProp, epName, method });
+                }
+            }
+        }
+        ts.forEachChild(node, visit);
+    }
+    visit(sourceFile);
+    return results;
+}
+function detectRtkEndpointAliases(filePath) {
+    if (!isAstParseable(filePath))
+        return [];
+    let sourceFile;
+    try {
+        sourceFile = getSourceFile(filePath);
+    }
+    catch {
+        return [];
+    }
+    const toPascal = (name) => (name.length ? name[0].toUpperCase() + name.slice(1) : name);
+    return findRtkEndpointMatches(sourceFile).map(({ epName, method }) => {
+        const pascal = toPascal(epName);
+        const aliases = method === 'query'
+            ? [`use${pascal}Query`, `useLazy${pascal}Query`]
+            : [`use${pascal}Mutation`];
+        return { endpointName: epName, aliases };
+    });
+}
+/**
+ * The candidate-enumeration counterpart to {@link detectRtkEndpointAliases}: produces full
+ * {@link ExtractionCandidate}s for each RTK endpoint, so {@link enumerateFileCandidates} doesn't
+ * silently skip them (see {@link findRtkEndpointMatches} for why the general declaration walk
+ * can't see them). Always `isExported:true` — an endpoint reached only through its generated hook
+ * is, for every practical purpose, part of the file's export surface; nothing about whether it
+ * "counts" as a node is a judgment call, so this feeds the SAME auto-accept path as a normal
+ * exported declaration.
+ */
+function detectRtkEndpointNodes(filePath) {
+    if (!isAstParseable(filePath))
+        return [];
+    let sourceFile;
+    try {
+        sourceFile = getSourceFile(filePath);
+    }
+    catch {
+        return [];
+    }
+    return findRtkEndpointMatches(sourceFile).map(({ propNode, epName }) => {
+        const start = propNode.getStart(sourceFile);
+        const end = propNode.getEnd();
+        const code = propNode.getText(sourceFile);
+        return {
+            qualified: epName,
+            name: epName,
+            type: 'rtk_endpoint',
+            signature: code.split('\n')[0].slice(0, 200),
+            codeSnapshot: code,
+            startLine: sourceFile.getLineAndCharacterOfPosition(start).line + 1,
+            endLine: sourceFile.getLineAndCharacterOfPosition(end).line + 1,
+            isExported: true
+        };
+    });
+}
 /** Navigate a dotted path through nested object-literal properties. */
 function navigateObjectPath(obj, segments) {
     let current = obj;
@@ -362,6 +557,10 @@ function navigateObjectPath(obj, segments) {
             current = null;
         }
     }
+    /* istanbul ignore next -- unreachable: every iteration of the loop above returns (either
+       `null` via a missing prop, or `prop` on the last segment), so control can only fall past
+       the loop when `segments` is empty. The sole caller (findInFrameworkContainer) already
+       guards `segments.length === 0` before ever calling this function. */
     return null;
 }
 /**
@@ -372,6 +571,9 @@ function navigateObjectPath(obj, segments) {
  * factory call's object-literal argument, so we isolate just that method.
  */
 function findInFrameworkContainer(sourceFile, segments) {
+    /* istanbul ignore if -- defensive: the sole caller (findNodeInAst) only reaches here when
+       `symbolName.includes('.')`, so `segments` (symbolName.split('.').slice(1)) always has at
+       least one element. */
     if (segments.length === 0)
         return null;
     const objArgs = [];
@@ -472,6 +674,10 @@ function findNodeInAst(sourceFile, className, symbolName) {
     // Fallback: className resolved to a non-class declaration (object literal, factory call,
     // etc). Search inside it for a property/method matching the member name, at any depth.
     if (!foundNode && className && containerCandidate) {
+        /* istanbul ignore next -- defensive: every current caller sets `className` from a symbolName
+           that included a '.' in the first place (locateNodeInFile/codeOfSymbol split on 2 parts,
+           resolveConnectionsLocally's className comes from parseNodeId, which only sets it alongside
+           a dotted symbolName), so the ": symbolName" (no-dot) fallback is never exercised. */
         const memberName = symbolName.includes('.') ? symbolName.split('.').pop() : symbolName;
         foundNode = findPropertyInContainer(containerCandidate, memberName);
     }
@@ -527,7 +733,7 @@ function getSourceFile(filePath, content) {
     if (cached && cached.mtimeMs === mtimeMs && content === undefined)
         return cached.sf;
     const text = content ?? fs.readFileSync(filePath, 'utf-8');
-    const sf = ts.createSourceFile(filePath, text, ts.ScriptTarget.Latest, true);
+    const sf = parseText(filePath, text);
     sourceFileCache.set(filePath, { mtimeMs, sf });
     return sf;
 }
@@ -615,6 +821,9 @@ function resolveToExistingFile(basePaths) {
         return cached;
     let result = null;
     outer: for (const base of basePaths) {
+        /* istanbul ignore if -- defensive: every entry basePaths can contain comes from
+           resolveImportToPaths, which only ever pushes path.resolve(...) results (always a
+           non-empty string) or pushes nothing at all — never a falsy element. */
         if (!base)
             continue;
         for (const ext of ['.ts', '.tsx', '.js', '.jsx']) {
@@ -659,6 +868,9 @@ function getBarrelReexports(resolvedImportPath) {
         barrelMissCache.add(resolvedImportPath);
         return [];
     }
+    /* istanbul ignore next -- defensive TOCTOU guard: `indexPath` was confirmed to exist one line
+       above via fs.existsSync; the `?? -1` only matters if the file is deleted in the instant
+       between that check and this statSync, a race not worth simulating in a unit test. */
     const mtimeMs = statMtime(indexPath) ?? -1;
     const cached = barrelCache.get(indexPath);
     if (cached && cached.mtimeMs === mtimeMs)
@@ -698,11 +910,30 @@ function getBarrelReexports(resolvedImportPath) {
 //     import alias by (case-insensitive) node name,
 //   - null when there is no default export at all.
 const ANON_DEFAULT = 'anon';
+/**
+ * The name for a non-identifier `export default <expr>` (an ExportAssignment): a named class or
+ * function expression's own name, or the ANON_DEFAULT marker for anything else.
+ */
+function anonOrNamedExpressionDefaultName(expr) {
+    /* istanbul ignore next -- unreachable: `export default class Foo {}` / `export default
+       function foo() {}`, named or anonymous, always parse as a ClassDeclaration/FunctionDeclaration
+       (getDefaultExportName's other, `stmt.name ? ... : ANON_DEFAULT`, branch), never as this
+       ExportAssignment's `expression`. The only way a ClassExpression/FunctionExpression can reach
+       here at all is wrapped (`export default (class Foo {})`), and then `expr` is the
+       ParenthesizedExpression, not the class/function expression itself — so this never matches in
+       practice, verified directly against the TS parser. */
+    if ((ts.isClassExpression(expr) || ts.isFunctionExpression(expr)) && expr.name)
+        return expr.name.text;
+    return ANON_DEFAULT; // `export default Joi.object({...})`, `{...}`, `() => …`
+}
 const defaultExportCache = new Map();
 function getDefaultExportName(filePath) {
     const ext = path.extname(filePath).toLowerCase();
     if (!['.ts', '.tsx', '.js', '.jsx'].includes(ext))
         return null;
+    /* istanbul ignore next -- defensive TOCTOU guard: every caller passes a `targetNode.file_path`
+       it already has from a live candidate-node list, i.e. a file that exists; the `?? -1` only
+       matters if it's deleted in the instant before this statSync. */
     const mtimeMs = statMtime(filePath) ?? -1;
     const cached = defaultExportCache.get(filePath);
     if (cached && cached.mtimeMs === mtimeMs)
@@ -714,12 +945,7 @@ function getDefaultExportName(filePath) {
             // `export default <expr>`
             if (ts.isExportAssignment(stmt) && !stmt.isExportEquals) {
                 const expr = stmt.expression;
-                if (ts.isIdentifier(expr))
-                    name = expr.text;
-                else if ((ts.isClassExpression(expr) || ts.isFunctionExpression(expr)) && expr.name)
-                    name = expr.name.text;
-                else
-                    name = ANON_DEFAULT; // `export default Joi.object({...})`, `{...}`, `() => …`
+                name = ts.isIdentifier(expr) ? expr.text : anonOrNamedExpressionDefaultName(expr);
                 break;
             }
             // `export default class X {}` / `export default function X() {}`
@@ -770,8 +996,7 @@ function resolveConnectionsLocally(sourceNodeId, sourceFilePath, candidateNodes,
         return [];
     }
     const fileContent = fs.readFileSync(sourceFilePath, 'utf-8');
-    const ext = path.extname(sourceFilePath).toLowerCase();
-    const isTsOrJs = ['.ts', '.tsx', '.js', '.jsx'].includes(ext);
+    const isTsOrJs = isAstParseable(sourceFilePath);
     const tsPaths = loadTsPaths(repoRoot);
     let referencedNames = new Set();
     let thisMembers = new Set();
@@ -822,6 +1047,8 @@ function resolveConnectionsLocally(sourceNodeId, sourceFilePath, candidateNodes,
             const paths = resolveImportToPaths(imp.moduleSpecifier, sourceDir, repoRoot, tsPaths);
             const barrels = [];
             for (const p of paths) {
+                /* istanbul ignore if -- defensive: see the matching guard in resolveToExistingFile —
+                   resolveImportToPaths never pushes a falsy path. */
                 if (!p)
                     continue;
                 const rx = getBarrelReexports(p);
@@ -889,8 +1116,11 @@ function resolveConnectionsLocally(sourceNodeId, sourceFilePath, candidateNodes,
                 connections.add(targetNode.id);
                 continue;
             }
+            // Check the target's own name AND any alias it's exported under (e.g. an RTK-generated
+            // hook name for its endpoint) — one implementation, several referenceable handles.
             const nameToCheck = memberName || symbolName;
-            if (referencedNames.has(nameToCheck)) {
+            const targetNames = [nameToCheck, ...(targetNode.aliases ?? [])];
+            if (targetNames.some(n => referencedNames.has(n))) {
                 connections.add(targetNode.id);
             }
             continue;
@@ -973,8 +1203,13 @@ function resolveConnectionsLocally(sourceNodeId, sourceFilePath, candidateNodes,
                 // matching a `Utils.formatDate` method) — a pure false positive.
             }
             else {
-                // Top-level function/variable imported & referenced
-                if (importedAsNames.includes(symbolName) && referencedNames.has(symbolName)) {
+                // Top-level function/variable imported & referenced — check the target's own declared
+                // name AND any alias it's exported under. This is the RTK fix: a caller importing
+                // `useGetAdminOrdersQuery` (generated by createApi, never a name that appears in the
+                // endpoint's own declaration) still resolves to the `getAdminOrders` endpoint node, as
+                // long as that alias was attached to it (see the RTK detector / Phase C).
+                const targetNames = [symbolName, ...(targetNode.aliases ?? [])];
+                if (targetNames.some(n => importedAsNames.includes(n) && referencedNames.has(n))) {
                     connections.add(targetNode.id);
                     continue;
                 }
@@ -1007,10 +1242,15 @@ function resolveConnectionsLocally(sourceNodeId, sourceFilePath, candidateNodes,
         // default-imported and its alias is referenced here, and the file is small enough that
         // its default export is unambiguous, link it. The node-count gate keeps this from
         // re-exploding on large files (whose default export is virtually always named anyway).
+        // `?? 99` is defensive only: `nodesPerFile` is built from `candidateNodes`, which always
+        // includes `targetNode` itself, so its own file is always present with count >= 1; the
+        // `?? 99` fallback can never actually be taken.
+        /* istanbul ignore next */
+        const targetFileNodeCount = nodesPerFile.get(normFile(targetNode.file_path)) ?? 99;
         if (isImported &&
             importedAsDefaultNames.some(alias => referencedNames.has(alias)) &&
             getDefaultExportName(targetNode.file_path) === ANON_DEFAULT &&
-            (nodesPerFile.get(normFile(targetNode.file_path)) ?? 99) <= 3) {
+            targetFileNodeCount <= 3) {
             connections.add(targetNode.id);
             continue;
         }
@@ -1049,13 +1289,13 @@ function resolveConnectionsLocally(sourceNodeId, sourceFilePath, candidateNodes,
     return Array.from(connections);
 }
 /**
- * Derive a node's identity/type/code directly from its declaration in a file — deterministic,
- * no LLM. Used by `--fill-missing` to create nodes that Phase-1 extraction skipped. Returns
- * null when the file isn't TS/JS or the symbol can't be located.
+ * Locate a symbol's span in a file via the AST. This is the write-side counterpart to
+ * `extractNodeFromFile`: same lookup, but it also surfaces the offsets, so a caller can
+ * replace the symbol without the caller ever having to read the file or reproduce its
+ * text byte-exactly.
  */
-function extractNodeFromFile(filePath, symbolName) {
-    const ext = path.extname(filePath).toLowerCase();
-    if (!['.ts', '.tsx', '.js', '.jsx'].includes(ext))
+function locateNodeInFile(filePath, symbolName) {
+    if (!isAstParseable(filePath))
         return null;
     try {
         const sf = getSourceFile(filePath);
@@ -1064,16 +1304,396 @@ function extractNodeFromFile(filePath, symbolName) {
         const node = findNodeInAst(sf, className, symbolName);
         if (!node)
             return null;
+        const start = node.getStart(sf); // skips leading trivia → a JSDoc block above stays put
+        const end = node.getEnd();
         const code = node.getText(sf);
+        const full = sf.getFullText();
+        // Indent is only meaningful when nothing but whitespace precedes the symbol on its line;
+        // for an inline symbol (`const x = function () {}`) there is no indent to re-apply.
+        const lineStart = full.lastIndexOf('\n', start - 1) + 1;
+        const prefix = full.slice(lineStart, start);
         return {
             name: parts[parts.length - 1] || symbolName,
             type: astBaseType(node),
             signature: code.split('\n')[0].slice(0, 200),
-            codeSnapshot: code
+            codeSnapshot: code,
+            start,
+            end,
+            startLine: sf.getLineAndCharacterOfPosition(start).line + 1,
+            endLine: sf.getLineAndCharacterOfPosition(end).line + 1,
+            indent: /^[ \t]*$/.test(prefix) ? prefix : ''
         };
     }
     catch {
         return null;
     }
 }
+function extractNodeFromFile(filePath, symbolName) {
+    const loc = locateNodeInFile(filePath, symbolName);
+    if (!loc)
+        return null;
+    const { name, type, signature, codeSnapshot } = loc;
+    return { name, type, signature, codeSnapshot };
+}
+/**
+ * The name a declaration contributes to a node id, or null if it isn't one the graph models.
+ *
+ * Mirrors the shapes `findNodeInAst` resolves in the opposite direction, including the
+ * object-literal factory form (`Page({ onShopLook() {} })` → `Page.onShopLook`) used by
+ * mini-program style frameworks.
+ */
+function declarationNameOf(node) {
+    const plain = (n) => n.name && (ts.isIdentifier(n.name) || ts.isStringLiteral(n.name)) ? n.name.text : null;
+    // Nothing declared inside a function body is a graph entity: a local `const`, a helper
+    // function, an object literal built in a return statement. Only declarations reachable from
+    // the file without passing through a function qualify — which still admits class members and
+    // factory-call members, since a class or a call is not a function body.
+    for (let p = node.parent; p; p = p.parent) {
+        if (ts.isSourceFile(p))
+            break;
+        if (isFunctionLikeScope(p))
+            return null;
+    }
+    if (ts.isFunctionDeclaration(node) || ts.isClassDeclaration(node) ||
+        ts.isInterfaceDeclaration(node) || ts.isTypeAliasDeclaration(node) ||
+        ts.isEnumDeclaration(node)) {
+        const n = plain(node);
+        return n ? { name: n, qualified: n } : null;
+    }
+    // Class members carry their class name. A method may also live in an object literal rather
+    // than a class, so membership is decided by the parent, not by the node kind.
+    if (ts.isMethodDeclaration(node) || ts.isPropertyDeclaration(node) ||
+        ts.isGetAccessorDeclaration(node) || ts.isSetAccessorDeclaration(node) ||
+        ts.isConstructorDeclaration(node) || ts.isPropertyAssignment(node) ||
+        ts.isShorthandPropertyAssignment(node)) {
+        const member = ts.isConstructorDeclaration(node) ? 'constructor' : plain(node);
+        if (!member)
+            return null;
+        if (node.parent && ts.isClassLike(node.parent) && node.parent.name) {
+            return { name: member, qualified: `${node.parent.name.text}.${member}` };
+        }
+        // A plain key is only a symbol when its object is itself named — `Page({ data: {...} })`
+        // or `const api = { timeout: 30 }`. Keys nested deeper (`data: { n: 1 }` → `n`) are that
+        // object's CONTENTS, not entities of their own: the graph models `Page.data`, never
+        // `Page.n`. Methods are exempt — a function nested at any depth is still a real symbol.
+        if (ts.isPropertyAssignment(node) || ts.isShorthandPropertyAssignment(node)) {
+            /* istanbul ignore next -- defensive: by grammar, a PropertyAssignment/
+               ShorthandPropertyAssignment's parent is always its containing ObjectLiteralExpression, so
+               the `: undefined` (not-an-object-literal-parent) side of this ternary is unreachable. */
+            const owner = node.parent && ts.isObjectLiteralExpression(node.parent) ? node.parent.parent : undefined;
+            const namedObject = owner && (ts.isCallExpression(owner) || ts.isVariableDeclaration(owner));
+            if (!namedObject)
+                return null;
+        }
+        // Otherwise it sits inside an object literal. Walk out to whatever names that object:
+        // a factory call (`Page({...})` → `Page.onShopLook`) or a variable (`const api = {...}`).
+        for (let cur = node.parent; cur; cur = cur.parent) {
+            if (ts.isCallExpression(cur) && ts.isIdentifier(cur.expression)) {
+                return { name: member, qualified: `${cur.expression.text}.${member}` };
+            }
+            if (ts.isVariableDeclaration(cur) && cur.name && ts.isIdentifier(cur.name)) {
+                return { name: member, qualified: `${cur.name.text}.${member}` };
+            }
+            if (ts.isClassLike(cur) && cur.name) {
+                return { name: member, qualified: `${cur.name.text}.${member}` };
+            }
+        }
+        return { name: member, qualified: member };
+    }
+    if (ts.isVariableDeclaration(node)) {
+        const n = plain(node);
+        return n ? { name: n, qualified: n } : null;
+    }
+    return null;
+}
+/** Every declaration whose span overlaps one of `ranges`, innermost-first ordering not implied. */
+function declarationsOverlapping(sf, ranges) {
+    // A zero-width range (a pure deletion) still has to intersect something, so give it width 1.
+    const spans = ranges.map(r => ({ start: r.start, end: Math.max(r.end, r.start + 1) }));
+    const hits = [];
+    const visit = (n) => {
+        const start = n.getStart(sf);
+        const end = n.getEnd();
+        if (!spans.some(s => start < s.end && s.start < end))
+            return; // disjoint — skip its subtree
+        const named = declarationNameOf(n);
+        if (named)
+            hits.push({ node: n, name: named.name, qualified: named.qualified, start, end });
+        ts.forEachChild(n, visit);
+    };
+    ts.forEachChild(sf, visit);
+    return hits;
+}
+/**
+ * Whether a declaration is part of the file's export surface — directly (`export function foo`,
+ * `export const foo = ...`), via a separate `export { foo }` statement, or transitively (a method
+ * of an exported class, a member of an object literal assigned to an exported variable). This is
+ * the auto-accept signal for {@link enumerateFileCandidates}: an exported, named declaration is
+ * unambiguously a real entity — nothing about its EXISTENCE is a judgment call, only an
+ * unexported/anonymous one needs curation.
+ */
+function isNodeExported(node, sourceFile) {
+    // Class/object-literal members inherit their container's export status — a method isn't
+    // separately "exported", it's reachable (or not) through whatever names its class/object.
+    if (ts.isMethodDeclaration(node) || ts.isPropertyDeclaration(node) || ts.isGetAccessorDeclaration(node) ||
+        ts.isSetAccessorDeclaration(node) || ts.isConstructorDeclaration(node) ||
+        ts.isPropertyAssignment(node) || ts.isShorthandPropertyAssignment(node)) {
+        if (node.parent && ts.isClassLike(node.parent))
+            return isNodeExported(node.parent, sourceFile);
+        for (let cur = node.parent; cur; cur = cur.parent) {
+            if (ts.isVariableStatement(cur))
+                return isNodeExported(cur, sourceFile);
+            if (ts.isSourceFile(cur))
+                break;
+        }
+        return false;
+    }
+    const hasExportModifier = (n) => !!n.modifiers?.some(m => m.kind === ts.SyntaxKind.ExportKeyword);
+    // `export const foo = ...`: the `export` modifier sits on the enclosing VariableStatement, not
+    // on the VariableDeclaration itself.
+    const modifierHost = ts.isVariableDeclaration(node) && node.parent && ts.isVariableDeclarationList(node.parent)
+        ? node.parent.parent
+        : node;
+    if (hasExportModifier(modifierHost))
+        return true;
+    // `export { foo, bar }` as its own statement elsewhere in the file, not a modifier at all.
+    const declaredName = (ts.isVariableDeclaration(node) && node.name && ts.isIdentifier(node.name)) ? node.name.text :
+        (node.name && ts.isIdentifier(node.name))
+            ? node.name.text
+            : null;
+    if (!declaredName)
+        return false;
+    for (const stmt of sourceFile.statements) {
+        if (ts.isExportDeclaration(stmt) && !stmt.moduleSpecifier &&
+            stmt.exportClause && ts.isNamedExports(stmt.exportClause)) {
+            if (stmt.exportClause.elements.some(el => el.name.text === declaredName || el.propertyName?.text === declaredName)) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+/**
+ * Enumerates every graph-eligible declaration in a file, deterministically — no LLM, so nothing
+ * gets silently missed the way the old whole-file-to-an-LLM extraction could. A named, EXPORTED
+ * declaration (`isExported:true`) is unambiguous: whether it "counts" as a node requires no
+ * judgment, so the caller can auto-accept it with zero LLM turns. Everything else — unexported
+ * helpers, anonymous default exports, tiny inline callbacks, object-literal factory members whose
+ * significance is genuinely a judgment call — is still enumerated (nothing is dropped silently)
+ * but flagged `isExported:false`, so an agentic curation pass only has to spend turns on THOSE.
+ */
+function enumerateFileCandidates(filePath) {
+    if (!isAstParseable(filePath))
+        return [];
+    let sourceFile;
+    try {
+        sourceFile = getSourceFile(filePath);
+    }
+    catch {
+        return [];
+    }
+    const fullText = sourceFile.getFullText();
+    const hits = declarationsOverlapping(sourceFile, [{ start: 0, end: fullText.length }]);
+    // A single declaration can surface more than once under different matching rules (e.g. a
+    // property assignment's own span, and — if it were itself a match — an initializer nested
+    // inside it). Keep the FIRST hit per qualified name: `declarationsOverlapping` walks
+    // parent-before-child, so the first hit is always the outermost, correct one.
+    const byQualified = new Map();
+    for (const h of hits) {
+        if (!byQualified.has(h.qualified))
+            byQualified.set(h.qualified, h);
+    }
+    const results = [];
+    for (const h of byQualified.values()) {
+        const code = h.node.getText(sourceFile);
+        results.push({
+            qualified: h.qualified,
+            name: h.name,
+            type: astBaseType(h.node),
+            signature: code.split('\n')[0].slice(0, 200),
+            codeSnapshot: code,
+            startLine: sourceFile.getLineAndCharacterOfPosition(h.start).line + 1,
+            endLine: sourceFile.getLineAndCharacterOfPosition(h.end).line + 1,
+            isExported: isNodeExported(h.node, sourceFile)
+        });
+    }
+    // RTK Query endpoints live inside a function body (`endpoints: (builder) => ({...})`), so the
+    // general declaration walk above structurally cannot see them — see `findRtkEndpointMatches`.
+    // Folded in here (not called separately by every consumer) so `enumerateFileCandidates` really
+    // is the complete candidate list for a file, RTK or not.
+    for (const rtkNode of detectRtkEndpointNodes(filePath)) {
+        if (!byQualified.has(rtkNode.qualified))
+            results.push(rtkNode);
+    }
+    return results;
+}
+/**
+ * Every OTHER top-level declaration in a file — functions, classes, consts, types, interfaces —
+ * the "what else is here" a raw file read used to be the only way to answer. Reuses
+ * {@link enumerateFileCandidates}'s own declaration walk (`declarationsOverlapping` /
+ * `astBaseType` / `isNodeExported`), but deliberately does NOT call `node.getText()` per hit the
+ * way that function does: `enumerateFileCandidates` materializes each declaration's FULL source
+ * just to build a one-line signature and then discards it, which is an extra copy of potentially
+ * the whole file in string allocations — on every single `get_node_code` call, this is squarely
+ * the wrong trade. A short slice of the already-loaded full text plus a line split gets the same
+ * signature far cheaper. The parse itself is free either way: `getSourceFile` is mtime-cached
+ * ({@link getSourceFile}), and by the time `get_node_code` calls this the file has usually already
+ * been parsed once this same request via `getLiveCode`/`extractLiveCode`.
+ */
+function outlineFile(filePath) {
+    if (!isAstParseable(filePath))
+        return [];
+    let sourceFile;
+    try {
+        sourceFile = getSourceFile(filePath);
+    }
+    catch {
+        return [];
+    }
+    const fullText = sourceFile.getFullText();
+    const hits = declarationsOverlapping(sourceFile, [{ start: 0, end: fullText.length }]);
+    // Same "keep the first (outermost) hit per qualified name" rule as enumerateFileCandidates —
+    // declarationsOverlapping walks parent-before-child, so the first hit is always correct.
+    const byQualified = new Map();
+    for (const h of hits) {
+        if (!byQualified.has(h.qualified))
+            byQualified.set(h.qualified, h);
+    }
+    const results = [];
+    for (const h of byQualified.values()) {
+        /* istanbul ignore next -- the `|| null` arm is unreachable: `declarationsOverlapping` takes
+           each hit's start from `node.getStart(sf)`, which skips leading trivia, so the slice always
+           begins at a real token character and its first line is never the empty string. Kept as a
+           type-level guarantee that `signature` is `string | null` rather than `string | undefined`. */
+        const signature = fullText.slice(h.start, h.start + 200).split('\n')[0] || null;
+        results.push({
+            qualified: h.qualified,
+            name: h.name,
+            type: astBaseType(h.node),
+            signature,
+            start_line: sourceFile.getLineAndCharacterOfPosition(h.start).line + 1,
+            end_line: sourceFile.getLineAndCharacterOfPosition(h.end).line + 1,
+            exported: isNodeExported(h.node, sourceFile)
+        });
+    }
+    // RTK Query endpoints live inside a function body and the general walk above structurally
+    // cannot see them (see detectRtkEndpointNodes) — folded in here so the outline is genuinely
+    // complete, RTK or not, same as enumerateFileCandidates. Its own codeSnapshot is dropped; these
+    // are individual endpoint bodies (small), not a whole-file cost, but the outline never carries
+    // code regardless of source.
+    for (const rtk of detectRtkEndpointNodes(filePath)) {
+        if (byQualified.has(rtk.qualified))
+            continue;
+        results.push({
+            qualified: rtk.qualified,
+            name: rtk.name,
+            type: rtk.type,
+            signature: rtk.signature,
+            start_line: rtk.startLine,
+            end_line: rtk.endLine,
+            exported: rtk.isExported
+        });
+    }
+    return results;
+}
+/**
+ * A file's own import list — file-path entry point for {@link getFileImports} (which needs an
+ * already-parsed `ts.SourceFile`). Used by the Phase D curation agent's `get_file_imports` tool:
+ * whether an ambiguous candidate is worth keeping is often decided by whether it's ever imported
+ * anywhere, and the file's OWN imports are the cheap first signal (e.g. a candidate that mirrors
+ * a re-exported name, or that only makes sense alongside a specific imported dependency).
+ */
+function listFileImports(filePath) {
+    if (!isAstParseable(filePath))
+        return [];
+    try {
+        return getFileImports(getSourceFile(filePath));
+    }
+    catch {
+        return [];
+    }
+}
+/** A symbol's current source in `sf`, or null when it isn't there. */
+function codeOfSymbol(sf, symbolName) {
+    const parts = symbolName.split('.');
+    const className = parts.length === 2 ? parts[0] : undefined;
+    const node = findNodeInAst(sf, className, symbolName);
+    return node ? node.getText(sf) : null;
+}
+/**
+ * Work out which symbols an edit actually changed, from where the edit landed.
+ *
+ * Position beats name matching: a span is unambiguous where a name is not (fifty classes can
+ * each have a `run`), it survives the symbol being renamed by the very edit being traced, and
+ * it finds code that did not exist until this write.
+ *
+ * Three passes, each removing a specific kind of wrong answer:
+ *   1. OVERLAP — every declaration intersecting the written span. A point would not do: text
+ *      appended after an anchor (`}` → `}\n\nfunction added() {}`) begins inside the PREVIOUS
+ *      function, so a point attributes the new function to its neighbour.
+ *   2. INNERMOST — drop any declaration that contains another hit, so inserting a method
+ *      reports the method and not its whole class.
+ *   3. CHANGED — compare each survivor against `beforeContent` and keep only what actually
+ *      differs. Overlap alone over-reports: the anchor's own function is intersected by an
+ *      append yet is untouched by it, and re-recording it would invent history for a change
+ *      that never happened. A symbol absent from `beforeContent` is new.
+ *
+ * Symbols already in the graph are matched by span against their RECORDED ids, never by
+ * re-deriving a name — a container name may have been chosen at index time and be absent from
+ * the source (`Component({...})` recorded as `ProductImageGalleryComponent`).
+ *
+ * `knownSymbols` should be the graph's nodes for this file; empty is fine, everything is then
+ * reported as new. An edit touching no symbol at all (an import, markup, a config value) yields
+ * nothing — a normal outcome, not an error.
+ */
+function findTouchedSymbols(filePath, ranges, knownSymbols = [], beforeContent) {
+    if (!isAstParseable(filePath) || !ranges.length)
+        return [];
+    try {
+        const sf = getSourceFile(filePath);
+        const before = beforeContent === undefined ? null : parseText(filePath, beforeContent);
+        // 1. overlap
+        const hits = declarationsOverlapping(sf, ranges);
+        if (!hits.length)
+            return [];
+        // Prefer the graph's own id wherever a hit is the same span as a node it already knows.
+        const byId = new Map();
+        for (const k of knownSymbols) {
+            const loc = locateNodeInFile(filePath, k.symbolName);
+            if (loc)
+                byId.set(`${loc.start}-${loc.end}`, k);
+        }
+        // 2. innermost: discard anything that strictly contains another hit
+        const innermost = hits.filter(h => !hits.some(o => o !== h && o.start >= h.start && o.end <= h.end && (o.end - o.start) < (h.end - h.start)));
+        // 3. changed-only
+        const out = new Map();
+        for (const h of innermost) {
+            const known = byId.get(`${h.start}-${h.end}`);
+            const symbolName = known ? known.symbolName : h.qualified;
+            const newCode = h.node.getText(sf);
+            const oldCode = before ? codeOfSymbol(before, symbolName) : null;
+            if (oldCode !== null && oldCode === newCode)
+                continue; // intersected but untouched
+            const key = known ? known.id : symbolName;
+            if (out.has(key))
+                continue;
+            out.set(key, {
+                node_id: known?.id,
+                symbolName,
+                name: h.name,
+                type: astBaseType(h.node),
+                signature: newCode.split('\n')[0].slice(0, 200),
+                codeSnapshot: newCode,
+                codeBefore: oldCode,
+                startLine: sf.getLineAndCharacterOfPosition(h.start).line + 1,
+                endLine: sf.getLineAndCharacterOfPosition(h.end).line + 1,
+                isNew: !known
+            });
+        }
+        return Array.from(out.values());
+    }
+    catch {
+        return [];
+    }
+}
 //# sourceMappingURL=ast.js.map