Skip to content

refactor(contract): slim loopx/contract.py below 1,800 lines (-217 net LOC) - #9255

Open
loopx-agent wants to merge 1 commit into
mainfrom
codex/slim-contract-py-20261122
Open

loopx-agent wants to merge 1 commit into
mainfrom
codex/slim-contract-py-20261122

Conversation

@loopx-agent

Copy link
Copy Markdown
Collaborator

Summary

Purely behavior-preserving, net-negative-LOC refactoring of loopx/contract.py to move it cleanly below the 2,000-line default module metric ceiling (1,989 -> 1,772 lines, -217 net; +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)

  • Shared bounded Git probe (_run_git_probe): Unified _git_query and _git_query_bytes over one session-isolated subprocess.Popen + timeout/Ctrl-C _retire_owned_probe lifecycle while keeping _GitAnswer, _GitBytesAnswer, _git_query, _git_query_bytes, and _literal_git_environment caller/test seams intact.
  • Shared goal filtering & Markdown Todo contract helpers:
    • Added _iter_filtered_goals and _resolve_existing_state_file shared across _todo_contract_diagnostics and _goal_source_and_projection_diagnostics (merging _authority_source_diagnostics and _active_state_projection_gap_warnings).
    • Split Markdown Todo fallback validation into _parse_markdown_todo_metadata, _markdown_user_todo_scope_violation (flat early-return precedence replacing the 11-arm elif chain and repeated (state_file=..., line=..., text=...) boilerplate), and _markdown_todo_contract_diagnostics.
  • Shared file eligibility & package-lock scanning:
    • Extracted _resolve_scannable_file, _is_skipped_dir_name, and _root_sort_key shared across _tracked_scan_files, iter_scan_files, _render_unreadable_directories, and scan_public_boundary.
    • Extracted _scan_package_lock_hits, unified the ownership_unavailable / _git_probe skip branch, and inlined single-use private wrappers (_hit_allowed_by_policy, _directory_reason).
  • Table-driven check_contract projection & duplicate summary cleanup:
    • Replaced repeated boundary unread/unavailable coercion and error emission with _BOUNDARY_FAILURE_FIELDS and a compact summary-check loop.
    • Simplified run-history duplicate classification and _index_duplicate_warning detail formatting; merged identical list and tuple arms in display_report_value.

Verification (Exact Head a08386ab)

  • Module metrics: 1,989 -> 1,772 lines (-217 net), any_count: 26 (unchanged), dict_any_count: 0.
  • Static checks:
    • 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 on origin/main)
    • uv run --extra test python -m mypy -> Success: no issues found in 17 source files
    • uv run --extra test python scripts/generate_semantic_inventory.py --changed-from origin/main -> supported candidates: 0
  • Focused & regression tests:
    • Exact-head focused suite (tests/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.
    • Pre-rebase identical-diff contract & canary suite: 565 passed, 6 skipped (macOS non-UTF-8/Windows skips); control-plane contract suites (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.
  • Counterfactual parity vs origin/main:
    • loopx check --format json matched bit-for-bit (returncode and full JSON payload) on clean, dirty (boundary leaks + missing root + package-lock.json + Markdown Todo contract), and repository README.md/docs/ fixtures.
    • Direct _todo_contract_diagnostics counterfactual comparison matched bit-for-bit across all 18 distinct Markdown Todo diagnostic codes plus archive exemptions, _index_duplicate_warning variants, __all__, _git_query, and _git_query_bytes.
  • Change Quality & Canary Premerge:
    • change-quality receipt: 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.

… boundary reporting

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 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 一个文件。

关键代码讲解

  1. _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 的隔离语义,同时完整保留所有测试打桩点。
  2. _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 完全一一对应。
  3. _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 报错。
  4. 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) 行为。
  5. 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 终态豁免,输出逐字节一致。

残余风险与验证说明:

  1. _git_query 现经 _run_git_probe 读取原始字节后再 .decode("utf-8", "replace"),不再启用 Popen(..., text=True) 的通用换行转换(若未来有新调用方直接读取 _git_query(...).stdout 中的 换行符需留意;当前唯一生产调用方 _git_probe._ask 仅检查 returncode,无影响)。
  2. 本地可维护性与回归验证结果:ruff check loopx/contract.py PASS;mypy loopx/contract.py 与全仓 python -m mypy(17 个文件)PASS;scripts/check_rfc_bilingual.py --base origin/main --head HEAD PASS;核心与关联单测 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)。
  3. 独立审查工作树运行 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.

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