@colbymchenry/codegraph 0.9.6 → 0.9.8

package/dist/db/queries.d.ts

@@ -0,0 +1,344 @@
+/**
+ * Database Queries
+ *
+ * Prepared statements for CRUD operations on the knowledge graph.
+ */
+import { SqliteDatabase } from './sqlite-adapter';
+import { Node, Edge, FileRecord, UnresolvedReference, NodeKind, EdgeKind, GraphStats, SearchOptions, SearchResult } from '../types';
+/**
+ * Query builder for the knowledge graph database
+ */
+export declare class QueryBuilder {
+    private db;
+    private nodeCache;
+    private readonly maxCacheSize;
+    private stmts;
+    constructor(db: SqliteDatabase);
+    /**
+     * Insert a new node
+     */
+    insertNode(node: Node): void;
+    /**
+     * Insert multiple nodes in a transaction
+     */
+    insertNodes(nodes: Node[]): void;
+    /**
+     * Update an existing node
+     */
+    updateNode(node: Node): void;
+    /**
+     * Delete a node by ID
+     */
+    deleteNode(id: string): void;
+    /**
+     * Delete all nodes for a file
+     */
+    deleteNodesByFile(filePath: string): void;
+    /**
+     * Get a node by ID
+     */
+    getNodeById(id: string): Node | null;
+    /**
+     * Batch lookup: fetch many nodes by ID in a single SQL round-trip.
+     *
+     * Replaces the N+1 pattern in graph traversal where every edge would
+     * trigger its own `getNodeById` call. For a function with 50 callers
+     * this collapses 50 point reads into one IN-list query (~10-50x
+     * faster end-to-end).
+     *
+     * Returns a Map keyed by id so callers can preserve their own ordering
+     * (typically the order edges were returned from the graph). Missing IDs
+     * are simply absent from the map.
+     *
+     * Cache-aware: ids already in the LRU cache are served from memory and
+     * the SQL query only touches the misses.
+     */
+    getNodesByIds(ids: readonly string[]): Map<string, Node>;
+    private getExistingNodeIds;
+    /**
+     * Add a node to the cache, evicting oldest if needed
+     */
+    private cacheNode;
+    /**
+     * Clear the node cache
+     */
+    clearCache(): void;
+    /**
+     * Get all nodes in a file
+     */
+    getNodesByFile(filePath: string): Node[];
+    /**
+     * Find the file that holds the densest concentration of the project's
+     * internal call graph — the "core" file. Used by context-builder to
+     * boost ranking of symbols in that file's directory (so e.g. sinatra
+     * queries surface `lib/sinatra/base.rb`'s `route!` instead of
+     * `sinatra-contrib/lib/sinatra/multi_route.rb`'s `route` extension).
+     *
+     * Returns null if no file has a meaningful concentration (e.g. spread
+     * evenly across many files, or empty index).
+     *
+     * "Internal" = source and target are in the same file. Cross-file
+     * edges aren't useful here — they don't tell us which file is the
+     * functional center.
+     *
+     * Excludes test/spec files from candidacy via path-pattern. The agent's
+     * typical question is "how does X work", not "how is X tested", so
+     * boosting a test file's directory would be a misfire.
+     */
+    getDominantFile(): {
+        filePath: string;
+        edgeCount: number;
+        nextEdgeCount: number;
+    } | null;
+    /**
+     * Find the file that holds the densest concentration of the project's
+     * `route` nodes (framework-emitted: Express/Gin/Flask/Rails/Drupal/etc.).
+     * Used by handleContext on small repos to inline the project's routing
+     * config when the agent's query is about request flow — eliminating the
+     * "Glob + Read routes.rb" pattern that beats codegraph on tiny realworld
+     * template repos.
+     *
+     * Excludes test/generated files from candidacy. Returns null if there
+     * are fewer than 3 non-test routes total, or if no file holds at least
+     * 30% of them (diffuse routing → no single answer file).
+     */
+    getTopRouteFile(): {
+        filePath: string;
+        routeCount: number;
+        totalRoutes: number;
+    } | null;
+    /**
+     * Build a URL → handler manifest from the index. Each route node's
+     * `references` edge points at the function/method that handles the
+     * request. We join them in one pass; the agent gets the canonical
+     * routing answer ("POST /users/login → AuthController#login") without
+     * having to parse the framework's route DSL itself.
+     *
+     * Also returns the file with the most handler endpoints — used as the
+     * "top handler file" to inline source for, so the agent has both the
+     * mapping AND the handler implementations.
+     */
+    getRoutingManifest(limit?: number): {
+        entries: Array<{
+            url: string;
+            handler: string;
+            handlerFile: string;
+            handlerLine: number;
+            handlerKind: string;
+        }>;
+        topHandlerFile: string | null;
+        topHandlerFileCount: number;
+        totalRoutes: number;
+    } | null;
+    /**
+     * Get all nodes of a specific kind
+     */
+    getNodesByKind(kind: NodeKind): Node[];
+    /**
+     * Get all nodes in the database
+     */
+    getAllNodes(): Node[];
+    /**
+     * Get nodes by exact name match (uses idx_nodes_name index)
+     */
+    getNodesByName(name: string): Node[];
+    /**
+     * Get nodes by exact qualified name match (uses idx_nodes_qualified_name index)
+     */
+    getNodesByQualifiedNameExact(qualifiedName: string): Node[];
+    /**
+     * Get nodes by lowercase name match (uses idx_nodes_lower_name expression index)
+     */
+    getNodesByLowerName(lowerName: string): Node[];
+    /**
+     * Search nodes by name using FTS with fallback to LIKE for better matching
+     *
+     * Search strategy:
+     * 1. Try FTS5 prefix match (query*) for word-start matching
+     * 2. If no results, try LIKE for substring matching (e.g., "signIn" finds "signInWithGoogle")
+     * 3. Score results based on match quality
+     */
+    searchNodes(query: string, options?: SearchOptions): SearchResult[];
+    /**
+     * Match-everything path used when the user supplied only field
+     * filters (`kind:function lang:typescript`) with no text. Returns
+     * candidates ordered by name; the caller's filter pass narrows to
+     * what was asked for.
+     */
+    private searchAllByFilters;
+    /**
+     * Fuzzy fallback: when zero FTS/LIKE hits, try an edit-distance
+     * sweep over the distinct symbol-name set. Caps `maxDist` at 2 so
+     * `getUssr` finds `getUser` but `process` doesn't match `prosody`.
+     * Bounded edit distance keeps each comparison cheap; the per-query
+     * scan is O(distinct-name-count) which is far smaller than total
+     * node count on any real codebase.
+     */
+    private searchNodesFuzzy;
+    /**
+     * FTS5 search with prefix matching
+     */
+    private searchNodesFTS;
+    /**
+     * LIKE-based substring search for cases where FTS doesn't match
+     * Useful for camelCase matching (e.g., "signIn" finds "signInWithGoogle")
+     */
+    private searchNodesLike;
+    /**
+     * Find nodes by exact name match
+     *
+     * Used for hybrid search - looks up symbols by exact name or case-insensitive match.
+     * Returns high-confidence matches for known symbol names extracted from query.
+     *
+     * @param names - Array of symbol names to look up
+     * @param options - Search options (kinds, languages, limit)
+     * @returns SearchResult array with exact matches scored at 1.0
+     */
+    findNodesByExactName(names: string[], options?: SearchOptions): SearchResult[];
+    /**
+     * Find nodes whose name contains a substring (LIKE-based).
+     * Useful for CamelCase-part matching where FTS fails because
+     * e.g. "TransportSearchAction" is one FTS token, not matchable by "Search"*.
+     *
+     * Results are ordered by name length (shorter = more likely to be the core type).
+     */
+    findNodesByNameSubstring(substring: string, options?: SearchOptions & {
+        excludePrefix?: boolean;
+    }): SearchResult[];
+    /**
+     * Insert a new edge
+     */
+    insertEdge(edge: Edge): void;
+    /**
+     * Insert multiple edges in a transaction
+     */
+    insertEdges(edges: Edge[]): void;
+    /**
+     * Delete all edges from a source node
+     */
+    deleteEdgesBySource(sourceId: string): void;
+    /**
+     * Get outgoing edges from a node
+     */
+    getOutgoingEdges(sourceId: string, kinds?: EdgeKind[], provenance?: string): Edge[];
+    /**
+     * Get incoming edges to a node
+     */
+    getIncomingEdges(targetId: string, kinds?: EdgeKind[]): Edge[];
+    /**
+     * Find all edges where both source and target are in the given node set.
+     * Useful for recovering inter-node connectivity after BFS.
+     */
+    findEdgesBetweenNodes(nodeIds: string[], kinds?: EdgeKind[]): Edge[];
+    /**
+     * Insert or update a file record
+     */
+    upsertFile(file: FileRecord): void;
+    /**
+     * Delete a file record and its nodes
+     */
+    deleteFile(filePath: string): void;
+    /**
+     * Get a file record by path
+     */
+    getFileByPath(filePath: string): FileRecord | null;
+    /**
+     * Get all tracked files
+     */
+    getAllFiles(): FileRecord[];
+    /**
+     * Get files that need re-indexing (hash changed)
+     */
+    getStaleFiles(currentHashes: Map<string, string>): FileRecord[];
+    /**
+     * Insert an unresolved reference
+     */
+    insertUnresolvedRef(ref: UnresolvedReference): void;
+    /**
+     * Insert multiple unresolved references in a transaction
+     */
+    insertUnresolvedRefsBatch(refs: UnresolvedReference[]): void;
+    /**
+     * Delete unresolved references from a node
+     */
+    deleteUnresolvedByNode(nodeId: string): void;
+    /**
+     * Get unresolved references by name (for resolution)
+     */
+    getUnresolvedByName(name: string): UnresolvedReference[];
+    /**
+     * Get all unresolved references
+     */
+    getUnresolvedReferences(): UnresolvedReference[];
+    /**
+     * Get the count of unresolved references without loading them into memory
+     */
+    getUnresolvedReferencesCount(): number;
+    /**
+     * Get a batch of unresolved references using LIMIT/OFFSET pagination.
+     * Used to process references in bounded memory chunks.
+     */
+    getUnresolvedReferencesBatch(offset: number, limit: number): UnresolvedReference[];
+    /**
+     * Get all tracked file paths (lightweight — no full FileRecord objects)
+     */
+    getAllFilePaths(): string[];
+    /**
+     * Get all distinct node names (lightweight — just name strings for pre-filtering)
+     */
+    getAllNodeNames(): string[];
+    /**
+     * Get unresolved references scoped to specific file paths.
+     * Uses the idx_unresolved_file_path index for efficient lookup.
+     */
+    getUnresolvedReferencesByFiles(filePaths: string[]): UnresolvedReference[];
+    /**
+     * Delete all unresolved references (after resolution)
+     */
+    clearUnresolvedReferences(): void;
+    /**
+     * Delete resolved references by their IDs
+     */
+    deleteResolvedReferences(fromNodeIds: string[]): void;
+    /**
+     * Delete specific resolved references by (fromNodeId, referenceName, referenceKind) tuples.
+     * More precise than deleteResolvedReferences — only removes refs that were actually resolved.
+     */
+    deleteSpecificResolvedReferences(refs: Array<{
+        fromNodeId: string;
+        referenceName: string;
+        referenceKind: string;
+    }>): void;
+    /**
+     * Lightweight (nodes, edges) count snapshot. Used around an index/sync
+     * run to compute true additions across extraction + resolution +
+     * synthesis — the per-phase counter in the orchestrator only sees
+     * extraction's contribution, which is why the CLI summary under-reported
+     * the edge count (resolution + synthesizer edges were invisible).
+     */
+    getNodeAndEdgeCount(): {
+        nodes: number;
+        edges: number;
+    };
+    /**
+     * Get graph statistics
+     */
+    getStats(): GraphStats;
+    /**
+     * Get a metadata value by key
+     */
+    getMetadata(key: string): string | null;
+    /**
+     * Set a metadata key-value pair (upsert)
+     */
+    setMetadata(key: string, value: string): void;
+    /**
+     * Get all metadata as a key-value record
+     */
+    getAllMetadata(): Record<string, string>;
+    /**
+     * Clear all data from the database
+     */
+    clear(): void;
+}
+//# sourceMappingURL=queries.d.ts.map

