scripts/assert-file — file assertions for checks, without the nested-quoting minefield

[bluemihai]

Why

A Ringer check lives inside a JSON string, inside a shell command. Every hand-written ruby -e '...' or python3 -c '...' assertion therefore passes through JSON escaping, then shell quoting, then the target language's string parser, before its regex is even compiled.

On one day I lost four consecutive checks to that stack — and in every case the check was wrong, not the work:

• one aborted because the banned string it grepped for appeared in the explanatory comment the brief had asked the worker to write;
• two carried \" sequences that reached Ruby as a syntax error, or as a literal that could never match;
• one asserted on a notes.md belonging to a different task entirely.

A wall of red from broken checks reads as a broken system rather than a careful one, and it teaches workers to bend correct code until the grep goes quiet.

What this adds

scripts/assert-file, a small stdlib-only helper so that class of bug cannot be written again — no nested quoting, comments stripped by file type, and a non-zero exit that says which assertion failed and what it actually saw.

assert-file PATH --absent PATTERN [...]     pattern must NOT appear
assert-file PATH --contains PATTERN [...]   pattern MUST appear
assert-file PATH --count PATTERN=N          pattern appears exactly N times
assert-file PATH --before A B               A must appear before B

--strip-comments is on by default (--raw opts out), which is the fix for the first failure above: a brief that asks a worker to justify itself in a comment shouldn't hand the check a false positive. Patterns are literal by default; --regex when you mean it. --label prefixes the failure message so a multi-assertion check says which one broke.

Tests

tests/test_assert_file.py, six tests, each running the real script as a subprocess — the thing under test is the command-line contract, and asserting on an imported function would prove something no check exercises.

Covers contains/absent on one file, comment-stripping plus its --raw opt-out, exact counts, ordering (--before catches order, not mere presence), a failure message that names the pattern it could not find, and — the one that matters most for check honesty — a missing file failing rather than passing vacuously.

Full suite green on this branch: 261 passed.

🤖 Generated with Claude Code