claude-db 0.4.1 → 0.5.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 (203) hide show
  1. package/CHANGELOG.md +399 -0
  2. package/README.md +62 -94
  3. package/dist/capture/command.d.ts +0 -14
  4. package/dist/capture/command.js +0 -23
  5. package/dist/capture/flush.d.ts +1 -50
  6. package/dist/capture/flush.js +4 -63
  7. package/dist/capture/git.js +0 -20
  8. package/dist/capture/identity.d.ts +0 -17
  9. package/dist/capture/identity.js +1 -21
  10. package/dist/capture/index.d.ts +1 -0
  11. package/dist/capture/index.js +1 -0
  12. package/dist/capture/manual.d.ts +0 -19
  13. package/dist/capture/manual.js +0 -0
  14. package/dist/capture/progress.d.ts +4 -0
  15. package/dist/capture/progress.js +33 -0
  16. package/dist/capture/transcript.d.ts +0 -45
  17. package/dist/capture/transcript.js +4 -70
  18. package/dist/capture/turn-extractor.d.ts +0 -15
  19. package/dist/capture/turn-extractor.js +1 -104
  20. package/dist/cli/args.d.ts +4 -0
  21. package/dist/cli/args.js +16 -0
  22. package/dist/cli/commands/doctor.d.ts +1 -0
  23. package/dist/cli/commands/doctor.js +76 -0
  24. package/dist/cli/commands/graph.d.ts +2 -0
  25. package/dist/cli/commands/graph.js +93 -0
  26. package/dist/cli/commands/insight.d.ts +3 -0
  27. package/dist/cli/commands/insight.js +129 -0
  28. package/dist/cli/commands/maintain.d.ts +3 -0
  29. package/dist/cli/commands/maintain.js +77 -0
  30. package/dist/cli/commands/memory.d.ts +3 -0
  31. package/dist/cli/commands/memory.js +77 -0
  32. package/dist/cli/commands/seed.d.ts +1 -0
  33. package/dist/cli/commands/seed.js +43 -0
  34. package/dist/cli/commands/setup.d.ts +4 -0
  35. package/dist/cli/commands/setup.js +156 -0
  36. package/dist/cli/commands/sync.d.ts +1 -0
  37. package/dist/cli/commands/sync.js +95 -0
  38. package/dist/cli/commands/transfer.d.ts +9 -0
  39. package/dist/cli/commands/transfer.js +129 -0
  40. package/dist/cli/commands/use.d.ts +1 -0
  41. package/dist/cli/commands/use.js +90 -0
  42. package/dist/cli/constants.d.ts +2 -0
  43. package/dist/cli/constants.js +4 -0
  44. package/dist/cli/files.d.ts +4 -0
  45. package/dist/cli/files.js +33 -0
  46. package/dist/cli/index.js +15 -1080
  47. package/dist/cli/install.d.ts +1 -59
  48. package/dist/cli/install.js +5 -194
  49. package/dist/cli/instructions.d.ts +5 -0
  50. package/dist/cli/instructions.js +55 -0
  51. package/dist/cli/paths.d.ts +5 -0
  52. package/dist/cli/paths.js +19 -0
  53. package/dist/cli/refresh.d.ts +1 -0
  54. package/dist/cli/refresh.js +25 -0
  55. package/dist/cli/usage.d.ts +1 -0
  56. package/dist/cli/usage.js +39 -0
  57. package/dist/config/load.d.ts +0 -5
  58. package/dist/config/load.js +1 -8
  59. package/dist/config/schema.js +2 -58
  60. package/dist/context.d.ts +0 -10
  61. package/dist/context.js +0 -16
  62. package/dist/embed/builtin.d.ts +0 -12
  63. package/dist/embed/builtin.js +0 -20
  64. package/dist/embed/embedder.d.ts +0 -14
  65. package/dist/embed/embedder.js +0 -1
  66. package/dist/embed/index.d.ts +0 -9
  67. package/dist/embed/index.js +0 -9
  68. package/dist/embed/local.d.ts +0 -8
  69. package/dist/embed/local.js +0 -12
  70. package/dist/graph/index.d.ts +7 -0
  71. package/dist/graph/index.js +4 -0
  72. package/dist/graph/languages/ecmascript.d.ts +4 -0
  73. package/dist/graph/languages/ecmascript.js +47 -0
  74. package/dist/graph/languages/go.d.ts +2 -0
  75. package/dist/graph/languages/go.js +15 -0
  76. package/dist/graph/languages/index.d.ts +6 -0
  77. package/dist/graph/languages/index.js +20 -0
  78. package/dist/graph/languages/python.d.ts +2 -0
  79. package/dist/graph/languages/python.js +15 -0
  80. package/dist/graph/languages/rules.d.ts +18 -0
  81. package/dist/graph/languages/rules.js +1 -0
  82. package/dist/graph/languages/rust.d.ts +2 -0
  83. package/dist/graph/languages/rust.js +16 -0
  84. package/dist/graph/parser.d.ts +31 -0
  85. package/dist/graph/parser.js +29 -0
  86. package/dist/graph/query/format.d.ts +2 -0
  87. package/dist/graph/query/format.js +41 -0
  88. package/dist/graph/query/index.d.ts +5 -0
  89. package/dist/graph/query/index.js +4 -0
  90. package/dist/graph/query/lookup.d.ts +21 -0
  91. package/dist/graph/query/lookup.js +35 -0
  92. package/dist/graph/query/path.d.ts +2 -0
  93. package/dist/graph/query/path.js +48 -0
  94. package/dist/graph/query/refresh.d.ts +2 -0
  95. package/dist/graph/query/refresh.js +21 -0
  96. package/dist/graph/scan/extract.d.ts +15 -0
  97. package/dist/graph/scan/extract.js +101 -0
  98. package/dist/graph/scan/files.d.ts +12 -0
  99. package/dist/graph/scan/files.js +51 -0
  100. package/dist/graph/scan/index.d.ts +18 -0
  101. package/dist/graph/scan/index.js +44 -0
  102. package/dist/graph/scan/resolve.d.ts +3 -0
  103. package/dist/graph/scan/resolve.js +48 -0
  104. package/dist/hooks/payload.d.ts +0 -8
  105. package/dist/hooks/payload.js +0 -6
  106. package/dist/hooks/relevance.d.ts +0 -17
  107. package/dist/hooks/relevance.js +55 -38
  108. package/dist/hooks/session-end.js +0 -11
  109. package/dist/hooks/session-start.js +33 -14
  110. package/dist/hooks/user-prompt.js +0 -18
  111. package/dist/mcp/render.d.ts +0 -20
  112. package/dist/mcp/render.js +0 -39
  113. package/dist/mcp/server.js +46 -25
  114. package/dist/search/rank.d.ts +0 -14
  115. package/dist/search/rank.js +0 -16
  116. package/dist/search/service.d.ts +1 -32
  117. package/dist/search/service.js +1 -36
  118. package/dist/store/adapter.d.ts +11 -44
  119. package/dist/store/adapter.js +1 -12
  120. package/dist/store/index.d.ts +0 -11
  121. package/dist/store/index.js +0 -11
  122. package/dist/store/mongo/docs.d.ts +61 -0
  123. package/dist/store/mongo/docs.js +106 -0
  124. package/dist/store/mongo/driver.d.ts +1 -15
  125. package/dist/store/mongo/driver.js +0 -15
  126. package/dist/store/mongo/filters.d.ts +6 -0
  127. package/dist/store/mongo/filters.js +18 -0
  128. package/dist/store/mongo/graph.d.ts +12 -0
  129. package/dist/store/mongo/graph.js +61 -0
  130. package/dist/store/mongo/helpers.d.ts +2 -0
  131. package/dist/store/mongo/helpers.js +8 -0
  132. package/dist/store/mongo/index.d.ts +16 -13
  133. package/dist/store/mongo/index.js +52 -295
  134. package/dist/store/mongo/observations.d.ts +10 -0
  135. package/dist/store/mongo/observations.js +97 -0
  136. package/dist/store/mongo/search.d.ts +6 -0
  137. package/dist/store/mongo/search.js +51 -0
  138. package/dist/store/mongo/sessions.d.ts +6 -0
  139. package/dist/store/mongo/sessions.js +24 -0
  140. package/dist/store/mongo/vectorSearch.d.ts +5 -0
  141. package/dist/store/mongo/vectorSearch.js +57 -0
  142. package/dist/store/postgres/driver.d.ts +19 -0
  143. package/dist/store/postgres/driver.js +13 -0
  144. package/dist/store/postgres/filters.d.ts +2 -0
  145. package/dist/store/postgres/filters.js +22 -0
  146. package/dist/store/postgres/graph.d.ts +11 -0
  147. package/dist/store/postgres/graph.js +115 -0
  148. package/dist/store/postgres/index.d.ts +20 -33
  149. package/dist/store/postgres/index.js +43 -428
  150. package/dist/store/postgres/insert.d.ts +3 -0
  151. package/dist/store/postgres/insert.js +59 -0
  152. package/dist/store/postgres/meta.d.ts +10 -0
  153. package/dist/store/postgres/meta.js +54 -0
  154. package/dist/store/postgres/observations.d.ts +10 -0
  155. package/dist/store/postgres/observations.js +139 -0
  156. package/dist/store/postgres/rows.d.ts +6 -0
  157. package/dist/store/postgres/rows.js +74 -0
  158. package/dist/store/postgres/schema.d.ts +3 -0
  159. package/dist/store/postgres/schema.js +84 -0
  160. package/dist/store/postgres/search.d.ts +3 -0
  161. package/dist/store/postgres/search.js +20 -0
  162. package/dist/store/postgres/sessions.d.ts +5 -0
  163. package/dist/store/postgres/sessions.js +26 -0
  164. package/dist/store/postgres/vectorSearch.d.ts +3 -0
  165. package/dist/store/postgres/vectorSearch.js +21 -0
  166. package/dist/store/sqlite/filters.d.ts +9 -0
  167. package/dist/store/sqlite/filters.js +77 -0
  168. package/dist/store/sqlite/graph.d.ts +11 -0
  169. package/dist/store/sqlite/graph.js +100 -0
  170. package/dist/store/sqlite/index.d.ts +12 -10
  171. package/dist/store/sqlite/index.js +41 -379
  172. package/dist/store/sqlite/observations.d.ts +10 -0
  173. package/dist/store/sqlite/observations.js +128 -0
  174. package/dist/store/sqlite/rows.d.ts +8 -0
  175. package/dist/store/sqlite/rows.js +84 -0
  176. package/dist/store/sqlite/schema.sql +42 -2
  177. package/dist/store/sqlite/search.d.ts +5 -0
  178. package/dist/store/sqlite/search.js +86 -0
  179. package/dist/store/sqlite/sessions.d.ts +5 -0
  180. package/dist/store/sqlite/sessions.js +21 -0
  181. package/dist/types.d.ts +47 -40
  182. package/dist/types.js +0 -4
  183. package/dist/update.d.ts +0 -20
  184. package/dist/update.js +4 -29
  185. package/dist/usages/find.d.ts +2 -8
  186. package/dist/usages/find.js +51 -54
  187. package/dist/usages/index.d.ts +1 -1
  188. package/dist/usages/index.js +1 -1
  189. package/dist/util/project.d.ts +0 -12
  190. package/dist/util/project.js +0 -24
  191. package/dist/util/scope.d.ts +0 -9
  192. package/dist/util/scope.js +0 -9
  193. package/dist/util/shortid.d.ts +0 -5
  194. package/dist/util/shortid.js +1 -19
  195. package/dist/util/snippet.d.ts +0 -26
  196. package/dist/util/snippet.js +0 -30
  197. package/dist/util/vector.d.ts +0 -12
  198. package/dist/util/vector.js +0 -12
  199. package/dist/util/warnings.d.ts +0 -11
  200. package/dist/util/warnings.js +0 -11
  201. package/docs/how-it-works.md +183 -0
  202. package/package.json +14 -3
  203. package/skills/cdb-scan/SKILL.md +31 -6
