Skip to content

refactor(issue-fix): slim cli.py to 1,630 LOC (-305) and eliminate Any - #9267

Open
loopx-agent wants to merge 1 commit into
mainfrom
codex/slim-issue-fix-cli-20261122
Open

loopx-agent wants to merge 1 commit into
mainfrom
codex/slim-issue-fix-cli-20261122

Conversation

@loopx-agent

Copy link
Copy Markdown
Collaborator

Goal And Delivered Outcome

  • Outcome basis / optional anchor: Direct maintainability & type-hygiene refactor of loopx/capabilities/issue_fix/cli.py (no roadmap id invented).
  • Goal/source and gap: loopx/capabilities/issue_fix/cli.py had grown to 1,935 lines with any_count: 5, centered in a 699-line register_issue_fix_commands and a 987-line handle_issue_fix_command with repeated argparse registration boilerplate, stdin checks, ledger path resolution, and 20 strict mypy diagnostics.
  • Observable before -> after, with the validation row that proves it:
    • loopx/capabilities/issue_fix/cli.py: 1,935 -> 1,630 lines (-305 net LOC), any_count: 5 -> 0, dict_any_count: 0 (verified by loopx.canary.maintainability_ratchet.module_metrics and tests/canary/test_maintainability_ratchet.py).
    • mypy --follow-imports=silent loopx/capabilities/issue_fix/cli.py: 20 errors -> 0 errors.
    • Byte-for-byte CLI --help parity across loopx issue-fix --help and all 20 subcommand --help outputs (21/21 exact matches) plus 941 passing unit/architecture tests, 15/15 issue-fix CLI smoke scripts, and 10/10 premerge catalog checks.
  • Issue/task and intended base: main (single-file refactor in loopx/capabilities/issue_fix/cli.py).

Author Declaration

  • Written by: model_agent (Antigravity Gemini)

Implemented against

  • Specification and revision: no written specification; the request in this PR is the basis (origin/main c563a473d8).
  • Criteria:
Criterion (spec clause) Disposition Symbol / path Test or command
Single-file net-negative LOC refactor (<= 1,770 LOC) implemented loopx/capabilities/issue_fix/cli.py (1,935 -> 1,630, -305) tests/canary/test_maintainability_ratchet.py
Eliminate all Any annotations (any_count: 5 -> 0, dict_any_count: 0) implemented Payload, Renderer, Mapping[str, object], _SubParsersAction[argparse.ArgumentParser] uv run --extra test mypy --follow-imports=silent loopx/capabilities/issue_fix/cli.py
Deduplicate argparse option groups & command handlers without sibling modules implemented _add_subparser, _add_repo_issue_url_args, _add_domain_state_args, _handle_*, _PR_GATE_RECONCILE_COMMANDS, _ERROR_RENDERERS uv run --extra test ruff check loopx/capabilities/issue_fix/cli.py
100% --help, error message, ledger write, and JSON/Markdown output parity implemented register_issue_fix_commands, handle_issue_fix_command 21/21 --help byte-for-byte comparison, 941 pytest cases, 15 CLI smokes
  • Self-check before submission: Read AGENTS.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); verified git diff --stat modifies only loopx/capabilities/issue_fix/cli.py; ran ruff, mypy, pytest, loopx check, CLI --help parity, 15 issue-fix CLI smokes, Change Quality Qualification (cqr_24b68fdc0f7f07af1c0f), and loopx canary premerge.

Scope And Continuation

  • Completed scope and remaining work: Complete within this scope. Only loopx/capabilities/issue_fix/cli.py was modified; loopx/canary/module_metric_baseline.json was left untouched and no sibling modules were added.
  • Slice boundary / successor: N/A — standalone behavior-preserving refactoring PR.

Validation

  • Tested revision: b2bff475c6ec7a860e294e9b6f247c99d5dd7793
  • Run state: finished
  • Input classes: public_fixture, synthetic
Check kind Result Public-safe evidence / limitation
static passed uv 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.
static passed loopx check --scan-path loopx/capabilities/issue_fix/cli.py -> ok=True, errors=0, warnings=0, public boundary scan clean: 1 files.
regression_parity passed loopx.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 of loopx issue-fix --help and all 20 subcommand --help outputs against origin/main (21/21 exact matches).
unit passed uv 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_entrypoint passed Executed 15 examples/issue-fix-*-smoke.py end-to-end CLI smoke scripts (15/15 ok) and uv run --extra test loopx canary premerge --from-git-diff --git-diff-base origin/main -> ok=True, 4/4 direct checks (git diff --check + scripts/check_rfc_bilingual.py), py_compile, and 10/10 catalog canaries passed; CQR receipt cqr_24b68fdc0f7f07af1c0f (status: valid).
  • Coverage and gaps: Note that an earlier broader grep-matched pytest sweep across cross-cutting architecture tests included two unrelated pre-existing environment failures in a fresh worktree (test_source_session_registry_denial.py flagging execution_preparation.py on origin/main and test_todo_consumer_host_retirement.py requiring a built dashboard bundle); all issue_fix, wire_schema_version_owners, content_digest_single_owner, maintainability_ratchet, CLI entrypoint/UTF-8, and canary premerge checks passed cleanly.

Frontend / Visual Evidence

  • UI impact: none
  • Before: N/A
  • After: N/A
  • First viewport and preview: N/A
  • States and viewports shown: N/A
  • Source data: none
  • Attention review: N/A
  • Craft review: N/A

Type of Change

  • Refactoring (no functional changes)

LoopX Area

  • Capability or extension (providers, adapters, skills)

Technical Direction

  • Direction / acceptance reference, when applicable: Core capability maintainability & strict typing hygiene (loopx/capabilities/issue_fix/cli.py).

Shared-authority RFC fixture impact

  • N/A (loopx/capabilities/issue_fix/cli.py only; no control-plane authority state or RFC fixtures modified).

Boundary Checklist

  • Neither the diff nor this PR body/comments/attachments disclose private state, credentials, raw traces or verifier output, internal links, or local machine paths (including .loopx/, .codex/goals/, and live ACTIVE_GOAL_STATE.md).
  • I did not duplicate maintainer-owned benchmark work unless a maintainer split out a public issue for it.
  • I kept the change scoped to the linked issue/task.
  • Existing English/Chinese RFC pairs (including ledger entries) both have a diff, and the local premerge check python3 scripts/check_rfc_bilingual.py --base origin/main --head HEAD passes, or no paired RFC changed.
  • I completed the visual evidence section for UI changes, or marked UI impact none.
  • Every commit includes a DCO Signed-off-by trailer (git commit -s).

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 loopx-agent left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 重构需求为评审基准。

关键代码讲解

  1. 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 审计不发生偏移。
  2. _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 重定义和空值告警。
  3. _resolve_outcome_delivery_evidence(cli.py)与 _handle_outcome(cli.py):用 Payload(dict[str, object])和 Mapping[str, object] 替换全部 Any 标注,并在提交证据校验与 _comparable_delivery_evidence 幂等比对分支中显式校验 dict 类型,消除 6 处 mypy 联合类型与解包报错。
  4. 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: PASS
  • mypy(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.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant