@vizalice/codegraph 1.5.0

package/dist/index.d.ts

@@ -0,0 +1,677 @@
+/**
+ * CodeGraph
+ *
+ * A local-first code intelligence system that builds a semantic
+ * knowledge graph from any codebase.
+ */
+import { Node, NodeKind, Edge, FileRecord, ExtractionResult, Subgraph, TraversalOptions, SearchOptions, SearchResult, SegmentMatch, Context, GraphStats, TaskInput, TaskContext, BuildContextOptions, FindRelevantContextOptions } from './types';
+import { IndexProgress, IndexResult, SyncResult } from './extraction';
+import { ResolutionResult } from './resolution';
+import { WatchOptions, PendingFile } from './sync';
+export * from './types';
+export { getDatabasePath, DatabaseConnection } from './db';
+export { QueryBuilder } from './db/queries';
+export { getCodeGraphDir, isInitialized, findNearestCodeGraphRoot, CODEGRAPH_DIR, } from './directory';
+export { IndexProgress, IndexResult, SyncResult } from './extraction';
+export { detectLanguage, isLanguageSupported, isGrammarLoaded, getSupportedLanguages, initGrammars, loadGrammarsForLanguages, loadAllGrammars } from './extraction';
+export { ResolutionResult } from './resolution';
+export { CodeGraphError, FileError, ParseError, DatabaseError, SearchError, VectorError, ConfigError, Logger, setLogger, getLogger, silentLogger, defaultLogger, } from './errors';
+export { Mutex, FileLock, processInBatches, debounce, throttle, MemoryMonitor } from './utils';
+export { FileWatcher, WatchOptions, PendingFile, LockUnavailableError } from './sync';
+export { MCPServer } from './mcp';
+/**
+ * Options for initializing a new CodeGraph project
+ */
+export interface InitOptions {
+    /** Whether to run initial indexing after init */
+    index?: boolean;
+    /** Progress callback for indexing */
+    onProgress?: (progress: IndexProgress) => void;
+}
+/**
+ * Options for opening an existing CodeGraph project
+ */
+export interface OpenOptions {
+    /** Whether to run sync if files have changed */
+    sync?: boolean;
+    /** Whether to run in read-only mode */
+    readOnly?: boolean;
+}
+/**
+ * Options for indexing
+ */
+export interface IndexOptions {
+    /** Progress callback */
+    onProgress?: (progress: IndexProgress) => void;
+    /** Abort signal for cancellation */
+    signal?: AbortSignal;
+    /** Enable verbose logging (worker lifecycle, memory, timeouts) */
+    verbose?: boolean;
+    /** Watcher fast path: reconcile ONLY these project-relative paths (see ExtractionOrchestrator.sync). */
+    paths?: string[];
+}
+/**
+ * Main CodeGraph class
+ *
+ * Provides the primary interface for interacting with the code knowledge graph.
+ */
+export declare class CodeGraph {
+    private db;
+    private queries;
+    private projectRoot;
+    private orchestrator;
+    private resolver;
+    private graphManager;
+    private traverser;
+    private contextBuilder;
+    private indexMutex;
+    private fileLock;
+    private watcher;
+    private constructor();
+    /**
+     * (Re)build the query/extraction/graph layers over the current `this.queries`
+     * (which wraps `this.db`). Factored out of the constructor so `reopenIfReplaced`
+     * can rebuild them against a fresh connection without duplicating the wiring.
+     * The path-based `fileLock` is independent of the DB handle, so it stays put.
+     */
+    private wireLayers;
+    /**
+     * Heal a stale database handle in place. If `.codegraph/` was removed and
+     * recreated at the SAME path while this instance held the DB open — a git
+     * worktree removed and re-added, or `rm -rf .codegraph` + `codegraph init` —
+     * our open fd points at the now-unlinked inode and can never see the new
+     * index, so every query returns the pre-removal snapshot until the process
+     * restarts (#925). When that's detected, open the live file at the same path,
+     * rebuild the query layers, and swap them IN PLACE, so every holder of this
+     * instance (the MCP daemon's default project, cached projectPath connections)
+     * heals without a restart. Returns true iff it reopened.
+     *
+     * POSIX-only in practice: `isReplacedOnDisk` never fires on Windows (an open
+     * file can't be unlinked there, and st_ino is unreliable).
+     */
+    reopenIfReplaced(): boolean;
+    /**
+     * Initialize a new CodeGraph project
+     *
+     * Creates the .CodeGraph directory, database, and configuration.
+     *
+     * @param projectRoot - Path to the project root directory
+     * @param options - Initialization options
+     * @returns A new CodeGraph instance
+     */
+    static init(projectRoot: string, options?: InitOptions): Promise<CodeGraph>;
+    /**
+     * Initialize synchronously (without indexing)
+     */
+    static initSync(projectRoot: string): CodeGraph;
+    /**
+     * Open an existing CodeGraph project
+     *
+     * @param projectRoot - Path to the project root directory
+     * @param options - Open options
+     * @returns A CodeGraph instance
+     */
+    static open(projectRoot: string, options?: OpenOptions): Promise<CodeGraph>;
+    /**
+     * Rebuild the project's database from scratch and return a fresh, empty
+     * instance — the "same result as a fresh init" semantics that `codegraph
+     * index` documents.
+     *
+     * Unlike `open()` followed by `clear()`, this DISCARDS the existing
+     * `.codegraph/codegraph.db` (and its `-wal`/`-shm` sidecars) before
+     * re-initializing, instead of opening the old database and DELETE-ing every
+     * row. On a large or pre-fix poisoned index — e.g. an old graph that scanned
+     * an ignored gitlink corpus (#1065) into ~1.6M nodes with a multi-GB WAL —
+     * the per-row `nodes_fts` delete-trigger churn blocks the main thread long
+     * enough to trip the #850 liveness watchdog before indexing even starts, so a
+     * full re-index could never recover the bad state (#1067). Discarding the
+     * files is O(1) regardless of size, reclaims the disk, and sidesteps opening
+     * (and running migrations against) the poisoned database entirely.
+     */
+    static recreate(projectRoot: string): Promise<CodeGraph>;
+    /**
+     * Open synchronously (without sync)
+     */
+    static openSync(projectRoot: string): CodeGraph;
+    /**
+     * Check if a directory has been initialized as a CodeGraph project
+     */
+    static isInitialized(projectRoot: string): boolean;
+    /**
+     * Close the CodeGraph instance and release resources
+     */
+    close(): void;
+    /**
+     * Get the project root directory
+     */
+    getProjectRoot(): string;
+    /**
+     * Index all files in the project
+     *
+     * Uses a mutex to prevent concurrent indexing operations.
+     */
+    indexAll(options?: IndexOptions): Promise<IndexResult>;
+    /**
+     * Index specific files
+     *
+     * Uses a mutex to prevent concurrent indexing operations.
+     */
+    indexFiles(filePaths: string[]): Promise<IndexResult>;
+    /**
+     * Sync with current file state (incremental update)
+     *
+     * Uses a mutex to prevent concurrent indexing operations.
+     */
+    sync(options?: IndexOptions): Promise<SyncResult>;
+    /**
+     * Check if an indexing operation is currently in progress
+     */
+    isIndexing(): boolean;
+    /**
+     * Start watching for file changes and auto-syncing.
+     *
+     * Uses native OS file events (FSEvents on macOS, inotify on Linux 19+,
+     * ReadDirectoryChangesW on Windows) with debouncing to avoid thrashing.
+     *
+     * @param options - Watch options (debounce delay, callbacks)
+     * @returns true if watching started successfully
+     */
+    watch(options?: WatchOptions): boolean;
+    /**
+     * Stop watching for file changes.
+     */
+    unwatch(): void;
+    /**
+     * Check if the file watcher is active.
+     */
+    isWatching(): boolean;
+    /**
+     * True once live watching has permanently degraded (OS watch-resource
+     * exhaustion, or a write lock held past the retry budget) and auto-sync is
+     * disabled until the next {@link watch} call. Distinct from `!isWatching()`:
+     * a stopped/never-started watcher is inactive but NOT degraded. MCP tools use
+     * this to surface a whole-index "results may be stale" notice, since
+     * `getPendingFiles()` goes empty once watching stops (#876).
+     */
+    isWatcherDegraded(): boolean;
+    /** The reason live watching degraded, or null if it is healthy (#876). */
+    getWatcherDegradedReason(): string | null;
+    /**
+     * Files seen by the file watcher since the last successful sync —
+     * the per-file "stale" signal MCP tools attach to responses so an agent
+     * can fall back to {@link Read} for just the affected file without
+     * waiting for a debounced sync to complete (issue #403).
+     *
+     * Returns an empty list when the watcher isn't active, or no events have
+     * arrived. Each entry includes `firstSeenMs` and `lastSeenMs` (wall-clock
+     * `Date.now()` values) so callers can render "edited Nms ago", plus an
+     * `indexing` flag indicating whether the in-flight sync (if any) will
+     * absorb that file.
+     */
+    getPendingFiles(): PendingFile[];
+    /**
+     * Resolves once the file watcher has installed its watch set. Useful for
+     * tests that need a deterministic boundary before asserting on
+     * `getPendingFiles()`. Resolves immediately when no watcher is active.
+     */
+    waitUntilWatcherReady(timeoutMs?: number): Promise<void>;
+    /**
+     * Get files that have changed since last index
+     */
+    getChangedFiles(): {
+        added: string[];
+        modified: string[];
+        removed: string[];
+    };
+    /**
+     * Most recent index timestamp (ms since epoch) across all tracked files, or
+     * null when nothing is indexed yet. Lets library consumers check index
+     * freshness without shelling out to `codegraph status --json`. (#329)
+     */
+    getLastIndexedAt(): number | null;
+    /**
+     * Completeness of the last full index run. `'complete'` is the only good
+     * state. `'indexing'` after the fact means a run was killed mid-index (OOM,
+     * SIGKILL, liveness watchdog) and the on-disk index is truncated;
+     * `'partial'` means the run finished but silently dropped files
+     * (discovered > indexed+skipped+errored); `'failed'` means it reported
+     * failure. `null` = index predates this marker. Surfaced by
+     * `codegraph status`.
+     */
+    getIndexState(): 'indexing' | 'complete' | 'partial' | 'failed' | null;
+    /**
+     * Which engine built the current index: the package version + extraction
+     * version stamped at the last full `indexAll`. Either field is null for an
+     * index built before stamping existed (treated as stale). See
+     * `extraction-version.ts` and `isIndexStale()`.
+     */
+    getIndexBuildInfo(): {
+        version: string | null;
+        extractionVersion: number | null;
+    };
+    /**
+     * True when the on-disk index was built by an engine whose extraction is
+     * older than the one now running — i.e. a re-index would add data a migration
+     * can't backfill. False when there's no index yet (nothing to refresh) or the
+     * stamp is current. This is the signal behind `codegraph status`'s re-index
+     * hint and `codegraph upgrade`'s reminder.
+     */
+    isIndexStale(): boolean;
+    /**
+     * Extract nodes and edges from source code (without storing)
+     */
+    extractFromSource(filePath: string, source: string): ExtractionResult;
+    /**
+     * Resolve unresolved references and create edges
+     *
+     * This method takes unresolved references from extraction and attempts
+     * to resolve them using multiple strategies:
+     * - Framework-specific patterns (React, Express, Laravel)
+     * - Import-based resolution
+     * - Name-based symbol matching
+     */
+    resolveReferences(onProgress?: (current: number, total: number) => void): ResolutionResult;
+    /**
+     * Resolve references in batches to keep memory bounded on large codebases.
+     * Processes chunks of unresolved refs, persisting results after each batch.
+     */
+    resolveReferencesBatched(onProgress?: (current: number, total: number) => void, onSynthesisProgress?: (done: number, total: number) => void, backpressure?: () => Promise<void> | null): Promise<ResolutionResult>;
+    /**
+     * References extracted but never attempted by a resolution pass. Zero on a
+     * healthy index — a completed pass consumes every pending row (resolving it
+     * or parking it as failed, #1240). Non-zero at rest means a pass was
+     * interrupted mid-run (killed indexer, crash — #1187), so some files' call
+     * edges are missing; the next `sync` sweeps them.
+     */
+    getPendingReferenceCount(): number;
+    /**
+     * Get detected frameworks in the project
+     */
+    getDetectedFrameworks(): string[];
+    /**
+     * Re-initialize the resolver (useful after adding new files)
+     */
+    reinitializeResolver(): void;
+    /**
+     * Get statistics about the knowledge graph
+     */
+    getStats(): GraphStats;
+    /**
+     * Active SQLite backend for this project's connection (`node-sqlite` — Node's
+     * built-in real-SQLite module). Surfaced via `codegraph status` and the
+     * `codegraph_status` MCP tool alongside the effective journal mode.
+     */
+    getBackend(): import('./db').SqliteBackend;
+    /**
+     * The journal mode actually in effect ('wal', 'delete', …). 'wal' means
+     * readers never block on a concurrent writer; anything else means they can,
+     * which is the precondition for the "database is locked" failures in issue
+     * #238. Surfaced via `codegraph status` and the `codegraph_status` MCP tool.
+     */
+    getJournalMode(): string;
+    /**
+     * Get a node by ID
+     */
+    getNode(id: string): Node | null;
+    /**
+     * Get all nodes in a file
+     */
+    getNodesInFile(filePath: string): Node[];
+    /**
+     * Get all nodes of a specific kind
+     */
+    getNodesByKind(kind: Node['kind']): Node[];
+    /**
+     * Get ALL nodes with an exact name (direct index lookup, not FTS-ranked/capped).
+     * Used to enumerate every overload of a heavily-overloaded name so the specific
+     * definition the caller wants is never dropped below a search cut.
+     */
+    getNodesByName(name: string): Node[];
+    /** Nodes whose name starts with `prefix` (index range scan, capped). */
+    getNodesByNamePrefix(prefix: string, limit?: number): Node[];
+    /**
+     * Nodes whose name CONTAINS `substring` (LIKE scan, ASCII-case-insensitive,
+     * shortest-first). The camel-infix lookup FTS can't do — `profileInfo`
+     * inside `getProfileInfoV2` is one FTS token (#1196).
+     */
+    getNodesByNameSubstring(substring: string, options?: {
+        kinds?: NodeKind[];
+        limit?: number;
+        excludePrefix?: boolean;
+    }): Node[];
+    /**
+     * Search nodes by text
+     */
+    searchNodes(query: string, options?: SearchOptions): SearchResult[];
+    /**
+     * Graph-derived prompt matching for the front-load hook's MEDIUM tier:
+     * which indexed symbols do these prose words name? "state machine des
+     * commandes" → `OrderStateMachine`, in any human language whose technical
+     * nouns are Latin script — no keyword list involved.
+     *
+     * Precision comes from the repo's own naming statistics, not vocabulary:
+     * - CO-OCCURRENCE: ≥2 words that are segments of the SAME name ("state" +
+     *   "machine" → OrderStateMachine) is strong evidence and always qualifies.
+     * - RARITY: a single matched word qualifies only when its segment is
+     *   discriminative here (≤ {@link SEGMENT_RARITY_CEILING} distinct names) —
+     *   "checkout" in a shop backend yes, "state" in a react app no.
+     * Every candidate is re-verified against `nodes` before being returned
+     * (vocab rows are proposals; deletions leave orphans by design), so a
+     * returned symbol is guaranteed to exist right now.
+     */
+    getSegmentMatches(words: string[], limit?: number): SegmentMatch[];
+    /** A single word ("state") can match hundreds of names in a big repo — that
+     *  is noise, not signal. Ceiling for the single-word tier; co-occurrence is
+     *  exempt because two words on one name is already discriminative. */
+    private static readonly SEGMENT_RARITY_CEILING;
+    /** Which of the prompt's original words match `name`'s segments (via
+     *  variants). Segments are recomputed in JS — a name-keyed vocab lookup
+     *  would scan the (segment, name) primary key. */
+    private wordsMatchingName;
+    /**
+     * One-shot upgrade heal for callers that open the graph WITHOUT syncing —
+     * concretely the prompt hook, whose MEDIUM tier reads the segment
+     * vocabulary: a database migrated from before the vocab table existed
+     * starts with it empty, and the only other backfill lives inside `sync()`,
+     * which such callers never run (#1142). Returns true when the vocab is
+     * usable (already populated — the overwhelmingly common one-SELECT case —
+     * or healed here); false when it isn't (empty graph, or another process
+     * holds the index lock — that process's own sync heals it).
+     */
+    healSegmentVocabIfEmpty(): Promise<boolean>;
+    /**
+     * Rebuild the segment vocabulary from the current graph, batched and
+     * yielding — the upgrade-heal path for indexes built before the vocab table
+     * existed. Runs inside the index mutex/lock (sync and
+     * healSegmentVocabIfEmpty hold them).
+     */
+    private rebuildNameSegmentVocab;
+    /**
+     * Normalized project-name tokens (go.mod / package.json / repo dir) used to
+     * down-weight the non-discriminative project name in search ranking (#720).
+     * Exposed so explore can exclude it from the PascalCase type-disambiguation
+     * bias, which would otherwise pull overloaded tokens toward whichever stack
+     * embeds the project name.
+     */
+    getProjectNameTokens(): Set<string>;
+    /**
+     * Find the project's "primary route file" — the file with the densest
+     * concentration of framework-emitted `route` nodes (≥3 routes, ≥30%
+     * of all non-test routes). Used to inline the routing config in
+     * `codegraph_explore` responses on small realworld template repos
+     * (rails-realworld, laravel-realworld, drupal-admintoolbar, …) where
+     * Glob+Read of `routes.rb`/`urls.py`/etc. otherwise beats codegraph.
+     */
+    getTopRouteFile(): {
+        filePath: string;
+        routeCount: number;
+        totalRoutes: number;
+    } | null;
+    /**
+     * Build a URL → handler routing manifest from the index. Each entry
+     * pairs a route node (URL + method) with its handler function/method
+     * via the `references` edge that framework resolvers emit. Returns
+     * null when fewer than 3 valid (non-test) routes exist.
+     */
+    getRoutingManifest(limit?: number): {
+        entries: Array<{
+            url: string;
+            handler: string;
+            handlerFile: string;
+            handlerLine: number;
+            handlerKind: string;
+        }>;
+        topHandlerFile: string | null;
+        topHandlerFileCount: number;
+        totalRoutes: number;
+    } | null;
+    /**
+     * Get outgoing edges from a node
+     */
+    getOutgoingEdges(nodeId: string): Edge[];
+    /**
+     * Get incoming edges to a node
+     */
+    getIncomingEdges(nodeId: string): Edge[];
+    /**
+     * Get a file record by path
+     */
+    getFile(filePath: string): FileRecord | null;
+    /**
+     * Get all tracked files
+     */
+    getFiles(): FileRecord[];
+    /**
+     * A `(path) => boolean` generated-file test over a BOUNDED candidate list,
+     * unioning the index-time content-banner flag with the filename convention
+     * (#1500). One query up front, O(1) per call after — built for use inside a
+     * ranking comparator, where re-querying per comparison would be quadratic.
+     *
+     * Pass every path you might ask about; a path outside the list falls back to
+     * the filename check alone.
+     */
+    generatedFilePredicate(filePaths: Iterable<string>): (filePath: string) => boolean;
+    /**
+     * A `(path) => boolean` ambient-declaration test over a BOUNDED candidate
+     * list: true for a file that declares nothing but types, originates no call
+     * edge, and that nothing in the index depends on — an ambient `.d.ts` of
+     * global shims, vendored typings, module augmentation (CG-28). Structural
+     * rather than extension-based, and deliberately narrow: see
+     * `QueryBuilder.getAmbientDeclarationPathsAmong` for why each condition is
+     * there, in particular why a `types.ts` the codebase imports is NOT flagged.
+     */
+    ambientDeclarationFilePredicate(filePaths: Iterable<string>): (filePath: string) => boolean;
+    /** How many indexed files are flagged tool-generated. Reported by `status`. */
+    getGeneratedFileCount(): number;
+    /**
+     * Get the context for a node (ancestors, children, references)
+     *
+     * Returns comprehensive context about a node including its containment
+     * hierarchy, children, incoming/outgoing references, type information,
+     * and relevant imports.
+     *
+     * @param nodeId - ID of the focal node
+     * @returns Context object with all related information
+     */
+    getContext(nodeId: string): Context;
+    /**
+     * Traverse the graph from a starting node
+     *
+     * Uses breadth-first search by default. Supports filtering by edge types,
+     * node types, and traversal direction.
+     *
+     * @param startId - Starting node ID
+     * @param options - Traversal options
+     * @returns Subgraph containing traversed nodes and edges
+     */
+    traverse(startId: string, options?: TraversalOptions): Subgraph;
+    /**
+     * Get the call graph for a function
+     *
+     * Returns both callers (functions that call this function) and
+     * callees (functions called by this function) up to the specified depth.
+     *
+     * @param nodeId - ID of the function/method node
+     * @param depth - Maximum depth in each direction (default: 2)
+     * @returns Subgraph containing the call graph
+     */
+    getCallGraph(nodeId: string, depth?: number): Subgraph;
+    /**
+     * Get the type hierarchy for a class/interface
+     *
+     * Returns both ancestors (types this extends/implements) and
+     * descendants (types that extend/implement this).
+     *
+     * @param nodeId - ID of the class/interface node
+     * @returns Subgraph containing the type hierarchy
+     */
+    getTypeHierarchy(nodeId: string): Subgraph;
+    /**
+     * Find all usages of a symbol
+     *
+     * Returns all nodes that reference the specified symbol through
+     * any edge type (calls, references, type_of, etc.).
+     *
+     * @param nodeId - ID of the symbol node
+     * @returns Array of nodes and edges that reference this symbol
+     */
+    findUsages(nodeId: string): Array<{
+        node: Node;
+        edge: Edge;
+    }>;
+    /**
+     * Get callers of a function/method
+     *
+     * @param nodeId - ID of the function/method node
+     * @param maxDepth - Maximum depth to traverse (default: 1)
+     * @returns Array of nodes that call this function
+     */
+    getCallers(nodeId: string, maxDepth?: number): Array<{
+        node: Node;
+        edge: Edge;
+    }>;
+    /**
+     * Get callees of a function/method
+     *
+     * @param nodeId - ID of the function/method node
+     * @param maxDepth - Maximum depth to traverse (default: 1)
+     * @returns Array of nodes called by this function
+     */
+    getCallees(nodeId: string, maxDepth?: number): Array<{
+        node: Node;
+        edge: Edge;
+    }>;
+    /**
+     * Calculate the impact radius of a node
+     *
+     * Returns all nodes that could be affected by changes to this node.
+     *
+     * @param nodeId - ID of the node
+     * @param maxDepth - Maximum depth to traverse (default: 3)
+     * @returns Subgraph containing potentially impacted nodes
+     */
+    getImpactRadius(nodeId: string, maxDepth?: number): Subgraph;
+    /**
+     * Find the shortest path between two nodes
+     *
+     * @param fromId - Starting node ID
+     * @param toId - Target node ID
+     * @param edgeKinds - Edge types to consider (all if empty)
+     * @returns Array of nodes and edges forming the path, or null if no path exists
+     */
+    findPath(fromId: string, toId: string, edgeKinds?: Edge['kind'][]): Array<{
+        node: Node;
+        edge: Edge | null;
+    }> | null;
+    /**
+     * Get ancestors of a node in the containment hierarchy
+     *
+     * @param nodeId - ID of the node
+     * @returns Array of ancestor nodes from immediate parent to root
+     */
+    getAncestors(nodeId: string): Node[];
+    /**
+     * Get immediate children of a node
+     *
+     * @param nodeId - ID of the node
+     * @returns Array of child nodes
+     */
+    getChildren(nodeId: string): Node[];
+    /**
+     * Get dependencies of a file
+     *
+     * @param filePath - Path to the file
+     * @returns Array of file paths this file depends on
+     */
+    getFileDependencies(filePath: string): string[];
+    /**
+     * Get dependents of a file
+     *
+     * @param filePath - Path to the file
+     * @returns Array of file paths that depend on this file
+     */
+    getFileDependents(filePath: string): string[];
+    /**
+     * Find circular dependencies in the codebase
+     *
+     * @returns Array of cycles, each cycle is an array of file paths
+     */
+    findCircularDependencies(): string[][];
+    /**
+     * Find dead code (unreferenced symbols)
+     *
+     * @param kinds - Node kinds to check (default: functions, methods, classes)
+     * @returns Array of unreferenced nodes
+     */
+    findDeadCode(kinds?: Node['kind'][]): Node[];
+    /**
+     * 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;
+    };
+    /**
+     * 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>;
+    /**
+     * Find relevant subgraph for a query
+     *
+     * Combines semantic search with graph traversal to find the most
+     * relevant nodes and their relationships for a given query.
+     *
+     * @param query - Natural language query describing the task
+     * @param options - Search and traversal options
+     * @returns Subgraph of relevant nodes and edges
+     */
+    findRelevantContext(query: string, options?: FindRelevantContextOptions): Promise<Subgraph>;
+    /**
+     * Build context for a task
+     *
+     * Creates comprehensive context by:
+     * 1. Running FTS search to find entry points
+     * 2. Expanding the graph around entry points
+     * 3. Extracting code blocks for key nodes
+     * 4. Formatting output for Claude
+     *
+     * @param input - Task description (string or {title, description})
+     * @param options - Build options (maxNodes, includeCode, format, etc.)
+     * @returns TaskContext object or formatted string (markdown/JSON)
+     */
+    buildContext(input: TaskInput, options?: BuildContextOptions): Promise<TaskContext | string>;
+    /**
+     * Optimize the database (vacuum and analyze)
+     */
+    optimize(): void;
+    /**
+     * Clear all data from the graph
+     */
+    clear(): void;
+    /**
+     * Alias for close() for backwards compatibility.
+     * @deprecated Use close() instead
+     */
+    destroy(): void;
+    /**
+     * Completely remove CodeGraph from the project.
+     * This closes the database and deletes the .CodeGraph directory.
+     *
+     * WARNING: This permanently deletes all CodeGraph data for the project.
+     */
+    uninitialize(): void;
+}
+export default CodeGraph;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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