claude-db 0.5.4 → 0.7.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 (45) hide show
  1. package/CHANGELOG.md +145 -0
  2. package/dist/capture/turn-extractor.js +9 -3
  3. package/dist/cli/commands/adoption.d.ts +1 -0
  4. package/dist/cli/commands/adoption.js +88 -0
  5. package/dist/cli/commands/graph.js +14 -2
  6. package/dist/cli/index.js +4 -0
  7. package/dist/cli/install.js +15 -10
  8. package/dist/cli/instructions.js +5 -4
  9. package/dist/cli/usage.js +1 -0
  10. package/dist/graph/index.d.ts +2 -2
  11. package/dist/graph/index.js +2 -2
  12. package/dist/graph/query/format.js +7 -3
  13. package/dist/graph/query/index.d.ts +1 -0
  14. package/dist/graph/query/index.js +1 -0
  15. package/dist/graph/query/lookup.d.ts +1 -0
  16. package/dist/graph/query/lookup.js +6 -0
  17. package/dist/graph/query/suggest.d.ts +5 -0
  18. package/dist/graph/query/suggest.js +65 -0
  19. package/dist/graph/scan/files.d.ts +1 -0
  20. package/dist/graph/scan/files.js +8 -2
  21. package/dist/graph/scan/index.d.ts +1 -1
  22. package/dist/graph/scan/index.js +1 -1
  23. package/dist/hooks/grep-symbols.d.ts +5 -0
  24. package/dist/hooks/grep-symbols.js +31 -0
  25. package/dist/hooks/prefer-usages.d.ts +2 -0
  26. package/dist/hooks/prefer-usages.js +78 -0
  27. package/dist/hooks/session-start.js +19 -0
  28. package/dist/mcp/server.js +6 -170
  29. package/dist/mcp/tools/kinds.d.ts +1 -0
  30. package/dist/mcp/tools/kinds.js +1 -0
  31. package/dist/mcp/tools/memory.d.ts +3 -0
  32. package/dist/mcp/tools/memory.js +46 -0
  33. package/dist/mcp/tools/observations.d.ts +3 -0
  34. package/dist/mcp/tools/observations.js +57 -0
  35. package/dist/mcp/tools/search.d.ts +3 -0
  36. package/dist/mcp/tools/search.js +55 -0
  37. package/dist/mcp/tools/usages.d.ts +3 -0
  38. package/dist/mcp/tools/usages.js +80 -0
  39. package/dist/search/service.js +3 -0
  40. package/dist/search/stopwords.d.ts +2 -0
  41. package/dist/search/stopwords.js +137 -0
  42. package/dist/store/sqlite/filters.js +3 -5
  43. package/dist/usages/find.d.ts +1 -1
  44. package/dist/usages/find.js +5 -3
  45. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -1,5 +1,150 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.7.0
