@saluzi/codegraph 0.1.0

package/dist/bin/codegraph.d.ts

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+/**
+ * CodeGraph CLI
+ *
+ * Command-line interface for CodeGraph code intelligence.
+ *
+ * Usage:
+ *   codegraph                    Run interactive installer (when no args)
+ *   codegraph install            Run interactive installer
+ *   codegraph uninstall          Remove CodeGraph from your agents
+ *   codegraph init [path]        Initialize CodeGraph in a project
+ *   codegraph uninit [path]      Remove CodeGraph from a project
+ *   codegraph index [path]       Index all files in the project
+ *   codegraph sync [path]        Sync changes since last index
+ *   codegraph status [path]      Show index status
+ *   codegraph query <search>     Search for symbols
+ *   codegraph files [options]    Show project file structure
+ *   codegraph context <task>     Build context for a task
+ *   codegraph callers <symbol>   Find what calls a function/method
+ *   codegraph callees <symbol>   Find what a function/method calls
+ *   codegraph impact <symbol>    Analyze what code is affected by changing a symbol
+ *   codegraph affected [files]   Find test files affected by changes
+ */
+export {};
+//# sourceMappingURL=codegraph.d.ts.map

package/dist/bin/node-version-check.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Node.js version compatibility check.
+ *
+ * Node 25.x has a V8 turboshaft WASM JIT Zone allocator bug that
+ * reliably crashes CodeGraph with `Fatal process out of memory: Zone`
+ * during tree-sitter grammar compilation. This module owns the
+ * user-facing banner shown before exit. Kept side-effect-free so it's
+ * safe to import from tests without triggering CLI bootstrap.
+ */
+/**
+ * Build the bordered banner shown when CodeGraph detects an
+ * unsupported Node.js major version (currently 25+). Pinned via unit
+ * test so the recovery commands and override instructions can't be
+ * silently stripped by future edits.
+ *
+ * Uses ASCII glyphs to stay readable on Windows OEM-codepage consoles
+ * (see ../ui/glyphs.ts for the rationale).
+ */
+export declare function buildNode25BlockBanner(nodeVersion: string): string;
+/**
+ * Lowest supported Node.js major version. Matches the `engines` floor in
+ * package.json. Below this, CodeGraph relies on language features / native APIs
+ * that aren't present, and the combination is untested. `engines` alone only
+ * *warns* on install (unless the user set `engine-strict`), so the CLI bootstrap
+ * also hard-blocks here to actually enforce the floor.
+ */
+export declare const MIN_NODE_MAJOR = 20;
+/**
+ * Build the bordered banner shown when CodeGraph detects a Node.js major below
+ * {@link MIN_NODE_MAJOR}. Pinned via unit test so the recovery commands and the
+ * override env var can't be silently stripped by future edits.
+ *
+ * Uses ASCII glyphs to stay readable on Windows OEM-codepage consoles
+ * (see ../ui/glyphs.ts for the rationale).
+ */
+export declare function buildNodeTooOldBanner(nodeVersion: string): string;
+//# sourceMappingURL=node-version-check.d.ts.map

package/dist/bin/uninstall.d.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+/**
+ * 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.
+ */
+//# sourceMappingURL=uninstall.d.ts.map

package/dist/context/formatter.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 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.js

@@ -0,0 +1,244 @@
+"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;
+/**
+ * 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
+    if (context.entryPoints.length > 0) {
+        lines.push('### Entry Points\n');
+        for (const node of context.entryPoints) {
+            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)
+    const otherSymbols = Array.from(context.subgraph.nodes.values())
+        .filter(n => !context.entryPoints.some(e => e.id === n.id))
+        .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
+    if (context.codeBlocks.length > 0) {
+        lines.push('### Code\n');
+        for (const block of context.codeBlocks) {
+            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/index.d.ts

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