claude-db 0.11.1 → 0.12.0

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 (170) hide show
  1. package/CHANGELOG.md +36 -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/index.js +4 -0
  7. package/dist/cli/usage.js +3 -1
  8. package/dist/graph/ast.d.ts +4 -0
  9. package/dist/graph/ast.js +11 -0
  10. package/dist/graph/grammars.d.ts +14 -0
  11. package/dist/graph/grammars.js +58 -0
  12. package/dist/graph/index.d.ts +2 -2
  13. package/dist/graph/index.js +2 -2
  14. package/dist/graph/languages/basic.js +5 -1
  15. package/dist/graph/languages/ecmascript.js +7 -0
  16. package/dist/graph/languages/go.js +0 -1
  17. package/dist/graph/languages/index.d.ts +1 -1
  18. package/dist/graph/languages/index.js +34 -9
  19. package/dist/graph/languages/java.d.ts +2 -0
  20. package/dist/graph/languages/java.js +38 -0
  21. package/dist/graph/languages/kotlin.d.ts +2 -0
  22. package/dist/graph/languages/kotlin.js +19 -0
  23. package/dist/graph/languages/python.js +10 -2
  24. package/dist/graph/languages/rules.d.ts +11 -0
  25. package/dist/graph/languages/rust.js +2 -1
  26. package/dist/graph/modules/binding.d.ts +61 -0
  27. package/dist/graph/modules/binding.js +43 -0
  28. package/dist/graph/modules/ecmascript/bind.d.ts +4 -0
  29. package/dist/graph/modules/ecmascript/bind.js +17 -0
  30. package/dist/graph/modules/ecmascript/contexts.d.ts +6 -0
  31. package/dist/graph/modules/ecmascript/contexts.js +86 -0
  32. package/dist/graph/modules/ecmascript/exports.d.ts +9 -0
  33. package/dist/graph/modules/ecmascript/exports.js +91 -0
  34. package/dist/graph/modules/ecmascript/imports.d.ts +4 -0
  35. package/dist/graph/modules/ecmascript/imports.js +73 -0
  36. package/dist/graph/modules/ecmascript/package-resolver.d.ts +4 -0
  37. package/dist/graph/modules/ecmascript/package-resolver.js +73 -0
  38. package/dist/graph/modules/ecmascript/resolver.d.ts +2 -0
  39. package/dist/graph/modules/ecmascript/resolver.js +22 -0
  40. package/dist/graph/modules/ecmascript/specifiers.d.ts +3 -0
  41. package/dist/graph/modules/ecmascript/specifiers.js +15 -0
  42. package/dist/graph/modules/ecmascript/system.d.ts +2 -0
  43. package/dist/graph/modules/ecmascript/system.js +18 -0
  44. package/dist/graph/modules/ecmascript/workspace-resolver.d.ts +5 -0
  45. package/dist/graph/modules/ecmascript/workspace-resolver.js +38 -0
  46. package/dist/graph/modules/go/grammar.d.ts +2 -0
  47. package/dist/graph/modules/go/grammar.js +54 -0
  48. package/dist/graph/modules/go/imports.d.ts +4 -0
  49. package/dist/graph/modules/go/imports.js +32 -0
  50. package/dist/graph/modules/go/resolver.d.ts +2 -0
  51. package/dist/graph/modules/go/resolver.js +54 -0
  52. package/dist/graph/modules/go/system.d.ts +2 -0
  53. package/dist/graph/modules/go/system.js +16 -0
  54. package/dist/graph/modules/java/declarations.d.ts +9 -0
  55. package/dist/graph/modules/java/declarations.js +108 -0
  56. package/dist/graph/modules/java/grammar.d.ts +2 -0
  57. package/dist/graph/modules/java/grammar.js +135 -0
  58. package/dist/graph/modules/java/imports.d.ts +4 -0
  59. package/dist/graph/modules/java/imports.js +13 -0
  60. package/dist/graph/modules/java/receivers.d.ts +3 -0
  61. package/dist/graph/modules/java/receivers.js +139 -0
  62. package/dist/graph/modules/java/system.d.ts +1 -0
  63. package/dist/graph/modules/java/system.js +13 -0
  64. package/dist/graph/modules/jvm/linking.d.ts +20 -0
  65. package/dist/graph/modules/jvm/linking.js +64 -0
  66. package/dist/graph/modules/jvm/packages.d.ts +5 -0
  67. package/dist/graph/modules/jvm/packages.js +58 -0
  68. package/dist/graph/modules/jvm/receivers.d.ts +44 -0
  69. package/dist/graph/modules/jvm/receivers.js +77 -0
  70. package/dist/graph/modules/jvm/system.d.ts +18 -0
  71. package/dist/graph/modules/jvm/system.js +29 -0
  72. package/dist/graph/modules/jvm/types.d.ts +3 -0
  73. package/dist/graph/modules/jvm/types.js +11 -0
  74. package/dist/graph/modules/kotlin/declarations.d.ts +8 -0
  75. package/dist/graph/modules/kotlin/declarations.js +69 -0
  76. package/dist/graph/modules/kotlin/grammar.d.ts +2 -0
  77. package/dist/graph/modules/kotlin/grammar.js +78 -0
  78. package/dist/graph/modules/kotlin/imports.d.ts +4 -0
  79. package/dist/graph/modules/kotlin/imports.js +25 -0
  80. package/dist/graph/modules/kotlin/receivers.d.ts +3 -0
  81. package/dist/graph/modules/kotlin/receivers.js +105 -0
  82. package/dist/graph/modules/kotlin/references.d.ts +8 -0
  83. package/dist/graph/modules/kotlin/references.js +69 -0
  84. package/dist/graph/modules/kotlin/system.d.ts +1 -0
  85. package/dist/graph/modules/kotlin/system.js +15 -0
  86. package/dist/graph/modules/members.d.ts +17 -0
  87. package/dist/graph/modules/members.js +30 -0
  88. package/dist/graph/modules/module-index.d.ts +9 -0
  89. package/dist/graph/modules/module-index.js +62 -0
  90. package/dist/graph/modules/names.d.ts +2 -0
  91. package/dist/graph/modules/names.js +3 -0
  92. package/dist/graph/modules/python/grammar.d.ts +2 -0
  93. package/dist/graph/modules/python/grammar.js +100 -0
  94. package/dist/graph/modules/python/imports.d.ts +3 -0
  95. package/dist/graph/modules/python/imports.js +72 -0
  96. package/dist/graph/modules/python/resolver.d.ts +2 -0
  97. package/dist/graph/modules/python/resolver.js +78 -0
  98. package/dist/graph/modules/python/system.d.ts +2 -0
  99. package/dist/graph/modules/python/system.js +16 -0
  100. package/dist/graph/modules/rebind.d.ts +8 -0
  101. package/dist/graph/modules/rebind.js +51 -0
  102. package/dist/graph/modules/registry.d.ts +5 -0
  103. package/dist/graph/modules/registry.js +47 -0
  104. package/dist/graph/modules/rust/grammar.d.ts +2 -0
  105. package/dist/graph/modules/rust/grammar.js +94 -0
  106. package/dist/graph/modules/rust/imports.d.ts +3 -0
  107. package/dist/graph/modules/rust/imports.js +90 -0
  108. package/dist/graph/modules/rust/resolver.d.ts +3 -0
  109. package/dist/graph/modules/rust/resolver.js +153 -0
  110. package/dist/graph/modules/rust/system.d.ts +2 -0
  111. package/dist/graph/modules/rust/system.js +16 -0
  112. package/dist/graph/modules/shadowing.d.ts +17 -0
  113. package/dist/graph/modules/shadowing.js +65 -0
  114. package/dist/graph/modules/system.d.ts +39 -0
  115. package/dist/graph/modules/system.js +1 -0
  116. package/dist/graph/modules/uses.d.ts +14 -0
  117. package/dist/graph/modules/uses.js +62 -0
  118. package/dist/graph/parser.d.ts +9 -11
  119. package/dist/graph/parser.js +5 -4
  120. package/dist/graph/query/answer.d.ts +15 -0
  121. package/dist/graph/query/answer.js +22 -0
  122. package/dist/graph/query/format.d.ts +8 -1
  123. package/dist/graph/query/format.js +103 -30
  124. package/dist/graph/query/groups.d.ts +14 -0
  125. package/dist/graph/query/groups.js +51 -0
  126. package/dist/graph/query/index.d.ts +2 -1
  127. package/dist/graph/query/index.js +2 -1
  128. package/dist/graph/query/lookup.d.ts +2 -0
  129. package/dist/graph/query/lookup.js +19 -2
  130. package/dist/graph/query/refresh.js +17 -18
  131. package/dist/graph/query/stale.d.ts +2 -0
  132. package/dist/graph/query/stale.js +39 -0
  133. package/dist/graph/query/text.d.ts +12 -0
  134. package/dist/graph/query/text.js +26 -0
  135. package/dist/graph/scan/binder.d.ts +13 -0
  136. package/dist/graph/scan/binder.js +210 -0
  137. package/dist/graph/scan/cache.d.ts +11 -0
  138. package/dist/graph/scan/cache.js +140 -0
  139. package/dist/graph/scan/extract.d.ts +4 -17
  140. package/dist/graph/scan/extract.js +105 -83
  141. package/dist/graph/scan/files.d.ts +3 -9
  142. package/dist/graph/scan/files.js +3 -2
  143. package/dist/graph/scan/index.d.ts +8 -3
  144. package/dist/graph/scan/index.js +96 -36
  145. package/dist/graph/scan/job.d.ts +1 -0
  146. package/dist/graph/scan/job.js +1 -0
  147. package/dist/graph/scan/persist.d.ts +3 -0
  148. package/dist/graph/scan/persist.js +22 -0
  149. package/dist/graph/scan/receivers.d.ts +21 -0
  150. package/dist/graph/scan/receivers.js +87 -0
  151. package/dist/graph/scan/resolve.d.ts +8 -2
  152. package/dist/graph/scan/resolve.js +50 -56
  153. package/dist/graph/scan/spans.d.ts +13 -0
  154. package/dist/graph/scan/spans.js +42 -0
  155. package/dist/graph/symbols.d.ts +10 -0
  156. package/dist/graph/symbols.js +30 -0
  157. package/dist/graph/types.d.ts +56 -0
  158. package/dist/graph/types.js +1 -0
  159. package/dist/hooks/background.js +1 -16
  160. package/dist/hooks/detached.d.ts +3 -0
  161. package/dist/hooks/detached.js +16 -0
  162. package/dist/hooks/graph-refresh.d.ts +1 -0
  163. package/dist/hooks/graph-refresh.js +9 -0
  164. package/dist/hooks/prefer-usages.js +53 -12
  165. package/dist/hooks/session-start.js +8 -8
  166. package/dist/mcp/tools/usages.js +40 -31
  167. package/dist/types.d.ts +1 -1
  168. package/dist/usages/find.js +1 -0
  169. package/docs/how-it-works.md +10 -8
  170. package/package.json +16 -5
