claude-db 0.11.0 → 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 (190) hide show
  1. package/CHANGELOG.md +63 -0
  2. package/README.md +44 -81
  3. package/dist/catchup/gather.d.ts +1 -0
  4. package/dist/catchup/gather.js +9 -2
  5. package/dist/catchup/git-state.d.ts +2 -0
  6. package/dist/catchup/git-state.js +3 -0
  7. package/dist/catchup/render.js +8 -0
  8. package/dist/cli/commands/graph.js +104 -80
  9. package/dist/cli/commands/languages.d.ts +1 -0
  10. package/dist/cli/commands/languages.js +22 -0
  11. package/dist/cli/files.d.ts +2 -0
  12. package/dist/cli/files.js +15 -1
  13. package/dist/cli/index.js +4 -0
  14. package/dist/cli/install.js +4 -3
  15. package/dist/cli/skills.js +6 -1
  16. package/dist/cli/usage.js +3 -1
  17. package/dist/facts/distill.d.ts +0 -2
  18. package/dist/facts/distill.js +4 -26
  19. package/dist/facts/handoff.js +11 -1
  20. package/dist/facts/known.d.ts +4 -0
  21. package/dist/facts/known.js +38 -0
  22. package/dist/facts/ops.d.ts +1 -1
  23. package/dist/facts/ops.js +4 -2
  24. package/dist/facts/start.js +5 -1
  25. package/dist/graph/ast.d.ts +4 -0
  26. package/dist/graph/ast.js +11 -0
  27. package/dist/graph/grammars.d.ts +14 -0
  28. package/dist/graph/grammars.js +58 -0
  29. package/dist/graph/index.d.ts +2 -2
  30. package/dist/graph/index.js +2 -2
  31. package/dist/graph/languages/basic.js +5 -1
  32. package/dist/graph/languages/ecmascript.js +7 -0
  33. package/dist/graph/languages/go.js +0 -1
  34. package/dist/graph/languages/index.d.ts +1 -1
  35. package/dist/graph/languages/index.js +34 -9
  36. package/dist/graph/languages/java.d.ts +2 -0
  37. package/dist/graph/languages/java.js +38 -0
  38. package/dist/graph/languages/kotlin.d.ts +2 -0
  39. package/dist/graph/languages/kotlin.js +19 -0
  40. package/dist/graph/languages/python.js +10 -2
  41. package/dist/graph/languages/rules.d.ts +11 -0
  42. package/dist/graph/languages/rust.js +2 -1
  43. package/dist/graph/modules/binding.d.ts +61 -0
  44. package/dist/graph/modules/binding.js +43 -0
  45. package/dist/graph/modules/ecmascript/bind.d.ts +4 -0
  46. package/dist/graph/modules/ecmascript/bind.js +17 -0
  47. package/dist/graph/modules/ecmascript/contexts.d.ts +6 -0
  48. package/dist/graph/modules/ecmascript/contexts.js +86 -0
  49. package/dist/graph/modules/ecmascript/exports.d.ts +9 -0
  50. package/dist/graph/modules/ecmascript/exports.js +91 -0
  51. package/dist/graph/modules/ecmascript/imports.d.ts +4 -0
  52. package/dist/graph/modules/ecmascript/imports.js +73 -0
  53. package/dist/graph/modules/ecmascript/package-resolver.d.ts +4 -0
  54. package/dist/graph/modules/ecmascript/package-resolver.js +73 -0
  55. package/dist/graph/modules/ecmascript/resolver.d.ts +2 -0
  56. package/dist/graph/modules/ecmascript/resolver.js +22 -0
  57. package/dist/graph/modules/ecmascript/specifiers.d.ts +3 -0
  58. package/dist/graph/modules/ecmascript/specifiers.js +15 -0
  59. package/dist/graph/modules/ecmascript/system.d.ts +2 -0
  60. package/dist/graph/modules/ecmascript/system.js +18 -0
  61. package/dist/graph/modules/ecmascript/workspace-resolver.d.ts +5 -0
  62. package/dist/graph/modules/ecmascript/workspace-resolver.js +38 -0
  63. package/dist/graph/modules/go/grammar.d.ts +2 -0
  64. package/dist/graph/modules/go/grammar.js +54 -0
  65. package/dist/graph/modules/go/imports.d.ts +4 -0
  66. package/dist/graph/modules/go/imports.js +32 -0
  67. package/dist/graph/modules/go/resolver.d.ts +2 -0
  68. package/dist/graph/modules/go/resolver.js +54 -0
  69. package/dist/graph/modules/go/system.d.ts +2 -0
  70. package/dist/graph/modules/go/system.js +16 -0
  71. package/dist/graph/modules/java/declarations.d.ts +9 -0
  72. package/dist/graph/modules/java/declarations.js +108 -0
  73. package/dist/graph/modules/java/grammar.d.ts +2 -0
  74. package/dist/graph/modules/java/grammar.js +135 -0
  75. package/dist/graph/modules/java/imports.d.ts +4 -0
  76. package/dist/graph/modules/java/imports.js +13 -0
  77. package/dist/graph/modules/java/receivers.d.ts +3 -0
  78. package/dist/graph/modules/java/receivers.js +139 -0
  79. package/dist/graph/modules/java/system.d.ts +1 -0
  80. package/dist/graph/modules/java/system.js +13 -0
  81. package/dist/graph/modules/jvm/linking.d.ts +20 -0
  82. package/dist/graph/modules/jvm/linking.js +64 -0
  83. package/dist/graph/modules/jvm/packages.d.ts +5 -0
  84. package/dist/graph/modules/jvm/packages.js +58 -0
  85. package/dist/graph/modules/jvm/receivers.d.ts +44 -0
  86. package/dist/graph/modules/jvm/receivers.js +77 -0
  87. package/dist/graph/modules/jvm/system.d.ts +18 -0
  88. package/dist/graph/modules/jvm/system.js +29 -0
  89. package/dist/graph/modules/jvm/types.d.ts +3 -0
  90. package/dist/graph/modules/jvm/types.js +11 -0
  91. package/dist/graph/modules/kotlin/declarations.d.ts +8 -0
  92. package/dist/graph/modules/kotlin/declarations.js +69 -0
  93. package/dist/graph/modules/kotlin/grammar.d.ts +2 -0
  94. package/dist/graph/modules/kotlin/grammar.js +78 -0
  95. package/dist/graph/modules/kotlin/imports.d.ts +4 -0
  96. package/dist/graph/modules/kotlin/imports.js +25 -0
  97. package/dist/graph/modules/kotlin/receivers.d.ts +3 -0
  98. package/dist/graph/modules/kotlin/receivers.js +105 -0
  99. package/dist/graph/modules/kotlin/references.d.ts +8 -0
  100. package/dist/graph/modules/kotlin/references.js +69 -0
  101. package/dist/graph/modules/kotlin/system.d.ts +1 -0
  102. package/dist/graph/modules/kotlin/system.js +15 -0
  103. package/dist/graph/modules/members.d.ts +17 -0
  104. package/dist/graph/modules/members.js +30 -0
  105. package/dist/graph/modules/module-index.d.ts +9 -0
  106. package/dist/graph/modules/module-index.js +62 -0
  107. package/dist/graph/modules/names.d.ts +2 -0
  108. package/dist/graph/modules/names.js +3 -0
  109. package/dist/graph/modules/python/grammar.d.ts +2 -0
  110. package/dist/graph/modules/python/grammar.js +100 -0
  111. package/dist/graph/modules/python/imports.d.ts +3 -0
  112. package/dist/graph/modules/python/imports.js +72 -0
  113. package/dist/graph/modules/python/resolver.d.ts +2 -0
  114. package/dist/graph/modules/python/resolver.js +78 -0
  115. package/dist/graph/modules/python/system.d.ts +2 -0
  116. package/dist/graph/modules/python/system.js +16 -0
  117. package/dist/graph/modules/rebind.d.ts +8 -0
  118. package/dist/graph/modules/rebind.js +51 -0
  119. package/dist/graph/modules/registry.d.ts +5 -0
  120. package/dist/graph/modules/registry.js +47 -0
  121. package/dist/graph/modules/rust/grammar.d.ts +2 -0
  122. package/dist/graph/modules/rust/grammar.js +94 -0
  123. package/dist/graph/modules/rust/imports.d.ts +3 -0
  124. package/dist/graph/modules/rust/imports.js +90 -0
  125. package/dist/graph/modules/rust/resolver.d.ts +3 -0
  126. package/dist/graph/modules/rust/resolver.js +153 -0
  127. package/dist/graph/modules/rust/system.d.ts +2 -0
  128. package/dist/graph/modules/rust/system.js +16 -0
  129. package/dist/graph/modules/shadowing.d.ts +17 -0
  130. package/dist/graph/modules/shadowing.js +65 -0
  131. package/dist/graph/modules/system.d.ts +39 -0
  132. package/dist/graph/modules/system.js +1 -0
  133. package/dist/graph/modules/uses.d.ts +14 -0
  134. package/dist/graph/modules/uses.js +62 -0
  135. package/dist/graph/parser.d.ts +9 -11
  136. package/dist/graph/parser.js +5 -4
  137. package/dist/graph/query/answer.d.ts +15 -0
  138. package/dist/graph/query/answer.js +22 -0
  139. package/dist/graph/query/format.d.ts +8 -1
  140. package/dist/graph/query/format.js +103 -30
  141. package/dist/graph/query/groups.d.ts +14 -0
  142. package/dist/graph/query/groups.js +51 -0
  143. package/dist/graph/query/index.d.ts +2 -1
  144. package/dist/graph/query/index.js +2 -1
  145. package/dist/graph/query/lookup.d.ts +2 -0
  146. package/dist/graph/query/lookup.js +19 -2
  147. package/dist/graph/query/refresh.js +17 -18
  148. package/dist/graph/query/stale.d.ts +2 -0
  149. package/dist/graph/query/stale.js +39 -0
  150. package/dist/graph/query/text.d.ts +12 -0
  151. package/dist/graph/query/text.js +26 -0
  152. package/dist/graph/scan/binder.d.ts +13 -0
  153. package/dist/graph/scan/binder.js +210 -0
  154. package/dist/graph/scan/cache.d.ts +11 -0
  155. package/dist/graph/scan/cache.js +140 -0
  156. package/dist/graph/scan/extract.d.ts +4 -17
  157. package/dist/graph/scan/extract.js +105 -83
  158. package/dist/graph/scan/files.d.ts +3 -9
  159. package/dist/graph/scan/files.js +3 -2
  160. package/dist/graph/scan/index.d.ts +8 -3
  161. package/dist/graph/scan/index.js +96 -36
  162. package/dist/graph/scan/job.d.ts +1 -0
  163. package/dist/graph/scan/job.js +1 -0
  164. package/dist/graph/scan/persist.d.ts +3 -0
  165. package/dist/graph/scan/persist.js +22 -0
  166. package/dist/graph/scan/receivers.d.ts +21 -0
  167. package/dist/graph/scan/receivers.js +87 -0
  168. package/dist/graph/scan/resolve.d.ts +8 -2
  169. package/dist/graph/scan/resolve.js +50 -56
  170. package/dist/graph/scan/spans.d.ts +13 -0
  171. package/dist/graph/scan/spans.js +42 -0
  172. package/dist/graph/symbols.d.ts +10 -0
  173. package/dist/graph/symbols.js +30 -0
  174. package/dist/graph/types.d.ts +56 -0
  175. package/dist/graph/types.js +1 -0
  176. package/dist/hooks/background.js +1 -16
  177. package/dist/hooks/detached.d.ts +3 -0
  178. package/dist/hooks/detached.js +16 -0
  179. package/dist/hooks/graph-refresh.d.ts +1 -0
  180. package/dist/hooks/graph-refresh.js +9 -0
  181. package/dist/hooks/prefer-usages.js +53 -12
  182. package/dist/hooks/session-start.js +8 -8
  183. package/dist/mcp/tools/usages.js +40 -31
  184. package/dist/types.d.ts +1 -1
  185. package/dist/usages/find.js +1 -0
  186. package/docs/how-it-works.md +10 -8
  187. package/docs/setup-guide.md +47 -299
  188. package/package.json +17 -6
  189. package/skills/catchup/SKILL.md +2 -0
  190. package/skills/handoff/SKILL.md +23 -7
