@ltm-alpha/alpha-cs 1.6.0

package/dist/graph/queries.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Graph Query Functions
+ *
+ * Higher-level query functions built on top of traversal algorithms.
+ */
+import { Node, Context, Subgraph } from '../types';
+import { QueryBuilder } from '../db/queries';
+import { GraphTraverser } from './traversal';
+/**
+ * Graph query manager for complex queries
+ */
+export declare class GraphQueryManager {
+    private queries;
+    private traverser;
+    constructor(queries: QueryBuilder);
+    /**
+     * Get full context for a node
+     *
+     * Returns the focal node along with its ancestors, children,
+     * and both incoming and outgoing references.
+     *
+     * @param nodeId - ID of the focal node
+     * @returns Context object with all related information
+     */
+    getContext(nodeId: string): Context;
+    /**
+     * Get dependencies of a file
+     *
+     * Returns all files that this file imports from.
+     *
+     * @param filePath - Path to the file
+     * @returns Array of file paths this file depends on
+     */
+    getFileDependencies(filePath: string): string[];
+    /**
+     * Get dependents of a file
+     *
+     * Returns all files that import from this file.
+     *
+     * @param filePath - Path to the file
+     * @returns Array of file paths that depend on this file
+     */
+    getFileDependents(filePath: string): string[];
+    /**
+     * Get all symbols exported by a file
+     *
+     * @param filePath - Path to the file
+     * @returns Array of exported nodes
+     */
+    getExportedSymbols(filePath: string): Node[];
+    /**
+     * Find symbols by qualified name pattern
+     *
+     * @param pattern - Pattern to match (supports * wildcard)
+     * @returns Array of matching nodes
+     */
+    findByQualifiedName(pattern: string): Node[];
+    /**
+     * Get the module/package structure
+     *
+     * Returns a tree structure of files organized by directory.
+     *
+     * @returns Map of directory paths to contained files
+     */
+    getModuleStructure(): Map<string, string[]>;
+    /**
+     * Find circular dependencies in the graph
+     *
+     * @returns Array of cycles, each cycle is an array of node IDs
+     */
+    findCircularDependencies(): string[][];
+    /**
+     * Get complexity metrics for a node
+     *
+     * @param nodeId - ID of the node
+     * @returns Object containing various complexity metrics
+     */
+    getNodeMetrics(nodeId: string): {
+        incomingEdgeCount: number;
+        outgoingEdgeCount: number;
+        callCount: number;
+        callerCount: number;
+        childCount: number;
+        depth: number;
+    };
+    /**
+     * Find dead code (nodes with no incoming references)
+     *
+     * @param kinds - Node kinds to check (default: functions, methods, classes)
+     * @returns Array of unreferenced nodes
+     */
+    findDeadCode(kinds?: Node['kind'][]): Node[];
+    /**
+     * Get subgraph containing nodes matching a filter
+     *
+     * @param filter - Filter function to select nodes
+     * @param includeEdges - Whether to include edges between matching nodes
+     * @returns Subgraph containing matching nodes
+     */
+    getFilteredSubgraph(filter: (node: Node) => boolean, includeEdges?: boolean): Subgraph;
+    /**
+     * Access the underlying traverser for direct traversal operations
+     */
+    getTraverser(): GraphTraverser;
+}
+//# sourceMappingURL=queries.d.ts.map

