🌿 ref-audit v1.0.3 · MIT

Why this exists

In living repositories, scripts get renamed and docs don't. A README that points to scripts/sync_all.py while the script is now sync.py is silent rot: nothing crashes, everyone just wastes time. ref-audit walks a tree, extracts backticked file paths from your Markdown, and reports the ones that don't resolve.

A cited path resolves via first match: ① as-is relative to the tree root, ② relative to the citing file's directory, ③ any file anywhere in the tree whose basename matches. Everything else is reported, split into likely-real (cites a .py/.sh or a path with directories) and other (often placeholders or intentional anti-pattern warnings).

Install (pip, v1.0+)

pip install ref-audit @ git+https://mandrilly.com/git/ref-audit.git

Zero runtime dependencies — Python ≥ 3.8, standard library only.

Quick start

ref-audit .                          # scan **/*.md under .
ref-audit . --glob 'docs/*.md'       # custom selection (repeatable)
ref-audit . --json                   # machine-readable (cron-friendly)
ref-audit . --allow legacy-name.db   # always skip this basename

Honest exit codes: 0 clean · 1 unresolved refs to review · 2 usage error (bad root, no files matched).

Source

git clone https://mandrilly.com/git/ref-audit.git

9 unit tests cover clean trees, unresolved detection, basename-index fallback, placeholder/URL/glob skipping, --allow, JSON output, and error paths. This repository audits clean against itself — try ref-audit . on the clone.