feat(state-dir): .codemap/ directory consolidation + self-healing files (impl of PR #53 plan)#54
Merged
SutuSebastian merged 7 commits intomainfrom May 3, 2026
Merged
Conversation
- application/state-dir.ts: resolveStateDir({root, cliFlag, env}) per plan §D7. Constants STATE_DIR_DEFAULT='.codemap', STATE_DB_NAME='index.db'. 12 unit tests cover precedence + relative/absolute paths.
- config.ts: ResolvedCodemapConfig gains stateDir; resolveCodemapConfig 3rd arg opts.stateDir; databasePath defaults to <stateDir>/index.db. User-supplied databasePath wins (escape hatch).
- config.ts: loadUserConfig reads <state-dir>/config.{ts,js,json} (D8); legacy <root>/codemap.config.* dropped (pre-v1).
- runtime.ts: getStateDir() getter.
- bootstrap.ts: --state-dir + CODEMAP_STATE_DIR; precedence per D7.
- bootstrap-codemap.ts (new): single helper extracts the loadUserConfig+resolveCodemapConfig+initCodemap+configureResolver dance from 9 cmd-* files. Tracer 4's ensureStateDir attaches here.
- All 9 cmd-* files refactored; stateDir threaded through interfaces + main.ts dispatch + ServerOpts (mcp/serve).
- audit-worktree.ts: cached entries at <sha>/.codemap/index.db (recursive layout — each cached worktree is its own self-contained codemap project).
- audit-engine.ts: makeWorktreeReindex stops hard-coding db path; openCodemapDatabase() reads from initialised runtime.
- sqlite-db.ts: openCodemapDatabase mkdirs the parent (state-dir may not exist on fresh project).
Dogfood:
- .codemap/.gitignore (self-managed, blacklist) — codemap repo + fixtures/minimal/
- root .gitignore: dropped .codemap.* and .codemap/audit-cache/ (nested .gitignore handles them)
- fixtures/minimal/.codemap.db* removed (stale legacy)
703 tests pass.
…er 2)
- STATE_GITIGNORE_BODY constant — single source of truth for the canonical blacklist.
- ensureStateGitignore(stateDir) — pure-shape return ({before, after, written}); idempotent (no write on steady state); auto-mkdir; user-edits rewritten back per D11 (file is codemap-managed; header line declares it).
- 5 tests cover: fresh write, idempotent, user-modified, older-version self-heal, returned shape matches disk.
Bumping STATE_GITIGNORE_BODY in a future PR is the entire migration — every consumer's project repairs itself on next codemap run.
…kill + changeset (Tracer 5) - README.md: --state-dir flag, config-file location, self-healing callout - docs/architecture.md: state-dir resolver in src/config.ts intro; bulk .codemap.db → .codemap/index.db; User config section rewritten with self-healing details (ensureStateGitignore + ensureStateConfig from src/application/, single attachment point in cli/bootstrap-codemap.ts) - docs/glossary.md: new entries for '.codemap/' / <state-dir> / CODEMAP_STATE_DIR; '.codemap/index.db'; '.codemap/.gitignore' / self-healing files - docs/roadmap.md: drop the consolidated-dir backlog item (it shipped) - docs/research/fallow.md: Adjacent-shipped bullet referencing PR #53 (plan) + #54 (impl) - .agents/rules/codemap.md + templates/agents/rules/codemap.md: bulk .codemap.db → .codemap/index.db; one-paragraph addition explaining state-dir + self-healing .gitignore (Rule 10 lockstep) - .agents/skills/codemap/SKILL.md + templates/agents/skills/codemap/SKILL.md: bulk path update (Rule 10 lockstep) - .changeset/codemap-dir-consolidation.md: minor — full design rationale + cleanup steps - docs/plans/codemap-dir-consolidation.md: deleted per docs-governance Rule 3
🦋 Changeset detectedLatest commit: c36ad42 The changes in this PR will be included in the next version bump. This PR includes changesets to release 1 package
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
|
Warning Rate limit exceeded
To keep reviews running without waiting, you can enable usage-based add-on for your organization. This allows additional reviews beyond the hourly cap. Account admins can enable it under billing. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (8)
📝 WalkthroughWalkthroughCodemap consolidates state artifacts into a configurable single directory (default ChangesState Directory Consolidation
Sequence DiagramsequenceDiagram
participant CLI as CLI (main.ts)
participant Parse as parseBootstrapArgs
participant Bootstrap as bootstrapCodemap
participant StateDir as State Dir Helpers
participant Config as loadUserConfig
participant Runtime as initCodemap
participant Cmd as Command Handler
CLI->>Parse: parseBootstrapArgs(argv)
Parse-->>CLI: { root, configFile, stateDir, rest }
CLI->>Bootstrap: bootstrapCodemap({ root, configFile, stateDir })
Bootstrap->>StateDir: resolveStateDir({ root, cliFlag, env })
StateDir-->>Bootstrap: absoluteStateDirPath
Bootstrap->>StateDir: ensureStateGitignore(stateDir)
StateDir-->>Bootstrap: { written: bool }
Bootstrap->>StateDir: ensureStateConfig(stateDir)
StateDir-->>Bootstrap: { found, written, warnings }
Bootstrap->>Config: loadUserConfig(root, configFile, { stateDir })
Config-->>Bootstrap: userConfig
Bootstrap->>Runtime: initCodemap(resolveCodemapConfig(root, user, { stateDir }))
Runtime-->>Bootstrap: ready
Bootstrap-->>CLI: initialized
CLI->>Cmd: runCommand(opts including stateDir)
Cmd->>Runtime: getStateDir(), openDb(), query()
Cmd-->>CLI: result
Estimated code review effort🎯 4 (Complex) | ⏱️ ~60 minutes Possibly related PRs
Suggested labels
Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Review rate limit: 0/1 reviews remaining, refill in 43 minutes and 18 seconds.Comment |
…hored comments
Doc staleness sweep (after Tracer 5):
- docs/glossary.md, docs/agents.md, docs/benchmark.md, docs/why-codemap.md, docs/research/competitive-scan-2026-04.md, docs/research/fallow.md (B.6 row): bulk `.codemap.db` → `.codemap/index.db` everywhere except the intentional 'old → new' migration callouts.
- docs/architecture.md, docs/research/fallow.md, docs/packaging.md: `codemap.config.{ts,json}` → `<state-dir>/config.{ts,js,json}`.
- docs/agents.md § Git: rewritten to describe the self-managed <state-dir>/.gitignore reconciler instead of root-.gitignore patching.
- docs/benchmark.md: 'where the DB lives' updated; manual .gitignore note dropped (reconciler handles it).
Concise-comments sweep on this turn's authored comments:
- src/application/state-config.ts: 2 inline comments slimmed (TS/JS-validation-only and passthrough-rationale).
Contributor
Author
|
@coderabbitai full review |
✅ Actions performedFull review triggered. |
Contributor
Author
|
@coderabbitai full review |
✅ Actions performedFull review triggered. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (4)
src/application/audit-worktree.ts (1)
53-53:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winThree stale
.codemap.dbreferences in JSDoc not updated by this PR.
- Line 53 (
PopulatedCacheEntry.dbPath):"Absolute path to the \.codemap.db` inside that worktree."`- Line 126 (
PopulateOpts.reindex):"must build \.codemap.db` inside it."`- Line 134 (
populateWorktreedocblock step 3):"builds \.codemap.db`"`All three should be updated to
.codemap/index.dbto match theCACHE_ENTRY_DB_RELconstant introduced on line 103.📝 Proposed fix
- /** Absolute path to the `.codemap.db` inside that worktree. */ + /** Absolute path to the `.codemap/index.db` inside that worktree. */ dbPath: string;- /** Reindex callback — receives the worktree path, must build `.codemap.db` inside it. */ + /** Reindex callback — receives the worktree path, must build `.codemap/index.db` inside it. */ reindex: (worktreePath: string) => Promise<void>;- * 3. caller's `reindex(<tmp>)` builds `.codemap.db` + * 3. caller's `reindex(<tmp>)` builds `.codemap/index.db`Also applies to: 126-126, 134-134
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/application/audit-worktree.ts` at line 53, Update the three stale JSDoc references that still say ".codemap.db" to the new path ".codemap/index.db": change the comment for PopulatedCacheEntry.dbPath, the doc for PopulateOpts.reindex, and the step in the populateWorktree docblock to reference ".codemap/index.db" (use the CACHE_ENTRY_DB_REL constant as the canonical source) so the documentation matches the new CACHE_ENTRY_DB_REL constant introduced in the file.src/cli/bootstrap.ts (1)
8-57:⚠️ Potential issue | 🟡 Minor | ⚡ Quick win
printCliUsage()has stale.codemap.dbreferences and missing docs for--state-dir/CODEMAP_STATE_DIR.Three gaps after the
--state-diraddition:
- Line 11:
update .codemap.db→ should be.codemap/index.db- Line 35:
keeps .codemap.db fresh→ should be.codemap/index.db- Line 49:
Environment:list omitsCODEMAP_STATE_DIRand--state-diris not listed under Options📝 Proposed fix
-Index (default): update .codemap.db for the project root (`--root` or cwd). +Index (default): update .codemap/index.db for the project root (`--root` or cwd).-Watch mode (long-running; keeps .codemap.db fresh on file edits): +Watch mode (long-running; keeps .codemap/index.db fresh on file edits):-Environment: CODEMAP_ROOT (same as --root) +Environment: CODEMAP_ROOT (same as --root), CODEMAP_STATE_DIR (same as --state-dir)Add to the Options section:
+ --state-dir DIR State directory (default .codemap/ under root)🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/cli/bootstrap.ts` around lines 8 - 57, Update printCliUsage(): change the two occurrences of ".codemap.db" to ".codemap/index.db" (the header "Index (default): update .codemap.db for the project root" and the watch-mode line "keeps .codemap.db fresh on file edits"); add documentation for --state-dir and CODEMAP_STATE_DIR in the printed help by adding a new Options bullet for "--state-dir <DIR> State directory (overrides CODEMAP_STATE_DIR)" and update the "Environment:" section to list CODEMAP_STATE_DIR alongside CODEMAP_ROOT so that printCliUsage() accurately documents the new state-dir flag and environment variable.src/config.ts (1)
63-68:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winOutdated JSDoc description for
databasePath.The description says "Default:
<root>/.codemap.db" but the actual default is now<stateDir>/index.db(line 181). Update the description to reflect the new default location.📝 Proposed fix
databasePath: z .string() .optional() .describe( - "SQLite database path, relative to root or absolute. Default: `<root>/.codemap.db`.", + "SQLite database path, relative to root or absolute. Default: `<state-dir>/index.db`.", ),🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/config.ts` around lines 63 - 68, The JSDoc for the zod field databasePath (the describe(...) call on the databasePath schema) is outdated; update its description string to state the correct default "<stateDir>/index.db" (or similar wording referencing stateDir) instead of "<root>/.codemap.db" so the describe(...) on databasePath matches the actual default used elsewhere (e.g., the default used when building the state directory and index DB).src/cli/main.ts (1)
312-314:⚠️ Potential issue | 🟠 Major | ⚡ Quick winPass
stateDirthroughquery --baselines.Line 313 is the one query dispatch path that still drops
stateDir, socodemap query --baselinesfalls back to the default DB instead of the caller-selected state directory.Suggested fix
if (parsed.kind === "listBaselines") { - await runListBaselinesCmd({ root, configFile, json: parsed.json }); + await runListBaselinesCmd({ + root, + configFile, + stateDir, + json: parsed.json, + }); return; }🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/cli/main.ts` around lines 312 - 314, The query dispatch for the "listBaselines" path drops the selected state directory so `codemap query --baselines` uses the default DB; update the call to runListBaselinesCmd in the branch where parsed.kind === "listBaselines" to pass the stateDir the same way other query variants do (include the stateDir variable alongside root, configFile and json), ensuring runListBaselinesCmd receives the caller-selected state directory and uses it to open the correct DB.
🧹 Nitpick comments (4)
src/application/state-dir.test.ts (1)
116-126: 💤 Low valueRedundant require for
mkdirSync.
mkdirSyncis already imported at the top of the file (line 5). The inlinerequire("node:fs")is unnecessary.♻️ Suggested fix
it("self-heals when an older codemap version's content is missing today's entries", () => { // Older shape — pre-audit-cache: only the DB lines. const olderBody = "# old codemap-managed file\nindex.db\nindex.db-shm\nindex.db-wal\n"; - const { mkdirSync } = require("node:fs") as typeof import("node:fs"); mkdirSync(stateDir, { recursive: true }); writeFileSync(join(stateDir, ".gitignore"), olderBody, "utf-8");🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/application/state-dir.test.ts` around lines 116 - 126, The test unnecessarily re-requires mkdirSync; remove the inline require and use the existing top-level import (mkdirSync) instead — edit the test in src/application/state-dir.test.ts to delete the "const { mkdirSync } = require('node:fs')" line and keep the call to mkdirSync(stateDir, { recursive: true }); so the test continues to call mkdirSync and validate ensureStateGitignore(stateDir) without duplicate imports..changeset/codemap-dir-consolidation.md (1)
9-19: 💤 Low valueConsider adding a language specifier to the fenced code block.
The directory tree structure could benefit from a language specifier (e.g.,
textorplaintext) to satisfy markdown linting rules, though this is purely cosmetic for a tree diagram.🔧 Suggested fix
-``` +```text <root>/ └── .codemap/ ← override via --state-dir / CODEMAP_STATE_DIR🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.changeset/codemap-dir-consolidation.md around lines 9 - 19, The markdown fenced code block showing the directory tree (starting with "<root>/" and ".codemap/") lacks a language specifier; update the opening fence from ``` to a language-tagged fence such as ```text or ```plaintext so the tree block satisfies markdown linting rules and renders as plain text.src/cli/cmd-index.ts (1)
8-14: 💤 Low valueConsider adding JSDoc documentation for
runIndexCmd.Other command handlers (
runShowCmd,runWatchCmd,runImpactCmd, etc.) have JSDoc comments describing their behavior. For consistency,runIndexCmdshould have similar documentation.📝 Proposed fix
+/** + * Run `codemap index`. Bootstraps codemap, opens db, then indexes files + * based on mode: `--files <paths>` for specific files, `--full` for full + * rebuild, or incremental by default. + */ export async function runIndexCmd(opts: {As per coding guidelines, all public APIs must have accompanying documentation.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/cli/cmd-index.ts` around lines 8 - 14, Add a JSDoc comment for the exported async function runIndexCmd describing its purpose, parameters, and return value (matching style used for runShowCmd/runWatchCmd/runImpactCmd); mention the opts parameter and its fields (root, configFile, stateDir, rest) and that the function calls bootstrapCodemap and returns a Promise<void>. Place the JSDoc immediately above the runIndexCmd declaration and follow the existing project's JSDoc format and tags.src/cli/bootstrap-codemap.ts (1)
2-3: 💤 Low valueConsider consolidating imports from the same module.
Both imports are from
"../application/state-dir"and can be merged into a single import statement.♻️ Proposed fix
-import { resolveStateDir } from "../application/state-dir"; -import { ensureStateGitignore } from "../application/state-dir"; +import { ensureStateGitignore, resolveStateDir } from "../application/state-dir";🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/cli/bootstrap-codemap.ts` around lines 2 - 3, The two separate imports from the same module should be consolidated into a single import statement: replace the duplicate imports of resolveStateDir and ensureStateGitignore with one combined import that imports both symbols (resolveStateDir, ensureStateGitignore) from "../application/state-dir" so they are imported together in a single line.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@templates/agents/skills/codemap/SKILL.md`:
- Around line 44-48: The doc still hardcodes `.codemap/...` as the state
directory; update wording in SKILL.md to reference the configurable state-dir
(e.g. use `<state-dir>/index.db` and `<state-dir>/recipes/` or explicitly state
“default: .codemap/” where appropriate) so references around
`.codemap/index.db`, `.codemap/recipes/`, and related sentences (mentions of
baselines, recipes, and gitignore behavior) reflect the new configurable
state-dir behavior; keep the CLI flag names (`--save-baseline`, `--baseline`,
`--baselines`, `--drop-baseline`, `--recipes-json`) unchanged and ensure any
place that implied “.codemap is not gitignored” or “.codemap/index.db is
gitignored” is updated to say “<state-dir>/index.db (default:
.codemap/index.db)” or similar.
---
Outside diff comments:
In `@src/application/audit-worktree.ts`:
- Line 53: Update the three stale JSDoc references that still say ".codemap.db"
to the new path ".codemap/index.db": change the comment for
PopulatedCacheEntry.dbPath, the doc for PopulateOpts.reindex, and the step in
the populateWorktree docblock to reference ".codemap/index.db" (use the
CACHE_ENTRY_DB_REL constant as the canonical source) so the documentation
matches the new CACHE_ENTRY_DB_REL constant introduced in the file.
In `@src/cli/bootstrap.ts`:
- Around line 8-57: Update printCliUsage(): change the two occurrences of
".codemap.db" to ".codemap/index.db" (the header "Index (default): update
.codemap.db for the project root" and the watch-mode line "keeps .codemap.db
fresh on file edits"); add documentation for --state-dir and CODEMAP_STATE_DIR
in the printed help by adding a new Options bullet for "--state-dir <DIR>
State directory (overrides CODEMAP_STATE_DIR)" and update the "Environment:"
section to list CODEMAP_STATE_DIR alongside CODEMAP_ROOT so that printCliUsage()
accurately documents the new state-dir flag and environment variable.
In `@src/cli/main.ts`:
- Around line 312-314: The query dispatch for the "listBaselines" path drops the
selected state directory so `codemap query --baselines` uses the default DB;
update the call to runListBaselinesCmd in the branch where parsed.kind ===
"listBaselines" to pass the stateDir the same way other query variants do
(include the stateDir variable alongside root, configFile and json), ensuring
runListBaselinesCmd receives the caller-selected state directory and uses it to
open the correct DB.
In `@src/config.ts`:
- Around line 63-68: The JSDoc for the zod field databasePath (the describe(...)
call on the databasePath schema) is outdated; update its description string to
state the correct default "<stateDir>/index.db" (or similar wording referencing
stateDir) instead of "<root>/.codemap.db" so the describe(...) on databasePath
matches the actual default used elsewhere (e.g., the default used when building
the state directory and index DB).
---
Nitpick comments:
In @.changeset/codemap-dir-consolidation.md:
- Around line 9-19: The markdown fenced code block showing the directory tree
(starting with "<root>/" and ".codemap/") lacks a language specifier; update the
opening fence from ``` to a language-tagged fence such as ```text or
```plaintext so the tree block satisfies markdown linting rules and renders as
plain text.
In `@src/application/state-dir.test.ts`:
- Around line 116-126: The test unnecessarily re-requires mkdirSync; remove the
inline require and use the existing top-level import (mkdirSync) instead — edit
the test in src/application/state-dir.test.ts to delete the "const { mkdirSync }
= require('node:fs')" line and keep the call to mkdirSync(stateDir, { recursive:
true }); so the test continues to call mkdirSync and validate
ensureStateGitignore(stateDir) without duplicate imports.
In `@src/cli/bootstrap-codemap.ts`:
- Around line 2-3: The two separate imports from the same module should be
consolidated into a single import statement: replace the duplicate imports of
resolveStateDir and ensureStateGitignore with one combined import that imports
both symbols (resolveStateDir, ensureStateGitignore) from
"../application/state-dir" so they are imported together in a single line.
In `@src/cli/cmd-index.ts`:
- Around line 8-14: Add a JSDoc comment for the exported async function
runIndexCmd describing its purpose, parameters, and return value (matching style
used for runShowCmd/runWatchCmd/runImpactCmd); mention the opts parameter and
its fields (root, configFile, stateDir, rest) and that the function calls
bootstrapCodemap and returns a Promise<void>. Place the JSDoc immediately above
the runIndexCmd declaration and follow the existing project's JSDoc format and
tags.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: b4c2da28-99d1-4bd6-a0af-3bc9caefdfd0
📒 Files selected for processing (50)
.agents/rules/codemap.md.agents/skills/codemap/SKILL.md.changeset/codemap-dir-consolidation.md.codemap/.gitignore.gitignoreREADME.mddocs/README.mddocs/agents.mddocs/architecture.mddocs/benchmark.mddocs/glossary.mddocs/packaging.mddocs/plans/codemap-dir-consolidation.mddocs/research/competitive-scan-2026-04.mddocs/research/fallow.mddocs/roadmap.mddocs/why-codemap.mdfixtures/minimal/.codemap/.gitignoresrc/agents-init.test.tssrc/agents-init.tssrc/application/audit-engine.tssrc/application/audit-worktree.test.tssrc/application/audit-worktree.tssrc/application/http-server.tssrc/application/mcp-server.tssrc/application/state-config.test.tssrc/application/state-config.tssrc/application/state-dir.test.tssrc/application/state-dir.tssrc/cli/bootstrap-codemap.tssrc/cli/bootstrap.tssrc/cli/cmd-audit.tssrc/cli/cmd-context.tssrc/cli/cmd-impact.tssrc/cli/cmd-index.tssrc/cli/cmd-mcp.tssrc/cli/cmd-query.tssrc/cli/cmd-serve.tssrc/cli/cmd-show.tssrc/cli/cmd-snippet.tssrc/cli/cmd-validate.tssrc/cli/cmd-watch.tssrc/cli/main.tssrc/cli/query-output-benchmark.test.tssrc/config.test.tssrc/config.tssrc/runtime.tssrc/sqlite-db.tstemplates/agents/rules/codemap.mdtemplates/agents/skills/codemap/SKILL.md
💤 Files with no reviewable changes (3)
- docs/plans/codemap-dir-consolidation.md
- docs/roadmap.md
- .gitignore
…f + 2 nitpicks)
Real bug:
- main.ts: runListBaselinesCmd was being called without stateDir — `codemap query --baselines` would fall back to the default DB instead of the caller-selected one. Fixed.
Stale doc refs:
- audit-worktree.ts: 3 JSDoc strings still said `.codemap.db` after Tracer 1's CACHE_ENTRY_DB_REL move; bumped to `.codemap/index.db`.
- bootstrap.ts: printCliUsage() had two `.codemap.db` refs + missing --state-dir/CODEMAP_STATE_DIR docs in Environment+Options. Fixed.
- config.ts: Zod databasePath.describe() said default was `<root>/.codemap.db`; corrected to `<state-dir>/index.db`.
- .agents/skills + templates skills: 2 hard-coded `.codemap/` refs reworded to `<state-dir>/` with `(default .codemap/)` callout (state-dir is configurable).
Nitpicks applied:
- state-dir.test.ts: dropped redundant `require('node:fs')` for mkdirSync (already imported).
- bootstrap-codemap.ts: consolidated two single-import lines from state-dir into one statement.
Nitpicks declined:
- changeset code-fence missing 'text' lang — purely cosmetic.
- cmd-index.ts JSDoc on runIndexCmd — 'all public APIs need JSDoc' is a fabricated rule (sibling cmds inconsistent; same hallucination rejected on PR #50).
Contributor
Author
|
Triaged 1 inline thread + 4 outside-diff comments + 4 nitpicks per `pr-comment-fact-check`. 7 of 9 actionable; 2 declined. Real bug found by CodeRabbit (🟠 Major):
Stale doc refs (🟡 Minor — all applied):
Nitpicks applied (2):
Nitpicks declined (2):
714 tests still pass. Ready for re-review or merge. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Implementation of PR #53's
.codemap/consolidation plan. Every codemap-managed path now lives under a single configurable state directory (default.codemap/); the per-feature root.gitignorepatching surface is collapsed to zero via the self-healing.codemap/.gitignorereconciler.Tracers
application/state-dir.ts—resolveStateDir({root, cliFlag, env})per plan §D7;ResolvedCodemapConfiggainsstateDir;databasePathdefaults to<state-dir>/index.db.loadUserConfignow reads<state-dir>/config.{ts,js,json}(D8). Legacy<root>/.codemap.db+<root>/codemap.config.*paths dropped (pre-v1, no shim per D2). Bootstrap surfaces--state-dir+CODEMAP_STATE_DIR. Extractedbootstrap-codemap.tshelper consolidates the dance from 9 cmd-* files. 12 unit tests.ensureStateGitignore— self-healing reconciler instate-dir.ts(D11). Pure{before, after, written}shape; idempotent; rewrites user-edited files back to canonical (file is codemap-managed, header line declares it). 5 unit tests including older-version self-heal.ensureStateConfig—application/state-config.ts(new). JSON: prune unknown keys withconsole.warn, alphabetical key sort, write only on drift. TS/JS: validate-only — never rewrites user code. 8 unit tests.bootstrap-codemap.tsruns reconcilers beforeloadUserConfig.agents-init.ts'sensureGitignoreCodemapPatternrewritten to delegate toensureStateGitignore— root.gitignoreno longer touched.docs/architecture.md§ User config,docs/glossary.md(new entries for<state-dir>,CODEMAP_STATE_DIR, self-healing files),.agents/+templates/agents/rule + skill (Rule 10 lockstep). Repo's own root.gitignoreslimmed (codemap entries removed);.codemap/.gitignorechecked in (canonical content).fixtures/minimal/dogfooded too. Plan deleted; minor changeset.Smoke
```
$ rm -rf /tmp/cm-smoke && mkdir -p /tmp/cm-smoke/src && echo "export const x = 1;" > /tmp/cm-smoke/src/a.ts
$ codemap --root /tmp/cm-smoke
$ ls -la /tmp/cm-smoke/.codemap/
.gitignore index.db index.db-shm index.db-wal
```
Single boot creates the state-dir + self-healing
.gitignore+ index DB; root.gitignoreis untouched.Self-healing principle (D11) in action
Future PRs that add a new generated cache:
STATE_GITIGNORE_BODY(one line)Every consumer's
<state-dir>/.gitignorerepairs itself on next codemap boot. Noagents initre-run, no manual.gitignoreedits, no migration script. The setup logic IS the migration.Same for the JSON config schema (
ensureStateConfigprunes removed fields, fills missing defaults via Zod, key-sorts).Test plan
ensureStateGitignoreoverwrite semantics (D11), and thebootstrap-codemap.tsordering (reconcilers beforeloadUserConfig).Pre-v1 cleanup for existing dev clones
Summary by CodeRabbit
New Features
--state-dirCLI option andCODEMAP_STATE_DIRenvironment variable..gitignoreand config) on startup.Refactor
.codemap/directory: database moved to.codemap/index.db, configuration to.codemap/config.{ts,js,json}, and gitignore patterns now managed in.codemap/.gitignore.Documentation