src/documate/check.py
Module

check.py

check.py — documate --check: the one gate. Are the docs fresh, real, and honest?

src/documate/check.py1 documented symbols

Overview

check.py — documate --check: the one gate. Are the docs fresh, real, and honest?

Three checks behind one gate (CI and the pre-commit hook run exactly this):

  freshness  the generated tier matches what `documate` would write right now
             (regenerate in memory, diff against disk — no timestamps, no hashes)
  anchors    every `sym:` anchor in an authored page still resolves to real code
  drift      an authored page describes code that changed since --base but wasn't
             itself updated. DIRECT (the documented file changed) gates; RIPPLE
             (a dependency of the documented code changed) is advisory only.

Degrade contract: a missing graph never gates (the CLI indexes before calling in, so this only bites on exotic setups); RIPPLE never gates. Exit 1 = a doc is stale, a doc names a ghost, or a doc is lying. With --briefs the findings are additionally emitted as work-order files (see briefs) — emission never changes the exit code. All output goes through ui (rich); the logic is stdlib only.

depends on src/documate/anchors.py, src/documate/briefs.py, src/documate/core.py, src/documate/docs.py, src/documate/drift.py, src/documate/ui.py  ·  used by src/documate/cli.py, src/documate/prose.py

API

Frun(ctx: Context, base: str | None=None, briefs_dir: Path | None=None, quiet: bool=False) -> int

src/documate/check.py:30

Run all three checks against base (default: config default_base); nonzero on any gate. With briefs_dir, also emit work-order files there for the drift findings and for changed-but-undocumented symbols — never affecting the exit code. With quiet (the --ai internal re-verify) the per-check success lines stay unprinted — the caller owns the one-line verdict — while failures and advisories print as ever.