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 pnpx at exact versions pinned in tool_pins.py, so every cerberus release measures with the same tools everywhere; pnpm 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 default lives in cerberus.toml: shared source ownership under [source], and check settings under their bite's table ([justfile], [pytest], [jscpd], …). The bundled file is the single home of the defaults; missing required keys are errors. A repo adjusts them with a root cerberus.toml, overlaid key by key. An explicit --config PATH stands in for that repository file. Lists replace the corresponding default list.

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.

Shared source ownership

[source]
production_roots = ["apps/*", "packages/*", "infra"]
test_files = [
    "**/tests/**",
    "**/__tests__/**",
    "**/*.test.*",
    "**/*.spec.*",
    "**/test_*.py",
    "**/*_test.py",
    "**/conftest.py",
]

Production roots are repository-relative directory globs; their descendants belong to production, including source assets, build configuration, and deployment infrastructure. Test-file globs take precedence even inside a production root. * matches one path segment and ** spans directories. Files outside both selections are other maintained files, such as development tooling. These conventions apply independently of which bites are enabled.

Knip intersects this ownership with registered JavaScript workspaces; a standalone root package remains production. Pyrefly requires coverage of production and test Python source, including flat infra/deploy.py and deeply nested roots. It reports a production root's src subtree when the file lives there. Both checks consume the same classification; [knip].prod_workspaces and [pyrefly].prod_workspaces must be replaced by [source].production_roots, with conflicting lists reconciled by the repository owner.

Other tools can consume the public API without scanning files or invoking the CLI:

from pathlib import Path
from cerberus import load_source_scope

scope = load_source_scope(Path("/path/to/repository"))
scope.is_production_file("infra/deploy.py")  # True with bundled defaults
scope.is_test_file("apps/widget/tests/widget.test.tsx")  # True
scope.find_production_root("apps/widget/src/widget.tsx")  # "apps/widget"

load_source_scope reads the defaults and repository overlay. The returned SourceScope classifies repository-relative POSIX paths without filesystem access; the caller owns file discovery and any generated-file filtering.

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.

Shared architecture policy

Declare application contract keepers and allowed workspace dependencies in [architecture]. ESLint reads the same declaration; see its configuration examples.

TypeScript seam checks use ESLint's resolved imports. The retired cli_ts_test_seam, lib_ts_test_seam, and fixture_roles_ts IDs report migration guidance when encountered in overlays. Their package policies are covered by the focused export, ownership, and reference checks.

Worker traversal covers first-party static imports and literal dynamic imports. Computed imports, third-party modules, and framework-provided entries are reported as static coverage limits; production bundle validation covers those boundaries. Side-effect detection checks top-level registration statements and cannot prove an arbitrary dependency graph pure.