@@ -0,0 +1,140 @@
1
+ import { mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
2
+ import { join } from 'node:path';
3
+ import { CONFIG_DIR } from '../../config/dir.js';
4
+ import { scopeToken } from '../../util/scope.js';
5
+ import { CACHE_KEY } from './files.js';
6
+ const MEMO_IDLE_MS = 10 * 60 * 1000;
7
+ export const cacheHome = () => process.env['CLAUDE_DB_GRAPH_CACHE'] ?? join(CONFIG_DIR, 'graph-cache');
8
+ const cachePath = (project) => join(cacheHome(), `${scopeToken(project)}.json`);
9
+ function receiverTable() {
10
+ const list = [];
11
+ const positions = new Map();
12
+ const indexOf = (receiver) => {
13
+ const known = positions.get(receiver);
14
+ if (known !== undefined)
15
+ return known;
16
+ positions.set(receiver, list.length);
17
+ list.push(receiver);
18
+ return list.length - 1;
19
+ };
20
+ return { list, indexOf };
21
+ }
22
+ function storeReference(reference, index, receivers) {
23
+ const { file: _file, from, to, receiver, returns, ...rest } = reference;
24
+ const fromAt = from ? index.get(from.id) : undefined;
25
+ const toAt = to === undefined ? undefined : index.get(to);
26
+ const stored = { ...rest, from: fromAt ?? from };
27
+ if (to !== undefined)
28
+ stored.to = toAt ?? to;
29
+ if (receiver)
30
+ stored.receiver = receivers.indexOf(receiver);
31
+ if (returns)
32
+ stored.returns = receivers.indexOf(returns);
33
+ return stored;
34
+ }
35
+ function loadReference(path, stored, symbols, receivers) {
36
+ const from = typeof stored.from === 'number' ? (symbols[stored.from] ?? null) : stored.from;
37
+ const to = typeof stored.to === 'number' ? symbols[stored.to]?.id : stored.to;
38
+ const receiver = stored.receiver === undefined ? undefined : receivers[stored.receiver];
39
+ const returns = stored.returns === undefined ? undefined : receivers[stored.returns];
40
+ const loaded = Object.assign(stored, { file: path, from });
41
+ delete loaded.to;
42
+ delete loaded.receiver;
43
+ delete loaded.returns;
44
+ const reference = loaded;
45
+ if (to !== undefined)
46
+ reference.to = to;
47
+ if (receiver)
48
+ reference.receiver = receiver;
49
+ if (returns)
50
+ reference.returns = returns;
51
+ return reference;
52
+ }
53
+ function toStored(entry) {
54
+ const index = new Map(entry.symbols.map((symbol, at) => [symbol.id, at]));
55
+ const receivers = receiverTable();
56
+ const references = entry.references.map((ref) => storeReference(ref, index, receivers));
57
+ return {
58
+ ...entry,
59
+ references,
60
+ ...(receivers.list.length > 0 ? { receivers: receivers.list } : {}),
61
+ };
62
+ }
63
+ function fromStored(path, entry) {
64
+ const { receivers = [], ...rest } = entry;
65
+ return {
66
+ ...rest,
67
+ references: entry.references.map((ref) => loadReference(path, ref, entry.symbols, receivers)),
68
+ };
69
+ }
70
+ const isStoredCache = (value) => typeof value === 'object' && value !== null && 'files' in value && 'key' in value;
71
+ function readStored(project) {
72
+ try {
73
+ const parsed = JSON.parse(readFileSync(cachePath(project), 'utf8'));
74
+ if (!isStoredCache(parsed) || parsed.key !== CACHE_KEY || parsed.project !== project) {
75
+ return null;
76
+ }
77
+ return parsed;
78
+ }
79
+ catch {
80
+ return null;
81
+ }
82
+ }
83
+ let memo = null;
84
+ let forget;
85
+ function fileStamp(path) {
86
+ try {
87
+ const stat = statSync(path);
88
+ return `${stat.mtimeMs}:${stat.size}`;
89
+ }
90
+ catch {
91
+ return '';
92
+ }
93
+ }
94
+ function remember(project, files) {
95
+ memo = { project, stamp: fileStamp(cachePath(project)), files };
96
+ clearTimeout(forget);
97
+ forget = setTimeout(() => {
98
+ memo = null;
99
+ }, MEMO_IDLE_MS);
100
+ forget.unref();
101
+ }
102
+ function readCache(project) {
103
+ const stored = readStored(project);
104
+ if (!stored)
105
+ return new Map();
106
+ try {
107
+ return new Map(Object.entries(stored.files).map(([path, entry]) => [path, fromStored(path, entry)]));
108
+ }
109
+ catch {
110
+ return new Map();
111
+ }
112
+ }
113
+ export function loadCache(project) {
114
+ const stamp = fileStamp(cachePath(project));
115
+ if (memo?.project === project && memo.stamp === stamp && stamp !== '') {
116
+ remember(project, memo.files);
117
+ return memo.files;
118
+ }
119
+ const files = readCache(project);
120
+ remember(project, files);
121
+ return files;
122
+ }
123
+ export function saveCache(project, files) {
124
+ const target = cachePath(project);
125
+ const temporary = `${target}.${process.pid}.tmp`;
126
+ const stored = {
127
+ key: CACHE_KEY,
128
+ project,
129
+ files: Object.fromEntries([...files].map(([path, entry]) => [path, toStored(entry)])),
130
+ };
131
+ try {
132
+ mkdirSync(cacheHome(), { recursive: true });
133
+ writeFileSync(temporary, JSON.stringify(stored));
134
+ renameSync(temporary, target);
135
+ remember(project, files);
136
+ }
137
+ catch {
138
+ rmSync(temporary, { force: true });
139
+ }
140
+ }
@@ -1,18 +1,5 @@
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
- weak?: boolean;
10
- to?: string;
11
- origin?: string;
12
- }
13
- export interface Extraction {
14
- symbols: CodeSymbol[];
15
- references: Reference[];
16
- }
17
- export declare function symbolId(project: string, file: string, name: string, kind: string, index?: number): string;
1
+ import { symbolId } from '../symbols.js';
2
+ import type { Extraction, Reference, SourceFile } from '../types.js';
3
+ export { symbolId };
4
+ export type { Extraction, Reference };
18
5
  export declare function extractFile(file: SourceFile, project: string): Extraction;
