@colbymchenry/codegraph 0.9.6 → 0.9.8

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.
Files changed (119) hide show
  1. package/README.md +122 -57
  2. package/dist/bin/codegraph.d.ts +25 -0
  3. package/dist/bin/node-version-check.d.ts +37 -0
  4. package/dist/bin/uninstall.d.ts +14 -0
  5. package/dist/context/formatter.d.ts +30 -0
  6. package/dist/context/index.d.ts +110 -0
  7. package/dist/db/index.d.ts +101 -0
  8. package/dist/db/migrations.d.ts +44 -0
  9. package/dist/db/queries.d.ts +344 -0
  10. package/dist/db/sqlite-adapter.d.ts +46 -0
  11. package/dist/directory.d.ts +57 -0
  12. package/dist/errors.d.ts +136 -0
  13. package/dist/extraction/dfm-extractor.d.ts +31 -0
  14. package/dist/extraction/generated-detection.d.ts +30 -0
  15. package/dist/extraction/grammars.d.ts +100 -0
  16. package/dist/extraction/index.d.ts +138 -0
  17. package/dist/extraction/languages/c-cpp.d.ts +4 -0
  18. package/dist/extraction/languages/csharp.d.ts +3 -0
  19. package/dist/extraction/languages/dart.d.ts +3 -0
  20. package/dist/extraction/languages/go.d.ts +3 -0
  21. package/dist/extraction/languages/index.d.ts +10 -0
  22. package/dist/extraction/languages/java.d.ts +3 -0
  23. package/dist/extraction/languages/javascript.d.ts +3 -0
  24. package/dist/extraction/languages/kotlin.d.ts +3 -0
  25. package/dist/extraction/languages/lua.d.ts +3 -0
  26. package/dist/extraction/languages/luau.d.ts +3 -0
  27. package/dist/extraction/languages/objc.d.ts +3 -0
  28. package/dist/extraction/languages/pascal.d.ts +3 -0
  29. package/dist/extraction/languages/php.d.ts +3 -0
  30. package/dist/extraction/languages/python.d.ts +3 -0
  31. package/dist/extraction/languages/ruby.d.ts +3 -0
  32. package/dist/extraction/languages/rust.d.ts +3 -0
  33. package/dist/extraction/languages/scala.d.ts +3 -0
  34. package/dist/extraction/languages/swift.d.ts +3 -0
  35. package/dist/extraction/languages/typescript.d.ts +3 -0
  36. package/dist/extraction/liquid-extractor.d.ts +52 -0
  37. package/dist/extraction/mybatis-extractor.d.ts +48 -0
  38. package/dist/extraction/parse-worker.d.ts +8 -0
  39. package/dist/extraction/svelte-extractor.d.ts +56 -0
  40. package/dist/extraction/tree-sitter-helpers.d.ts +28 -0
  41. package/dist/extraction/tree-sitter-types.d.ts +193 -0
  42. package/dist/extraction/tree-sitter.d.ts +291 -0
  43. package/dist/extraction/vue-extractor.d.ts +36 -0
  44. package/dist/extraction/wasm-runtime-flags.d.ts +38 -0
  45. package/dist/graph/index.d.ts +8 -0
  46. package/dist/graph/queries.d.ts +106 -0
  47. package/dist/graph/traversal.d.ts +127 -0
  48. package/dist/index.d.ts +492 -0
  49. package/dist/installer/config-writer.d.ts +28 -0
  50. package/dist/installer/index.d.ts +100 -0
  51. package/dist/installer/instructions-template.d.ts +18 -0
  52. package/dist/installer/targets/antigravity.d.ts +57 -0
  53. package/dist/installer/targets/claude.d.ts +56 -0
  54. package/dist/installer/targets/codex.d.ts +18 -0
  55. package/dist/installer/targets/cursor.d.ts +35 -0
  56. package/dist/installer/targets/gemini.d.ts +26 -0
  57. package/dist/installer/targets/hermes.d.ts +18 -0
  58. package/dist/installer/targets/kiro.d.ts +27 -0
  59. package/dist/installer/targets/opencode.d.ts +30 -0
  60. package/dist/installer/targets/registry.d.ts +35 -0
  61. package/dist/installer/targets/shared.d.ts +77 -0
  62. package/dist/installer/targets/toml.d.ts +52 -0
  63. package/dist/installer/targets/types.d.ts +101 -0
  64. package/dist/mcp/daemon-paths.d.ts +46 -0
  65. package/dist/mcp/daemon.d.ts +161 -0
  66. package/dist/mcp/engine.d.ts +105 -0
  67. package/dist/mcp/index.d.ts +112 -0
  68. package/dist/mcp/proxy.d.ts +81 -0
  69. package/dist/mcp/server-instructions.d.ts +19 -0
  70. package/dist/mcp/session.d.ts +77 -0
  71. package/dist/mcp/tools.d.ts +423 -0
  72. package/dist/mcp/transport.d.ts +188 -0
  73. package/dist/mcp/version.d.ts +19 -0
  74. package/dist/resolution/callback-synthesizer.d.ts +10 -0
  75. package/dist/resolution/frameworks/cargo-workspace.d.ts +18 -0
  76. package/dist/resolution/frameworks/csharp.d.ts +8 -0
  77. package/dist/resolution/frameworks/drupal.d.ts +51 -0
  78. package/dist/resolution/frameworks/expo-modules.d.ts +3 -0
  79. package/dist/resolution/frameworks/express.d.ts +8 -0
  80. package/dist/resolution/frameworks/fabric.d.ts +3 -0
  81. package/dist/resolution/frameworks/go.d.ts +8 -0
  82. package/dist/resolution/frameworks/index.d.ts +48 -0
  83. package/dist/resolution/frameworks/java.d.ts +8 -0
  84. package/dist/resolution/frameworks/laravel.d.ts +13 -0
  85. package/dist/resolution/frameworks/nestjs.d.ts +26 -0
  86. package/dist/resolution/frameworks/play.d.ts +19 -0
  87. package/dist/resolution/frameworks/python.d.ts +10 -0
  88. package/dist/resolution/frameworks/react-native.d.ts +3 -0
  89. package/dist/resolution/frameworks/react.d.ts +8 -0
  90. package/dist/resolution/frameworks/ruby.d.ts +8 -0
  91. package/dist/resolution/frameworks/rust.d.ts +8 -0
  92. package/dist/resolution/frameworks/svelte.d.ts +9 -0
  93. package/dist/resolution/frameworks/swift-objc.d.ts +37 -0
  94. package/dist/resolution/frameworks/swift.d.ts +10 -0
  95. package/dist/resolution/frameworks/vue.d.ts +9 -0
  96. package/dist/resolution/go-module.d.ts +26 -0
  97. package/dist/resolution/import-resolver.d.ts +68 -0
  98. package/dist/resolution/index.d.ts +116 -0
  99. package/dist/resolution/lru-cache.d.ts +24 -0
  100. package/dist/resolution/name-matcher.d.ts +32 -0
  101. package/dist/resolution/path-aliases.d.ts +68 -0
  102. package/dist/resolution/strip-comments.d.ts +27 -0
  103. package/dist/resolution/swift-objc-bridge.d.ts +134 -0
  104. package/dist/resolution/types.d.ts +209 -0
  105. package/dist/search/query-parser.d.ts +57 -0
  106. package/dist/search/query-utils.d.ts +53 -0
  107. package/dist/sync/git-hooks.d.ts +45 -0
  108. package/dist/sync/index.d.ts +19 -0
  109. package/dist/sync/watch-policy.d.ts +48 -0
  110. package/dist/sync/watcher.d.ts +191 -0
  111. package/dist/sync/worktree.d.ts +54 -0
  112. package/dist/types.d.ts +369 -0
  113. package/dist/ui/glyphs.d.ts +42 -0
  114. package/dist/ui/shimmer-progress.d.ts +11 -0
  115. package/dist/ui/shimmer-worker.d.ts +2 -0
  116. package/dist/ui/types.d.ts +17 -0
  117. package/dist/utils.d.ts +205 -0
  118. package/npm-sdk.js +75 -0
  119. 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
