@saluzi/codegraph 0.2.0 → 0.2.1

package/dist/bin/uninstall.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * CodeGraph preuninstall cleanup script
+ *
+ * Runs automatically when `npm uninstall -g @colbymchenry/codegraph`
+ * is called. Loops over every known agent target's `uninstall(loc)`
+ * for the global location only — local-location entries live inside
+ * project working trees and aren't ours to nuke at npm-uninstall
+ * time.
+ *
+ * This script must never throw — a failed cleanup must not block
+ * uninstall.
+ */
+try {
+    // Lazy require so any module-level error in the registry can't
+    // bubble out and abort the npm uninstall.
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const { ALL_TARGETS } = require('../installer/targets/registry');
+    for (const target of ALL_TARGETS) {
+        if (!target.supportsLocation('global'))
+            continue;
+        try {
+            target.uninstall('global');
+        }
+        catch {
+            // Each target is independently safe-to-skip; per-target failure
+            // must not stop the loop.
+        }
+    }
+}
+catch {
+    // If the registry itself can't be loaded (e.g. partial install),
+    // we silently skip cleanup. Uninstall still completes.
+}
+//# sourceMappingURL=uninstall.js.map

package/dist/bin/uninstall.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"uninstall.js","sourceRoot":"","sources":["../../src/bin/uninstall.ts"],"names":[],"mappings":";;AACA;;;;;;;;;;;GAWG;AAEH,IAAI,CAAC;IACH,+DAA+D;IAC/D,0CAA0C;IAC1C,iEAAiE;IACjE,MAAM,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC,+BAA+B,CACf,CAAC;IAEjD,KAAK,MAAM,MAAM,IAAI,WAAW,EAAE,CAAC;QACjC,IAAI,CAAC,MAAM,CAAC,gBAAgB,CAAC,QAAQ,CAAC;YAAE,SAAS;QACjD,IAAI,CAAC;YACH,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;QAC7B,CAAC;QAAC,MAAM,CAAC;YACP,gEAAgE;YAChE,0BAA0B;QAC5B,CAAC;IACH,CAAC;AACH,CAAC;AAAC,MAAM,CAAC;IACP,iEAAiE;IACjE,uDAAuD;AACzD,CAAC"}

package/dist/context/formatter.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Context Formatter
+ *
+ * Formats TaskContext as markdown or JSON for consumption by Claude.
+ */
+import { Node, TaskContext, Subgraph } from '../types';
+/**
+ * Format context as markdown
+ *
+ * Creates a compact markdown document optimized for Claude with minimal context usage:
+ * - Brief summary
+ * - Entry points with locations
+ * - Code blocks only for key symbols
+ */
+export declare function formatContextAsMarkdown(context: TaskContext): string;
+/**
+ * Format context as JSON
+ *
+ * Returns a structured JSON representation suitable for programmatic use.
+ */
+export declare function formatContextAsJson(context: TaskContext): string;
+/**
+ * Format a subgraph as an ASCII tree structure
+ */
+export declare function formatSubgraphTree(subgraph: Subgraph, entryPoints: Node[]): string;
+/**
+ * Format bytes as human-readable string
+ */
+export declare function formatBytes(bytes: number): string;
+//# sourceMappingURL=formatter.d.ts.map

package/dist/context/formatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatter.d.ts","sourceRoot":"","sources":["../../src/context/formatter.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,IAAI,EAAQ,WAAW,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAG7D;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,CAwEpE;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,CAsBhE;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,QAAQ,EAAE,WAAW,EAAE,IAAI,EAAE,GAAG,MAAM,CAqClF;AAsHD;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAQjD"}

package/dist/context/formatter.js