@@ -1,38 +1,22 @@
1
- import { observationId } from '../../capture/identity.js';
2
- import { redact } from '../../capture/redact.js';
1
+ import { originOf, sameNode } from '../ast.js';
3
2
  import { callsIn, declarationsIn } from '../languages/index.js';
3
+ import { moduleSystemFor } from '../modules/registry.js';
4
4
  import { languageHandle, loadParser } from '../parser.js';
5
- const CALLABLE = new Set(['function', 'method', 'class']);
5
+ import { symbolFactory, symbolId } from '../symbols.js';
6
+ import { container, enclosing, nearestAbove } from './spans.js';
7
+ export { symbolId };
6
8
  const IDENTIFIER = /^[\w$]+[?!]?$/;
7
- export function symbolId(project, file, name, kind, index = 0) {
8
- const seed = `${project}\0${file}\0${name}\0${kind}`;
9
- return observationId('graph', 0, index === 0 ? seed : `${seed}\0${index}`);
10
- }
11
- function counter() {
12
- const seen = new Map();
13
- return (name, kind) => {
14
- const key = `${name}\0${kind}`;
15
- const index = seen.get(key) ?? 0;
16
- seen.set(key, index + 1);
17
- return index;
18
- };
19
- }
20
9
  function extractByPattern(file, project) {
21
- const lines = file.source.split('\n');
10
+ const declare = symbolFactory({
11
+ project,
12
+ path: file.path,
13
+ lang: file.spec.label,
14
+ lines: file.source.split('\n'),
15
+ });
22
16
  const symbols = [];
23
17
  const spans = [];
24
- const occurrence = counter();
25
18
  for (const declaration of declarationsIn(file.source)) {
26
- const symbol = {
27
- id: symbolId(project, file.path, declaration.name, declaration.kind, occurrence(declaration.name, declaration.kind)),
28
- project,
29
- name: declaration.name,
30
- kind: declaration.kind,
31
- file: file.path,
32
- line: declaration.line,
33
- lang: file.spec.label,
34
- signature: redact((lines[declaration.line - 1] ?? '').trim()).slice(0, 200),
35
- };
19
+ const symbol = declare(declaration.name, declaration.kind, declaration.line);
36
20
  symbols.push(symbol);
37
21
  spans.push({ start: declaration.line, end: declaration.line, symbol });
38
22
  }
@@ -46,16 +30,6 @@ function extractByPattern(file, project) {
46
30
  }));