package/dist/db/sqlite-adapter.d.ts

@@ -0,0 +1,46 @@
+/**
+ * SQLite Adapter
+ *
+ * Thin wrapper over Node's built-in `node:sqlite` (`DatabaseSync`), exposed
+ * through a small better-sqlite3-shaped interface so the rest of the codebase
+ * is storage-agnostic.
+ *
+ * CodeGraph ships with a bundled Node runtime, so `node:sqlite` (real SQLite,
+ * with WAL + FTS5) is always available — there is no native build step and no
+ * wasm fallback. When run from source instead, it requires Node >= 22.5.
+ */
+export interface SqliteStatement {
+    run(...params: any[]): {
+        changes: number;
+        lastInsertRowid: number | bigint;
+    };
+    get(...params: any[]): any;
+    all(...params: any[]): any[];
+}
+export interface SqliteDatabase {
+    prepare(sql: string): SqliteStatement;
+    exec(sql: string): void;
+    pragma(str: string, options?: {
+        simple?: boolean;
+    }): any;
+    transaction<T>(fn: (...args: any[]) => T): (...args: any[]) => T;
+    close(): void;
+    readonly open: boolean;
+}
+/**
+ * The active SQLite backend. Only one now (`node:sqlite`); kept as a named type
+ * so `codegraph status` and the per-instance reporting have a stable shape.
+ */
+export type SqliteBackend = 'node-sqlite';
+/**
+ * Create a database connection backed by `node:sqlite`.
+ *
+ * Returns the active backend alongside the db so each `DatabaseConnection` can
+ * report it per-instance — MCP can open multiple project DBs in one process, so
+ * a process-global would race.
+ */
+export declare function createDatabase(dbPath: string): {
+    db: SqliteDatabase;
+    backend: SqliteBackend;
+};
+//# sourceMappingURL=sqlite-adapter.d.ts.map

