feat(ratchet): add comprehensive --help output for all subcommands#45
feat(ratchet): add comprehensive --help output for all subcommands#45ALIPHATICHYD wants to merge 2 commits into
Conversation
|
@coderabbitai review |
✅ Action performedReview finished.
|
ℹ️ Recent review info⚙️ Run configurationConfiguration used: Repository UI Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (1)
📝 WalkthroughWalkthroughThe ratchet.py CLI updates Unicode glyphs used in human-readable reports and replaces parse_args() with an expanded ArgumentParser that adds multi-line descriptions, epilogs, RawDescriptionHelpFormatter, and richer per-subcommand help and examples. ChangesCLI Help and Output Refinement
🎯 4 (Complex) | ⏱️ ~45 minutes
🚥 Pre-merge checks | ✅ 3 | ❌ 2❌ Failed checks (2 warnings)
✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@tools/flow-install/skills/_shared/ratchet.py`:
- Around line 348-376: The code references args.verbose in the score output
block but the comprehensive score subparser that builds args for the "score"
command doesn't define --verbose, causing an AttributeError; update the score
subparser (the code that creates the "score" argparse subparser used by the
score command) to add a --verbose / -v boolean flag so args.verbose exists
(mirror the name used in the output block), ensuring the verbose flag is stored
as a boolean on args and can be checked in the printing logic.
- Around line 896-932: The code contains a duplicate call to
parser.add_subparsers() creating a second subparsers group (the block that
defines sc, gt, sn, ev, dc, st) which will raise "cannot have multiple subparser
arguments"; remove this entire duplicate block (the second
parser.add_subparsers(...) and the subsequent sc/gt/sn/ev/dc/st add_parser calls
and their add_argument lines) so only the original subparsers definition
remains, ensuring references to the parser and subparsers variables elsewhere
are unchanged.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 313a46c4-b6fd-46a0-8248-9a7d863d5b93
📒 Files selected for processing (1)
tools/flow-install/skills/_shared/ratchet.py
There was a problem hiding this comment.
Caution
Inline review comments failed to post. This is likely due to GitHub's internal server error or limits when posting large numbers of comments. If you are seeing this consistently it is likely a permissions issue. Please check "Moderation" -> "Code review limits" under your organization settings.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@tools/flow-install/skills/_shared/ratchet.py`:
- Around line 348-376: The code references args.verbose in the score output
block but the comprehensive score subparser that builds args for the "score"
command doesn't define --verbose, causing an AttributeError; update the score
subparser (the code that creates the "score" argparse subparser used by the
score command) to add a --verbose / -v boolean flag so args.verbose exists
(mirror the name used in the output block), ensuring the verbose flag is stored
as a boolean on args and can be checked in the printing logic.
- Around line 896-932: The code contains a duplicate call to
parser.add_subparsers() creating a second subparsers group (the block that
defines sc, gt, sn, ev, dc, st) which will raise "cannot have multiple subparser
arguments"; remove this entire duplicate block (the second
parser.add_subparsers(...) and the subsequent sc/gt/sn/ev/dc/st add_parser calls
and their add_argument lines) so only the original subparsers definition
remains, ensuring references to the parser and subparsers variables elsewhere
are unchanged.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 313a46c4-b6fd-46a0-8248-9a7d863d5b93
📒 Files selected for processing (1)
tools/flow-install/skills/_shared/ratchet.py
🛑 Comments failed to post (2)
tools/flow-install/skills/_shared/ratchet.py (2)
348-376:
⚠️ Potential issue | 🔴 Critical | ⚡ Quick win
args.verbosewill raiseAttributeError—--verbosenot defined in thescoresubparser.The comprehensive
scoresubparser (lines 706-726) defines--skill,--layer, and--json, but not--verbose. This code block referencesargs.verbose, which will fail at runtime.Add the
--verboseargument to the comprehensivescoresubparser:Proposed fix: add --verbose to the comprehensive score subparser
Add this after line 726:
sc.add_argument( "--json", action="store_true", help="Output result as JSON instead of human-readable text.", ) + sc.add_argument( + "--verbose", + action="store_true", + help="Print a per-variable breakdown (raw value, weight, weighted contribution).", + )🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@tools/flow-install/skills/_shared/ratchet.py` around lines 348 - 376, The code references args.verbose in the score output block but the comprehensive score subparser that builds args for the "score" command doesn't define --verbose, causing an AttributeError; update the score subparser (the code that creates the "score" argparse subparser used by the score command) to add a --verbose / -v boolean flag so args.verbose exists (mirror the name used in the output block), ensuring the verbose flag is stored as a boolean on args and can be checked in the printing logic.
896-932:
⚠️ Potential issue | 🔴 Critical | ⚡ Quick winDuplicate
add_subparsers()call will crash at runtime.
parser.add_subparsers()is called twice on the same parser (first at line 674, again at line 896). Argparse raises"error: cannot have multiple subparser arguments"whenparse_args()executes.This block appears to be leftover code from before the comprehensive help was added. Remove it entirely.
Proposed fix: delete the duplicate block
st.add_argument( "--json", action="store_true", help="Output result as JSON.", ) - subparsers = parser.add_subparsers(dest="command", required=True) - - # score - sc = subparsers.add_parser("score", help="Compute composite score") - sc.add_argument("--skill", required=True) - sc.add_argument("--layer", type=int, default=1, choices=[1, 2]) - sc.add_argument("--json", action="store_true") - sc.add_argument( - "--verbose", - action="store_true", - help="Print a per-variable breakdown (raw value, weight, weighted contribution).", - ) - - # gates - gt = subparsers.add_parser("gates", help="Check hard constraint gates") - gt.add_argument("--skill", required=True) - gt.add_argument("--json", action="store_true") - - # snapshot - sn = subparsers.add_parser("snapshot", help="Snapshot skill state before improvement") - sn.add_argument("--skill", required=True) - - # evaluate - ev = subparsers.add_parser("evaluate", help="Evaluate improvement impact") - ev.add_argument("--skill", required=True) - ev.add_argument("--window", type=int, required=True, help="Number of post-improvement runs to evaluate") - ev.add_argument("--json", action="store_true") - - # decide - dc = subparsers.add_parser("decide", help="Make keep/revert decision") - dc.add_argument("--skill", required=True) - dc.add_argument("--json", action="store_true") - - # status - st = subparsers.add_parser("status", help="Show ratchet state") - st.add_argument("--skill", required=True) - st.add_argument("--json", action="store_true") return parser.parse_args()📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.st.add_argument("--skill", required=True) st.add_argument("--json", action="store_true") return parser.parse_args()🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@tools/flow-install/skills/_shared/ratchet.py` around lines 896 - 932, The code contains a duplicate call to parser.add_subparsers() creating a second subparsers group (the block that defines sc, gt, sn, ev, dc, st) which will raise "cannot have multiple subparser arguments"; remove this entire duplicate block (the second parser.add_subparsers(...) and the subsequent sc/gt/sn/ev/dc/st add_parser calls and their add_argument lines) so only the original subparsers definition remains, ensuring references to the parser and subparsers variables elsewhere are unchanged.
2 participants
Summary
Adds comprehensive
--helpoutput toratchet.pycovering all sixsubcommands (
score,gates,snapshot,evaluate,decide,status)with descriptions and usage examples.
Closes #28
Changes
tools/flow-install/skills/_shared/ratchet.py—parse_args()only:ArgumentParserwith full description (metric formula,gates list, typical cycle walkthrough) and
RawDescriptionHelpFormatterso multi-line text and examples survive formatting
description=(what it does), anepilog=(at least one usage example), and
help=on every argumentparse_args()is touched; all argument names,types, defaults, and
required=flags are preserved exactlyAcceptance Criteria
python3 ratchet.py --helpshows all subcommands with descriptions--helpwith argument detailsTesting
This change is purely additive to CLI metadata. The CI harness
(
run-ci-verify.sh,run-flow-install-eval.sh) does not invokeratchet.pydirectly, so all existing checks pass unchanged.Verified locally:
python3 -c "import ast; ast.parse(open('tools/flow-install/skills/_shared/ratchet.py').read()); print('OK')" python3 ratchet.py --help python3 ratchet.py score --help python3 ratchet.py gates --help python3 ratchet.py snapshot --help python3 ratchet.py evaluate --help python3 ratchet.py decide --help python3 ratchet.py status --helpSummary by CodeRabbit
Documentation
Style
Bug Fix / Change