@@ -0,0 +1,263 @@
+"use strict";
+/**
+ * Context Formatter
+ *
+ * Formats TaskContext as markdown or JSON for consumption by Claude.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatContextAsMarkdown = formatContextAsMarkdown;
+exports.formatContextAsJson = formatContextAsJson;
+exports.formatSubgraphTree = formatSubgraphTree;
+exports.formatBytes = formatBytes;
+const generated_detection_1 = require("../extraction/generated-detection");
+/**
+ * Format context as markdown
+ *
+ * Creates a compact markdown document optimized for Claude with minimal context usage:
+ * - Brief summary
+ * - Entry points with locations
+ * - Code blocks only for key symbols
+ */
+function formatContextAsMarkdown(context) {
+    const lines = [];
+    // Header with query
+    lines.push('## Code Context\n');
+    lines.push(`**Query:** ${context.query}\n`);
+    // Entry points - compact format. Re-sort so generated files (.pb.go,
+    // .pulsar.go, mocks, …) rank LAST — a flow query should lead with the
+    // hand-written implementation, not protobuf scaffolding.
+    const orderedEntries = [...context.entryPoints].sort((a, b) => {
+        const aGen = (0, generated_detection_1.isGeneratedFile)(a.filePath) ? 1 : 0;
+        const bGen = (0, generated_detection_1.isGeneratedFile)(b.filePath) ? 1 : 0;
+        return aGen - bGen;
+    });
+    if (orderedEntries.length > 0) {
+        lines.push('### Entry Points\n');
+        for (const node of orderedEntries) {
+            const location = node.startLine ? `:${node.startLine}` : '';
+            lines.push(`- **${node.name}** (${node.kind}) - ${node.filePath}${location}`);
+            if (node.signature) {
+                lines.push(`  \`${node.signature}\``);
+            }
+        }
+        lines.push('');
+    }
+    // Related symbols - compact list (skip verbose structure tree). Drop nodes
+    // in generated source files (`.pb.go` / `.pulsar.go` / mocks / …) — agents
+    // chasing a flow never want to land on protobuf scaffolding (cosmos-Q3 used
+    // to list `gov.pulsar.go::GetExpeditedThreshold` and `1.pulsar.go::Get` in
+    // Related Symbols, pure noise that displaced real-flow entries).
+    const otherSymbols = Array.from(context.subgraph.nodes.values())
+        .filter(n => !context.entryPoints.some(e => e.id === n.id))
+        .filter(n => !(0, generated_detection_1.isGeneratedFile)(n.filePath))
+        .slice(0, 10); // Limit to 10 related symbols
+    if (otherSymbols.length > 0) {
+        lines.push('### Related Symbols\n');
+        const byFile = new Map();
+        for (const node of otherSymbols) {
+            const existing = byFile.get(node.filePath) || [];
+            existing.push(node);
+            byFile.set(node.filePath, existing);
+        }
+        for (const [file, nodes] of byFile) {
+            const nodeList = nodes.map(n => `${n.name}:${n.startLine}`).join(', ');
+            lines.push(`- ${file}: ${nodeList}`);
+        }
+        lines.push('');
+    }
+    // Code blocks - only for key entry points. Re-sort so non-generated blocks
+    // show first (consistent with Entry Points reordering above).
+    if (context.codeBlocks.length > 0) {
+        const orderedBlocks = [...context.codeBlocks].sort((a, b) => {
+            const aGen = (0, generated_detection_1.isGeneratedFile)(a.filePath) ? 1 : 0;
+            const bGen = (0, generated_detection_1.isGeneratedFile)(b.filePath) ? 1 : 0;
+            return aGen - bGen;
+        });
+        lines.push('### Code\n');
+        for (const block of orderedBlocks) {
+            const nodeName = block.node?.name ?? 'Unknown';
+            lines.push(`#### ${nodeName} (${block.filePath}:${block.startLine})\n`);
+            lines.push('```' + block.language);
+            lines.push(block.content);
+            lines.push('```\n');
+        }
+    }
+    return lines.join('\n');
+}
+/**
+ * Format context as JSON
+ *
+ * Returns a structured JSON representation suitable for programmatic use.
+ */
+function formatContextAsJson(context) {
+    // Convert Map to array for JSON serialization
+    const serializable = {
+        query: context.query,
+        summary: context.summary,
+        entryPoints: context.entryPoints.map(serializeNode),
+        nodes: Array.from(context.subgraph.nodes.values()).map(serializeNode),
+        edges: context.subgraph.edges.map(serializeEdge),
+        codeBlocks: context.codeBlocks.map((block) => ({
+            filePath: block.filePath,
+            startLine: block.startLine,
+            endLine: block.endLine,
+            language: block.language,
+            content: block.content,
+            nodeName: block.node?.name,
+            nodeKind: block.node?.kind,
+        })),
+        relatedFiles: context.relatedFiles,
+        stats: context.stats,
+    };
+    return JSON.stringify(serializable, null, 2);
+}
+/**
+ * Format a subgraph as an ASCII tree structure
+ */
+function formatSubgraphTree(subgraph, entryPoints) {
+    const lines = [];
+    const printed = new Set();
+    // Build adjacency list for outgoing edges
+    const outgoing = new Map();
+    for (const edge of subgraph.edges) {
+        const existing = outgoing.get(edge.source) ?? [];
+        existing.push(edge);
+        outgoing.set(edge.source, existing);
+    }
+    // Print each entry point as a tree root
+    for (const entry of entryPoints) {
+        formatNodeTree(entry, subgraph, outgoing, printed, lines, 0, '');
+        lines.push(''); // Blank line between trees
+    }
+    // Print any remaining nodes not reached from entry points
+    const remaining = [];
+    for (const node of subgraph.nodes.values()) {
+        if (!printed.has(node.id)) {
+            remaining.push(node);
+        }
+    }
+    if (remaining.length > 0 && remaining.length <= 10) {
+        lines.push('Other relevant symbols:');
+        for (const node of remaining) {
+            const location = node.startLine ? `:${node.startLine}` : '';
+            lines.push(`  ${node.kind}: ${node.name} (${node.filePath}${location})`);
+        }
+    }
+    else if (remaining.length > 10) {
+        lines.push(`... and ${remaining.length} more related symbols`);
+    }
+    return lines.join('\n').trim();
+}
+/**
+ * Format a single node and its relationships
+ */
+function formatNodeTree(node, subgraph, outgoing, printed, lines, depth, prefix) {
+    if (printed.has(node.id)) {
+        return;
+    }
+    printed.add(node.id);
+    // Node header
+    const location = node.startLine ? `:${node.startLine}` : '';
+    const signature = node.signature ? ` - ${truncate(node.signature, 50)}` : '';
+    lines.push(`${prefix}${node.kind}: ${node.name} (${node.filePath}${location})${signature}`);
+    // Outgoing edges
+    const edges = outgoing.get(node.id) ?? [];
+    const significantEdges = edges.filter((e) => ['calls', 'extends', 'implements', 'imports', 'references'].includes(e.kind));
+    // Group by kind
+    const edgesByKind = new Map();
+    for (const edge of significantEdges) {
+        const existing = edgesByKind.get(edge.kind) ?? [];
+        existing.push(edge);
+        edgesByKind.set(edge.kind, existing);
+    }
+    // Print edges grouped by kind
+    const newPrefix = prefix + '  ';
+    for (const [kind, kindEdges] of edgesByKind) {
+        if (kindEdges.length > 3) {
+            // Summarize if too many
+            const names = kindEdges
+                .slice(0, 3)
+                .map((e) => {
+                const target = subgraph.nodes.get(e.target);
+                return target?.name ?? 'unknown';
+            })
+                .join(', ');
+            lines.push(`${newPrefix}├── ${kind}: ${names} and ${kindEdges.length - 3} more`);
+        }
+        else {
+            for (let i = 0; i < kindEdges.length; i++) {
+                const edge = kindEdges[i];
+                const target = subgraph.nodes.get(edge.target);
+                const targetName = target?.name ?? 'unknown';
+                const connector = i === kindEdges.length - 1 ? '└──' : '├──';
+                lines.push(`${newPrefix}${connector} ${kind} → ${targetName}`);
+            }
+        }
+    }
+    // Recurse for directly connected nodes (limited depth)
+    if (depth < 1) {
+        for (const edge of significantEdges.slice(0, 3)) {
+            const target = subgraph.nodes.get(edge.target);
+            if (target && !printed.has(target.id)) {
+                formatNodeTree(target, subgraph, outgoing, printed, lines, depth + 1, newPrefix);
+            }
+        }
+    }
+}
+/**
+ * Serialize a node for JSON output
+ */
+function serializeNode(node) {
+    return {
+        id: node.id,
+        kind: node.kind,
+        name: node.name,
+        qualifiedName: node.qualifiedName,
+        filePath: node.filePath,
+        language: node.language,
+        startLine: node.startLine,
+        endLine: node.endLine,
+        signature: node.signature,
+        docstring: node.docstring,
+        visibility: node.visibility,
+        isExported: node.isExported,
+        isAsync: node.isAsync,
+        isStatic: node.isStatic,
+    };
+}
+/**
+ * Serialize an edge for JSON output
+ */
+function serializeEdge(edge) {
+    return {
+        source: edge.source,
+        target: edge.target,
+        kind: edge.kind,
+        line: edge.line,
+        column: edge.column,
+    };
+}
+/**
+ * Truncate a string with ellipsis
+ */
+function truncate(str, maxLength) {
+    if (str.length <= maxLength) {
+        return str;
+    }
+    return str.slice(0, maxLength - 3) + '...';
+}
+/**
+ * Format bytes as human-readable string
+ */
+function formatBytes(bytes) {
+    if (bytes < 1024) {
+        return `${bytes} bytes`;
+    }
+    else if (bytes < 1024 * 1024) {
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    }
+    else {
+        return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+    }
+}
+//# sourceMappingURL=formatter.js.map

