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
package/CHANGELOG.md CHANGED
@@ -1,5 +1,68 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.12.0
4
+
5
+ ### Added
6
+
7
+ - **Imports are followed in seven languages.** TypeScript, JavaScript, Python, Go, Rust, Java and Kotlin bind
8
+ an import to the exact file and symbol it names, so two symbols with one name in different modules stay
9
+ apart. `usages` lists the importing files in an `Imported by` group, and a name exported under another
10
+ name is followed too.
11
+ - **Java and Kotlin method calls reach the right method.** `x.method()` goes to the method of the declared
12
+ type of `x`, through parent classes and chained calls. A call on a value of unknown type stays `INFERRED`
13
+ and is listed once, under all the definitions it could be.
14
+ - **Kotlin is read with real syntax after install.** Grammars now ship as one small package per platform,
15
+ so nothing is downloaded and the install is about 44 MB smaller. `claude-db languages` shows how each
16
+ language is read; `languages add` and `remove` have nothing left to do. Where no grammar package fits,
17
+ such as Alpine Linux, those languages are read by pattern.
18
+
19
+ ### Changed
20
+
21
+ - **`find_usages` and `claude-db usages` answer from the graph by default.** References are grouped under
22
+ the definition they belong to, and lines that `git grep` finds but the graph cannot link come last, so
23
+ nothing a search would find is lost. Before the first `scan`, the answer comes from text and says so.
24
+ - **Scans re-read only what changed.** A local cache keeps each file's parse, so a refresh after an edit
25
+ takes well under a second. The first scan after upgrading re-reads every file once.
26
+ - **Hooks never wait for the graph.** The grep hook says when files changed since the last scan and
27
+ refreshes the graph in the background.
28
+
29
+ ### Development
30
+
31
+ - `npm run bench:usages` measures `find_usages` against compilers and independent checkers on 28 pinned
32
+ public repositories, with a nightly check for regressions.
33
+ - Code graph tests are fixture files run by one runner.
34
+
35
+ ### Docs
36
+
37
+ - A shorter CONTRIBUTING, with separate pages for adding a language and for releasing.
38
+
39
+ ## 0.11.1
40
+
41
+ ### Fixed
42
+
43
+ - **Facts no longer repeat a rule you saved by hand.** When a chat ended, the fact-making call saw the
44
+ earlier facts but not the rules you saved with `remember`, so it saved the same rule again and the start
45
+ of a chat listed it twice. The call now sees those rules and is told not to repeat them. Rules already
46
+ duplicated stay until you remove one with `claude-db forget <id>`.
47
+ - **`uninstall --project` leaves nothing empty behind.** It used to leave an empty `.mcp.json` and
48
+ `.claude/settings.local.json`, and an empty `.claude/skills` folder. It now removes them when nothing else
49
+ is in them. Your own settings, servers and skills are never touched, and a machine-wide uninstall is
50
+ unchanged.
51
+
52
+ ### Changed
53
+
54
+ - **`/handoff` keeps more, in a fixed size.** The note can now hold Decided, Rejected, Watch out and State
55
+ lines, with the reason after "because", and carries still-true lines forward. It is capped at 8 lines of
56
+ about 200 characters. At the start of a chat only those 8 lines are shown, each cut at 220 characters, with
57
+ a line saying how many more there are. The first line ends with the note's id, so the full text can be
58
+ read with `get_observations`.
59
+ - **`/catchup` shows the branch and how many files are uncommitted**, and the recent decisions and dead
60
+ ends, so a handoff can be written from facts and not only from the chat.
61
+
62
+ ### Docs
63
+
64
+ - A shorter setup guide and README, and a cleaner docs site with a Skills page and a clearer code block.
65
+
3
66
  ## 0.11.0
4
67
 
5
68
  ### Added
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  <img src="./assets/wordmark.svg" alt="claude-db" width="330">
2
2
 
3
- **Persistent memory for Claude Code. Bring your own database.**
3
+ **Free, open-source memory for Claude Code. Your own database, no cloud, no subscription.**
4
4
 
