@onsager/docs-drift-check

Zero-dependency docs drift guard. It reads your Markdown docs, extracts every link/path they cite, and fails if any repo-relative target no longer resolves — so a doc can't silently rot to pointing at moved or deleted files. This is the floor rung of the docs-drift-guard methodology: the cheap, deterministic check every docs-as-code repo should run in CI.

It is intentionally not an LLM/agent check — it's plain Node, deterministic, no spend, safe as a blocking gate. Links inside code fences/inline code are ignored, so example snippets never trip it.

Install

npm i -D @onsager/docs-drift-check

Use

# fail if any internal link in these docs is dead
npx docs-drift-check 'docs/**/*.md' README.md

# also verify http(s) links over the network (slower, opt-in)
npx docs-drift-check --external 'docs/**/*.md'

Wire it into your gate — e.g. a package.json script:

{ "scripts": { "test:docs": "docs-drift-check 'docs/**/*.md' README.md" } }

or a node:test wrapper so it runs with the rest of your suite:

import { test } from "node:test";
import assert from "node:assert/strict";
import { execFileSync } from "node:child_process";

test("docs cite no dead paths", () => {
  execFileSync("docs-drift-check", ["docs/**/*.md", "README.md"], { stdio: "inherit" });
});

What it catches (and what it doesn't)

| | | |---|---| | ✅ catches | a cited file is renamed / moved / deleted (the link goes dead) | | ✅ catches (--external) | an http(s) link returns ≥ 400 or is unreachable | | ❌ does not catch | a cited file still exists but its contents drifted so the prose is now wrong |

The contents-drifted case is semantic drift — pair this floor check with the higher rungs in the docs-drift-guard skill (rule enforcement, e.g. dependency-cruiser/import-linter; and a CODEOWNERS path-triggered re-read).

Options

docs-drift-check [--external] [--json] [--root <dir>] <glob|file|dir> [...]

Exit codes: 0 clean · 1 broken links found · 2 usage error. The repo root (against which relative paths resolve) defaults to the git toplevel; override with --root.

API

import { checkDoc, expandTargets, repoRoot } from "@onsager/docs-drift-check";

License

MIT © Onsager AI