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
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.