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
uvand Python 3.14
The justfile_baseline bite shells out to just, which ships with the package (via rust-just) — no separate install.
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.
| Option | Description |
|---|---|
--check NAME |
Limit to named bite(s); repeatable |
--config PATH |
Use a cerberus.toml other than the bundled |
--fix |
Auto-fix fixable problems (e.g. trailing whitespace) |
A repo opts out of specific bites with [tool.cerberus] disable = ["bite_id", ...] in its pyproject.toml.
Bites
| ID | Scope | Verifies |
|---|---|---|
justfile_baseline |
content | Canonical baseline block (byte-exact, --fixable), recipe names, aliases, check pipeline, local cerberus run, wrapped tool calls, no trailing whitespace |
zyplux_deps_latest |
content | Every @zyplux/* npm package, zyplux-* PyPI distribution, and ghcr.io/zyplux image is used at its latest release |
ci_workflow_gate |
content | ci.yml exists, exposes a ci check, runs on PRs (push to main recommended) |
ci_check_sequence |
content | ci.yml runs the canonical check sequence per stack, in the org container |
ci_cerberus_step |
content | A CI workflow runs cerberus to self-verify org invariants |
workflow_toolchain_only |
content | Workflows set up only the workspace toolchain (uv, bun), not extra tools |
pyrefly_strict |
content | All code, tests included, type-checks under strict pyrefly with no relaxations |
ruff_select_all |
content | ruff runs standalone in preview with select = ["ALL"]; relaxations stay sanctioned |
line_length_120 |
content | ruff line-length and prettier printWidth are both 120 |
rumdl_canonical_config |
content | .rumdl.toml carries the org-canonical rule config (per-repo exclude allowed) |
knip_standalone_config |
content | knip config is standalone, never inline in package.json; knip.prod.json runs the entry-exports pass and exempts exactly the repo's published npm targets |
vitest_only_runner |
content | TypeScript tests run on vitest, never bun's built-in test runner (package.json, justfile, CI) |
tsc_project_references |
content | TypeScript typecheck runs via project references (tsc -b), not a per-package fan-out |
catalog_pinned_deps |
content | Every workspace package.json dependency pins via catalog: or workspace: |
story_tests_lockstep_py |
content | tests/**/stories/*.md criteria have a matching, title-matched pytest test |
story_tests_lockstep_ts |
content | tests/**/stories/*.md criteria have a matching, title-matched vitest test |
cli_ts_test_seam |
content | CLI apps export only the root seam; story tests reach workspace code via fixture aliases |
lib_ts_test_seam |
content | Libraries export only the root seam; story tests reach workspace code via fixture aliases |
cli_py_test_seam |
content | CLI apps' story tests import only their root module or cli entry module |
lib_py_test_seam |
content | Libraries' story tests import only their root module |
release_surface_version_bump |
git-history | A published target's version is bumped whenever its release surface changes |
codeowners_coverage |
content | CODEOWNERS present and covers /.github/ |
pytest_coverage_floor |
content | pyproject.toml [tool.coverage.report] fail_under is set to at least 90% |
vitest_coverage_floor |
content | The root vitest.config.* coverage.thresholds are all set to at least 90% |
jscpd_dupes_threshold |
content | Copy-paste duplication per language stays under the configured jscpd threshold |
fallow_analyzer |
content | fallow finds no unused code, circular imports, or functions above its complexity thresholds |
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
Policy — required recipes and aliases, the canonical CI sequence — lives in cerberus.toml. Override it with --config PATH.
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.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file zyplux_cerberus-0.13.0.tar.gz.
File metadata
- Download URL: zyplux_cerberus-0.13.0.tar.gz
- Upload date:
- Size: 55.0 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
uv/0.11.28 {"installer":{"name":"uv","version":"0.11.28","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
b84c444598c44d4881053951ccf4ff23a993306dff1a99bef104ef6614e0fb16
|
|
| MD5 |
c6e2c88a923e079178ec92f5cb1ff55d
|
|
| BLAKE2b-256 |
03dba3fcea677d1363df67a7fa0d6d0db7537406758a626a86cb967c2436a109
|
File details
Details for the file zyplux_cerberus-0.13.0-py3-none-any.whl.
File metadata
- Download URL: zyplux_cerberus-0.13.0-py3-none-any.whl
- Upload date:
- Size: 82.6 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
uv/0.11.28 {"installer":{"name":"uv","version":"0.11.28","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
24d3cef455d9be0ce5bbd71b65a3d2a18abba848f0dee9d1306ffcf34cb98535
|
|
| MD5 |
bf4917434ad95b77b15f84978701294b
|
|
| BLAKE2b-256 |
3989b09133146d011019f6423b762eb154e37a9925ba5dfc711b7420a1890bff
|