package/dist/graph/queries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queries.d.ts","sourceRoot":"","sources":["../../src/graph/queries.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,IAAI,EAAQ,OAAO,EAAE,QAAQ,EAAY,MAAM,UAAU,CAAC;AACnE,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE7C;;GAEG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,OAAO,CAAe;IAC9B,OAAO,CAAC,SAAS,CAAiB;gBAEtB,OAAO,EAAE,YAAY;IAKjC;;;;;;;;OAQG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IA8EnC;;;;;;;OAOG;IACH,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE;IAQ/C;;;;;;;OAOG;IACH,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE;IAW7C;;;;;OAKG;IACH,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,EAAE;IAK5C;;;;;OAKG;IACH,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,EAAE;IAmC5C;;;;;;OAMG;IACH,kBAAkB,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC;IAiB3C;;;;OAIG;IACH,wBAAwB,IAAI,MAAM,EAAE,EAAE;IAwCtC;;;;;OAKG;IACH,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG;QAC9B,iBAAiB,EAAE,MAAM,CAAC;QAC1B,iBAAiB,EAAE,MAAM,CAAC;QAC1B,SAAS,EAAE,MAAM,CAAC;QAClB,WAAW,EAAE,MAAM,CAAC;QACpB,UAAU,EAAE,MAAM,CAAC;QACnB,KAAK,EAAE,MAAM,CAAC;KACf;IAoBD;;;;;OAKG;IACH,YAAY,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,GAAG,IAAI,EAAE;IA0B5C;;;;;;OAMG;IACH,mBAAmB,CACjB,MAAM,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,EAC/B,YAAY,GAAE,OAAc,GAC3B,QAAQ;IAiDX;;OAEG;IACH,YAAY,IAAI,cAAc;CAG/B"}

package/dist/graph/queries.js