47
31
  return { symbols, references };
48
32
  }
49
- function nearestAbove(line, spans) {
50
- let best = null;
51
- for (const span of spans) {
52
- if (span.start > line)
53
- continue;
54
- if (!best || span.start > best.start)
55
- best = span;
56
- }
57
- return best?.symbol ?? null;
58
- }
59
33
  function resolveField(node, path) {
60
34
  let current = node;
61
35
  for (const name of path) {
@@ -68,24 +42,39 @@ function resolveField(node, path) {
68
42
  function unquote(text) {
69
43
  return text.replace(/^['"`]|['"`]$/g, '').replace(/^[<(:\s]+|[)\s]+$/g, '');
70
44
  }
71
- function enclosing(line, spans) {
72
- let best = null;
73
- let fallback = null;
74
- for (const span of spans) {
75
- if (line < span.start || line > span.end)
76
- continue;
77
- const width = span.end - span.start;
78
- if (CALLABLE.has(span.symbol.kind)) {
79
- if (!best || width < best.end - best.start)
80
- best = span;
81
- continue;
82
- }
83
- if (span.start === line)
84
- continue;
85
- if (!fallback || width < fallback.end - fallback.start)
86
- fallback = span;
87
- }
88
- return (best ?? fallback)?.symbol ?? null;
45
+ const DOTTED = /^(?!this\b|super\b)[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*$/;
46
+ function qualifiedName(node, qualifier, name) {
47
+ const text = node.field(qualifier)?.text().trim();
48
+ return text && DOTTED.test(text) ? `${text}.${name}` : null;
49
+ }
50
+ function isDeclarationSite(node, sites) {
51
+ if (!sites)
52
+ return false;
53
+ const parent = node.parent();
54
+ if (!parent || !sites.includes(parent.kind()))
55
+ return false;
56
+ const declared = parent.field('name');
57
+ return !declared || sameNode(declared, node);
58
+ }
59
+ function selected(child, item) {
60
+ if (item.field)
61
+ return child.field(item.field);
62
+ if (!item.select)
63
+ return child;
64
+ const kinds = item.select;
65
+ return child.children().find((inner) => kinds.includes(inner.kind())) ?? null;
66
+ }
67
+ function listedTargets(node, items) {
68
+ return node.children().flatMap((child) => {
69
+ const item = items.find((candidate) => candidate.kind === child.kind());
70
+ const target = item && selected(child, item);
71
+ return target ? [target] : [];
72
+ });
73
+ }
74
+ function targetsOf(rule, matched) {
75
+ if (rule.listOf)
76
+ return listedTargets(matched, rule.listOf);
77
+ return rule.field.length === 0 ? namedTargets(matched) : [matched];
89
78
  }
90
79
  function namedTargets(node) {
91
80
  if (!/\s/.test(node.text().trim()))
@@ -99,43 +88,59 @@ function namedTargets(node) {
99
88
  }
100
89
  return inner.length > 0 ? inner : [node];
101
90
  }
91
+ function nodesByKind(root, kinds) {
92
+ const grouped = new Map();
93
+ const wanted = [...new Set(kinds)].map((kind) => ({ kind }));
94
+ for (const node of root.findAll({ rule: { any: wanted } })) {
95
+ const kind = node.kind();
96
+ const bucket = grouped.get(kind);
97
+ if (bucket)
98
+ bucket.push(node);
99
+ else
100
+ grouped.set(kind, [node]);
101
+ }
102
+ return grouped;
103
+ }
102
104
  export function extractFile(file, project) {
103
105
  if (file.spec.basic)
104
106
  return extractByPattern(file, project);
105
107
  const parser = loadParser();
106
108
  const root = parser.parse(languageHandle(parser, file.spec.id), file.source).root();
107
- const lines = file.source.split('\n');
109
+ const declare = symbolFactory({
110
+ project,
111
+ path: file.path,
112
+ lang: file.spec.label,
113
+ lines: file.source.split('\n'),
114
+ });
108
115
  const symbols = [];
109
116
  const spans = [];
110
- const occurrence = counter();
117
+ const system = moduleSystemFor(file.spec.label);
118
+ const ruleKinds = [...file.spec.definitions, ...file.spec.references].map((rule) => rule.kind);
119
+ const nodes = nodesByKind(root, [...ruleKinds, ...(system?.nodeKinds ?? [])]);
111
120
  for (const rule of file.spec.definitions) {
112
- for (const node of root.findAll({ rule: { kind: rule.kind } })) {
113
- const named = resolveField(node, rule.field);
121
+ for (const node of nodes.get(rule.kind) ?? []) {
122
+ const named = rule.nameKind
123
+ ? (node.children().find((child) => child.kind() === rule.nameKind) ?? null)
124
+ : resolveField(node, rule.field);
114
125
  const name = named?.text();
115
126
  if (!named || !name || !IDENTIFIER.test(name))
116
127
  continue;
117
- const line = named.range().start.line + 1;
118
- const symbol = {
119
- id: symbolId(project, file.path, name, rule.symbol, occurrence(name, rule.symbol)),
120
- project,
121
- name,
122
- kind: rule.symbol,
123
- file: file.path,
124
- line,
125
- lang: file.spec.label,
126
- signature: redact((lines[line - 1] ?? '').trim()).slice(0, 200),
127
- };
128
+ const member = rule.memberOf?.includes(node.parent()?.kind() ?? '');
129
+ const symbol = declare(name, member ? 'method' : rule.symbol, named.range().start.line + 1);
128
130
  symbols.push(symbol);
131
+ const { start, end } = node.range();
129
132
  spans.push({
130
- start: node.range().start.line + 1,
131
- end: node.range().end.line + 1,
133
+ start: start.line + 1,
134
+ end: end.line + 1,
135
+ from: start.index,
136
+ to: end.index,
132
137
  symbol,
133
138
  });
134
139
  }
135
140
  }
136
141
  const references = [];
137
142
  for (const span of spans) {
138
- const owner = enclosing(span.start, spans.filter((other) => other.symbol.id !== span.symbol.id));
143
+ const owner = container(span, spans);
139
144
  if (!owner)
140
145
  continue;
141
146
  references.push({
@@ -148,36 +153,53 @@ export function extractFile(file, project) {
148
153
  });
149
154
  }
150
155
  for (const rule of file.spec.references) {
151
- for (const node of root.findAll({ rule: { kind: rule.kind } })) {
156
+ for (const node of nodes.get(rule.kind) ?? []) {
152
157
  const matched = rule.field.length === 0 ? node : resolveField(node, rule.field);
153
158
  if (!matched)
154
159
  continue;
155
- const targets = rule.field.length === 0 ? namedTargets(matched) : [matched];
156
- for (const target of targets) {
160
+ if (rule.parents && !rule.parents.includes(node.parent()?.kind() ?? ''))
161
+ continue;
162
+ if (rule.objectKinds && !rule.objectKinds.includes(node.field('object')?.kind() ?? '')) {
163
+ continue;
164
+ }
165
+ for (const target of targetsOf(rule, matched)) {
157
166
  const raw = target.text();
158
167
  if (!raw)
159
168
  continue;
160
- const name = unquote(raw.trim());
161
- if (!name || /\s/.test(name))
169
+ const written = unquote(raw.trim());
170
+ if (!written || /\s/.test(written))
171
+ continue;
172
+ const name = rule.qualifier ? qualifiedName(node, rule.qualifier, written) : written;
173
+ if (!name)
162
174
  continue;
163
175
  if (rule.relation === 'references' && name.includes('.'))
164
176
  continue;
165
177
  if (rule.namePattern && !rule.namePattern.test(name))
166
178
  continue;
167
- if (rule.excludeParents?.includes(node.parent()?.kind() ?? ''))
179
+ if (isDeclarationSite(node, rule.excludeParents))
168
180
  continue;
169
181
  const line = target.range().start.line + 1;
170
- const span = node.range();
171
182
  references.push({
172
183
  file: file.path,
173
184
  name,
174
185
  relation: rule.relation,
175
186
  line,
176
187
  from: enclosing(line, spans),
177
- origin: `${span.start.line}:${span.start.column}-${span.end.line}:${span.end.column}`,
188
+ origin: originOf(node),
178
189
  });
179
190
  }
180
191
  }
181
192
  }
182
- return { symbols, references };
193
+ if (!system)
194
+ return { symbols, references };
195
+ const facts = system.read({
196
+ root,
197
+ nodes,
198
+ file,
199
+ declare,
200
+ symbols,
201
+ references,
202
+ owner: (line) => enclosing(line, spans),
203
+ });
204
+ return { symbols: [...symbols, ...facts.added], references: facts.references };
183
205
  }
@@ -1,12 +1,6 @@
1
- import type { LanguageSpec } from '../languages/index.js';
2
- export interface SourceFile {
3
- unreadable?: boolean;
4
- path: string;
5
- spec: LanguageSpec;
6
- source: string;
7
- hash: string;
8
- }
9
- export declare const SCAN_VERSION = 5;
1
+ import type { SourceFile } from '../types.js';
2
+ export declare const SCAN_VERSION = 7;
3
+ export declare const CACHE_KEY: string;
10
4
  export declare function hashOf(bytes: Buffer): string;
11
5
  export declare function listFiles(root: string): string[];
12
6
  export declare function sourceFiles(root: string): string[];
@@ -2,16 +2,17 @@ import { execFileSync } from 'node:child_process';
2
2
  import { createHash } from 'node:crypto';
3
3
  import { readFileSync } from 'node:fs';
4
4
  import { join } from 'node:path';
5
+ import { grammarSignature } from '../grammars.js';
5
6
  import { BASIC_FINGERPRINT, LANGUAGES, languageFor } from '../languages/index.js';
6
7
  const MAX_BUFFER = 64 * 1024 * 1024;
7
8
  const MAX_FILE_BYTES = 1024 * 1024;
8
- export const SCAN_VERSION = 5;
9
+ export const SCAN_VERSION = 7;
9
10
  const RULES_FINGERPRINT = createHash('sha256')
10
11
  .update(JSON.stringify(LANGUAGES, (_key, value) => value instanceof RegExp ? String(value) : value))
11
12
  .update(BASIC_FINGERPRINT)
12
13
  .digest('hex')
13
14
  .slice(0, 12);
14
- const CACHE_KEY = `v${SCAN_VERSION}:${RULES_FINGERPRINT}\n`;
15
+ export const CACHE_KEY = `v${SCAN_VERSION}:${RULES_FINGERPRINT}:${grammarSignature()}\n`;
15
16
  export function hashOf(bytes) {
16
17
  return createHash('sha256').update(CACHE_KEY).update(bytes).digest('hex').slice(0, 32);
17
18
  }
@@ -1,18 +1,23 @@
1
1
  import type { CodeEdge, CodeSymbol, ScannedFile } from '../../types.js';
2
2
  export { SCAN_VERSION, currentHashes, hashOf } from './files.js';
3
+ export { saveScan } from './persist.js';
3
4
  export interface ScanOptions {
4
5
  root: string;
5
6
  project: string;
6
- known: Map<string, string>;
7
+ stored?: ReadonlyMap<string, string>;
7
8
  force?: boolean;
8
- existing?: CodeSymbol[];
9
+ hashes?: ReadonlyMap<string, string>;
10
+ saveCacheLater?: boolean;
9
11
  }
10
12
  export interface ScanResult {
11
13
  symbols: CodeSymbol[];
12
14
  edges: CodeEdge[];
13
15
  files: ScannedFile[];
14
16
  changed: string[];
17
+ rewrite: string[];
18
+ removed: string[];
15
19
  skipped: number;
16
20
  unsupported: number;
21
+ patternRead: Record<string, number>;
17
22
  }
18
- export declare function scanRepository(options: ScanOptions): ScanResult;
23
+ export declare function scanRepository(options: ScanOptions): Promise<ScanResult>;
@@ -1,54 +1,114 @@
1
+ import { createHash } from 'node:crypto';
2
+ import { GRAMMARS } from '../grammars.js';
3
+ import { languageFor } from '../languages/index.js';
4
+ import { createModuleContext } from '../modules/registry.js';
1
5
  import { loadParser } from '../parser.js';
6
+ import { loadCache, saveCache } from './cache.js';
2
7
  import { extractFile } from './extract.js';
3
8
  import { listFiles, readSource } from './files.js';
4
- import { resolveEdges } from './resolve.js';
9
+ import { createLinker } from './resolve.js';
5
10
  export { SCAN_VERSION, currentHashes, hashOf } from './files.js';
6
- export function scanRepository(options) {
7
- const { root, project, known, force } = options;
8
- loadParser();
9
- const result = {
10
- symbols: [],
11
- edges: [],
12
- files: [],
11
+ export { saveScan } from './persist.js';
12
+ const nextTurn = () => new Promise((resolve) => setImmediate(resolve));
13
+ function extractEntry(file, project) {
14
+ if (file.unreadable)
15
+ return { hash: file.hash, symbols: [], references: [], edgesHash: '' };
16
+ try {
17
+ const { symbols, references } = extractFile(file, project);
18
+ return { hash: file.hash, symbols, references, edgesHash: '' };
19
+ }
20
+ catch {
21
+ return null;
22
+ }
23
+ }
24
+ function countPatternRead(counts, spec) {
25
+ if (spec.basic && GRAMMARS.includes(spec.label)) {
26
+ counts[spec.label] = (counts[spec.label] ?? 0) + 1;
27
+ }
28
+ }
29
+ async function collect(root, project, cache, hashes) {
30
+ const paths = listFiles(root);
31
+ const state = {
32
+ paths,
33
+ entries: new Map(),
13
34
  changed: [],
14
35
  skipped: 0,
15
36
  unsupported: 0,
37
+ patternRead: {},
16
38
  };
17
- const references = [];
18
- const scannedAt = Date.now();
19
- for (const path of listFiles(root)) {
20
- const file = readSource(root, path);
21
- if (!file) {
22
- result.unsupported += 1;
39
+ for (const path of paths) {
40
+ const spec = languageFor(path);
41
+ if (!spec) {
42
+ state.unsupported += 1;
23
43
  continue;
24
44
  }
25
- if (!force && known.get(path) === file.hash) {
26
- result.skipped += 1;
45
+ countPatternRead(state.patternRead, spec);
46
+ const cached = cache.get(path);
47
+ if (cached && hashes?.get(path) === cached.hash) {
48
+ state.entries.set(path, cached);
49
+ state.skipped += 1;
27
50
  continue;
28
51
  }
29
- if (file.unreadable) {
30
- result.unsupported += 1;
31
- result.changed.push(path);
32
- result.files.push({ project, path, hash: file.hash, scannedAt });
52
+ const file = readSource(root, path);
53
+ if (!file) {
54
+ state.unsupported += 1;
33
55
  continue;
34
56
  }
35
- let extracted;
36
- try {
37
- extracted = extractFile(file, project);
38
- }
39
- catch {
40
- result.unsupported += 1;
57
+ if (cached?.hash === file.hash) {
58
+ state.entries.set(path, cached);
59
+ state.skipped += 1;
41
60
  continue;
42
61
  }
43
- result.symbols.push(...extracted.symbols);
44
- references.push(...extracted.references);
45
- result.changed.push(path);
46
- result.files.push({ project, path, hash: file.hash, scannedAt });
62
+ const entry = extractEntry(file, project);
63
+ if (file.unreadable || !entry)
64
+ state.unsupported += 1;
65
+ if (!entry)
66
+ continue;
67
+ state.entries.set(path, entry);
68
+ state.changed.push(path);
69
+ await nextTurn();
47
70
  }
48
- const rescanned = new Set(result.changed);
49
- const resolvable = options.existing === undefined
50
- ? result.symbols
51
- : [...result.symbols, ...options.existing.filter((s) => !rescanned.has(s.file))];
52
- result.edges = resolveEdges(project, resolvable, references);
53
- return result;
71
+ return state;
72
+ }
73
+ function linkerFor(root, project, state) {
74
+ const entries = [...state.entries.values()];
75
+ return createLinker(project, entries.flatMap((entry) => entry.symbols), entries.flatMap((entry) => entry.references), createModuleContext(root, new Set(state.paths)));
76
+ }
77
+ const fingerprint = (linker, references) => createHash('sha1')
78
+ .update(references.map((reference) => linker.outcome(reference)).join('\n'))
79
+ .digest('base64url');
80
+ export async function scanRepository(options) {
81
+ const { root, project, force = false } = options;
82
+ const stored = options.stored ?? new Map();
83
+ loadParser();
84
+ const scannedAt = Date.now();
85
+ const cache = force ? new Map() : loadCache(project);
86
+ const state = await collect(root, project, cache, options.hashes);
87
+ const linker = linkerFor(root, project, state);
88
+ const changed = new Set(state.changed);
89
+ const rewrite = [];
90
+ const files = [];
91
+ for (const [path, entry] of state.entries) {
92
+ const edgesHash = fingerprint(linker, entry.references);
93
+ const dirty = force || changed.has(path) || stored.get(path) !== entry.hash;
94
+ if (dirty || edgesHash !== entry.edgesHash)
95
+ rewrite.push(path);
96
+ state.entries.set(path, { ...entry, edgesHash });
97
+ files.push({ project, path, hash: entry.hash, scannedAt });
98
+ }
99
+ if (options.saveCacheLater)
100
+ setImmediate(() => saveCache(project, state.entries));
101
+ else
102
+ saveCache(project, state.entries);
103
+ return {
104
+ symbols: [...state.entries.values()].flatMap((entry) => entry.symbols),
105
+ edges: rewrite.flatMap((path) => linker.edgesFor(state.entries.get(path)?.references ?? [])),
106
+ files,
107
+ changed: state.changed,
108
+ rewrite,
109
+ removed: [...stored.keys()].filter((path) => !state.entries.has(path)),
110
+ skipped: state.skipped,
111
+ unsupported: state.unsupported,
112
+ patternRead: state.patternRead,
113
+ };
54
114
  }
@@ -0,0 +1 @@
1
+ export declare const GRAPH_JOB = "graph-refresh";
@@ -0,0 +1 @@
1
+ export const GRAPH_JOB = 'graph-refresh';
@@ -0,0 +1,3 @@
1
+ import type { MemoryStore } from '../../store/adapter.js';
2
+ import type { ScanResult } from './index.js';
3
+ export declare function saveScan(store: MemoryStore, project: string, scan: ScanResult, force?: boolean): Promise<void>;