claude-db 0.11.1 → 0.12.1

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 (175) hide show
  1. package/CHANGELOG.md +44 -0
  2. package/README.md +5 -4
  3. package/dist/cli/commands/graph.js +104 -80
  4. package/dist/cli/commands/languages.d.ts +1 -0
  5. package/dist/cli/commands/languages.js +22 -0
  6. package/dist/cli/commands/pick.js +4 -2
  7. package/dist/cli/index.js +4 -0
  8. package/dist/cli/usage.js +3 -1
  9. package/dist/graph/ast.d.ts +4 -0
  10. package/dist/graph/ast.js +11 -0
  11. package/dist/graph/grammars.d.ts +14 -0
  12. package/dist/graph/grammars.js +58 -0
  13. package/dist/graph/index.d.ts +2 -2
  14. package/dist/graph/index.js +2 -2
  15. package/dist/graph/languages/basic.js +5 -1
  16. package/dist/graph/languages/ecmascript.js +7 -0
  17. package/dist/graph/languages/go.js +0 -1
  18. package/dist/graph/languages/index.d.ts +1 -1
  19. package/dist/graph/languages/index.js +34 -9
  20. package/dist/graph/languages/java.d.ts +2 -0
  21. package/dist/graph/languages/java.js +38 -0
  22. package/dist/graph/languages/kotlin.d.ts +2 -0
  23. package/dist/graph/languages/kotlin.js +19 -0
  24. package/dist/graph/languages/python.js +10 -2
  25. package/dist/graph/languages/rules.d.ts +11 -0
  26. package/dist/graph/languages/rust.js +2 -1
  27. package/dist/graph/modules/binding.d.ts +61 -0
  28. package/dist/graph/modules/binding.js +43 -0
  29. package/dist/graph/modules/ecmascript/bind.d.ts +4 -0
  30. package/dist/graph/modules/ecmascript/bind.js +17 -0
  31. package/dist/graph/modules/ecmascript/contexts.d.ts +6 -0
  32. package/dist/graph/modules/ecmascript/contexts.js +86 -0
  33. package/dist/graph/modules/ecmascript/exports.d.ts +9 -0
  34. package/dist/graph/modules/ecmascript/exports.js +91 -0
  35. package/dist/graph/modules/ecmascript/imports.d.ts +4 -0
  36. package/dist/graph/modules/ecmascript/imports.js +73 -0
  37. package/dist/graph/modules/ecmascript/package-resolver.d.ts +4 -0
  38. package/dist/graph/modules/ecmascript/package-resolver.js +73 -0
  39. package/dist/graph/modules/ecmascript/resolver.d.ts +2 -0
  40. package/dist/graph/modules/ecmascript/resolver.js +22 -0
  41. package/dist/graph/modules/ecmascript/specifiers.d.ts +3 -0
  42. package/dist/graph/modules/ecmascript/specifiers.js +15 -0
  43. package/dist/graph/modules/ecmascript/system.d.ts +2 -0
  44. package/dist/graph/modules/ecmascript/system.js +18 -0
  45. package/dist/graph/modules/ecmascript/workspace-resolver.d.ts +5 -0
  46. package/dist/graph/modules/ecmascript/workspace-resolver.js +38 -0
  47. package/dist/graph/modules/go/grammar.d.ts +2 -0
  48. package/dist/graph/modules/go/grammar.js +54 -0
  49. package/dist/graph/modules/go/imports.d.ts +4 -0
  50. package/dist/graph/modules/go/imports.js +32 -0
  51. package/dist/graph/modules/go/resolver.d.ts +2 -0
  52. package/dist/graph/modules/go/resolver.js +54 -0
  53. package/dist/graph/modules/go/system.d.ts +2 -0
  54. package/dist/graph/modules/go/system.js +16 -0
  55. package/dist/graph/modules/java/declarations.d.ts +9 -0
  56. package/dist/graph/modules/java/declarations.js +108 -0
  57. package/dist/graph/modules/java/grammar.d.ts +2 -0
  58. package/dist/graph/modules/java/grammar.js +135 -0
  59. package/dist/graph/modules/java/imports.d.ts +4 -0
  60. package/dist/graph/modules/java/imports.js +13 -0
  61. package/dist/graph/modules/java/receivers.d.ts +3 -0
  62. package/dist/graph/modules/java/receivers.js +139 -0
  63. package/dist/graph/modules/java/system.d.ts +1 -0
  64. package/dist/graph/modules/java/system.js +13 -0
  65. package/dist/graph/modules/jvm/linking.d.ts +20 -0
  66. package/dist/graph/modules/jvm/linking.js +64 -0
  67. package/dist/graph/modules/jvm/packages.d.ts +5 -0
  68. package/dist/graph/modules/jvm/packages.js +58 -0
  69. package/dist/graph/modules/jvm/receivers.d.ts +44 -0
  70. package/dist/graph/modules/jvm/receivers.js +77 -0
  71. package/dist/graph/modules/jvm/system.d.ts +18 -0
  72. package/dist/graph/modules/jvm/system.js +29 -0
  73. package/dist/graph/modules/jvm/types.d.ts +3 -0
  74. package/dist/graph/modules/jvm/types.js +11 -0
  75. package/dist/graph/modules/kotlin/declarations.d.ts +8 -0
  76. package/dist/graph/modules/kotlin/declarations.js +69 -0
  77. package/dist/graph/modules/kotlin/grammar.d.ts +2 -0
  78. package/dist/graph/modules/kotlin/grammar.js +78 -0
  79. package/dist/graph/modules/kotlin/imports.d.ts +4 -0
  80. package/dist/graph/modules/kotlin/imports.js +25 -0
  81. package/dist/graph/modules/kotlin/receivers.d.ts +3 -0
  82. package/dist/graph/modules/kotlin/receivers.js +105 -0
  83. package/dist/graph/modules/kotlin/references.d.ts +8 -0
  84. package/dist/graph/modules/kotlin/references.js +69 -0
  85. package/dist/graph/modules/kotlin/system.d.ts +1 -0
  86. package/dist/graph/modules/kotlin/system.js +15 -0
  87. package/dist/graph/modules/members.d.ts +17 -0
  88. package/dist/graph/modules/members.js +30 -0
  89. package/dist/graph/modules/module-index.d.ts +9 -0
  90. package/dist/graph/modules/module-index.js +62 -0
  91. package/dist/graph/modules/names.d.ts +2 -0
  92. package/dist/graph/modules/names.js +3 -0
  93. package/dist/graph/modules/python/grammar.d.ts +2 -0
  94. package/dist/graph/modules/python/grammar.js +100 -0
  95. package/dist/graph/modules/python/imports.d.ts +3 -0
  96. package/dist/graph/modules/python/imports.js +72 -0
  97. package/dist/graph/modules/python/resolver.d.ts +2 -0
  98. package/dist/graph/modules/python/resolver.js +78 -0
  99. package/dist/graph/modules/python/system.d.ts +2 -0
  100. package/dist/graph/modules/python/system.js +16 -0
  101. package/dist/graph/modules/rebind.d.ts +8 -0
  102. package/dist/graph/modules/rebind.js +51 -0
  103. package/dist/graph/modules/registry.d.ts +5 -0
  104. package/dist/graph/modules/registry.js +47 -0
  105. package/dist/graph/modules/rust/grammar.d.ts +2 -0
  106. package/dist/graph/modules/rust/grammar.js +94 -0
  107. package/dist/graph/modules/rust/imports.d.ts +3 -0
  108. package/dist/graph/modules/rust/imports.js +90 -0
  109. package/dist/graph/modules/rust/resolver.d.ts +3 -0
  110. package/dist/graph/modules/rust/resolver.js +153 -0
  111. package/dist/graph/modules/rust/system.d.ts +2 -0
  112. package/dist/graph/modules/rust/system.js +16 -0
  113. package/dist/graph/modules/shadowing.d.ts +17 -0
  114. package/dist/graph/modules/shadowing.js +65 -0
  115. package/dist/graph/modules/system.d.ts +39 -0
  116. package/dist/graph/modules/system.js +1 -0
  117. package/dist/graph/modules/uses.d.ts +14 -0
  118. package/dist/graph/modules/uses.js +62 -0
  119. package/dist/graph/parser.d.ts +9 -11
  120. package/dist/graph/parser.js +5 -4
  121. package/dist/graph/query/answer.d.ts +15 -0
  122. package/dist/graph/query/answer.js +22 -0
  123. package/dist/graph/query/format.d.ts +8 -1
  124. package/dist/graph/query/format.js +103 -30
  125. package/dist/graph/query/groups.d.ts +14 -0
  126. package/dist/graph/query/groups.js +51 -0
  127. package/dist/graph/query/index.d.ts +2 -1
  128. package/dist/graph/query/index.js +2 -1
  129. package/dist/graph/query/lookup.d.ts +2 -0
  130. package/dist/graph/query/lookup.js +19 -2
  131. package/dist/graph/query/refresh.js +17 -18
  132. package/dist/graph/query/stale.d.ts +2 -0
  133. package/dist/graph/query/stale.js +39 -0
  134. package/dist/graph/query/text.d.ts +12 -0
  135. package/dist/graph/query/text.js +26 -0
  136. package/dist/graph/scan/binder.d.ts +13 -0
  137. package/dist/graph/scan/binder.js +210 -0
  138. package/dist/graph/scan/cache.d.ts +11 -0
  139. package/dist/graph/scan/cache.js +140 -0
  140. package/dist/graph/scan/extract.d.ts +4 -17
  141. package/dist/graph/scan/extract.js +105 -83
  142. package/dist/graph/scan/files.d.ts +3 -9
  143. package/dist/graph/scan/files.js +3 -2
  144. package/dist/graph/scan/index.d.ts +8 -3
  145. package/dist/graph/scan/index.js +96 -36
  146. package/dist/graph/scan/job.d.ts +1 -0
  147. package/dist/graph/scan/job.js +1 -0
  148. package/dist/graph/scan/persist.d.ts +3 -0
  149. package/dist/graph/scan/persist.js +22 -0
  150. package/dist/graph/scan/receivers.d.ts +21 -0
  151. package/dist/graph/scan/receivers.js +87 -0
  152. package/dist/graph/scan/resolve.d.ts +8 -2
  153. package/dist/graph/scan/resolve.js +50 -56
  154. package/dist/graph/scan/spans.d.ts +13 -0
  155. package/dist/graph/scan/spans.js +42 -0
  156. package/dist/graph/symbols.d.ts +10 -0
  157. package/dist/graph/symbols.js +30 -0
  158. package/dist/graph/types.d.ts +56 -0
  159. package/dist/graph/types.js +1 -0
  160. package/dist/hooks/background.js +1 -16
  161. package/dist/hooks/detached.d.ts +3 -0
  162. package/dist/hooks/detached.js +16 -0
  163. package/dist/hooks/graph-refresh.d.ts +1 -0
  164. package/dist/hooks/graph-refresh.js +9 -0
  165. package/dist/hooks/prefer-usages.js +53 -12
  166. package/dist/hooks/session-start.js +8 -8
  167. package/dist/mcp/tools/usages.js +40 -31
  168. package/dist/pick/run.d.ts +6 -0
  169. package/dist/pick/run.js +8 -1
  170. package/dist/types.d.ts +1 -1
  171. package/dist/usages/find.js +1 -0
  172. package/dist/util/claude-cli.d.ts +1 -0
  173. package/dist/util/claude-cli.js +15 -3
  174. package/docs/how-it-works.md +10 -8
  175. package/package.json +16 -5