package/dist/directory.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Directory Management
+ *
+ * Manages the .codegraph/ directory structure for CodeGraph data.
+ */
+/**
+ * CodeGraph directory name
+ */
+export declare const CODEGRAPH_DIR = ".codegraph";
+/**
+ * Get the .codegraph directory path for a project
+ */
+export declare function getCodeGraphDir(projectRoot: string): string;
+/**
+ * Check if a project has been initialized with CodeGraph
+ * Requires both .codegraph/ directory AND codegraph.db to exist
+ */
+export declare function isInitialized(projectRoot: string): boolean;
+/**
+ * Find the nearest parent directory containing .codegraph/
+ *
+ * Walks up from the given path to find a CodeGraph-initialized project,
+ * similar to how git finds .git/ directories.
+ *
+ * @param startPath - Directory to start searching from
+ * @returns The project root containing .codegraph/, or null if not found
+ */
+export declare function findNearestCodeGraphRoot(startPath: string): string | null;
+/**
+ * Create the .codegraph directory structure
+ * Note: Only throws if codegraph.db already exists, not just if .codegraph/ exists.
+ */
+export declare function createDirectory(projectRoot: string): void;
+/**
+ * Remove the .codegraph directory
+ */
+export declare function removeDirectory(projectRoot: string): void;
+/**
+ * Get all files in the .codegraph directory
+ */
+export declare function listDirectoryContents(projectRoot: string): string[];
+/**
+ * Get the total size of the .codegraph directory in bytes
+ */
+export declare function getDirectorySize(projectRoot: string): number;
+/**
+ * Ensure a subdirectory exists within .codegraph
+ */
+export declare function ensureSubdirectory(projectRoot: string, subdirName: string): string;
+/**
+ * Check if the .codegraph directory has valid structure
+ */
+export declare function validateDirectory(projectRoot: string): {
+    valid: boolean;
+    errors: string[];
+};
+//# sourceMappingURL=directory.d.ts.map