@@ -0,0 +1,341 @@
+"use strict";
+/**
+ * Graph Query Functions
+ *
+ * Higher-level query functions built on top of traversal algorithms.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GraphQueryManager = void 0;
+const traversal_1 = require("./traversal");
+/**
+ * Graph query manager for complex queries
+ */
+class GraphQueryManager {
+    queries;
+    traverser;
+    constructor(queries) {
+        this.queries = queries;
+        this.traverser = new traversal_1.GraphTraverser(queries);
+    }
+    /**
+     * Get full context for a node
+     *
+     * Returns the focal node along with its ancestors, children,
+     * and both incoming and outgoing references.
+     *
+     * @param nodeId - ID of the focal node
+     * @returns Context object with all related information
+     */
+    getContext(nodeId) {
+        const focal = this.queries.getNodeById(nodeId);
+        if (!focal) {
+            throw new Error(`Node not found: ${nodeId}`);
+        }
+        // Get ancestors (containment hierarchy)
+        const ancestors = this.traverser.getAncestors(nodeId);
+        // Get children
+        const children = this.traverser.getChildren(nodeId);
+        // Get incoming references (things that reference this node)
+        const incomingEdges = this.queries.getIncomingEdges(nodeId);
+        const incomingRefs = [];
+        for (const edge of incomingEdges) {
+            // Skip containment edges (already in ancestors)
+            if (edge.kind === 'contains') {
+                continue;
+            }
+            const node = this.queries.getNodeById(edge.source);
+            if (node) {
+                incomingRefs.push({ node, edge });
+            }
+        }
+        // Get outgoing references (things this node references)
+        const outgoingEdges = this.queries.getOutgoingEdges(nodeId);
+        const outgoingRefs = [];
+        for (const edge of outgoingEdges) {
+            // Skip containment edges (already in children)
+            if (edge.kind === 'contains') {
+                continue;
+            }
+            const node = this.queries.getNodeById(edge.target);
+            if (node) {
+                outgoingRefs.push({ node, edge });
+            }
+        }
+        // Get type information (type_of, returns edges)
+        const types = [];
+        const typeEdgeKinds = ['type_of', 'returns'];
+        for (const kind of typeEdgeKinds) {
+            const typeEdges = this.queries.getOutgoingEdges(nodeId, [kind]);
+            for (const edge of typeEdges) {
+                const typeNode = this.queries.getNodeById(edge.target);
+                if (typeNode && !types.some((t) => t.id === typeNode.id)) {
+                    types.push(typeNode);
+                }
+            }
+        }
+        // Get relevant imports
+        const imports = [];
+        const fileNode = ancestors.find((a) => a.kind === 'file');
+        if (fileNode) {
+            const importEdges = this.queries.getOutgoingEdges(fileNode.id, ['imports']);
+            for (const edge of importEdges) {
+                const importNode = this.queries.getNodeById(edge.target);
+                if (importNode) {
+                    imports.push(importNode);
+                }
+            }
+        }
+        return {
+            focal,
+            ancestors,
+            children,
+            incomingRefs,
+            outgoingRefs,
+            types,
+            imports,
+        };
+    }
+    /**
+     * Get dependencies of a file
+     *
+     * Returns all files that this file imports from.
+     *
+     * @param filePath - Path to the file
+     * @returns Array of file paths this file depends on
+     */
+    getFileDependencies(filePath) {
+        // Follow the symbol-level cross-file edge graph, not just `imports`:
+        // an `imports` edge here points from a file to its own local import
+        // declarations (same-file), so the actual cross-file dependencies live in
+        // the resolved calls/references/instantiates/extends/... edges.
+        return this.queries.getDependencyFilePaths(filePath);
+    }
+    /**
+     * Get dependents of a file
+     *
+     * Returns all files that import from this file.
+     *
+     * @param filePath - Path to the file
+     * @returns Array of file paths that depend on this file
+     */
+    getFileDependents(filePath) {
+        // Previously this only followed `imports` edges into the file node or its
+        // exported symbols and returned 0 dependents for *every* file — because an
+        // `imports` edge here connects a file to its own local import declarations
+        // (always same-file), never to the providing file. The real cross-file
+        // dependency signal is the resolved symbol graph (calls/references/
+        // instantiates/extends/implements/...), which is what blast-radius /
+        // `affected` need. Delegate to the indexed projection of that graph.
+        return this.queries.getDependentFilePaths(filePath);
+    }
+    /**
+     * Get all symbols exported by a file
+     *
+     * @param filePath - Path to the file
+     * @returns Array of exported nodes
+     */
+    getExportedSymbols(filePath) {
+        const nodes = this.queries.getNodesByFile(filePath);
+        return nodes.filter((n) => n.isExported);
+    }
+    /**
+     * Find symbols by qualified name pattern
+     *
+     * @param pattern - Pattern to match (supports * wildcard)
+     * @returns Array of matching nodes
+     */
+    findByQualifiedName(pattern) {
+        // Convert glob pattern to regex
+        const regexPattern = pattern
+            .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+            .replace(/\*/g, '.*')
+            .replace(/\?/g, '.');
+        const regex = new RegExp(`^${regexPattern}$`);
+        // This is inefficient for large graphs - would need FTS index on qualified_name
+        // For now, use kind-based filtering if possible
+        const allNodes = [];
+        const kinds = [
+            'class',
+            'union',
+            'function',
+            'method',
+            'interface',
+            'type_alias',
+            'variable',
+            'constant',
+        ];
+        for (const kind of kinds) {
+            const nodes = this.queries.getNodesByKind(kind);
+            for (const node of nodes) {
+                if (regex.test(node.qualifiedName)) {
+                    allNodes.push(node);
+                }
+            }
+        }
+        return allNodes;
+    }
+    /**
+     * Get the module/package structure
+     *
+     * Returns a tree structure of files organized by directory.
+     *
+     * @returns Map of directory paths to contained files
+     */
+    getModuleStructure() {
+        const files = this.queries.getAllFiles();
+        const structure = new Map();
+        for (const file of files) {
+            const parts = file.path.split('/');
+            const dir = parts.slice(0, -1).join('/') || '.';
+            if (!structure.has(dir)) {
+                structure.set(dir, []);
+            }
+            structure.get(dir).push(file.path);
+        }
+        return structure;
+    }
+    /**
+     * Find circular dependencies in the graph
+     *
+     * @returns Array of cycles, each cycle is an array of node IDs
+     */
+    findCircularDependencies() {
+        const files = this.queries.getAllFiles();
+        const cycles = [];
+        const visited = new Set();
+        const recursionStack = new Set();
+        const dfs = (filePath, path) => {
+            if (recursionStack.has(filePath)) {
+                // Found a cycle
+                const cycleStart = path.indexOf(filePath);
+                if (cycleStart !== -1) {
+                    cycles.push(path.slice(cycleStart));
+                }
+                return;
+            }
+            if (visited.has(filePath)) {
+                return;
+            }
+            visited.add(filePath);
+            recursionStack.add(filePath);
+            const dependencies = this.getFileDependencies(filePath);
+            for (const dep of dependencies) {
+                dfs(dep, [...path, filePath]);
+            }
+            recursionStack.delete(filePath);
+        };
+        for (const file of files) {
+            if (!visited.has(file.path)) {
+                dfs(file.path, []);
+            }
+        }
+        return cycles;
+    }
+    /**
+     * Get complexity metrics for a node
+     *
+     * @param nodeId - ID of the node
+     * @returns Object containing various complexity metrics
+     */
+    getNodeMetrics(nodeId) {
+        const incomingEdges = this.queries.getIncomingEdges(nodeId);
+        const outgoingEdges = this.queries.getOutgoingEdges(nodeId);
+        const callEdges = outgoingEdges.filter((e) => e.kind === 'calls');
+        const callerEdges = incomingEdges.filter((e) => e.kind === 'calls');
+        const containsEdges = outgoingEdges.filter((e) => e.kind === 'contains');
+        const ancestors = this.traverser.getAncestors(nodeId);
+        return {
+            incomingEdgeCount: incomingEdges.length,
+            outgoingEdgeCount: outgoingEdges.length,
+            callCount: callEdges.length,
+            callerCount: callerEdges.length,
+            childCount: containsEdges.length,
+            depth: ancestors.length,
+        };
+    }
+    /**
+     * Find dead code (nodes with no incoming references)
+     *
+     * @param kinds - Node kinds to check (default: functions, methods, classes)
+     * @returns Array of unreferenced nodes
+     */
+    findDeadCode(kinds) {
+        const targetKinds = kinds || ['function', 'method', 'class'];
+        const deadCode = [];
+        for (const kind of targetKinds) {
+            const nodes = this.queries.getNodesByKind(kind);
+            for (const node of nodes) {
+                // Skip exported symbols (they may be used externally)
+                if (node.isExported) {
+                    continue;
+                }
+                const incomingEdges = this.queries.getIncomingEdges(node.id);
+                // Filter out containment edges
+                const references = incomingEdges.filter((e) => e.kind !== 'contains');
+                if (references.length === 0) {
+                    deadCode.push(node);
+                }
+            }
+        }
+        return deadCode;
+    }
+    /**
+     * Get subgraph containing nodes matching a filter
+     *
+     * @param filter - Filter function to select nodes
+     * @param includeEdges - Whether to include edges between matching nodes
+     * @returns Subgraph containing matching nodes
+     */
+    getFilteredSubgraph(filter, includeEdges = true) {
+        const nodes = new Map();
+        const edges = [];
+        // Get all nodes of common kinds
+        const kinds = [
+            'file',
+            'module',
+            'class',
+            'struct',
+            'union',
+            'interface',
+            'trait',
+            'function',
+            'method',
+            'variable',
+            'constant',
+            'enum',
+            'type_alias',
+        ];
+        for (const kind of kinds) {
+            const kindNodes = this.queries.getNodesByKind(kind);
+            for (const node of kindNodes) {
+                if (filter(node)) {
+                    nodes.set(node.id, node);
+                }
+            }
+        }
+        // Include edges between matching nodes
+        if (includeEdges) {
+            for (const nodeId of nodes.keys()) {
+                const outgoing = this.queries.getOutgoingEdges(nodeId);
+                for (const edge of outgoing) {
+                    if (nodes.has(edge.target)) {
+                        edges.push(edge);
+                    }
+                }
+            }
+        }
+        return {
+            nodes,
+            edges,
+            roots: [],
+        };
+    }
+    /**
+     * Access the underlying traverser for direct traversal operations
+     */
+    getTraverser() {
+        return this.traverser;
+    }
+}
+exports.GraphQueryManager = GraphQueryManager;
+//# sourceMappingURL=queries.js.map