package/dist/context/formatter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatter.js","sourceRoot":"","sources":["../../src/context/formatter.ts"],"names":[],"mappings":"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"}

package/dist/context/index.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Context Builder
+ *
+ * Builds rich context for tasks by combining FTS search with graph traversal.
+ * Outputs structured context ready to inject into Claude.
+ */
+import { Subgraph, TaskContext, TaskInput, BuildContextOptions, FindRelevantContextOptions } from '../types';
+import { QueryBuilder } from '../db/queries';
+import { GraphTraverser } from '../graph';
+export { LOW_CONFIDENCE_MARKER } from './markers';
+/**
+ * Context Builder
+ *
+ * Coordinates semantic search and graph traversal to build
+ * comprehensive context for tasks.
+ */
+export declare class ContextBuilder {
+    private projectRoot;
+    private queries;
+    private traverser;
+    constructor(projectRoot: string, queries: QueryBuilder, traverser: GraphTraverser);
+    /**
+     * Build context for a task
+     *
+     * Pipeline:
+     * 1. Parse task input (string or {title, description})
+     * 2. Run semantic search to find entry points
+     * 3. Expand graph around entry points
+     * 4. Extract code blocks for key nodes
+     * 5. Format output for Claude
+     *
+     * @param input - Task description or object with title/description
+     * @param options - Build options
+     * @returns TaskContext (structured) or formatted string
+     */
+    buildContext(input: TaskInput, options?: BuildContextOptions): Promise<TaskContext | string>;
+    /**
+     * Honest handoff appended when retrieval confidence is low (the query matched
+     * mostly common words). Instead of the usual "this covers the surface" framing
+     * — which, when wrong, sends the agent off to Read/Grep — it admits the
+     * uncertainty and routes the agent to the precise tools (explore with real
+     * symbol names, search, or files to browse the closest areas we *did* surface).
+     */
+    private buildLowConfidenceNote;
+    /**
+     * Surface short call-paths among the symbols this context already found,
+     * derived in-memory from the subgraph's `calls` edges (no extra queries).
+     *
+     * This bakes the value of path-finding INTO the always-loaded `context` tool.
+     * Agents reliably read context's output but do NOT discover/adopt a standalone
+     * trace tool (in deferred-MCP harnesses they only ToolSearch-select tools they
+     * already know). Delivering the flow here means "how does X reach Y" is
+     * answered without the agent needing to find, load, or choose a new tool.
+     * Chains stop where the static call graph ends (e.g. dynamic dispatch) — that
+     * truncation is honest, and the agent can codegraph_node the last hop to bridge.
+     */
+    private buildCallPathsSection;
+    /**
+     * Find relevant subgraph for a query
+     *
+     * Uses hybrid search combining exact symbol lookup with semantic search:
+     * 1. Extract potential symbol names from query
+     * 2. Look up exact matches for those symbols (high confidence)
+     * 3. Use semantic search for concept matching
+     * 4. Merge results, prioritizing exact matches
+     * 5. Traverse graph from entry points
+     *
+     * @param query - Natural language query
+     * @param options - Search and traversal options
+     * @returns Subgraph of relevant nodes and edges
+     */
+    findRelevantContext(query: string, options?: FindRelevantContextOptions): Promise<Subgraph>;
+    /**
+     * Get the source code for a node
+     *
+     * Reads the file and extracts the code between startLine and endLine.
+     *
+     * @param nodeId - ID of the node
+     * @returns Code string or null if not found
+     */
+    getCode(nodeId: string): Promise<string | null>;
+    /**
+     * Extract code from a node's source file
+     */
+    private extractNodeCode;
+    /**
+     * Get entry points from a subgraph (the root nodes)
+     */
+    private getEntryPoints;
+    /**
+     * Extract code blocks for key nodes in the subgraph
+     */
+    private extractCodeBlocks;
+    /**
+     * Get unique files from a subgraph
+     */
+    private getRelatedFiles;
+    /**
+     * Generate a summary of the context
+     */
+    private generateSummary;
+    /**
+     * Resolve import/export nodes to their actual definitions
+     *
+     * When search returns `import { TerminalPanel }`, users want the TerminalPanel
+     * class definition, not the import statement. This follows the `imports` edge
+     * to find and return the actual definition instead.
+     *
+     * @param results - Search results that may include import/export nodes
+     * @returns Results with imports resolved to definitions where possible
+     */
+    private resolveImportsToDefinitions;
+}
+/**
+ * Create a context builder
+ */
+export declare function createContextBuilder(projectRoot: string, queries: QueryBuilder, traverser: GraphTraverser): ContextBuilder;
+export { formatContextAsMarkdown, formatContextAsJson } from './formatter';
+//# sourceMappingURL=index.d.ts.map

