fix(quality): close type and lint ratchets

scripts/architecture/ruff_ratchet.py

@@ -26,7 +26,14 @@ def run_ruff() -> list[dict[str, Any]]:
     )
     if result.returncode not in {0, 1}:
         raise RuntimeError(result.stderr or result.stdout or "Ruff 执行失败")
-    return json.loads(result.stdout or "[]")
+    diagnostics = json.loads(result.stdout or "[]")
+    if not isinstance(diagnostics, list):
+        raise RuntimeError("Ruff JSON 输出不是诊断列表")
+    if result.returncode == 0 and diagnostics:
+        raise RuntimeError("Ruff 返回成功但仍输出诊断")
+    if result.returncode == 1 and not diagnostics:
+        raise RuntimeError("Ruff 返回诊断状态但输出为空")
+    return diagnostics
 
 
 def aggregate_diagnostics(
@@ -40,22 +47,40 @@ def aggregate_diagnostics(
     return {path: dict(sorted(codes.items())) for path, codes in sorted(report.items())}
 
 
+def classify_counts(
+    baseline: dict[str, dict[str, int]],
+    current: dict[str, dict[str, int]],
+) -> tuple[list[str], list[str]]:
+    """把计数差异分为不可写入的回退和可固化的低水位下降。"""
+    regressions: list[str] = []
+    stale: list[str] = []
+    for path in sorted(baseline.keys() | current.keys()):
+        previous = baseline.get(path, {})
+        latest = current.get(path, {})
+        for code in sorted(previous.keys() | latest.keys()):
+            old_count = previous.get(code, 0)
+            new_count = latest.get(code, 0)
+            if new_count > old_count:
+                if old_count == 0:
+                    regressions.append(f"{path}: 新增 Ruff 诊断 [{code}] x{new_count}")
+                else:
+                    regressions.append(
+                        f"{path}: Ruff 诊断增长 [{code}] {old_count}->{new_count}"
+                    )
+            elif new_count < old_count:
+                stale.append(
+                    f"{path}: Ruff 低水位未固化 [{code}] {old_count}->{new_count}"
+                )
+    return regressions, stale
+
+
 def compare_counts(
     baseline: dict[str, dict[str, int]],
     current: dict[str, dict[str, int]],
 ) -> list[str]:
-    """返回新增规则或既有数量增长；修复和删除均合法。"""
-    problems = []
-    for path, codes in current.items():
-        previous = baseline.get(path, {})
-        for code, count in codes.items():
-            if code not in previous:
-                problems.append(f"{path}: 新增 Ruff 诊断 [{code}] x{count}")
-            elif count > previous[code]:
-                problems.append(
-                    f"{path}: Ruff 诊断增长 [{code}] {previous[code]}->{count}"
-                )
-    return problems
+    """返回 Ruff 诊断增长和尚未固化的新低水位。"""
+    regressions, stale = classify_counts(baseline, current)
+    return [*regressions, *stale]
 
 
 def main() -> int:
@@ -65,22 +90,40 @@ def main() -> int:
     parser.add_argument("--baseline", type=Path, default=DEFAULT_BASELINE)
     args = parser.parse_args()
     current = aggregate_diagnostics(run_ruff())
+    baseline_exists = args.baseline.exists()
+    baseline = (
+        json.loads(args.baseline.read_text(encoding="utf-8"))
+        if baseline_exists
+        else {}
+    )
+    regressions, stale = classify_counts(baseline, current)
     if args.write:
+        if baseline_exists and regressions:
+            print("\n".join(regressions))
+            print("拒绝写入：当前结果包含 Ruff 回退，--write 只能固化下降后的低水位。")
+            return 1
         args.baseline.parent.mkdir(parents=True, exist_ok=True)
         args.baseline.write_text(
             json.dumps(current, ensure_ascii=False, indent=2, sort_keys=True) + "\n",
             encoding="utf-8",
         )
-        print(f"已写入 {args.baseline.relative_to(PROJECT_ROOT)}")
+        display_path = (
+            args.baseline.relative_to(PROJECT_ROOT)
+            if args.baseline.is_relative_to(PROJECT_ROOT)
+            else args.baseline
+        )
+        print(f"已写入 {display_path}")
         return 0
-    baseline = json.loads(args.baseline.read_text(encoding="utf-8"))
-    problems = compare_counts(baseline, current)
+    problems = [*regressions, *stale]
     if problems:
         print("\n".join(problems))
-        print("提示：修复后可用 --write 收紧基线；禁止为绕过门禁放宽基线。")
+        if regressions:
+            print("先消除 Ruff 回退；存在增长时禁止用 --write 覆盖基线。")
+        else:
+            print("提示：当前只有债务下降，可用 --write 固化新的低水位。")
         return 1
     total = sum(count for codes in current.values() for count in codes.values())
-    print(f"Ruff ratchet 通过（存量 {total} 个诊断，只降不增）")
+    print(f"Ruff ratchet 通过（低水位已同步：{total} 个诊断）")
     return 0