Files
ersatztv/docs/decisions/records/ci/python-lint-ruff-config-committed.md
T
timothy a706784881 fix(780): lint an explicit git population — discovery-based ruff was defeatable in three ways
Re-review of the previous fix commit found the population guard did not close the
vacuity it was added for. `ruff check . --show-files` reports DISCOVERY, and an
`exclude` defeats discovery in three config scopes — including `[format]`, which
is where an appended line lands by TOML rules. Measured with 0.12.11 against a
tracked file holding an unused import, a hardcoded credential and a formatting
error (GREEN = gate silently off):

  exclude in        check .   explicit   format --check .   explicit
  top level         GREEN     red        GREEN              red
  [lint]            GREEN     red        red                red
  [format]          red       red        GREEN              red
  + force-exclude   -         GREEN      -                  red with --no-force-exclude

So both steps now pass an explicit population from
`git ls-files -z '*.py' '*.pyi' '*.ipynb'` with `--no-force-exclude`, guarded by
an empty-list arm. All five mutants above are detected; an empty population
errors. This also fixes the count-comparison's three defects in one move: it
covers `.pyi` (which the old `git ls-files '*.py'` miscounted into a false red),
tracked-but-gitignored files (a permanent false red — `git add -f` under an
ignored path is established practice here), and compensating drift that a count
comparison nets to zero.

RUF100 is now selected. The previous commit added a `# noqa: UP031` to a site the
FIRST commit had already fixed in code — a suppression suppressing nothing, in a
change whose whole premise is that suppressions must stay honest — and two more
had been dead in the tree for months. All three removed. The split is 55 fixed in
code / 17 suppressed, not 54/18.

The `git` half of `Preflight external tools` moves back ahead of the lint steps,
which now consume `git`: without it a missing git kills the step at the population
assignment under `-e`, and the step's own `::error::` never prints. The orphaned
pytest/PyYAML rationale comment goes back onto its own step.

Docs: the record's mutation paragraph called the `[format]` exclude a
mutation-construction pitfall when it was a live coverage hole — it now carries the
measured matrix instead; `mechanics:` frontmatter rewritten; "all eight S105 hits"
scoped (there are nine in the tree, one pre-existing); the defect-shapes
reproduction block now actually runs (`mkdir -p`, `;` not `&&`, a sha not `main`,
not /tmp).

Refs: #780
Decisions-Edit: yes
2026-08-21 23:44:54 +02:00

6.3 KiB

key, title, status, since, supersedes, superseded-by, rule, signals, mechanics
key title status since supersedes superseded-by rule signals mechanics
ci.python-lint-ruff-config-committed 2026-08-21 — Python lint is a committed ruff.toml enforced in CI, not the operator machine's global config (#780) active 2026-08-21 none none The repo commits `ruff.toml`, and the `script-tests` job runs `ruff check` + `ruff format --check` under a PINNED ruff over an EXPLICIT population from `git ls-files`, never `ruff check .`. Never rely on `~/.config/ruff/ruff.toml`, and never add a lint rule to the config without making the tree clean against it in the same PR. ruff · pyright · python lint · `ruff format --check` · lint passes on my machine but not yours · no repo lint config · S105 on a test stub credential · paths: `ruff.toml`, `.gitea/workflows/pr-checks.yml` · issues: #780, #773, #648, #512 Config at repo root; `.gitea/workflows/pr-checks.yml` -> `script-tests` pins `ruff==0.12.11` via pip and runs both commands ahead of the jq preflight and pytest. Population is `git ls-files -z '*.py' '*.pyi' '*.ipynb'` passed explicitly with `--no-force-exclude`, guarded by an empty-list arm; discovery-based `ruff check .` is defeated by an `exclude` in any of three config scopes. Bumping the pin is a deliberate PR because a new ruff release adds rules.