@@ -0,0 +1,22 @@
1
+ const REMOVE_BATCH = 500;
2
+ async function removeFiles(store, project, files) {
3
+ for (let start = 0; start < files.length; start += REMOVE_BATCH) {
4
+ const batch = files.slice(start, start + REMOVE_BATCH);
5
+ if (batch.length > 0)
6
+ await store.removeGraph(project, batch);
7
+ }
8
+ }
9
+ export async function saveScan(store, project, scan, force = false) {
10
+ if (force) {
11
+ await store.removeGraph(project);
12
+ await store.upsertGraph({ symbols: scan.symbols, edges: scan.edges, files: scan.files });
13
+ return;
14
+ }
15
+ await removeFiles(store, project, [...scan.removed, ...scan.rewrite]);
16
+ const rewrite = new Set(scan.rewrite);
17
+ await store.upsertGraph({
18
+ symbols: scan.symbols.filter((symbol) => rewrite.has(symbol.file)),
19
+ edges: scan.edges.filter((edge) => rewrite.has(edge.file)),
20
+ files: scan.files.filter((file) => rewrite.has(file.path)),
21
+ });
22
+ }
@@ -0,0 +1,21 @@
1
+ import type { CodeSymbol } from '../../types.js';
2
+ import type { Reference, TypeRef } from '../types.js';
3
+ export declare const OUTSIDE: {
4
+ readonly outside: true;
5
+ };
6
+ export type Value = {
7
+ symbol: CodeSymbol;
8
+ } | typeof OUTSIDE | null;
9
+ export type Member = {
10
+ target: CodeSymbol;
11
+ } | typeof OUTSIDE | null;
12
+ export interface Hierarchy {
13
+ inherited: (owner: CodeSymbol, wanted: string) => CodeSymbol | undefined;
14
+ parentsOf: (owner: CodeSymbol) => CodeSymbol[];
15
+ typeOf: (file: string, type: TypeRef) => Value;
16
+ callee: (call: Reference) => CodeSymbol | undefined;
17
+ }
18
+ export interface Receivers {
19
+ memberFor: (reference: Reference, wanted: string) => Member;
20
+ }
21
+ export declare function createReceivers(references: Reference[], hierarchy: Hierarchy): Receivers;
@@ -0,0 +1,87 @@
1
+ const OWNERS = new Set(['class', 'interface', 'enum']);
2
+ const NESTING_DEPTH = 8;
3
+ export const OUTSIDE = { outside: true };
4
+ const isBetterCall = (candidate, known) => !known || (!known.link && !known.receiver && !!(candidate.link ?? candidate.receiver));
5
+ function firstMember(owners, find) {
6
+ for (const owner of owners) {
7
+ const found = find(owner);
8
+ if (found)
9
+ return { target: found };
10
+ }
11
+ return null;
12
+ }
13
+ export function createReceivers(references, hierarchy) {
14
+ const ownerOf = new Map();
15
+ const returnsOf = new Map();
16
+ const calls = new Map();
17
+ const around = new Map();
18
+ for (const reference of references) {
19
+ if (reference.relation === 'defines' && reference.from && reference.to) {
20
+ ownerOf.set(reference.to, reference.from);
21
+ if (reference.returns)
22
+ returnsOf.set(reference.to, reference);
23
+ }
24
+ if (reference.relation !== 'calls' || reference.origin === undefined)
25
+ continue;
26
+ const inFile = calls.get(reference.file) ?? new Map();
27
+ calls.set(reference.file, inFile);
28
+ if (isBetterCall(reference, inFile.get(reference.origin))) {
29
+ inFile.set(reference.origin, reference);
30
+ }
31
+ }
32
+ const walkOut = (symbol) => {
33
+ const classes = [];
34
+ let at = symbol;
35
+ for (let depth = 0; at && depth < NESTING_DEPTH; depth += 1) {
36
+ if (OWNERS.has(at.kind))
37
+ classes.push(at);
38
+ at = ownerOf.get(at.id);
39
+ }
40
+ return classes;
41
+ };
42
+ const classesAround = (symbol) => {
43
+ if (!symbol)
44
+ return [];
45
+ const known = around.get(symbol.id);
46
+ if (known)
47
+ return known;
48
+ const classes = walkOut(symbol);
49
+ around.set(symbol.id, classes);
50
+ return classes;
51
+ };
52
+ const valueOf = (receiver, reference) => {
53
+ if (receiver.kind === 'outside')
54
+ return OUTSIDE;
55
+ if (receiver.kind === 'type')
56
+ return hierarchy.typeOf(reference.file, receiver.type);
57
+ if (receiver.kind !== 'result')
58
+ return null;
59
+ const call = calls.get(reference.file)?.get(receiver.of);
60
+ const method = call ? hierarchy.callee(call) : undefined;
61
+ const declared = method ? returnsOf.get(method.id) : undefined;
62
+ return declared?.returns ? valueOf(declared.returns, declared) : null;
63
+ };
64
+ const memberFor = (reference, wanted) => {
65
+ const { receiver } = reference;
66
+ if (!receiver || (receiver.kind === 'self' && reference.link))
67
+ return null;
68
+ const find = (owner) => hierarchy.inherited(owner, wanted);
69
+ if (receiver.kind === 'self')
70
+ return firstMember(classesAround(reference.from), find);
71
+ if (receiver.kind === 'parent') {
72
+ const [own] = classesAround(reference.from);
73
+ return own ? (firstMember(hierarchy.parentsOf(own), find) ?? OUTSIDE) : null;
74
+ }
75
+ const value = valueOf(receiver, reference);
76
+ const exact = receiver.kind === 'outside' || ('exact' in receiver && receiver.exact === true);
77
+ if (!value)
78
+ return null;
79
+ if ('outside' in value)
80
+ return exact ? OUTSIDE : null;
81
+ const found = find(value.symbol);
82
+ if (found)
83
+ return { target: found };
84
+ return exact ? OUTSIDE : null;
85
+ };
86
+ return { memberFor };
87
+ }
@@ -1,3 +1,9 @@
1
1
  import type { CodeEdge, CodeSymbol } from '../../types.js';