package/dist/graph/queries.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queries.js","sourceRoot":"","sources":["../../src/graph/queries.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;AAIH,2CAA6C;AAE7C;;GAEG;AACH,MAAa,iBAAiB;IACpB,OAAO,CAAe;IACtB,SAAS,CAAiB;IAElC,YAAY,OAAqB;QAC/B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,SAAS,GAAG,IAAI,0BAAc,CAAC,OAAO,CAAC,CAAC;IAC/C,CAAC;IAED;;;;;;;;OAQG;IACH,UAAU,CAAC,MAAc;QACvB,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;QAE/C,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,MAAM,IAAI,KAAK,CAAC,mBAAmB,MAAM,EAAE,CAAC,CAAC;QAC/C,CAAC;QAED,wCAAwC;QACxC,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC;QAEtD,eAAe;QACf,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;QAEpD,4DAA4D;QAC5D,MAAM,aAAa,GAAG,IAAI,CAAC,OAAO,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC;QAC5D,MAAM,YAAY,GAAsC,EAAE,CAAC;QAC3D,KAAK,MAAM,IAAI,IAAI,aAAa,EAAE,CAAC;YACjC,gDAAgD;YAChD,IAAI,IAAI,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;gBAC7B,SAAS;YACX,CAAC;YACD,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YACnD,IAAI,IAAI,EAAE,CAAC;gBACT,YAAY,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;YACpC,CAAC;QACH,CAAC;QAED,wDAAwD;QACxD,MAAM,aAAa,GAAG,IAAI,CAAC,OAAO,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC;QAC5D,MAAM,YAAY,GAAsC,EAAE,CAAC;QAC3D,KAAK,MAAM,IAAI,IAAI,aAAa,EAAE,CAAC;YACjC,+CAA+C;YAC/C,IAAI,IAAI,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;gBAC7B,SAAS;YACX,CAAC;YACD,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YACnD,IAAI,IAAI,EAAE,CAAC;gBACT,YAAY,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;YACpC,CAAC;QACH,CAAC;QAED,gDAAgD;QAChD,MAAM,KAAK,GAAW,EAAE,CAAC;QACzB,MAAM,aAAa,GAAe,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;QACzD,KAAK,MAAM,IAAI,IAAI,aAAa,EAAE,CAAC;YACjC,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,gBAAgB,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;YAChE,KAAK,MAAM,IAAI,IAAI,SAAS,EAAE,CAAC;gBAC7B,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;gBACvD,IAAI,QAAQ,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;oBACzD,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;gBACvB,CAAC;YACH,CAAC;QACH,CAAC;QAED,uBAAuB;QACvB,MAAM,OAAO,GAAW,EAAE,CAAC;QAC3B,MAAM,QAAQ,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC;QAC1D,IAAI,QAAQ,EAAE,CAAC;YACb,MAAM,WAAW,GAAG,IAAI,CAAC,OAAO,CAAC,gBAAgB,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC;YAC5E,KAAK,MAAM,IAAI,IAAI,WAAW,EAAE,CAAC;gBAC/B,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;gBACzD,IAAI,UAAU,EAAE,CAAC;oBACf,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;gBAC3B,CAAC;YACH,CAAC;QACH,CAAC;QAED,OAAO;YACL,KAAK;YACL,SAAS;YACT,QAAQ;YACR,YAAY;YACZ,YAAY;YACZ,KAAK;YACL,OAAO;SACR,CAAC;IACJ,CAAC;IAED;;;;;;;OAOG;IACH,mBAAmB,CAAC,QAAgB;QAClC,qEAAqE;QACrE,oEAAoE;QACpE,0EAA0E;QAC1E,gEAAgE;QAChE,OAAO,IAAI,CAAC,OAAO,CAAC,sBAAsB,CAAC,QAAQ,CAAC,CAAC;IACvD,CAAC;IAED;;;;;;;OAOG;IACH,iBAAiB,CAAC,QAAgB;QAChC,0EAA0E;QAC1E,2EAA2E;QAC3E,2EAA2E;QAC3E,uEAAuE;QACvE,oEAAoE;QACpE,qEAAqE;QACrE,qEAAqE;QACrE,OAAO,IAAI,CAAC,OAAO,CAAC,qBAAqB,CAAC,QAAQ,CAAC,CAAC;IACtD,CAAC;IAED;;;;;OAKG;IACH,kBAAkB,CAAC,QAAgB;QACjC,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC;QACpD,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC;IAC3C,CAAC;IAED;;;;;OAKG;IACH,mBAAmB,CAAC,OAAe;QACjC,gCAAgC;QAChC,MAAM,YAAY,GAAG,OAAO;aACzB,OAAO,CAAC,mBAAmB,EAAE,MAAM,CAAC;aACpC,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC;aACpB,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QAEvB,MAAM,KAAK,GAAG,IAAI,MAAM,CAAC,IAAI,YAAY,GAAG,CAAC,CAAC;QAE9C,gFAAgF;QAChF,gDAAgD;QAChD,MAAM,QAAQ,GAAW,EAAE,CAAC;QAC5B,MAAM,KAAK,GAAmB;YAC5B,OAAO;YACP,OAAO;YACP,UAAU;YACV,QAAQ;YACR,WAAW;YACX,YAAY;YACZ,UAAU;YACV,UAAU;SACX,CAAC;QAEF,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC;YAChD,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;gBACzB,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,EAAE,CAAC;oBACnC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;gBACtB,CAAC;YACH,CAAC;QACH,CAAC;QAED,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED;;;;;;OAMG;IACH,kBAAkB;QAChB,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC;QACzC,MAAM,SAAS,GAAG,IAAI,GAAG,EAAoB,CAAC;QAE9C,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;YACnC,MAAM,GAAG,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC;YAEhD,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;gBACxB,SAAS,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;YACzB,CAAC;YACD,SAAS,CAAC,GAAG,CAAC,GAAG,CAAE,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACtC,CAAC;QAED,OAAO,SAAS,CAAC;IACnB,CAAC;IAED;;;;OAIG;IACH,wBAAwB;QACtB,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC;QACzC,MAAM,MAAM,GAAe,EAAE,CAAC;QAC9B,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;QAClC,MAAM,cAAc,GAAG,IAAI,GAAG,EAAU,CAAC;QAEzC,MAAM,GAAG,GAAG,CAAC,QAAgB,EAAE,IAAc,EAAQ,EAAE;YACrD,IAAI,cAAc,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;gBACjC,gBAAgB;gBAChB,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;gBAC1C,IAAI,UAAU,KAAK,CAAC,CAAC,EAAE,CAAC;oBACtB,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC;gBACtC,CAAC;gBACD,OAAO;YACT,CAAC;YAED,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;gBAC1B,OAAO;YACT,CAAC;YAED,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;YACtB,cAAc,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;YAE7B,MAAM,YAAY,GAAG,IAAI,CAAC,mBAAmB,CAAC,QAAQ,CAAC,CAAC;YACxD,KAAK,MAAM,GAAG,IAAI,YAAY,EAAE,CAAC;gBAC/B,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC;YAChC,CAAC;YAED,cAAc,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAClC,CAAC,CAAC;QAEF,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC5B,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;YACrB,CAAC;QACH,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;;;;OAKG;IACH,cAAc,CAAC,MAAc;QAQ3B,MAAM,aAAa,GAAG,IAAI,CAAC,OAAO,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC;QAC5D,MAAM,aAAa,GAAG,IAAI,CAAC,OAAO,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC;QAE5D,MAAM,SAAS,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC;QAClE,MAAM,WAAW,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC;QACpE,MAAM,aAAa,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,UAAU,CAAC,CAAC;QAEzE,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC;QAEtD,OAAO;YACL,iBAAiB,EAAE,aAAa,CAAC,MAAM;YACvC,iBAAiB,EAAE,aAAa,CAAC,MAAM;YACvC,SAAS,EAAE,SAAS,CAAC,MAAM;YAC3B,WAAW,EAAE,WAAW,CAAC,MAAM;YAC/B,UAAU,EAAE,aAAa,CAAC,MAAM;YAChC,KAAK,EAAE,SAAS,CAAC,MAAM;SACxB,CAAC;IACJ,CAAC;IAED;;;;;OAKG;IACH,YAAY,CAAC,KAAsB;QACjC,MAAM,WAAW,GAAG,KAAK,IAAI,CAAC,UAAU,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;QAC7D,MAAM,QAAQ,GAAW,EAAE,CAAC;QAE5B,KAAK,MAAM,IAAI,IAAI,WAAW,EAAE,CAAC;YAC/B,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC;YAChD,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;gBACzB,sDAAsD;gBACtD,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;oBACpB,SAAS;gBACX,CAAC;gBAED,MAAM,aAAa,GAAG,IAAI,CAAC,OAAO,CAAC,gBAAgB,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;gBAE7D,+BAA+B;gBAC/B,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,UAAU,CAAC,CAAC;gBAEtE,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;oBAC5B,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;gBACtB,CAAC;YACH,CAAC;QACH,CAAC;QAED,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED;;;;;;OAMG;IACH,mBAAmB,CACjB,MAA+B,EAC/B,eAAwB,IAAI;QAE5B,MAAM,KAAK,GAAG,IAAI,GAAG,EAAgB,CAAC;QACtC,MAAM,KAAK,GAAW,EAAE,CAAC;QAEzB,gCAAgC;QAChC,MAAM,KAAK,GAAmB;YAC5B,MAAM;YACN,QAAQ;YACR,OAAO;YACP,QAAQ;YACR,OAAO;YACP,WAAW;YACX,OAAO;YACP,UAAU;YACV,QAAQ;YACR,UAAU;YACV,UAAU;YACV,MAAM;YACN,YAAY;SACb,CAAC;QAEF,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC;YACpD,KAAK,MAAM,IAAI,IAAI,SAAS,EAAE,CAAC;gBAC7B,IAAI,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;oBACjB,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;gBAC3B,CAAC;YACH,CAAC;QACH,CAAC;QAED,uCAAuC;QACvC,IAAI,YAAY,EAAE,CAAC;YACjB,KAAK,MAAM,MAAM,IAAI,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;gBAClC,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC;gBACvD,KAAK,MAAM,IAAI,IAAI,QAAQ,EAAE,CAAC;oBAC5B,IAAI,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;wBAC3B,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;oBACnB,CAAC;gBACH,CAAC;YACH,CAAC;QACH,CAAC;QAED,OAAO;YACL,KAAK;YACL,KAAK;YACL,KAAK,EAAE,EAAE;SACV,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,YAAY;QACV,OAAO,IAAI,CAAC,SAAS,CAAC;IACxB,CAAC;CACF;AA9XD,8CA8XC"}

