docs: record why the ruff layer stays off, and stop it failing silently - #805
Merged
Conversation
#787 shipped a deterministic lint source gated behind GRUG_LINT_EVIDENCE=ruff and it has never run. Two reasons, both measured 2026-07-31 and now recorded in the module so nobody repeats the experiment: 1. ruff IS NOT IN THE RUNTIME IMAGE. Verified against the live consumer: exec: "ruff": executable file not found in $PATH. Setting the env var alone changes nothing - every call takes the FileNotFoundError path and returns (). The comment said 'inert unless enabled', which was not the truth: it is inert, and would stay inert if enabled. 2. THE SELECTION FOUND NOTHING REAL HERE. Against services/ with the exact _SELECT/_IGNORE: 127 findings, 34 outside tests, not one confirmable true positive. S105/S106 (72) fired on NAMES - SECRET_HEADER is a header name, EXPOSED_SECRET is one of grug's own SAST rule names; 67 of 72 were in tests S608 (13) 'SQL injection' on f-strings interpolating the module constant TTL_LIVE, every user value bound via %s - correct, safe code B023 (2) real pattern, but both closures run SYNCHRONOUSLY inside the same iteration ASYNC (0) clean Default unchanged - it stays OFF, which the measurement vindicates. The B family is the only part worth revisiting; S measured 0/29 and should be dropped from _SELECT before anyone enables this. Not re-tuned here: changing the selection without a fresh measurement is how the last speculative source reached 71% of all output (#767). Also promoted the missing-binary log from info to warning. Reaching it means an operator deliberately enabled a finding source and is getting silent nothing; that deserves a line they will actually see. Claude-Session: https://claude.ai/code/session_01Weq76G5TQhR9ogo4zCK1Gd
5 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Size: XS
Why
#787 shipped a deterministic lint source gated behind
GRUG_LINT_EVIDENCE=ruff.It has never run, and I could not have known why from the code. Two reasons,
both measured today and now recorded in the module so nobody repeats the
experiment.
1.
ruffis not in the runtime imageVerified against the live consumer:
So setting the env var alone changes nothing - every call takes the
FileNotFoundErrorpath and returns(). The comment said "inert unlessGRUG_LINT_EVIDENCE=ruff", which was not the truth: it is inert, and wouldstay inert if enabled.
2. The selection found nothing real on this codebase
Run against
services/with the exact_SELECT/_IGNORE: 127 findings, 34outside tests, and not one confirmable true positive.
SECRET_HEADERis a header name,EXPOSED_SECRETis one of grug's own SAST rule names. 67 of 72 in testsTTL_LIVE, every user value bound via%s- correct, safe codeWhat changed
Documentation and one log level. The default is unchanged - it stays OFF,
which the measurement vindicates.
Promoted the missing-binary log from
infotowarning: reaching it means anoperator deliberately enabled a finding source and is getting silent nothing.
That deserves a line someone will actually see.
Acceptance criteria
Out of scope
ruffin the image. Pointless until the selection is worth running,and the measurement says it is not.
_SELECTto dropS. It measured 0/29 and should go, but changinga selection without a fresh measurement is exactly how the last speculative
source reached 71% of all output ([grug] poller_handler.handler is 2x both complexity caps - six inline copies of one best-effort pass #767). The
Bfamily is the part worthrevisiting, with numbers, as its own change.
Verification
1840 passed, 2 skippedassumed
Part of #707.