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
package/CHANGELOG.md CHANGED
@@ -1,5 +1,41 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.12.0
4
+
5
+ ### Added
6
+
7
+ - **Imports are followed in seven languages.** TypeScript, JavaScript, Python, Go, Rust, Java and Kotlin bind
8
+ an import to the exact file and symbol it names, so two symbols with one name in different modules stay
9
+ apart. `usages` lists the importing files in an `Imported by` group, and a name exported under another
10
+ name is followed too.
11
+ - **Java and Kotlin method calls reach the right method.** `x.method()` goes to the method of the declared
12
+ type of `x`, through parent classes and chained calls. A call on a value of unknown type stays `INFERRED`
13
+ and is listed once, under all the definitions it could be.
14
+ - **Kotlin is read with real syntax after install.** Grammars now ship as one small package per platform,
15
+ so nothing is downloaded and the install is about 44 MB smaller. `claude-db languages` shows how each
16
+ language is read; `languages add` and `remove` have nothing left to do. Where no grammar package fits,
17
+ such as Alpine Linux, those languages are read by pattern.
18
+
19
+ ### Changed
20
+
21
+ - **`find_usages` and `claude-db usages` answer from the graph by default.** References are grouped under
22
+ the definition they belong to, and lines that `git grep` finds but the graph cannot link come last, so
23
+ nothing a search would find is lost. Before the first `scan`, the answer comes from text and says so.
24
+ - **Scans re-read only what changed.** A local cache keeps each file's parse, so a refresh after an edit
25
+ takes well under a second. The first scan after upgrading re-reads every file once.
26
+ - **Hooks never wait for the graph.** The grep hook says when files changed since the last scan and
27
+ refreshes the graph in the background.
28
+
29
+ ### Development
30
+
31
+ - `npm run bench:usages` measures `find_usages` against compilers and independent checkers on 28 pinned
32
+ public repositories, with a nightly check for regressions.
33
+ - Code graph tests are fixture files run by one runner.
34
+
35
+ ### Docs
36
+
37
+ - A shorter CONTRIBUTING, with separate pages for adding a language and for releasing.
38
+
3
39
  ## 0.11.1
4
40
 
5
41
  ### Fixed
package/README.md CHANGED
@@ -26,8 +26,9 @@ gives Claude the right part of it at the right time.
26
26
  chat ends, and the next chat starts by seeing them.
27
27
  - **Recalls what fits.** Each prompt gets the one or two earlier memories that
28
28
  match it, and nothing when none fit.
29
- - **Maps your code.** Who defines or calls a symbol is answered in one call,
30
- instead of grep and reading files.
29
+ - **Maps your code.** Who defines, calls or imports a symbol is answered in one
30
+ call, instead of grep and reading files. It follows imports in TypeScript,
31
+ JavaScript, Python, Go, Rust, Java and Kotlin.
31
32
  - **Keeps it yours.** SQLite on your machine by default, or Postgres or MongoDB
32
33
  to share across machines. No cloud, no subscription.
33
34
 
@@ -91,8 +92,8 @@ npm test
91
92
  npm run lint