package/dist/context/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/context/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAKL,QAAQ,EAER,WAAW,EACX,SAAS,EACT,mBAAmB,EACnB,0BAA0B,EAE3B,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AA2J1C,OAAO,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC;AAElD;;;;;GAKG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,OAAO,CAAe;IAC9B,OAAO,CAAC,SAAS,CAAiB;gBAGhC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,YAAY,EACrB,SAAS,EAAE,cAAc;IAO3B;;;;;;;;;;;;;OAaG;IACG,YAAY,CAChB,KAAK,EAAE,SAAS,EAChB,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,WAAW,GAAG,MAAM,CAAC;IA2DhC;;;;;;OAMG;IACH,OAAO,CAAC,sBAAsB;IAuB9B;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,qBAAqB;IAkG7B;;;;;;;;;;;;;OAaG;IACG,mBAAmB,CACvB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,0BAA+B,GACvC,OAAO,CAAC,QAAQ,CAAC;IAosBpB;;;;;;;OAOG;IACG,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IASrD;;OAEG;YACW,eAAe;IA8B7B;;OAEG;IACH,OAAO,CAAC,cAAc;IAMtB;;OAEG;YACW,iBAAiB;IA+D/B;;OAEG;IACH,OAAO,CAAC,eAAe;IAQvB;;OAEG;IACH,OAAO,CAAC,eAAe;IAiBvB;;;;;;;;;OASG;IACH,OAAO,CAAC,2BAA2B;CAiDpC;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,YAAY,EACrB,SAAS,EAAE,cAAc,GACxB,cAAc,CAEhB;AAGD,OAAO,EAAE,uBAAuB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC"}