15.3 协作与版本管理

#!/usr/bin/env python3
# file: sim/na_15_3_spec_diff.py
# tier: S
# verify: /opt/homebrew/bin/python3 sim/na_15_3_spec_diff.py
"""卷一 15.3 协作与版本管理（S 层）：规格变更的机器可读 diff 与影响面。

本机可复现的部分：把 config/story_spec.json（v1）与 out/spec_v2.json（v2）
做一次结构 diff，落成 out/spec_diff_arch.json，并回答两个评审问题——
  1) 这次变更是**纯增量**的吗（删键 0 个、改值只发生在版本号上）？
  2) 触及的每一段，各有多少个文件在读它（变更影响面）？

真实团队的评审会 / 排期 / 冻结流程本机没有，属 X 档，正文逐处标注。
产出 out/spec_diff_arch.json。非增量变更即非零退出。
"""
from __future__ import annotations

import json
import os
import sys

HERE = os.path.dirname(os.path.abspath(__file__))
ROOT = os.path.dirname(HERE)
SCAN_DIRS = ("sim", "core/src/inkwell", "core/test", "web")
SCAN_EXT = (".py", ".ts", ".mjs")
# 允许改值的位置：版本号本身。除此之外任何改值都说明这次变更不是纯增量。
ALLOWED_CHANGED = {"meta.spec_version"}


def load(rel: str) -> dict:
    with open(os.path.join(ROOT, rel), encoding="utf-8") as fh:
        return json.load(fh)


def diff(a, b, path: str = "") -> tuple[list[str], list[str], list[dict]]:
    """返回 (added, removed, changed)。列表按索引逐项递归，路径形如 beats[0].pov。"""
    added: list[str] = []
    removed: list[str] = []
    changed: list[dict] = []
    if isinstance(a, dict) and isinstance(b, dict):
        for k in sorted(set(a) | set(b)):
            p = f"{path}.{k}" if path else k
            if k not in a:
                added.append(p)
            elif k not in b:
                removed.append(p)
            else:
                da, dr, dc = diff(a[k], b[k], p)
                added += da
                removed += dr
                changed += dc
    elif isinstance(a, list) and isinstance(b, list):
        for i in range(max(len(a), len(b))):
            p = f"{path}[{i}]"
            if i >= len(a):
                added.append(p)
            elif i >= len(b):
                removed.append(p)
            else:
                da, dr, dc = diff(a[i], b[i], p)
                added += da
                removed += dr
                changed += dc
    elif a != b:
        changed.append({"path": path, "from": a, "to": b})
    return added, removed, changed


def consumers(section: str) -> dict:
    """谁在读这一段：扫源码里出现的 `["<section>"]` 取值形式。"""
    hits: list[str] = []
    for rel in SCAN_DIRS:
        d = os.path.join(ROOT, rel)
        if not os.path.isdir(d):
            continue
        for f in sorted(os.listdir(d)):
            if not f.endswith(SCAN_EXT) or not os.path.isfile(os.path.join(d, f)):
                continue
            with open(os.path.join(d, f), encoding="utf-8") as fh:
                if f'["{section}"]' in fh.read():
                    hits.append(f"{rel}/{f}")
    return {"referrers": len(hits), "examples": hits[:3]}


def section_of(path: str) -> str:
    return path.split(".")[0].split("[")[0]


def main() -> int:
    problems: list[str] = []
    v1 = load("config/story_spec.json")
    if not os.path.isfile(os.path.join(ROOT, "out/spec_v2.json")):
        print("FAIL 缺 out/spec_v2.json，先跑 /opt/homebrew/bin/python3 sim/na_02_migrate.py")
        return 1
    v2 = load("out/spec_v2.json")

    added, removed, changed = diff(v1, v2)

    if removed:
        problems.append(f"出现删除键 {len(removed)} 个：{removed[:3]}")
    off = [c["path"] for c in changed if c["path"] not in ALLOWED_CHANGED]
    if off:
        problems.append(f"改值超出允许集 {sorted(ALLOWED_CHANGED)}：{off[:3]}")

    touched: dict[str, int] = {}
    for p in added + removed + [c["path"] for c in changed]:
        s = section_of(p)
        touched[s] = touched.get(s, 0) + 1
    impact = {s: consumers(s) for s in sorted(touched)}

    report = {
        "ok": not problems,
        "problems": problems,
        "from": "config/story_spec.json",
        "to": "out/spec_v2.json",
        "added": len(added),
        "removed": removed,
        "changed": changed,
        "touched_sections": touched,
        "impact": impact,
    }
    out = os.path.join(ROOT, "out/spec_diff_arch.json")
    os.makedirs(os.path.dirname(out), exist_ok=True)
    with open(out, "w", encoding="utf-8") as fh:
        json.dump(report, fh, ensure_ascii=False, indent=2)
        fh.write("\n")

    print("v1 → v2 结构 diff（v2 由 sim/na_02_migrate.py 产出）")
    print(f"  新增键 {len(added)} 个，删除键 {len(removed)} 个，改值 {len(changed)} 处")
    for c in changed:
        print(f"    改值 {c['path']}：{c['from']} → {c['to']}")
    print(f"  触及段 {len(touched)} 个：" + "、".join(f"{s}×{n}" for s, n in sorted(touched.items())))
    print("变更影响面（读该段的源码文件数）：")
    for s, info in impact.items():
        ex = "、".join(info["examples"]) if info["examples"] else "（无）"
        print(f"  {s:<10} 被 {info['referrers']:>2} 个文件读  例：{ex}")
    for p in problems:
        print(f"FAIL {p}")
    if problems:
        return 1
    print("OK na_15_3_spec_diff：变更是纯增量的，触及段全部给出影响面")
    return 0


if __name__ == "__main__":
    sys.exit(main())

v1 → v2 结构 diff（v2 由 sim/na_02_migrate.py 产出）
  新增键 66 个，删除键 0 个，改值 1 处
    改值 meta.spec_version：1 → 2
  触及段 4 个：beats×16、dialogue×48、meta×2、metrics×1
变更影响面（读该段的源码文件数）：
  beats      被 19 个文件读  例：sim/na_00_spec_check.py、sim/na_00_toc_scale.py、sim/na_01_skeleton.py
  dialogue   被 43 个文件读  例：sim/na_00_spec_check.py、sim/na_00_toc_scale.py、sim/na_01_line_render.py
  meta       被 26 个文件读  例：sim/na_00_spec_check.py、sim/na_00_toc_scale.py、sim/na_01_skeleton.py
  metrics    被  8 个文件读  例：sim/na_01_skeleton.py、sim/na_01_spec_parse.py、sim/na_02_field_usage.py
OK na_15_3_spec_diff：变更是纯增量的，触及段全部给出影响面