92
93
  ```
93
94
 
94
- [CONTRIBUTING.md](./CONTRIBUTING.md) has the conventions, the test setup, how to
95
- add a language to the code graph, and how releases are made. Security reports go
95
+ [CONTRIBUTING.md](./CONTRIBUTING.md) has the setup, the rules and the pull request
96
+ checklist, with links to adding a language and to releasing. Security reports go
96
97
  through [SECURITY.md](./SECURITY.md), privately.
97
98
 
98
99
  ## License
@@ -1,112 +1,136 @@
1
1
  import { createContext } from '../../context.js';
2
2
  import { findUsages, formatUsages, repoRootFor } from '../../usages/index.js';
3
- import { formatGraph, languageNames, queryGraph, refreshGraph, scanRepository, suggestFor, } from '../../graph/index.js';
3
+ import { NO_GRAPH, NO_GRAPH_FOR_PATH, answerQuery, formatGraph, hasGraph, languageNames, refreshGraph, saveScan, scanRepository, suggestFor, } from '../../graph/index.js';
4
+ import { PLATFORM } from '../../graph/grammars.js';
5
+ import { GRAPH_JOB } from '../../graph/scan/job.js';
6
+ import { releaseJob } from '../../util/job-lock.js';
4
7
  import { resolveProject } from '../../util/project.js';
5
8
  import { valueOf, withoutFlags } from '../args.js';
9
+ function printScan(root, scan, elapsedMs) {
10
+ console.log(`Scanned ${root}`);
11
+ console.log(` ${scan.symbols.length} symbols, ${scan.edges.length} edges written for ` +
12
+ `${scan.rewrite.length} file(s)`);
13
+ console.log(` ${scan.changed.length} file(s) parsed, ${scan.skipped} unchanged, ` +
14
+ `${scan.unsupported} not a supported language`);
15
+ console.log(` ${elapsedMs}ms (languages: ${languageNames()})`);
16
+ for (const [language, count] of Object.entries(scan.patternRead)) {
17
+ console.log(` ${count} ${language} file(s) are read by pattern: this install has no ${language} ` +
18
+ `grammar for ${PLATFORM}. Reinstall claude-db to add it.`);
19
+ }
20
+ if (scan.symbols.length === 0 && scan.changed.length > 0) {
21
+ console.log(' Nothing was extracted, which usually means no supported source files.');
22
+ }
23
+ }
24
+ async function runScan(root, project, force) {
25
+ const ctx = await createContext();
26
+ try {
27
+ const stored = new Map((await ctx.store.scannedFiles(project)).map((file) => [file.path, file.hash]));
28
+ const started = Date.now();
29
+ const scan = await scanRepository({ root, project, stored, force });
30
+ await saveScan(ctx.store, project, scan, force);
31
+ printScan(root, scan, Date.now() - started);
32
+ }
33
+ finally {
34
+ await ctx.close();
35
+ }
36
+ }
37
+ async function runRefresh(root, project) {
38
+ const ctx = await createContext();
39
+ try {
40
+ await refreshGraph(ctx.store, root, project);
41
+ }
42
+ finally {
43
+ await ctx.close();
44
+ }
45
+ }
6
46
  export async function cmdScan(argv) {
7
- const force = argv.includes('--force');
8
47
  const path = valueOf(argv, '--path');
9
48
  const root = repoRootFor(path ?? process.cwd());
10
49
  const project = resolveProject(undefined);
11
- const ctx = await createContext();
50
+ if (!argv.includes('--background')) {
51
+ await runScan(root, project, argv.includes('--force'));
52
+ return;
53
+ }
12
54
  try {
13
- const known = force
14
- ? new Map()
15
- : new Map((await ctx.store.scannedFiles(project)).map((f) => [f.path, f.hash]));
16
- const existing = force ? [] : await ctx.store.findSymbols({ project, limit: 200000 });
17
- const started = Date.now();
18
- const scan = scanRepository({
19
- root,
20
- project,
21
- known,
22
- ...(force ? { force } : {}),
23
- ...(existing.length > 0 ? { existing } : {}),
24
- });
25
- if (force)
26
- await ctx.store.removeGraph(project);
27
- else if (scan.changed.length > 0)
28
- await ctx.store.removeGraph(project, scan.changed);
29
- await ctx.store.upsertGraph({
30
- symbols: scan.symbols,
31
- edges: scan.edges,
32
- files: scan.files,
33
- });
34
- console.log(`Scanned ${root}`);
35
- console.log(` ${scan.symbols.length} symbols, ${scan.edges.length} edges`);
36
- console.log(` ${scan.changed.length} file(s) parsed, ${scan.skipped} unchanged, ` +
37
- `${scan.unsupported} not a supported language`);
38
- console.log(` ${Date.now() - started}ms (languages: ${languageNames()})`);
39
- if (scan.symbols.length === 0 && scan.changed.length > 0) {
40
- console.log(' Nothing was extracted, which usually means no supported source files.');
41
- }
55
+ await runRefresh(root, project);
42
56
  }
43
57
  finally {
44
- await ctx.close();
58
+ releaseJob(GRAPH_JOB, project);
45
59
  }
46
60
  }
47
- export async function cmdUsages(argv) {
48
- const regex = argv.includes('--regex');
61
+ const MODES = ['text', 'usages', 'explain', 'path'];
62
+ function fail(message) {
63
+ console.error(message);
64
+ process.exit(1);
65
+ }
66
+ const isMode = (value) => MODES.includes(value);
67
+ function usagesInput(argv) {
49
68
  const path = valueOf(argv, '--path');
69
+ const target = valueOf(argv, '--target');
70
+ const mode = valueOf(argv, '--mode') ?? 'usages';
50
71
  const context = Number(valueOf(argv, '--context') ?? 0);
51
72
  const limit = Number(valueOf(argv, '--limit') ?? 100);
52
- const mode = valueOf(argv, '--mode') ?? 'text';
53
- const targetFlag = valueOf(argv, '--target');
54
73
  const words = withoutFlags(argv, ['--path', '--context', '--limit', '--mode', '--target'])
55
74
  .filter((arg) => arg !== '--regex')
56
75
  .join(' ')
57
76
  .trim();
58
77
  if (!words) {
59
- console.error('Usage: claude-db usages [--mode text|usages|explain|path] [--regex] ' +
78
+ fail('Usage: claude-db usages [--mode usages|explain|path|text] [--regex] ' +
60
79
  '[--context <n>] [--path <dir>] [--limit <n>] <symbol> [<target>]');
61
- process.exit(1);
62
- }
63
- if (!Number.isFinite(context) || context < 0) {
64
- console.error('--context must be a non-negative number.');
65
- process.exit(1);
66
- }
67
- if (!Number.isFinite(limit) || limit <= 0) {
68
- console.error('--limit must be a positive number.');
69
- process.exit(1);
70
- }
71
- if (mode === 'text') {
72
- const result = findUsages({ symbol: words, regex, context, limit, ...(path ? { path } : {}) });
73
- console.log(formatUsages(result, await suggestionsOnMiss(result.matches.length, words)));
74
- return;
75
- }
76
- if (mode !== 'usages' && mode !== 'explain' && mode !== 'path') {
77
- console.error(`Unknown --mode "${mode}". Use text, usages, explain or path.`);
78
- process.exit(1);
79
80
  }
80
- const [symbol, positional] = words.split(/\s+/);
81
- const target = targetFlag ?? positional;
82
- if (mode === 'path' && !target) {
83
- console.error('--mode path needs two symbols: claude-db usages --mode path <from> <to>');
84
- process.exit(1);
81
+ if (!Number.isFinite(context) || context < 0)
82
+ fail('--context must be a non-negative number.');
83
+ if (!Number.isFinite(limit) || limit <= 0)
84
+ fail('--limit must be a positive number.');
85
+ if (!isMode(mode))
86
+ fail(`Unknown --mode "${mode}". Use usages, explain, path or text.`);
87
+ return {
88
+ words,
89
+ mode,
90
+ regex: argv.includes('--regex'),
91
+ context,
92
+ limit,
93
+ ...(path ? { path } : {}),
94
+ ...(target ? { target } : {}),
95
+ };
96
+ }
97
+ async function textAnswer(store, input) {
98
+ const { words, regex, context, limit, path } = input;
99
+ const result = findUsages({ symbol: words, regex, context, limit, ...(path ? { path } : {}) });
100
+ const missed = result.matches.length === 0 ? await suggestFor(store, resolveProject(undefined), words) : [];
101
+ return formatUsages(result, missed);
102
+ }
103
+ async function graphAnswer(store, input) {
104
+ const [symbol = '', positional] = input.words.split(/\s+/);
105
+ const target = input.target ?? positional;
106
+ if (input.mode === 'path' && !target) {
107
+ fail('--mode path needs two symbols: claude-db usages --mode path <from> <to>');
85
108
  }
86
- const root = repoRootFor(path ?? process.cwd());
87
109
  const project = resolveProject(undefined);
88
- const ctx = await createContext();
89
- try {
90
- const refreshed = await refreshGraph(ctx.store, root, project);
91
- const answer = await queryGraph(ctx.store, project, {
92
- mode,
93
- symbol: symbol ?? '',
94
- ...(target ? { target } : {}),
95
- limit,
96
- });
97
- answer.refreshed = refreshed;
98
- console.log(formatGraph(answer, root));
99
- }
100
- finally {
101
- await ctx.close();
110
+ if (!(await hasGraph(store, project))) {
111
+ if (input.mode === 'path')
112
+ fail(NO_GRAPH_FOR_PATH);
113
+ return `${NO_GRAPH}\n${await textAnswer(store, input)}`;
102
114
  }
115
+ const root = repoRootFor(input.path ?? process.cwd());
116
+ const mode = input.mode === 'text' ? 'usages' : input.mode;
117
+ const answer = await answerQuery({
118
+ store,
119
+ root,
120
+ project,
121
+ query: { mode, symbol, ...(target ? { target } : {}), limit: input.limit },
122
+ refresh: true,
123
+ });
124
+ return formatGraph(answer, root);
103
125
  }
104
- async function suggestionsOnMiss(matches, symbol) {
105
- if (matches > 0)
106
- return [];
126
+ export async function cmdUsages(argv) {
127
+ const input = usagesInput(argv);
107
128
  const ctx = await createContext();
108
129
  try {
109
- return await suggestFor(ctx.store, resolveProject(undefined), symbol);
130
+ const text = input.mode === 'text'
131
+ ? await textAnswer(ctx.store, input)
132
+ : await graphAnswer(ctx.store, input);
133
+ console.log(text);
110
134
  }
111
135
  finally {
112
136
  await ctx.close();
@@ -0,0 +1 @@
1
+ export declare function cmdLanguages(argv: (string | undefined)[]): void;
@@ -0,0 +1,22 @@
1
+ import { GRAMMARS, PLATFORM, hasGrammar } from '../../graph/grammars.js';
2
+ import { languageNames } from '../../graph/index.js';
3
+ const SHIPPED = 'Grammars ship with claude-db for each platform, so there is nothing to add or remove.';
4
+ const stateOf = (name) => hasGrammar(name)
5
+ ? 'read with real syntax'
6
+ : `read by pattern: no grammar for ${PLATFORM} in this install`;
7
+ function listLanguages() {
8
+ console.log(`read with real syntax: ${languageNames()}`);
9
+ for (const name of GRAMMARS)
10
+ console.log(` ${name.padEnd(8)} ${stateOf(name)}`);
11
+ if (GRAMMARS.some((name) => !hasGrammar(name))) {
12
+ console.log('Reinstall claude-db to add the grammars for this platform.');
13
+ }
14
+ }
15
+ export function cmdLanguages(argv) {
16
+ const [action] = argv.filter((arg) => arg !== undefined);
17
+ if (action === undefined || action === 'list')
18
+ return listLanguages();
19
+ if (action === 'add' || action === 'remove')
20
+ return console.log(SHIPPED);
21
+ throw new Error('usage: claude-db languages [list]');
22
+ }
package/dist/cli/index.js CHANGED
@@ -13,6 +13,7 @@ import { cmdCatchup } from './commands/catchup.js';
13
13
  import { cmdDistill } from './commands/distill.js';
14
14
  import { cmdPick } from './commands/pick.js';
15
15
  import { cmdScan, cmdUsages } from './commands/graph.js';
16
+ import { cmdLanguages } from './commands/languages.js';
16
17
  import { cmdSeed } from './commands/seed.js';
17
18
  import { cmdAdoption } from './commands/adoption.js';
18
19
  import { cmdView } from './commands/view.js';
@@ -110,6 +111,9 @@ async function run() {
110
111
  case 'scan':
111
112
  await cmdScan(args);
112
113
  break;
114
+ case 'languages':
115
+ cmdLanguages(args);
116
+ break;
113
117
  case 'sync':
114
118
  await cmdSync(args);
115
119
  break;
package/dist/cli/usage.js CHANGED
@@ -26,7 +26,9 @@ export function usage() {
26
26
  [--repair] ...only chats that already have memory
27
27
  seed --from-git [--limit n] Fill a cold memory from this repo's history
28
28
  scan [--force] Map this repo's symbols and how they connect
29
- usages [--mode m] <symbol> Who uses a symbol; --mode usages|explain|path
29
+ languages Show how each language is read: real syntax or pattern
30
+ usages [--mode m] <symbol> Who uses a symbol: the graph, then text it could not link
31
+ [--mode usages|explain|path|text]
30
32
  [--target <symbol>] ...the second symbol, for --mode path
31
33
  [--regex] [--context n] [--path <dir>] [--limit n]
32
34
  export [--all] > out.jsonl Dump memory as JSONL, for backup or migration
@@ -0,0 +1,4 @@
1
+ import type { AstNode, AstRange } from './parser.js';
2
+ export declare function sameNode(a: AstNode | null, b: AstNode): boolean;
3
+ export declare function originFrom({ start, end }: AstRange): string;
4
+ export declare const originOf: (node: AstNode) => string;
@@ -0,0 +1,11 @@
1
+ export function sameNode(a, b) {
2
+ if (!a)
3
+ return false;
4
+ const left = a.range().start;
5
+ const right = b.range().start;
6
+ return left.line === right.line && left.column === right.column;
7
+ }
8
+ export function originFrom({ start, end }) {
9
+ return `${start.line}:${start.column}-${end.line}:${end.column}`;
10
+ }
11
+ export const originOf = (node) => originFrom(node.range());
@@ -0,0 +1,14 @@
1
+ export interface Grammar {
2
+ readonly libraryPath: string;
3
+ }
4
+ export type Load = (id: string) => unknown;
5
+ export declare const GRAMMARS: readonly string[];
6
+ export declare const PLATFORM: string;
7
+ export declare const PLATFORM_PACKAGE: string;
8
+ export declare const grammarHome: () => string;
9
+ export declare const isUsable: (grammar: unknown) => grammar is Grammar;
10
+ export declare function findGrammar(name: string, loads: readonly Load[]): Grammar | undefined;
11
+ export declare function loadGrammar(name: string): Grammar | undefined;
12
+ export declare const hasGrammar: (name: string) => boolean;
13
+ export declare const availableGrammars: () => string[];
14
+ export declare function grammarSignature(): string;
@@ -0,0 +1,58 @@
1
+ import { statSync } from 'node:fs';
2
+ import { createRequire } from 'node:module';
3
+ import { join } from 'node:path';
4
+ import { CONFIG_DIR } from '../config/dir.js';
5
+ export const GRAMMARS = ['go', 'java', 'kotlin', 'python', 'ruby', 'rust'];
6
+ export const PLATFORM = `${process.platform}-${process.arch}`;
7
+ export const PLATFORM_PACKAGE = `claude-db-grammars-${PLATFORM}`;
8
+ const loaded = new Map();
9
+ export const grammarHome = () => process.env.CLAUDE_DB_GRAMMARS ?? join(CONFIG_DIR, 'grammars');
10
+ const places = () => [
11
+ createRequire(import.meta.url),
12
+ createRequire(join(grammarHome(), 'package.json')),
13
+ ];
14
+ function fromPlatform(load, name) {
15
+ const grammars = load(PLATFORM_PACKAGE);
16
+ return grammars[name];
17
+ }
18
+ function fromAstGrep(load, name) {
19
+ const grammar = load(`@ast-grep/lang-${name}`);
20
+ return grammar.default ?? grammar;
21
+ }
22
+ function librarySize(grammar) {
23
+ try {
24
+ const path = grammar.libraryPath;
25
+ return typeof path === 'string' && path.length > 0 ? statSync(path).size : 0;
26
+ }
27
+ catch {
28
+ return 0;
29
+ }
30
+ }
31
+ export const isUsable = (grammar) => librarySize(grammar) > 0;
32
+ export function findGrammar(name, loads) {
33
+ for (const read of [fromPlatform, fromAstGrep]) {
34
+ for (const load of loads) {
35
+ try {
36
+ const grammar = read(load, name);
37
+ if (isUsable(grammar))
38
+ return grammar;
39
+ }
40
+ catch {
41
+ continue;
42
+ }
43
+ }
44
+ }
45
+ return undefined;
46
+ }
47
+ export function loadGrammar(name) {
48
+ if (!loaded.has(name))
49
+ loaded.set(name, findGrammar(name, places()) ?? null);
50
+ return loaded.get(name) ?? undefined;
51
+ }
52
+ export const hasGrammar = (name) => loadGrammar(name) !== undefined;
53
+ export const availableGrammars = () => GRAMMARS.filter(hasGrammar);
54
+ export function grammarSignature() {
55
+ return availableGrammars()
56
+ .map((name) => `${name}:${librarySize(loadGrammar(name))}`)
57
+ .join(',');
58
+ }
@@ -1,3 +1,3 @@
1
1
  export { LANGUAGES, languageFor, languageNames } from './languages/index.js';
2
- export { SCAN_VERSION, currentHashes, hashOf, scanRepository } from './scan/index.js';
3
- export { formatGraph, nearest, queryGraph, refreshGraph, suggestFor } from './query/index.js';
2
+ export { SCAN_VERSION, currentHashes, hashOf, saveScan, scanRepository } from './scan/index.js';
3
+ export { NO_GRAPH, NO_GRAPH_FOR_PATH, addText, answerQuery, formatGraph, formatText, hasGraph, nearest, queryGraph, refreshGraph, suggestFor, } from './query/index.js';
@@ -1,3 +1,3 @@
1
1
  export { LANGUAGES, languageFor, languageNames } from './languages/index.js';
2
- export { SCAN_VERSION, currentHashes, hashOf, scanRepository } from './scan/index.js';
3
- export { formatGraph, nearest, queryGraph, refreshGraph, suggestFor } from './query/index.js';
2
+ export { SCAN_VERSION, currentHashes, hashOf, saveScan, scanRepository } from './scan/index.js';
3
+ export { NO_GRAPH, NO_GRAPH_FOR_PATH, addText, answerQuery, formatGraph, formatText, hasGraph, nearest, queryGraph, refreshGraph, suggestFor, } from './query/index.js';
@@ -2,8 +2,12 @@ const LABELS = {
2
2
  c: ['.c', '.h'],
3
3
  cpp: ['.cc', '.cpp', '.cxx', '.hpp', '.hh'],
4
4
  csharp: ['.cs'],
5
- java: ['.java'],
6
5
  kotlin: ['.kt', '.kts'],
6
+ go: ['.go'],
7
+ java: ['.java'],
8
+ python: ['.py', '.pyi'],
9
+ ruby: ['.rb', '.rake'],
10
+ rust: ['.rs'],
7
11
  swift: ['.swift'],
8
12
  'objective-c': ['.m', '.mm'],
9
13
  scala: ['.scala'],
@@ -9,6 +9,7 @@ const SHARED_REFERENCES = [
9
9
  { kind: 'call_expression', field: ['function', 'property'], relation: 'calls' },
10
10
  { kind: 'call_expression', field: ['function', 'object'], relation: 'references' },
11
11
  { kind: 'new_expression', field: ['constructor'], relation: 'calls' },
12
+ { kind: 'new_expression', field: ['constructor', 'property'], relation: 'calls' },
12
13
  { kind: 'import_statement', field: ['source'], relation: 'imports' },
13
14
  { kind: 'export_statement', field: ['source'], relation: 'imports' },
14
15
  ];
@@ -37,6 +38,12 @@ const TYPED_REFERENCES = [
37
38
  relation: 'references',
38
39
  excludeParents: TYPE_DECLARATION_SITES,
39
40
  },
41
+ {
42
+ kind: 'member_expression',
43
+ field: ['property'],
44
+ relation: 'references',
45
+ objectKinds: ['satisfies_expression', 'as_expression'],
46
+ },
40
47
  ];
41
48
  export const typescript = {
42
49
  id: 'TypeScript',
@@ -10,6 +10,5 @@ export const go = {
10
10
  references: [
11
11
  { kind: 'call_expression', field: ['function'], relation: 'calls' },
12
12
  { kind: 'call_expression', field: ['function', 'field'], relation: 'calls' },
13
- { kind: 'import_spec', field: ['path'], relation: 'imports' },
14
13
  ],
15
14
  };
@@ -1,7 +1,7 @@
1
1
  import type { LanguageSpec } from './rules.js';
2
2
  export type { LanguageSpec } from './rules.js';
3
3
  export declare const LANGUAGES: LanguageSpec[];
4
- export declare const DYNAMIC_LANGUAGES: string[];
5
4
  export { BASIC_FINGERPRINT, callsIn, declarationsIn } from './basic.js';
5
+ export declare const needsGrammar: (spec: LanguageSpec) => boolean;
6
6
  export declare function languageFor(path: string): LanguageSpec | null;
7
7
  export declare function languageNames(): string;
@@ -1,23 +1,48 @@
1
+ import { GRAMMARS, hasGrammar } from '../grammars.js';
1
2
  import { BASIC_LANGUAGES } from './basic.js';
2
3
  import { javascript, tsx, typescript } from './ecmascript.js';
3
4
  import { go } from './go.js';
5
+ import { java } from './java.js';
6
+ import { kotlin } from './kotlin.js';
4
7
  import { python } from './python.js';
5
8
  import { ruby } from './ruby.js';
6
9
  import { rust } from './rust.js';
7
- export const LANGUAGES = [typescript, tsx, javascript, python, go, rust, ruby];
8
- export const DYNAMIC_LANGUAGES = ['python', 'go', 'rust', 'ruby'];
10
+ export const LANGUAGES = [
11
+ typescript,
12
+ tsx,
13
+ javascript,
14
+ python,
15
+ go,
16
+ rust,
17
+ ruby,
18
+ java,
19
+ kotlin,
20
+ ];
9
21
  export { BASIC_FINGERPRINT, callsIn, declarationsIn } from './basic.js';
10
- const BY_EXTENSION = new Map();
11
- for (const spec of [...LANGUAGES, ...BASIC_LANGUAGES]) {
12
- for (const extension of spec.extensions)
13
- BY_EXTENSION.set(extension, spec);
14
- }
22
+ export const needsGrammar = (spec) => GRAMMARS.includes(spec.id);
23
+ const isReadable = (spec) => !needsGrammar(spec) || hasGrammar(spec.id);
24
+ const byExtension = (specs) => {
25
+ const found = new Map();
26
+ for (const spec of specs) {
27
+ for (const extension of spec.extensions)
28
+ found.set(extension, spec);
29
+ }
30
+ return found;
31
+ };
32
+ const REAL = byExtension(LANGUAGES);
33
+ const BASIC = byExtension(BASIC_LANGUAGES);
15
34
  export function languageFor(path) {
16
35
  const dot = path.lastIndexOf('.');
17
36
  if (dot < 0)
18
37
  return null;
19
- return BY_EXTENSION.get(path.slice(dot).toLowerCase()) ?? null;
38
+ const extension = path.slice(dot).toLowerCase();
39
+ const real = REAL.get(extension);
40
+ if (real && isReadable(real))
41
+ return real;
42
+ return BASIC.get(extension) ?? null;
20
43
  }
21
44
  export function languageNames() {
22
- return `${LANGUAGES.map((spec) => spec.label).join(', ')}, and ${BASIC_LANGUAGES.length} more by pattern`;
45
+ const parsed = LANGUAGES.filter(isReadable).map((spec) => spec.label);
46
+ const patterns = BASIC_LANGUAGES.filter((spec) => !parsed.includes(spec.label));
47
+ return `${parsed.join(', ')}, and ${patterns.length} more by pattern`;
23
48
  }
@@ -0,0 +1,2 @@
1
+ import type { LanguageSpec } from './rules.js';
2
+ export declare const java: LanguageSpec;
@@ -0,0 +1,38 @@
1
+ const TYPES = [
2
+ { kind: 'type_identifier' },
3
+ { kind: 'scoped_type_identifier' },
4
+ { kind: 'generic_type', select: ['type_identifier', 'scoped_type_identifier'] },
5
+ ];
6
+ export const java = {
7
+ id: 'java',
8
+ label: 'java',
9
+ extensions: ['.java'],
10
+ definitions: [
11
+ { kind: 'class_declaration', field: ['name'], symbol: 'class' },
12
+ { kind: 'record_declaration', field: ['name'], symbol: 'class' },
13
+ { kind: 'interface_declaration', field: ['name'], symbol: 'interface' },
14
+ { kind: 'annotation_type_declaration', field: ['name'], symbol: 'interface' },
15
+ { kind: 'enum_declaration', field: ['name'], symbol: 'enum' },
16
+ { kind: 'method_declaration', field: ['name'], symbol: 'method' },
17
+ ],
18
+ references: [
19
+ { kind: 'method_invocation', field: ['name'], relation: 'calls' },
20
+ { kind: 'method_invocation', field: ['name'], qualifier: 'object', relation: 'calls' },
21
+ { kind: 'object_creation_expression', field: [], relation: 'calls', listOf: TYPES },
22
+ { kind: 'superclass', field: [], relation: 'extends', listOf: TYPES },
23
+ {
24
+ kind: 'type_list',
25
+ field: [],
26
+ relation: 'implements',
27
+ parents: ['super_interfaces'],
28
+ listOf: TYPES,
29
+ },
30
+ {
31
+ kind: 'type_list',
32
+ field: [],
33
+ relation: 'extends',
34
+ parents: ['extends_interfaces'],
35
+ listOf: TYPES,
36
+ },
37
+ ],
38
+ };
@@ -0,0 +1,2 @@
1
+ import type { LanguageSpec } from './rules.js';
2
+ export declare const kotlin: LanguageSpec;
@@ -0,0 +1,19 @@
1
+ const BODIES = ['class_body', 'enum_class_body'];
2
+ export const kotlin = {
3
+ id: 'kotlin',
4
+ label: 'kotlin',
5
+ extensions: ['.kt', '.kts'],
6
+ definitions: [
7
+ { kind: 'class_declaration', field: [], nameKind: 'type_identifier', symbol: 'class' },
8
+ { kind: 'object_declaration', field: [], nameKind: 'type_identifier', symbol: 'class' },
9
+ { kind: 'type_alias', field: [], nameKind: 'type_identifier', symbol: 'type' },
10
+ {
11
+ kind: 'function_declaration',
12
+ field: [],
13
+ nameKind: 'simple_identifier',
14
+ symbol: 'function',
15
+ memberOf: BODIES,
16
+ },
17
+ ],
18
+ references: [],
19
+ };
@@ -9,7 +9,15 @@ export const python = {
9
9
  references: [
10
10
  { kind: 'call', field: ['function'], relation: 'calls' },
11
11
  { kind: 'call', field: ['function', 'attribute'], relation: 'calls' },
12
- { kind: 'import_from_statement', field: ['module_name'], relation: 'imports' },
13
- { kind: 'class_definition', field: ['superclasses'], relation: 'extends' },
12
+ {
13
+ kind: 'class_definition',
14
+ field: ['superclasses'],
15
+ relation: 'extends',
16
+ listOf: [
17
+ { kind: 'identifier' },
18
+ { kind: 'attribute' },
19
+ { kind: 'subscript', field: 'value' },
20
+ ],
21
+ },
14
22
  ],
15
23
  };