5
5
  [![npm](https://img.shields.io/npm/v/claude-db.svg)](https://www.npmjs.com/package/claude-db)
6
6
  [![CI](https://github.com/Avijit07x/claude-db/actions/workflows/ci.yml/badge.svg)](https://github.com/Avijit07x/claude-db/actions/workflows/ci.yml)
@@ -12,112 +12,75 @@
12
12
 
13
13
  ---
14
14
 
15
- ## Every session starts from zero
15
+ ## Why
16
16
 
17
- You spent an hour yesterday explaining why the store has three adapters, which
18
- approach you tried and dropped, and why one function must not be touched. Today
19
- Claude knows none of it, so you explain it again.
17
+ Every Claude Code chat starts from zero. You explain the same decisions, dead
18
+ ends and rules again, and Claude works out what calls what from scratch.
20
19
 
21
- claude-db gives Claude a memory that lasts, and a map of your code so it stops
22
- working out what calls what from scratch.
20
+ claude-db fixes that. It keeps what you decided and a map of your code, and
21
+ gives Claude the right part of it at the right time.
23
22
 
24
- ## What you get
23
+ ## What it does
25
24
 
26
- - **A memory that carries over.** When a chat ends, its decisions, dead ends and
27
- rules are saved as short facts, and the next chat starts by seeing them.
28
- - **The right memory with each prompt.** Claude Haiku picks the one or two
29
- earlier memories that fit what you just asked. That costs about 20 tokens a
30
- prompt on average, and nothing on 69% of prompts.
31
- - **A code graph.** Who defines or calls a symbol, answered in one call: 2.0x
32
- cheaper than grep and reading files, measured on eight real symbols.
33
- - **Your own database.** SQLite by default, or Postgres or MongoDB to share
34
- memory across machines. No cloud, no subscription.
25
+ - **Remembers across chats.** Decisions, dead ends and rules are saved when a
26
+ chat ends, and the next chat starts by seeing them.
27
+ - **Recalls what fits.** Each prompt gets the one or two earlier memories that
28
+ match it, and nothing when none fit.
29
+ - **Maps your code.** Who defines, calls or imports a symbol is answered in one
30
+ call, instead of grep and reading files. It follows imports in TypeScript,
31
+ JavaScript, Python, Go, Rust, Java and Kotlin.
32
+ - **Keeps it yours.** SQLite on your machine by default, or Postgres or MongoDB
33
+ to share across machines. No cloud, no subscription.
35
34
 
36
35
  ## Install
37
36
 
37
+ You need Node 22.16 or newer and a git repository.
38
+
38
39
  ```bash
39
40
  npm install -g claude-db
40
-
41
41
  cd your-project
42
42
  claude-db install --project
43
43
  ```
44
44
 
45
- Restart Claude Code. Capture and recall are hooks, so there is nothing else to
46
- run.
47
-
48
- `--project` limits it to this repo instead of every project on the machine. Add
49
- `.mcp.json` to your `.gitignore`, since it holds a path that only exists on your
50
- machine.
51
-
52
- A fresh install has no history yet. `claude-db scan` builds the code graph, and
53
- the `/cdb-scan` skill maps an existing codebase into memory, so search has
54
- something to find on day one. `/catchup` answers "where did I stop?" and `/handoff` leaves a note for the
55
- next chat. The [setup guide](./docs/setup-guide.md) covers
56
- the settings and habits that give the best results.
57
-
58
- ## Commands
59
-
60
- `cdb` is a shorter alias for all of them.
45
+ Restart Claude Code. There is nothing else to run, because capture and recall
46
+ are hooks.
61
47
 
62
- | Command | What it does |
63
- | ------------------------------- | ----------------------------------------------------- |
64
- | `claude-db install [--project]` | Register the hooks and the MCP server |
65
- | `claude-db status` | Is it wired up, and when did it last record anything |
66
- | `claude-db doctor [--deep]` | Show the resolved config; `--deep` tests a round trip |
67
- | `claude-db scan` | Build the code graph for this repo |
68
- | `claude-db use <url>` | Switch database and verify it |
69
- | `claude-db distill [on\|off]` | Turn chats into facts with Haiku |
70
- | `claude-db pick [on\|off]` | Let Haiku pick the memory shown with each prompt |
71
- | `claude-db view` | See this project's memory in the browser |
48
+ Then load what already exists with `claude-db flush` and `claude-db scan`. The
49
+ [setup guide](./docs/setup-guide.md) has the rest.
72
50
 
73
- Every other command, including `search`, `remember`, `sync` and `export`, is in
74
- the [CLI reference](https://claude-db.vercel.app/docs/cli).
51
+ ## Everyday use
75
52
 
76
- ## Use another database
53
+ | Where | What it does |
54
+ | --------------------- | ------------------------------------------------- |
55
+ | `/catchup` | Answers "where did I stop?" when you come back |
56
+ | `/handoff` | Leaves a short note for the next chat or a mate |
57
+ | `/cdb-scan` | Maps an existing codebase into memory |
58
+ | `claude-db status` | Shows whether it is wired up and what it recorded |
59
+ | `claude-db doctor` | Checks the setup, and finds what is wrong |
60
+ | `claude-db use <url>` | Switches to Postgres or MongoDB (`pg`/`mongodb`) |
77
61
 
78
- ```bash
79
- claude-db use "postgres://user:pass@host:5432/memory"
80
- claude-db use "mongodb+srv://user:pass@cluster.mongodb.net/memory"
81
- ```
82
-
83
- Install the driver first, with `npm install -g pg` or `npm install -g mongodb`.
84
- Neither ships by default.
62
+ `cdb` is a shorter alias. Every command is in the
63
+ [CLI reference](https://claude-db.vercel.app/docs/cli).
85
64
 
86
65
  ## Privacy
87
66
 
88
- Memory stays in your own database. Three things use the network, and each has
89
- an off switch:
90
-
91
- - **When a chat ends**, its saved, redacted text is sent once to Claude Haiku
92
- through your own login, to make facts. Turn it off with `claude-db distill off`.
93
- - **When a prompt has related memory**, the prompt, the end of Claude's last
94
- reply and up to ten saved excerpts go to Haiku, so it can pick what to show.
95
- Turn it off with `claude-db pick off`.
96
- - **Once a day**, the npm registry is asked for the latest version. Turn it off
97
- with `"updates": "off"` in the config.
67
+ Memory stays in your own database. Two features call Claude Haiku through your
68
+ own login, and each has an off switch: `claude-db distill off` for making facts
69
+ from finished chats, and `claude-db pick off` for choosing memory per prompt.
70
+ Once a day it asks npm for the latest version (`"updates": "off"` stops that).
98
71
 
99
72
  `.env`, `secrets/`, `node_modules` and `.git/` are never stored. Text inside
100
73
  `<private>...</private>` is stripped, and API keys and tokens are redacted
101
74
  before anything is written or sent.
102
75
 
103
- ## Requirements
104
-
105
- Node 22.16 or newer. SQLite comes from Node's builtin `node:sqlite`, so nothing
106
- compiles at install time. For real semantic search, run
107
- `npm install -g @xenova/transformers` and the embedder upgrades itself.
108
-
109
76
  ## Documentation
110
77
 
111
- - [Documentation site](https://claude-db.vercel.app/docs): the
112
- [CLI reference](https://claude-db.vercel.app/docs/cli),
113
- [MCP tools](https://claude-db.vercel.app/docs/mcp-tools),
114
- [how it works](https://claude-db.vercel.app/docs/how-it-works),
115
- [databases](https://claude-db.vercel.app/docs/databases) and
116
- [troubleshooting](https://claude-db.vercel.app/docs/troubleshooting)
117
- - [Setup guide](./docs/setup-guide.md): settings, habits and costs
78
+ - [Setup guide](./docs/setup-guide.md): install, head start and habits
79
+ - [Documentation site](https://claude-db.vercel.app/docs): CLI, MCP tools,
80
+ databases and troubleshooting
118
81
  - [With and without](./docs/with-and-without.md) and
119
- [benchmarks](https://claude-db.vercel.app/docs/benchmarks): every number,
120
- including the symbols where plain grep wins
82
+ [benchmarks](https://claude-db.vercel.app/docs/benchmarks): the numbers,
83
+ including where plain grep wins
121
84
  - [Changelog](./CHANGELOG.md)
122
85
 
123
86
  ## Contributing
@@ -129,8 +92,8 @@ npm test
129
92
  npm run lint
130
93
  ```
131
94
 
132
- [CONTRIBUTING.md](./CONTRIBUTING.md) has the conventions, the test setup, how to
133
- add a language to the code graph, and how releases are made. Security reports go
95
+ [CONTRIBUTING.md](./CONTRIBUTING.md) has the setup, the rules and the pull request
96
+ checklist, with links to adding a language and to releasing. Security reports go
134
97
  through [SECURITY.md](./SECURITY.md), privately.
135
98
 
136
99
  ## License
@@ -11,6 +11,7 @@ export interface CatchupData {
11
11
  work: string[];
12
12
  } | null;
13
13
  todos: string[];
14
+ decisions: string[];
14
15
  uncommitted: string[];
15
16
  git: GitState | null;
16
17
  }
@@ -1,10 +1,11 @@
1
1
  import { openWork } from '../capture/progress.js';
2
- import { FACT_SESSION, factType, onePerKey } from '../facts/model.js';
2
+ import { FACT_SESSION, factLabel, factType, onePerKey } from '../facts/model.js';
3
3
  import { handoffBodyLines, newestHandoff } from '../facts/handoff.js';
4
4
  import { readGitState } from './git-state.js';
5
5
  const CHAT_TITLES = 6;
6
6
  const TODOS = 5;
7
7
  const UNCOMMITTED = 5;
8
+ const DECISIONS = 5;
8
9
  const FACTS_SCANNED = 100;
9
10
  export async function gatherCatchup(ctx, project, now = Date.now()) {
10
11
  const handoff = await newestHandoff(ctx, project, now);
@@ -20,10 +21,15 @@ export async function gatherCatchup(ctx, project, now = Date.now()) {
20
21
  newest: true,
21
22
  limit: FACTS_SCANNED,
22
23
  });
23
- const todos = onePerKey(facts.filter((obs) => obs.status !== 'replaced'))
24
+ const current = onePerKey(facts.filter((obs) => obs.status !== 'replaced'));
25
+ const todos = current
24
26
  .filter((obs) => factType(obs) === 'todo')
25
27
  .slice(0, TODOS)
26
28
  .map((obs) => obs.title);
29
+ const decisions = current
30
+ .filter((obs) => ['decision', 'deadend'].includes(factType(obs) ?? ''))
31
+ .slice(0, DECISIONS)
32
+ .map((obs) => `${factLabel(obs)}: ${obs.title}`);
27
33
  const uncommitted = (await openWork(ctx.store, project))
28
34
  .slice(0, UNCOMMITTED)
29
35
  .map((obs) => obs.title);
@@ -33,6 +39,7 @@ export async function gatherCatchup(ctx, project, now = Date.now()) {
33
39
  ? { at: latest.startedAt, summary: latest.summary ?? '', work: chatWork }
34
40
  : null,
35
41
  todos,
42
+ decisions,
36
43
  uncommitted,
37
44
  git: readGitState(project),
38
45
  };
@@ -1,4 +1,6 @@
1
1
  export interface GitState {
2
+ branch: string | null;
3
+ changed: number;
2
4
  status: string[];
3
5
  hiddenStatusLines: number;
4
6
  commits: string[];
@@ -19,8 +19,11 @@ function lines(text) {
19
19
  export function readGitState(project, git = runGit(project)) {
20
20
  try {
21
21
  const status = lines(git(['status', '--short']));
22
+ const branch = lines(git(['branch', '--show-current']))[0] ?? null;
22
23
  const commits = lines(git(['log', `-n${RECENT_COMMITS}`, '--pretty=format:%h %s'])).map(redact);
23
24
  return {
25
+ branch,
26
+ changed: status.length,
24
27
  status: status.slice(0, STATUS_LINES),
25
28
  hiddenStatusLines: Math.max(0, status.length - STATUS_LINES),
26
29
  commits,
@@ -16,6 +16,12 @@ function gitLines(data) {
16
16
  commits: git.commits.map((line) => ` ${line}`),
17
17
  };
18
18
  }
19
+ function branchLine(git) {
20
+ if (!git)
21
+ return [];
22
+ const state = git.changed === 0 ? 'clean' : `${git.changed} file${git.changed === 1 ? '' : 's'} uncommitted`;
23
+ return [`Branch: ${git.branch ?? 'detached HEAD'}, ${state}`, ''];
24
+ }
19
25
  function chatBlock(chat, now) {
20
26
  if (!chat)
21
27
  return [];
@@ -33,7 +39,9 @@ export function renderCatchup(data, now = Date.now()) {
33
39
  ...handoffBlock(data.handoff, now),
34
40
  ...chatBlock(data.lastChat, now),
35
41
  ...section('Still to do (from facts):', bullets(data.todos)),
42
+ ...section('Decisions and dead ends (from facts):', bullets(data.decisions)),
36
43
  ...section('Not committed yet (recorded work):', bullets(data.uncommitted)),
44
+ ...branchLine(data.git),
37
45
  ...section('Git status:', status),
38
46
  ...section('Recent commits:', commits),
39
47
  ];
@@ -1,112 +1,136 @@
1
1
  import { createContext } from '../../context.js';
2
2
  import { findUsages, formatUsages, repoRootFor } from '../../usages/index.js';
3
- import { formatGraph, languageNames, queryGraph, refreshGraph, scanRepository, suggestFor, } from '../../graph/index.js';
3
+ import { NO_GRAPH, NO_GRAPH_FOR_PATH, answerQuery, formatGraph, hasGraph, languageNames, refreshGraph, saveScan, scanRepository, suggestFor, } from '../../graph/index.js';
4
+ import { PLATFORM } from '../../graph/grammars.js';
5
+ import { GRAPH_JOB } from '../../graph/scan/job.js';
6
+ import { releaseJob } from '../../util/job-lock.js';
4
7
  import { resolveProject } from '../../util/project.js';
5
8
  import { valueOf, withoutFlags } from '../args.js';
9
+ function printScan(root, scan, elapsedMs) {
10
+ console.log(`Scanned ${root}`);
11
+ console.log(` ${scan.symbols.length} symbols, ${scan.edges.length} edges written for ` +
12
+ `${scan.rewrite.length} file(s)`);
13
+ console.log(` ${scan.changed.length} file(s) parsed, ${scan.skipped} unchanged, ` +
14
+ `${scan.unsupported} not a supported language`);
15
+ console.log(` ${elapsedMs}ms (languages: ${languageNames()})`);
16
+ for (const [language, count] of Object.entries(scan.patternRead)) {
17
+ console.log(` ${count} ${language} file(s) are read by pattern: this install has no ${language} ` +
18
+ `grammar for ${PLATFORM}. Reinstall claude-db to add it.`);
19
+ }
20
+ if (scan.symbols.length === 0 && scan.changed.length > 0) {
21
+ console.log(' Nothing was extracted, which usually means no supported source files.');
22
+ }
23
+ }
24
+ async function runScan(root, project, force) {
25
+ const ctx = await createContext();
26
+ try {
27
+ const stored = new Map((await ctx.store.scannedFiles(project)).map((file) => [file.path, file.hash]));
28
+ const started = Date.now();
29
+ const scan = await scanRepository({ root, project, stored, force });
30
+ await saveScan(ctx.store, project, scan, force);
31
+ printScan(root, scan, Date.now() - started);
32
+ }
33
+ finally {
34
+ await ctx.close();
35
+ }
36
+ }
37
+ async function runRefresh(root, project) {
38
+ const ctx = await createContext();
39
+ try {
40
+ await refreshGraph(ctx.store, root, project);
41
+ }
42
+ finally {
43
+ await ctx.close();
44
+ }
45
+ }
6
46
  export async function cmdScan(argv) {
7
- const force = argv.includes('--force');
8
47
  const path = valueOf(argv, '--path');
9
48
  const root = repoRootFor(path ?? process.cwd());
10
49
  const project = resolveProject(undefined);
11
- const ctx = await createContext();
50
+ if (!argv.includes('--background')) {
51
+ await runScan(root, project, argv.includes('--force'));
52
+ return;
53
+ }
12
54
  try {
13
- const known = force
14
- ? new Map()
15
- : new Map((await ctx.store.scannedFiles(project)).map((f) => [f.path, f.hash]));
16
- const existing = force ? [] : await ctx.store.findSymbols({ project, limit: 200000 });
17
- const started = Date.now();
18
- const scan = scanRepository({
19
- root,
20
- project,
21
- known,
22
- ...(force ? { force } : {}),
23
- ...(existing.length > 0 ? { existing } : {}),
24
- });
25
- if (force)
26
- await ctx.store.removeGraph(project);
27
- else if (scan.changed.length > 0)
28
- await ctx.store.removeGraph(project, scan.changed);
29
- await ctx.store.upsertGraph({
30
- symbols: scan.symbols,
31
- edges: scan.edges,
32
- files: scan.files,
33
- });
34
- console.log(`Scanned ${root}`);
35
- console.log(` ${scan.symbols.length} symbols, ${scan.edges.length} edges`);
36
- console.log(` ${scan.changed.length} file(s) parsed, ${scan.skipped} unchanged, ` +
37
- `${scan.unsupported} not a supported language`);
38
- console.log(` ${Date.now() - started}ms (languages: ${languageNames()})`);
39
- if (scan.symbols.length === 0 && scan.changed.length > 0) {
40
- console.log(' Nothing was extracted, which usually means no supported source files.');
41
- }
55
+ await runRefresh(root, project);
42
56
  }
43
57
  finally {
44
- await ctx.close();
58
+ releaseJob(GRAPH_JOB, project);
45
59
  }
46
60
  }
47
- export async function cmdUsages(argv) {
48
- const regex = argv.includes('--regex');
61
+ const MODES = ['text', 'usages', 'explain', 'path'];
62
+ function fail(message) {
63
+ console.error(message);
64
+ process.exit(1);
65
+ }
66
+ const isMode = (value) => MODES.includes(value);
67
+ function usagesInput(argv) {
49
68
  const path = valueOf(argv, '--path');
69
+ const target = valueOf(argv, '--target');
70
+ const mode = valueOf(argv, '--mode') ?? 'usages';
50
71
  const context = Number(valueOf(argv, '--context') ?? 0);
51
72
  const limit = Number(valueOf(argv, '--limit') ?? 100);
52
- const mode = valueOf(argv, '--mode') ?? 'text';
53
- const targetFlag = valueOf(argv, '--target');
54
73
  const words = withoutFlags(argv, ['--path', '--context', '--limit', '--mode', '--target'])
55
74
  .filter((arg) => arg !== '--regex')
56
75
  .join(' ')
57
76
  .trim();
58
77
  if (!words) {
59
- console.error('Usage: claude-db usages [--mode text|usages|explain|path] [--regex] ' +
78
+ fail('Usage: claude-db usages [--mode usages|explain|path|text] [--regex] ' +
60
79
  '[--context <n>] [--path <dir>] [--limit <n>] <symbol> [<target>]');
61
- process.exit(1);
62
- }
63
- if (!Number.isFinite(context) || context < 0) {
64
- console.error('--context must be a non-negative number.');
65
- process.exit(1);
66
- }
67
- if (!Number.isFinite(limit) || limit <= 0) {
68
- console.error('--limit must be a positive number.');
69
- process.exit(1);
70
- }
71
- if (mode === 'text') {
72
- const result = findUsages({ symbol: words, regex, context, limit, ...(path ? { path } : {}) });
73
- console.log(formatUsages(result, await suggestionsOnMiss(result.matches.length, words)));
74
- return;
75
- }
76
- if (mode !== 'usages' && mode !== 'explain' && mode !== 'path') {
77
- console.error(`Unknown --mode "${mode}". Use text, usages, explain or path.`);
78
- process.exit(1);
79
80
  }
80
- const [symbol, positional] = words.split(/\s+/);
81
- const target = targetFlag ?? positional;
82
- if (mode === 'path' && !target) {
83
- console.error('--mode path needs two symbols: claude-db usages --mode path <from> <to>');
84
- process.exit(1);
81
+ if (!Number.isFinite(context) || context < 0)
82
+ fail('--context must be a non-negative number.');
83
+ if (!Number.isFinite(limit) || limit <= 0)
84
+ fail('--limit must be a positive number.');
85
+ if (!isMode(mode))
86
+ fail(`Unknown --mode "${mode}". Use usages, explain, path or text.`);
87
+ return {
88
+ words,
89
+ mode,
90
+ regex: argv.includes('--regex'),
91
+ context,
92
+ limit,
93
+ ...(path ? { path } : {}),
94
+ ...(target ? { target } : {}),
95
+ };
96
+ }
97
+ async function textAnswer(store, input) {
98
+ const { words, regex, context, limit, path } = input;
99
+ const result = findUsages({ symbol: words, regex, context, limit, ...(path ? { path } : {}) });
100
+ const missed = result.matches.length === 0 ? await suggestFor(store, resolveProject(undefined), words) : [];
101
+ return formatUsages(result, missed);
102
+ }
103
+ async function graphAnswer(store, input) {
104
+ const [symbol = '', positional] = input.words.split(/\s+/);
105
+ const target = input.target ?? positional;
106
+ if (input.mode === 'path' && !target) {
107
+ fail('--mode path needs two symbols: claude-db usages --mode path <from> <to>');
85
108
  }
86
- const root = repoRootFor(path ?? process.cwd());
87
109
  const project = resolveProject(undefined);
88
- const ctx = await createContext();
89
- try {
90
- const refreshed = await refreshGraph(ctx.store, root, project);
91
- const answer = await queryGraph(ctx.store, project, {
92
- mode,
93
- symbol: symbol ?? '',
94
- ...(target ? { target } : {}),
95
- limit,
96
- });
97
- answer.refreshed = refreshed;
98
- console.log(formatGraph(answer, root));
99
- }
100
- finally {
101
- await ctx.close();
110
+ if (!(await hasGraph(store, project))) {
111
+ if (input.mode === 'path')
112
+ fail(NO_GRAPH_FOR_PATH);
113
+ return `${NO_GRAPH}\n${await textAnswer(store, input)}`;
102
114
  }
115
+ const root = repoRootFor(input.path ?? process.cwd());
116
+ const mode = input.mode === 'text' ? 'usages' : input.mode;
117
+ const answer = await answerQuery({
118
+ store,
119
+ root,
120
+ project,
121
+ query: { mode, symbol, ...(target ? { target } : {}), limit: input.limit },
122
+ refresh: true,
123
+ });
124
+ return formatGraph(answer, root);
103
125
  }
104
- async function suggestionsOnMiss(matches, symbol) {
105
- if (matches > 0)
106
- return [];
126
+ export async function cmdUsages(argv) {
127
+ const input = usagesInput(argv);
107
128
  const ctx = await createContext();
108
129
  try {
109
- return await suggestFor(ctx.store, resolveProject(undefined), symbol);
130
+ const text = input.mode === 'text'
131
+ ? await textAnswer(ctx.store, input)
132
+ : await graphAnswer(ctx.store, input);
133
+ console.log(text);
110
134
  }
111
135
  finally {
112
136
  await ctx.close();
@@ -0,0 +1 @@
1
+ export declare function cmdLanguages(argv: (string | undefined)[]): void;
@@ -0,0 +1,22 @@
1
+ import { GRAMMARS, PLATFORM, hasGrammar } from '../../graph/grammars.js';
2
+ import { languageNames } from '../../graph/index.js';
3
+ const SHIPPED = 'Grammars ship with claude-db for each platform, so there is nothing to add or remove.';
4
+ const stateOf = (name) => hasGrammar(name)
5
+ ? 'read with real syntax'
6
+ : `read by pattern: no grammar for ${PLATFORM} in this install`;
7
+ function listLanguages() {
8
+ console.log(`read with real syntax: ${languageNames()}`);
9
+ for (const name of GRAMMARS)
10
+ console.log(` ${name.padEnd(8)} ${stateOf(name)}`);
11
+ if (GRAMMARS.some((name) => !hasGrammar(name))) {
12
+ console.log('Reinstall claude-db to add the grammars for this platform.');
13
+ }
14
+ }
15
+ export function cmdLanguages(argv) {
16
+ const [action] = argv.filter((arg) => arg !== undefined);
17
+ if (action === undefined || action === 'list')
18
+ return listLanguages();
19
+ if (action === 'add' || action === 'remove')
20
+ return console.log(SHIPPED);
21
+ throw new Error('usage: claude-db languages [list]');
22
+ }
@@ -2,3 +2,5 @@ export declare function readText(path: string): string;
2
2
  export declare function writeAtomic(path: string, content: string): void;
3
3
  export declare function readJson(path: string): Record<string, unknown>;
4
4
  export declare function writeJson(path: string, value: unknown): void;
5
+ export declare function writeJsonOrRemove(path: string, value: Record<string, unknown>): void;
6
+ export declare function removeIfEmpty(path: string): void;
package/dist/cli/files.js CHANGED
@@ -1,5 +1,5 @@
1
1
  import { dirname } from 'node:path';
2
- import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
2
+ import { mkdirSync, readFileSync, renameSync, rmSync, rmdirSync, writeFileSync } from 'node:fs';
3
3
  export function readText(path) {
4
4
  try {
5
5
  return readFileSync(path, 'utf8');
@@ -31,3 +31,17 @@ export function readJson(path) {
31
31
  export function writeJson(path, value) {
32
32
  writeAtomic(path, `${JSON.stringify(value, null, 2)}\n`);
33
33
  }
34
+ export function writeJsonOrRemove(path, value) {
35
+ if (Object.keys(value).length === 0)
36
+ rmSync(path, { force: true });
37
+ else
38
+ writeJson(path, value);
39
+ }
40
+ export function removeIfEmpty(path) {
41
+ try {
42
+ rmdirSync(path);
43
+ }
44
+ catch {
45
+ return;
46
+ }
47
+ }
package/dist/cli/index.js CHANGED
@@ -13,6 +13,7 @@ import { cmdCatchup } from './commands/catchup.js';
13
13
  import { cmdDistill } from './commands/distill.js';
14
14
  import { cmdPick } from './commands/pick.js';
15
15
  import { cmdScan, cmdUsages } from './commands/graph.js';
16
+ import { cmdLanguages } from './commands/languages.js';
16
17
  import { cmdSeed } from './commands/seed.js';
17
18
  import { cmdAdoption } from './commands/adoption.js';
18
19
  import { cmdView } from './commands/view.js';
@@ -110,6 +111,9 @@ async function run() {
110
111
  case 'scan':
111
112
  await cmdScan(args);
112
113
  break;
114
+ case 'languages':
115
+ cmdLanguages(args);
116
+ break;
113
117
  case 'sync':
114
118
  await cmdSync(args);
115
119
  break;