doc-drift-check 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-05-15
+
+### Added
+
+- Initial release.
+- Three drift classes: stale file paths, stale npm scripts, broken relative markdown links.
+- Fenced code block skipping (``` and ~~~).
+- Per-file ignore marker (`<!-- doc-drift: ignore -->` within first N header lines).
+- Per-run existence cache.
+- Programmatic API (`checkDocs`) and CLI (`doc-drift-check`).
+- Zero runtime dependencies; requires Node `>=22`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Norm Anderson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,183 @@
+# doc-drift-check
+
+Detect drift between markdown documentation and the code it describes. Zero runtime dependencies, Node 22+.
+
+## What it does
+
+Scans markdown files for three classes of stale reference and fails if any are broken:
+
+1. **File paths** — backticked tokens like `` `src/foo.js` `` that point to files no longer in the repo.
+2. **npm scripts** — backticked tokens like `` `npm run build` `` whose script name is missing from `package.json#scripts`.
+3. **Relative markdown links** — `[text](path)` and `![alt](src)` whose target file does not exist.
+
+Built for agent-centric docs (AGENTS.md, ARCHITECTURE.md, runbooks) that promise specific files and commands to autonomous tooling — and rot the moment anything is renamed.
+
+## Install
+
+```sh
+npm i -D doc-drift-check
+```
+
+Requires Node `>=22` (uses native `fs.glob`).
+
+## Quick start
+
+Create `doc-drift.config.js` in your repo root:
+
+```js
+export default {
+  cwd: process.cwd(),
+  files: [
+    'AGENTS.md',
+    'ARCHITECTURE.md',
+    'docs/runbooks/**/*.md',
+  ],
+  checks: {
+    paths: {
+      pattern: /`(src\/[a-z0-9-]+(?:\/[a-z0-9-]+)*\.(?:js|cjs|mjs))`/g,
+    },
+    scripts: {
+      pattern: /`npm run ([a-z0-9:_-]+)`/g,
+      registry: 'package.json#scripts',
+    },
+    links: { enabled: true },
+  },
+};
+```
+
+Run:
+
+```sh
+npx doc-drift-check
+```
+
+Exit codes: `0` clean, `1` drift detected, `2` usage/config error.
+
+## Configuration reference
+
+| Field | Type | Default | Purpose |
+|-------|------|---------|---------|
+| `cwd` | `string` \| `URL` | `process.cwd()` | Root for path resolution. |
+| `files` | `string[]` | _(required)_ | Plain paths or globs (`*`, `?`, `**`, `{a,b}`). |
+| `checks.paths.pattern` | `RegExp` | _(none)_ | Global regex with one capture group for the path. |
+| `checks.paths.resolveFrom` | `string` | `cwd` | Override root for path existence. |
+| `checks.scripts.pattern` | `RegExp` | _(none)_ | Global regex with one capture group for the script name. |
+| `checks.scripts.registry` | `Set`, `string`, `array`, or `() => Set` | _(required if scripts enabled)_ | Source of valid script names. String form `'package.json#<key>'` reads JSON keys. |
+| `checks.links.enabled` | `boolean` | `true` if `links` present | Toggle markdown link check. |
+| `ignore.marker` | `string` | `<!-- doc-drift: ignore -->` | Per-file skip marker. |
+| `ignore.headerLines` | `number` | `3` | How many top lines to scan for the marker. |
+
+## Drift classes
+
+### File paths
+
+Useful for AGENTS.md sections like "modules live in `src/...`". The default pattern (configurable per repo) catches lowercase `src/foo/bar.js`-style references. Resolves relative to `resolveFrom` (default cwd).
+
+### npm scripts
+
+Catches `` `npm run build` `` references whose script name is gone from `package.json`. Registry can be:
+- a string `'package.json#scripts'` (reads JSON keys),
+- a `Set<string>` (literal list),
+- an array (coerced to Set),
+- a `() => Set | Promise<Set>` (computed at runtime).
+
+### Markdown links
+
+Standard `[text](href)` and `![alt](src)` syntax. Skips:
+- absolute URLs (any `scheme:` prefix)
+- bare anchors (`#section`)
+
+Strips `#anchor` and `?query` before existence check. Repo-absolute links (`/docs/foo.md`) resolve from `cwd`; relative links resolve from the containing file's directory.
+
+## Fenced code blocks
+
+Lines inside ` ``` ` or `~~~` fences are skipped to keep example code from producing false positives. Fence delimiters of length 4+ behave the same.
+
+## Per-file opt-out
+
+Place the marker within the first `headerLines` of a file to skip it entirely:
+
+```md
+<!-- doc-drift: ignore -->
+
+# Some doc
+```
+
+Useful for design notes that intentionally reference paths that don't exist (yet).
+
+## Programmatic API
+
+```js
+import { checkDocs } from 'doc-drift-check';
+
+const result = await checkDocs({
+  cwd: process.cwd(),
+  files: ['AGENTS.md'],
+  checks: { links: { enabled: true } },
+});
+
+if (!result.ok) {
+  for (const err of result.errors) {
+    console.error(`${err.file}:${err.line}: ${err.kind}: ${err.token}`);
+  }
+  process.exit(1);
+}
+```
+
+`result` shape:
+
+```ts
+{
+  ok: boolean;
+  errors: Array<{
+    file: string;
+    line: number;
+    kind: 'missing-file' | 'missing-script' | 'broken-link';
+    token: string;
+    message: string;
+  }>;
+  filesScanned: number;
+}
+```
+
+## CI integration
+
+```yml
+- uses: actions/setup-node@v4
+  with:
+    node-version: 22
+- run: npm ci
+- run: npx doc-drift-check
+```
+
+Or chain into an existing validate script:
+
+```json
+{
+  "scripts": {
+    "docs:check": "doc-drift-check",
+    "validate": "npm run lint && npm run docs:check && npm test"
+  }
+}
+```
+
+## vs `markdown-link-check`
+
+| Concern | `markdown-link-check` | `doc-drift-check` |
+|---------|----------------------|-------------------|
+| Runtime deps | 40+ transitive | 0 |
+| Known CVEs | 13 at time of writing | 0 |
+| Drift classes | Links only | Paths, scripts, links |
+| Configurable patterns | Limited | Full regex per class |
+| External URL fetch | Yes (network flake) | No (deferred to v0.2) |
+| Per-file opt-out | No | Yes |
+
+`doc-drift-check` does not check live URLs. That's a separate problem with different failure modes (rate limits, transient errors) — outside the scope of "your repo no longer matches its docs."
+
+## Stability
+
+`0.x` releases follow semver but the surface is small enough that minor versions may add config keys. Breaking config changes will bump major. The CLI exit codes (`0`/`1`/`2`) are stable.
+
+## License
+
+MIT

package/bin/doc-drift-check.js

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+import process from 'node:process';
+import { checkDocs } from '../src/index.js';
+import { loadConfig, ConfigError } from '../src/config/load.js';
+import { walk } from '../src/walker.js';
+
+const USAGE = `Usage:
+  doc-drift-check [--config <path>] [--list-files] [--help]
+
+Options:
+  --config <path>   path to config file (default: ./doc-drift.config.js)
+  --list-files      print resolved file list (debug) and exit 0
+  --help, -h        show this help
+
+Exit codes:
+  0  clean
+  1  drift detected
+  2  usage / config error
+`;
+
+function parseArgs(argv) {
+  const out = { config: null, listFiles: false, help: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--help' || a === '-h') out.help = true;
+    else if (a === '--list-files') out.listFiles = true;
+    else if (a === '--config') {
+      out.config = argv[++i];
+      if (!out.config) {
+        process.stderr.write('--config requires a path\n');
+        process.exit(2);
+      }
+    } else if (a.startsWith('--config=')) {
+      out.config = a.slice('--config='.length);
+    } else {
+      process.stderr.write(`unknown argument: ${a}\n`);
+      process.exit(2);
+    }
+  }
+  return out;
+}
+
+function format(err) {
+  return `${err.file}:${err.line}: ${err.kind}: ${err.token} — ${err.message}`;
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+
+  let cfg;
+  try {
+    cfg = await loadConfig(args.config, process.cwd());
+  } catch (err) {
+    process.stderr.write(`${err.message}\n`);
+    return err.exitCode ?? 2;
+  }
+
+  if (args.listFiles) {
+    const files = await walk(cfg.files ?? [], cfg.cwd ?? process.cwd());
+    for (const f of files) process.stdout.write(`${f}\n`);
+    return 0;
+  }
+
+  let result;
+  try {
+    result = await checkDocs(cfg);
+  } catch (err) {
+    process.stderr.write(`${err.message}\n`);
+    return err.exitCode ?? 2;
+  }
+
+  if (!result.ok) {
+    for (const e of result.errors) process.stderr.write(`${format(e)}\n`);
+    process.stderr.write(`\n${result.errors.length} drift error(s) across ${result.filesScanned} file(s)\n`);
+    return 1;
+  }
+
+  process.stdout.write(`doc-drift-check: ${result.filesScanned} file(s) clean\n`);
+  return 0;
+}
+
+main().then(
+  (code) => process.exit(code),
+  (err) => {
+    process.stderr.write(`unexpected: ${err.stack ?? err.message}\n`);
+    process.exit(2);
+  },
+);

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "doc-drift-check",
+  "version": "0.1.0",
+  "description": "Detect drift between markdown docs and the code they describe. Zero runtime dependencies.",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "bin": {
+    "doc-drift-check": "bin/doc-drift-check.js"
+  },
+  "scripts": {
+    "test": "node --test \"test/**/*.test.js\"",
+    "test:coverage": "node --test --experimental-test-coverage \"test/**/*.test.js\""
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "src/",
+    "bin/",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "keywords": [
+    "markdown",
+    "documentation",
+    "lint",
+    "doc-drift",
+    "agents.md",
+    "ci"
+  ],
+  "author": "Norm Anderson",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/blytzynorm/doc-drift-check.git"
+  },
+  "bugs": {
+    "url": "https://github.com/blytzynorm/doc-drift-check/issues"
+  },
+  "homepage": "https://github.com/blytzynorm/doc-drift-check#readme"
+}

package/src/cache.js

@@ -0,0 +1,21 @@
+import { access } from 'node:fs/promises';
+
+export function createCache() {
+  const map = new Map();
+  return {
+    async exists(absPath) {
+      if (map.has(absPath)) return map.get(absPath);
+      let ok = true;
+      try {
+        await access(absPath);
+      } catch {
+        ok = false;
+      }
+      map.set(absPath, ok);
+      return ok;
+    },
+    get size() {
+      return map.size;
+    },
+  };
+}

package/src/checks/links.js

@@ -0,0 +1,37 @@
+import path from 'node:path';
+import { KINDS } from '../util.js';
+
+const LINK_RE = /!?\[[^\]]*\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g;
+const SCHEME_RE = /^[a-z][a-z0-9+.-]*:/i;
+
+export async function checkLinks(ctx) {
+  const { line, lineNumber, filePath, absFilePath, cache, cwd } = ctx;
+  const fileDir = path.dirname(absFilePath ?? filePath);
+  const findings = [];
+
+  for (const m of line.matchAll(LINK_RE)) {
+    const href = m[1];
+    if (!href) continue;
+    if (SCHEME_RE.test(href)) continue;
+    if (href.startsWith('#')) continue;
+
+    const cleanHref = href.replace(/[#?].*$/, '');
+    if (!cleanHref) continue;
+
+    const absTarget = cleanHref.startsWith('/')
+      ? path.join(cwd, cleanHref)
+      : path.resolve(fileDir, cleanHref);
+
+    const ok = await cache.exists(absTarget);
+    if (!ok) {
+      findings.push({
+        file: filePath,
+        line: lineNumber,
+        kind: KINDS.BROKEN_LINK,
+        token: href,
+        message: `broken markdown link: ${href}`,
+      });
+    }
+  }
+  return findings;
+}

package/src/checks/paths.js

@@ -0,0 +1,28 @@
+import path from 'node:path';
+import { KINDS, clonePattern } from '../util.js';
+
+export async function checkPaths(ctx) {
+  const { line, lineNumber, filePath, opts, cache, cwd } = ctx;
+  if (!opts?.pattern) return [];
+
+  const pattern = clonePattern(opts.pattern);
+  const resolveFrom = opts.resolveFrom ?? cwd;
+  const findings = [];
+
+  for (const m of line.matchAll(pattern)) {
+    const token = m[1];
+    if (!token) continue;
+    const abs = path.resolve(resolveFrom, token);
+    const ok = await cache.exists(abs);
+    if (!ok) {
+      findings.push({
+        file: filePath,
+        line: lineNumber,
+        kind: KINDS.MISSING_FILE,
+        token,
+        message: `referenced file does not exist: ${token}`,
+      });
+    }
+  }
+  return findings;
+}

package/src/checks/scripts.js

@@ -0,0 +1,32 @@
+import { KINDS, clonePattern, resolveRegistry } from '../util.js';
+
+const resolvedRegistry = new WeakMap();
+
+export async function checkScripts(ctx) {
+  const { line, lineNumber, filePath, opts, cwd } = ctx;
+  if (!opts?.pattern || opts.registry == null) return [];
+
+  let registry = resolvedRegistry.get(opts);
+  if (!registry) {
+    registry = await resolveRegistry(opts.registry, cwd);
+    resolvedRegistry.set(opts, registry);
+  }
+
+  const pattern = clonePattern(opts.pattern);
+  const findings = [];
+
+  for (const m of line.matchAll(pattern)) {
+    const token = m[1];
+    if (!token) continue;
+    if (!registry.has(token)) {
+      findings.push({
+        file: filePath,
+        line: lineNumber,
+        kind: KINDS.MISSING_SCRIPT,
+        token,
+        message: `referenced script does not exist: ${token}`,
+      });
+    }
+  }
+  return findings;
+}

package/src/config/load.js

@@ -0,0 +1,68 @@
+import path from 'node:path';
+import { access } from 'node:fs/promises';
+import { pathToFileURL } from 'node:url';
+
+const DEFAULT_NAMES = ['doc-drift.config.js', 'doc-drift.config.mjs'];
+
+class ConfigError extends Error {
+  constructor(message) {
+    super(message);
+    this.exitCode = 2;
+    this.name = 'ConfigError';
+  }
+}
+
+async function fileExists(p) {
+  try {
+    await access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function loadConfig(input, cwd = process.cwd()) {
+  if (input && typeof input === 'object' && !Array.isArray(input)) {
+    return normalize(input);
+  }
+
+  let resolved;
+  if (typeof input === 'string') {
+    resolved = path.resolve(cwd, input);
+    if (!(await fileExists(resolved))) {
+      throw new ConfigError(`config file not found: ${resolved}`);
+    }
+  } else {
+    for (const name of DEFAULT_NAMES) {
+      const candidate = path.resolve(cwd, name);
+      if (await fileExists(candidate)) {
+        resolved = candidate;
+        break;
+      }
+    }
+    if (!resolved) {
+      throw new ConfigError(
+        `no doc-drift.config.js found in ${cwd} (pass --config <path> or create one)`,
+      );
+    }
+  }
+
+  let mod;
+  try {
+    mod = await import(pathToFileURL(resolved).href);
+  } catch (err) {
+    throw new ConfigError(`failed to import config ${resolved}: ${err.message}`);
+  }
+
+  const cfg = mod.default ?? mod.config ?? mod;
+  if (!cfg || typeof cfg !== 'object') {
+    throw new ConfigError(`config at ${resolved} did not export an object`);
+  }
+  return normalize(cfg);
+}
+
+function normalize(cfg) {
+  return { ...cfg };
+}
+
+export { ConfigError };

package/src/index.js

@@ -0,0 +1,94 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { walk } from './walker.js';
+import { iterLines } from './parser.js';
+import { createCache } from './cache.js';
+import { checkPaths } from './checks/paths.js';
+import { checkScripts } from './checks/scripts.js';
+import { checkLinks } from './checks/links.js';
+import { resolveCwd } from './util.js';
+
+const DEFAULT_IGNORE_MARKER = '<!-- doc-drift: ignore -->';
+const DEFAULT_HEADER_LINES = 3;
+
+function hasIgnoreMarker(content, marker, headerLines) {
+  let pos = 0;
+  for (let i = 0; i < headerLines; i++) {
+    const next = content.indexOf('\n', pos);
+    const line = next === -1 ? content.slice(pos) : content.slice(pos, next);
+    if (line.includes(marker)) return true;
+    if (next === -1) break;
+    pos = next + 1;
+  }
+  return false;
+}
+
+export async function checkDocs(options = {}) {
+  if (!options.files || !Array.isArray(options.files) || options.files.length === 0) {
+    const err = new Error('checkDocs: options.files must be a non-empty array');
+    err.exitCode = 2;
+    throw err;
+  }
+
+  const cwd = resolveCwd(options.cwd);
+  const ignore = options.ignore ?? {};
+  const marker = ignore.marker ?? DEFAULT_IGNORE_MARKER;
+  const headerLines = ignore.headerLines ?? DEFAULT_HEADER_LINES;
+
+  const checks = options.checks ?? {};
+  const cache = createCache();
+  const files = await walk(options.files, cwd);
+
+  const errors = [];
+  let filesScanned = 0;
+
+  for (const filePath of files) {
+    let content;
+    try {
+      content = await readFile(filePath, 'utf8');
+    } catch (err) {
+      const e = new Error(`failed to read ${filePath}: ${err.message}`);
+      e.exitCode = 2;
+      throw e;
+    }
+
+    filesScanned++;
+    if (hasIgnoreMarker(content, marker, headerLines)) continue;
+
+    const relFile = path.relative(cwd, filePath) || filePath;
+    const ctx = {
+      filePath: relFile,
+      absFilePath: filePath,
+      cache,
+      cwd,
+      line: '',
+      lineNumber: 0,
+      opts: null,
+    };
+
+    for (const { line, lineNumber, skip } of iterLines(content)) {
+      if (skip) continue;
+      ctx.line = line;
+      ctx.lineNumber = lineNumber;
+
+      if (checks.paths) {
+        ctx.opts = checks.paths;
+        errors.push(...(await checkPaths(ctx)));
+      }
+      if (checks.scripts) {
+        ctx.opts = checks.scripts;
+        errors.push(...(await checkScripts(ctx)));
+      }
+      if (checks.links && checks.links.enabled !== false) {
+        ctx.opts = checks.links;
+        errors.push(...(await checkLinks(ctx)));
+      }
+    }
+  }
+
+  return {
+    ok: errors.length === 0,
+    errors,
+    filesScanned,
+  };
+}

package/src/parser.js

@@ -0,0 +1,29 @@
+const BACKTICK_FENCE = /^`{3,}/;
+const TILDE_FENCE = /^~{3,}/;
+
+export function* iterLines(content) {
+  const text = content.replace(/\r\n/g, '\n');
+  const lines = text.split('\n');
+  if (lines.length > 0 && lines[lines.length - 1] === '') {
+    lines.pop();
+  }
+
+  let inBackTick = false;
+  let inTilde = false;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const trimmed = line.replace(/^\s+/, '');
+    let toggledThisLine = false;
+
+    if (!inTilde && BACKTICK_FENCE.test(trimmed)) {
+      inBackTick = !inBackTick;
+      toggledThisLine = true;
+    } else if (!inBackTick && TILDE_FENCE.test(trimmed)) {
+      inTilde = !inTilde;
+      toggledThisLine = true;
+    }
+
+    yield { line, lineNumber: i + 1, skip: inBackTick || inTilde || toggledThisLine };
+  }
+}