@@ -1,16 +1,4 @@
1
1
  import type { Embedder } from './embedder.js';
2
- /**
3
- * Zero-dependency embedder using the hashing trick over word and character
4
- * n-grams. Installs nothing, downloads nothing, runs in microseconds.
5
- *
6
- * Honest about what this is: it captures lexical and morphological similarity,
7
- * not meaning. "reconnect" matches "reconnecting" and survives typos, which
8
- * plain FTS5 token matching does not. It will NOT match "car" to "automobile"
9
- * the way a real sentence-transformer does.
10
- *
11
- * Its job is to be the floor, so that zero-config installs get fuzzy recall
12
- * instead of nothing when the ONNX model is unavailable.
13
- */
14
2
  export declare class BuiltinEmbedder implements Embedder {
15
3
  readonly id = "builtin-hashing";
16
4
  readonly dimensions = 256;
@@ -1,41 +1,23 @@
1
1
  import { normalize } from './embedder.js';
2
2
  const DIMENSIONS = 256;
3
- /**
4
- * Zero-dependency embedder using the hashing trick over word and character
5
- * n-grams. Installs nothing, downloads nothing, runs in microseconds.
6
- *
7
- * Honest about what this is: it captures lexical and morphological similarity,
8
- * not meaning. "reconnect" matches "reconnecting" and survives typos, which
9
- * plain FTS5 token matching does not. It will NOT match "car" to "automobile"
10
- * the way a real sentence-transformer does.
11
- *
12
- * Its job is to be the floor, so that zero-config installs get fuzzy recall
13
- * instead of nothing when the ONNX model is unavailable.
14
- */
15
3
  export class BuiltinEmbedder {
16
4
  id = 'builtin-hashing';
17
5
  dimensions = DIMENSIONS;
18
- // Measured: unrelated queries top out at 0.135, related start at 0.235.
19
6
  minRelevance = 0.18;
20
7
  async embed(texts) {
21
8
  return texts.map((text) => this.vectorize(text));
22
9
  }
23
10
  vectorize(text) {
24
11
  const vector = new Array(DIMENSIONS).fill(0);
25
- // Any script: ASCII-only shredded accented Latin and gave CJK a zero
26
- // vector. CJK arrives as one long token, where the trigrams do the work.
27
12
  const words = text
28
13
  .toLowerCase()
29
14
  .split(/[^\p{L}\p{N}]+/u)
30
15
  .filter((word) => word.length > 1);
31
16
  for (const word of words) {
32
- // Whole word carries the most signal.
33
17
  add(vector, `w:${word}`, 1);
34
- // Character trigrams give partial credit for shared stems and typos.
35
18
  for (const gram of trigrams(word))
36
19
  add(vector, `g:${gram}`, 0.35);
37
20
  }
38
- // Adjacent word pairs retain a little word order.
39
21
  for (let i = 1; i < words.length; i += 1) {
40
22
  add(vector, `b:${words[i - 1]}_${words[i]}`, 0.5);
41
23
  }
@@ -45,8 +27,6 @@ export class BuiltinEmbedder {
45
27
  function add(vector, token, weight) {
46
28
  const hash = fnv1a(token);
47
29
  const index = hash % DIMENSIONS;
48
- // Sign from a spare hash bit keeps unrelated collisions from always
49
- // accumulating constructively.
50
30
  const sign = (hash >>> 31) & 1 ? -1 : 1;
51
31
  vector[index] = (vector[index] ?? 0) + weight * sign;
52
32
  }
@@ -1,23 +1,9 @@
1
- /**
2
- * Turns text into a normalized vector. Implementations must return unit-length
3
- * vectors so downstream similarity is a plain dot product.
4
- */
5
1
  export interface Embedder {
6
2
  readonly id: string;
7
3
  readonly dimensions: number;
8
- /**
9
- * Cosine similarity below which a match is indistinguishable from noise.
10
- *
11
- * This belongs to the model, not to the search code: different embedding
12
- * spaces have wildly different baselines. Measured on this codebase, the
13
- * builtin hashing embedder scores unrelated text up to 0.135 and related
14
- * text from 0.235, so its floor sits in that gap. Sentence transformers
15
- * have a much higher baseline and need a correspondingly higher floor.
16
- */
17
4
  readonly minRelevance: number;
18
5
  embed(texts: string[]): Promise<number[][]>;
19
6
  }
20
- /** Used when embeddings are disabled. Search falls back to keyword-only. */
21
7
  export declare class NoopEmbedder implements Embedder {
22
8
  readonly id = "none";
23
9
  readonly dimensions = 0;
@@ -1,4 +1,3 @@
1
- /** Used when embeddings are disabled. Search falls back to keyword-only. */
2
1
  export class NoopEmbedder {
3
2
  id = 'none';
4
3
  dimensions = 0;
@@ -3,13 +3,4 @@ export type { Embedder } from './embedder.js';
3
3
  export { NoopEmbedder, normalize } from './embedder.js';
4
4
  export { BuiltinEmbedder } from './builtin.js';
5
5
  export type EmbeddingProvider = 'auto' | 'local' | 'builtin' | 'none';
6
- /**
7
- * `auto` is the default and the reason zero-config installs still get fuzzy
8
- * recall: it prefers the real sentence-transformer, but a missing or broken
9
- * ONNX runtime silently falls back to the builtin rather than leaving the
10
- * user with keyword-only search and no explanation.
11
- *
12
- * The probe runs one real embedding, because importing the module succeeds in
13
- * cases where the native backend still fails at inference time.
14
- */
15
6
  export declare function createEmbedder(provider: EmbeddingProvider): Promise<Embedder>;
@@ -2,15 +2,6 @@ import { NoopEmbedder } from './embedder.js';
2
2
  import { BuiltinEmbedder } from './builtin.js';
3
3
  export { NoopEmbedder, normalize } from './embedder.js';
4
4
  export { BuiltinEmbedder } from './builtin.js';
5
- /**
6
- * `auto` is the default and the reason zero-config installs still get fuzzy
7
- * recall: it prefers the real sentence-transformer, but a missing or broken
8
- * ONNX runtime silently falls back to the builtin rather than leaving the
9
- * user with keyword-only search and no explanation.
10
- *
11
- * The probe runs one real embedding, because importing the module succeeds in
12
- * cases where the native backend still fails at inference time.
13
- */
14
5
  export async function createEmbedder(provider) {
15
6
  switch (provider) {
16
7
  case 'none':
@@ -1,12 +1,4 @@
1
1
  import type { Embedder } from './embedder.js';
2
- /**
3
- * all-MiniLM-L6-v2 running locally through transformers.js. No API key, no
4
- * per-token cost, and observations never leave the machine. The model (~25MB)
5
- * downloads once on first use and is cached by the library thereafter.
6
- *
7
- * The pipeline is loaded lazily and memoized: importing this module must stay
8
- * cheap because hook scripts import it on every tool call.
9
- */
10
2
  export declare class LocalEmbedder implements Embedder {
11
3
  readonly id = "Xenova/all-MiniLM-L6-v2";
12
4
  readonly dimensions = 384;
@@ -1,17 +1,7 @@
1
1
  import { normalize } from './embedder.js';
2
- /**
3
- * all-MiniLM-L6-v2 running locally through transformers.js. No API key, no
4
- * per-token cost, and observations never leave the machine. The model (~25MB)
5
- * downloads once on first use and is cached by the library thereafter.
6
- *
7
- * The pipeline is loaded lazily and memoized: importing this module must stay
8
- * cheap because hook scripts import it on every tool call.
9
- */
10
2
  export class LocalEmbedder {
11
3
  id = 'Xenova/all-MiniLM-L6-v2';
12
4
  dimensions = 384;
13
- // MiniLM packs unrelated sentence pairs around 0.1-0.3 and related pairs
14
- // above 0.4, so its noise floor sits well above the builtin's.
15
5
  minRelevance = 0.35;
16
6
  pipelinePromise = null;
17
7
  async embed(texts) {
@@ -25,8 +15,6 @@ export class LocalEmbedder {
25
15
  this.pipelinePromise ??= (async () => {
26
16
  let transformers;
27
17
  try {
28
- // Widened specifier: the package is an optional peer and may be absent
29
- // at build time, so TypeScript must not try to resolve it.
30
18
  transformers = (await import('@xenova/transformers'));
31
19
  }
32
20
  catch {
@@ -0,0 +1,7 @@
1
+ export { LANGUAGES, languageFor, languageNames } from './languages/index.js';
2
+ export type { LanguageSpec } from './languages/index.js';
3
+ export { loadParser } from './parser.js';
4
+ export { currentHashes, listFiles, scanRepository, sourceFiles } from './scan/index.js';
5
+ export type { ScanOptions, ScanResult } from './scan/index.js';
6
+ export { formatGraph, queryGraph, refreshGraph, shortestPath } from './query/index.js';
7
+ export type { GraphAnswer, GraphMode, GraphQuery } from './query/index.js';
@@ -0,0 +1,4 @@
1
+ export { LANGUAGES, languageFor, languageNames } from './languages/index.js';
2
+ export { loadParser } from './parser.js';
3
+ export { currentHashes, listFiles, scanRepository, sourceFiles } from './scan/index.js';
4
+ export { formatGraph, queryGraph, refreshGraph, shortestPath } from './query/index.js';
@@ -0,0 +1,4 @@
1
+ import type { LanguageSpec } from './rules.js';
2
+ export declare const typescript: LanguageSpec;
3
+ export declare const tsx: LanguageSpec;
4
+ export declare const javascript: LanguageSpec;
@@ -0,0 +1,47 @@
1
+ const SHARED_DEFINITIONS = [
2
+ { kind: 'function_declaration', field: ['name'], symbol: 'function' },
3
+ { kind: 'generator_function_declaration', field: ['name'], symbol: 'function' },
4
+ { kind: 'method_definition', field: ['name'], symbol: 'method' },
5
+ { kind: 'variable_declarator', field: ['name'], symbol: 'const' },
6
+ ];
7
+ const SHARED_REFERENCES = [
8
+ { kind: 'call_expression', field: ['function'], relation: 'calls' },
9
+ { kind: 'call_expression', field: ['function', 'property'], relation: 'calls' },
10
+ { kind: 'new_expression', field: ['constructor'], relation: 'calls' },
11
+ { kind: 'import_statement', field: ['source'], relation: 'imports' },
12
+ { kind: 'export_statement', field: ['source'], relation: 'imports' },
13
+ ];
14
+ const TYPED_DEFINITIONS = [
15
+ { kind: 'class_declaration', field: ['name'], symbol: 'class' },
16
+ { kind: 'abstract_class_declaration', field: ['name'], symbol: 'class' },
17
+ { kind: 'interface_declaration', field: ['name'], symbol: 'interface' },
18
+ { kind: 'type_alias_declaration', field: ['name'], symbol: 'type' },
19
+ { kind: 'enum_declaration', field: ['name'], symbol: 'enum' },
20
+ ];
21
+ const TYPED_REFERENCES = [
22
+ { kind: 'extends_clause', field: ['value'], relation: 'extends' },
23
+ { kind: 'implements_clause', field: [], relation: 'implements' },
24
+ ];
25
+ export const typescript = {
26
+ id: 'TypeScript',
27
+ label: 'typescript',
28
+ extensions: ['.ts', '.mts', '.cts'],
29
+ definitions: [...SHARED_DEFINITIONS, ...TYPED_DEFINITIONS],
30
+ references: [...SHARED_REFERENCES, ...TYPED_REFERENCES],
31
+ };
32
+ export const tsx = {
33
+ ...typescript,
34
+ id: 'Tsx',
35
+ label: 'tsx',
36
+ extensions: ['.tsx'],
37
+ };
38
+ export const javascript = {
39
+ id: 'JavaScript',
40
+ label: 'javascript',
41
+ extensions: ['.js', '.mjs', '.cjs', '.jsx'],
42
+ definitions: [
43
+ ...SHARED_DEFINITIONS,
44
+ { kind: 'class_declaration', field: ['name'], symbol: 'class' },
45
+ ],
46
+ references: [...SHARED_REFERENCES, { kind: 'class_heritage', field: [], relation: 'extends' }],
47
+ };
@@ -0,0 +1,2 @@
1
+ import type { LanguageSpec } from './rules.js';
2
+ export declare const go: LanguageSpec;
@@ -0,0 +1,15 @@
1
+ export const go = {
2
+ id: 'go',
3
+ label: 'go',
4
+ extensions: ['.go'],
5
+ definitions: [
6
+ { kind: 'function_declaration', field: ['name'], symbol: 'function' },
7
+ { kind: 'method_declaration', field: ['name'], symbol: 'method' },
8
+ { kind: 'type_spec', field: ['name'], symbol: 'type' },
9
+ ],
10
+ references: [
11
+ { kind: 'call_expression', field: ['function'], relation: 'calls' },
12
+ { kind: 'call_expression', field: ['function', 'field'], relation: 'calls' },
13
+ { kind: 'import_spec', field: ['path'], relation: 'imports' },
14
+ ],
15
+ };
@@ -0,0 +1,6 @@
1
+ import type { LanguageSpec } from './rules.js';
2
+ export type { DefinitionRule, LanguageSpec, ReferenceRule } from './rules.js';
3
+ export declare const LANGUAGES: LanguageSpec[];
4
+ export declare const DYNAMIC_LANGUAGES: string[];
5
+ export declare function languageFor(path: string): LanguageSpec | null;
6
+ export declare function languageNames(): string;
@@ -0,0 +1,20 @@
1
+ import { javascript, tsx, typescript } from './ecmascript.js';
2
+ import { go } from './go.js';
3
+ import { python } from './python.js';
4
+ import { rust } from './rust.js';
5
+ export const LANGUAGES = [typescript, tsx, javascript, python, go, rust];
6
+ export const DYNAMIC_LANGUAGES = ['python', 'go', 'rust'];
7
+ const BY_EXTENSION = new Map();
8
+ for (const spec of LANGUAGES) {
9
+ for (const extension of spec.extensions)
10
+ BY_EXTENSION.set(extension, spec);
11
+ }
12
+ export function languageFor(path) {
13
+ const dot = path.lastIndexOf('.');
14
+ if (dot < 0)
15
+ return null;
16
+ return BY_EXTENSION.get(path.slice(dot).toLowerCase()) ?? null;
17
+ }
18
+ export function languageNames() {
19
+ return LANGUAGES.map((spec) => spec.label).join(', ');
20
+ }
@@ -0,0 +1,2 @@
1
+ import type { LanguageSpec } from './rules.js';
2
+ export declare const python: LanguageSpec;
@@ -0,0 +1,15 @@
1
+ export const python = {
2
+ id: 'python',
3
+ label: 'python',
4
+ extensions: ['.py', '.pyi'],
5
+ definitions: [
6
+ { kind: 'function_definition', field: ['name'], symbol: 'function' },
7
+ { kind: 'class_definition', field: ['name'], symbol: 'class' },
8
+ ],
9
+ references: [
10
+ { kind: 'call', field: ['function'], relation: 'calls' },
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' },
14
+ ],
15
+ };
@@ -0,0 +1,18 @@
1
+ import type { EdgeRelation, SymbolKind } from '../../types.js';
2
+ export interface DefinitionRule {
3
+ kind: string;
4
+ field: string[];
5
+ symbol: SymbolKind;
6
+ }
7
+ export interface ReferenceRule {
8
+ kind: string;
9
+ field: string[];
10
+ relation: EdgeRelation;
11
+ }
12
+ export interface LanguageSpec {
13
+ id: string;
14
+ label: string;
15
+ extensions: string[];
16
+ definitions: DefinitionRule[];
17
+ references: ReferenceRule[];
18
+ }
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,2 @@
1
+ import type { LanguageSpec } from './rules.js';
2
+ export declare const rust: LanguageSpec;
@@ -0,0 +1,16 @@
1
+ export const rust = {
2
+ id: 'rust',
3
+ label: 'rust',
4
+ extensions: ['.rs'],
5
+ definitions: [
6
+ { kind: 'function_item', field: ['name'], symbol: 'function' },
7
+ { kind: 'struct_item', field: ['name'], symbol: 'class' },
8
+ { kind: 'enum_item', field: ['name'], symbol: 'enum' },
9
+ { kind: 'trait_item', field: ['name'], symbol: 'interface' },
10
+ { kind: 'type_item', field: ['name'], symbol: 'type' },
11
+ ],
12
+ references: [
13
+ { kind: 'call_expression', field: ['function'], relation: 'calls' },
14
+ { kind: 'use_declaration', field: ['argument'], relation: 'imports' },
15
+ ],
16
+ };
@@ -0,0 +1,31 @@
1
+ export interface AstRange {
2
+ start: {
3
+ line: number;
4
+ column: number;
5
+ };
6
+ end: {
7
+ line: number;
8
+ column: number;
9
+ };
10
+ }
11
+ export interface AstNode {
12
+ text(): string;
13
+ kind(): string;
14
+ range(): AstRange;
15
+ field(name: string): AstNode | null;
16
+ findAll(matcher: {
17
+ rule: {
18
+ kind: string;
19
+ };
20
+ }): AstNode[];
21
+ }
22
+ interface AstGrepModule {
23
+ parse(language: unknown, source: string): {
24
+ root(): AstNode;
25
+ };
26
+ registerDynamicLanguage(languages: Record<string, unknown>): void;
27
+ Lang: Record<string, unknown>;
28
+ }
29
+ export declare function loadParser(): AstGrepModule;
30
+ export declare function languageHandle(parser: AstGrepModule, id: string): unknown;
31
+ export {};
@@ -0,0 +1,29 @@
1
+ import { createRequire } from 'node:module';
2
+ import { DYNAMIC_LANGUAGES } from './languages/index.js';
3
+ let cached = null;
4
+ export function loadParser() {
5
+ if (cached)
6
+ return cached;
7
+ const require = createRequire(import.meta.url);
8
+ let parser;
9
+ try {
10
+ parser = require('@ast-grep/napi');
11
+ }
12
+ catch (error) {
13
+ throw new Error('ast-grep failed to load, so the code graph cannot be built. It ships ' +
14
+ 'as a prebuilt binary per platform, so this usually means this one is ' +
15
+ `unsupported: ${process.platform}/${process.arch}. ` +
16
+ `(${error instanceof Error ? error.message.split('\n')[0] : String(error)})`);
17
+ }
18
+ const dynamic = {};
19
+ for (const name of DYNAMIC_LANGUAGES) {
20
+ const mod = require(`@ast-grep/lang-${name}`);
21
+ dynamic[name] = mod.default ?? mod;
22
+ }
23
+ parser.registerDynamicLanguage(dynamic);
24
+ cached = parser;
25
+ return parser;
26
+ }
27
+ export function languageHandle(parser, id) {
28
+ return parser.Lang[id] ?? id;
29
+ }
@@ -0,0 +1,2 @@
1
+ import type { GraphAnswer } from './lookup.js';
2
+ export declare function formatGraph(answer: GraphAnswer, root: string): string;
@@ -0,0 +1,41 @@
1
+ function tag(edge) {
2
+ const score = edge.confidence === 'INFERRED' ? ` ${edge.score.toFixed(2)}` : '';
3
+ return `[${edge.relation}] [${edge.confidence}${score}]`;
4
+ }
5
+ export function formatGraph(answer, root) {
6
+ if (answer.mode === 'path') {
7
+ if (answer.path.length === 0) {
8
+ return `No path found from "${answer.symbol}" to "${answer.target ?? ''}".`;
9
+ }
10
+ return [
11
+ `Shortest path (${answer.path.length - 1} hops):`,
12
+ ` ${answer.path.join(' --> ')}`,
13
+ ].join('\n');
14
+ }
15
+ if (answer.empty)
16
+ return `No symbol "${answer.symbol}" in the graph for ${root}.`;
17
+ const lines = [];
18
+ for (const definition of answer.definitions) {
19
+ lines.push(`${definition.name} [${definition.kind}]`);
20
+ lines.push(` Source: ${definition.file}:${definition.line}`);
21
+ if (definition.signature)
22
+ lines.push(` ${definition.signature}`);
23
+ }
24
+ if (answer.definitions.length === 0) {
25
+ lines.push(`${answer.symbol} [no definition in this repository]`);
26
+ }
27
+ lines.push(` Referenced by (${answer.inbound.length}):`);
28
+ for (const edge of answer.inbound) {
29
+ lines.push(` <-- ${edge.srcName} ${tag(edge)} ${edge.file}:${edge.line}`);
30
+ }
31
+ if (answer.mode === 'explain') {
32
+ lines.push(` Reaches (${answer.outbound.length}):`);
33
+ for (const edge of answer.outbound) {
34
+ lines.push(` --> ${edge.dstName} ${tag(edge)} ${edge.file}:${edge.line}`);
35
+ }
36
+ }
37
+ if (answer.refreshed.length > 0) {
38
+ lines.push(` (re-parsed ${answer.refreshed.length} changed file(s) before answering)`);
39
+ }
40
+ return lines.join('\n');
41
+ }
@@ -0,0 +1,5 @@
1
+ export { formatGraph } from './format.js';
2
+ export { queryGraph } from './lookup.js';
3
+ export type { GraphAnswer, GraphMode, GraphQuery } from './lookup.js';
4
+ export { shortestPath } from './path.js';
5
+ export { refreshGraph } from './refresh.js';
@@ -0,0 +1,4 @@
1
+ export { formatGraph } from './format.js';
2
+ export { queryGraph } from './lookup.js';
3
+ export { shortestPath } from './path.js';
4
+ export { refreshGraph } from './refresh.js';
@@ -0,0 +1,21 @@
1
+ import type { MemoryStore } from '../../store/adapter.js';
2
+ import type { CodeEdge, CodeSymbol } from '../../types.js';
3
+ export type GraphMode = 'usages' | 'explain' | 'path';
4
+ export interface GraphAnswer {
5
+ mode: GraphMode;
6
+ symbol: string;
7
+ target?: string;
8
+ definitions: CodeSymbol[];
9
+ inbound: CodeEdge[];
10
+ outbound: CodeEdge[];
11
+ path: string[];
12
+ refreshed: string[];
13
+ empty: boolean;
14
+ }
15
+ export interface GraphQuery {
16
+ mode: GraphMode;
17
+ symbol: string;
18
+ target?: string;
19
+ limit: number;
20
+ }
21
+ export declare function queryGraph(store: MemoryStore, project: string, query: GraphQuery): Promise<GraphAnswer>;
@@ -0,0 +1,35 @@
1
+ import { shortestPath } from './path.js';
2
+ export async function queryGraph(store, project, query) {
3
+ const answer = {
4
+ mode: query.mode,
5
+ symbol: query.symbol,
6
+ definitions: [],
7
+ inbound: [],
8
+ outbound: [],
9
+ path: [],
10
+ refreshed: [],
11
+ empty: false,
12
+ };
13
+ if (query.mode === 'path') {
14
+ if (query.target)
15
+ answer.target = query.target;
16
+ answer.path = await shortestPath(store, project, query.symbol, query.target ?? '');
17
+ answer.empty = answer.path.length === 0;
18
+ return answer;
19
+ }
20
+ answer.definitions = await store.findSymbols({
21
+ project,
22
+ name: query.symbol,
23
+ limit: query.limit,
24
+ });
25
+ const ids = answer.definitions.map((symbol) => symbol.id);
26
+ const edges = await store.findEdges({
27
+ project,
28
+ ...(ids.length > 0 ? { srcIds: ids, dstIds: ids } : {}),
29
+ limit: Math.max(query.limit * 10, 500),
30
+ });
31
+ answer.inbound = edges.filter((edge) => edge.dstName === query.symbol);
32
+ answer.outbound = edges.filter((edge) => ids.includes(edge.srcId) && edge.dstName !== query.symbol);
33
+ answer.empty = answer.definitions.length === 0 && answer.inbound.length === 0;
34
+ return answer;
35
+ }
@@ -0,0 +1,2 @@
1
+ import type { MemoryStore } from '../../store/adapter.js';
2
+ export declare function shortestPath(store: MemoryStore, project: string, from: string, to: string): Promise<string[]>;
@@ -0,0 +1,48 @@
1
+ const MAX_EDGES = 20000;
2
+ const MAX_SYMBOLS = 20000;
3
+ export async function shortestPath(store, project, from, to) {
4
+ if (!from || !to)
5
+ return [];
6
+ if (from === to)
7
+ return [from];
8
+ const graphology = (await import('graphology'));
9
+ const Graph = graphology.default;
10
+ const { bidirectional } = (await import('graphology-shortest-path/unweighted.js'));
11
+ const [symbols, edges] = await Promise.all([
12
+ store.findSymbols({ project, limit: MAX_SYMBOLS }),
13
+ store.findEdges({ project, limit: MAX_EDGES }),
14
+ ]);
15
+ const label = new Map();
16
+ for (const symbol of symbols)
17
+ label.set(symbol.id, symbol.name);
18
+ const graph = new Graph({ type: 'directed', multi: false, allowSelfLoops: false });
19
+ const nodeFor = (id, name) => (id ? id : `name:${name}`);
20
+ for (const edge of edges) {
21
+ const src = nodeFor(edge.srcId, edge.srcName);
22
+ const dst = nodeFor(edge.dstId, edge.dstName);
23
+ if (src === dst)
24
+ continue;
25
+ graph.mergeDirectedEdge(src, dst);
26
+ }
27
+ const endpoints = (name) => {
28
+ const ids = symbols.filter((symbol) => symbol.name === name).map((symbol) => symbol.id);
29
+ const nodes = ids.filter((id) => graph.hasNode(id));
30
+ const unresolved = `name:${name}`;
31
+ if (graph.hasNode(unresolved))
32
+ nodes.push(unresolved);
33
+ return nodes;
34
+ };
35
+ let best = null;
36
+ for (const start of endpoints(from)) {
37
+ for (const end of endpoints(to)) {
38
+ if (start === end)
39
+ continue;
40
+ const found = bidirectional(graph, start, end);
41
+ if (found && (!best || found.length < best.length))
42
+ best = found;
43
+ }
44
+ }
45
+ if (!best)
46
+ return [];
47
+ return best.map((node) => label.get(node) ?? node.replace(/^name:/, ''));
48
+ }
@@ -0,0 +1,2 @@
1
+ import type { MemoryStore } from '../../store/adapter.js';
2
+ export declare function refreshGraph(store: MemoryStore, root: string, project: string): Promise<string[]>;
@@ -0,0 +1,21 @@
1
+ import { currentHashes, scanRepository } from '../scan/index.js';
2
+ export async function refreshGraph(store, root, project) {
3
+ const stored = new Map((await store.scannedFiles(project)).map((file) => [file.path, file.hash]));
4
+ const current = currentHashes(root);
5
+ const changed = [...current.entries()]
6
+ .filter(([path, hash]) => stored.get(path) !== hash)
7
+ .map(([path]) => path);
8
+ const deleted = [...stored.keys()].filter((path) => !current.has(path));
9
+ if (deleted.length > 0)
10
+ await store.removeGraph(project, deleted);
11
+ if (changed.length === 0)
12
+ return deleted;
13
+ const scan = scanRepository({ root, project, known: new Map() });
14
+ await store.removeGraph(project, scan.changed);
15
+ await store.upsertGraph({
16
+ symbols: scan.symbols,
17
+ edges: scan.edges,
18
+ files: scan.files,
19
+ });
20
+ return [...deleted, ...changed];
21
+ }
@@ -0,0 +1,15 @@
1
+ import type { CodeSymbol, EdgeRelation } from '../../types.js';
2
+ import type { SourceFile } from './files.js';
3
+ export interface Reference {
4
+ file: string;
5
+ name: string;
6
+ relation: EdgeRelation;
7
+ line: number;
8
+ from: CodeSymbol | null;
9
+ }
10
+ export interface Extraction {
11
+ symbols: CodeSymbol[];
12
+ references: Reference[];
13
+ }
14
+ export declare function symbolId(project: string, file: string, name: string, kind: string): string;
15
+ export declare function extractFile(file: SourceFile, project: string): Extraction;