2
- import type { Reference } from './extract.js';
3
- export declare function resolveEdges(project: string, symbols: CodeSymbol[], references: Reference[]): CodeEdge[];
2
+ import type { ModuleContext } from '../modules/system.js';
3
+ import type { Reference } from '../types.js';
4
+ export interface Linker {
5
+ edgesFor(references: Reference[]): CodeEdge[];
6
+ outcome(reference: Reference): string;
7
+ }
8
+ export declare function createLinker(project: string, symbols: CodeSymbol[], references: Reference[], modules?: ModuleContext): Linker;
9
+ export declare function resolveEdges(project: string, symbols: CodeSymbol[], references: Reference[], modules?: ModuleContext): CodeEdge[];
@@ -1,61 +1,56 @@
1
1
  import { observationId } from '../../capture/identity.js';
2
- const SAME_FILE = 1;
3
- const SINGLE_MATCH = 0.95;
4
- const AMBIGUOUS_MATCH = 0.85;
2
+ import { lastSegment } from '../modules/names.js';
3
+ import { createModuleContext } from '../modules/registry.js';
4
+ import { createBinder } from './binder.js';
5
5
  function edgeId(project, file, line, from, to, relation, origin) {
6
6
  return observationId('graph', 0, `${project}\0${file}\0${line}\0${from}\0${to}\0${relation}\0${origin}`);
7
7
  }
