Repository navigation
refactor(contract): slim loopx/contract.py below 1,800 lines (-217 net LOC) - #9255
loopx-agent wants to merge 1 commit into
Conversation
… boundary reporting 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 check)、状态汇总(loopx status)或合并前公共边界扫描(loopx canary premerge)时,依赖 loopx/contract.py 的维护者与开发者都会直接受其模块体量、静态类型健康度与内部可维护性影响。
改动前(origin/main),loopx/contract.py 已膨胀至 1,989 行,距离默认模块行数上限 MODULE_LINE_LIMIT = 2000 仅余 11 行缓冲,且存在 4 处 mypy 静态类型报错与 3 个超过 60 条 AST 语句的高复杂度函数(_todo_contract_diagnostics 157 条、scan_public_boundary 120 条、check_contract 101 条);一旦为修复边界或诊断问题新增十余行代码,便会触发维护性棘轮告警,迫使后续变更在交付压力下临时申请豁免或仓促拆分文件。改动后(精确头 a08386ab7325814d73d7977dd5216bc68325c1d0),在不拆分新模块、不改公开契约的前提下,仅通过内部合并重复逻辑与抽离扁平辅助函数,将文件体量压低至 1,772 行(净减 217 行,留出 228 行安全余量),同时消除全部 4 处 mypy 报错。
模块行数从 1,989 行降至 1,772 行(+466 / -683,净减 217 行),any_count 保持 26、dict_any_count 保持 0;mypy loopx/contract.py 由基线 4 处错误清零至 0(全仓库 17 个受检文件均通过);超过 60 条 AST 语句的函数由 3 个降至 2 个(check_contract 降至 87 条,低于 DECISION_STATEMENT_LIMIT = 90);且所有 loopx check、loopx status、公共边界扫描、Markdown Todo 合约校验及 Git 探针失败闭环输出均与基线完全一致。
本 PR 不改动 LEAK_RULES 安全正则、预过滤大小写折叠或凭证引用判定逻辑,不迁移 Python/TypeScript 控制面所有权,不调整任何 JSON/Markdown 状态字段或 CLI 参数契约,也不拆分新的兄弟模块。
改动思路 / Approach
如果不做任何改动,loopx/contract.py 只剩 11 行余量,极易在常规维护时触发 diff_scoped_module_ceiling_violations;而若直接拆出新兄弟模块,则会引入新的跨文件依赖面并破坏现有测试对 _git_probe、_git_query、_git_query_bytes、_tracked_scan_files 等私有打桩点的路径绑定。相比之下,在原文件内部做零行为变更的去重与扁平化收敛,是成本最低且最容易逆转的方案。
本次改动仅在 loopx/contract.py 内部完成局部职责拆解与重复逻辑合并,将 Git 进程探针、目标过滤与状态文件路径解析、Markdown Todo 元数据校验及边界失败表驱动映射保留在现有契约所有权边界内,未新增平行状态所有权或跨模块循环依赖。 严格限定于单文件 loopx/contract.py 内部重构(1,989 -> 1,772 行,净减 217 行),不迁移 TypeScript 控制面所有权、不修改公共安全正则或词汇表,也不拆分新的兄弟模块。
在结构分层上,整个模块仍维持既有边界:check_contract(被 loopx/cli_commands/status.py 与 loopx/status.py 调用)作为顶层合约聚合入口,协调注册表检查、Todo 权威路由(优先委托 read_canonical_todos_if_promoted 与 todo_contract_diagnostics,仅在返回 None 时回退到 Markdown 校验)、权威源完整性校验与状态投影缺口提示;scan_public_boundary(亦被 loopx/canary/premerge.py 直接调用)则封装文件枚举、局部私密状态过滤、Git 所有权探测(通过 _run_git_probe 与 _retire_owned_probe 严格在超时或取消时回收进程组)及 LEAK_RULES 规则匹配,所有探测失败与未读目录/文件均按 fail-closed 原则保留在失败字段中并置 ok=False。
| 维度 | 基线 (origin/main: 7fb1c851) |
当前头 (a08386ab) |
变化评估 |
|---|---|---|---|
| 文件行数 / 净增减 | 1,989 行 | 1,772 行 (+466 / -683) |
净减 217 行,留出 228 行余量 |
any_count / dict_any_count |
26 / 0 | 26 / 0 | 保持不变 |
mypy loopx/contract.py |
4 个错误 | 0 个错误(17 文件通过) | 修复既有的类型收窄缺口 |
| >60 AST 语句函数 | 3 个 (157 / 120 / 101) | 2 个 (101 / 87) | check_contract 低于 90 上限 |
| 语义词表候选 | — | 0 (supported candidates: 0) |
无词表/协议变更 |
具体改动 / Changes
经检索仓库文档与可维护性基线策略,针对“将 loopx/contract.py 内部精简至 1,800 行以下”这一纯内部重构,仓库并无单独成文的 RFC 或 Issue 规格说明书(spec_basis: no_spec),其工程验收依据来自 loopx/canary/maintainability_ratchet.py 中的 MODULE_LINE_LIMIT = 2000、DECISION_STATEMENT_LIMIT = 90 以及 docs/development/README.md 规定的重构行为等价与回归门禁原则。对 git diff origin/main...HEAD 逐行核对确认,本次变更仅修改 loopx/contract.py 一个文件。
关键代码讲解
_run_git_probe(loopx/contract.py:487):将原_git_query(text=True)与_git_query_bytes(原始字节)两段高度重复的subprocess.Popen、GIT_PROBE_TIMEOUT_SECONDS超时控制、BaseException中断回收进程组_retire_owned_probe及OSError兜底逻辑合并为单一字节探测通道;_git_query_bytes直接委托返回_GitBytesAnswer,_git_query则以"utf-8"/"replace"解码并返回_GitAnswer。保留_literal_git_environment()清理GIT_*_PATHSPECS并固定LC_ALL=C、LANGUAGE=C的隔离语义,同时完整保留所有测试打桩点。_markdown_user_todo_scope_violation(loopx/contract.py:831) 与_markdown_todo_contract_diagnostics(loopx/contract.py:897):将原本嵌在_todo_contract_diagnostics中的 280 余行 Markdown Todo 解析与校验循环拆为_parse_markdown_todo_metadata、_markdown_user_todo_scope_violation与_markdown_todo_contract_diagnostics。其中 11 支用户待办作用域规则由深层if/elif改写为扁平 early-return 并统一拼接(state_file=..., line=..., text=...)位置尾注,经核对 11 条分支的判断顺序、错误码与文本模板与origin/main完全一一对应。_goal_source_and_projection_diagnostics(loopx/contract.py:1111):通过复用新增的_iter_filtered_goals与_resolve_existing_state_file,将原先两段重复遍历registry_goals(registry)的_authority_source_diagnostics与_active_state_projection_gap_warnings合并为单次遍历,同时严格维持check_contract中error_diagnostics、checks与warnings各自的追加顺序不变,并以isinstance(raw_roles, (list, tuple))消除了基线第 1207 行的mypy报错。scan_public_boundary(loopx/contract.py:1335) 与文件枚举辅助函数:抽离_resolve_scannable_file、_is_skipped_dir_name、_root_sort_key、_scan_package_lock_hits,并把_unreadable_directory_label/_unreadable_directory_labels内联并入_render_unreadable_directories(经全库检索确认无外部引用)。在public_files()中用短路表达式ownership_unavailable or (git := _git_probe(path)).get("tracked") is None合并重复分支:一旦某个私有状态文件 Git 探针无响应,立即置ownership_unavailable = True并跳过后续_git_probe调用,同时始终拒绝打开未确认未跟踪的私密文件;在private_doc_url策略放行路径上保留每文件复用的git := git or _git_probe(path)行为。check_contract(loopx/contract.py:1527):使用_BOUNDARY_FAILURE_FIELDS数据表驱动missing_scan_roots、unreadable_directories、unreadable_files、unavailable_git_probes的提取、ok聚合和错误发射;用raw <= unique早退简化运行历史重复行判定(完全等价保持legacy_runtime_goal与reward_overlay_rows分类逻辑);并用raw_git = boundary_payload.get("git")类型收窄清除了基线第 1710–1713 行的 3 处mypy报错。display_report_value合并了等价的(list, tuple)分支,__getattr__、__dir__、__all__及terminate_process_tree惰性加载机制均未改动。
对主干的风险 / Risks
经独立逐行审计与本地全链路验证,本 PR 不存在阻塞合入的问题(no blocking finding)。
在最坏回归场景与负向路径上,重点核查了以下边界:
- Git 探针失败闭环与短路保护:当
_git_probe对首个私密状态文件返回tracked=None时,实测确认仅触发 1 次_git_probe调用后即设置ownership_unavailable=True,后续私密文件均跳过探测并同时记入unavailable_git_probes与skipped_private_state_files,不打开文件内容且保持ok=False。test_contract_git_probe_budget.py与test_contract_git_probe_cancel.py在真实延迟与SIGINT取消下均通过,确认_retire_owned_probe正确回收子进程树。 - 不可读目录/文件与缺失扫描根:
test_contract_scan_missing_roots.py、test_contract_scan_unreadable_directories.py、test_contract_scan_unreadable_files.py全部通过;反事实比对确认跨双扫描根同名不可读目录仍输出['sub: Permission denied', 'sub (2): Permission denied'],无效 UTF-8 与chmod 000文件仍如实报错且ok=False。 - Markdown Todo 与 19 种诊断优先级:以
todo_snapshot=None回退路径驱动的基线 vs 当前头反事实实验覆盖了全部 19 种不同code(共 22 条诊断、13 条被检用户门控),包含多错误并发时的抢占顺序及## Completed Work Archive终态豁免,输出逐字节一致。
残余风险与验证说明:
_git_query现经_run_git_probe读取原始字节后再.decode("utf-8", "replace"),不再启用Popen(..., text=True)的通用换行转换(若未来有新调用方直接读取_git_query(...).stdout中的换行符需留意;当前唯一生产调用方_git_probe._ask仅检查returncode,无影响)。- 本地可维护性与回归验证结果:
ruff check loopx/contract.pyPASS;mypy loopx/contract.py与全仓python -m mypy(17 个文件)PASS;scripts/check_rfc_bilingual.py --base origin/main --head HEADPASS;核心与关联单测 702 passed, 6 skipped(6 个 skip 均位于tests/canary/test_git_path_display.py,因 macOS APFS 原生拒绝非 UTF-8 或含 CR 字节的文件名,属平台预期跳过);补充调用方套件(195 passed in 372.32s)PASS;基线 vs 当前头跨 20 项run_counterfactual.py检查与 6 项cf_extra.py检查(含干净/脏场景loopx check --format json、loopx status --format json、display_report_value、render_contract_markdown、__all__、惰性terminate_process_tree)全部逐字节一致(PARITY_OK)。 - 独立审查工作树运行
loopx canary premerge时的两项环境差异说明:examples/semantic-vocabulary-drift-smoke.py因审查隔离工作树未安装本地node_modules(npm ci --ignore-scripts)而报环境缺失(external_unrelated),但scripts/generate_semantic_inventory.py --changed-from origin/main已独立证实supported candidates: 0;change-quality verify因回执文件名按工作树路径哈希键控而在新审查工作树返回receipt_missing,但已核实作者在同scope_fingerprint(86b128b0c0935a5ea031de3818328bdfc0ed0aff4dcdf240cb760672c8d0ec8f)下已记录通过回执cqr_86b128b0c0935a5ea031(decision: pass)。依据wait_for_ci: false策略,未轮询或等待远端 GitHub Actions CI。
我的整体评价 / Verdict
综合全部独立验证结果,这是一次克制、整洁且可逆的单文件内部精简重构。
long_horizon(preserved):check_contract、scan_public_boundary、Todo 合约校验与历史索引诊断的全部语义、错误码和 fail-closed 不变量均完整保留。user_experience(preserved):loopx check与loopx status的 CLI 退出码、JSON 载荷、Markdown 报告及错误提示均与基线完全一致。visual_review(not_applicable):经核查仅修改 Python 诊断模块loopx/contract.py,不涉及任何渲染前端或交互界面变更;unverified_scope: none(非 UTF-8/CR 文件名路径在 macOS APFS 上受文件系统限制跳过 6 条用例)。observable_semantics(equivalent)、code_volume(necessary;compatibility_assessment: retain)、change_proportionality(proportionate;architecture_assessment: retain)、default_off_isolation(not_applicable)、authority_semantics(not_applicable) 与semantic_alignment(not_applicable):未新增或修改任何状态词表或协议字段,与现有公共与测试边界完全兼容,当前精确头a08386ab7325814d73d7977dd5216bc68325c1d0经远端校验未发生漂移。
English verdict: APPROVE — exact head a08386ab7325814d73d7977dd5216bc68325c1d0 cleanly reduces loopx/contract.py from 1,989 to 1,772 lines (-217 net LOC) with zero sibling modules, fixes all 4 baseline mypy errors, preserves all security/Git-probe fail-closed invariants, and passes local unit/regression tests and counterfactual parity checks without blocking findings.
Summary
Purely behavior-preserving, net-negative-LOC refactoring of
loopx/contract.pyto move it cleanly below the 2,000-line default module metric ceiling (1,989 -> 1,772lines,-217net;+466 / -683,any_count: 26 -> 26,dict_any_count: 0 -> 0) with zero new sibling modules and zero changes to security rules, regexes, prefilters, or Git-probe fail-closed invariants.What Changed (
loopx/contract.py)_run_git_probe): Unified_git_queryand_git_query_bytesover one session-isolatedsubprocess.Popen+ timeout/Ctrl-C_retire_owned_probelifecycle while keeping_GitAnswer,_GitBytesAnswer,_git_query,_git_query_bytes, and_literal_git_environmentcaller/test seams intact._iter_filtered_goalsand_resolve_existing_state_fileshared across_todo_contract_diagnosticsand_goal_source_and_projection_diagnostics(merging_authority_source_diagnosticsand_active_state_projection_gap_warnings)._parse_markdown_todo_metadata,_markdown_user_todo_scope_violation(flat early-return precedence replacing the 11-armelifchain and repeated(state_file=..., line=..., text=...)boilerplate), and_markdown_todo_contract_diagnostics._resolve_scannable_file,_is_skipped_dir_name, and_root_sort_keyshared across_tracked_scan_files,iter_scan_files,_render_unreadable_directories, andscan_public_boundary._scan_package_lock_hits, unified theownership_unavailable/_git_probeskip branch, and inlined single-use private wrappers (_hit_allowed_by_policy,_directory_reason).check_contractprojection & duplicate summary cleanup:_BOUNDARY_FAILURE_FIELDSand a compact summary-check loop._index_duplicate_warningdetail formatting; merged identicallistandtuplearms indisplay_report_value.Verification (Exact Head
a08386ab)1,989 -> 1,772lines (-217net),any_count: 26(unchanged),dict_any_count: 0.uv run --extra test ruff check loopx/contract.py->All checks passed!uv run --extra test mypy loopx/contract.py->Success: no issues found in 1 source file(down from 4 pre-existing issues onorigin/main)uv run --extra test python -m mypy->Success: no issues found in 17 source filesuv run --extra test python scripts/generate_semantic_inventory.py --changed-from origin/main->supported candidates: 0tests/test_contract_*.py,tests/test_public_*.py,tests/test_process_runtime_loading.py,tests/canary/test_maintainability_ratchet.py,tests/control_plane/test_public_safety_credential_caller_faces.py,tests/control_plane/test_contract_health.py,tests/control_plane/test_m6_quality_gates.py): 438 passed in 72.39s.test_public_boundary_parallel_reads.py,test_contract_health.py,test_canonical_status_todos.py,test_truncated_active_state_todos.py,test_todo_source_runtime_route.py,test_status_history_reuse.py,test_m6_quality_gates.py,test_presentation_public_safety.py,test_status_collection_material_capability_wiring.py): 395 passed in 176.29s.origin/main:loopx check --format jsonmatched bit-for-bit (returncodeand full JSON payload) on clean, dirty (boundary leaks + missing root +package-lock.json+ Markdown Todo contract), and repositoryREADME.md/docs/fixtures._todo_contract_diagnosticscounterfactual comparison matched bit-for-bit across all 18 distinct Markdown Todo diagnostic codes plus archive exemptions,_index_duplicate_warningvariants,__all__,_git_query, and_git_query_bytes.change-qualityreceipt:cqr_86b128b0c0935a5ea031(decision: pass,receipt_valid: true,scope_fingerprint: 86b128b0c0935a5ea031de3818328bdfc0ed0aff4dcdf240cb760672c8d0ec8f).canary premerge --from-git-diff --git-diff-base origin/main --goal-id personal-loopx-maintenance:gate.status: passed,direct_failure_count: 0,selected_check_count: 6,failure_count: 0.