@@ -0,0 +1,369 @@
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
+ /**
174
+ * Options for graph traversal
175
+ */
176
+ export interface TraversalOptions {
177
+ /** Maximum depth to traverse (default: Infinity) */
178
+ maxDepth?: number;
179
+ /** Edge types to follow (default: all) */
180
+ edgeKinds?: EdgeKind[];
181
+ /** Node types to include (default: all) */
182
+ nodeKinds?: NodeKind[];
183
+ /** Direction of traversal */
184
+ direction?: 'outgoing' | 'incoming' | 'both';
185
+ /** Maximum nodes to return */
186
+ limit?: number;
187
+ /** Whether to include the starting node */
188
+ includeStart?: boolean;
189
+ }
190
+ /**
191
+ * Options for searching the graph
192
+ */
193
+ export interface SearchOptions {
194
+ /** Node types to search */
195
+ kinds?: NodeKind[];
196
+ /** Languages to include */
197
+ languages?: Language[];
198
+ /** File path patterns to include */
199
+ includePatterns?: string[];
200
+ /** File path patterns to exclude */
201
+ excludePatterns?: string[];
202
+ /** Maximum results to return */
203
+ limit?: number;
204
+ /** Offset for pagination */
205
+ offset?: number;
206
+ /** Whether search is case-sensitive */
207
+ caseSensitive?: boolean;
208
+ }
209
+ /**
210
+ * A search result with relevance scoring
211
+ */
212
+ export interface SearchResult {
213
+ /** Matching node */
214
+ node: Node;
215
+ /** Relevance score (0-1) */
216
+ score: number;
217
+ /** Matched text snippets for highlighting */
218
+ highlights?: string[];
219
+ }
220
+ /**
221
+ * Context information for code understanding
222
+ */
223
+ export interface Context {
224
+ /** Primary node being examined */
225
+ focal: Node;
226
+ /** Nodes containing the focal node (file, class, etc.) */
227
+ ancestors: Node[];
228
+ /** Nodes directly contained by focal node */
229
+ children: Node[];
230
+ /** Incoming references (who calls/uses this) */
231
+ incomingRefs: Array<{
232
+ node: Node;
233
+ edge: Edge;
234
+ }>;
235
+ /** Outgoing references (what this calls/uses) */
236
+ outgoingRefs: Array<{
237
+ node: Node;
238
+ edge: Edge;
239
+ }>;
240
+ /** Related type information */
241
+ types: Node[];
242
+ /** Relevant imports */
243
+ imports: Node[];
244
+ }
245
+ /**
246
+ * A block of code with context
247
+ */
248
+ export interface CodeBlock {
249
+ /** The code content */
250
+ content: string;
251
+ /** File path */
252
+ filePath: string;
253
+ /** Starting line */
254
+ startLine: number;
255
+ /** Ending line */
256
+ endLine: number;
257
+ /** Language for syntax highlighting */
258
+ language: Language;
259
+ /** Associated node if extracted */
260
+ node?: Node;
261
+ }
262
+ /**
263
+ * Database schema version info
264
+ */
265
+ export interface SchemaVersion {
266
+ /** Current schema version */
267
+ version: number;
268
+ /** When schema was created/updated */
269
+ appliedAt: number;
270
+ /** Description of this version */
271
+ description?: string;
272
+ }
273
+ /**
274
+ * Statistics about the knowledge graph
275
+ */
276
+ export interface GraphStats {
277
+ /** Total number of nodes */
278
+ nodeCount: number;
279
+ /** Total number of edges */
280
+ edgeCount: number;
281
+ /** Number of tracked files */
282
+ fileCount: number;
283
+ /** Node counts by kind */
284
+ nodesByKind: Record<NodeKind, number>;
285
+ /** Edge counts by kind */
286
+ edgesByKind: Record<EdgeKind, number>;
287
+ /** File counts by language */
288
+ filesByLanguage: Record<Language, number>;
289
+ /** Database size in bytes */
290
+ dbSizeBytes: number;
291
+ /** Last update timestamp */
292
+ lastUpdated: number;
293
+ }
294
+ /**
295
+ * Input for building task context
296
+ */
297
+ export type TaskInput = string | {
298
+ title: string;
299
+ description?: string;
300
+ };
301
+ /**
302
+ * Options for building task context
303
+ */
304
+ export interface BuildContextOptions {
305
+ /** Maximum number of nodes to include (default: 50) */
306
+ maxNodes?: number;
307
+ /** Maximum number of code blocks to include (default: 10) */
308
+ maxCodeBlocks?: number;
309
+ /** Maximum characters per code block (default: 2000) */
310
+ maxCodeBlockSize?: number;
311
+ /** Whether to include code blocks (default: true) */
312
+ includeCode?: boolean;
313
+ /** Output format (default: 'markdown') */
314
+ format?: 'markdown' | 'json';
315
+ /** Number of semantic search results (default: 5) */
316
+ searchLimit?: number;
317
+ /** Graph traversal depth from entry points (default: 2) */
318
+ traversalDepth?: number;
319
+ /** Minimum semantic similarity score (default: 0.3) */
320
+ minScore?: number;
321
+ }
322
+ /**
323
+ * Full context for a task, ready for Claude
324
+ */
325
+ export interface TaskContext {
326
+ /** The original query/task */
327
+ query: string;
328
+ /** Subgraph of relevant nodes and edges */
329
+ subgraph: Subgraph;
330
+ /** Entry point nodes (from semantic search) */
331
+ entryPoints: Node[];
332
+ /** Code blocks extracted from key nodes */
333
+ codeBlocks: CodeBlock[];
334
+ /** Files involved in this context */
335
+ relatedFiles: string[];
336
+ /** Brief summary of the context */
337
+ summary: string;
338
+ /** Statistics about the context */
339
+ stats: {
340
+ /** Number of nodes included */
341
+ nodeCount: number;
342
+ /** Number of edges included */
343
+ edgeCount: number;
344
+ /** Number of files touched */
345
+ fileCount: number;
346
+ /** Number of code blocks included */
347
+ codeBlockCount: number;
348
+ /** Total characters in code blocks */
349
+ totalCodeSize: number;
350
+ };
351
+ }
352
+ /**
353
+ * Options for finding relevant context
354
+ */
355
+ export interface FindRelevantContextOptions {
356
+ /** Number of semantic search results (default: 5) */
357
+ searchLimit?: number;
358
+ /** Graph traversal depth (default: 2) */
359
+ traversalDepth?: number;
360
+ /** Maximum nodes in result (default: 50) */
361
+ maxNodes?: number;
362
+ /** Minimum semantic similarity score (default: 0.3) */
363
+ minScore?: number;
364
+ /** Edge types to follow in traversal */
365
+ edgeKinds?: EdgeKind[];
366
+ /** Node types to include */
367
+ nodeKinds?: NodeKind[];
368
+ }
369
+ //# 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
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=shimmer-worker.d.ts.map
@@ -0,0 +1,17 @@
1
+ /** Messages from main thread to worker */
2
+ export type ShimmerWorkerMessage = {
3
+ type: 'update';
4
+ phase: string;
5
+ phaseName: string;
6
+ percent: number;
7
+ count: number;
8
+ } | {
9
+ type: 'finish-phase';
10
+ } | {
11
+ type: 'stop';
12
+ };
13
+ /** Messages from worker to main thread */
14
+ export type ShimmerMainMessage = {
15
+ type: 'stopped';
16
+ };
17
+ //# sourceMappingURL=types.d.ts.map