Dev toolbox
Checks and their tiers: QA.md. This page: the tools behind them and their gotchas.
Every tool explains itself: uv run <tool> guide, and guide tune before changing a threshold.
Source: aesop toolbox.
Fresh clone
uv sync
uv run madoqua install && git checkout hooks/pre-commit # core.hooksPath is local config; install overwrites our shim
Commit hook (hooks/pre-commit)
| staged | runs | blocks on |
|---|---|---|
.py / .pyi |
madoqua fix: ruff check --fix, ruff format (re-staged) |
— |
.py / .pyi |
madoqua check: ruff check, ty check (staged only), biston, zorilla, gerenuk run |
any failure |
.md under content/, docs/, scaffold/, or root *.md |
build (links, frontmatter) + tag/scaffold tests |
broken link, bad YAML, unknown tag |
~0.3 s each. Never --no-verify / MADOQUA_SKIP past a check that's telling the truth.
Security lint is ruff S (no bandit); tests/** ignores S101/S105/S106.
Other commands
| command | for |
|---|---|
uv run poe fix |
format + autofix everything |
uv run poe check-all |
everything incl. dead code (vulture), unused deps (deptry) |
BASE_URL= uv run build && python -m http.server -d site |
local preview, root-relative links |
uv run tyf find/refs/list/calls <sym> |
symbol lookup; use instead of grep for definitions/references |
uv run gerenuk audit <file> |
symbols nothing references |
uv run gerenuk impacted-tests |
which tests the diff reaches, and why |
uv run pycoati . --format pretty |
test-suite suspicion audit before a cleanup; never in hook/CI (runs suite 3×) |
Refresh the toolbox
uv lock --refresh --upgrade-package madoqua --upgrade-package gerenuk --upgrade-package biston --upgrade-package zorilla --upgrade-package pycoati --upgrade-package ty-find && uv sync
--refresh matters: without it uv may serve a stale index.
Gotchas
- ty is beta: prefer # ty: ignore[rule] over blanket suppression. uv run poe typecheck is repo-wide; the hook isn't.
- gerenuk diffs the working tree vs origin/main: unstaged edits count; touching pyproject.toml/uv.lock runs the full suite. --base HEAD scopes to the commit.
- ty-find index goes stale after the hook's ruff format. Tell: tyf refs lists only the definition, or gerenuk selected is empty. Fix: uv run tyf daemon restart.
- ruff format can wrap a line and move a trailing # zorilla: ignore off the flagged line.