knowledge-governance/scripts/check_changelog.py

#!/usr/bin/env python3
"""CHANGELOG.md 结构自检 —— 把"版本变更要写清改了什么、怎么验收"变成退出码。

判据（每条都能被 --self-test 证明会红）：
  1. 至少有一个已发布版本条目；
  2. 每个已发布版本都带日期（`## [x.y.z] - YYYY-MM-DD`）；`[Unreleased]` 段免检日期；
  3. 每个已发布版本块里**必须有** `### 改了什么` 与 `### 怎么验收` 两节；
  4. 版本号不重复，且按出现顺序**严格递减**（最新在最上面）；
  5. 已发布版本块本身不为空（两节下面得有内容，不能只留个标题）。

用法：
    python3 scripts/check-changelog.py             # 检查仓库根的 CHANGELOG.md
    python3 scripts/check-changelog.py <path>      # 检查指定文件
    python3 scripts/check-changelog.py --self-test # 反向自检：造正/反夹具断言会红会绿

为什么要有 --self-test：一个永远返回 0 的校验器比没有校验更糟 —— 它给人一种
已经检查过的错觉（正本 §0-2）。
"""
from __future__ import annotations

import re
import sys
import tempfile
from pathlib import Path

ROOT = Path(__file__).resolve().parent.parent

HEADING = re.compile(r"^##\s*\[([^\]]+)\](\s*-\s*(\d{4}-\d{2}-\d{2}))?\s*$", re.MULTILINE)
SEMVER = re.compile(r"^\d+\.\d+\.\d+$")
SEC_CHANGE = "### 改了什么"
SEC_ACCEPT = "### 怎么验收"


def _blocks(text: str):
    """把文件切成 [(heading, version, date, body), ...]，保持出现顺序。"""
    out = []
    matches = list(HEADING.finditer(text))
    for i, m in enumerate(matches):
        end = matches[i + 1].start() if i + 1 < len(matches) else len(text)
        out.append((m.group(0), m.group(1), m.group(3), text[m.end():end]))
    return out


def check(path: Path | None = None) -> list[str]:
    path = path or (ROOT / "CHANGELOG.md")
    if not path.is_file():
        return [f"找不到 {path}"]
    blocks = _blocks(path.read_text(encoding="utf-8"))
    released = [b for b in blocks if SEMVER.match(b[1])]
    if not released:
        return ["没有已发布版本条目（形如 `## [0.1.0] - 2026-10-10`）"]

    problems: list[str] = []
    seen: list[str] = []
    for heading, ver, date, body in released:
        seen.append(ver)
        if not date:
            problems.append(f"{heading} 缺少日期（要写成 `## [{ver}] - YYYY-MM-DD`）")
        for sec in (SEC_CHANGE, SEC_ACCEPT):
            if sec not in body:
                problems.append(f"[{ver}] 缺少小节 `{sec}` —— 版本条目必须说明改了什么、怎么验收")
        # 两节下面无内容：只剩标题或空行
        for sec in (SEC_CHANGE, SEC_ACCEPT):
            if sec in body:
                tail = body.split(sec, 1)[1]
                tail = re.split(r"^###\s", tail, maxsplit=1, flags=re.MULTILINE)[0]
                if not [l for l in tail.splitlines() if l.strip() and not l.strip().startswith("```")][:1]:
                    problems.append(f"[{ver}] 的 `{sec}` 下面是空的")
    dupes = {v for v in seen if seen.count(v) > 1}
    if dupes:
        problems.append(f"版本号重复：{sorted(dupes)}")
    nums = [tuple(int(x) for x in v.split(".")) for v in seen]
    if nums != sorted(nums, reverse=True):
        problems.append(f"版本号没有按出现顺序严格递减（最新应在最上面）：{seen}")
    return problems


GOOD = """# 变更记录

## [Unreleased]

### 改了什么

- 还没发布的东西

## [0.2.0] - 2026-02-01

### 改了什么

- 加了 X

### 怎么验收

1. 跑 `curl /health` 期望 200

## [0.1.0] - 2026-01-01

### 改了什么

- 初版

### 怎么验收

1. 起容器，打开首页
"""

BAD = """# 变更记录

## [0.1.0]

### 改了什么

- 没有日期、没有怎么验收、而且版本顺序还倒着

## [0.2.0] - 2026-02-01

### 改了什么

- 上面那个比这个旧，顺序错了
"""


def self_test() -> int:
    problems: list[str] = []
    with tempfile.TemporaryDirectory() as d:
        g = Path(d) / "good.md"
        b = Path(d) / "bad.md"
        g.write_text(GOOD, encoding="utf-8")
        b.write_text(BAD, encoding="utf-8")
        gk = check(g)
        bk = check(b)
        if gk:
            problems.append(f"合规夹具竟然报红：{gk}")
        want = ["缺少日期", f"缺少小节 `{SEC_ACCEPT}`", "严格递减"]
        joined = " / ".join(bk)
        for w in want:
            if w not in joined:
                problems.append(f"违规夹具没有报出 `{w}` —— 这条判据是死的")
        if not bk:
            problems.append("违规夹具完全没报红")
    if problems:
        print("❌ 反向自检失败：", file=sys.stderr)
        for p in problems:
            print(f"   · {p}", file=sys.stderr)
        return 1
    print("✅ 反向自检通过：合规夹具全绿；违规夹具按预期报出日期/验收节/顺序三类问题")
    return 0


def main(argv: list[str]) -> int:
    if "--self-test" in argv:
        return self_test()
    target = next((a for a in argv if not a.startswith("-")), None)
    problems = check(Path(target) if target else None)
    if problems:
        print("❌ CHANGELOG.md 结构不合规：", file=sys.stderr)
        for p in problems:
            print(f"   · {p}", file=sys.stderr)
        print("\n每个已发布版本都要写成：\n"
              "   ## [x.y.z] - YYYY-MM-DD\n\n   ### 改了什么\n   - …\n\n   ### 怎么验收\n   1. 命令 → 期望现象\n",
              file=sys.stderr)
        return 1
    print("✅ CHANGELOG.md 结构合规")
    return 0


if __name__ == "__main__":
    raise SystemExit(main(sys.argv[1:]))