package/dist/graph/symbol-lookup.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Symbol Lookup — the single "what did the user mean by this name?" path.
+ *
+ * Every verb that takes a symbol NAME from a human (or an agent) has to turn
+ * that string into node(s). `codegraph_node` and `codegraph_explore` went
+ * through the matcher below; the `callers` / `callees` / `impact` CLI verbs
+ * carried their own ad-hoc filter instead:
+ *
+ *     node.name === symbol || node.name.endsWith('.' + symbol)
+ *
+ * which compares the query against the BARE name only. That produced two
+ * opposite failures in the same repository:
+ *
+ *   - a bare name over-reported: `callers group` silently merged the callers of
+ *     every distinct symbol named `group` — in any language — into one list
+ *     headed "Callers of group", with nothing saying they were different
+ *     symbols;
+ *   - a qualified name under-reported: `Foo.Bar.baz` can never equal a bare
+ *     `baz`, so every candidate failed the filter and the code fell through to
+ *     an arbitrary top-of-FTS hit — or reported "not found" for a symbol that
+ *     plainly exists.
+ *
+ * Both are fixed by routing all of them through one resolver, which this module
+ * owns so the CLI and the MCP tools cannot drift apart again.
+ */
+import type { Node } from '../types';
+/** Rust path prefixes that name no directory (`crate::x`, `super::y`). */
+export declare const RUST_PATH_PREFIXES: Set<string>;
+/** Does this query carry any scope qualifier at all? */
+export declare function isQualifiedSymbol(symbol: string): boolean;
+/** The bare identifier at the end of a qualified query (arity spelling stripped). */
+export declare function lastQualifierPart(symbol: string): string;
+/**
+ * Does `node` satisfy the user's symbol query?
+ *
+ * Bare queries match the name. Qualified queries are checked against the
+ * qualifiedName under both separator conventions, then — for languages whose
+ * hierarchy lives in the file path rather than the name (Rust modules, Python
+ * packages) — against the path.
+ */
+export declare function matchesSymbol(node: Node, symbol: string): boolean;
+/** The slice of AlphaCodeSense a symbol lookup needs — keeps this module testable. */
+export interface SymbolLookupHost {
+    getNodesByName(name: string): Node[];
+    searchNodes(query: string, options?: {
+        limit?: number;
+    }): Array<{
+        node: Node;
+    }>;
+    generatedFilePredicate(paths: string[]): (path: string) => boolean;
+}
+export interface SymbolLookupResult {
+    /** Every definition the query names, keepers before generated stubs. */
+    nodes: Node[];
+    /**
+     * The query named more than one distinct definition. Callers that aggregate
+     * across all of them MUST surface this — an aggregate presented as one
+     * symbol's answer is the over-reporting failure described at the top.
+     */
+    ambiguous: boolean;
+}
+/**
+ * One group per (filePath, qualifiedName): same-file overloads stay together,
+ * while unrelated definitions keep their own edges. Shared by CLI and MCP.
+ * A non-matching file hint keeps all definitions and must be disclosed.
+ */
+export declare function groupDefinitions(nodes: Node[], fileFilter?: string): {
+    groups: Node[][];
+    filteredOut: boolean;
+};
+/**
+ * Resolve a user-supplied symbol name to the definitions it names.
+ *
+ * The exact-name index is consulted FIRST and is authoritative: it is complete
+ * and uncapped, whereas FTS ranks and truncates, and tokenises away `::` — so
+ * a qualified query could miss a symbol that exists, or land on whatever
+ * happened to rank first. FTS candidates still have to satisfy the matcher;
+ * partial or mistyped names must never select the top fuzzy hit (#1473).
+ */
+export declare function lookupSymbolNodes(cg: SymbolLookupHost, symbol: string): SymbolLookupResult;
+/** One-line "kind at path:line" label used when disclosing an ambiguous query. */
+export declare function describeSymbolNode(node: Node): string;
+//# sourceMappingURL=symbol-lookup.d.ts.map

