@colbymchenry/codegraph 0.9.7 → 0.9.9
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +116 -32
- package/dist/bin/codegraph.d.ts +25 -0
- package/dist/bin/node-version-check.d.ts +37 -0
- package/dist/bin/uninstall.d.ts +14 -0
- package/dist/context/formatter.d.ts +30 -0
- package/dist/context/index.d.ts +119 -0
- package/dist/context/markers.d.ts +19 -0
- package/dist/db/index.d.ts +101 -0
- package/dist/db/migrations.d.ts +44 -0
- package/dist/db/queries.d.ts +344 -0
- package/dist/db/sqlite-adapter.d.ts +46 -0
- package/dist/directory.d.ts +57 -0
- package/dist/errors.d.ts +136 -0
- package/dist/extraction/dfm-extractor.d.ts +31 -0
- package/dist/extraction/generated-detection.d.ts +30 -0
- package/dist/extraction/grammars.d.ts +100 -0
- package/dist/extraction/index.d.ts +138 -0
- package/dist/extraction/languages/c-cpp.d.ts +4 -0
- package/dist/extraction/languages/csharp.d.ts +3 -0
- package/dist/extraction/languages/dart.d.ts +3 -0
- package/dist/extraction/languages/go.d.ts +3 -0
- package/dist/extraction/languages/index.d.ts +10 -0
- package/dist/extraction/languages/java.d.ts +3 -0
- package/dist/extraction/languages/javascript.d.ts +3 -0
- package/dist/extraction/languages/kotlin.d.ts +3 -0
- package/dist/extraction/languages/lua.d.ts +3 -0
- package/dist/extraction/languages/luau.d.ts +3 -0
- package/dist/extraction/languages/objc.d.ts +3 -0
- package/dist/extraction/languages/pascal.d.ts +3 -0
- package/dist/extraction/languages/php.d.ts +3 -0
- package/dist/extraction/languages/python.d.ts +3 -0
- package/dist/extraction/languages/ruby.d.ts +3 -0
- package/dist/extraction/languages/rust.d.ts +3 -0
- package/dist/extraction/languages/scala.d.ts +3 -0
- package/dist/extraction/languages/swift.d.ts +3 -0
- package/dist/extraction/languages/typescript.d.ts +3 -0
- package/dist/extraction/liquid-extractor.d.ts +52 -0
- package/dist/extraction/mybatis-extractor.d.ts +48 -0
- package/dist/extraction/parse-worker.d.ts +8 -0
- package/dist/extraction/svelte-extractor.d.ts +56 -0
- package/dist/extraction/tree-sitter-helpers.d.ts +28 -0
- package/dist/extraction/tree-sitter-types.d.ts +193 -0
- package/dist/extraction/tree-sitter.d.ts +317 -0
- package/dist/extraction/vue-extractor.d.ts +36 -0
- package/dist/extraction/wasm-runtime-flags.d.ts +38 -0
- package/dist/graph/index.d.ts +8 -0
- package/dist/graph/queries.d.ts +106 -0
- package/dist/graph/traversal.d.ts +127 -0
- package/dist/index.d.ts +498 -0
- package/dist/installer/config-writer.d.ts +28 -0
- package/dist/installer/index.d.ts +100 -0
- package/dist/installer/instructions-template.d.ts +18 -0
- package/dist/installer/targets/antigravity.d.ts +57 -0
- package/dist/installer/targets/claude.d.ts +56 -0
- package/dist/installer/targets/codex.d.ts +18 -0
- package/dist/installer/targets/cursor.d.ts +35 -0
- package/dist/installer/targets/gemini.d.ts +26 -0
- package/dist/installer/targets/hermes.d.ts +18 -0
- package/dist/installer/targets/kiro.d.ts +27 -0
- package/dist/installer/targets/opencode.d.ts +30 -0
- package/dist/installer/targets/registry.d.ts +35 -0
- package/dist/installer/targets/shared.d.ts +77 -0
- package/dist/installer/targets/toml.d.ts +52 -0
- package/dist/installer/targets/types.d.ts +101 -0
- package/dist/mcp/daemon-paths.d.ts +46 -0
- package/dist/mcp/daemon.d.ts +161 -0
- package/dist/mcp/engine.d.ts +105 -0
- package/dist/mcp/index.d.ts +112 -0
- package/dist/mcp/proxy.d.ts +81 -0
- package/dist/mcp/server-instructions.d.ts +19 -0
- package/dist/mcp/session.d.ts +77 -0
- package/dist/mcp/tools.d.ts +413 -0
- package/dist/mcp/transport.d.ts +188 -0
- package/dist/mcp/version.d.ts +19 -0
- package/dist/resolution/callback-synthesizer.d.ts +10 -0
- package/dist/resolution/frameworks/cargo-workspace.d.ts +18 -0
- package/dist/resolution/frameworks/csharp.d.ts +8 -0
- package/dist/resolution/frameworks/drupal.d.ts +51 -0
- package/dist/resolution/frameworks/expo-modules.d.ts +3 -0
- package/dist/resolution/frameworks/express.d.ts +8 -0
- package/dist/resolution/frameworks/fabric.d.ts +3 -0
- package/dist/resolution/frameworks/go.d.ts +8 -0
- package/dist/resolution/frameworks/index.d.ts +48 -0
- package/dist/resolution/frameworks/java.d.ts +8 -0
- package/dist/resolution/frameworks/laravel.d.ts +13 -0
- package/dist/resolution/frameworks/nestjs.d.ts +26 -0
- package/dist/resolution/frameworks/play.d.ts +19 -0
- package/dist/resolution/frameworks/python.d.ts +10 -0
- package/dist/resolution/frameworks/react-native.d.ts +3 -0
- package/dist/resolution/frameworks/react.d.ts +8 -0
- package/dist/resolution/frameworks/ruby.d.ts +8 -0
- package/dist/resolution/frameworks/rust.d.ts +8 -0
- package/dist/resolution/frameworks/svelte.d.ts +9 -0
- package/dist/resolution/frameworks/swift-objc.d.ts +37 -0
- package/dist/resolution/frameworks/swift.d.ts +10 -0
- package/dist/resolution/frameworks/vue.d.ts +9 -0
- package/dist/resolution/go-module.d.ts +26 -0
- package/dist/resolution/import-resolver.d.ts +68 -0
- package/dist/resolution/index.d.ts +116 -0
- package/dist/resolution/lru-cache.d.ts +24 -0
- package/dist/resolution/name-matcher.d.ts +32 -0
- package/dist/resolution/path-aliases.d.ts +68 -0
- package/dist/resolution/strip-comments.d.ts +27 -0
- package/dist/resolution/swift-objc-bridge.d.ts +134 -0
- package/dist/resolution/types.d.ts +209 -0
- package/dist/search/query-parser.d.ts +57 -0
- package/dist/search/query-utils.d.ts +71 -0
- package/dist/sync/git-hooks.d.ts +45 -0
- package/dist/sync/index.d.ts +19 -0
- package/dist/sync/watch-policy.d.ts +48 -0
- package/dist/sync/watcher.d.ts +191 -0
- package/dist/sync/worktree.d.ts +54 -0
- package/dist/types.d.ts +377 -0
- package/dist/ui/glyphs.d.ts +42 -0
- package/dist/ui/shimmer-progress.d.ts +11 -0
- package/dist/ui/shimmer-worker.d.ts +2 -0
- package/dist/ui/types.d.ts +17 -0
- package/dist/utils.d.ts +205 -0
- package/npm-sdk.js +75 -0
- package/package.json +18 -7
|
@@ -0,0 +1,191 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* File Watcher
|
|
3
|
+
*
|
|
4
|
+
* Watches the project directory for file changes and triggers debounced sync
|
|
5
|
+
* operations to keep the code graph up-to-date.
|
|
6
|
+
*
|
|
7
|
+
* Uses chokidar, whose `ignored` callback filters directories BEFORE they are
|
|
8
|
+
* watched — so we never register inotify watches on excluded trees like
|
|
9
|
+
* node_modules/, dist/, .git/ (fixes #276: recursive fs.watch exhausted the
|
|
10
|
+
* kernel watch budget on large repos). The ignore decision reuses the indexer's
|
|
11
|
+
* `buildDefaultIgnore` (built-in default-ignore dirs + the project's .gitignore)
|
|
12
|
+
* so the watcher watches exactly the set the indexer indexes — in particular,
|
|
13
|
+
* node_modules/build/cache dirs are excluded even when the repo has no
|
|
14
|
+
* .gitignore (#407), which a .gitignore-only filter would miss.
|
|
15
|
+
*/
|
|
16
|
+
/**
|
|
17
|
+
* Options for the file watcher
|
|
18
|
+
*/
|
|
19
|
+
export interface WatchOptions {
|
|
20
|
+
/**
|
|
21
|
+
* Debounce delay in milliseconds.
|
|
22
|
+
* After the last file change, wait this long before triggering sync.
|
|
23
|
+
* Default: 2000ms
|
|
24
|
+
*/
|
|
25
|
+
debounceMs?: number;
|
|
26
|
+
/**
|
|
27
|
+
* Callback when a sync completes (for logging/diagnostics).
|
|
28
|
+
*/
|
|
29
|
+
onSyncComplete?: (result: {
|
|
30
|
+
filesChanged: number;
|
|
31
|
+
durationMs: number;
|
|
32
|
+
}) => void;
|
|
33
|
+
/**
|
|
34
|
+
* Callback when a sync errors (for logging/diagnostics).
|
|
35
|
+
*/
|
|
36
|
+
onSyncError?: (error: Error) => void;
|
|
37
|
+
}
|
|
38
|
+
/**
|
|
39
|
+
* Thrown by a `syncFn` to signal that the underlying sync couldn't acquire
|
|
40
|
+
* the cross-process write lock (#449). The watcher treats this as "no
|
|
41
|
+
* progress" — preserves `pendingFiles`, skips `onSyncComplete`, and the
|
|
42
|
+
* `finally` block reschedules. Quiet (debug-only) because a long-running
|
|
43
|
+
* external indexer can hit this every debounce cycle.
|
|
44
|
+
*/
|
|
45
|
+
export declare class LockUnavailableError extends Error {
|
|
46
|
+
constructor(message?: string);
|
|
47
|
+
}
|
|
48
|
+
/**
|
|
49
|
+
* Per-file pending entry — tracks a source file the watcher saw an event for
|
|
50
|
+
* but hasn't yet synced into the index. Exposed via {@link FileWatcher.getPendingFiles}
|
|
51
|
+
* so MCP tool responses can mark stale results without forcing a wait.
|
|
52
|
+
*/
|
|
53
|
+
export interface PendingFile {
|
|
54
|
+
/** Project-relative POSIX path (e.g. "src/foo.ts"). */
|
|
55
|
+
path: string;
|
|
56
|
+
/** Wall-clock ms at the first event we saw for this path since the last sync. */
|
|
57
|
+
firstSeenMs: number;
|
|
58
|
+
/** Wall-clock ms at the most recent event we saw for this path. */
|
|
59
|
+
lastSeenMs: number;
|
|
60
|
+
/**
|
|
61
|
+
* True when a sync is currently in flight that began AFTER this file's most
|
|
62
|
+
* recent event — i.e. the next successful sync will pick it up. False when
|
|
63
|
+
* the file is still in the debounce window (no sync running yet).
|
|
64
|
+
*/
|
|
65
|
+
indexing: boolean;
|
|
66
|
+
}
|
|
67
|
+
/**
|
|
68
|
+
* FileWatcher monitors a project directory for changes and triggers
|
|
69
|
+
* debounced sync operations via a provided callback.
|
|
70
|
+
*
|
|
71
|
+
* Design goals:
|
|
72
|
+
* - Minimal resource usage (chokidar filters excluded directories before
|
|
73
|
+
* registering an inotify watch — see module docs / #276)
|
|
74
|
+
* - Debounced to avoid thrashing on rapid saves
|
|
75
|
+
* - Filters to supported source files by extension
|
|
76
|
+
* - Ignores .codegraph/ and .git/ regardless of .gitignore
|
|
77
|
+
* - Tracks per-file pending state so MCP tools can flag stale results
|
|
78
|
+
* without blocking on a sync (issue #403)
|
|
79
|
+
*/
|
|
80
|
+
export declare class FileWatcher {
|
|
81
|
+
private watcher;
|
|
82
|
+
private debounceTimer;
|
|
83
|
+
/**
|
|
84
|
+
* Files seen by the watcher since the last successful sync — populated on
|
|
85
|
+
* every chokidar event, cleared at the start of a sync, and re-populated by
|
|
86
|
+
* events that arrive mid-sync (or restored on sync failure). Keyed by the
|
|
87
|
+
* same project-relative POSIX path the rest of the codebase uses, so a
|
|
88
|
+
* caller can intersect tool-response file paths against this map cheaply.
|
|
89
|
+
*/
|
|
90
|
+
private pendingFiles;
|
|
91
|
+
/**
|
|
92
|
+
* Wall-clock ms at which the in-flight sync began. Combined with
|
|
93
|
+
* {@link pendingFiles}'s `lastSeenMs`, this distinguishes "still in the
|
|
94
|
+
* debounce window" (lastSeen > syncStarted, sync hasn't started yet for
|
|
95
|
+
* this edit) from "currently being indexed" (lastSeen <= syncStarted).
|
|
96
|
+
*/
|
|
97
|
+
private syncStartedMs;
|
|
98
|
+
private syncing;
|
|
99
|
+
private stopped;
|
|
100
|
+
/**
|
|
101
|
+
* False until chokidar fires its `ready` event. Gates `pendingFiles`
|
|
102
|
+
* insertion so the initial crawl's `add` events (one per pre-existing
|
|
103
|
+
* source file) don't pollute the per-file staleness signal. The events
|
|
104
|
+
* still flow into `scheduleSync()` to preserve the previous "initial
|
|
105
|
+
* scan triggers a reconciling sync" behavior.
|
|
106
|
+
*/
|
|
107
|
+
private chokidarReady;
|
|
108
|
+
/**
|
|
109
|
+
* Callbacks that resolve when chokidar fires `ready`. Used by tests (and
|
|
110
|
+
* any production caller that cares about a clean baseline) to deterministically
|
|
111
|
+
* gate on the end of the initial scan instead of guessing at a sleep duration.
|
|
112
|
+
*/
|
|
113
|
+
private readyWaiters;
|
|
114
|
+
private ignoreMatcher;
|
|
115
|
+
private readonly projectRoot;
|
|
116
|
+
private readonly debounceMs;
|
|
117
|
+
private readonly syncFn;
|
|
118
|
+
private readonly onSyncComplete?;
|
|
119
|
+
private readonly onSyncError?;
|
|
120
|
+
constructor(projectRoot: string, syncFn: () => Promise<{
|
|
121
|
+
filesChanged: number;
|
|
122
|
+
durationMs: number;
|
|
123
|
+
}>, options?: WatchOptions);
|
|
124
|
+
/**
|
|
125
|
+
* Start watching for file changes.
|
|
126
|
+
* Returns true if watching started successfully, false otherwise.
|
|
127
|
+
*/
|
|
128
|
+
start(): boolean;
|
|
129
|
+
/** Our own dirs are always ignored, regardless of .gitignore. */
|
|
130
|
+
private isAlwaysIgnored;
|
|
131
|
+
/**
|
|
132
|
+
* chokidar `ignored` predicate — true for any path that should NOT be watched.
|
|
133
|
+
* Uses chokidar's provided `stats` to decide directory-vs-file so a dir-only
|
|
134
|
+
* rule like `build/` matches, without an extra `statSync` per path.
|
|
135
|
+
*/
|
|
136
|
+
private shouldIgnore;
|
|
137
|
+
/**
|
|
138
|
+
* Stop watching for file changes.
|
|
139
|
+
*/
|
|
140
|
+
stop(): void;
|
|
141
|
+
/**
|
|
142
|
+
* Whether the watcher is currently active.
|
|
143
|
+
*/
|
|
144
|
+
isActive(): boolean;
|
|
145
|
+
/**
|
|
146
|
+
* Resolves once chokidar has fired its `ready` event (or immediately if
|
|
147
|
+
* it has already done so). Useful for tests that need a deterministic
|
|
148
|
+
* boundary before asserting on `pendingFiles` — guessing a sleep duration
|
|
149
|
+
* is flaky under load because chokidar can take longer than expected to
|
|
150
|
+
* finish its initial crawl on slow filesystems / parallel test runs.
|
|
151
|
+
*
|
|
152
|
+
* Production callers don't need this: `pendingFiles` is read continuously,
|
|
153
|
+
* the staleness banner is always correct (empty or populated), and the
|
|
154
|
+
* initial-scan window is a small one-time startup cost.
|
|
155
|
+
*/
|
|
156
|
+
waitUntilReady(timeoutMs?: number): Promise<void>;
|
|
157
|
+
/**
|
|
158
|
+
* Schedule a debounced sync.
|
|
159
|
+
*/
|
|
160
|
+
private scheduleSync;
|
|
161
|
+
/**
|
|
162
|
+
* Flush pending changes by running sync.
|
|
163
|
+
*
|
|
164
|
+
* pendingFiles is NOT cleared at the start of sync — entries are removed
|
|
165
|
+
* only after sync commits successfully, and only for entries whose
|
|
166
|
+
* lastSeenMs <= syncStartedMs. That way, a query that arrives mid-sync
|
|
167
|
+
* still sees the affected files marked stale (the DB hasn't been updated
|
|
168
|
+
* yet), and an event that lands mid-sync persists into the follow-up.
|
|
169
|
+
*
|
|
170
|
+
* On sync failure pendingFiles is left untouched — every edit is still
|
|
171
|
+
* unindexed, and the rescheduled sync will absorb the same set next time.
|
|
172
|
+
*/
|
|
173
|
+
private flush;
|
|
174
|
+
/**
|
|
175
|
+
* Snapshot of files seen by the watcher since the last successful sync.
|
|
176
|
+
*
|
|
177
|
+
* Used by MCP tool responses to mark stale results without blocking on a
|
|
178
|
+
* sync: a tool that returns a hit in `src/foo.ts` while `src/foo.ts` is in
|
|
179
|
+
* this list tells the agent "Read this file directly, the index lags."
|
|
180
|
+
*
|
|
181
|
+
* `indexing` is true when a sync is currently in flight whose start time is
|
|
182
|
+
* AFTER this file's most recent event — i.e. that sync will absorb the
|
|
183
|
+
* edit. False means the file is still inside the debounce window and no
|
|
184
|
+
* sync has started yet (a follow-up call a few hundred ms later may show
|
|
185
|
+
* `indexing: true` or the file may have left the list entirely).
|
|
186
|
+
*
|
|
187
|
+
* Cheap: O(pendingFiles.size), no I/O, no locks.
|
|
188
|
+
*/
|
|
189
|
+
getPendingFiles(): PendingFile[];
|
|
190
|
+
}
|
|
191
|
+
//# sourceMappingURL=watcher.d.ts.map
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Git Worktree Awareness
|
|
3
|
+
*
|
|
4
|
+
* A CodeGraph index lives in a `.codegraph/` directory and is resolved by
|
|
5
|
+
* walking up parent directories to the nearest one (see
|
|
6
|
+
* `findNearestCodeGraphRoot`). That walk is unaware of git worktrees: when a
|
|
7
|
+
* worktree is created *inside* the main checkout (e.g. some tools place them
|
|
8
|
+
* under `.gitignore`d paths like `.claude/worktrees/<name>/`), a command run
|
|
9
|
+
* from the worktree walks up and silently resolves the MAIN checkout's index.
|
|
10
|
+
*
|
|
11
|
+
* Every query then returns results from the main tree's code — usually a
|
|
12
|
+
* different branch — rather than the worktree the user is actually editing.
|
|
13
|
+
* Symbols added or changed only in the worktree are invisible. This module
|
|
14
|
+
* detects that "borrowed index" situation so callers can warn about it.
|
|
15
|
+
*
|
|
16
|
+
* Detection is best-effort: when git is unavailable or the path isn't a repo,
|
|
17
|
+
* it reports "no mismatch" and callers carry on unchanged.
|
|
18
|
+
*/
|
|
19
|
+
/**
|
|
20
|
+
* Absolute, symlink-resolved toplevel of the git working tree that `dir`
|
|
21
|
+
* belongs to, or null when `dir` isn't inside a git repo (or git is missing).
|
|
22
|
+
*
|
|
23
|
+
* `git rev-parse --show-toplevel` returns the per-worktree root: the main
|
|
24
|
+
* checkout and each linked worktree report their own distinct directory, which
|
|
25
|
+
* is exactly the distinction this module relies on.
|
|
26
|
+
*/
|
|
27
|
+
export declare function gitWorktreeRoot(dir: string): string | null;
|
|
28
|
+
export interface WorktreeIndexMismatch {
|
|
29
|
+
/** The git working tree the command was run from. */
|
|
30
|
+
worktreeRoot: string;
|
|
31
|
+
/** The (different) working tree whose `.codegraph` index is being used. */
|
|
32
|
+
indexRoot: string;
|
|
33
|
+
}
|
|
34
|
+
/**
|
|
35
|
+
* Detect when `startPath` lives in one git working tree but the resolved
|
|
36
|
+
* CodeGraph index (`indexRoot`) belongs to a *different* working tree.
|
|
37
|
+
*
|
|
38
|
+
* Returns null — meaning "nothing to warn about" — when:
|
|
39
|
+
* - `startPath` isn't in a git repo (or git is unavailable),
|
|
40
|
+
* - the index already lives in `startPath`'s own working tree, or
|
|
41
|
+
* - `indexRoot` isn't itself a working-tree root (an unrelated parent dir
|
|
42
|
+
* that merely happens to contain a `.codegraph/`), which keeps non-git
|
|
43
|
+
* and monorepo-subdir layouts from producing false warnings.
|
|
44
|
+
*/
|
|
45
|
+
export declare function detectWorktreeIndexMismatch(startPath: string, indexRoot: string): WorktreeIndexMismatch | null;
|
|
46
|
+
/** One-line-per-fact warning describing a detected mismatch. */
|
|
47
|
+
export declare function worktreeMismatchWarning(m: WorktreeIndexMismatch): string;
|
|
48
|
+
/**
|
|
49
|
+
* Compact, single-line variant for prefixing a tool's result. Read tools
|
|
50
|
+
* return their answer inline, so the heads-up has to ride on the same payload
|
|
51
|
+
* the agent is already reading — a multi-line block would bury the result.
|
|
52
|
+
*/
|
|
53
|
+
export declare function worktreeMismatchNotice(m: WorktreeIndexMismatch): string;
|
|
54
|
+
//# sourceMappingURL=worktree.d.ts.map
|
package/dist/types.d.ts
ADDED
|
@@ -0,0 +1,377 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* CodeGraph Type Definitions
|
|
3
|
+
*
|
|
4
|
+
* Core types for the semantic knowledge graph system.
|
|
5
|
+
*/
|
|
6
|
+
/**
|
|
7
|
+
* Types of nodes in the knowledge graph.
|
|
8
|
+
*
|
|
9
|
+
* Defined as a runtime-iterable `as const` array so the same source
|
|
10
|
+
* of truth backs both the TS type and any runtime validation
|
|
11
|
+
* (e.g. the search query parser).
|
|
12
|
+
*/
|
|
13
|
+
export declare const NODE_KINDS: readonly ["file", "module", "class", "struct", "interface", "trait", "protocol", "function", "method", "property", "field", "variable", "constant", "enum", "enum_member", "type_alias", "namespace", "parameter", "import", "export", "route", "component"];
|
|
14
|
+
export type NodeKind = (typeof NODE_KINDS)[number];
|
|
15
|
+
/**
|
|
16
|
+
* Types of edges (relationships) between nodes
|
|
17
|
+
*/
|
|
18
|
+
export type EdgeKind = 'contains' | 'calls' | 'imports' | 'exports' | 'extends' | 'implements' | 'references' | 'type_of' | 'returns' | 'instantiates' | 'overrides' | 'decorates';
|
|
19
|
+
/**
|
|
20
|
+
* Supported programming languages. See NODE_KINDS for why this is a
|
|
21
|
+
* runtime-iterable const array.
|
|
22
|
+
*/
|
|
23
|
+
export declare const LANGUAGES: readonly ["typescript", "javascript", "tsx", "jsx", "python", "go", "rust", "java", "c", "cpp", "csharp", "php", "ruby", "swift", "kotlin", "dart", "svelte", "vue", "liquid", "pascal", "scala", "lua", "luau", "objc", "yaml", "twig", "xml", "properties", "unknown"];
|
|
24
|
+
export type Language = (typeof LANGUAGES)[number];
|
|
25
|
+
/**
|
|
26
|
+
* A node in the knowledge graph representing a code symbol
|
|
27
|
+
*/
|
|
28
|
+
export interface Node {
|
|
29
|
+
/** Unique identifier (hash of file path + qualified name) */
|
|
30
|
+
id: string;
|
|
31
|
+
/** Type of code element */
|
|
32
|
+
kind: NodeKind;
|
|
33
|
+
/** Simple name (e.g., "calculateTotal") */
|
|
34
|
+
name: string;
|
|
35
|
+
/** Fully qualified name (e.g., "src/utils.ts::MathHelper.calculateTotal") */
|
|
36
|
+
qualifiedName: string;
|
|
37
|
+
/** File path relative to project root */
|
|
38
|
+
filePath: string;
|
|
39
|
+
/** Programming language */
|
|
40
|
+
language: Language;
|
|
41
|
+
/** Starting line number (1-indexed) */
|
|
42
|
+
startLine: number;
|
|
43
|
+
/** Ending line number (1-indexed) */
|
|
44
|
+
endLine: number;
|
|
45
|
+
/** Starting column (0-indexed) */
|
|
46
|
+
startColumn: number;
|
|
47
|
+
/** Ending column (0-indexed) */
|
|
48
|
+
endColumn: number;
|
|
49
|
+
/** Documentation string if present */
|
|
50
|
+
docstring?: string;
|
|
51
|
+
/** Function/method signature */
|
|
52
|
+
signature?: string;
|
|
53
|
+
/** Visibility modifier */
|
|
54
|
+
visibility?: 'public' | 'private' | 'protected' | 'internal';
|
|
55
|
+
/** Whether symbol is exported */
|
|
56
|
+
isExported?: boolean;
|
|
57
|
+
/** Whether symbol is async */
|
|
58
|
+
isAsync?: boolean;
|
|
59
|
+
/** Whether symbol is static */
|
|
60
|
+
isStatic?: boolean;
|
|
61
|
+
/** Whether symbol is abstract */
|
|
62
|
+
isAbstract?: boolean;
|
|
63
|
+
/** Decorators/annotations applied */
|
|
64
|
+
decorators?: string[];
|
|
65
|
+
/** Generic type parameters */
|
|
66
|
+
typeParameters?: string[];
|
|
67
|
+
/** When the node was last updated */
|
|
68
|
+
updatedAt: number;
|
|
69
|
+
}
|
|
70
|
+
/**
|
|
71
|
+
* An edge representing a relationship between two nodes
|
|
72
|
+
*/
|
|
73
|
+
export interface Edge {
|
|
74
|
+
/** Source node ID */
|
|
75
|
+
source: string;
|
|
76
|
+
/** Target node ID */
|
|
77
|
+
target: string;
|
|
78
|
+
/** Type of relationship */
|
|
79
|
+
kind: EdgeKind;
|
|
80
|
+
/** Additional context about the relationship */
|
|
81
|
+
metadata?: Record<string, unknown>;
|
|
82
|
+
/** Line number where relationship occurs (e.g., call site) */
|
|
83
|
+
line?: number;
|
|
84
|
+
/** Column number where relationship occurs */
|
|
85
|
+
column?: number;
|
|
86
|
+
/** How this edge was created */
|
|
87
|
+
provenance?: 'tree-sitter' | 'scip' | 'heuristic';
|
|
88
|
+
}
|
|
89
|
+
/**
|
|
90
|
+
* Metadata about a tracked file
|
|
91
|
+
*/
|
|
92
|
+
export interface FileRecord {
|
|
93
|
+
/** File path relative to project root */
|
|
94
|
+
path: string;
|
|
95
|
+
/** Content hash for change detection */
|
|
96
|
+
contentHash: string;
|
|
97
|
+
/** Detected language */
|
|
98
|
+
language: Language;
|
|
99
|
+
/** File size in bytes */
|
|
100
|
+
size: number;
|
|
101
|
+
/** Last modification timestamp */
|
|
102
|
+
modifiedAt: number;
|
|
103
|
+
/** When last indexed */
|
|
104
|
+
indexedAt: number;
|
|
105
|
+
/** Number of nodes extracted */
|
|
106
|
+
nodeCount: number;
|
|
107
|
+
/** Any extraction errors */
|
|
108
|
+
errors?: ExtractionError[];
|
|
109
|
+
}
|
|
110
|
+
/**
|
|
111
|
+
* Result from parsing a source file
|
|
112
|
+
*/
|
|
113
|
+
export interface ExtractionResult {
|
|
114
|
+
/** Extracted nodes */
|
|
115
|
+
nodes: Node[];
|
|
116
|
+
/** Extracted edges */
|
|
117
|
+
edges: Edge[];
|
|
118
|
+
/** References that couldn't be resolved yet */
|
|
119
|
+
unresolvedReferences: UnresolvedReference[];
|
|
120
|
+
/** Any errors during extraction */
|
|
121
|
+
errors: ExtractionError[];
|
|
122
|
+
/** Extraction duration in milliseconds */
|
|
123
|
+
durationMs: number;
|
|
124
|
+
}
|
|
125
|
+
/**
|
|
126
|
+
* Error during code extraction
|
|
127
|
+
*/
|
|
128
|
+
export interface ExtractionError {
|
|
129
|
+
/** Error message */
|
|
130
|
+
message: string;
|
|
131
|
+
/** File path where the error occurred */
|
|
132
|
+
filePath?: string;
|
|
133
|
+
/** Line number if available */
|
|
134
|
+
line?: number;
|
|
135
|
+
/** Column number if available */
|
|
136
|
+
column?: number;
|
|
137
|
+
/** Error severity */
|
|
138
|
+
severity: 'error' | 'warning';
|
|
139
|
+
/** Error code for categorization */
|
|
140
|
+
code?: string;
|
|
141
|
+
}
|
|
142
|
+
/**
|
|
143
|
+
* A reference that couldn't be resolved during extraction
|
|
144
|
+
*/
|
|
145
|
+
export interface UnresolvedReference {
|
|
146
|
+
/** ID of the node containing the reference */
|
|
147
|
+
fromNodeId: string;
|
|
148
|
+
/** Name being referenced */
|
|
149
|
+
referenceName: string;
|
|
150
|
+
/** Type of reference (call, type, import, etc.) */
|
|
151
|
+
referenceKind: EdgeKind;
|
|
152
|
+
/** Location of the reference */
|
|
153
|
+
line: number;
|
|
154
|
+
column: number;
|
|
155
|
+
/** File path where reference occurs (denormalized for performance) */
|
|
156
|
+
filePath?: string;
|
|
157
|
+
/** Language of the source file (denormalized for performance) */
|
|
158
|
+
language?: Language;
|
|
159
|
+
/** Possible qualified names it might resolve to */
|
|
160
|
+
candidates?: string[];
|
|
161
|
+
}
|
|
162
|
+
/**
|
|
163
|
+
* A subgraph containing a subset of the knowledge graph
|
|
164
|
+
*/
|
|
165
|
+
export interface Subgraph {
|
|
166
|
+
/** Nodes in this subgraph */
|
|
167
|
+
nodes: Map<string, Node>;
|
|
168
|
+
/** Edges in this subgraph */
|
|
169
|
+
edges: Edge[];
|
|
170
|
+
/** Root node IDs (entry points) */
|
|
171
|
+
roots: string[];
|
|
172
|
+
/**
|
|
173
|
+
* Retrieval confidence for context-style queries. `'low'` means the query
|
|
174
|
+
* resolved only to isolated common-word matches (no entry point corroborated
|
|
175
|
+
* by 2+ distinct query terms) — callers should surface an honest handoff to
|
|
176
|
+
* explore/trace rather than present the results as comprehensive. Undefined
|
|
177
|
+
* for graph traversals that don't run the search-ranking path.
|
|
178
|
+
*/
|
|
179
|
+
confidence?: 'high' | 'low';
|
|
180
|
+
}
|
|
181
|
+
/**
|
|
182
|
+
* Options for graph traversal
|
|
183
|
+
*/
|
|
184
|
+
export interface TraversalOptions {
|
|
185
|
+
/** Maximum depth to traverse (default: Infinity) */
|
|
186
|
+
maxDepth?: number;
|
|
187
|
+
/** Edge types to follow (default: all) */
|
|
188
|
+
edgeKinds?: EdgeKind[];
|
|
189
|
+
/** Node types to include (default: all) */
|
|
190
|
+
nodeKinds?: NodeKind[];
|
|
191
|
+
/** Direction of traversal */
|
|
192
|
+
direction?: 'outgoing' | 'incoming' | 'both';
|
|
193
|
+
/** Maximum nodes to return */
|
|
194
|
+
limit?: number;
|
|
195
|
+
/** Whether to include the starting node */
|
|
196
|
+
includeStart?: boolean;
|
|
197
|
+
}
|
|
198
|
+
/**
|
|
199
|
+
* Options for searching the graph
|
|
200
|
+
*/
|
|
201
|
+
export interface SearchOptions {
|
|
202
|
+
/** Node types to search */
|
|
203
|
+
kinds?: NodeKind[];
|
|
204
|
+
/** Languages to include */
|
|
205
|
+
languages?: Language[];
|
|
206
|
+
/** File path patterns to include */
|
|
207
|
+
includePatterns?: string[];
|
|
208
|
+
/** File path patterns to exclude */
|
|
209
|
+
excludePatterns?: string[];
|
|
210
|
+
/** Maximum results to return */
|
|
211
|
+
limit?: number;
|
|
212
|
+
/** Offset for pagination */
|
|
213
|
+
offset?: number;
|
|
214
|
+
/** Whether search is case-sensitive */
|
|
215
|
+
caseSensitive?: boolean;
|
|
216
|
+
}
|
|
217
|
+
/**
|
|
218
|
+
* A search result with relevance scoring
|
|
219
|
+
*/
|
|
220
|
+
export interface SearchResult {
|
|
221
|
+
/** Matching node */
|
|
222
|
+
node: Node;
|
|
223
|
+
/** Relevance score (0-1) */
|
|
224
|
+
score: number;
|
|
225
|
+
/** Matched text snippets for highlighting */
|
|
226
|
+
highlights?: string[];
|
|
227
|
+
}
|
|
228
|
+
/**
|
|
229
|
+
* Context information for code understanding
|
|
230
|
+
*/
|
|
231
|
+
export interface Context {
|
|
232
|
+
/** Primary node being examined */
|
|
233
|
+
focal: Node;
|
|
234
|
+
/** Nodes containing the focal node (file, class, etc.) */
|
|
235
|
+
ancestors: Node[];
|
|
236
|
+
/** Nodes directly contained by focal node */
|
|
237
|
+
children: Node[];
|
|
238
|
+
/** Incoming references (who calls/uses this) */
|
|
239
|
+
incomingRefs: Array<{
|
|
240
|
+
node: Node;
|
|
241
|
+
edge: Edge;
|
|
242
|
+
}>;
|
|
243
|
+
/** Outgoing references (what this calls/uses) */
|
|
244
|
+
outgoingRefs: Array<{
|
|
245
|
+
node: Node;
|
|
246
|
+
edge: Edge;
|
|
247
|
+
}>;
|
|
248
|
+
/** Related type information */
|
|
249
|
+
types: Node[];
|
|
250
|
+
/** Relevant imports */
|
|
251
|
+
imports: Node[];
|
|
252
|
+
}
|
|
253
|
+
/**
|
|
254
|
+
* A block of code with context
|
|
255
|
+
*/
|
|
256
|
+
export interface CodeBlock {
|
|
257
|
+
/** The code content */
|
|
258
|
+
content: string;
|
|
259
|
+
/** File path */
|
|
260
|
+
filePath: string;
|
|
261
|
+
/** Starting line */
|
|
262
|
+
startLine: number;
|
|
263
|
+
/** Ending line */
|
|
264
|
+
endLine: number;
|
|
265
|
+
/** Language for syntax highlighting */
|
|
266
|
+
language: Language;
|
|
267
|
+
/** Associated node if extracted */
|
|
268
|
+
node?: Node;
|
|
269
|
+
}
|
|
270
|
+
/**
|
|
271
|
+
* Database schema version info
|
|
272
|
+
*/
|
|
273
|
+
export interface SchemaVersion {
|
|
274
|
+
/** Current schema version */
|
|
275
|
+
version: number;
|
|
276
|
+
/** When schema was created/updated */
|
|
277
|
+
appliedAt: number;
|
|
278
|
+
/** Description of this version */
|
|
279
|
+
description?: string;
|
|
280
|
+
}
|
|
281
|
+
/**
|
|
282
|
+
* Statistics about the knowledge graph
|
|
283
|
+
*/
|
|
284
|
+
export interface GraphStats {
|
|
285
|
+
/** Total number of nodes */
|
|
286
|
+
nodeCount: number;
|
|
287
|
+
/** Total number of edges */
|
|
288
|
+
edgeCount: number;
|
|
289
|
+
/** Number of tracked files */
|
|
290
|
+
fileCount: number;
|
|
291
|
+
/** Node counts by kind */
|
|
292
|
+
nodesByKind: Record<NodeKind, number>;
|
|
293
|
+
/** Edge counts by kind */
|
|
294
|
+
edgesByKind: Record<EdgeKind, number>;
|
|
295
|
+
/** File counts by language */
|
|
296
|
+
filesByLanguage: Record<Language, number>;
|
|
297
|
+
/** Database size in bytes */
|
|
298
|
+
dbSizeBytes: number;
|
|
299
|
+
/** Last update timestamp */
|
|
300
|
+
lastUpdated: number;
|
|
301
|
+
}
|
|
302
|
+
/**
|
|
303
|
+
* Input for building task context
|
|
304
|
+
*/
|
|
305
|
+
export type TaskInput = string | {
|
|
306
|
+
title: string;
|
|
307
|
+
description?: string;
|
|
308
|
+
};
|
|
309
|
+
/**
|
|
310
|
+
* Options for building task context
|
|
311
|
+
*/
|
|
312
|
+
export interface BuildContextOptions {
|
|
313
|
+
/** Maximum number of nodes to include (default: 50) */
|
|
314
|
+
maxNodes?: number;
|
|
315
|
+
/** Maximum number of code blocks to include (default: 10) */
|
|
316
|
+
maxCodeBlocks?: number;
|
|
317
|
+
/** Maximum characters per code block (default: 2000) */
|
|
318
|
+
maxCodeBlockSize?: number;
|
|
319
|
+
/** Whether to include code blocks (default: true) */
|
|
320
|
+
includeCode?: boolean;
|
|
321
|
+
/** Output format (default: 'markdown') */
|
|
322
|
+
format?: 'markdown' | 'json';
|
|
323
|
+
/** Number of semantic search results (default: 5) */
|
|
324
|
+
searchLimit?: number;
|
|
325
|
+
/** Graph traversal depth from entry points (default: 2) */
|
|
326
|
+
traversalDepth?: number;
|
|
327
|
+
/** Minimum semantic similarity score (default: 0.3) */
|
|
328
|
+
minScore?: number;
|
|
329
|
+
}
|
|
330
|
+
/**
|
|
331
|
+
* Full context for a task, ready for Claude
|
|
332
|
+
*/
|
|
333
|
+
export interface TaskContext {
|
|
334
|
+
/** The original query/task */
|
|
335
|
+
query: string;
|
|
336
|
+
/** Subgraph of relevant nodes and edges */
|
|
337
|
+
subgraph: Subgraph;
|
|
338
|
+
/** Entry point nodes (from semantic search) */
|
|
339
|
+
entryPoints: Node[];
|
|
340
|
+
/** Code blocks extracted from key nodes */
|
|
341
|
+
codeBlocks: CodeBlock[];
|
|
342
|
+
/** Files involved in this context */
|
|
343
|
+
relatedFiles: string[];
|
|
344
|
+
/** Brief summary of the context */
|
|
345
|
+
summary: string;
|
|
346
|
+
/** Statistics about the context */
|
|
347
|
+
stats: {
|
|
348
|
+
/** Number of nodes included */
|
|
349
|
+
nodeCount: number;
|
|
350
|
+
/** Number of edges included */
|
|
351
|
+
edgeCount: number;
|
|
352
|
+
/** Number of files touched */
|
|
353
|
+
fileCount: number;
|
|
354
|
+
/** Number of code blocks included */
|
|
355
|
+
codeBlockCount: number;
|
|
356
|
+
/** Total characters in code blocks */
|
|
357
|
+
totalCodeSize: number;
|
|
358
|
+
};
|
|
359
|
+
}
|
|
360
|
+
/**
|
|
361
|
+
* Options for finding relevant context
|
|
362
|
+
*/
|
|
363
|
+
export interface FindRelevantContextOptions {
|
|
364
|
+
/** Number of semantic search results (default: 5) */
|
|
365
|
+
searchLimit?: number;
|
|
366
|
+
/** Graph traversal depth (default: 2) */
|
|
367
|
+
traversalDepth?: number;
|
|
368
|
+
/** Maximum nodes in result (default: 50) */
|
|
369
|
+
maxNodes?: number;
|
|
370
|
+
/** Minimum semantic similarity score (default: 0.3) */
|
|
371
|
+
minScore?: number;
|
|
372
|
+
/** Edge types to follow in traversal */
|
|
373
|
+
edgeKinds?: EdgeKind[];
|
|
374
|
+
/** Node types to include */
|
|
375
|
+
nodeKinds?: NodeKind[];
|
|
376
|
+
}
|
|
377
|
+
//# sourceMappingURL=types.d.ts.map
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Glyph selection for CLI output.
|
|
3
|
+
*
|
|
4
|
+
* On Windows, console output is interpreted via the active output
|
|
5
|
+
* codepage. PowerShell 5.1 and cmd.exe default to OEM codepages
|
|
6
|
+
* (CP437, CP936, ...), so UTF-8 bytes written to the console render
|
|
7
|
+
* as mojibake (see #168). The shimmer worker is hit hardest because
|
|
8
|
+
* it uses `fs.writeSync(1, ...)` (raw bytes, no TTY-aware encoding
|
|
9
|
+
* conversion) to keep animation smooth while the main thread is
|
|
10
|
+
* blocked in SQLite. To stay readable everywhere, we fall back to
|
|
11
|
+
* ASCII glyphs whenever the terminal is not known to handle UTF-8.
|
|
12
|
+
*
|
|
13
|
+
* Detection is intentionally simple:
|
|
14
|
+
* - `CODEGRAPH_ASCII=1` -> ASCII (escape hatch for any terminal)
|
|
15
|
+
* - `CODEGRAPH_UNICODE=1` -> Unicode (opt-in on Windows)
|
|
16
|
+
* - Windows -> ASCII by default
|
|
17
|
+
* - Linux kernel console (`TERM=linux`) -> ASCII
|
|
18
|
+
* - Everything else -> Unicode
|
|
19
|
+
*/
|
|
20
|
+
export declare function supportsUnicode(): boolean;
|
|
21
|
+
export interface Glyphs {
|
|
22
|
+
ok: string;
|
|
23
|
+
err: string;
|
|
24
|
+
info: string;
|
|
25
|
+
warn: string;
|
|
26
|
+
spinner: string[];
|
|
27
|
+
barFilled: string;
|
|
28
|
+
barEmpty: string;
|
|
29
|
+
rail: string;
|
|
30
|
+
phaseDone: string;
|
|
31
|
+
dash: string;
|
|
32
|
+
hLine: string;
|
|
33
|
+
treeBranch: string;
|
|
34
|
+
treeLast: string;
|
|
35
|
+
treePipe: string;
|
|
36
|
+
}
|
|
37
|
+
export declare const UNICODE_GLYPHS: Glyphs;
|
|
38
|
+
export declare const ASCII_GLYPHS: Glyphs;
|
|
39
|
+
export declare function getGlyphs(): Glyphs;
|
|
40
|
+
/** Reset the cached glyph set. Test-only; production code should call `getGlyphs()`. */
|
|
41
|
+
export declare function _resetGlyphsCache(): void;
|
|
42
|
+
//# sourceMappingURL=glyphs.d.ts.map
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
export interface IndexProgress {
|
|
2
|
+
phase: string;
|
|
3
|
+
current: number;
|
|
4
|
+
total: number;
|
|
5
|
+
}
|
|
6
|
+
export interface ShimmerProgress {
|
|
7
|
+
onProgress: (progress: IndexProgress) => void;
|
|
8
|
+
stop: () => Promise<void>;
|
|
9
|
+
}
|
|
10
|
+
export declare function createShimmerProgress(): ShimmerProgress;
|
|
11
|
+
//# sourceMappingURL=shimmer-progress.d.ts.map
|