Two files, one repository
justrach/codedb ships 3 formats across 3 indexed files. The question worth asking is whether the second one says anything the first does not.
| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 5 | 6 | 0% |
| Commands | 1 | 1 | 3 | 20% |
| Section tags | 1 | 2 | 3 | 17% |
What each file covers
Sections
0 shared · 5 only in A · 6 only in B- − codedb Agent Guidelines
- − What codedb is (and isn't)
- − Review guidelines
- − Pre-merge verification
- − Security-sensitive areas
- + codedb — Agent Instructions
- + Project
- + Rules
- + Filing Issues
- + Test Style
- + Code Style
Commands
1 shared · 1 only in A · 3 only in B- − python3 scripts/e2e_mcp_test.py \
- + zig build test-index
- + zig build test 2>&1 | grep "issue-XX"
- + gh issue create
- zig build test
Section tags
1 shared · 2 only in A · 3 only in B- − git-pr
- − security
- + test
- + code-style
- + do-not
- agent-behaviour
Line diff
justrach/codedb · AGENTS.md
@@ −1 @@
1# codedb Agent Guidelines
2
3## What codedb is (and isn't)
4
5codedb is a **code-intelligence and context tool, not an editor.** It exists to
6help agents *find and understand* code — structural search, symbol/caller
7lookup, dependency graph, outlines, and task-shaped context — so they can edit
8with their own native tools. codedb has **no edit capability**: the old
9`codedb_edit` fallback (and the HTTP `POST /edit` endpoint, the post-edit
10linter, and `codedb_diagnostics`) was removed because MCP edit calls bypass the
11client's own undo/rewind tracking. Keep that framing consistent across tool
12descriptions, the MCP `initialize` instructions, the README, and these docs.
13
14## Review guidelines
15
16- Flag any security issues: injection, file traversal, untrusted input, secret exposure
17- Verify that sensitive files (.env, .pem, .key, credentials) are excluded from indexing AND search
18- Check that telemetry behavior matches documentation claims
19- Flag any regression in benchmark-critical paths (threshold: 10%)
20- Treat P1 issues as merge-blocking
21- Verify new language parsers handle malformed input gracefully (braces in strings, unterminated comments)
22- Check that installer scripts don't execute untrusted code or skip verification
23
24## Pre-merge verification
25
26Run these before merging any MCP-related change:
27
28```bash
29zig build test # unit tests
30python3 scripts/e2e_mcp_test.py \
31 --binary zig-out/bin/codedb \
32 --project /path/to/codedb # E2E MCP scenarios
33```
34
35`e2e_mcp_test.py` covers three scenarios:
361. **issue-346 regression** — spawn from cwd=`/`, roots handshake, tools return real data
372. **Normal mode** — explicit positional root (`codedb <path> mcp`), immediate scan
383. **No-roots client** — spawn from `/` with no roots capability, stays alive gracefully
39
40## Security-sensitive areas
41
42- `src/watcher.zig` — file indexing skip lists (secrets must be excluded)
43- `src/mcp.zig` — file read/search (path traversal, scope boundaries)
44- `src/telemetry.zig` — data collection and transmission (must match docs)
45- `src/snapshot.zig` — sensitive file filtering
46- `install/install.sh` — binary download and config modification
47
justrach/codedb · CLAUDE.md
@@ +1 @@
1# codedb — Agent Instructions
2
3## Project
4
5Zig 0.16.x code intelligence server. Tests live in the split `src/test_*.zig` files — one binary per area (see `build.zig`). Build and test with `zig build test`; run a single binary with e.g. `zig build test-index`.
6
7## Rules
8
9### Filing Issues
10
11**Every GitHub issue must include a failing test case.** No exceptions.
12
13When creating an issue:
14
151. Write a `test "issue-XX: <description>"` block in the matching `src/test_*.zig` file (e.g. `src/test_index.zig` for index bugs) that **fails** on the current `main` branch
162. Verify it fails: `zig build test 2>&1 | grep "issue-XX"`
173. File the issue via `gh issue create` with this structure:
18 - **Title:** `<module>: <concise description>`
19 - **Body sections:** Problem, Failing Test (the zig test block), Expected, Fix
20 - **Labels:** `bug` for defects, `priority:p0` for crashes, `priority:p2` for correctness
214. Commit the failing test on a branch: `issue-XX-failing-test`
225. Do **not** fix the bug in the same commit as the failing test
23
24If you cannot write a failing test, the issue is not well-defined enough to file.
25
26### Test Style
27
28- Use `std.testing` and `testing.allocator`
29- Use `std.heap.ArenaAllocator` for Explorer tests
30- Always `defer` cleanup (arena.deinit, allocator.free)
31- One test per issue, named `test "issue-XX: <short description>"`
32- Keep tests minimal — only exercise the specific broken code path
33
34### Code Style
35
36- No comments or documentation changes unless explicitly asked
37- Prefer minimal, targeted fixes over refactors
38- Follow existing patterns in the module you're editing
39
@@ −1 +1 @@
1−# codedb Agent Guidelines
1+# codedb — Agent Instructions
22
3−## What codedb is (and isn't)
3+## Project
44
5−codedb is a **code-intelligence and context tool, not an editor.** It exists to
6−help agents *find and understand* code — structural search, symbol/caller
7−lookup, dependency graph, outlines, and task-shaped context — so they can edit
8−with their own native tools. codedb has **no edit capability**: the old
9−`codedb_edit` fallback (and the HTTP `POST /edit` endpoint, the post-edit
10−linter, and `codedb_diagnostics`) was removed because MCP edit calls bypass the
11−client's own undo/rewind tracking. Keep that framing consistent across tool
12−descriptions, the MCP `initialize` instructions, the README, and these docs.
5+Zig 0.16.x code intelligence server. Tests live in the split `src/test_*.zig` files — one binary per area (see `build.zig`). Build and test with `zig build test`; run a single binary with e.g. `zig build test-index`.
136
14−## Review guidelines
7+## Rules
158
16−- Flag any security issues: injection, file traversal, untrusted input, secret exposure
17−- Verify that sensitive files (.env, .pem, .key, credentials) are excluded from indexing AND search
18−- Check that telemetry behavior matches documentation claims
19−- Flag any regression in benchmark-critical paths (threshold: 10%)
20−- Treat P1 issues as merge-blocking
21−- Verify new language parsers handle malformed input gracefully (braces in strings, unterminated comments)
22−- Check that installer scripts don't execute untrusted code or skip verification
9+### Filing Issues
2310
24−## Pre-merge verification
11+**Every GitHub issue must include a failing test case.** No exceptions.
2512
26−Run these before merging any MCP-related change:
13+When creating an issue:
2714
28−```bash
29−zig build test # unit tests
30−python3 scripts/e2e_mcp_test.py \
31− --binary zig-out/bin/codedb \
32− --project /path/to/codedb # E2E MCP scenarios
33−```
15+1. Write a `test "issue-XX: <description>"` block in the matching `src/test_*.zig` file (e.g. `src/test_index.zig` for index bugs) that **fails** on the current `main` branch
16+2. Verify it fails: `zig build test 2>&1 | grep "issue-XX"`
17+3. File the issue via `gh issue create` with this structure:
18+ - **Title:** `<module>: <concise description>`
19+ - **Body sections:** Problem, Failing Test (the zig test block), Expected, Fix
20+ - **Labels:** `bug` for defects, `priority:p0` for crashes, `priority:p2` for correctness
21+4. Commit the failing test on a branch: `issue-XX-failing-test`
22+5. Do **not** fix the bug in the same commit as the failing test
3423
35−`e2e_mcp_test.py` covers three scenarios:
36−1. **issue-346 regression** — spawn from cwd=`/`, roots handshake, tools return real data
37−2. **Normal mode** — explicit positional root (`codedb <path> mcp`), immediate scan
38−3. **No-roots client** — spawn from `/` with no roots capability, stays alive gracefully
24+If you cannot write a failing test, the issue is not well-defined enough to file.
3925
40−## Security-sensitive areas
26+### Test Style
4127
42−- `src/watcher.zig` — file indexing skip lists (secrets must be excluded)
43−- `src/mcp.zig` — file read/search (path traversal, scope boundaries)
44−- `src/telemetry.zig` — data collection and transmission (must match docs)
45−- `src/snapshot.zig` — sensitive file filtering
46−- `install/install.sh` — binary download and config modification
28+- Use `std.testing` and `testing.allocator`
29+- Use `std.heap.ArenaAllocator` for Explorer tests
30+- Always `defer` cleanup (arena.deinit, allocator.free)
31+- One test per issue, named `test "issue-XX: <short description>"`
32+- Keep tests minimal — only exercise the specific broken code path
33+
34+### Code Style
35+
36+- No comments or documentation changes unless explicitly asked
37+- Prefer minimal, targeted fixes over refactors
38+- Follow existing patterns in the module you're editing
4739