package/dist/graph/symbol-lookup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"symbol-lookup.d.ts","sourceRoot":"","sources":["../../src/graph/symbol-lookup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,UAAU,CAAC;AAErC,0EAA0E;AAC1E,eAAO,MAAM,kBAAkB,aAAsC,CAAC;AAEtE,wDAAwD;AACxD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEzD;AAED,qFAAqF;AACrF,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAIxD;AAYD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAqDjE;AAED,sFAAsF;AACtF,MAAM,WAAW,gBAAgB;IAC/B,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,CAAC;IACrC,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,KAAK,CAAC;QAAE,IAAI,EAAE,IAAI,CAAA;KAAE,CAAC,CAAC;IAChF,sBAAsB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;CACpE;AAED,MAAM,WAAW,kBAAkB;IACjC,wEAAwE;IACxE,KAAK,EAAE,IAAI,EAAE,CAAC;IACd;;;;OAIG;IACH,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,IAAI,EAAE,EACb,UAAU,CAAC,EAAE,MAAM,GAClB;IAAE,MAAM,EAAE,IAAI,EAAE,EAAE,CAAC;IAAC,WAAW,EAAE,OAAO,CAAA;CAAE,CAmB5C;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,GAAG,kBAAkB,CA0B1F;AAED,kFAAkF;AAClF,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAErD"}