DriftFence

Make sure your README doesn't lie.

DriftFence is a TypeScript Node.js CLI that catches outdated README and docs commands, package scripts, file references, and env var references before they reach users.

Install

Install from npm:

npm install -D driftfence

Usage

Check the current project:

npx driftfence check

Check a specific project directory:

npx driftfence check ./path/to/project

Example Output

The local clean demo exits with code 0:

npm run demo:clean

The local drift demo intentionally contains documentation drift and exits with code 1:

npm run demo:drift

Example output from the drift fixture:

DriftFence found documentation drift.

Package scripts:
- `npm run build` in README.md references missing package.json script `build`.

File paths:
- `docs/missing.md` referenced in README.md does not exist.
- `docs/advanced.md` referenced in docs/config.md does not exist.

Env vars:
- `DATABASE_URL` is used in src/index.ts but missing from .env.example.

4 issues found.

MVP Checks

DriftFence checks README.md and docs/**/*.{md,mdx} for documentation drift.

Current checks:

• package script references
• file path references
• local Markdown links and images
• env var references in Markdown and MDX docs
• env var usage in source files

Relative Markdown links are resolved from the document containing them. Links starting with / are resolved from the project root.

Package script references include commands like:

npm run build
npm test
npm start
pnpm build
yarn build

Env var checks currently support references like:

API_URL
DATABASE_URL
VITE_API_URL

and source usages like:

process.env.API_URL
import.meta.env.VITE_API_URL

Configuration

Configuration is optional. Create driftfence.config.json at the project root to suppress known intentional drift.

{
  "ignorePaths": ["docs/generated.md"],
  "ignoreEnvVars": ["DATABASE_URL"],
  "ignorePackageScripts": ["start"]
}

ignorePaths may match the original normalized destination, the destination without its query or fragment, or the resolved project-relative path. ignoreEnvVars and ignorePackageScripts match names exactly.

Exit Codes

DriftFence uses stable CLI exit codes:

• 0 — no documentation drift found
• 1 — documentation drift found
• 2 — invalid project directory or CLI usage error

Ignoring intentional examples

Use ignore blocks when docs intentionally show fake paths, broken commands, fake env vars, or sample DriftFence output.

<!-- driftfence-ignore-start -->

```sh
npm run missing-script
```

See `docs/missing.md`.
Set `DATABASE_URL`.

<!-- driftfence-ignore-end -->

Keep ignore blocks narrow so real setup instructions are still checked.

Roadmap

• GitHub Action
• changed-files mode
• richer source analysis

AI

AI features are not included in the MVP.

DriftFence is deterministic-first: it checks concrete references in docs and code instead of guessing.