4
+
5
+ ### Changed
6
+
7
+ - **The usages hook now directs instead of offering.** Replaying 1,871 Bash
8
+ commands from real transcripts showed the additive wording ("the grep below
9
+ still runs") produced 0% unprompted tool adoption — the graph answer arrived
10
+ and was ignored. The hook now names the grepped symbol and instructs the
11
+ agent to use `find_usages`, with the graph answer still inline so the
12
+ instruction is self-justifying.
13
+
14
+ - **Plain lowercase words count as symbols when the graph holds a real
15
+ declaration.** The symbol filter only matched camelCase, PascalCase and
16
+ snake_case, so single-word names — `search`, `forget`, `timeline`, exactly
17
+ the vocabulary a project's public surface tends to use — could never fire
18
+ the hook. Words of four or more characters now qualify, gated on resolving
19
+ to a declared function, method or class rather than a local `const`, so
20
+ greps for `value` or `result` stay silent. Measured on the replay corpus:
21
+ +9 fires, no regressions.
22
+
23
+ - **`git grep` and `rg` count as searching the tree.** Both are recursive by
24
+ default, but the hook required a `-r` flag or a path argument, so every
25
+ `git grep <symbol>` and bare `rg <symbol>` passed unseen. A piped `rg` is
26
+ still treated as output filtering. Space-separated flag values
27
+ (`rg -t ts`, `grep -A 3`) no longer confuse pattern extraction.
28
+
29
+ - **A preference's title is now the rule itself.** Titles were built from
30
+ the assistant's reasoning, so a turn that stated a standing rule while work
31
+ was in flight could be filed as a preference titled "140 checks pass" —
32
+ junk in the new session-start index. Preference titles now come from the
33
+ user's own words.
34
+
35
+ - **The installed instructions speak in the first person.** "This project has
36
+ persistent memory" reads as someone else's feature; "you have persistent
37
+ memory of this project" reads as the model's own recall. The installed
38
+ block now uses the second framing, matching how the model treats memory it
39
+ actually uses. Already-installed projects pick the new text up automatically
40
+ at the next session start.
41
+
42
+ ### Added
43
+
44
+ - **Session start injects a standing-rules index.** The model uses whatever is
45
+ already in its context and skips what costs a call, so memory it cannot see
46
+ is memory it does not use. The startup injection now lists the most recent
47
+ preference observations — one line each, with the id to expand via
48
+ `get_observations` — so recalling a standing rule becomes expanding a line
49
+ already on screen instead of discovering whether one exists. Rules recorded
50
+ explicitly with `remember` list ahead of auto-classified ones.
51
+
52
+ - **Symbol greps are blocked by default, with the graph answer in the deny
53
+ reason.** A blind A/B on a real task showed the block outperforms the
54
+ nudge: the agent pivots to `find_usages` immediately, loses no turn — the
55
+ answer it needed rides in the deny reason — and non-symbol greps pass
56
+ through untouched. `CLAUDE_DB_USAGES_HOOK=directive` keeps the softer
57
+ inject-only mode; `off` disables the hook entirely.
58
+
59
+ - **`claude-db adoption` measures whether any of this works.** It reads the
60
+ project's transcripts and reports Bash commands vs greps vs hook fires vs
61
+ memory tool calls — the grep-to-memory ratio that motivated this release,
62
+ reproducible on any project with one command.
63
+
64
+ ### Fixed
65
+
66
+ - **`claude-db install` stacked duplicate hooks whenever the install path
67
+ changed.** Registration deduped by exact command string, so reinstalling
68
+ from a new location — a repo build vs the global install, or any node
69
+ upgrade under nvm moving the global path — appended a second registration
70
+ with the same matcher: two node processes and two database opens on every
71
+ Bash call. Install now replaces its own hook entries by file name wherever
72
+ they point, and uninstall removes them from any path, not just the one it
73
+ is run from.
74
+
75
+ - **The graph could not answer for the MCP tool names themselves.**
76
+ `find_usages("forget")` returned nothing: tool names existed only as string
77
+ literals with anonymous handlers, so there was no declaration to index.
78
+ Handlers are now named functions matching their tools (`search`, `forget`,
79
+ `timeline`, `remember`, `get_observations`, `find_usages`), so the graph
80
+ answers questions about the project's own public surface.
81
+
82
+ ## 0.6.0
83
+
84
+ ### Fixed
85
+
86
+ - **`scan` served a stale graph after every upgrade.** The scan cache keyed on
87
+ file content hash alone, so when an extractor changed, users' files did not —
88
+ and `scan` reported `N unchanged, 0 parsed` while continuing to serve edges
89
+ built by the previous extractor. Fixes shipped in 0.5.3 never reached anyone
90
+ who upgraded; only `scan --force` surfaced them, and nothing told you to run
91
+ it. The cache key now mixes in a `SCAN_VERSION` and a fingerprint of the
92
+ language rules, so an upgrade reparses once, automatically, and a rule edit
93
+ invalidates the cache without anyone remembering to bump a constant.
94
+ Verified against a cache written by the old extractor: 240 files skipped
95
+ before, 204 reparsed after, and an unchanged file is still skipped on the
96
+ next scan.
97
+
98
+ - **One common word in a query returned the whole corpus.** SQLite keyword
99
+ search ORs every token, so `"quantum entanglement recipes for sourdough"`
100
+ matched 30 rows on the strength of `for` alone, and an all-stopword query
101
+ matched everything. Postgres and Mongo were never affected — `plainto_tsquery`
102
+ and Mongo's `$text` strip stopwords already — so SQLite, the default backend,
103
+ was the only one exposed. Stopwords are now removed before the query is built,
104
+ and a query with no content words returns nothing instead of the corpus. The
105
+ filtering lives in `src/search`, not the adapter, so every backend behaves the
106
+ same. Note this could not be fixed after ranking: RRF discards score magnitude
107
+ by design, so the fused score is not a relevance measure and cannot be
108
+ thresholded.
109
+
110
+ - **`get_observations` answered with an empty string.** An id that resolved to
111
+ nothing produced no output at all rather than saying so, which reads as a
112
+ broken tool. It now names the ids that did not resolve, and a partial batch
113
+ appends which ones were missing instead of silently dropping them.
114
+
115
+ - **`timeline` could not tell a bad id from a quiet session.** Both produced
116
+ `No matching observations.`; the two now read differently.
117
+
118
+ ### Added
119
+
120
+ - **A `PreToolUse` hook that answers symbol searches from the code graph.**
121
+ When a shell `grep` or the Grep tool searches for something shaped like a code
122
+ symbol, the hook runs the graph lookup and returns the definition and every
123
+ reference alongside the search — the grep still runs, so nothing is blocked and
124
+ no second call is needed. It stays silent for plain text, piped output
125
+ filtering, `-v`, regexes, lowercase words, and any project with no graph
126
+ scanned. `CLAUDE_DB_USAGES_HOOK=off` disables it. Registered by `install` and
127
+ removed by `uninstall` like the other hooks.
128
+
129
+ - **`find_usages` suggests near names on a miss.** A miss used to end at
130
+ `No usages of that symbol found`, which is where people give up and go back to
131
+ grep. `embedObservation` now suggests `embedObservations`, `find_symbols`
132
+ suggests `findSymbols`, and a name with no near match still suggests nothing
133
+ rather than something incidental.
134
+
135
+ ### Changed
136
+
137
+ - **Tool descriptions now say when to reach for the tool.** `search`, `timeline`
138
+ and `get_observations` opened with `Layer 1/2/3`, an internal concept that
139
+ never stated a trigger, and `find_usages` opened by describing itself as a live
140
+ `git grep`. They now lead with the condition that should make you call them,
141
+ and `search` explains what to try when nothing matches.
142
+
143
+ - **`src/mcp/server.ts` split 303 lines into one module per tool group.**
144
+ `server.ts` is 37 lines of bootstrap; the tools live in `src/mcp/tools/`. The
145
+ tool logic is importable and unit-testable for the first time — previously
146
+ anything in `server.ts` self-started a stdio transport on import.
147
+
3
148
  ## 0.5.4
4
149
 
5
150
  ### Fixed
@@ -32,14 +32,15 @@ function buildObservation(turn, sessionId, project, config) {
32
32
  .filter((line) => line !== '')
33
33
  .join('\n'), config.capture.maxBodyChars));
