cerberus

Verifies repository invariants — CI workflow structure, justfile and dependency conventions, CODEOWNERS, and release-version bumps — as a per-repo linter against a checkout.

Requirements

• uv and Python 3.14

The justfile bite shells out to just, which ships with the package (via rust-just) — no separate install. The jscpd and fallow bites run their tools via bunx at exact versions pinned in tool_pins.py, so every cerberus release measures with the same tools everywhere; bunx (bun) must be on PATH.

Lint a repo

uv run cerberus            # lint the current directory
uv run cerberus PATH       # lint a checkout at PATH

Runs every bite and exits non-zero on any failure or error, so it drops into CI like any linter. Run cerberus list to see every bite, its scope, and what it verifies.

A repo switches a bite off with off = true in that bite's cerberus.toml table (see Config below); naming an off bite with --check still runs it.

Bites

The justfile baseline

Every repo's justfile must start with the line # BASELINE, carry the canonical block from baseline.just byte-for-byte, and close it with a # CUSTOM line. Everything after # CUSTOM is the repo's own (extra aliases, recipes, set/mod statements, variables). With both markers present, --fix restores a drifted baseline region and leaves the custom tail untouched; the zyplux repo's own justfile mirrors the packaged canonical, and cerberus keeps the two identical.

Config

Every bite default — required recipes and aliases, the canonical CI sequence, coverage floors, line width, sanctioned lint relaxations, the canonical rumdl config — lives in cerberus.toml, each setting under its bite's table ([justfile], [pytest], [jscpd], …). That bundled file is part of the code: it is the single home of the defaults, the loader treats a missing key as an error rather than falling back to a value hidden in source, and every bite has a table — bites with nothing to configure carry an empty one, so the file doubles as the visible index of everything cerberus checks. A repo adjusts the defaults by shipping a cerberus.toml at its root: it overlays the bundled configuration key by key, so it only names what it overrides (e.g. a stricter [jscpd] threshold). An explicit --config PATH overlays the same way, standing in for the repo's own file.

Every bite table also takes a common off key, handled by the runner: off = true removes the bite from the run entirely — no output line — and an overlay's off = false re-enables a bite the bundled defaults ship off. tool_pins_latest ships off for exactly that reason: only the repo carrying the pin source can act on it, and that repo's overlay switches it on.

zyplux_deps_latest queries npm, PyPI, and GHCR at lint time; a failed lookup is reported as an error, never a silent pass. It has no --fix — run just upgrade to catch up.

tool_pins_latest guards the jscpd/fallow pins the same way, but runs only in the repo that carries tool_pins.py — the one place a pin can be bumped. Consumer repos never see it (bundled off = true) and pick new pins up with the next cerberus release, which zyplux_deps_latest already forces them onto.