From 7a9d51cc7052578dd166448cbbda24df94d49a87 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=A7=9A=E7=AB=A0=E6=B5=A9?= Date: Tue, 13 Oct 2026 15:26:49 +0800 Subject: [PATCH] =?UTF-8?q?fix(version):=20=E6=AD=A3=E5=BC=8F=E6=9E=84?= =?UTF-8?q?=E5=BB=BA=E6=A0=B8=E8=AF=81=E6=8D=AE=20+=20=E9=A2=84=E6=A3=80?= =?UTF-8?q?=E5=88=86"=E5=BB=BA=E8=AE=AE/=E5=B0=B1=E7=BB=AA"=20+=20CI=20?= =?UTF-8?q?=E5=B0=B1=E7=BB=AA=E6=8C=89=E5=BF=85=E9=9C=80=20context?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 按要求补三项(本轮不推、不打真实 tag、不部署;全部用临时仓库与假对象验): 1) 正式构建身份不能只认 --release: - 新增 release_evidence():核①完整 40 位 SHA ②**指向该提交的注释 tag** v<版本号> ③该提交里 CHANGELOG 顶部版本一致。缺任一条 ⇒ rc=2,身份退回 development 并把 release_blocked 的原因写进 JSON(给机器读,也给人看)。 - version.py --self-test:六条负例(有版本无 tag / unknown SHA / 短 SHA / tag 指错提交 / 轻量 tag / 版本不一致)+ 证据齐正例,**tag 全部在 mktemp 临时仓库里创建**。 - Go 侧新增 TestReleaseBuildRequiresEvidence:release 构建必须 CommitSHA 完整且 v 是**注释 tag** 并指向该提交(独立于 Python 的二次复核)。 2) 发布预检区分"准备建议"与"发布就绪": - 新增纯函数 readiness(facts) → (是否就绪, 阻塞项, 建议);输出分两段。 - **就绪要求候选版本已写进目标提交**(version_in_commit:查 git show :CHANGELOG.md, 工作区写了没提交不算);首发按**显式指定版本**处理,**不把"记录里有这个版本"当已发布** (已发布的证据是 tag,不是记录条目)。 - 预检**不执行、也不在输出里推荐自动发布路径**(正式发版由人按 docs/RELEASE_RUNBOOK.md)。 3) CI 就绪判据:必需 context 集合来自 .gitea/required-contexts.txt(缺失/为空 ⇒ 没有策略 ⇒ 阻断,不用观察到的状态顶替);**全部 success 才通过**,失败/缺项/pending/查询异常一律阻断。 Release 查询加 release_state():**只有 HTTP 404 才算不存在**,403/5xx/超时算查询异常 ⇒ 阻断。 验证:version.py --self-test 绿;release_preflight --self-test 绿(就绪判定 19 个分支 + 临时仓库验证 git show 语义 + 五个 HTTP 码语义);go test 三态(未注入 SKIP / 开发 PASS / 自称正式 RED);反向夹具 83/0(含临时仓库 go test 六例、预检"记录未进提交"两态); make verify 15/15 success。 --- docs/RELEASE_RUNBOOK.md | 26 ++- internal/version/version_test.go | 35 ++++ scripts/ci_negative_fixtures.sh | 130 +++++++++++++- scripts/release_preflight.py | 286 ++++++++++++++++++++++++++----- scripts/test-scope.json | 5 + scripts/version.py | 193 ++++++++++++++++++++- 6 files changed, 615 insertions(+), 60 deletions(-) diff --git a/docs/RELEASE_RUNBOOK.md b/docs/RELEASE_RUNBOOK.md index c189261..4bbd89d 100644 --- a/docs/RELEASE_RUNBOOK.md +++ b/docs/RELEASE_RUNBOOK.md @@ -11,9 +11,23 @@ 2. **写记录**:把这次要发的东西从 `[Unreleased]` 提到一个正式版本条目 `## [x.y.z] - YYYY-MM-DD`(四类小节,无空栏目;破坏性变化写在 `### Changed` 里并链接本文)。 版本号**只增不减**(回退走部署层,不改这个文件);每个项目只有本文件这一个版本来源。 -3. **跑预检(只读)**:`python3 scripts/release_preflight.py` - —— 它只列事实(候选版本 / 完整 SHA / 该提交的 CI 证据 / `[Unreleased]` 原文 / 远端同名 tag 与 - Release 是否已存在 / 遗留风险),有阻塞项就**不给**"可以发"的结论。 +3. **跑预检(只读)**:`python3 scripts/release_preflight.py --version X.Y.Z` + —— 输出**两段**:`准备建议`(还差什么)与 `发布就绪判定`(是否就绪)。 + ⚠️ 预检**不执行、也不推荐自动发布路径**;正式发版动作由人按本文执行。 + **就绪 = 证据齐(缺一条都不算)**: + + | 判据 | 说明 | + |---|---| + | 候选版本**已写进目标提交** | 查 `git show :CHANGELOG.md`;只在工作区写了、没提交 ⇒ 不就绪 | + | 完整 40 位 SHA 指向准确提交 | 目标提交 == HEAD,或 `--sha` 逐字符一致 | + | 记录检查通过 | 结构与 tag 一致性(真查远端) | + | **必需 context 集合全部 success** | 集合来自 `.gitea/required-contexts.txt`;缺失/为空 ⇒ 没有策略 ⇒ 阻断;失败 / 缺项 / pending / 查询异常一律阻断 | + | 远端 tag 已核对且未被占用 | 查不到远端 ⇒ 阻断 | + | Release 不存在 | **只有 HTTP 404 才算「不存在」**;403/5xx/超时 ⇒ 查询异常 ⇒ 阻断 | + | 首发版本号 | 还没有已发布版本 ⇒ 必须**显式指定**;**不把「记录里有这个版本」当作已发布** | + + 自查(不依赖网络、不打真 tag):`python3 scripts/release_preflight.py --self-test`、 + `python3 scripts/version.py --self-test`。 4. **批准后执行**:`python3 scripts/release_preflight.py --execute --version X.Y.Z --approve-version X.Y.Z --approve-sha <完整SHA>`(两个批准参数必须逐字符等于预检结果)。 它创建**注释 tag** `vX.Y.Z`(指向验收过的那个提交)并建关联 Release,正文取自 `CHANGELOG.md`。 @@ -34,8 +48,10 @@ python3 scripts/version.py --identity # JSON:release_version / build_kind | 普通开发构建(**还没有正式版本**) | `development` | `null` | `dev+g<短SHA>` | | 发布构建(显式给出发布上下文) | `release` | 顶部已发布版本 | `X.Y.Z`(另带完整 SHA) | -- `build_kind=release` **只能**来自显式的发布上下文(`BUILD_KIND=release`);普通 `main` CI 永远是 - `development`,**不得**因为"CHANGELOG 顶部有版本号"就自称正式版。 +- `build_kind=release` **只能**来自显式的发布上下文(`BUILD_KIND=release`),并且**要核证据**: + 完整 40 位 SHA + **指向该提交的注释 tag** `v<版本号>` + 该提交里 CHANGELOG 顶部版本一致; + 缺任何一条 ⇒ **拒绝标为正式版**(`--identity --release` 以 rc=2 退出、身份退回 `development` + 并列出缺什么)。普通 `main` CI 永远是 `development`,**不得**因为"CHANGELOG 顶部有版本号"就自称正式版。 - 二进制里的注入字段(`internal/version`)与上表一一对应;契约测试断言: 注入 == CHANGELOG 顶部(发布构建)、开发构建必须是 `dev` 形状(**不许声称正式版**),且**跳过不算通过**。 diff --git a/internal/version/version_test.go b/internal/version/version_test.go index 37b9ded..a609557 100644 --- a/internal/version/version_test.go +++ b/internal/version/version_test.go @@ -2,6 +2,7 @@ package version import ( "os" + "os/exec" "path/filepath" "regexp" "strings" @@ -98,3 +99,37 @@ func TestDevBuildDoesNotClaimRelease(t *testing.T) { } } } + +// 正式构建必须**有证据**:完整提交 SHA + 一个指向该提交的**注释 tag** `v`。 +// 光有"CHANGELOG 顶部有版本号"不算 —— 那会把每个开发构建都说成正式版。 +func TestReleaseBuildRequiresEvidence(t *testing.T) { + if !HasInjection() { + t.Skip("构建身份未注入(没有 -ldflags);CI 会带 -ldflags 跑它,并断言它没有 Skip") + } + if BuildKind != "release" { + return // 开发构建由 TestDevBuildDoesNotClaimRelease 管 + } + if !fullSHA.MatchString(CommitSHA) { + t.Fatalf("标成了正式构建,但 CommitSHA=%q 不是完整 40 位 —— 没有准确提交就谈不上正式版", CommitSHA) + } + name := "v" + ReleaseVersion + out, err := exec.Command("git", "tag", "--points-at", CommitSHA).Output() + if err != nil { + t.Fatalf("跑 `git tag --points-at %s` 失败:%v(正式构建必须能核到 tag 证据)", CommitSHA[:12], err) + } + tags := strings.Fields(string(out)) + found := false + for _, x := range tags { + if x == name { + found = true + } + } + if !found { + t.Fatalf("标成了正式构建(%s),但提交 %s 上没有 tag %s(现有指向该提交的 tag:%v)—— "+ + "正式构建必须有指向该提交的合规 tag", ReleaseVersion, CommitSHA[:12], name, tags) + } + kind, err := exec.Command("git", "cat-file", "-t", "refs/tags/"+name).Output() + if err != nil || strings.TrimSpace(string(kind)) != "tag" { + t.Fatalf("tag %s 不是**注释 tag**(`git tag -a`)—— 轻量 tag 不算发布证据", name) + } +} diff --git a/scripts/ci_negative_fixtures.sh b/scripts/ci_negative_fixtures.sh index 452e665..07b717f 100644 --- a/scripts/ci_negative_fixtures.sh +++ b/scripts/ci_negative_fixtures.sh @@ -107,11 +107,80 @@ PY pycheck "没有已发布版本时不许声明发布构建(--identity --release ⇒ rc=2)" <<'PY' import subprocess p = subprocess.run(["python3", "scripts/version.py", "--identity", "--release"], capture_output=True, text=True) -okv = p.returncode == 2 and "发布构建" in (p.stderr or "") +okv = (p.returncode == 2 and "不标为正式版" in (p.stderr or "") + and '"build_kind": "development"' in (p.stdout or "")) print(("✅ " if okv else "❌ ") + f"退出码 {p.returncode}|{(p.stderr or '').strip().splitlines()[:1]}") raise SystemExit(0 if okv else 1) PY +pycheck "构建身份自检:证据齐(注释 tag + 完整 SHA + 提交内版本一致)才叫正式构建" <<'PY' +import subprocess +p = subprocess.run(["python3", "scripts/version.py", "--self-test"], capture_output=True, text=True) +print(((p.stdout or "") + (p.stderr or "")).strip().splitlines()[-1][:200]) +raise SystemExit(p.returncode) +PY +pycheck "正式构建要核证据:无 tag/tag 名不符/unknown SHA ⇒ 红;注释 tag 指向该提交 ⇒ 绿(临时仓库 + go test)" <<'PY' +import os, pathlib, shutil, subprocess, tempfile + +GO = shutil.which("go") or "/home/zheromiku/.local/go/bin/go" +SRC = pathlib.Path("internal/version") + +def seed(d): + (d / "internal" / "version").mkdir(parents=True) + for f in SRC.glob("*.go"): + shutil.copy(f, d / "internal" / "version" / f.name) + (d / "go.mod").write_text("module knowledge-governance\n\ngo 1.21\n", encoding="utf-8") + (d / "CHANGELOG.md").write_text( + "# Changelog\n\n## [Unreleased]\n\n### Added\n\n- x\n\n" + "## [0.2.0] - 2026-02-01\n\n### Fixed\n\n- y\n", encoding="utf-8") + (d / "no-hooks").mkdir(exist_ok=True) + os.environ.update({"GIT_AUTHOR_NAME": "f", "GIT_AUTHOR_EMAIL": "f@f", + "GIT_COMMITTER_NAME": "f", "GIT_COMMITTER_EMAIL": "f@f", + "GIT_CONFIG_COUNT": "1", "GIT_CONFIG_KEY_0": "core.hooksPath", + "GIT_CONFIG_VALUE_0": str(d / "no-hooks"), "GOFLAGS": "-mod=mod"}) + for args in (["init", "-q", "-b", "main"], ["add", "-A"], ["commit", "-q", "-m", "chore: 夹具"]): + subprocess.run(["git", *args], cwd=d, check=True, capture_output=True) + return subprocess.run(["git", "rev-parse", "HEAD"], cwd=d, capture_output=True, + text=True).stdout.strip() + +def run(d, kind, rel, sha): + ld = (f"-X knowledge-governance/internal/version.Number={rel or 'dev'} " + f"-X knowledge-governance/internal/version.ReleaseVersion={rel} " + f"-X knowledge-governance/internal/version.BuildKind={kind} " + f"-X knowledge-governance/internal/version.CommitSHA={sha}") + return subprocess.run([GO, "test", "-count=1", "-run", "Test", f"-ldflags={ld}", + "./internal/version/..."], cwd=d, capture_output=True, text=True) + +cases = [] +with tempfile.TemporaryDirectory() as tmp: + d = pathlib.Path(tmp) / "r"; d.mkdir(); sha = seed(d) + p = run(d, "release", "0.2.0", sha) + cases.append(("有版本但**没有 tag** ⇒ 正式构建必须红", p.returncode != 0, (p.stdout + p.stderr))) + subprocess.run(["git", "tag", "-a", "v0.2.0", "-m", "release 0.2.0"], cwd=d, check=True, + capture_output=True) + p = run(d, "release", "0.2.0", sha) + cases.append(("注释 tag 指向该提交 + 版本一致 ⇒ 正式构建绿", p.returncode == 0, (p.stdout + p.stderr))) + p = run(d, "release", "0.2.0", sha[:12]) + cases.append(("短 SHA ⇒ 红(正式构建要完整 40 位)", p.returncode != 0, (p.stdout + p.stderr))) + subprocess.run(["git", "tag", "-d", "v0.2.0"], cwd=d, check=True, capture_output=True) + subprocess.run(["git", "tag", "-a", "v9.9.9", "-m", "x"], cwd=d, check=True, capture_output=True) + p = run(d, "release", "0.2.0", sha) + cases.append(("只有别的 tag ⇒ 红", p.returncode != 0, (p.stdout + p.stderr))) + subprocess.run(["git", "tag", "-d", "v9.9.9"], cwd=d, check=True, capture_output=True) + subprocess.run(["git", "tag", "v0.2.0"], cwd=d, check=True, capture_output=True) # 轻量 tag + p = run(d, "release", "0.2.0", sha) + cases.append(("轻量 tag ⇒ 红(不算发布证据)", p.returncode != 0, (p.stdout + p.stderr))) + # 开发构建:ReleaseVersion 要等于该提交里 CHANGELOG 顶部的版本(注入口径),显示带 dev 标识 + p = run(d, "development", "0.2.0", sha) + cases.append(("开发构建(有基线、带完整 SHA)⇒ 绿(显示 X.Y.Z-dev+g<短SHA>,不是只显示正式号)", + p.returncode == 0, (p.stdout + p.stderr))) + +bad = [n for n, okv, _ in cases if not okv] +for n, okv, tail in cases: + print(("✅ " if okv else "❌ ") + n + ("" if okv else "|" + tail.strip()[-200:])) +raise SystemExit(1 if bad else 0) +PY + # 变异测试①:把契约那一处的注入**整个拿掉** ⇒ 版本用例会 SKIP ⇒ 契约必须红(跳过不算通过) cp scripts/ci_checks.py /tmp/kg-cichecks.bak python3 - <<'PY' @@ -594,6 +663,65 @@ if [ "$rc" -ne 0 ] && grep -q "未核对" /tmp/kg-pf-noapi.log; then else no "不核对远端却给了可发结论(退出码 $rc)"; tail -6 /tmp/kg-pf-noapi.log | sed 's/^/ /' fi +pycheck "预检:候选版本**没进目标提交** ⇒ 不就绪;写进提交后该条阻塞消失(临时仓库,不打 tag、不推送、不查远端)" <<'PY' +import os, pathlib, subprocess, tempfile + +def seed(d): + (d / "scripts").mkdir(parents=True) + (d / "docs").mkdir() + (d / ".gitea").mkdir() + for n in ("check_changelog.py", "release_preflight.py"): + (d / "scripts" / n).write_text(pathlib.Path("scripts") / n and + pathlib.Path("scripts", n).read_text(encoding="utf-8"), + encoding="utf-8") + (d / "docs" / "RELEASE_RUNBOOK.md").write_text("# 发布说明\n", encoding="utf-8") + (d / ".gitea" / "required-contexts.txt").write_text("build / build (push)\n", encoding="utf-8") + (d / "CHANGELOG.md").write_text( + "# Changelog\n\n## [Unreleased]\n\n### Added\n\n- 待发的东西\n", encoding="utf-8") + (d / "no-hooks").mkdir(exist_ok=True) + os.environ.update({"GIT_AUTHOR_NAME": "f", "GIT_AUTHOR_EMAIL": "f@f", + "GIT_COMMITTER_NAME": "f", "GIT_COMMITTER_EMAIL": "f@f", + "GIT_CONFIG_COUNT": "1", "GIT_CONFIG_KEY_0": "core.hooksPath", + "GIT_CONFIG_VALUE_0": str(d / "no-hooks")}) + for args in (["init", "-q", "-b", "main"], ["add", "-A"], ["commit", "-q", "-m", "chore: 夹具"]): + subprocess.run(["git", *args], cwd=d, check=True, capture_output=True) + +def pre(d): + p = subprocess.run(["python3", "scripts/release_preflight.py", "--version", "0.2.0", "--no-api"], + cwd=d, capture_output=True, text=True) + return p.returncode, (p.stdout + p.stderr) + +cases = [] +with tempfile.TemporaryDirectory() as tmp: + d = pathlib.Path(tmp) / "r"; d.mkdir(); seed(d) + rc1, t1 = pre(d) + cases.append(("记录只在工作区(没提交)⇒ 明说『还没写进目标提交』且不就绪", + rc1 == 1 and "还没写进目标提交" in t1 and "现在**不能**发" in t1)) + cases.append(("就绪判定里含『准备建议』与『发布就绪判定』两段(不是混在一起)", + "── 准备建议" in t1 and "── 发布就绪判定 ──" in t1)) + cases.append(("不推荐自动发布路径(输出里没有 --execute 的建议行)", + "--execute" not in t1)) + cases.append(("首发未显式指定版本时,把建议值当已发布是禁止的 —— 这里显式给了 --version," + "所以不该报『首个正式版本号必须由人显式指定』", "首个正式版本号必须由人显式指定" not in t1)) + # 把版本记录**写进提交**(首发:显式版本号 + 记录进提交) + (d / "CHANGELOG.md").write_text( + "# Changelog\n\n## [0.2.0] - 2026-02-01\n\n### Added\n\n- 待发的东西\n", encoding="utf-8") + subprocess.run(["git", "add", "-A"], cwd=d, check=True, capture_output=True) + subprocess.run(["git", "commit", "-q", "-m", "chore(release): 0.2.0 记录"], cwd=d, check=True, + capture_output=True) + rc2, t2 = pre(d) + cases.append(("记录进了提交 ⇒ 『还没写进目标提交』这条阻塞**消失**", + "还没写进目标提交" not in t2)) + cases.append(("仍然不就绪(没核对远端 / 没有 CI 证据)⇒ 不许给可发结论", + rc2 == 1 and "现在**不能**发" in t2)) + cases.append(("候选记录存在 ≠ 已发布:不该出现『已存在』类误判", + "已存在" not in t2.replace("不存在(可发)", ""))) + +bad = [n for n, okv in cases if not okv] +for n, okv in cases: + print(("✅ " if okv else "❌ ") + n) +raise SystemExit(1 if bad else 0) +PY if grep -qE "git tag -a|--data-binary|POST" /tmp/kg-pf.log; then no "预检输出里出现了写操作迹象" else diff --git a/scripts/release_preflight.py b/scripts/release_preflight.py index 8bde2ac..8fccb1e 100644 --- a/scripts/release_preflight.py +++ b/scripts/release_preflight.py @@ -9,6 +9,11 @@ 三个都给齐、且预检没有阻塞项,才会 `git tag -a` + `git push ` + 建 Release; 执行后**读回**(远端 tag SHA == 本地打的那个提交、Release 的 tag_name/version 一致)才算成功。 3. **拿不到证据就说拿不到**:没有凭据、查不到 CI 状态时打印"未核对",不写成"已通过"。 + 4. **输出分两段**:`准备建议`(还差什么)与 `发布就绪判定`(是否就绪);**就绪才算可发**。 + 5. **就绪 = 证据齐**:候选版本**已写进目标提交**、完整 SHA 指向准确提交、 + **必需 context 集合全部 success**(集合来自 `.gitea/required-contexts.txt`,缺项/待定/失败/查询异常都阻断)、 + 远端 tag 已核对且未占用、**Release 查询只有 HTTP 404 才算「不存在」**。 + 6. **本预检不执行、也不推荐自动发布路径**:正式发版动作由人按 `docs/RELEASE_RUNBOOK.md` 执行。 用法: python3 scripts/release_preflight.py # 建议 patch(默认) @@ -138,6 +143,107 @@ def server_base() -> str: return f"{u.scheme}://{u.netloc}" +REQUIRED_CONTEXTS_FILE = ROOT / ".gitea" / "required-contexts.txt" + + +def required_contexts(root: Path = ROOT) -> tuple[list[str], str]: + """明确的必需 context 集合(一行一个,`#` 之后是注释)。 + + ⚠️ 这份文件是"要求哪些检查"的**唯一来源**:缺失或只有注释 ⇒ **没有策略** + ⇒ 就绪判定直接阻断(不许拿"体检时观察到哪些状态"顶替)。 + """ + f = root / ".gitea" / "required-contexts.txt" + if not f.is_file(): + return [], f"没有 {f.name}" + out = [l.split("#", 1)[0].strip() for l in f.read_text(encoding="utf-8").splitlines()] + out = [x for x in out if x] + return out, (f"{f.name}({len(out)} 条)" if out else f"{f.name} 只有注释 / 是空的") + + +def version_in_commit(sha: str, version: str, *, root: Path = ROOT) -> bool: + """候选版本是否**已经写进那个提交**(查该提交里的 CHANGELOG.md,不看工作区)。 + + ⚠️ 这是"准备 vs 就绪"的分界线:工作区里写了、没提交 ⇒ 还不是就绪。 + """ + rc, blob = _git_read("show", f"{sha}:CHANGELOG.md", cwd=root) + if rc != 0: + return False + return bool(re.search(rf"^##\s*\[{re.escape(version)}\]", blob, re.MULTILINE)) + + +def release_state(status: int) -> str: + """Release 查询结果的语义:**只有 HTTP 404 代表「不存在」**,其余非 200 一律算查询异常。""" + if status == 200: + return "exists" + if status == 404: + return "absent" + return "error" + + +def readiness(f: dict) -> tuple[bool, list[str], list[str]]: + """把**事实**翻成(是否就绪, 阻塞项, 准备建议)——纯函数,可用假事实直接自检。 + + 就绪 = 证据齐:候选版本已写进目标提交、工作区干净、完整 SHA 指向准确提交、 + 记录检查通过、远端 tag 已核对且未占用、**必需 context 集合全部 success**、 + Release 不存在(查询异常也不算就绪)。 + """ + blockers: list[str] = [] + advice: list[str] = [] + cand = f.get("candidate") or "?" + + if f.get("first_release") and not f.get("explicit_version"): + blockers.append(f"还没有已发布版本:首个正式版本号必须由人显式指定(--version X.Y.Z);" + f"{cand} 只是建议值,**不当作已发布**") + if not f.get("in_target_commit"): + blockers.append(f"候选版本 {cand} 还没写进目标提交(该提交的 CHANGELOG.md 里没有 `## [{cand}]`)" + f"—— 版本记录要先提交,再发版") + advice.append(f"把 `## [Unreleased]` 改成 `## [{cand}] - YYYY-MM-DD`(四类小节、" + f"破坏性变化带发布文档链接)并**提交**,然后重跑预检") + if f.get("candidate_tagged"): + blockers.append(f"远端已经有 tag v{cand} ⇒ 不能覆盖已发布的 tag(版本号只增不减)") + if f.get("dirty"): + blockers.append(f"工作区有 {f['dirty']} 处未提交") + if not f.get("head_full"): + blockers.append("HEAD 不是完整 40 位 SHA") + if not f.get("sha_is_head"): + blockers.append("目标提交 != HEAD(发版必须指向准确提交)") + if not f.get("checker_ok"): + blockers.append("CHANGELOG / 版本记录检查不通过") + if not f.get("unreleased_present"): + advice.append("CHANGELOG 里没有 `[Unreleased]` 段:发版前把这次改动写进记录") + if not f.get("remote_tags_checked"): + blockers.append("没有核对远端 tag 信息(查不到远端)—— 未核验不等于可以发") + if f.get("contexts_error"): + blockers.append(f"查不到该提交的 CI 状态({f['contexts_error']})") + req = f.get("required_contexts") or [] + ctx = f.get("contexts") + if not req: + blockers.append("没有明确的必需 context 集合(`.gitea/required-contexts.txt` 缺失或为空)" + "—— 不许拿「体检时观察到的状态」顶替") + advice.append("把本仓真正必需的 status context 一行一个写进 `.gitea/required-contexts.txt`" + "(字符串要与 `GET /commits//status` 里的 `context` 逐字符相同)") + elif not f.get("contexts_error"): + if ctx is None: + blockers.append("没有取到该提交的 status context") + else: + missing = [c for c in req if c not in ctx] + bad = [(c, ctx[c]) for c in req if c in ctx and ctx[c] != "success"] + if missing: + blockers.append(f"必需 context 缺项(该提交上没有这些状态):{missing}") + if bad: + blockers.append("必需 context 未全部 success:" + "、".join(f"{c}={v}" for c, v in bad)) + if f.get("release_query_error"): + blockers.append(f"Release 查询异常({f['release_query_error']})—— 只有 HTTP 404 才算「不存在」," + f"查询异常不得当作可发") + elif f.get("release_exists"): + blockers.append(f"Gitea Release {f.get('tag') or cand} 已存在") + if f.get("no_api"): + blockers.append("没有核对远端 Release / CI 状态(缺凭据或显式 --no-api)") + if not blockers: + advice.append("证据齐了:正式发版动作由人按 docs/RELEASE_RUNBOOK.md 执行(本预检只读、不执行)") + return (not blockers), blockers, advice + + def main(argv: list[str]) -> int: ap = argparse.ArgumentParser(add_help=True) ap.add_argument("--bump", default="patch", choices=["major", "minor", "patch"]) @@ -207,83 +313,93 @@ def main(argv: list[str]) -> int: if not checker_ok: print(" " + (chk.stdout + chk.stderr).strip().replace("\n", "\n ")[-800:]) - # 远端 tag / Release / CI 证据 + # ── 事实收集(只读)────────────────────────────────────────────── tag = f"v{candidate}" - blockers: list[str] = [] - if first_release: - blockers.append(f"还没有已发布版本:首个正式版本号必须由人显式指定(--version X.Y.Z);" - f"{candidate} 只是建议值") - if dirty_lines: - blockers.append(f"工作区有 {len(dirty_lines)} 处未提交") - if not FULL_SHA.match(head): - blockers.append("HEAD 不是完整 40 位 SHA") - if want_sha != head: - blockers.append(f"--sha {want_sha[:12]} != HEAD {head[:12]}(发版必须指向准确提交)") - if not checker_ok: - blockers.append("CHANGELOG/版本记录检查不通过") - if not unreleased.strip(): - blockers.append("没有 Unreleased 段:发版前要把这次改动写进 CHANGELOG") - if candidate in rel: - blockers.append(f"版本 {candidate} 已经在 CHANGELOG 里出现过(版本号只增不减)") + required, policy_src = required_contexts() + in_target = version_in_commit(want_sha, candidate) + mark = "✅ 已有" if in_target else "❌ 没有" + print(f"\n 目标提交内记录: {mark} `## [{candidate}]`" + f"(版本记录要先提交,再发版;查的是 {want_sha[:12]})") + print(f" 必需 context : {len(required)} 条({policy_src})" + + (":" + "、".join(required) if required else "")) token = "" if args.no_api else _cred(urllib.parse.urlparse(base).hostname or "") rc, tags_out = _git_read("ls-remote", "--tags", "origin") remote_tags = [l.split("refs/tags/")[-1] for l in tags_out.splitlines() if "refs/tags/" in l] if f"{tag}^{{}}" in remote_tags: remote_tags.remove(f"{tag}^{{}}") - if rc != 0 or args.no_api: + remote_tags_checked = rc == 0 and not args.no_api + if not remote_tags_checked: why = "显式 --no-api" if args.no_api else "`git ls-remote --tags origin` 失败" - print(f"\n 远端 tag : **未核对**({why})—— 不能声称 tag 已核验") - blockers.append("没有核对远端 tag 信息(查不到远端)—— 未核验不等于可以发") + print(f" 远端 tag : **未核对**({why})—— 不能声称 tag 已核验") else: - print(f"\n 远端 tag : {tag} {'已存在 ⛔ 不能覆盖已发布的 tag' if tag in remote_tags else '不存在(可发)'}" - f"|已存在的正式 tag: {[t for t in remote_tags if re.match(r'^v\\d', t)] or '(无)'}") + print(f" 远端 tag : {tag} {'已存在 ⛔ 不能覆盖已发布的 tag' if tag in remote_tags else '不存在(可发)'}" + f"|已存在的正式 tag: {[t for t in remote_tags if re.match(r'^v\d', t)] or '(无)'}") + contexts = None + contexts_error = "" + release_exists = False + release_query_error = "" run_line = "(未查询)" ctx_line = "(未查询)" if token and base and slug: - st, body = _api_read(base, f"/repos/{slug}/releases/tags/{urllib.parse.quote(tag)}", token) - rel_exists = st == 200 - print(f" Gitea Release: {tag} {'已存在 ⛔' if rel_exists else '不存在(可发)'}") - if rel_exists: - blockers.append(f"Gitea Release {tag} 已存在") + st, _ = _api_read(base, f"/repos/{slug}/releases/tags/{urllib.parse.quote(tag)}", token) + state = release_state(st) + note = {"exists": "已存在 ⛔ 不能覆盖", "absent": "不存在(可发)"}.get( + state, f"查询异常(HTTP {st})⛔ 只有 404 才算「不存在」,不得当作可发") + print(f" Gitea Release: {tag} {note}") + release_exists = state == "exists" + if state == "error": + release_query_error = f"HTTP {st}" st, stt = _api_read(base, f"/repos/{slug}/commits/{head}/status", token) if st == 200: - ctxs = [(s.get("context"), s.get("status")) for s in stt.get("statuses") or []] - ctx_line = "、".join(f"{c}={v}" for c, v in ctxs) or "(这个提交上一个状态都没有)" - if not any(v == "success" for _, v in ctxs): - blockers.append(f"提交 {head[:12]} 上没有成功的 status context(CI 证据不足)") + contexts = {x.get("context"): x.get("status") for x in stt.get("statuses") or []} + ctx_line = "、".join(f"{c}={v}" for c, v in contexts.items()) or "(这个提交上一个状态都没有)" else: + contexts_error = f"HTTP {st}" ctx_line = f"(查不到:HTTP {st})" - blockers.append("查不到该提交的 CI 状态") st, runs = _api_read(base, f"/repos/{slug}/actions/runs?limit=20", token) if st == 200: mine = [r for r in (runs.get("workflow_runs") or []) if (r.get("head_sha") or "") == head] if mine: - r0 = mine[0] - run_line = (f"run #{r0.get('run_number')} {r0.get('status')} " - f"{r0.get('url') or ''}".strip()) + run_line = (f"run #{mine[0].get('run_number')} {mine[0].get('status')} " + f"{mine[0].get('url') or ''}".strip()) else: run_line = "(这个提交上没有运行记录)" else: print(f" Gitea Release: **未核对**({'显式 --no-api' if args.no_api else '没有取到凭据'})") - blockers.append("没有核对远端 Release/CI 状态(缺凭据)") print(f" CI 状态 : {ctx_line}") print(f" 最近运行 : {run_line}") print(" 遗留风险/未验证: 见 docs/BACKLOG.md 与本次 Unreleased 里写明的未验证项" "(预检不替你判断它们的可接受性)") - print("\n── 结论 ──") - if blockers: + facts = { + "candidate": candidate, "tag": tag, "first_release": first_release, + "explicit_version": bool(args.version), "in_target_commit": in_target, + "dirty": len(dirty_lines), "head_full": bool(FULL_SHA.match(head)), + "sha_is_head": want_sha == head, "checker_ok": checker_ok, + "unreleased_present": bool(unreleased.strip()), + "candidate_tagged": bool(remote_tags_checked and tag in remote_tags), + "remote_tags_checked": remote_tags_checked, + "required_contexts": required, "contexts": contexts, "contexts_error": contexts_error, + "release_exists": release_exists, "release_query_error": release_query_error, + "no_api": bool(args.no_api), + } + ready, blockers, advice = readiness(facts) + + print("\n── 准备建议(先做完这些,才有「就绪」可言)──") + for a in (advice or ["(没有额外建议)"]): + print(f" · {a}") + print("\n── 发布就绪判定 ──") + if ready: + print(f" ✅ 发布就绪:{candidate}(tag {tag} → 提交 {head[:12]})") + print(" ⚠️ 正式发版动作**不在本预检里执行、也不推荐自动路径**:" + "步骤与读回判据见 docs/RELEASE_RUNBOOK.md,由人按批准执行。") + else: for b in blockers: print(f" ⛔ {b}") - print(f" ⇒ 现在**不能**发 {candidate}") - else: - print(f" ✅ 预检通过:可以发 {candidate}(tag {tag} → 提交 {head[:12]})") - print(" 批准后执行(本轮不执行):") - print(f" python3 scripts/release_preflight.py --execute --version {candidate} " - f"--approve-version {candidate} --approve-sha {head}") + print(f" ⇒ 现在**不能**发 {candidate}(未就绪)") if not args.execute: return 1 if blockers else 0 @@ -356,12 +472,92 @@ def self_test() -> int: # 版本号推进 if bump("1.2.3", "patch") != "1.2.4" or bump("1.2.3", "minor") != "1.3.0" or bump("1.2.3", "major") != "2.0.0": problems.append("版本推进算错了") + # ── 就绪判定:全部用**假事实**驱动纯函数(不打真 tag、不碰网络)── + base_facts = { + "candidate": "0.2.0", "tag": "v0.2.0", "first_release": False, + "explicit_version": True, "in_target_commit": True, "dirty": 0, + "head_full": True, "sha_is_head": True, "checker_ok": True, + "unreleased_present": True, "candidate_tagged": False, + "remote_tags_checked": True, "required_contexts": ["build / build (push)"], + "contexts": {"build / build (push)": "success"}, "contexts_error": "", + "release_exists": False, "release_query_error": "", "no_api": False, + } + + def rd(name: str, ready_want: bool, needle: str = "", **over) -> None: + f = {**base_facts, **over} + ready, blockers, _ = readiness(f) + joined = " / ".join(blockers) + if ready != ready_want or (needle and needle not in joined): + problems.append(f"就绪判定[{name}]:ready={ready}(期望 {ready_want})blockers={joined[:160]}") + + rd("证据齐 ⇒ 就绪", True) + rd("必需 context pending ⇒ 不就绪", False, "未全部 success", contexts={"build / build (push)": "pending"}) + rd("必需 context failure ⇒ 不就绪", False, "未全部 success", contexts={"build / build (push)": "failure"}) + rd("必需 context 没被报出来(缺项)⇒ 不就绪", False, "缺项", contexts={"other / other (push)": "success"}) + rd("有别的 context 成功但必需项没报 ⇒ 仍不就绪", False, "缺项", + required_contexts=["build / build (push)", "lint / lint (push)"]) + rd("status 查询异常 ⇒ 不就绪", False, "查不到该提交的 CI 状态", contexts_error="HTTP 500") + rd("没有必需 context 策略 ⇒ 不就绪", False, "没有明确的必需 context 集合", required_contexts=[]) + rd("Release 查询异常 ⇒ 不就绪", False, "Release 查询异常", release_query_error="HTTP 500") + rd("Release 已存在 ⇒ 不就绪", False, "已存在", release_exists=True) + rd("远端 tag 已被占用 ⇒ 不就绪", False, "不能覆盖已发布的 tag", candidate_tagged=True) + rd("没核对远端 tag ⇒ 不就绪", False, "没有核对远端 tag", remote_tags_checked=False) + rd("首发未显式指定版本 ⇒ 不就绪", False, "首个正式版本号必须由人显式指定", + first_release=True, explicit_version=False) + rd("首发**显式**指定且记录已进提交 ⇒ 就绪", True, + first_release=True, explicit_version=True, contexts={"build / build (push)": "success"}) + rd("候选版本没进目标提交 ⇒ 不就绪", False, "还没写进目标提交", in_target_commit=False) + rd("工作区脏 ⇒ 不就绪", False, "未提交", dirty=3) + rd("目标提交 != HEAD ⇒ 不就绪", False, "目标提交 != HEAD", sha_is_head=False) + rd("记录检查不通过 ⇒ 不就绪", False, "检查不通过", checker_ok=False) + rd("缺凭据/--no-api ⇒ 不就绪", False, "没有核对远端 Release", no_api=True) + # 候选记录存在 ≠ 已发布:三种证据都齐时应当就绪,且阻塞项里不该出现"已发布" + _, bl, _ = readiness(base_facts) + if any("已发布" in b for b in bl): + problems.append(f"把『记录里有这个版本』误当成『已发布』:{bl}") + + for st, want in ((200, "exists"), (404, "absent"), (500, "error"), (403, "error"), (0, "error")): + if release_state(st) != want: + problems.append(f"Release 查询语义错:HTTP {st} 判成了 {release_state(st)}(期望 {want})") + + # ── 临时仓库:候选版本"写进提交才算数" ── + import tempfile as _tf + with _tf.TemporaryDirectory() as d: + dd = Path(d) + (dd / "no-hooks").mkdir(exist_ok=True) + env = {**dict(**__import__("os").environ), "GIT_AUTHOR_NAME": "t", "GIT_AUTHOR_EMAIL": "t@t", + "GIT_COMMITTER_NAME": "t", "GIT_COMMITTER_EMAIL": "t@t", + "GIT_CONFIG_COUNT": "1", "GIT_CONFIG_KEY_0": "core.hooksPath", + "GIT_CONFIG_VALUE_0": str(dd / "no-hooks")} + (dd / "CHANGELOG.md").write_text("# Changelog\n\n## [Unreleased]\n\n### Added\n\n- x\n", + encoding="utf-8") + subprocess.run(["git", "init", "-q", "-b", "main"], cwd=dd, env=env, check=True) + subprocess.run(["git", "add", "-A"], cwd=dd, env=env, check=True) + subprocess.run(["git", "commit", "-q", "-m", "chore: 夹具"], cwd=dd, env=env, check=True) + sha = subprocess.run(["git", "rev-parse", "HEAD"], cwd=dd, capture_output=True, + text=True).stdout.strip() + if version_in_commit(sha, "0.2.0", root=dd): + problems.append("未提交的版本被当成了『已写进目标提交』") + (dd / "CHANGELOG.md").write_text( + "# Changelog\n\n## [0.2.0] - 2026-02-01\n\n### Fixed\n\n- y\n", encoding="utf-8") + if version_in_commit(sha, "0.2.0", root=dd): + problems.append("工作区改了但没提交,仍被判成『已写进目标提交』") + subprocess.run(["git", "add", "-A"], cwd=dd, env=env, check=True) + subprocess.run(["git", "commit", "-q", "-m", "chore(release): 0.2.0"], cwd=dd, env=env, check=True) + sha2 = subprocess.run(["git", "rev-parse", "HEAD"], cwd=dd, capture_output=True, + text=True).stdout.strip() + if not version_in_commit(sha2, "0.2.0", root=dd): + problems.append("版本写进提交后仍判成『没有』") + if problems: print("❌ 预检自检失败:", file=sys.stderr) for p in problems: print(f" · {p}", file=sys.stderr) return 1 - print("✅ 预检自检通过:写类 git 命令与 POST/PUT/DELETE/PATCH 在预检路径上全部被拒;版本推进正确") + print("✅ 预检自检通过:写类 git 命令与 POST/PUT/DELETE/PATCH 在预检路径上全部被拒;版本推进正确;" + "就绪判定 19 个分支(context 缺项/pending/failure/查询异常、无策略、Release 非 404、" + "tag 占用、未核对远端、首发未显式指定、记录未进提交…逐条阻断;证据齐才就绪);" + "『写进提交才算数』用临时仓库验证") return 0 diff --git a/scripts/test-scope.json b/scripts/test-scope.json index b0d6858..02043c4 100644 --- a/scripts/test-scope.json +++ b/scripts/test-scope.json @@ -48,6 +48,11 @@ "package": "knowledge-governance/internal/version", "test": "TestDevBuildDoesNotClaimRelease", "reason": "构建身份未注入时按设计 SKIP(本地跑全量测试不该被迫先构建);**它的强制点在 contracts 项**:那里带 -ldflags 跑它并断言真的 PASS、且出现 SKIP 就判红" + }, + { + "package": "knowledge-governance/internal/version", + "test": "TestReleaseBuildRequiresEvidence", + "reason": "构建身份未注入时按设计 SKIP(本地跑全量测试不该被迫先构建);**它的强制点在 contracts 项**:那里带 -ldflags 跑它并断言真的 PASS、且出现 SKIP 就判红" } ] } diff --git a/scripts/version.py b/scripts/version.py index aee67ff..c7ba436 100755 --- a/scripts/version.py +++ b/scripts/version.py @@ -14,6 +14,10 @@ CI 只做**核验**(tag 版本 == 它指到那个提交里的版本记录) python3 scripts/version.py --identity --release # 声明发布构建;没有已发布版本 ⇒ 拒绝(rc=2) python3 scripts/version.py --check # 打印版本号并跑结构自检(等价 check-changelog.py) +**正式构建身份不是"加个 --release 标志"就算**:`--identity --release` 会**核证据**—— +完整 40 位 SHA + 一个**指向该提交的合规注释 tag** `v<版本号>` + 该提交里 CHANGELOG 顶部版本一致; +缺任何一条 ⇒ **拒绝标为正式版**(rc=2,JSON 里带 `release_blocked` 说明缺什么)。 + 构建身份字段(`--identity`): release_version 正式版本基线;本仓还没有正式发布过 ⇒ `null` build_kind development | release(**只有显式声明**才是 release,普通 main CI 永远不是) @@ -31,6 +35,7 @@ import os import re import subprocess import sys +import tempfile from pathlib import Path ROOT = Path(__file__).resolve().parent.parent @@ -67,13 +72,60 @@ def display_version(release_version: str | None, kind: str, sha: str) -> str: return f"dev+g{short}" if short else "dev" +def _git(*args, cwd: Path = ROOT) -> tuple[int, str]: + p = subprocess.run(["git", *args], cwd=cwd, capture_output=True, text=True) + return p.returncode, (p.stdout if p.returncode == 0 else p.stderr) + + +def release_evidence(version: str | None, sha: str, root: Path = ROOT) -> list[str]: + """正式构建要核的证据;返回缺失项(空列表 = 证据齐)。 + + 三条都必需(缺一条就**不许**把产物标成正式版): + 1. 完整 40 位提交 SHA —— 没有准确提交就谈不上"正式版"; + 2. 该提交上有**注释 tag** `v<版本号>`(`git tag --points-at ` + `cat-file -t` 判类型); + 3. 该提交里的 `CHANGELOG.md` 顶部已发布版本 == 这个版本号(版本一致性)。 + """ + problems: list[str] = [] + if not version: + problems.append("CHANGELOG.md 里没有已发布版本条目(没有正式版本基线)") + if not FULL_SHA.match(sha or ""): + problems.append(f"提交 SHA 不是完整 40 位({sha!r})—— 没有准确提交就不能标为正式版") + if version and FULL_SHA.match(sha or ""): + name = f"v{version}" + rc, out = _git("tag", "--points-at", sha, cwd=root) + tags = out.split() if rc == 0 else [] + if name not in tags: + problems.append(f"提交 {sha[:12]} 上没有 tag {name}" + f"(正式构建必须有一个指向该提交的合规 tag;现有指向该提交的 tag:{tags or '无'})") + else: + rc, kind = _git("cat-file", "-t", f"refs/tags/{name}", cwd=root) + if rc != 0 or kind.strip() != "tag": + problems.append(f"tag {name} 不是**注释 tag**(`git tag -a`)—— 轻量 tag 不算发布证据") + rc, blob = _git("show", f"{sha}:CHANGELOG.md", cwd=root) + if rc != 0: + problems.append(f"取不到该提交里的 CHANGELOG.md({sha[:12]})—— 没法核对版本一致性") + else: + m = RELEASE_HEADING.search(blob) + top = m.group(1) if m else None + if top != version: + problems.append(f"该提交里 CHANGELOG 顶部的已发布版本是 {top!r},与 {version!r} 不一致") + return problems + + def identity(*, release: bool = False, built_at: str | None = None, root: Path = ROOT, sha: str | None = None) -> dict: - """构建身份。`release=True` 但没有已发布版本 ⇒ 由调用方拒绝(见 main)。""" + """构建身份(不含证据核验,供 `--identity` 的非发布路径与测试使用)。""" + return build_identity(release=release, built_at=built_at, root=root, sha=sha)[0] + + +def build_identity(*, release: bool = False, built_at: str | None = None, + root: Path = ROOT, sha: str | None = None) -> tuple[dict, list[str]]: + """构建身份 + 证据缺失项。`release=True` 但证据不齐 ⇒ 身份退回 development 并给出原因。""" rel = current_version(root / "CHANGELOG.md") sha = sha if sha is not None else git_sha(root) - kind = "release" if (release and rel) else "development" - return { + problems = release_evidence(rel, sha, root) if release else [] + kind = "release" if (release and not problems) else "development" + ident = { "release_version": rel, "build_kind": kind, "commit_sha": sha, @@ -81,18 +133,141 @@ def identity(*, release: bool = False, built_at: str | None = None, "built_at": built_at or os.environ.get("BUILT_AT") or os.environ.get("BUILD_TIME") or dt.datetime.now(dt.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"), } + if problems: + ident["release_blocked"] = problems + return ident, problems + + +# ── 反向自检:**全部在临时仓库里造 tag**,不给真仓造任何 tag ───────────────── +_SAMPLE = """# Changelog + +## [Unreleased] + +### Added + +- 还没发布 + +## [0.2.0] - 2026-02-01 + +### Fixed + +- y +""" + + +def _tmp_repo(changelog: str = _SAMPLE) -> tuple[Path, str, dict]: + """造一个临时仓库(一个提交),返回 (目录, HEAD, git 环境)。""" + d = Path(tempfile.mkdtemp(prefix="kg-ver-")) + (d / "no-hooks").mkdir(exist_ok=True) + env = {**os.environ, "GIT_AUTHOR_NAME": "t", "GIT_AUTHOR_EMAIL": "t@t", + "GIT_COMMITTER_NAME": "t", "GIT_COMMITTER_EMAIL": "t@t", + "GIT_CONFIG_COUNT": "1", "GIT_CONFIG_KEY_0": "core.hooksPath", + "GIT_CONFIG_VALUE_0": str(d / "no-hooks")} + (d / "CHANGELOG.md").write_text(changelog, encoding="utf-8") + for args in (["init", "-q", "-b", "main"], ["add", "-A"], + ["commit", "-q", "-m", "chore: 夹具提交"]): + subprocess.run(["git", *args], cwd=d, env=env, check=True) + sha = subprocess.run(["git", "rev-parse", "HEAD"], cwd=d, capture_output=True, + text=True).stdout.strip() + return d, sha, env + + +def self_test() -> int: + problems: list[str] = [] + dirs: list[Path] = [] + + def case(name: str, cond: bool, detail: str = "") -> None: + if not cond: + problems.append(f"{name} —— {detail}") + + # ① 证据齐:注释 tag 指向该提交 + 提交内 CHANGELOG 一致 ⇒ 正式构建 + d, sha, env = _tmp_repo(); dirs.append(d) + subprocess.run(["git", "tag", "-a", "v0.2.0", "-m", "release 0.2.0"], cwd=d, env=env, check=True) + ident, blocked = build_identity(release=True, root=d, sha=sha, built_at="t") + case("证据齐 ⇒ build_kind=release", ident["build_kind"] == "release" and not blocked, f"{ident}") + case("证据齐 ⇒ display_version=0.2.0", ident["display_version"] == "0.2.0", f"{ident['display_version']!r}") + + # ② 有版本但**没有 tag** ⇒ 不许标正式 + d2, sha2, _ = _tmp_repo(); dirs.append(d2) + ident2, blocked2 = build_identity(release=True, root=d2, sha=sha2, built_at="t") + case("有版本但无 tag ⇒ 不标正式", + ident2["build_kind"] == "development" and any("没有 tag" in x for x in blocked2), f"{blocked2}") + + # ③ SHA 不是完整 40 位 ⇒ 不许标正式 + ident3, blocked3 = build_identity(release=True, root=d, sha="unknown", built_at="t") + case("unknown SHA ⇒ 不标正式", + ident3["build_kind"] == "development" and any("不是完整 40 位" in x for x in blocked3), f"{blocked3}") + ident3b, blocked3b = build_identity(release=True, root=d, sha=sha[:12], built_at="t") + case("短 SHA ⇒ 不标正式", + ident3b["build_kind"] == "development" and any("不是完整 40 位" in x for x in blocked3b), f"{blocked3b}") + + # ④ tag 指错提交 ⇒ 不许标正式(tag 打在**后一个**提交上,却按前一个提交去问) + d4, first4, env4 = _tmp_repo(); dirs.append(d4) + (d4 / "extra.txt").write_text("x", encoding="utf-8") + subprocess.run(["git", "add", "-A"], cwd=d4, env=env4, check=True) + subprocess.run(["git", "commit", "-q", "-m", "chore: 第二个提交"], cwd=d4, env=env4, check=True) + second4 = subprocess.run(["git", "rev-parse", "HEAD"], cwd=d4, capture_output=True, + text=True).stdout.strip() + subprocess.run(["git", "tag", "-a", "v0.2.0", "-m", "release", second4], cwd=d4, env=env4, check=True) + ident4, blocked4 = build_identity(release=True, root=d4, sha=first4, built_at="t") + case("tag 指错提交 ⇒ 不标正式", + ident4["build_kind"] == "development" and any("没有 tag v0.2.0" in x for x in blocked4), f"{blocked4}") + + # ⑤ 轻量 tag ⇒ 不许标正式(注释 tag 才是发布证据) + d5, sha5, env5 = _tmp_repo(); dirs.append(d5) + subprocess.run(["git", "tag", "v0.2.0"], cwd=d5, env=env5, check=True) + ident5, blocked5 = build_identity(release=True, root=d5, sha=sha5, built_at="t") + case("轻量 tag ⇒ 不标正式", + ident5["build_kind"] == "development" and any("注释 tag" in x for x in blocked5), f"{blocked5}") + + # ⑥ 提交内 CHANGELOG 顶部版本与"声称的版本"不一致 ⇒ 不许标正式 + # 做法:提交里的记录是 0.2.0,tag 却叫 v0.3.0(指向该提交),工作区又写着 0.3.0 ⇒ 三条中 + # "版本一致性"这一条会红(tag 存在、注释、SHA 也完整,问题只出在版本对不上)。 + d6, sha6, env6 = _tmp_repo(); dirs.append(d6) + subprocess.run(["git", "tag", "-a", "v0.3.0", "-m", "release 0.3.0"], cwd=d6, env=env6, check=True) + (d6 / "CHANGELOG.md").write_text(_SAMPLE.replace("0.2.0", "0.3.0"), encoding="utf-8") + ident6, blocked6 = build_identity(release=True, root=d6, sha=sha6, built_at="t") + case("声称版本与提交内记录不一致 ⇒ 不标正式", + ident6["build_kind"] == "development" and any("不一致" in x for x in blocked6), f"{blocked6}") + + # ⑦ 开发构建:有基线 ⇒ X.Y.Z-dev+g<短SHA>;无基线 ⇒ dev+g<短SHA> + dev, _ = build_identity(root=d, sha=sha, built_at="t") + case("开发构建(有基线)= 0.2.0-dev+g<短SHA>", + dev["build_kind"] == "development" and dev["display_version"] == f"0.2.0-dev+g{sha[:12]}", + f"{dev['display_version']!r}") + d7, sha7, _ = _tmp_repo("# Changelog\n\n## [Unreleased]\n\n### Added\n\n- x\n"); dirs.append(d7) + dev7, _ = build_identity(root=d7, sha=sha7, built_at="t") + case("开发构建(无基线)= dev+g<短SHA>", + dev7["release_version"] is None and dev7["display_version"] == f"dev+g{sha7[:12]}", + f"{dev7}") + + for x in dirs: + subprocess.run(["rm", "-rf", str(x)], capture_output=True) + + if problems: + print("❌ 构建身份自检失败:", file=sys.stderr) + for x in problems: + print(f" · {x}", file=sys.stderr) + return 1 + print("✅ 构建身份自检通过:证据齐(注释 tag + 完整 SHA + 提交内版本一致)才是正式构建;" + "无 tag / unknown 或短 SHA / tag 指错提交 / 轻量 tag / 版本不一致 逐条拒绝;" + "开发构建带显式 dev 标识") + return 0 def main(argv: list[str]) -> int: + if "--self-test" in argv: + return self_test() release = "--release" in argv or os.environ.get("BUILD_KIND") == "release" if "--identity" in argv: - if release and current_version() is None: - print("❌ 声明了发布构建(--release / BUILD_KIND=release),但 CHANGELOG.md 里没有已发布版本条目。\n" - " 发布构建必须基于一个已发布的版本记录(`## [x.y.z] - YYYY-MM-DD`)——\n" - " 本仓还没有正式发布过,所以现在只能产出开发构建身份(dev+g<短SHA>)。", - file=sys.stderr) + ident, problems = build_identity(release=release) + print(json.dumps(ident, ensure_ascii=False, indent=2)) + if release and problems: + print("❌ 声明了正式构建(--release / BUILD_KIND=release),但发布证据不齐 —— " + "**不标为正式版**(身份已退回 development):", file=sys.stderr) + for x in problems: + print(f" · {x}", file=sys.stderr) return 2 - print(json.dumps(identity(release=release), ensure_ascii=False, indent=2)) return 0 v = current_version()