The global instructions tell every session to run ruff check, ruff format --check and pyright after touching Python. Before this, the repo enforced none of them and committed no config, so ruff fell back to whichever ~/.config/ruff/ruff.toml the operator's machine happened to have — a second machine lints this repo differently, or not at all. That is the same shape as #643/#647/#648 (a shell gate whose behaviour was a function of an untested interpreter version) and #512 (a test that passed on a fast laptop and flaked on a starved CI VM): the verdict was a property of the environment rather than of the repo.

The committed config is the operator's global one apart from per-file-ignores, which is narrowed to scripts/tests/**. That is what the tree was de-facto written against, so adopting it cost a mechanical reformat rather than a rewrite: 72 findings against 706674272, of which 55 were fixed in code (mostly by the format pass) and 17 carry a per-site # noqa with its reason inline. RUF100 is selected so those suppressions stay honest — a # noqa that stops matching anything is otherwise invisible, and three were live in the tree the moment the rule was switched on.

One exemption is directory-wide, and it is the boring one. S101 for scripts/tests/**, because a test suite asserts. S105 is deliberately NOT directory-wide. All eight of its hits among those 72 findings are stub credentials handed to the real hooks (env["ETV_GITEA_TOKEN"] = "stub"), with no true positive in the tree today (a ninth # noqa: S105 predates this and sits on a commit-message marker in decisions_validate.py). A directory blanket would give up hardcoded-credential coverage over the largest Python surface in the repo, permanently, to suppress eight known lines — and this is the only Python lint the repo runs, so nothing else would catch a real token pasted into a fixture next year. Per-site # noqa: S105 costs the same and keeps the rule live.

The population comes from git ls-files, not from ruff's discovery, and that is the load-bearing part. ruff check . reports on what it discovers, and an exclude defeats it in three different config scopes — including [format], which is where an appended line lands by TOML rules. Measured with ruff 0.12.11 against a tracked file holding an unused import, a hardcoded credential and a formatting error; GREEN means the gate was silently off:

exclude in ruff check . explicit list ruff format --check . explicit list
top level GREEN red GREEN red
[lint] GREEN red red red
[format] red red GREEN red
+ force-exclude — GREEN — red, with --no-force-exclude

Explicitly-passed paths bypass excludes; force-exclude re-enables them, which is what --no-force-exclude pins shut. The empty-list arm is the anti-vacuity check — ruff check . over no files exits 0 with a stderr warning, so an emptied population is a green gate, not a red one. Enumerating from git also covers .pyi and tracked-but-gitignored files, which discovery skips.

Both steps were witnessed red on the runner before merge, not argued to work: run 2158 job 9111 (❌ Failure - Main Lint scripts (ruff check) on an F401) and run 2164 job 9137 (❌ Failure - Main Lint scripts (ruff format --check)), each from a temporary probe commit reverted in the same PR. A second probe was needed because the first reddened check and the job stopped there, leaving format --check still never executed.

Lint runs early in the job, ahead of the jq preflight. Preflight jq version is a hard --expect tripwire; a lint step behind it stops running for as long as the jq contract is broken, under a red that names jq. Ordering is the difference between a gate that is skipped and one that is not. The git half of Preflight external tools stays ahead of the lint steps, because they consume git: without it, a missing git kills the step at the population assignment and the step's own ::error:: never prints.

pyright is deliberately NOT gated. Its only findings here are reportMissingImports for etv_client in scripts/scripted-schedules/entrypoint.py, resolvable only inside that script's deploy environment. Gating it would put a node toolchain on the git-only small lane to find nothing. Revisit when this repo grows a typed Python surface — the reason is the cost/finding ratio today, not a judgement that type checking does not belong.

The pin is the second half of the fix. An unpinned pip install ruff re-introduces exactly the divergence the config closes, one layer up: the verdict becomes a function of when the job ran. Same argument as the jq pin in the same job (ci.jq-version-contract), and the same consequence — a bump is a PR someone reads. pytest and pyyaml in the same job stay unpinned, and the asymmetry is the point rather than an oversight: a pytest release does not add assertions to your suite, a ruff release adds rules to your lint.