DocFresh is a local-first CLI that checks whether README and docs examples still match the repository they describe.
It scans markdown files for local links, file references, package script commands, README package metadata, and explicitly marked smoke examples. It does not call hosted services, phone home, or run arbitrary commands by default.
DocFresh is not published to npm yet. Install the current CLI from a source checkout:
git clone https://github.com/rogerchappel/docfresh.git
cd docfresh
npm ci
npm run build
npm pack
npm install -g ./rogerchappel-docfresh-0.1.0.tgz
docfresh --helpTo run it without a global install, use the built entry point:
node dist/cli.js --helpCheck the current repository:
docfresh checkCheck another local repository and print JSON:
docfresh check --root fixtures/valid-docs --format jsonRun opted-in smoke examples:
docfresh check --root fixtures/valid-docs --smokeThe repository's own maintained-document gate is npm run self:check. It
targets the product and tutorial documents, excluding promotional and
deliberately stale demonstration material.
Run a copy-pasteable fixture demo that builds the CLI and captures both text and JSON reports:
bash examples/check-valid-docs-demo.shSmoke commands only run when the fenced block is explicitly marked:
```sh docfresh: smoke
node --version
```- Broken local markdown links such as
[Guide](docs/missing.md). - Backticked file references such as
src/index.ts. Paths beginning with./or../resolve from the Markdown file; all other paths resolve from the repository root. Extensionless owner/project identifiers are ignored when they do not match an existing root path. - Documented package commands such as
npm run buildorpnpm check. - Basic README install and usage coverage for package repositories.
- Failing commands in fenced blocks marked with
docfresh: smokewhen--smokeis enabled.
Text output is optimized for terminal review:
docfresh check --root fixtures/stale-docsJSON output is stable enough for scripts and agents:
docfresh check --root fixtures/stale-docs --format jsonDocFresh exits with 0 when no error findings are present and 1 when documentation drift is found.
Generate pass/fail JSON reports from the checked-in fixtures:
bash demo/run-json-drift-demo.shThe script writes .docfresh-demo/valid-docs.json and
.docfresh-demo/stale-docs.json so reviewers can inspect both sides of the
drift signal. See JSON Drift Report Demo
for the walkthrough.
npm run check
npm test
npm run build
npm run smoke
npm run package:smoke
bash scripts/validate.shexamples/basicpasses.examples/staleintentionally fails.bash examples/pre-pr-markdown-gate.shchecks one README in fresh and stale fixtures and verifies JSON gate output.fixtures/valid-docs,fixtures/stale-docs, andfixtures/smoke-failback the automated tests.demo/run-docfresh-basic.shruns a short README freshness demo and verifies the JSON report for the passing fixture.bash examples/run-docfresh-demo.shruns a fixture-backed freshness demo and checks a JSON report.
Run the fixture-backed demo to capture passing, stale, JSON, and smoke-check outputs:
bash demo/readme-smoke-check.shSee docs/tutorials/readme-smoke-gate.md for a pull request workflow that starts with regular docs drift checks and adds opted-in smoke commands.
For a fixture-backed demo that writes both a clean JSON report and a stale text report, run:
bash demo/readme-drift-smoke.shSee the README drift demo for a walkthrough script and promotion-safe talking points.
Run a passing fixture and capture text and JSON reports:
bash examples/check-valid-docs-demo.shRun the stale-docs fixture and confirm DocFresh reports review-worthy drift:
bash demo/stale-docs-report.shCompare a clean README fixture with a thin README that needs install and usage metadata:
bash demo/readme-readiness-gate.shSee docs/tutorials/readme-readiness-gate.md for a pre-release docs review workflow.
Capture the expected failure path for a stale package script and broken local references:
bash demo/package-script-reference-sweep.shSee docs/tutorials/package-script-reference-sweep.md for the walkthrough and docs/promo/package-script-reference-social-hooks.md for promotion-safe hooks.
For promotion or screencast prep, see
docs/promo/stale-docs-video-brief.md.
For a runnable CI-style drift check, see CI Docs Drift Check:
bash demo/ci-docs-drift.shPromotion-ready hooks for that CI demo live in
docs/promo/ci-docs-drift-social-hooks.md.
Launch-positioning notes across the stale-docs, package-script, and CI drift
demos live in
docs/promo/docs-drift-launch-notes.md.
For a pre-PR demo that writes both passing and stale-docs reports to a temporary directory:
npm run build
bash demo/run-docs-sweep.shSee docs/tutorials/pre-pr-docs-sweep.md for the walkthrough and docs/promo/social-hooks.md for grounded promotion copy.
For a short screencast outline of the same flow, see
docs/promo/pre-pr-docs-sweep-video-brief.md.
Inspired by markdown link checkers, README smoke tests, and docs-as-tests practices. Reframed for local developer-tool repos and agent-generated documentation.
See CONTRIBUTING.md. Keep changes local-first, fixture-backed, and free of telemetry.
See SECURITY.md. Do not include secrets in fixtures, examples, tests, or issue reports.
Run the same checks expected before opening or cutting a release:
npm run check
npm run test
npm run build
npm run smoke
npm run package:smoke
npm run release:checkUse npm run package:smoke to create the package tarball, confirm it contains
the CLI/runtime files and required documentation assets, install it in an
isolated temporary prefix, and invoke docfresh --help.
Use Node.js 20 or newer. Run these checks before opening a PR:
npm run build
npm run check
npm test
npm run smoke
npm run package:smoke
npm run release:checkMIT
docfresh is a local-first helper for preparing reviewable evidence. It does not replace human review, live system validation, or project-specific policy checks, and generated output should be inspected before use in release or operational decisions.