0.5.0: three ports — comment-stripped presence guards, unknown-flag refusal, pipe-proof verdict lines - #4
Merged
Merged
Conversation
…efuse unknown flags, verdicts a pipe cannot eat
Three artifacts, each generalizing a failure that recurred across an agent
fleet, each carrying the house contract: one pure file, declared failure
posture, limits pinned as tested expectations, a where-it-stops section.
lib/strip-comments.mjs — ANY "string X still appears in file Y" check strips
comments first, because a drift guard grepping raw source was satisfied by
the JSX comment EXPLAINING the removal it should have caught. A presence
guard has both failure directions silent (needle survives in a comment =
false green; needle eaten from code = false red), so this is a scanner, not
two regexes: strings, template text, ${} substitutions, and regex literals
are tracked. The header keeps the correction where the first cut had the
exact bug it prevents — a quote in a regex character class desynchronised it
and 215 comments survived stripping. Shell (#) variant included; heredocs
scanned like code, erring toward FOUND, pinned.
lib/known-flags.mjs — an unrecognized option is a usage error, not a
default. A dropped flag returns ok:true with the flag ignored, which is how
a documented-but-unimplemented flag "worked" three times and a typo'd scope
flag shrank a 1,192-file sweep to 2 and printed PASS. Asserts over raw argv
(deliberately not a parser); prints every offender; exit accepts a function
OR a number, because two authors read the docs as a number and the
function-only contract crashed on the one path whose job is a clean refusal.
lib/result-line.mjs — every verdict-emitting check prints one terminal
greppable RESULT: line, because `cmd | tail; echo exit:$?` prints tail's
exit, and that class hit four independent lanes in one day against a
correct, starred rule saying not to do it. Documentation is not the remedy;
it is what already existed. Unmapped exits render UNKNOWN rather than a
guessed verdict; fd:2 is mandatory on --json scripts (a verdict line after a
JSON document breaks the parser — pinned); nesting is declared by the
parent, sanitized and bounded.
26 new tests, three of which pin LIMITS rather than features. 214 pass.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CkTF1JryMkGt4Qx2A2vHEh
…ywords take both sides' additions
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
1 participant
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.
The three clean ports from the 0.5.0 queue — the ones that needed no invented generalization. The other three candidates (sweep-declaration, can-it-go-red, dismissal-history) each hardcode an internal data shape and stay unported until something outside the fleet wants them; generalizing an API with one consumer is guessing at the second consumer's needs.
Each file carries the house contract: one pure file, a declared failure posture, limits pinned as tested expectations (three of the 26 new tests pin LIMITS, not features), and a where-it-stops section.
lib/strip-comments.mjs${}substitutions, regex literals. The header keeps the correction where the first cut had the exact bug it prevents.lib/known-flags.mjs--flaglanded in the args bag, was never read, and the call returnedok:true— a documented-but-unimplemented flag "worked" three times; a typo'd scope flag shrank a 1,192-file sweep to 2 files and printed PASS.exittakes a function or a number (the function-only contract crashed on the one path whose job is a clean refusal)lib/result-line.mjscmd | tail -N; echo exit:$?prints tail's exit — four independent lanes in one day, against a correct, indexed, starred rule saying not to do it. Documentation is not the remedy; it is what already existed.UNKNOWN(a wrong verdict travels further than a missing one); the emitter swallows its own errors;{fd:2}mandatory on--json(pinned)Also in the diff: three README table rows, three Coverage-and-limits sections, version 0.3.0 → 0.5.0 (0.4.0 is PR #1's bump; if merge order inverts this is a one-line fixup).
214 tests pass. Branched from
main; independent of #1/#2/#3 except for adjacent-line proximity in the README table (adds rows; #2 edits a different row).🤖 Generated with Claude Code