[PR #7334] fix(cli): state each option default once in help output #7819

Open
opened 2026-11-05 01:47:54 +00:00 by bsakaguchi · 0 comments
Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/7334
Author: @akushonkamen
Created: 10/26/2026
Status: 🔄 Open

Base: main ← Head: fix/7306-duplicate-help-defaults


📝 Commits (3)

  • f600732 fix(cli): state each option default once in help output
  • 68f9017 style(cli): apply oxfmt to captureCommands
  • 645f693 chore: retrigger ci after main recovery

📊 Changes

4 files changed (+67 additions, -6 deletions)

View changed files

📝 src/cli/binaryDiagnosticsCommands.ts (+6 -6)
📝 src/cli/captureCommands.ts (+9 -0)
📝 src/cli/signalCommands.ts (+6 -0)
➕ tests/boundary/cli/helpDefaultAnnotation.test.ts (+46 -0)

📄 Description

Summary

Six CLI commands printed an option default twice in --help output: once as prose inside the option description and once as the automatic (default: …) annotation the help renderer appends when the option has a schema default. This removes the redundant prose from the CLI-layer option descriptions so each default is stated exactly once, and adds a boundary test covering all six commands.

Fixes #7306

Problem and expected behavior

Smallest trigger: node scripts/rea.mjs inspect-byte-entropy --help prints --block-size <number> Power-of-two block size from 256 to 65536 bytes (default 4096) (default: 4096). The violated invariant is that an option's help presents its default once. Both annotations carried the same value in the same units, so the defect was purely presentational redundancy across 11 entries in six commands: inspect-byte-entropy (--block-size, --offset), inspect-devicetree (four --max-* options), decode-signal-recording (--line_offset), inspect-packet-capture (--match_offset), inspect-packet-fields (--kind, --offset), and inspect-signal-decoders (--offset).

Change and scope

The redundant text lived in two layers:

  • src/cli/binaryDiagnosticsCommands.ts — the CLI-layer .describe() overrides themselves appended (default N); those clauses are dropped.
  • src/cli/captureCommands.ts and src/cli/signalCommands.ts — the commands spread shared domain-schema shapes, whose descriptions say "default 0" / "defaults to protocols". Following the existing pattern in those files (the CLI-layer limit overrides), the affected fields are re-described at the CLI wiring layer with the default mention removed.

The domain schemas and the MCP tool contracts are intentionally unchanged, so machine-readable schema defaults and advertised tool descriptions are untouched. No help content beyond the duplicated default wording is altered.

Contribution scope: not applicable; ordinary presentation fix within the existing CLI surface.

Contract and boundary impact

  • Semantic owner and earliest changed stage: CLI help presentation (transport/projection layer); consumers are human CLI readers only.
  • Contribution scope fit and linked maintainer decision: not applicable.
  • CLI and MCP/tool-catalog contract: CLI help text only; MCP tool descriptions, input schemas and defaults unchanged. Generated catalogs are unaffected (verified: no artifact/catalog files changed).
  • Provider, bridge, target-format, or platform compatibility: none.
  • Evidence, artifact, provenance, or reconstruction contract: not applicable.
  • Target selection, authority, upstream behavior, and cleanup details: not applicable.
  • Generated metadata: none; no build outputs committed.

Expected effects: documentation or usability only; no target interaction.

  • Documentation or usability only; no target interaction.

Evidence and regression coverage

  • Tests added or updated: tests/boundary/cli/helpDefaultAnnotation.test.ts runs --help for the six affected commands and asserts that no help line restates the automatic (default: …) annotation's value in its description (matching (default X), default X, or defaults to X prose before the automatic annotation).
  • Base reproduction or other evidence: on base revision 077de9259 the new test fails with exactly the reported lines, e.g. --block-size <number> Power-of-two block size from 256 to 65536 bytes (default 4096) (default: 4096) and --offset <number> Window start as a decimal file byte offset (default 0) (default: 0); after the fix it passes.
  • User-visible CLI/MCP output: inspect-byte-entropy --help now shows --block-size <number> Power-of-two block size from 256 to 65536 bytes (default: 4096); the same single-annotation presentation applies to the other ten entries.
  • Remaining proof gaps: the test enumerates the six commands from the issue, not a complete catalog audit; other commands could carry similar wording but none were reported.

Boundary regressions: not applicable (no boundary or lifecycle behavior changed).

Validation performed

  • npx vitest run tests/boundary/cli/helpDefaultAnnotation.test.ts — red on base (failed with the two byte-entropy duplicate lines and the equivalent duplicates in the other five commands), green after the fix.
  • npx vitest run tests/boundary/cli/ — 1198 passed; 33 failures in 11 files are pre-existing environment issues on this machine (local Node is 24.21.0 while supported_runtime requires ^24.22.1, and IDA/Hopper/provider probes are absent); none touch the six affected commands or help rendering.
  • node scripts/rea.mjs <command> --help for the six commands against a local build — all exit 0 with each default shown once.

Compatibility, safety, and release

  • Breaking changes or migration steps: none; help text only.
  • Real Hopper/Ghidra, browser, or OS coverage: not applicable.
  • Package or release metadata impact: none.
  • Security, privacy, process, or containment review: not applicable; no target interaction.

Author readiness

Human owner: @akushonkamen

  • I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work.
  • I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps.
  • I declare this PR ready for initial maintainer review.

Before merge

  • This PR addresses a concrete problem or an agreed enhancement.
  • Material scope and authority questions are resolved, and any required maintainer scope decision covers the final diff.
  • The PR has one focused outcome and the title follows type(scope): outcome.
  • Related issue is linked, or the reason for not linking one is stated above.
  • Tests cover changed observable behavior and meaningful failure paths.
  • Owning docs, contracts, and generated metadata are updated where needed.
  • User-visible CLI/MCP changes include representative output.
  • I checked the final diff for secrets, unrelated cleanup, and unsupported claims.

🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.

## 📋 Pull Request Information **Original PR:** https://github.com/morluto/rea/pull/7334 **Author:** [@akushonkamen](https://github.com/akushonkamen) **Created:** 10/26/2026 **Status:** 🔄 Open **Base:** `main` ← **Head:** `fix/7306-duplicate-help-defaults` --- ### 📝 Commits (3) - [`f600732`](https://github.com/morluto/rea/commit/f6007329d13723184b7662b8e582591181b15463) fix(cli): state each option default once in help output - [`68f9017`](https://github.com/morluto/rea/commit/68f9017786fff43db014e2c999e34ce007c2b2ca) style(cli): apply oxfmt to captureCommands - [`645f693`](https://github.com/morluto/rea/commit/645f693e422b1dcaf0f6ebd69cf566af446e87f5) chore: retrigger ci after main recovery ### 📊 Changes **4 files changed** (+67 additions, -6 deletions) <details> <summary>View changed files</summary> 📝 `src/cli/binaryDiagnosticsCommands.ts` (+6 -6) 📝 `src/cli/captureCommands.ts` (+9 -0) 📝 `src/cli/signalCommands.ts` (+6 -0) ➕ `tests/boundary/cli/helpDefaultAnnotation.test.ts` (+46 -0) </details> ### 📄 Description ## Summary Six CLI commands printed an option default twice in `--help` output: once as prose inside the option description and once as the automatic `(default: …)` annotation the help renderer appends when the option has a schema default. This removes the redundant prose from the CLI-layer option descriptions so each default is stated exactly once, and adds a boundary test covering all six commands. Fixes #7306 ## Problem and expected behavior Smallest trigger: `node scripts/rea.mjs inspect-byte-entropy --help` prints `--block-size <number> Power-of-two block size from 256 to 65536 bytes (default 4096) (default: 4096)`. The violated invariant is that an option's help presents its default once. Both annotations carried the same value in the same units, so the defect was purely presentational redundancy across 11 entries in six commands: `inspect-byte-entropy` (`--block-size`, `--offset`), `inspect-devicetree` (four `--max-*` options), `decode-signal-recording` (`--line_offset`), `inspect-packet-capture` (`--match_offset`), `inspect-packet-fields` (`--kind`, `--offset`), and `inspect-signal-decoders` (`--offset`). ## Change and scope The redundant text lived in two layers: - `src/cli/binaryDiagnosticsCommands.ts` — the CLI-layer `.describe()` overrides themselves appended `(default N)`; those clauses are dropped. - `src/cli/captureCommands.ts` and `src/cli/signalCommands.ts` — the commands spread shared domain-schema shapes, whose descriptions say "default 0" / "defaults to protocols". Following the existing pattern in those files (the CLI-layer `limit` overrides), the affected fields are re-described at the CLI wiring layer with the default mention removed. The domain schemas and the MCP tool contracts are intentionally unchanged, so machine-readable schema defaults and advertised tool descriptions are untouched. No help content beyond the duplicated default wording is altered. Contribution scope: not applicable; ordinary presentation fix within the existing CLI surface. ## Contract and boundary impact - Semantic owner and earliest changed stage: CLI help presentation (transport/projection layer); consumers are human CLI readers only. - Contribution scope fit and linked maintainer decision: not applicable. - CLI and MCP/tool-catalog contract: CLI help text only; MCP tool descriptions, input schemas and defaults unchanged. Generated catalogs are unaffected (verified: no artifact/catalog files changed). - Provider, bridge, target-format, or platform compatibility: none. - Evidence, artifact, provenance, or reconstruction contract: not applicable. - Target selection, authority, upstream behavior, and cleanup details: not applicable. - Generated metadata: none; no build outputs committed. Expected effects: documentation or usability only; no target interaction. - [x] Documentation or usability only; no target interaction. ## Evidence and regression coverage - Tests added or updated: `tests/boundary/cli/helpDefaultAnnotation.test.ts` runs `--help` for the six affected commands and asserts that no help line restates the automatic `(default: …)` annotation's value in its description (matching `(default X)`, `default X`, or `defaults to X` prose before the automatic annotation). - Base reproduction or other evidence: on base revision `077de9259` the new test fails with exactly the reported lines, e.g. `--block-size <number> Power-of-two block size from 256 to 65536 bytes (default 4096) (default: 4096)` and `--offset <number> Window start as a decimal file byte offset (default 0) (default: 0)`; after the fix it passes. - User-visible CLI/MCP output: `inspect-byte-entropy --help` now shows `--block-size <number> Power-of-two block size from 256 to 65536 bytes (default: 4096)`; the same single-annotation presentation applies to the other ten entries. - Remaining proof gaps: the test enumerates the six commands from the issue, not a complete catalog audit; other commands could carry similar wording but none were reported. Boundary regressions: not applicable (no boundary or lifecycle behavior changed). ## Validation performed - `npx vitest run tests/boundary/cli/helpDefaultAnnotation.test.ts` — red on base (failed with the two byte-entropy duplicate lines and the equivalent duplicates in the other five commands), green after the fix. - `npx vitest run tests/boundary/cli/` — 1198 passed; 33 failures in 11 files are pre-existing environment issues on this machine (local Node is 24.21.0 while `supported_runtime` requires `^24.22.1`, and IDA/Hopper/provider probes are absent); none touch the six affected commands or help rendering. - `node scripts/rea.mjs <command> --help` for the six commands against a local build — all exit 0 with each default shown once. ## Compatibility, safety, and release - Breaking changes or migration steps: none; help text only. - Real Hopper/Ghidra, browser, or OS coverage: not applicable. - Package or release metadata impact: none. - Security, privacy, process, or containment review: not applicable; no target interaction. ## Author readiness Human owner: @akushonkamen - [x] I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work. - [x] I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps. - [x] I declare this PR ready for initial maintainer review. ## Before merge - [x] This PR addresses a concrete problem or an agreed enhancement. - [x] Material scope and authority questions are resolved, and any required maintainer scope decision covers the final diff. - [x] The PR has one focused outcome and the title follows `type(scope): outcome`. - [x] Related issue is linked, or the reason for not linking one is stated above. - [x] Tests cover changed observable behavior and meaningful failure paths. - [x] Owning docs, contracts, and generated metadata are updated where needed. - [x] User-visible CLI/MCP changes include representative output. - [x] I checked the final diff for secrets, unrelated cleanup, and unsupported claims. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
morluto/rea#7819
No description provided.