package/dist/errors.d.ts

@@ -0,0 +1,136 @@
+/**
+ * CodeGraph Error Classes
+ *
+ * Custom error types for better error handling and debugging.
+ *
+ * @module errors
+ *
+ * @example
+ * ```typescript
+ * import { FileError, ParseError, setLogger, silentLogger } from 'codegraph';
+ *
+ * // Catch specific error types
+ * try {
+ *   await cg.indexAll();
+ * } catch (error) {
+ *   if (error instanceof FileError) {
+ *     console.log(`File error at ${error.filePath}: ${error.message}`);
+ *   } else if (error instanceof ParseError) {
+ *     console.log(`Parse error at ${error.filePath}:${error.line}`);
+ *   }
+ * }
+ *
+ * // Disable logging for tests
+ * setLogger(silentLogger);
+ * ```
+ */
+/**
+ * Base error class for all CodeGraph errors.
+ *
+ * All CodeGraph-specific errors extend this class, allowing you to catch
+ * all CodeGraph errors with a single catch block.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await cg.indexAll();
+ * } catch (error) {
+ *   if (error instanceof CodeGraphError) {
+ *     console.log(`CodeGraph error [${error.code}]: ${error.message}`);
+ *   }
+ * }
+ * ```
+ */
+export declare class CodeGraphError extends Error {
+    /** Error code for categorization (e.g., 'FILE_ERROR', 'PARSE_ERROR') */
+    readonly code: string;
+    /** Additional context about the error */
+    readonly context?: Record<string, unknown>;
+    constructor(message: string, code: string, context?: Record<string, unknown>);
+}
+/**
+ * Error reading or accessing files
+ */
+export declare class FileError extends CodeGraphError {
+    readonly filePath: string;
+    constructor(message: string, filePath: string, cause?: Error);
+}
+/**
+ * Error parsing source code
+ */
+export declare class ParseError extends CodeGraphError {
+    readonly filePath: string;
+    readonly line?: number;
+    readonly column?: number;
+    constructor(message: string, filePath: string, options?: {
+        line?: number;
+        column?: number;
+        cause?: Error;
+    });
+}
+/**
+ * Error with database operations
+ */
+export declare class DatabaseError extends CodeGraphError {
+    readonly operation: string;
+    constructor(message: string, operation: string, cause?: Error);
+}
+/**
+ * Error with search operations
+ */
+export declare class SearchError extends CodeGraphError {
+    readonly query: string;
+    constructor(message: string, query: string, cause?: Error);
+}
+/**
+ * Error with vector/embedding operations
+ */
+export declare class VectorError extends CodeGraphError {
+    constructor(message: string, operation: string, cause?: Error);
+}
+/**
+ * Error with configuration
+ */
+export declare class ConfigError extends CodeGraphError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+/**
+ * Simple logger for CodeGraph operations
+ *
+ * By default, logs to console.warn for warnings and console.error for errors.
+ * Can be configured to use custom logging.
+ */
+export interface Logger {
+    debug(message: string, context?: Record<string, unknown>): void;
+    warn(message: string, context?: Record<string, unknown>): void;
+    error(message: string, context?: Record<string, unknown>): void;
+}
+/**
+ * Default console-based logger
+ */
+export declare const defaultLogger: Logger;
+/**
+ * Silent logger (no output) - useful for tests
+ */
+export declare const silentLogger: Logger;
+/**
+ * Set the global logger
+ */
+export declare function setLogger(logger: Logger): void;
+/**
+ * Get the current logger
+ */
+export declare function getLogger(): Logger;
+/**
+ * Log a debug message
+ */
+export declare function logDebug(message: string, context?: Record<string, unknown>): void;
+/**
+ * Log a warning message
+ */
+export declare function logWarn(message: string, context?: Record<string, unknown>): void;
+/**
+ * Log an error message
+ */
+export declare function logError(message: string, context?: Record<string, unknown>): void;
+//# sourceMappingURL=errors.d.ts.map

