Repository navigation
refactor(issue-fix): slim cli.py to 1,630 LOC (-305) and eliminate Any - #9267
loopx-agent wants to merge 1 commit into
Conversation
Extract shared argparse option-group builders and per-subcommand handlers with lookup-table dispatch for PR gate reconciliation and error rendering in loopx/capabilities/issue_fix/cli.py. Reduce the module from 1,935 to 1,630 lines (-305 net LOC) and replace all 5 Any annotations (any_count: 5 -> 0, dict_any_count: 0) with narrow Mapping[str, object], dict[str, object], and typed _SubParsersAction annotations while preserving byte-for-byte CLI --help output and behavior parity. Signed-off-by: LoopX Agent <337587101+loopx-agent@users.noreply.github.com>
loopx-agent
left a comment
There was a problem hiding this comment.
Reviewer: model_agent · Gemini · Google · self_reported
Approval conclusion (author-owned PR; GitHub blocks formal self-approval)
动机 / Motivation
在日常维护与扩展 loopx issue-fix 命令行子命令时,研发人员与能力代理需要频繁阅读并修改 loopx/capabilities/issue_fix/cli.py。修改前,该文件长达 1,935 行,包含 699 行的参数注册函数与 987 行的命令分派巨型函数,多分支共享局部作用域导致 ledger_path 变量重定义与 registry_path/origin 类型未收窄,存在 5 处 Any 注解并在单文件严格类型检查下报 20 个错误;修改后,无需拆出新模块即可收敛至 1,630 行、清零全部 Any 与类型报错。可观测结果为代码行数从 1,935 行净减 305 行至 1,630 行,Any 计数从 5 降至 0(dict[str, Any] 为 0),单文件 mypy 错误从 20 个降为 0,同时全部 21 条 --help 输出与运行期 JSON/Markdown 响应保持字节级一致。本次重构边界明确不拆分新的兄弟模块、不修改 module_metric_baseline.json 基线配置,也不改动任何已有 CLI 参数、帮助文本或持久化账本契约。
改动思路 / Approach
架构上将 CLI 传输层与命令解析保留在 loopx/capabilities/issue_fix/cli.py 内,所有领域决策与持久化契约继续由现有能力子模块负责。具体做法是在参数注册侧提取 _add_subparser、_add_repo_issue_url_args、_add_fetch_metadata_args、_add_domain_state_args 与 _add_required_goal_repo_args 等共享参数组构建器,并用循环合并完全同构的 acceptance-fixture 与 repo-branch-fixture 注册;在命令分派侧将 987 行的 handle_issue_fix_command 拆分为单用途命令处理器与 _PR_GATE_RECONCILE_COMMANDS、_ERROR_RENDERERS 查找表,辅以 _optional_json_object、_ensure_single_stdin、_resolve_provider_path、_resolve_ledger_path、_set_write_skipped_reason 与 _set_writeback_performed 消除重复模板与深层缩进。本 PR 边界为单文件代码减法与零 Any 改造,完成后无需后续拆分子模块或跟进补丁。
| 指标 | 基线 (c563a473d8) |
当前精确头 (b2bff475c6) |
变化 |
|---|---|---|---|
总行数 (lines) |
1,935 | 1,630 | -305 |
Any 计数 (any_count) |
5 | 0 | -5 |
dict[str, Any] (dict_any_count) |
0 | 0 | 0 |
mypy 单文件诊断 |
20 errors | 0 errors | 清零 |
具体改动 / Changes
本 PR 无书面规格文档(spec_basis: no_spec,spec_source: none),以对 origin/main(c563a473d845af6f23f9245c3af242ad505c393b)行为 100% 等价的单文件减法与零 Any 重构需求为评审基准。
关键代码讲解
register_issue_fix_commands(cli.py)及共享参数组构建器(_add_repo_issue_url_args、_add_domain_state_args等):按基线完全一致的顺序注册issue-fix及其 20 个子命令,保留SNAPSHOT_SCHEMA_VERSION在metrics帮助文本中的 f-string 引用,保证所有--help输出和test_wire_schema_version_owners.py审计不发生偏移。_handle_pr_lifecycle(cli.py)与_execute_pr_lifecycle_transition(cli.py):将 264 行的 PR 生命周期分支独立成两个强类型函数,通过_resolve_origin_request与registry_path/ledger_path显式判空收窄,在写入账本前保留origin_request并由handle_issue_fix_command统一剥离后输出,清除了原本的ledger_path重定义和空值告警。_resolve_outcome_delivery_evidence(cli.py)与_handle_outcome(cli.py):用Payload(dict[str, object])和Mapping[str, object]替换全部Any标注,并在提交证据校验与_comparable_delivery_evidence幂等比对分支中显式校验dict类型,消除 6 处mypy联合类型与解包报错。handle_issue_fix_command(cli.py)及查找表_PR_GATE_RECONCILE_COMMANDS(cli.py)、_ERROR_RENDERERS(cli.py):主入口缩减至 118 行;错误渲染表严格保持基线差异(pr-lifecycle与pr-gate-reconcile在异常路径走生命周期 Markdown 渲染,其余未列名命令回落至render_issue_fix_acceptance_loop_markdown),确保异常输出与返回码完全一致。
对主干的风险 / Risks
本次改动仅涉及 loopx/capabilities/issue_fix/cli.py,核心风险集中在参数顺序/默认值偏移、异常优先级与多 - 标准输入冲突提示变更、以及测试通过模块属性打桩(monkeypatch)的符号缺失(如 collect_public_github_candidate_preflight_input、_load_json_object、_MAX_INLINE_JSON_CHARS、_materialize_goal_reviewer_notification_lifecycle 与 BARE_SHA256_PATTERN)。实测对照表明:所有必需模块级符号与导出别名均原样保留;21/21 条 --help 与基线逐字节一致;8 组覆盖正/负路径的基线对比 CLI 调用(含冲突参数与双标准输入错误)返回码与 stdout SHA-256 摘要完全一致。当前验证记录如下:
ruff check loopx/capabilities/issue_fix/cli.py: PASSmypy(17-file 严格配置)与mypy --follow-imports=silent loopx/capabilities/issue_fix/cli.py: PASS(0 errors)pytest(issue_fix全量能力/控制面/架构测试、test_wire_schema_version_owners.py、test_content_digest_single_owner.py、test_maintainability_ratchet.py、test_cli_entrypoint.py、test_cli_stdio_utf8.py): PASS(941 passed)- CLI
--help(21/21)与基线/HEAD 执行对比(8/8)及 15 个examples/issue-fix-*-smoke.py端到端冒烟: PASS loopx check --scan-path loopx/capabilities/issue_fix/cli.py与loopx canary premerge --from-git-diff --git-diff-base origin/main: PASS(10/10 catalog canaries + 4/4 direct checks +py_compile,CQR 凭证cqr_24b68fdc0f7f07af1c0f有效)
我的整体评价 / Verdict
在精确提交 b2bff475c6ec7a860e294e9b6f247c99d5dd7793 上:long_horizon 与 user_experience 均为 preserved;visual_review 因属纯 CLI 单文件重构判定 not_applicable(reason: CLI-only single-file Python refactor in loopx/capabilities/issue_fix/cli.py with no UI or rendered presentation changes.;unverified_scope: none);未引入任何新词表或状态字段(semantic_alignment: not_applicable),无隐含默认行为或权限边界变更,且可观测语义与基线完全等价、无阻塞发现。英文简短结论:
English verdict: APPROVE — exact head b2bff47 reduces loopx/capabilities/issue_fix/cli.py from 1,935 to 1,630 lines (-305 LOC) and eliminates all 5 Any annotations with zero findings; ruff, mypy, 941 pytest cases, 21/21 --help parity checks, 8/8 base-vs-head CLI execution parity checks, 15 issue-fix CLI smokes, and canary premerge (10/10) all PASS.
Goal And Delivered Outcome
loopx/capabilities/issue_fix/cli.py(no roadmap id invented).loopx/capabilities/issue_fix/cli.pyhad grown to1,935lines withany_count: 5, centered in a 699-lineregister_issue_fix_commandsand a 987-linehandle_issue_fix_commandwith repeated argparse registration boilerplate, stdin checks, ledger path resolution, and 20 strictmypydiagnostics.loopx/capabilities/issue_fix/cli.py:1,935 -> 1,630lines (-305 net LOC),any_count: 5 -> 0,dict_any_count: 0(verified byloopx.canary.maintainability_ratchet.module_metricsandtests/canary/test_maintainability_ratchet.py).mypy --follow-imports=silent loopx/capabilities/issue_fix/cli.py:20 errors -> 0 errors.--helpparity acrossloopx issue-fix --helpand all 20 subcommand--helpoutputs (21/21exact matches) plus941passing unit/architecture tests,15/15issue-fix CLI smoke scripts, and10/10premerge catalog checks.main(single-file refactor inloopx/capabilities/issue_fix/cli.py).Author Declaration
Implemented against
origin/mainc563a473d8).<= 1,770LOC)loopx/capabilities/issue_fix/cli.py(1,935 -> 1,630,-305)tests/canary/test_maintainability_ratchet.pyAnyannotations (any_count: 5 -> 0,dict_any_count: 0)Payload,Renderer,Mapping[str, object],_SubParsersAction[argparse.ArgumentParser]uv run --extra test mypy --follow-imports=silent loopx/capabilities/issue_fix/cli.py_add_subparser,_add_repo_issue_url_args,_add_domain_state_args,_handle_*,_PR_GATE_RECONCILE_COMMANDS,_ERROR_RENDERERSuv run --extra test ruff check loopx/capabilities/issue_fix/cli.py--help, error message, ledger write, and JSON/Markdown output parityregister_issue_fix_commands,handle_issue_fix_command21/21--helpbyte-for-byte comparison,941pytest cases,15CLI smokesAGENTS.md,CLAUDE.md,CONTRIBUTING.md,.github/CODEOWNERS,loopx/capabilities/issue_fix/cli.py, and related architecture/consumer tests (test_wire_schema_version_owners.py,test_content_digest_single_owner.py,test_issue_fix_candidate_evidence.py); verifiedgit diff --statmodifies onlyloopx/capabilities/issue_fix/cli.py; ranruff,mypy,pytest,loopx check, CLI--helpparity, 15issue-fixCLI smokes, Change Quality Qualification (cqr_24b68fdc0f7f07af1c0f), andloopx canary premerge.Scope And Continuation
loopx/capabilities/issue_fix/cli.pywas modified;loopx/canary/module_metric_baseline.jsonwas left untouched and no sibling modules were added.Validation
b2bff475c6ec7a860e294e9b6f247c99d5dd7793public_fixture,syntheticstaticpasseduv run --extra test ruff check loopx/capabilities/issue_fix/cli.py->All checks passed!;uv run --extra test mypy(17-file config) ->Success: no issues found in 17 source files;uv run --extra test mypy --follow-imports=silent loopx/capabilities/issue_fix/cli.py->Success: no issues found in 1 source file.staticpassedloopx check --scan-path loopx/capabilities/issue_fix/cli.py->ok=True,errors=0,warnings=0,public boundary scan clean: 1 files.regression_paritypassedloopx.canary.maintainability_ratchet.module_metrics(Path("loopx/capabilities/issue_fix/cli.py")):lines: 1935 -> 1630,any_count: 5 -> 0,dict_any_count: 0 -> 0. Byte-for-byte comparison ofloopx issue-fix --helpand all 20 subcommand--helpoutputs againstorigin/main(21/21exact matches).unitpasseduv run --extra test pytest -q tests/capabilities/test_issue_fix_*.py tests/control_plane/test_issue_fix_*.py tests/architecture/test_issue_fix_*.py tests/architecture/test_wire_schema_version_owners.py tests/architecture/test_content_digest_single_owner.py tests/canary/test_maintainability_ratchet.py tests/test_cli_entrypoint.py tests/test_cli_stdio_utf8.py->941 passed.real_entrypointpassedexamples/issue-fix-*-smoke.pyend-to-end CLI smoke scripts (15/15ok) anduv run --extra test loopx canary premerge --from-git-diff --git-diff-base origin/main->ok=True,4/4direct checks (git diff --check+scripts/check_rfc_bilingual.py),py_compile, and10/10catalog canaries passed; CQR receiptcqr_24b68fdc0f7f07af1c0f(status: valid).pytestsweep across cross-cutting architecture tests included two unrelated pre-existing environment failures in a fresh worktree (test_source_session_registry_denial.pyflaggingexecution_preparation.pyonorigin/mainandtest_todo_consumer_host_retirement.pyrequiring a built dashboard bundle); allissue_fix,wire_schema_version_owners,content_digest_single_owner,maintainability_ratchet, CLI entrypoint/UTF-8, andcanary premergechecks passed cleanly.Frontend / Visual Evidence
Type of Change
LoopX Area
Technical Direction
loopx/capabilities/issue_fix/cli.py).Shared-authority RFC fixture impact
loopx/capabilities/issue_fix/cli.pyonly; no control-plane authority state or RFC fixtures modified).Boundary Checklist
.loopx/,.codex/goals/, and liveACTIVE_GOAL_STATE.md).python3 scripts/check_rfc_bilingual.py --base origin/main --head HEADpasses, or no paired RFC changed.none.Signed-off-bytrailer (git commit -s).