repowiseYour docs name files, link to headings, and tell readers to run commands.
repowise checks each of those references against the repository and
reports the ones the tree refutes. It runs on every init and update,
needs no model, and never edits your documents.
repowise doc-drift # everything the index found
repowise doc-drift --kind anchor # just links to renamed headings
repowise doc-drift --min-confidence 0.9 # the ones safe to fix without lookingWhat it checks
| Kind | The document says | It is a finding when |
|---|---|---|
path | a file or directory exists | nothing is at that path |
link | see another document | the target is gone |
anchor | see a heading | the heading was renamed or removed |
command | run make x or npm run x | the manifest no longer declares it |
symbol | a function, class or method by name | it was defined when the line was written and is defined nowhere now |
A symbol finding needs proof from git: git blame finds the commit that
wrote the document line, and at that commit a source file defined exactly
that name. A backticked word the code never defined is not reported.
A clean run does not mean your documentation is true. It means every reference repowise could resolve, resolved. It has no opinion on prose.
Reading a finding
Each finding carries the line as written, the heading trail above it, what was checked, and a confidence (stored from 0.4 up). When the tree says where the reference went, it also suggests a replacement:
| Suggestion | When |
|---|---|
| Became a package | src/cli.py is gone and src/cli/ exists |
| Renamed in git | git records the file moving, and the new path exists |
| Similar heading or target | one declared heading or make / npm run target is a close match |
| Renamed symbol | the defining file now defines one close name of the same kind |
A suggestion is evidence for you to check. It never raises a finding's confidence.
Keeping a reference on purpose
Mark it in the document, so the choice travels with the text:
<!-- repowise-drift-ignore -->
Create `src/plugins/my_plugin.py` with the following contents.The marker covers its own line and the next. Put
<!-- repowise-drift-ignore-file --> anywhere in a document to silence all
of it. Silenced references are still counted.
In CI
repowise doc-drift --check reads the working tree with no index and
exits 1 on a finding at or above 0.7 confidence. Use a baseline or
--since auto on a repository that already has drift. Setup is on
Gates in CI, every flag on
repowise doc-drift.
Where else it shows up
get_health(include=["doc_drift"])for an agent. Seeget_health.get_context(targets=["src/auth.py"], include=["doc_drift"])answers the reverse question: which documents name this file, and whether they already drift. Ask before you move or rename something. Seeget_context.- The Code Health page in the dashboard.
- The VS Code extension's Problems panel, for Markdown files.