package/src/util.js

@@ -0,0 +1,38 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const KINDS = Object.freeze({
+  MISSING_FILE: 'missing-file',
+  MISSING_SCRIPT: 'missing-script',
+  BROKEN_LINK: 'broken-link',
+});
+
+export function resolveCwd(cwd) {
+  if (!cwd) return process.cwd();
+  if (cwd instanceof URL) return fileURLToPath(cwd);
+  if (typeof cwd === 'string' && cwd.startsWith('file://')) return fileURLToPath(cwd);
+  return cwd;
+}
+
+export function clonePattern(rx) {
+  const flags = rx.flags.includes('g') ? rx.flags : rx.flags + 'g';
+  return new RegExp(rx.source, flags);
+}
+
+export async function resolveRegistry(spec, cwd = process.cwd()) {
+  if (spec instanceof Set) return spec;
+  if (typeof spec === 'function') {
+    const r = await spec();
+    return r instanceof Set ? r : new Set(r);
+  }
+  if (Array.isArray(spec)) return new Set(spec);
+  if (typeof spec === 'string') {
+    const [file, key = 'scripts'] = spec.split('#');
+    const abs = path.resolve(cwd, file);
+    const raw = await readFile(abs, 'utf8');
+    const json = JSON.parse(raw);
+    return new Set(Object.keys(json[key] ?? {}));
+  }
+  return new Set();
+}

package/src/walker.js

@@ -0,0 +1,22 @@
+import { glob } from 'node:fs/promises';
+import path from 'node:path';
+import { resolveCwd } from './util.js';
+
+const GLOB_RE = /[*?[\]{}]/;
+
+export async function walk(files, cwd) {
+  const root = resolveCwd(cwd);
+  const out = new Set();
+
+  for (const entry of files) {
+    if (GLOB_RE.test(entry)) {
+      for await (const match of glob(entry, { cwd: root })) {
+        out.add(path.resolve(root, match));
+      }
+    } else {
+      out.add(path.resolve(root, entry));
+    }
+  }
+
+  return Array.from(out);
+}