@@ -1,6 +1,6 @@
1
1
  import { z } from 'zod';
2
2
  import { findUsages as textUsages, formatUsages, repoRootFor } from '../../usages/index.js';
3
- import { formatGraph, queryGraph, refreshGraph, suggestFor } from '../../graph/index.js';
3
+ import { NO_GRAPH, NO_GRAPH_FOR_PATH, answerQuery, formatGraph, hasGraph, suggestFor, } from '../../graph/index.js';
4
4
  import { resolveProject } from '../../util/project.js';
5
5
  export function register(server, ctx) {
6
6
  server.tool('find_usages', 'USE THIS INSTEAD OF grep/rg WHENEVER THE THING YOU ARE LOOKING UP IS A CODE ' +
@@ -9,16 +9,16 @@ export function register(server, ctx) {
9
9
  'grep cannot tell a call from an import from an inherit and will not show ' +
10
10
  'you the blast radius. Reach for grep only for what is genuinely text: ' +
11
11
  'plain prose, comments, log output, string literals, multi-pattern regex, ' +
12
- 'or the scoping flags this tool does not expose. Modes: "usages" lists what ' +
13
- 'references the symbol with the relation on each line, "explain" adds what ' +
14
- 'the symbol reaches, "path" traces how two symbols connect (pass the second ' +
15
- 'as `target`), and `mode: "text"` (default) is a live `git grep` that needs ' +
16
- 'no scan. Graph modes read the graph built by `claude-db scan` and re-parse ' +
17
- 'anything that changed before replying, so they cannot report a line the ' +
18
- 'source has moved past. Every edge is tagged EXTRACTED (read literally from ' +
19
- 'the syntax) or INFERRED (matched by name across files, with a score). A ' +
20
- 'miss suggests near names, so a half-remembered symbol is still worth ' +
21
- 'asking about. Use `search` instead for "why is this the way it is" (history).', {
12
+ 'or the scoping flags this tool does not expose. Modes: "usages" (default) ' +
13
+ 'lists what references the symbol, with the relation on each line, then the ' +
14
+ 'grep lines the graph could not link; "explain" adds what the symbol reaches, ' +
15
+ '"path" traces how two symbols connect (pass the second as `target`), and ' +
16
+ '"text" is a plain live `git grep`. Graph modes re-parse anything that ' +
17
+ 'changed before replying, and answer from text until `claude-db scan` has ' +
18
+ 'run. Every edge is tagged EXTRACTED (read literally from the syntax) or ' +
19
+ 'INFERRED (matched by name across files, with a score). A miss suggests near ' +
20
+ 'names, so a half-remembered symbol is still worth asking about. Use `search` ' +
21
+ 'instead for "why is this the way it is" (history).', {
22
22
  symbol: z
23
23
  .string()
24
24
  .min(1)
@@ -26,9 +26,9 @@ export function register(server, ctx) {
26
26
  .describe('Exact name to search for, e.g. "useAuth" or "CartButton"'),
27
27
  mode: z
28
28
  .enum(['text', 'usages', 'explain', 'path'])
29
- .default('text')
30
- .describe('How to answer. "text" greps live and needs no scan; the rest query the ' +
31
- 'stored graph and return nothing useful until `claude-db scan` has run'),
29
+ .default('usages')
30
+ .describe('How to answer. "usages" (default) uses the code graph plus grep; "text" ' +
31
+ 'greps live only'),
32
32
  target: z.string().optional().describe('The second symbol, for mode "path" only'),
33
33
  path: z
34
34
  .string()
@@ -58,23 +58,32 @@ export function register(server, ctx) {
58
58
  .describe('Cap on matching lines returned; the result says how many more exist'),
59
59
  }, (args) => find_usages(ctx, args));
60
60
  }
61
- async function find_usages(ctx, { symbol, mode, target, path, regex, context, limit, }) {
62
- if (mode === 'text') {
63
- const result = textUsages({ symbol, regex, context, limit, ...(path ? { path } : {}) });
64
- const missed = result.matches.length === 0
65
- ? await suggestFor(ctx.store, resolveProject(undefined), symbol)
66
- : [];
67
- return { content: [{ type: 'text', text: formatUsages(result, missed) }] };
68
- }
69
- const root = repoRootFor(path ?? process.cwd());
61
+ const reply = (text) => ({ content: [{ type: 'text', text }] });
62
+ async function textAnswer(ctx, args) {
63
+ const { symbol, regex, context, limit, path } = args;
64
+ const result = textUsages({ symbol, regex, context, limit, ...(path ? { path } : {}) });
65
+ const missed = result.matches.length === 0
66
+ ? await suggestFor(ctx.store, resolveProject(undefined), symbol)
67
+ : [];
68
+ return formatUsages(result, missed);
69
+ }
70
+ async function find_usages(ctx, args) {
71
+ if (args.mode === 'text')
72
+ return reply(await textAnswer(ctx, args));
70
73
  const project = resolveProject(undefined);
71
- const refreshed = await refreshGraph(ctx.store, root, project);
72
- const answer = await queryGraph(ctx.store, project, {
73
- mode,
74
- symbol,
75
- ...(target ? { target } : {}),
76
- limit,
74
+ if (!(await hasGraph(ctx.store, project))) {
75
+ if (args.mode === 'path')
76
+ return reply(NO_GRAPH_FOR_PATH);
77
+ return reply(`${NO_GRAPH}\n${await textAnswer(ctx, args)}`);
78
+ }
79
+ const root = repoRootFor(args.path ?? process.cwd());
80
+ const { mode, symbol, target, limit } = args;
81
+ const answer = await answerQuery({
82
+ store: ctx.store,
83
+ root,
84
+ project,
85
+ query: { mode, symbol, ...(target ? { target } : {}), limit },
86
+ refresh: true,
77
87
  });
78
- answer.refreshed = refreshed;
79
- return { content: [{ type: 'text', text: formatGraph(answer, root) }] };
88
+ return reply(formatGraph(answer, root));
80
89
  }
package/dist/types.d.ts CHANGED
@@ -68,7 +68,7 @@ export interface TimelineQuery {
68
68
  after: number;
69
69
  }
70
70
  export type SymbolKind = 'function' | 'class' | 'interface' | 'type' | 'enum' | 'const' | 'method';
71
- export type EdgeRelation = 'calls' | 'imports' | 'extends' | 'implements' | 'references' | 'defines';
71
+ export type EdgeRelation = 'calls' | 'imports' | 'extends' | 'implements' | 'references' | 'defines' | 'aliases';
72
72
  export type EdgeConfidence = 'EXTRACTED' | 'INFERRED';
73
73
  export interface CodeSymbol {
74
74
  id: string;
@@ -43,6 +43,7 @@ export function repoRootFor(start) {
43
43
  try {
44
44
  return execFileSync('git', ['-C', dir, 'rev-parse', '--show-toplevel'], {
45
45
  encoding: 'utf8',
46
+ stdio: ['ignore', 'pipe', 'pipe'],
46
47
  }).trim();
47
48
  }
48
49
  catch (error) {
@@ -172,12 +172,15 @@ re-parses files whose contents changed.
172
172
 
173
173
  `find_usages` then answers in four modes, over MCP as well as the CLI:
174
174
 
175
- | mode | answers |
176
- | ---------------- | ----------------------------------------------------------- |
177
- | `text` (default) | live `git grep`; needs no scan and is never stale |
178
- | `usages` | what references this symbol, with the relation on each line |
179
- | `explain` | that, plus what the symbol itself reaches |
180
- | `path` | how two symbols connect |
175
+ | mode | answers |
176
+ | ------------------ | ----------------------------------------------------------- |
177
+ | `usages` (default) | what references this symbol, with the relation on each line |
178
+ | `explain` | that, plus what the symbol itself reaches |
179
+ | `path` | how two symbols connect |
180
+ | `text` | live `git grep`; needs no scan |
181
+
182
+ `usages` ends with the lines `git grep` finds that the graph could not link, so
183
+ it never shows less than a plain search.
181
184
 
182
185
  ```
183
186
  Shortest path (4 hops):
@@ -194,8 +197,7 @@ so it is labelled rather than presented as fact.
194
197
  **A stored index can go stale, and this one is not allowed to.** Every graph
195
198
  query hashes the working tree first and re-parses whatever changed before
196
199
  answering, so it cannot report a line the source has already moved past. The
197
- SessionStart hook does the same refresh in the background for repositories that
198
- have been scanned, but correctness does not depend on it having run.
200
+ hooks refresh in the background instead, so they never wait.
199
201
 
200
202
  Traversal is keyed on symbol id rather than name. Keying by name would merge
201
203
  every same-named symbol into one node, and a repository with a `run` in each
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "claude-db",
3
- "version": "0.11.1",
3
+ "version": "0.12.0",
4
4
  "description": "Free, open-source memory for Claude Code. Remembers why decisions were made and maps your code. Your own database (SQLite, Postgres or MongoDB), no cloud, no subscription.",
5
5
  "license": "Apache-2.0",
6
6
  "type": "module",
@@ -45,24 +45,28 @@
45
45
  "bench:tokens": "node scripts/bench-tokens.mjs",
46
46
  "bench:ab": "node scripts/bench-ab.mjs",
47
47
  "bench:inject": "node scripts/bench-inject.mjs",
48
+ "bench:usages": "node scripts/bench-usages.mjs",
48
49
  "postinstall": "node -e \"const v=process.versions.node.split('.').map(Number); if(v[0]<22||(v[0]===22&&v[1]<16)){console.error('\\n claude-db needs Node >= 22.16 (its builtin SQLite has full-text search from there). You have '+process.versions.node+'.\\n');process.exit(1)}\"",
49
50
  "prepublishOnly": "npm run build && npm test",
50
51
  "format": "prettier --write .",
51
52
  "format:check": "prettier --check ."
52
53
  },
53
54
  "dependencies": {
54
- "@ast-grep/lang-go": "^0.0.6",
55
- "@ast-grep/lang-python": "^0.0.6",
56
- "@ast-grep/lang-ruby": "^0.0.7",
57
- "@ast-grep/lang-rust": "^0.0.7",
58
55
  "@ast-grep/napi": "^0.45.0",
59
56
  "@modelcontextprotocol/sdk": "^1.30.0",
60
57
  "graphology": "^0.26.0",
61
58
  "graphology-shortest-path": "^2.1.0",
59
+ "oxc-resolver": "^11.24.2",
62
60
  "zod": "^4.4.3"
63
61
  },
64
62
  "devDependencies": {
65
63
  "@arethetypeswrong/cli": "^0.18.5",
64
+ "@ast-grep/lang-go": "^0.0.6",
65
+ "@ast-grep/lang-java": "^0.0.7",
66
+ "@ast-grep/lang-kotlin": "0.0.7",
67
+ "@ast-grep/lang-python": "^0.0.6",
68
+ "@ast-grep/lang-ruby": "^0.0.7",
69
+ "@ast-grep/lang-rust": "^0.0.7",
66
70
  "@eslint/js": "^10.0.1",
67
71
  "@types/node": "^22.20.1",
68
72
  "c8": "^12.0.0",
@@ -124,5 +128,12 @@
124
128
  "author": "Avijit Dey",
125
129
  "publishConfig": {
126
130
  "access": "public"
131
+ },
132
+ "optionalDependencies": {
133
+ "claude-db-grammars-linux-x64": "0.12.0",
134
+ "claude-db-grammars-linux-arm64": "0.12.0",
135
+ "claude-db-grammars-darwin-x64": "0.12.0",
136
+ "claude-db-grammars-darwin-arm64": "0.12.0",
137
+ "claude-db-grammars-win32-x64": "0.12.0"
127
138
  }
128
139
  }