@aroman22/codegraph-vba 1.3.3

package/dist/db/queries.d.ts

@@ -0,0 +1,402 @@
+/**
+ * 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 projectNameTokens;
+    private nodeCache;
+    private readonly maxCacheSize;
+    private stmts;
+    constructor(db: SqliteDatabase);
+    /** Set the normalized project-name tokens used to down-weight non-discriminative
+     * query words in path scoring (#720). Called once when the project opens. */
+    setProjectNameTokens(tokens: Set<string>): void;
+    /** The normalized project-name tokens (#720); empty if none were derived. */
+    getProjectNameTokens(): Set<string>;
+    /**
+     * 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[];
+    /**
+     * Stream every node of a kind one at a time (lazy) instead of materializing
+     * them all like {@link getNodesByKind}. For unbounded kinds (`function`,
+     * `method`) on a symbol-dense project the full array is gigabytes; the
+     * dynamic-edge synthesizers only scan-and-filter, so they iterate to keep
+     * memory O(1) in the node count rather than O(nodes) (#610).
+     */
+    iterateNodesByKind(kind: NodeKind): IterableIterator<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[];
+    private isEventHandlerNode;
+    /**
+     * 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[];
+    /**
+     * Distinct file paths that DEPEND ON `filePath`: every file containing a
+     * symbol with a cross-file edge (any kind except `contains`) into a symbol
+     * of this file. This is the file-level projection of the symbol dependency
+     * graph and the basis for blast-radius / `affected` test selection.
+     *
+     * It deliberately does NOT restrict to `imports` edges. In this graph an
+     * `imports` edge connects a file to its own local import declarations
+     * (it is always same-file), so an imports-only lookup returns zero
+     * cross-file dependents for every file. The real cross-file dependency
+     * signal is the resolved call/reference graph — calls, references,
+     * instantiates, extends, implements, overrides, type_of, returns,
+     * decorates — exactly what {@link GraphTraverser.getImpactRadius} traverses.
+     * `contains` is excluded: a parent containing a symbol does not *depend* on
+     * it. One indexed query (idx_nodes_file_path + idx_edges_target_kind).
+     */
+    getDependentFilePaths(filePath: string): string[];
+    /**
+     * Distinct file paths that `filePath` DEPENDS ON — the inverse of
+     * {@link getDependentFilePaths}: every file containing a symbol that a
+     * symbol of this file has a cross-file edge into. Same edge-kind rules
+     * (all kinds except `contains`); same reason imports-only is insufficient.
+     */
+    getDependencyFilePaths(filePath: string): string[];
+    /**
+     * Cross-file edges whose TARGET is a node in `filePath` and whose SOURCE is a
+     * node in a *different* file, paired with the target node's (name, kind) so a
+     * caller can re-resolve the edge to the re-indexed target's new ID (node IDs
+     * are `sha256(filePath:kind:name:line)`, so any line shift in the callee file
+     * changes target IDs and a naive re-insert by old ID silently drops them).
+     * Used by `storeExtractionResult` to preserve incoming edges across a file
+     * re-index (issue #899). Same edge-kind rules as
+     * {@link getDependentFilePaths}: all kinds except `contains`.
+     */
+    getCrossFileIncomingEdgesWithTarget(filePath: string): Array<Edge & {
+        targetName: string;
+        targetKind: NodeKind;
+    }>;
+    /**
+     * 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[];
+    /**
+     * Most recent index timestamp (ms since epoch) across all tracked files, or
+     * null when nothing is indexed yet. One indexed aggregate, no per-row scan. (#329)
+     */
+    getLastIndexedAt(): number | null;
+    /**
+     * 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,53 @@
+/**
+ * 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[];
+    /**
+     * Lazily yield result rows one at a time instead of materializing the whole
+     * set with `all()`. Use for unbounded scans (e.g. every function/method node)
+     * so memory stays O(1) in the row count rather than O(rows) — see #610, where
+     * `all()`-ing every symbol on a dense project spiked the heap into an OOM.
+     */
+    iterate(...params: any[]): IterableIterator<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,179 @@
+/**
+ * Directory Management
+ *
+ * Manages the .codegraph/ directory structure for CodeGraph data.
+ */
+/**
+ * Resolve the per-project data directory name, honoring the `CODEGRAPH_DIR`
+ * environment override (default `.codegraph`). The override is a single path
+ * segment that lives in the project root.
+ *
+ * Why this exists: two environments that share one working tree must NOT share
+ * one `.codegraph/` — most concretely Windows-native and WSL (issue #636). The
+ * daemon lockfile (`.codegraph/daemon.pid`) records a platform-specific pid and
+ * socket path (a Windows named pipe vs a WSL Unix socket), and SQLite file
+ * locking across the WSL2 ↔ Windows filesystem boundary is unreliable, so two
+ * daemons sharing one index risks corruption. Setting `CODEGRAPH_DIR=.codegraph-win`
+ * on one side gives each environment its own index in the same tree.
+ *
+ * Read live (not captured at load) so it is both process-accurate and testable.
+ * An override that isn't a plain directory name — empty, containing a path
+ * separator, `.`, `..`/traversal, or absolute — is ignored (we keep the
+ * default) rather than risk writing the index outside the project or into the
+ * project root itself; we warn once to stderr so the misconfiguration is seen.
+ */
+export declare function codeGraphDirName(): string;
+/**
+ * CodeGraph directory name — a load-time snapshot of {@link codeGraphDirName}.
+ * A running process's environment is fixed, so this equals the live value;
+ * it's kept as a stable string export for backward compatibility. Internal code
+ * resolves the name through {@link codeGraphDirName} / {@link getCodeGraphDir}
+ * so the `CODEGRAPH_DIR` override always applies.
+ */
+export declare const CODEGRAPH_DIR: string;
+/**
+ * Is `name` (a single path segment) a CodeGraph data directory? Matches the
+ * default `.codegraph`, the active `CODEGRAPH_DIR` override, and any
+ * `.codegraph-*` sibling. File-watching and the indexer skip ALL of these, so
+ * when two environments share one working tree (Windows + WSL, issue #636)
+ * neither indexes or watches the other's index directory.
+ */
+export declare function isCodeGraphDataDir(name: string): boolean;
+/**
+ * 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
+ */
+/**
+ * Reason a directory is unsafe to use as an index ROOT, or null when it's fine.
+ *
+ * Indexing your home directory or a filesystem root drags in caches, `Library`,
+ * every other project, etc. — a multi-GB index, constant file-watcher churn, and
+ * (pre-1.0 on macOS) a file-descriptor blowup that exhausted `kern.maxfiles` and
+ * took unrelated apps / the whole machine down (#845). The classic trigger:
+ * running the installer or `codegraph init` from `$HOME`, which auto-indexes the
+ * current directory. These are never intended project roots, so the installer
+ * and `init`/`index` refuse them (overridable with `--force`).
+ *
+ * Pure-ish (reads only `os.homedir()` + realpath) so it's easy to unit-test.
+ * The returned string is a human phrase that slots into "… looks like {reason}".
+ */
+export declare function unsafeIndexRootReason(projectRoot: string): string | null;
+export declare function findNearestCodeGraphRoot(startPath: string): string | null;
+/**
+ * Indexed sub-project roots beneath `root` (bounded breadth-first scan). For
+ * the monorepo case behind #964: the index lives in a CHILD
+ * (`packages/x/.codegraph/`), not at the workspace root the agent's cwd points
+ * at. Descent stops at the first indexed directory on a branch (a project's
+ * own sub-dirs aren't separate projects) and is bounded by depth + count so it
+ * never turns into a full-tree crawl on a large repo.
+ */
+export declare function findIndexedSubprojectRoots(root: string, opts?: {
+    maxDepth?: number;
+    max?: number;
+}): string[];
+/**
+ * Does `prompt` contain an explicit structural keyword (English or CJK)? A
+ * keyword is a strong, self-contained signal, so the front-load hook fires on it
+ * directly — no graph check needed. (A *code-token* match, by contrast, is only
+ * a candidate the hook verifies against the graph first; see {@link extractCodeTokens}.)
+ */
+export declare function hasStructuralKeyword(prompt: string): boolean;
+/**
+ * Identifier-shaped tokens in `prompt` — camelCase / PascalCase-with-inner-cap,
+ * snake_case, a `name(` call, or the two sides of an `a.b` member access. Naming
+ * a symbol is a code question whatever the surrounding human language, and these
+ * shapes almost never occur in ordinary prose, so they catch the common
+ * "<symbol> 的调用链?" / "where is <symbol> 定義" prompts no keyword list would.
+ *
+ * These are *candidates*, not a verdict: a tech brand like `JavaScript` or
+ * `GitHub` is identifier-shaped too, so the front-load hook checks each token
+ * against the actual index ({@link getNodesByName}) and only fires when one is a
+ * real symbol here — otherwise a brand-name prompt would inject ~16KB of
+ * low-relevance context (issue #994 follow-up). A doc/data filename ("README.md")
+ * is excluded from the member-access form since it's a file reference, not a symbol.
+ */
+export declare function extractCodeTokens(prompt: string): string[];
+/**
+ * Cheap, graph-free candidate gate for the front-load hook: could `prompt` be a
+ * structural / flow / impact / "where-how" question worth front-loading context
+ * for? True on an explicit keyword (English or CJK, issue #994) OR an
+ * identifier-shaped token. A keyword is sufficient to fire on its own; a
+ * token-only match is only a candidate the hook then verifies against the graph
+ * (a brand name like `JavaScript` is token-shaped but isn't a symbol). Every
+ * non-candidate prompt ("fix this typo", in any language) stays a zero-cost no-op.
+ */
+export declare function isStructuralPrompt(prompt: string): boolean;
+/**
+ * What the front-load hook should do for a prompt issued from a directory.
+ */
+export interface FrontloadPlan {
+    /** Open + explore this project and inject its source as context. `null` when
+     *  there's no single project to front-load (none indexed, or several indexed
+     *  sub-projects with no clear match — see {@link nudgeProjects}). */
+    exploreRoot: string | null;
+    /** Indexed sub-projects to surface in a "pass `projectPath`" nudge: the rest
+     *  of a monorepo's indexed projects alongside `exploreRoot`, or — when no one
+     *  project clearly matches — the full list (with `exploreRoot` null). */
+    nudgeProjects: string[];
+    /** True when the plan came from scanning DOWN into sub-projects (cwd itself
+     *  is not under any index) — the monorepo case, where a follow-up
+     *  `codegraph_explore` needs an explicit `projectPath`. */
+    viaSubScan: boolean;
+}
+/**
+ * Decide what the front-load hook injects for a `prompt` issued from `cwd`,
+ * shaped by where the `.codegraph/` index(es) actually are:
+ *   1. **cwd (or an ancestor) is indexed** → front-load that project. The
+ *      normal single-project / nested-file case.
+ *   2. **cwd isn't indexed but looks like a workspace root** → the indexes live
+ *      in sub-projects (the monorepo case behind #964). One indexed
+ *      sub-project → front-load it; several → front-load the one the prompt
+ *      names (by relative path like `packages/api`, or package directory name)
+ *      and nudge about the rest; several with no match → nudge the full list so
+ *      the agent passes `projectPath`, rather than guessing wrong.
+ *   3. **nothing indexed reachable** → do nothing (the agent's own tools apply).
+ */
+export declare function planFrontload(cwd: string, prompt: string): FrontloadPlan;
+/**
+ * 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