8
- export function resolveEdges(project, symbols, references) {
9
- const byName = new Map();
10
- for (const symbol of symbols) {
11
- const bucket = byName.get(symbol.name);
12
- if (bucket)
13
- bucket.push(symbol);
14
- else
15
- byName.set(symbol.name, [symbol]);
16
- }
17
- const edges = [];
18
- const origins = new Map();
19
- for (const reference of references) {
20
- const candidates = byName.get(reference.name) ?? [];
21
- const exact = reference.to
22
- ? candidates.find((candidate) => candidate.id === reference.to)
23
- : undefined;
24
- const local = exact ?? candidates.find((candidate) => candidate.file === reference.file);
25
- const target = local ?? candidates[0];
26
- if (!target && reference.weak)
27
- continue;
28
- let confidence = 'EXTRACTED';
29
- let score = SAME_FILE;
30
- if (!local && candidates.length === 1) {
31
- confidence = 'INFERRED';
32
- score = SINGLE_MATCH;
33
- }
34
- else if (!local && candidates.length > 1) {
35
- confidence = 'INFERRED';
36
- score = AMBIGUOUS_MATCH;
8
+ export function createLinker(project, symbols, references, modules) {
9
+ const context = modules ?? createModuleContext('', new Set(symbols.map((symbol) => symbol.file)));
10
+ const binder = createBinder(symbols, references, context);
11
+ const outcome = (reference) => {
12
+ const resolution = binder.resolve(reference);
13
+ if (!resolution)
14
+ return '';
15
+ const external = resolution.external ? 1 : 0;
16
+ return `${resolution.target?.id ?? ''}|${resolution.confidence}|${resolution.score}|${external}`;
17
+ };
18
+ const edgesFor = (batch) => {
19
+ const edges = [];
20
+ const origins = new Map();
21
+ const sealed = new Set();
22
+ for (const reference of batch) {
23
+ const resolution = binder.resolve(reference);
24
+ if (!resolution)
25
+ continue;
26
+ const fromName = reference.from?.name ?? reference.file;
27
+ const edge = {
28
+ id: edgeId(project, reference.file, reference.line, fromName, reference.name, reference.relation, reference.origin ?? ''),
29
+ project,
30
+ srcId: reference.from?.id ?? '',
31
+ srcName: fromName,
32
+ dstId: resolution.target?.id ?? '',
33
+ dstName: reference.name,
34
+ relation: reference.relation,
35
+ confidence: resolution.confidence,
36
+ score: resolution.score,
37
+ file: reference.file,
38
+ line: reference.line,
39
+ };
40
+ edges.push(edge);
41
+ if (reference.origin !== undefined)
42
+ origins.set(edge.id, reference.origin);
43
+ if (resolution.external)
44
+ sealed.add(edge.id);
37
45
  }
38
- const fromName = reference.from?.name ?? reference.file;
39
- edges.push({
40
- id: edgeId(project, reference.file, reference.line, fromName, reference.name, reference.relation, reference.origin ?? ''),
41
- project,
42
- srcId: reference.from?.id ?? '',
43
- srcName: fromName,
44
- dstId: target?.id ?? '',
45
- dstName: reference.name,
46
- relation: reference.relation,
47
- confidence,
48
- score,
49
- file: reference.file,
50
- line: reference.line,
51
- });
52
- const added = edges[edges.length - 1];
53
- if (added && reference.origin !== undefined)
54
- origins.set(added.id, reference.origin);
55
- }
56
- return mergeMemberCalls(edges, origins);
46
+ return mergeMemberCalls(edges, origins, sealed);
47
+ };
48
+ return { edgesFor, outcome };
49
+ }
50
+ export function resolveEdges(project, symbols, references, modules) {
51
+ return createLinker(project, symbols, references, modules).edgesFor(references);
57
52
  }
58
- function mergeMemberCalls(edges, origins) {
53
+ function mergeMemberCalls(edges, origins, sealed) {
59
54
  const byLine = new Map();
60
55
  for (const edge of edges) {
61
56
  const key = `${edge.file}\0${edge.line}`;
@@ -68,10 +63,9 @@ function mergeMemberCalls(edges, origins) {
68
63
  const merged = new Set();
69
64
  for (const bucket of byLine.values()) {
70
65
  for (const qualified of bucket) {
71
- const dot = qualified.dstName.lastIndexOf('.');
72
- if (dot < 0)
66
+ const tail = lastSegment(qualified.dstName);
67
+ if (tail === qualified.dstName)
73
68
  continue;
74
- const tail = qualified.dstName.slice(dot + 1);
75
69
  for (const bare of bucket) {
76
70
  if (bare === qualified)
77
71
  continue;
@@ -81,7 +75,7 @@ function mergeMemberCalls(edges, origins) {
81
75
  const to = origins.get(bare.id);
82
76
  if (from === undefined || to === undefined || from !== to)
83
77
  continue;
84
- if (!qualified.dstId && bare.dstId) {
78
+ if (!qualified.dstId && bare.dstId && !sealed.has(qualified.id)) {
85
79
  qualified.dstId = bare.dstId;
86
80
  qualified.confidence = bare.confidence;
87
81
  qualified.score = bare.score;
@@ -0,0 +1,13 @@
1
+ import type { CodeSymbol } from '../../types.js';
2
+ export interface Span {
3
+ start: number;
4
+ end: number;
5
+ symbol: CodeSymbol;
6
+ }
7
+ export interface Extent extends Span {
8
+ from: number;
9
+ to: number;
10
+ }
11
+ export declare function nearestAbove(line: number, spans: Span[]): CodeSymbol | null;
12
+ export declare function enclosing(line: number, spans: Span[]): CodeSymbol | null;
13
+ export declare function container(inner: Extent, spans: Extent[]): CodeSymbol | null;
@@ -0,0 +1,42 @@
1
+ const CALLABLE = new Set(['function', 'method', 'class']);
2
+ export function nearestAbove(line, spans) {
3
+ let best = null;
4
+ for (const span of spans) {
5
+ if (span.start > line)
6
+ continue;
7
+ if (!best || span.start > best.start)
8
+ best = span;
9
+ }
10
+ return best?.symbol ?? null;
11
+ }
12
+ export function enclosing(line, spans) {
13
+ let best = null;
14
+ let fallback = null;
15
+ for (const span of spans) {
16
+ if (line < span.start || line > span.end)
17
+ continue;
18
+ const width = span.end - span.start;
19
+ if (CALLABLE.has(span.symbol.kind)) {
20
+ if (!best || width < best.end - best.start)
21
+ best = span;
22
+ continue;
23
+ }
24
+ if (span.start === line)
25
+ continue;
26
+ if (!fallback || width < fallback.end - fallback.start)
27
+ fallback = span;
28
+ }
29
+ return (best ?? fallback)?.symbol ?? null;
30
+ }
31
+ export function container(inner, spans) {
32
+ let best = null;
33
+ for (const span of spans) {
34
+ if (span === inner || span.from > inner.from || span.to < inner.to)
35
+ continue;
36
+ if (span.from === inner.from && span.to === inner.to)
37
+ continue;
38
+ if (!best || span.to - span.from < best.to - best.from)
39
+ best = span;
40
+ }
41
+ return best?.symbol ?? null;
42
+ }
@@ -0,0 +1,10 @@
1
+ import type { CodeSymbol, SymbolKind } from '../types.js';
2
+ export declare function symbolId(project: string, file: string, name: string, kind: string, index?: number): string;
3
+ export interface SymbolSource {
4
+ project: string;
5
+ path: string;
6
+ lang: string;
7
+ lines: string[];
8
+ }
9
+ export type Declare = (name: string, kind: SymbolKind, line: number) => CodeSymbol;
10
+ export declare function symbolFactory(source: SymbolSource): Declare;
@@ -0,0 +1,30 @@
1
+ import { observationId } from '../capture/identity.js';
2
+ import { redact } from '../capture/redact.js';
3
+ const SIGNATURE_CHARS = 200;
4
+ const SIGNATURE_WINDOW = 1000;
5
+ export function symbolId(project, file, name, kind, index = 0) {
6
+ const seed = `${project}\0${file}\0${name}\0${kind}`;
7
+ return observationId('graph', 0, index === 0 ? seed : `${seed}\0${index}`);
8
+ }
9
+ function counter() {
10
+ const seen = new Map();
11
+ return (name, kind) => {
12
+ const key = `${name}\0${kind}`;
13
+ const index = seen.get(key) ?? 0;
14
+ seen.set(key, index + 1);
15
+ return index;
16
+ };
17
+ }
18
+ export function symbolFactory(source) {
19
+ const occurrence = counter();
20
+ return (name, kind, line) => ({
21
+ id: symbolId(source.project, source.path, name, kind, occurrence(name, kind)),
22
+ project: source.project,
23
+ name,
24
+ kind,
25
+ file: source.path,
26
+ line,
27
+ lang: source.lang,
28
+ signature: redact((source.lines[line - 1] ?? '').trim().slice(0, SIGNATURE_WINDOW)).slice(0, SIGNATURE_CHARS),
29
+ });
30
+ }
@@ -0,0 +1,56 @@
1
+ import type { CodeSymbol, EdgeRelation } from '../types.js';
2
+ import type { LanguageSpec } from './languages/rules.js';
3
+ export interface ModuleLink {
4
+ specifier: string;
5
+ member?: string;
6
+ via?: string[];
7
+ strict?: boolean;
8
+ exported?: string;
9
+ namespace?: boolean;
10
+ opens?: string[];
11
+ }
12
+ export interface TypeRef {
13
+ name: string;
14
+ link?: ModuleLink;
15
+ }
16
+ export type Receiver = {
17
+ kind: 'type';
18
+ type: TypeRef;
19
+ exact?: true;
20
+ } | {
21
+ kind: 'result';
22
+ of: string;
23
+ exact?: true;
24
+ } | {
25
+ kind: 'self';
26
+ } | {
27
+ kind: 'parent';
28
+ } | {
29
+ kind: 'outside';
30
+ } | {
31
+ kind: 'unknown';
32
+ };
33
+ export interface Reference {
34
+ file: string;
35
+ name: string;
36
+ relation: EdgeRelation;
37
+ line: number;
38
+ from: CodeSymbol | null;
39
+ weak?: boolean;
40
+ to?: string;
41
+ origin?: string;
42
+ link?: ModuleLink;
43
+ receiver?: Receiver;
44
+ returns?: Receiver;
45
+ }
46
+ export interface Extraction {
47
+ symbols: CodeSymbol[];
48
+ references: Reference[];
49
+ }
50
+ export interface SourceFile {
51
+ unreadable?: boolean;
52
+ path: string;
53
+ spec: LanguageSpec;
54
+ source: string;
55
+ hash: string;
56
+ }
@@ -0,0 +1 @@
1
+ export {};
@@ -1,23 +1,8 @@
1
- import { spawn } from 'node:child_process';
2
- import { dirname, resolve } from 'node:path';
3
- import { fileURLToPath } from 'node:url';
4
1
  import { claimReingest, claimScrub, reingestDone, releaseReingest, releaseScrub, } from '../capture/index.js';
5
2
  import { FACTS_JOB } from '../facts/distill.js';
6
3
  import { claimJob, jobMark, releaseJob } from '../util/job-lock.js';
7
- const DIST = resolve(dirname(fileURLToPath(import.meta.url)), '..');
8
- const CLI = resolve(DIST, 'cli', 'index.js');
9
- const PICK_WORKER = resolve(DIST, 'pick', 'worker.js');
4
+ import { CLI, PICK_WORKER, runDetached } from './detached.js';
10
5
  const FACTS_EVERY_MS = 60 * 60 * 1000;
11
- function runDetached(script, args, cwd, release) {
12
- try {
13
- spawn(process.execPath, [script, ...args], { cwd, detached: true, stdio: 'ignore' })
14
- .on('error', release)
15
- .unref();
16
- }
17
- catch {
18
- release();
19
- }
20
- }
21
6
  export function startBackgroundWork(project, database, now = Date.now()) {
22
7
  if (claimScrub(database, now)) {
23
8
  runDetached(CLI, ['redact', '--background'], project, () => releaseScrub(database));
@@ -0,0 +1,3 @@
1
+ export declare const CLI: string;
2
+ export declare const PICK_WORKER: string;
3
+ export declare function runDetached(script: string, args: string[], cwd: string, release: () => void): void;
@@ -0,0 +1,16 @@
1
+ import { spawn } from 'node:child_process';
2
+ import { dirname, resolve } from 'node:path';
3
+ import { fileURLToPath } from 'node:url';
4
+ const DIST = resolve(dirname(fileURLToPath(import.meta.url)), '..');
5
+ export const CLI = resolve(DIST, 'cli', 'index.js');
6
+ export const PICK_WORKER = resolve(DIST, 'pick', 'worker.js');
7
+ export function runDetached(script, args, cwd, release) {
8
+ try {
9
+ spawn(process.execPath, [script, ...args], { cwd, detached: true, stdio: 'ignore' })
10
+ .on('error', release)
11
+ .unref();
12
+ }
13
+ catch {
14
+ release();
15
+ }
16
+ }
@@ -0,0 +1 @@
1
+ export declare function refreshGraphInBackground(project: string, root: string, now?: number): boolean;
@@ -0,0 +1,9 @@
1
+ import { GRAPH_JOB } from '../graph/scan/job.js';
2
+ import { claimJob, releaseJob } from '../util/job-lock.js';
3
+ import { CLI, runDetached } from './detached.js';
4
+ export function refreshGraphInBackground(project, root, now = Date.now()) {
5
+ if (!claimJob(GRAPH_JOB, project, now))
6
+ return false;
7
+ runDetached(CLI, ['scan', '--background', '--path', root], project, () => releaseJob(GRAPH_JOB, project));
8
+ return true;
9
+ }
@@ -1,13 +1,18 @@
1
1
  #!/usr/bin/env node
2
2
  import { createContext } from '../context.js';
3
- import { formatGraph, queryGraph } from '../graph/index.js';
3
+ import { addText, answerQuery, formatGraph, formatText } from '../graph/index.js';
4
+ import { staleFiles } from '../graph/query/stale.js';
5
+ import { repoRootFor } from '../usages/index.js';
4
6
  import { DECLARED, isSymbol, isWord, symbolsGreppedIn } from './grep-symbols.js';
7
+ import { refreshGraphInBackground } from './graph-refresh.js';
5
8
  import { readPayload, runHook } from './payload.js';
6
9
  import { resolveProject } from '../util/project.js';
7
10
  import { silenceSqliteWarning } from '../util/warnings.js';
8
11
  silenceSqliteWarning();
9
12
  const MAX_SYMBOLS = 2;
10
13
  const MAX_LINES = 14;
14
+ const TEXT_LINES = 6;
15
+ const EDGE_LIMIT = 20;
11
16
  function requested(payload) {
12
17
  const input = payload.tool_input ?? {};
13
18
  if (payload.tool_name === 'Grep') {
@@ -25,6 +30,50 @@ function trim(answer) {
25
30
  return answer;
26
31
  return [...lines.slice(0, MAX_LINES), ` ... more via find_usages`].join('\n');
27
32
  }
33
+ const answers = (answer, symbol) => !answer.empty && (isSymbol(symbol) || answer.definitions.some((d) => DECLARED.has(d.kind)));
34
+ function block(answer, root) {
35
+ const graph = trim(formatGraph(answer, root, { text: false }));
36
+ return [graph, ...formatText(answer.text, TEXT_LINES)].join('\n');
37
+ }
38
+ const staleNote = (count) => `(${count} file(s) changed since the last scan and are being re-read in the background, ` +
39
+ 'so lines in them may have moved. The text matches are live.)';
40
+ async function freshnessNote(store, project) {
41
+ try {
42
+ const root = repoRootFor(project);
43
+ const stale = staleFiles(root, await store.scannedFiles(project));
44
+ if (stale.length === 0)
45
+ return null;
46
+ refreshGraphInBackground(project, root);
47
+ return staleNote(stale.length);
48
+ }
49
+ catch {
50
+ return null;
51
+ }
52
+ }
53
+ async function answerSymbols(ctx, project, symbols) {
54
+ const answered = { named: [], blocks: [] };
55
+ for (const symbol of symbols) {
56
+ const answer = await answerQuery({
57
+ store: ctx.store,
58
+ root: project,
59
+ project,
60
+ query: { mode: 'usages', symbol, limit: EDGE_LIMIT },
61
+ refresh: false,
62
+ text: false,
63
+ });
64
+ if (!answers(answer, symbol))
65
+ continue;
66
+ addText(answer, project);
67
+ answered.named.push(symbol);
68
+ answered.blocks.push(block(answer, project));
69
+ }
70
+ if (answered.blocks.length > 0) {
71
+ const note = await freshnessNote(ctx.store, project);
72
+ if (note)
73
+ answered.blocks.push(note);
74
+ }
75
+ return answered;
76
+ }
28
77
  await runHook(async () => {
29
78
  const mode = process.env['CLAUDE_DB_USAGES_HOOK'] ?? 'deny';
30
79
  if (mode === 'off')
@@ -35,22 +84,14 @@ await runHook(async () => {
35
84
  return;
36
85
  const project = resolveProject(payload.cwd);
37
86
  const ctx = await createContext();
38
- const blocks = [];
39
- const named = [];
87
+ let answered;
40
88
  try {
41
- for (const symbol of symbols) {
42
- const answer = await queryGraph(ctx.store, project, { mode: 'usages', symbol, limit: 20 });
43
- if (answer.empty)
44
- continue;
45
- if (!isSymbol(symbol) && !answer.definitions.some((d) => DECLARED.has(d.kind)))
46
- continue;
47
- named.push(symbol);
48
- blocks.push(trim(formatGraph(answer, project)));
49
- }
89
+ answered = await answerSymbols(ctx, project, symbols);
50
90
  }
51
91
  finally {
52
92
  await ctx.close();
53
93
  }
94
+ const { named, blocks } = answered;
54
95
  if (blocks.length === 0)
55
96
  return;
56
97
  const names = named.map((s) => `\`${s}\``).join(', ');
@@ -7,12 +7,14 @@ import { createContext } from '../context.js';
7
7
  import { distillNotice } from '../facts/notice.js';
8
8
  import { startFacts } from '../facts/start.js';
9
9
  import { startBackgroundWork } from './background.js';
10
+ import { refreshGraphInBackground } from './graph-refresh.js';
10
11
  import { recoverAfterCompact } from './compact.js';
11
12
  import { capturingDisabled, emitSessionStart, readPayload, runHook } from './payload.js';
12
13
  import { markShown } from './shown.js';
13
14
  import { legacyBlock } from './start-legacy.js';
14
15
  import { resolveProject } from '../util/project.js';
15
16
  import { mentionsPath } from '../util/paths.js';
17
+ import { repoRootFor } from '../usages/index.js';
16
18
  import { refreshInstalled } from '../cli/refresh.js';
17
19
  import { updateNotice } from '../update.js';
18
20
  import { silenceSqliteWarning } from '../util/warnings.js';
@@ -20,13 +22,9 @@ silenceSqliteWarning();
20
22
  const SERVER = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'mcp', 'server.js');
21
23
  const SCAN_HINT = 'Code graph not built yet — run `claude-db scan` once to enable ' +
22
24
  'find_usages and the symbol-grep hook.';
23
- async function refreshGraphQuietly(store, project) {
25
+ function refreshGraphQuietly(project) {
24
26
  try {
25
- if ((await store.scannedFiles(project)).length === 0)
26
- return;
27
- const { refreshGraph } = await import('../graph/index.js');
28
- const { repoRootFor } = await import('../usages/index.js');
29
- await refreshGraph(store, repoRootFor(project), project);
27
+ refreshGraphInBackground(project, repoRootFor(project));
30
28
  }
31
29
  catch {
32
30
  return;
@@ -72,7 +70,8 @@ await runHook(async () => {
72
70
  parts.push("Search this project's full history with the memory MCP tools before " +
73
71
  'asking the user to re-explain prior decisions.');
74
72
  }
75
- if ((await ctx.store.scannedFiles(project)).length === 0)
73
+ const scanned = (await ctx.store.scannedFiles(project)).length > 0;
74
+ if (!scanned)
76
75
  parts.push(SCAN_HINT);
77
76
  const update = ctx.config.updates === 'off' ? null : updateNotice();
78
77
  if (update)
@@ -80,7 +79,8 @@ await runHook(async () => {
80
79
  const body = parts.join('\n');
81
80
  const notice = capturing ? await distillNotice(ctx, project) : null;
82
81
  emitSessionStart(`${body}\n(context ≈ ${Math.round(body.length / 4)} tokens)\n`, notice);
83
- await refreshGraphQuietly(ctx.store, project);
82
+ if (scanned)
83
+ refreshGraphQuietly(project);
84
84
  }
85
85
  finally {
86
86
  await ctx.close();