package/dist/extraction/dfm-extractor.d.ts

@@ -0,0 +1,31 @@
+import { ExtractionResult } from '../types';
+/**
+ * Custom extractor for Delphi DFM/FMX form files.
+ *
+ * DFM/FMX files describe the visual component hierarchy and event handler
+ * bindings. They use a simple text format (object/end blocks) that we parse
+ * with regex — no tree-sitter grammar exists for this format.
+ *
+ * Extracted information:
+ * - Components as NodeKind `component`
+ * - Nesting as EdgeKind `contains`
+ * - Event handlers (OnClick = MethodName) as UnresolvedReference → EdgeKind `references`
+ */
+export declare class DfmExtractor {
+    private filePath;
+    private source;
+    private nodes;
+    private edges;
+    private unresolvedReferences;
+    private errors;
+    constructor(filePath: string, source: string);
+    /**
+     * Extract components and event handler references from DFM/FMX source
+     */
+    extract(): ExtractionResult;
+    /** Create a file node for the DFM form file */
+    private createFileNode;
+    /** Parse object/end blocks and extract components + event handlers */
+    private parseComponents;
+}
+//# sourceMappingURL=dfm-extractor.d.ts.map

package/dist/extraction/generated-detection.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Generated-file detection for symbol-disambiguation down-ranking.
+ *
+ * When a query like "Send" matches 17 symbols across protobuf scaffolding,
+ * test mocks, and the hand-written implementation, the FTS ranker often
+ * surfaces the generated stubs first because their names are identical
+ * to the implementation's name (validated empirically on cosmos-sdk —
+ * see project_go_multi_module_audit memory). Generated stubs frequently
+ * have no body to trace from, so the agent ends up reading source anyway.
+ *
+ * This helper is a pure path-based classifier consulted at disambiguation
+ * time (findSymbol / findAllSymbols / codegraph_search formatting), NOT
+ * a hard filter — generated nodes are still in the graph and remain
+ * reachable; they just rank LAST when there's a real implementation
+ * with the same name.
+ *
+ * Scope: suffix patterns only. Most generated files follow the
+ * `<basename>.<tool>.<ext>` convention (`.pb.go`, `_grpc.pb.go`,
+ * `.g.dart`, `_pb2.py`), and that covers ~all of what we saw in the
+ * Go audit. A future addition would be scanning for the canonical
+ * `// Code generated by` header during extraction, for the rare files
+ * that defy the suffix convention.
+ */
+/**
+ * Whether `filePath` looks like a tool-generated source file based on
+ * its filename. Path-only — does not read content. The result is a
+ * relevance hint for disambiguation, not a hard claim.
+ */
+export declare function isGeneratedFile(filePath: string): boolean;
+//# sourceMappingURL=generated-detection.d.ts.map