Analysing legacy code with an assistant usually produces a pile of Markdown nobody can audit; here each file declares the line ranges it covers, so the honest questions — what fraction is documented, what is untouched, which explanations no longer match the code — are answered from hashes rather than from impressions. The habit that makes it work is reconciling immediately after writing an analysis, because coverage is recorded at that step and not before. Everything lives in the repo, so a second agent in a later session starts from what the first one already covered.
Coverage accounting for code analysis. Each analysis is a Markdown file declaring the source file and line ranges it explains; a registry hashes both sides so it knows when an analysis has gone out of date with the code it describes.
- Analysis files written under the project's analysis directory with frontmatter recording the source path, the covered line ranges and the dates
- That frontmatter parsed back out of any analysis file
- Reconciliation of one analysis into the registry — hashes, covered ranges and freshness — which is the step that makes coverage real rather than claimed
- A full rescan across every matching analysis file, for after a pull or a bulk edit
- Per-source status: total lines, which ranges are analysed, which are missing, and which analysis files claim them
- A project-wide overview with coverage percentages per source, range attribution, stale records, and file and line totals, computed from fresh records only
- The registry queried by staleness — analysis newer than the source, source newer than the analysis, or the record missing entirely — and the whole inventory returned as structured JSON
- A tree view of analysis records grouped by directory
- The registry exported as a report in JSON, YAML, text or HTML
- Selected analyses bundled for reading elsewhere: a table of contents and combined file, split into parts with a manifest when size requires it
Node.js 18 or newer with npx on the PATH; it runs as npx @mtimma/knowerage. KNOWERAGE_WORKSPACE_ROOT has to point at the project root, since everything is relative to it. KNOWERAGE_AUTO_FULL_RECONCILE is optional and off unless set to a truthy value; when on, a watcher rebuilds the registry after changes under the knowerage directory, ignoring its own writes so it cannot loop. Reconciliation is not automatic otherwise — an analysis written without it is not counted. State lives in the repository as analysis Markdown plus a registry JSON file keyed by analysis path, so it is reviewable and travels with the code. It can also be built from source with Cargo.
One command — npx @mtimma/knowerage