Catch documentation drift after a code change

A source change can leave documentation looking perfectly healthy. The page still builds. Its links still work. The instructions may even describe the previous behavior accurately.

The missing signal is that someone needs to look again.

Dewey's source maps declare the files they describe. An explicit review records the current document and covered source. When either changes, dewey check asks for another review. It identifies a maintenance task; it does not decide whether a changed line makes the prose false. How Dewey checks documentation

Here is a complete small example using @deweydocs/dewey 0.5.1.

Make the behavior easy to inspect

Create a directory with this package.json:

{  "name": "retry-demo",  "private": true,  "type": "module",  "scripts": { "demo": "bun src/index.ts" }}

Create src/retry.ts:

export const maxAttempts = 3

Create src/index.ts:

import { maxAttempts } from './retry.ts'console.log(`Maximum attempts: ${maxAttempts}`)

Run bun run demo. It prints Maximum attempts: 3. This is a local example that prints a value; it does not make network requests or implement retries.

Install and initialize Dewey:

bun add -d @deweydocs/dewey@0.5.1bunx dewey init \  --purpose "Print the retry budget" \  --rule "Keep the retry budget in src/retry.ts"

The initial bunx dewey check --json exits with status 1. It reports draft documents and a map that has never been reviewed. Creating files has not completed the documentation work.

Establish the reviewed baseline

Replace docs/src.agent.md with a map grounded in the two source files:

---kind: maptitle: Retry implementationcovers: [src/*]---# Retry implementation## Files- `src/index.ts` imports and prints the retry budget.- `src/retry.ts` exports `maxAttempts`, currently 3.## Data flowThe entry point reads the exported constant and prints it to stdout.## Invariants and trapsThe budget is defined in one source file. Printing the budget does not perform a network request.

Finish the generated docs/quickstart.md as well. Keep kind: guide, remove draft: true, and explain that a reader with Bun can run bun run demo from the project root and expect Maximum attempts: 3.

After checking those statements against the source, run:

bunx dewey review docs/src.agent.mdbunx dewey buildbunx dewey check --json

The completed example returns:

{ "passed": true, "issues": [] }

The review command stores the reviewed state in .dewey/reviews.json. Commit that file with the documentation and .dewey/project.json so later checks use the same baseline. Review workflow

Change the code, then rebuild

Change the constant in src/retry.ts from 3 to 5. Run the demo again. It now prints Maximum attempts: 5, while both documents still describe three attempts.

Run:

bunx dewey buildbunx dewey check --json

Build succeeds. Check exits 1 and reports:

{  "code": "REVIEW_REQUIRED",  "path": "docs/src.agent.md",  "message": "Covered files moved since the last review (changed: src/retry.ts)",  "fix": "Re-read the covered code, correct the doc, then run dewey review docs/src.agent.md."}

dewey build can succeed while dewey check exits 1. The build does not record a review.

Correct the explanation before acknowledging it

Read the change. Update the map's stated value and the quickstart's expected output from three to five. Then record the review and rebuild:

bunx dewey review docs/src.agent.mdbunx dewey buildbunx dewey check --json

The example passes again.

The quickstart needed an edit because it named the old value. The check identified the covered map; it did not automatically discover every sentence affected by the change. Follow the behavior through related guides and references during review. If a guide needs its own source-based review signal, it can declare covers and receive an explicit review too.

Put the signal in CI

Once the repository has a reviewed baseline, run these commands in CI:

bunx dewey buildbunx dewey check --json > dewey-check.json

Check exits 1 when it finds an issue, while the report remains available for inspection. Keep dewey review out of the automatic build step. Running it without reviewing the document would erase the signal you wanted.

Dewey also checks references and generated output. It does not run the commands in your documentation. Run bun run demo and compare the printed line with the guide. The CLI reference documents the check and review commands used above.