S0090-cli-exit-2: the exit-code contract cites sysexits accurately - #50
Merged
Conversation
Exit 2 was documented as EX_USAGE, and sysexits.h assigns EX_USAGE the value 64. The label sat twice in src/core/exit-codes.ts (the module's contract table and the USAGE member JSDoc, which compiles into dist/*.d.ts and renders on a consumer's hover), and README.md plus docs-content/concepts-archetype.md grounded their whole table in that header while listing 1 and 2, which it defines at neither value. Exit 2 now carries no sysexits constant and both 1 and 2 are stated as this CLI's own values. The four correct labels (EX_DATAERR 65, EX_NOINPUT 66, EX_UNAVAILABLE 69, EX_SOFTWARE 70) are untouched. No published number moved and no member of the exported EXIT map was added, removed or renamed. test/exit-code-matrix.test.ts is byte identical to its content on the base commit. test/exit-code-docs.test.ts is new: it sweeps every source file, the README and every published docs page, binds each sysexits constant to the number that surface attributes it to, and reds when the two disagree, naming the surface, the line and the code. It carries the header's own table from the cited man pages, reports a constant that table does not define rather than passing it through, asserts the premise on each side (the sweep's population, both association rules against the real map) and replays the exact text that shipped before this correction as a negative control, with a control of its own for the shapes that must stay silent.
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.
Spec:
work/specs/S0090-cli-exit-2/spec.md(umbrella).The defect
The CLI publishes an exit-code contract and grounds it in the Unix
sysexits.hheader. Under thatframing it labelled exit
2asEX_USAGE.sysexits.hassignsEX_USAGEthe value64. Adeveloper aligning their own tooling to the header therefore learned a false fact about it from our
documentation, on the surface an editor renders on hover and the surface a docs site serves.
The label sat in two places in
src/core/exit-codes.ts(the module contract table and theUSAGEmember JSDoc, which compiles into
dist/*.d.ts), andREADME.mdplusdocs-content/concepts-archetype.mdgrounded their whole table in that header while listing1and2, which it defines at neither value.What changed
2carries no sysexits constant.1and2are both stated as this CLI's own values, inthe module contract, in each of their table rows, and on both published pages.
EX_DATAERR65,EX_NOINPUT66,EX_UNAVAILABLE69,EX_SOFTWARE70) are untouched.test/exit-code-docs.test.tsis new. It sweeps the README, every source file and every publisheddocs page, binds each sysexits constant to the number that surface attributes it to through three
association rules (member doc comment, table row, nearest number on the line), and reds when the
two disagree, naming the surface, the line and the code.
What did not change
0/1/2/65/66/69/70are where they were.EXITmap was added, removed or renamed.test/exit-code-matrix.test.tsis byte identical to its content on the base commit:git diff --exit-code origin/main...HEAD -- test/exit-code-matrix.test.tsis empty.docs-content/sidebars.jsonor docs IA change.The new guard is not vacuous
Two vacuity traps have sprung in this suite before, so the guard asserts the premise on each side:
the sweep's population is asserted positive and the specific files named; both association rules are
asserted to bind the four correct labels to 65/66/69/70 against the real map; the exact text that
shipped before this correction is replayed as a negative control and must be reported; and that
control has its own control, three correct shapes that must stay silent over a population asserted
non-empty.
Checked end to end as well: restoring the three surfaces from
origin/mainwith this test in placeturns 7 of its 22 cases red, including
which are the two defect sites this change removes.
Gates
pnpm typecheck,pnpm lint,pnpm format:check,pnpm check:no-emdash(11 binary excluded, thecount CLAUDE.md records),
pnpm check:no-internal-refs,pnpm check:agent-notes,pnpm test(38 files, 690 tests) and
pnpm test:coverage(core 97.84 / 93.95 / 93.28 / 98.12, commands98.53 / 94.18 / 100 / 99.68, both above the per-directory 90 gate) all pass.
Changeset (
patch) and a[Unreleased]changelog entry are included.