Repository navigation
refactor(domain-packs): eliminate Any in issue_fix and add metric ratchet - #8972
Conversation
…chet 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)
已针对 PR #8972 exact head 2fed8440708fe37a3bc2788ea54834b0bf650a5c 完成完整审查与本地验证(审查结论:APPROVE,无 P0/P1/P2 阻断问题)。
动机 / Motivation
受影响调用方与运维者:所有消费 loopx/domain_packs/issue_fix.py 的 Issue-Fix 域状态读写、Feasibility 提升、Candidate Preflight、Maintainer Correction 结算、Reviewer Notification 状态持久化及 Repository Snapshot 保留模块(涵盖 loopx/capabilities/issue_fix/cli.py、correction_settlement.py、discovered_issue_promotion.py、pr_lifecycle.py、reviewer_cli.py 与 reviewer_notification_drain.py 等),以及 loopx/canary/ 可维护性棘轮维护者。
修改前(6844005820):loopx/domain_packs/issue_fix.py 共 642 行并存在 50 处 Any / dict[str, Any] 宽松类型标注;同时 persist_issue_fix_reviewer_notification_state 在第 514 行将 prior_queue 标注为 dict[str, dict[str, Any]] 后又在第 538 行将其重绑为 list 用于列表相等比较,导致 mypy --strict 直接报出 2 个类型赋值与 comparison-overlap 错误;此外捕获边界检查、Key 提取、JSONL 逐行读取和默认路径拼接存在重复代码,且该模块尚未纳入 module_metric_baseline.json 零 Any 上限棘轮门禁。修改后(2fed844070):issue_fix.py 降至 612 行(净减 30 行),any_count 与 dict_any_count 均降至 0,mypy --strict 与全仓 mypy(17 个文件)均为 0 错误,并以 lines: 627, any_count: 0, dict_any_count: 0 纳入棘轮基线。
可观测结果:module_metrics(Path("loopx/domain_packs/issue_fix.py")) 返回 {'lines': 612, 'any_count': 0, 'dict_any_count': 0};mypy --strict --follow-imports=silent 与全仓 mypy(17 个文件)均报 0 issues;ruff check 通过;Issue-Fix/架构/棘轮/词表 pytest 套件 724 passed(另有 2 条 test_t06_stopped_goal_refuses_at_effect_time[file|sqlite] 为未改动 origin/main@6844005820 上既有的 activation_state 过时测试夹具失败,经实跑比对完全一致);隔离 HOME 下全部 6 个 Issue-Fix smoke 脚本通过;canary premerge --tier quick ok: true;loopx check ok: True;所有公开符号名、返回字典结构、原地变更行为与 ValueError 错误文本逐字不变。
非目标边界:本 PR 不更改任何 JSONL 账本 Schema、键值策略、锁机制或 CLI 行为,不顺带修改未触及的 tests/capabilities/test_issue_fix_maintainer_correction_admission.py:403 中既有 activation_state 测试夹具,亦不授予自动合入权限。
改动思路 / Approach
全部强类型收口、变量遮蔽修复与重复样板合并均在既有的 loopx/domain_packs/issue_fix.py 模块边界内完成,通过 dict[str, object]、Mapping[str, object]、Sequence[object]、Sequence[str] 与最小化的 TypeGuard 窄化辅助实现零 Any 静态契约,同时保持对 loopx/domain_state.py、loopx/capabilities/issue_fix/* 等全部上下游调用方的完全兼容,无需修改任何调用方文件或新增平行适配层。
当前 PR 边界:修改严格限定于 loopx/domain_packs/issue_fix.py 与 loopx/canary/module_metric_baseline.json 两个文件,保持持久化格式、失败策略与公开契约 100% 不变;既有 origin/main 测试夹具 test_t06_stopped_goal_refuses_at_effect_time 的 activation_state 迁移留待独立测试修复 PR 处理。
- 边界与原地变更安全:
payload与domain_state_projection的窄化采用TypeGuard[dict[str, object]](_is_str_dict)而非复制字典,确保_upsert_issue_fix_payload、promote_issue_fix_feasibility_ledger_jsonl和persist_issue_fix_reviewer_notification_state对调用方传入字典的原地更新(如write_performed、write_result、setdefault与队列回写)语义毫厘不差。 - 修复 L538-539 变量遮蔽与严格类型冲突:将第
514行按idempotency_key建索引的字典重命名为prior_queued_by_key,保留prior_queue: Sequence[object]指向原始payload.get("reviewer_notification_queue")列表(非列表回退[]),使merged_receipts == prior_receipts and queue == prior_queue的运行时行为完全一致且通过mypy --strict的--strict-equality检查。 - 公共辅助收敛与棘轮锁死:抽取
_FEASIBILITY_CAPTURE_BOUNDARY_FIELDS、_PR_LIFECYCLE_CAPTURE_BOUNDARY_FIELDS、_require_false_capture_flags、_ledger_key、_read_jsonl_dicts(strict_label=...)及_issue_fix_ledger_path,并将无闭包依赖的_unchanged_pr_lifecycle_observation与_preserve_compact_lifecycle_evidence提升至模块级;在module_metric_baseline.json注册any_count=0, dict_any_count=0, lines=627。
具体改动 / Changes
本次 diff 仅触及 2 个文件(262 insertions(+), 287 deletions(-),整体净减 25 行;issue_fix.py 由 642 行降至 612 行)。本重构无独立外部书面规格文档(no_spec),完全以既有 loopx/domain_packs/issue_fix.py 运行时契约、单测与架构护栏测试为基准:
loopx/domain_packs/issue_fix.py(+257 / -287,642 -> 612行,50 Any -> 0):移除typing.Any导入与全部50处Any注解,修复prior_queue遮蔽问题,合并捕获边界、Key 提取、JSONL 读取与路径 helper,完整保留所有文档字符串、说明注释、错误提示和公开常量/函数名。loopx/canary/module_metric_baseline.json(+5 / -0,L68-72):按字母序注册"loopx/domain_packs/issue_fix.py": {"any_count": 0, "dict_any_count": 0, "lines": 627}。
关键代码讲解
_is_str_dict/_is_object_list/_object_list(loopx/domain_packs/issue_fix.py:44-53):分别以TypeGuard[dict[str, object]]、TypeGuard[list[object]]与列表回退函数替代零散的isinstance(..., dict/list)判断;既避免复制可变投影字典导致原地写回失效,又使Sequence[object]比较满足mypy --strict校验。_ledger_key与_read_jsonl_dicts(loopx/domain_packs/issue_fix.py:64-103):_ledger_key统一处理顶层(Candidate Preflight)和嵌套observation(Feasibility / PR Lifecycle)的repo+ref_field校验并保持原有ValueError文案;_read_jsonl_dicts(..., strict_label=...)同时服务宽容读取(read_issue_fix_pr_lifecycle_ledger_row、retain_issue_fix_repository_snapshot_jsonl)与严格逐行报错(promote_issue_fix_feasibility_ledger_jsonl)。_unchanged_pr_lifecycle_observation/_preserve_compact_lifecycle_evidence(loopx/domain_packs/issue_fix.py:343-396):提取自原upsert_issue_fix_pr_lifecycle_ledger_jsonl内部闭包,循环合并reviewer_notification_receipts/reviewer_notification_queue回退逻辑,保留origin_request、first_push_ci、maintainer_corrections及旧读者兼容字段maintainer_correction/maintainer_correction_fingerprint。persist_issue_fix_reviewer_notification_state(loopx/domain_packs/issue_fix.py:473-544):复用_PR_LIFECYCLE_CAPTURE_BOUNDARY_FIELDS回填历史缺省布尔位,以prior_queued_by_key区分索引字典与原始列表prior_queue,彻底消除旧代码 L538-539 类型冲突并保持畸形队列项触发写回清理的精确等价行为。
对主干的风险 / Risks
- 静态与运行期契约一致性(Failure Analysis & Negative Walkthrough):最敏感风险为
Mapping与dict窄化后影响原地修改或畸形 JSONL/队列回退分支。已在promote_issue_fix_feasibility_ledger_jsonl、upsert_issue_fix_pr_lifecycle_ledger_jsonl、persist_issue_fix_reviewer_notification_state与_validated_reviewer_notification_queue_receipt中逐支核对:非dict行、无效 JSONL 行、重复或无效 receipt key、缺省边界字段与异常队列项的拒绝和回退完全等价。 - 范围契合与变更比例(Scope Fit & Change Proportionality):
issue_fix.py服务于全部 Issue-Fix CLI/Capability 主路径(活跃生产调用方覆盖cli.py、correction_settlement.py、discovered_issue_promotion.py、reviewer_notification_drain.py、reviewer_cli.py等);零Any与净减30行并配棘轮上限,维护收益明显且可零成本回滚。 - 默认关闭隔离、权限与语义对齐(Isolation, Authority & Semantic Alignment):纯静态类型收口与本地私有函数整理,无新增 CLI 开关、状态枚举或运行期行为分支;保留
REVIEWER_NOTIFICATION_LOCAL_TIME_PATTERN、REVIEWER_NOTIFICATION_QUEUE_RECEIPT_SCHEMA_VERSION与ENVELOPED_SHA256_PATTERN单一拥有者契约,无词表漂移(candidate_decision="reuse_existing")。 - 本地完整验证结果(exact head
2fed8440708fe37a3bc2788ea54834b0bf650a5c):module_metrics:{'lines': 612, 'any_count': 0, 'dict_any_count': 0}(PASS)mypy --strict --follow-imports=silent loopx/domain_packs/issue_fix.py& 全仓mypy(17 files): PASS(0 issues)ruff check loopx/domain_packs/issue_fix.py tests/canary/test_maintainability_ratchet.py: PASS(All checks passed)pytest -q(Issue-Fix/架构/棘轮/词表漂移套件): 724 passed(test_issue_fix_local_time_owner.py、test_issue_fix_queue_receipt_version_owner.py、test_content_digest_single_owner.py、test_issue_fix_private_evidence_settlement.py、test_maintainability_ratchet.py、test_semantic_vocabulary_drift.py等全部通过;test_issue_fix_maintainer_correction_admission.py::test_t06_stopped_goal_refuses_at_effect_time[file|sqlite]2条失败已在未改动origin/main@6844005820实跑复现,系既有activation_state夹具过期)6个 Issue-Fix smoke 脚本(隔离HOME下运行): PASS(6/6ok)loopx canary premerge --tier quick --from-git-diff --git-diff-base origin/main: PASS(ok: true, selected=3, failures=0)loopx check --scan-path loopx/domain_packs/issue_fix.py --scan-path loopx/canary/module_metric_baseline.json: PASS(ok: True, errors=0, warnings=0)- 远端 GitHub CI(
Package Smoke / loopx-core、Python Tests / changes、Release Artifacts / prepare)于新推头提交仍在运行中(IN_PROGRESS,作为诊断信息记录;DCOSign-off与inspect-pr-diff等已绿)。
我的整体评价 / Verdict
- Long-horizon 影响:
improved— 清除issue_fix.py全部50处Any与L538-539隐藏的类型遮蔽问题,净减30行重复代码并以any_count=0, lines<=627纳入棘轮门禁,降低长程 Issue-Fix 域状态演进中的类型漂移风险。 - User-experience 影响:
not_applicable— 纯内部 Python 强类型重构与棘轮基线注册,无终端输出或 UI 变更;visual_review为not_applicable。 - 可观测语义 / 复用 / 词表:
observable_semantics为equivalent,repository_reuse为reused,authority_semantics与semantic_alignment均为aligned(candidate_decision="reuse_existing")。
改动严格收敛、静态类型检查与运行时测试及 smokes 充分证明行为等价,无 P0/P1/P2 阻断项。本 PR 为作者自有且触及产品运行时,正式合入仍需维护者授权及远端 CI 通过。
English verdict: APPROVE exact head 2fed844 (author-owned COMMENTED approval review); removes all 50 Any annotations and fixes the 2 strict mypy errors in loopx/domain_packs/issue_fix.py (642 -> 612 lines) with zero-Any baseline ratchet, verified by strict/repo mypy (0 issues across 17 files), ruff, 724 passing pytest tests (2 pre-existing activation_state fixture failures reproduced on origin/main), all 6 issue-fix smokes under isolated HOME, quick premerge canary, and boundary check.
Summary
50Anyannotations inloopx/domain_packs/issue_fix.py(any_count: 50 -> 0,dict_any_count: 0 -> 0) and slimmed the module from642to612lines (-30lines) while preserving all existing docstrings, explanatory comments, public/tested symbol names, dict return shapes, and error strings.mypy --stricterrors at the former lines538-539inpersist_issue_fix_reviewer_notification_stateby separatingprior_queued_by_key(dict[str, dict[str, object]]) fromprior_queue(Sequence[object]), preserving exact runtime comparison semantics (merged_receipts == prior_receipts and queue == prior_queue)._is_str_dict,_is_object_list,_object_list,_require_false_capture_flags,_ledger_key,_read_jsonl_dicts,_issue_fix_ledger_path, and module-level_unchanged_pr_lifecycle_observation/_preserve_compact_lifecycle_evidence)."loopx/domain_packs/issue_fix.py"(any_count: 0,dict_any_count: 0,lines: 627) alphabetically inloopx/canary/module_metric_baseline.json.Verification
module_metrics(Path("loopx/domain_packs/issue_fix.py")):{'lines': 612, 'any_count': 0, 'dict_any_count': 0}uv run --extra test mypy --strict --follow-imports=silent loopx/domain_packs/issue_fix.py:Success: no issues found in 1 source fileuv run --extra test mypy:Success: no issues found in 17 source filesuv run --extra test ruff check loopx/domain_packs/issue_fix.py tests/canary/test_maintainability_ratchet.py:All checks passed!uv run --extra test pytest -q tests/capabilities/test_issue_fix_*.py tests/architecture/test_issue_fix_*.py tests/architecture/test_content_digest_single_owner.py tests/control_plane/test_issue_fix_private_evidence_settlement.py tests/canary/test_maintainability_ratchet.py tests/architecture/test_semantic_vocabulary_drift.py:724 passed(2pre-existing failures intests/capabilities/test_issue_fix_maintainer_correction_admission.py::test_t06_stopped_goal_refuses_at_effect_time[file|sqlite]from legacyactivation_stateoverride, reproduced identically on untouchedorigin/main@6844005820).HOME: all6passed (examples/issue-fix-outcome-projection-smoke.py,examples/issue-fix-explore-projection-smoke.py,examples/issue-fix-reviewer-request-smoke.py,examples/issue-fix-pr-lifecycle-smoke.py,examples/issue-fix-discovered-issue-promotion-smoke.py,examples/issue-fix-reviewer-notification-drain-postwrite-smoke.py).uv run --extra test loopx canary premerge --tier quick --from-git-diff --git-diff-base origin/main:passed(ok: true,selected_checks: 3,failures: 0).uv run --extra test loopx check --scan-path loopx/domain_packs/issue_fix.py --scan-path loopx/canary/module_metric_baseline.json:ok: True(errors=0, warnings=0, checks=5).