34
34
  const author = currentAuthor();
35
+ const kind = classifyTurn(turn);
35
36
  return {
36
37
  id: observationId(sessionId, turn.timestamp, turn.prompt),
37
38
  sessionId,
38
39
  project,
39
40
  ...(author ? { author } : {}),
40
41
  status: files.length > 0 ? 'open' : 'done',
41
- kind: classifyTurn(turn),
42
- title: redact(buildTitle(turn, files)),
42
+ kind,
43
+ title: redact(buildTitle(turn, files, kind)),
43
44
  body,
44
45
  files,
45
46
  tags: topLevelDirs(files, project),
@@ -66,7 +67,12 @@ function reports(sentence) {
66
67
  const text = sentence.replace(/\[redacted[^\]]*\]/g, '');
67
68
  return EVIDENCE.some((test) => test.test(text)) ? 1 : 0;
68
69
  }
69
- function buildTitle(turn, files) {
70
+ function buildTitle(turn, files, kind) {
71
+ if (kind === 'preference') {
72
+ const rule = firstSentence(redact(turn.prompt));
73
+ if (rule)
74
+ return headline(rule);
75
+ }
70
76
  const prose = stripMarkdown(redact(turn.reasoning));
71
77
  const scored = scoreSentences(prose);
72
78
  const best = scored.find(([, score]) => score > 0) ?? scored.find(([, score]) => score === 0);
@@ -0,0 +1 @@
1
+ export declare function cmdAdoption(): Promise<void>;
@@ -0,0 +1,88 @@
1
+ import { readFileSync } from 'node:fs';
2
+ import { createContext } from '../../context.js';
3
+ import { queryGraph } from '../../graph/index.js';
4
+ import { transcriptsFor } from '../../capture/transcript.js';
5
+ import { resolveProject } from '../../util/project.js';
6
+ import { DECLARED, isSymbol, symbolsGreppedIn } from '../../hooks/grep-symbols.js';
7
+ export async function cmdAdoption() {
8
+ const project = resolveProject(undefined);
9
+ const files = transcriptsFor(project);
10
+ if (files.length === 0) {
11
+ console.log(`No transcripts found for ${project}.`);
12
+ return;
13
+ }
14
+ const seen = new Set();
15
+ const bash = [];
16
+ const memory = new Map();
17
+ for (const file of files) {
18
+ for (const line of readFileSync(file, 'utf8').split('\n')) {
19
+ if (!line.includes('"tool_use"'))
20
+ continue;
21
+ let entry;
22
+ try {
23
+ entry = JSON.parse(line);
24
+ }
25
+ catch {
26
+ continue;
27
+ }
28
+ const content = entry?.message?.content;
29
+ if (!Array.isArray(content))
30
+ continue;
31
+ for (const item of content) {
32
+ if (item?.type !== 'tool_use' || typeof item.id !== 'string' || seen.has(item.id))
33
+ continue;
34
+ seen.add(item.id);
35
+ const name = typeof item.name === 'string' ? item.name : '';
36
+ if (name === 'Bash' && typeof item.input?.command === 'string') {
37
+ bash.push(item.input.command);
38
+ }
39
+ if (name.startsWith('mcp__memory__')) {
40
+ const tool = name.slice('mcp__memory__'.length);
41
+ memory.set(tool, (memory.get(tool) ?? 0) + 1);
42
+ }
43
+ }
44
+ }
45
+ }
46
+ const greps = bash.filter((command) => /\b(?:grep|rg)\b/.test(command));
47
+ const candidates = greps.map((command) => symbolsGreppedIn(command)).filter((s) => s.length > 0);
48
+ const ctx = await createContext();
49
+ let fires = 0;
50
+ const cache = new Map();
51
+ try {
52
+ for (const symbols of candidates) {
53
+ let hit = false;
54
+ for (const symbol of symbols.slice(0, 2)) {
55
+ let fired = cache.get(symbol);
56
+ if (fired === undefined) {
57
+ const answer = await queryGraph(ctx.store, project, { mode: 'usages', symbol, limit: 20 });
58
+ fired =
59
+ !answer.empty &&
60
+ (isSymbol(symbol) || answer.definitions.some((d) => DECLARED.has(d.kind)));
61
+ cache.set(symbol, fired);
62
+ }
63
+ if (fired)
64
+ hit = true;
65
+ }
66
+ if (hit)
67
+ fires++;
68
+ }
69
+ }
70
+ finally {
71
+ await ctx.close();
72
+ }
73
+ const memoryTotal = [...memory.values()].reduce((a, b) => a + b, 0);
74
+ const pct = (n, of) => (of === 0 ? '0.0%' : `${((n / of) * 100).toFixed(1)}%`);
75
+ console.log(`Adoption for ${project} (${files.length} transcripts)\n`);
76
+ console.log(` Bash commands ${bash.length}`);
77
+ console.log(` containing grep/rg ${greps.length} (${pct(greps.length, bash.length)})`);
78
+ console.log(` usages-hook candidates ${candidates.length}`);
79
+ console.log(` would fire today ${fires} (${pct(fires, bash.length)} of all commands)`);
80
+ console.log(`\n memory tool calls ${memoryTotal}`);
81
+ for (const [tool, count] of [...memory].sort((a, b) => b[1] - a[1])) {
82
+ console.log(` ${tool.padEnd(18)} ${count}`);
83
+ }
84
+ if (greps.length > 0) {
85
+ const ratio = memoryTotal === 0 ? 'no memory calls yet' : `${(greps.length / memoryTotal).toFixed(1)} greps per memory call`;
86
+ console.log(`\n ${ratio}`);
87
+ }
88
+ }
@@ -1,6 +1,6 @@
1
1
  import { createContext } from '../../context.js';
2
2
  import { findUsages, formatUsages, repoRootFor } from '../../usages/index.js';
3
- import { formatGraph, languageNames, queryGraph, refreshGraph, scanRepository, } from '../../graph/index.js';
3
+ import { formatGraph, languageNames, queryGraph, refreshGraph, scanRepository, suggestFor, } from '../../graph/index.js';
4
4
  import { resolveProject } from '../../util/project.js';
5
5
  import { valueOf, withoutFlags } from '../args.js';
6
6
  export async function cmdScan(argv) {
@@ -61,7 +61,8 @@ export async function cmdUsages(argv) {
61
61
  process.exit(1);
62
62
  }
63
63
  if (mode === 'text') {
64
- console.log(formatUsages(findUsages({ symbol: words, regex, context, limit, ...(path ? { path } : {}) })));
64
+ const result = findUsages({ symbol: words, regex, context, limit, ...(path ? { path } : {}) });
65
+ console.log(formatUsages(result, await suggestionsOnMiss(result.matches.length, words)));
65
66
  return;
66
67
  }
67
68
  if (mode !== 'usages' && mode !== 'explain' && mode !== 'path') {
@@ -91,3 +92,14 @@ export async function cmdUsages(argv) {
91
92
  await ctx.close();
92
93
  }
93
94
  }
95
+ async function suggestionsOnMiss(matches, symbol) {
96
+ if (matches > 0)
97
+ return [];
98
+ const ctx = await createContext();
99
+ try {
100
+ return await suggestFor(ctx.store, resolveProject(undefined), symbol);
101
+ }
102
+ finally {
103
+ await ctx.close();
104
+ }
105
+ }
package/dist/cli/index.js CHANGED
@@ -11,6 +11,7 @@ import { cmdMerge, cmdProjects, cmdStats } from './commands/insight.js';
11
11
  import { cmdFlush, cmdReset, cmdUpdate } from './commands/maintain.js';
12
12
  import { cmdScan, cmdUsages } from './commands/graph.js';
13
13
  import { cmdSeed } from './commands/seed.js';
14
+ import { cmdAdoption } from './commands/adoption.js';
14
15
  import { silenceSqliteWarning } from '../util/warnings.js';
15
16
  silenceSqliteWarning();
16
17
  const [command, ...args] = process.argv.slice(2);
@@ -62,6 +63,9 @@ async function run() {
62
63
  case 'stats':
63
64
  await cmdStats();
64
65
  break;
66
+ case 'adoption':
67
+ await cmdAdoption();
68
+ break;
65
69
  case 'update':
66
70
  await cmdUpdate(args);
67
71
  break;
@@ -18,6 +18,7 @@ const HOOKS = [
18
18
  ['SessionStart', 'session-start.js'],
19
19
  ['UserPromptSubmit', 'user-prompt.js'],
20
20
  ['SessionEnd', 'session-end.js'],
21
+ ['PreToolUse', 'prefer-usages.js', 'Bash|Grep'],
21
22
  ];
22
23
  export function assertStableLocation(distDir) {
23
24
  const ephemeral = ['_npx', '_cacache'];
@@ -35,16 +36,17 @@ export function install(distDir, scope, project) {
35
36
  const settings = readJson(path);
36
37
  const hooks = (settings['hooks'] ?? {});
37
38
  for (const [event, file, matcher] of HOOKS) {
38
- const command = hookCommand(distDir, file);
39
- const existing = hooks[event] ?? [];
40
- const present = existing.some((entry) => entry.hooks.some((hook) => hook.command === command));
41
- if (present)
42
- continue;
43
- existing.push({
39
+ const kept = (hooks[event] ?? [])
40
+ .map((entry) => ({
41
+ ...entry,
42
+ hooks: entry.hooks.filter((hook) => !isOurHook(hook.command)),
43
+ }))
44
+ .filter((entry) => entry.hooks.length > 0);
45
+ kept.push({
44
46
  ...(matcher ? { matcher } : {}),
45
- hooks: [{ type: 'command', command }],
47
+ hooks: [{ type: 'command', command: hookCommand(distDir, file) }],
46
48
  });
47
- hooks[event] = existing;
49
+ hooks[event] = kept;
48
50
  }
49
51
  settings['hooks'] = hooks;
50
52
  delete settings['mcpServers'];
@@ -80,13 +82,12 @@ export function uninstall(distDir, scope, project) {
80
82
  const settings = readJson(path);
81
83
  if (Object.keys(settings).length === 0)
82
84
  return null;
83
- const ours = new Set(HOOKS.map(([, file]) => hookCommand(distDir, file)));
84
85
  const hooks = (settings['hooks'] ?? {});
85
86
  for (const [event, entries] of Object.entries(hooks)) {
86
87
  const kept = entries
87
88
  .map((entry) => ({
88
89
  ...entry,
89
- hooks: entry.hooks.filter((hook) => !ours.has(hook.command)),
90
+ hooks: entry.hooks.filter((hook) => !isOurHook(hook.command)),
90
91
  }))
91
92
  .filter((entry) => entry.hooks.length > 0);
92
93
  if (kept.length > 0)
@@ -120,3 +121,7 @@ export function uninstall(distDir, scope, project) {
120
121
  function hookCommand(distDir, file) {
121
122
  return `node ${resolve(distDir, 'hooks', file)}`;
122
123
  }
124
+ function isOurHook(command) {
125
+ const path = command.replace(/\\/g, '/');
126
+ return HOOKS.some(([, file]) => path.endsWith(`/hooks/${file}`));
127
+ }
@@ -6,11 +6,12 @@ export const INSTRUCTIONS = [
6
6
  BLOCK_START,
7
7
  '## Project memory',
8
8
  '',
9
- 'This project has persistent memory of past sessions, served by the `memory`',
10
- 'MCP server. Session summaries are injected at startup and the best matching',
11
- 'observation is injected above each prompt, but that is only ever a slice.',
9
+ 'You have persistent memory of this project: your past sessions, decisions',
10
+ 'and their reasoning, served by the `memory` MCP server. Session summaries',
11
+ 'are injected at startup and the best matching observation is injected above',
12
+ 'each prompt, but that is only ever a slice of what you know.',
12
13
  '',
13
- 'Search it *before* re-deriving something this project already knows. That',
14
+ 'Recall the rest *before* re-deriving something you already learned. That',
14
15
  'means before grepping or reading git history to reconstruct why something is',
15
16
  'the way it is, before saying you lack context, and before asking the user to',
16
17
  're-explain a past decision or a failed approach: call `search`, then',
package/dist/cli/usage.js CHANGED
@@ -15,6 +15,7 @@ export function usage() {
15
15
  projects List every project with memory in this database
16
16
  merge [<old-path>] [--yes] Move memory from an old project path onto this one
17
17
  stats What this project's memory is made of
18
+ adoption How often sessions grep vs use the memory tools
18
19
  flush Re-ingest every transcript for this project
19
20
  seed --from-git [--limit n] Fill a cold memory from this repo's history
20
21
  scan [--force] Map this repo's symbols and how they connect
@@ -1,7 +1,7 @@
1
1
  export { LANGUAGES, languageFor, languageNames } from './languages/index.js';
2
2
  export type { LanguageSpec } from './languages/index.js';
3
3
  export { loadParser } from './parser.js';
4
- export { currentHashes, listFiles, scanRepository, sourceFiles } from './scan/index.js';
4
+ export { SCAN_VERSION, currentHashes, hashOf, listFiles, scanRepository, sourceFiles, } from './scan/index.js';
5
5
  export type { ScanOptions, ScanResult } from './scan/index.js';
6
- export { formatGraph, queryGraph, refreshGraph, shortestPath } from './query/index.js';
6
+ export { formatGraph, nearest, queryGraph, refreshGraph, shortestPath, suggestFor, } from './query/index.js';
7
7
  export type { GraphAnswer, GraphMode, GraphQuery } from './query/index.js';
@@ -1,4 +1,4 @@
1
1
  export { LANGUAGES, languageFor, languageNames } from './languages/index.js';
2
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';
3
+ export { SCAN_VERSION, currentHashes, hashOf, listFiles, scanRepository, sourceFiles, } from './scan/index.js';
4
+ export { formatGraph, nearest, queryGraph, refreshGraph, shortestPath, suggestFor, } from './query/index.js';
@@ -1,3 +1,4 @@
1
+ import { formatSuggestions } from './suggest.js';
1
2
  function tag(edge) {
2
3
  const score = edge.confidence === 'INFERRED' ? ` ${edge.score.toFixed(2)}` : '';
3
4
  return `[${edge.relation}] [${edge.confidence}${score}]`;
@@ -5,15 +6,18 @@ function tag(edge) {
5
6
  export function formatGraph(answer, root) {
6
7
  if (answer.mode === 'path') {
7
8
  if (answer.path.length === 0) {
8
- return `No path found from "${answer.symbol}" to "${answer.target ?? ''}".`;
9
+ return (`No path found from "${answer.symbol}" to "${answer.target ?? ''}".` +
10
+ formatSuggestions(answer.suggestions));
9
11
  }
10
12
  return [
11
13
  `Shortest path (${answer.path.length - 1} hops):`,
12
14
  ` ${answer.path.join(' --> ')}`,
13
15
  ].join('\n');
14
16
  }
15
- if (answer.empty)
16
- return `No symbol "${answer.symbol}" in the graph for ${root}.`;
17
+ if (answer.empty) {
18
+ return (`No symbol "${answer.symbol}" in the graph for ${root}.` +
19
+ formatSuggestions(answer.suggestions));
20
+ }
17
21
  const lines = [];
18
22
  for (const definition of answer.definitions) {
19
23
  lines.push(`${definition.name} [${definition.kind}]`);
@@ -3,3 +3,4 @@ export { queryGraph } from './lookup.js';
3
3
  export type { GraphAnswer, GraphMode, GraphQuery } from './lookup.js';
4
4
  export { shortestPath } from './path.js';
5
5
  export { refreshGraph } from './refresh.js';
6
+ export { nearest, suggestFor } from './suggest.js';
@@ -2,3 +2,4 @@ export { formatGraph } from './format.js';
2
2
  export { queryGraph } from './lookup.js';
3
3
  export { shortestPath } from './path.js';
4
4
  export { refreshGraph } from './refresh.js';
5
+ export { nearest, suggestFor } from './suggest.js';
@@ -11,6 +11,7 @@ export interface GraphAnswer {
11
11
  path: string[];
12
12
  refreshed: string[];
13
13
  empty: boolean;
14
+ suggestions: string[];
14
15
  }
15
16
  export interface GraphQuery {
16
17
  mode: GraphMode;
@@ -1,4 +1,5 @@
1
1
  import { shortestPath } from './path.js';
2
+ import { suggestFor } from './suggest.js';
2
3
  export async function queryGraph(store, project, query) {
3
4
  const answer = {
4
5
  mode: query.mode,
@@ -9,12 +10,15 @@ export async function queryGraph(store, project, query) {
9
10
  path: [],
10
11
  refreshed: [],
11
12
  empty: false,
13
+ suggestions: [],
12
14
  };
13
15
  if (query.mode === 'path') {
14
16
  if (query.target)
15
17
  answer.target = query.target;
16
18
  answer.path = await shortestPath(store, project, query.symbol, query.target ?? '');
17
19
  answer.empty = answer.path.length === 0;
20
+ if (answer.empty)
21
+ answer.suggestions = await suggestFor(store, project, query.symbol);
18
22
  return answer;
19
23
  }
20
24
  answer.definitions = await store.findSymbols({
@@ -31,5 +35,7 @@ export async function queryGraph(store, project, query) {
31
35
  answer.inbound = edges.filter((edge) => edge.dstName === query.symbol);
32
36
  answer.outbound = edges.filter((edge) => ids.includes(edge.srcId) && edge.dstName !== query.symbol);
33
37
  answer.empty = answer.definitions.length === 0 && answer.inbound.length === 0;
38
+ if (answer.empty)
39
+ answer.suggestions = await suggestFor(store, project, query.symbol);
34
40
  return answer;
35
41
  }
@@ -0,0 +1,5 @@
1
+ import type { MemoryStore } from '../../store/adapter.js';
2
+ /** Names closest to `symbol`, best first. A miss that names no alternative is where people quit. */
3
+ export declare function nearest(names: Iterable<string>, symbol: string, limit?: number): string[];
4
+ export declare function suggestFor(store: MemoryStore, project: string, symbol: string): Promise<string[]>;
5
+ export declare function formatSuggestions(suggestions: string[]): string;
@@ -0,0 +1,65 @@
1
+ const CANDIDATES = 5000;
2
+ function tokens(name) {
3
+ return (name
4
+ .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
5
+ .split(/[^A-Za-z0-9]+/)
6
+ .filter(Boolean)
7
+ .map((part) => part.toLowerCase())
8
+ // Stem the plural: "hooks" and "hook" are the same misremembered name.
9
+ .map((part) => (part.length > 3 && part.endsWith('s') ? part.slice(0, -1) : part)));
10
+ }
11
+ function score(candidate, query) {
12
+ const left = candidate.toLowerCase();
13
+ const right = query.toLowerCase();
14
+ if (left === right)
15
+ return 100;
16
+ // Ratios are taken against the LONGER name: without that, one-letter locals
17
+ // score as well as the real symbol, because everything contains "e".
18
+ const longest = Math.max(left.length, right.length);
19
+ let prefix = 0;
20
+ while (prefix < left.length && prefix < right.length && left[prefix] === right[prefix]) {
21
+ prefix += 1;
22
+ }
23
+ const byPrefix = prefix >= 3 ? (prefix / longest) * 120 : 0;
24
+ const wanted = tokens(query);
25
+ const mine = tokens(candidate);
26
+ const shared = mine.filter((part) => wanted.includes(part)).length;
27
+ const byToken = shared > 0 ? (shared / Math.max(mine.length, wanted.length)) * 100 : 0;
28
+ const contains = left.includes(right) || right.includes(left);
29
+ const byContains = contains ? (Math.min(left.length, right.length) / longest) * 100 : 0;
30
+ return Math.max(byPrefix, byToken, byContains);
31
+ }
32
+ /** Names closest to `symbol`, best first. A miss that names no alternative is where people quit. */
33
+ export function nearest(names, symbol, limit = 5) {
34
+ const scored = new Map();
35
+ for (const name of names) {
36
+ // Two-character locals are never what someone misremembered.
37
+ if (name === symbol || name.length < 3)
38
+ continue;
39
+ const value = score(name, symbol);
40
+ // Below this, matches are incidental ("widget" contains "get") and a wrong
41
+ // suggestion costs more than none: it sends you looking for the wrong thing.
42
+ if (value >= 40)
43
+ scored.set(name, Math.max(scored.get(name) ?? 0, value));
44
+ }
45
+ return [...scored]
46
+ .sort((a, b) => b[1] - a[1] || a[0].length - b[0].length || a[0].localeCompare(b[0]))
47
+ .slice(0, limit)
48
+ .map(([name]) => name);
49
+ }
50
+ export async function suggestFor(store, project, symbol) {
51
+ if (!symbol)
52
+ return [];
53
+ try {
54
+ const symbols = await store.findSymbols({ project, limit: CANDIDATES });
55
+ return nearest(symbols.map((entry) => entry.name), symbol);
56
+ }
57
+ catch {
58
+ return [];
59
+ }
60
+ }
61
+ export function formatSuggestions(suggestions) {
62
+ if (suggestions.length === 0)
63
+ return '';
64
+ return `\nDid you mean: ${suggestions.join(', ')}`;
65
+ }
@@ -5,6 +5,7 @@ export interface SourceFile {
5
5
  source: string;
6
6
  hash: string;
7
7
  }
8
+ export declare const SCAN_VERSION = 2;
8
9
  export declare function hashOf(bytes: Buffer): string;
9
10
  export declare function listFiles(root: string): string[];
10
11
  export declare function sourceFiles(root: string): string[];
@@ -2,11 +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 { languageFor } from '../languages/index.js';
5
+ import { LANGUAGES, languageFor } from '../languages/index.js';
6
6
  const MAX_BUFFER = 64 * 1024 * 1024;
7
7
  const MAX_FILE_BYTES = 1024 * 1024;
8
+ export const SCAN_VERSION = 2;
9
+ const RULES_FINGERPRINT = createHash('sha256')
10
+ .update(JSON.stringify(LANGUAGES))
11
+ .digest('hex')
12
+ .slice(0, 12);
13
+ const CACHE_KEY = `v${SCAN_VERSION}:${RULES_FINGERPRINT}\n`;
8
14
  export function hashOf(bytes) {
9
- return createHash('sha256').update(bytes).digest('hex').slice(0, 32);
15
+ return createHash('sha256').update(CACHE_KEY).update(bytes).digest('hex').slice(0, 32);
10
16
  }
11
17
  export function listFiles(root) {
12
18
  const list = (args) => execFileSync('git', ['-C', root, ...args], {
@@ -1,6 +1,6 @@
1
1
  import type { CodeEdge, CodeSymbol, ScannedFile } from '../../types.js';
2
2
  export type { SourceFile } from './files.js';
3
- export { currentHashes, hashOf, listFiles, sourceFiles } from './files.js';
3
+ export { SCAN_VERSION, currentHashes, hashOf, listFiles, sourceFiles } from './files.js';
4
4
  export interface ScanOptions {
5
5
  root: string;
6
6
  project: string;
@@ -2,7 +2,7 @@ import { loadParser } from '../parser.js';
2
2
  import { extractFile } from './extract.js';
3
3
  import { listFiles, readSource } from './files.js';
4
4
  import { resolveEdges } from './resolve.js';
5
- export { currentHashes, hashOf, listFiles, sourceFiles } from './files.js';
5
+ export { SCAN_VERSION, currentHashes, hashOf, listFiles, sourceFiles } from './files.js';
6
6
  export function scanRepository(options) {
7
7
  const { root, project, known, force } = options;
8
8
  loadParser();
@@ -0,0 +1,5 @@
1
+ export declare const DECLARED: Set<string>;
2
+ export declare function isSymbol(pattern: string): boolean;
3
+ export declare function isWord(pattern: string): boolean;
4
+ /** Symbols a shell command searches the tree for, which the code graph also answers. */
5
+ export declare function symbolsGreppedIn(command: string): string[];