diff --git a/Dockerfile b/Dockerfile index 86f63c3..bae2c03 100644 --- a/Dockerfile +++ b/Dockerfile @@ -4,15 +4,19 @@ COPY go.mod go.sum ./ RUN go mod download COPY cmd ./cmd COPY internal ./internal -# 构建期身份:由调用方 --build-arg 传入。来源是仓库根 CHANGELOG.md 顶部的已发布版本 -# (`python3 scripts/version.py`),**不要手填**。不传就落成 dev / unknown —— 那是故意的: +# 构建期身份:由调用方 --build-arg 传入。依据是仓库根 CHANGELOG.md 顶部的已发布版本 +# (`python3 scripts/version.py --identity`),**不要手填**。不传就落成 dev / unknown —— 那是故意的: # 一个显眼的 dev 好过一个看起来正常的假版本号(正本 §6.1)。 +# BUILD_KIND 只有**显式的发布上下文**才传 release;普通构建一律 development, +# 产物的 DisplayVersion() 会是 dev+g<短SHA>(开发构建不许只显示上一正式版本号)。 # ⚠️ TODO:compose.yaml 还没把这三个 args 透传进来(改动会与在审的 PR #2 冲突), # 所以当前由 compose 构建出的镜像会报 dev;透传后即报真实版本。 ARG VERSION=dev +ARG RELEASE_VERSION= +ARG BUILD_KIND=development ARG COMMIT_SHA=unknown ARG BUILD_TIME=unknown -RUN LDFLAGS="-X knowledge-governance/internal/version.Number=${VERSION} -X knowledge-governance/internal/version.CommitSHA=${COMMIT_SHA} -X knowledge-governance/internal/version.BuildTime=${BUILD_TIME}" \ +RUN LDFLAGS="-X knowledge-governance/internal/version.Number=${VERSION} -X knowledge-governance/internal/version.ReleaseVersion=${RELEASE_VERSION} -X knowledge-governance/internal/version.BuildKind=${BUILD_KIND} -X knowledge-governance/internal/version.CommitSHA=${COMMIT_SHA} -X knowledge-governance/internal/version.BuildTime=${BUILD_TIME}" \ && CGO_ENABLED=0 GOOS=linux go build -trimpath -ldflags "$LDFLAGS" -o /out/api ./cmd/api \ && CGO_ENABLED=0 GOOS=linux go build -trimpath -ldflags "$LDFLAGS" -o /out/worker ./cmd/worker \ && CGO_ENABLED=0 GOOS=linux go build -trimpath -ldflags "$LDFLAGS" -o /out/release-worker ./cmd/release-worker \ diff --git a/Makefile b/Makefile index 70a72b9..914282a 100644 --- a/Makefile +++ b/Makefile @@ -2,11 +2,15 @@ GO ?= go PY ?= python3 # 版本号的唯一来源是仓库根的 CHANGELOG.md(正本 §6.1:版本号只有一个来源)。 -# 刻意**不用** `git describe --tags`:CI 检出是 `git fetch --depth 50`,取不到 tag, +# 刻意**不**在构建时跑 `git describe --tags`:日常检出是浅克隆、拿不到 tag, # 那会让版本号在本地正常、在 CI 上静默退化(见 docs/agents/traps.md trap-5)。 -VERSION ?= $(shell $(PY) scripts/version.py 2>/dev/null || echo dev) -COMMIT_SHA ?= $(shell git rev-parse --short=12 HEAD 2>/dev/null || echo unknown) -BUILD_TIME ?= $(shell date -u +%Y-%m-%dT%H:%M:%SZ) +# **正式 tag** 由人批准后创建(注释 tag `vX.Y.Z`),CI 只核验「tag 版本 == 该提交里的版本记录」。 +VERSION ?= $(shell $(PY) scripts/version.py 2>/dev/null || echo dev) +RELEASE_VERSION ?= $(shell $(PY) scripts/version.py 2>/dev/null || echo) +BUILD_KIND ?= development +COMMIT_SHA ?= $(shell git rev-parse --short=12 HEAD 2>/dev/null || echo unknown) +FULL_SHA ?= $(shell git rev-parse HEAD 2>/dev/null || echo unknown) +BUILD_TIME ?= $(shell date -u +%Y-%m-%dT%H:%M:%SZ) .PHONY: verify checks list \ format static-go static-web deps-install build-go build-web \ @@ -63,23 +67,29 @@ web-test: tests-web web-typecheck: static-web web-build: build-web -# 打印当前版本号(唯一来源:CHANGELOG.md 顶部那个已发布版本) +# 构建身份(JSON):release_version / build_kind / commit_sha / display_version / built_at +# 开发构建也能用:没有正式版本时是 dev+g<短SHA>,不会退化成"上一正式版本号"。 version: - @$(PY) scripts/version.py + @$(PY) scripts/version.py --identity -# 变更记录结构自检:每个已发布版本都必须有「改了什么」「怎么验收」两节 +# 变更记录结构自检:小节只认 Added/Changed/Fixed/Security(分类可省略、不许空栏目), +# 破坏性变化必须在 Changed 里带发布文档链接。加 --tags 再核「tag 版本 == 该提交里的版本记录」。 changelog-check: @$(PY) scripts/check_changelog.py -# 版本契约:注入进二进制的号必须等于 CHANGELOG 顶部。 -# ⚠️ 不注入时该用例会 SKIP —— 那是"本地不想被迫先构建"的便利,但**CI 必须断言它真的 PASS** -# (门禁的 contracts 项就是这么做的;被跳过的断言等于没有断言)。 +# 版本契约:注入进二进制的身份必须与 CHANGELOG 对账,且**开发构建不许自称正式版**。 +# ⚠️ 不注入时这两条用例会 SKIP —— 那是"本地不想被迫先构建"的便利,但**CI 必须断言它们真的 PASS** +# (门禁的 contracts 项就是这么做的,并额外跑一条"自称正式版 ⇒ 必须红"的负例)。 version-contract: - $(GO) test -ldflags "-X knowledge-governance/internal/version.Number=$(VERSION)" \ - -count=1 -run TestNumberMatchesChangelog -v ./internal/version/... + $(GO) test -ldflags "-X knowledge-governance/internal/version.Number=$(VERSION) \ + -X knowledge-governance/internal/version.ReleaseVersion=$(RELEASE_VERSION) \ + -X knowledge-governance/internal/version.BuildKind=$(BUILD_KIND) \ + -X knowledge-governance/internal/version.CommitSHA=$(FULL_SHA)" \ + -count=1 -run Test -v ./internal/version/... -# 构建镜像。三个 build-arg 必须显式传入 —— 不传就落成 dev/unknown(故意的: +# 构建镜像。build-arg 必须显式传入 —— 不传就落成 dev/unknown(故意的: # 一个显眼的 dev 好过一个看起来正常的假版本号)。compose.yaml 的 args 透传见 PR TODO。 image: - docker build --build-arg VERSION=$(VERSION) --build-arg COMMIT_SHA=$(COMMIT_SHA) \ + docker build --build-arg VERSION=$(VERSION) --build-arg RELEASE_VERSION=$(RELEASE_VERSION) \ + --build-arg BUILD_KIND=$(BUILD_KIND) --build-arg COMMIT_SHA=$(COMMIT_SHA) \ --build-arg BUILD_TIME=$(BUILD_TIME) -t knowledge-governance-p1:$(VERSION)-$(COMMIT_SHA) . \ No newline at end of file diff --git a/internal/version/version.go b/internal/version/version.go index e82daa2..4c0d0e9 100644 --- a/internal/version/version.go +++ b/internal/version/version.go @@ -1,28 +1,96 @@ // Package version 承载"这个二进制是什么"的构建期身份。 // -// 三个值**全部由构建期注入**(正本 §6.1:版本号只有一个来源,且要能从产物读回来): +// 字段由构建期注入(正本 §6.1:版本号只有一个来源,且要能从产物读回来): // -// go build -trimpath \ -// -ldflags "-X knowledge-governance/internal/version.Number=$(python3 scripts/version.py) \ -// -X knowledge-governance/internal/version.CommitSHA=$(git rev-parse --short=12 HEAD) \ -// -X knowledge-governance/internal/version.BuildTime=$(date -u +%Y-%m-%dT%H:%M:%SZ)" \ -// ./cmd/api +// VERSION=$(python3 scripts/version.py 2>/dev/null || echo dev) +// go build -trimpath -ldflags "\ +// -X knowledge-governance/internal/version.Number=${VERSION} \ +// -X knowledge-governance/internal/version.ReleaseVersion= \ +// -X knowledge-governance/internal/version.BuildKind=development|release \ +// -X knowledge-governance/internal/version.CommitSHA=$(git rev-parse HEAD) \ +// -X knowledge-governance/internal/version.BuildTime=$(date -u +%Y-%m-%dT%H:%M:%SZ)" ./cmd/api // -// 三条纪律: +// 四条纪律: // // 1. **不要**把它们改成编译期常量,也**不要**另建仓库根的 VERSION 文件 —— // 版本号的唯一来源是 CHANGELOG.md,由 scripts/version.py 解析。 -// 放第二份副本的结果是发版要改两处,忘一处就漂移。 -// 2. **不要**给这些变量设"看起来正常的默认值"。未注入时保持下面的零值, +// 2. **不要**给这些变量设"看起来正常的默认值"。未注入时保持零值, // 好让"忘了注入"表现成一个显眼的 dev,而不是一个假的正经版本号。 -// 3. `Number` 的正确性由 internal/version 的契约测试兜底:注入进去的号 -// 必须等于 CHANGELOG.md 顶部的已发布版本(CI 会带 -ldflags 跑它, -// 并额外断言"没有 SKIP" —— 被跳过的断言等于没有断言)。 +// 3. **开发构建不许自称正式版**:`BuildKind` 只能来自显式的发布上下文 +// (`BUILD_KIND=release`);普通 main CI 永远是 development, +// DisplayVersion() 必须带 `-dev+g<短SHA>`,**不允许只显示上一正式版本号**。 +// 4. 契约由本包的测试兜底:发布构建的 ReleaseVersion 必须等于 CHANGELOG.md 顶部的 +// 已发布版本,开发构建必须是 dev 形状;CI 带 -ldflags 跑它并断言**没有 SKIP** +// (被跳过的断言等于没有断言)。 package version -// Number / CommitSHA / BuildTime 由 -ldflags -X 注入;未注入时保持下面的值。 -var ( - Number = "dev" - CommitSHA = "unknown" - BuildTime = "unknown" +import ( + "fmt" + "regexp" ) + +// Number / ReleaseVersion / BuildKind / CommitSHA / BuildTime 由 -ldflags -X 注入; +// 未注入时保持下面的值。 +var ( + Number = "dev" // 已发布版本号或 dev(= ReleaseVersion,或 dev) + ReleaseVersion = "" // 正式版本基线;还没有正式发布过 ⇒ 空 + BuildKind = "development" // development | release + CommitSHA = "unknown" // 完整 40 位提交 SHA + BuildTime = "unknown" // 构建时间(built_at) +) + +var ( + fullSHA = regexp.MustCompile(`^[0-9a-f]{40}$`) + semver = regexp.MustCompile(`^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$`) +) + +// IsRelease 只在**显式声明**且确实有正式版本基线时为真。 +func IsRelease() bool { return BuildKind == "release" && semver.MatchString(ReleaseVersion) } + +// ShortSHA 返回 12 位短 SHA;没有注入有效 SHA 时返回空串。 +func ShortSHA() string { + if !fullSHA.MatchString(CommitSHA) { + return "" + } + return CommitSHA[:12] +} + +// DisplayVersion 是**用户可见标识**,规则与 scripts/version.py 一致: +// +// 发布构建 → 0.1.0 +// 开发构建(有基线) → 0.1.0-dev+g<短SHA> +// 开发构建(无基线) → dev+g<短SHA> +// 什么都拿不到 → dev +// +// ⚠️ 开发构建**不会**退化成"只显示上一正式版本号"——那正是要修的问题。 +func DisplayVersion() string { + if IsRelease() { + return ReleaseVersion + } + short := ShortSHA() + switch { + case ReleaseVersion != "" && short != "": + return ReleaseVersion + "-dev+g" + short + case ReleaseVersion != "": + return ReleaseVersion + "-dev" + case short != "": + return "dev+g" + short + default: + return "dev" + } +} + +// Info 是给人看的一行摘要(不含密钥,可安全打印进日志)。 +func Info() string { + sha := CommitSHA + if len(sha) > 12 { + sha = sha[:12] + } + return fmt.Sprintf("%s(%s,提交 %s,构建于 %s)", DisplayVersion(), BuildKind, sha, BuildTime) +} + +// HasInjection 判断构建期是否真的注入了身份:未注入时契约测试应当 Skip, +// 而 CI 必须断言它**没有** Skip。 +func HasInjection() bool { + return !(Number == "dev" && ReleaseVersion == "" && CommitSHA == "unknown") +} diff --git a/internal/version/version_test.go b/internal/version/version_test.go index fb3173b..37b9ded 100644 --- a/internal/version/version_test.go +++ b/internal/version/version_test.go @@ -4,23 +4,13 @@ import ( "os" "path/filepath" "regexp" + "strings" "testing" ) -// 版本契约:注入进二进制的号,必须等于仓库根 CHANGELOG.md 顶部的已发布版本。 -// -// 为什么要有这条断言:CHANGELOG.md 是版本号的**唯一来源**,而注入是构建期动作。 -// 两者只要没人对账,就会出现"改了 CHANGELOG 没重新构建"(产物报旧号)或 -// "构建时手填了一个号"(产物报的号 CHANGELOG 里根本没有)—— 两种都让 -// "线上跑的是哪个提交/版本"这个问题失去答案,而症状是静默的。 -// -// 未注入时(普通 `go test ./...`)本用例 Skip:本地跑全量测试不必先构建。 -// 但 CI 必须带 -ldflags 跑它,**并断言没有 SKIP**(.gitea/workflows/build.yml -// 的「版本与变更记录契约」步;被跳过的断言等于没有断言)。 -func TestNumberMatchesChangelog(t *testing.T) { - if Number == "dev" { - t.Skip("版本号未注入(没有 -ldflags);CI 会注入后跑这条断言") - } +// changelogTopVersion 返回仓库根 CHANGELOG.md 顶部的已发布版本号;还没有正式版本时返回 ""。 +func changelogTopVersion(t *testing.T) string { + t.Helper() path := filepath.Join("..", "..", "CHANGELOG.md") raw, err := os.ReadFile(path) if err != nil { @@ -28,13 +18,83 @@ func TestNumberMatchesChangelog(t *testing.T) { } m := regexp.MustCompile(`(?m)^##\s*\[(\d+\.\d+\.\d+)\]`).FindSubmatch(raw) if m == nil { - t.Fatalf("%s 里没有已发布版本条目(形如 `## [0.1.0] - 2026-01-01`);"+ - "没有条目就没有版本号,不该回落到一个假版本", path) + return "" } - want := string(m[1]) - if Number != want { - t.Fatalf("注入的版本 %q != CHANGELOG 顶部 %q。"+ + return string(m[1]) +} + +// 版本契约:注入进二进制的**正式版本基线**,必须等于仓库根 CHANGELOG.md 顶部的已发布版本。 +// +// 为什么要有这条断言:CHANGELOG.md 是版本号的**唯一来源**,而注入是构建期动作。 +// 两者只要没人对账,就会出现"改了 CHANGELOG 没重新构建"(产物报旧号)或 +// "构建时手填了一个号"(产物报的号 CHANGELOG 里根本没有)—— 两种都让 +// "线上跑的是哪个提交/版本"这个问题失去答案,而症状是静默的。 +// +// ⚠️ "还没有正式版本"不等于出错:那时 ReleaseVersion 必须是空,**不许**编一个基线出来。 +// +// 未注入时(普通 `go test ./...`)本用例 Skip:本地跑全量测试不必先构建。 +// 但 CI 必须带 -ldflags 跑它,**并断言没有 SKIP**(被跳过的断言等于没有断言)。 +func TestNumberMatchesChangelog(t *testing.T) { + if !HasInjection() { + t.Skip("构建身份未注入(没有 -ldflags);CI 会注入后跑这条断言,并断言它没有 Skip") + } + want := changelogTopVersion(t) + if want == "" { + if ReleaseVersion != "" { + t.Fatalf("CHANGELOG.md 里还没有已发布版本,ReleaseVersion 却是 %q —— 不许编一个版本基线出来", ReleaseVersion) + } + } else if ReleaseVersion != want { + t.Fatalf("注入的 ReleaseVersion %q != CHANGELOG 顶部 %q。"+ "常见原因:改了 CHANGELOG 却没重新构建(产物还报旧号),"+ - "或者构建时手填了一个 CHANGELOG 里没有的号", Number, want) + "或者构建时手填了一个 CHANGELOG 里没有的号", ReleaseVersion, want) + } + if Number != ReleaseVersion && Number != "dev" { + t.Fatalf("Number %q 既不是 ReleaseVersion %q 也不是 dev —— 注入口径不一致", Number, ReleaseVersion) + } +} + +// 开发构建不许自称正式版:这是"用正式版号代表开发版"那个问题的守门断言。 +// +// - `BuildKind=release` 只允许出现在**确实有正式版本基线**的构建上,且显示就是那个版本; +// - 开发构建的 DisplayVersion 必须带 `dev` 形状,**不允许**退化成只显示上一正式版本号。 +func TestDevBuildDoesNotClaimRelease(t *testing.T) { + if !HasInjection() { + t.Skip("构建身份未注入(没有 -ldflags);CI 会带 -ldflags 跑它,并断言它没有 Skip") + } + want := changelogTopVersion(t) + disp := DisplayVersion() + + if BuildKind == "release" { + if want == "" { + t.Fatalf("标成了发布构建(BuildKind=release),但 CHANGELOG.md 里没有任何已发布版本条目 —— "+ + "发布构建必须基于正式版本记录(现在显示 %q)", disp) + } + if ReleaseVersion != want || !semver.MatchString(ReleaseVersion) { + t.Fatalf("发布构建的 ReleaseVersion %q 不是 CHANGELOG 顶部的正式版本 %q", ReleaseVersion, want) + } + if disp != ReleaseVersion { + t.Fatalf("发布构建 DisplayVersion %q 应等于 ReleaseVersion %q", disp, ReleaseVersion) + } + return + } + + if BuildKind != "development" { + t.Fatalf("BuildKind %q 既不是 development 也不是 release", BuildKind) + } + if !strings.Contains(disp, "dev") { + t.Fatalf("开发构建的 DisplayVersion %q 没有 dev 标识 —— 开发构建不能只显示正式版本号", disp) + } + if strings.Contains(disp, "+g") && ShortSHA() == "" { + t.Fatalf("DisplayVersion %q 带了 +g 但 CommitSHA %q 不是有效 SHA", disp, CommitSHA) + } + switch { + case want != "" && ShortSHA() != "": + if want := want + "-dev+g" + ShortSHA(); disp != want { + t.Fatalf("开发构建 DisplayVersion %q,期望 %q", disp, want) + } + case want == "" && ShortSHA() != "": + if want := "dev+g" + ShortSHA(); disp != want { + t.Fatalf("无正式基线的开发构建 DisplayVersion %q,期望 %q", disp, want) + } } } diff --git a/scripts/ci_checks.py b/scripts/ci_checks.py index 92395f5..1ca64b8 100644 --- a/scripts/ci_checks.py +++ b/scripts/ci_checks.py @@ -37,7 +37,7 @@ from typing import Callable ROOT = Path(__file__).resolve().parent.parent WEB = ROOT / "web" REPORT_DEFAULT = ROOT / "ci-report.json" -POLICY_REVISION = "ci-checks/2" # 判据变更时改这里,报告里跟着变 +POLICY_REVISION = "ci-checks/3" # 判据变更时改这里,报告里跟着变 MANIFESTS = ["go.mod", "go.sum", "web/package.json", "web/package-lock.json"] SUCCESS, FAILURE, SKIPPED, NOT_RUN = "success", "failure", "skipped", "not_run" @@ -249,9 +249,9 @@ def checks() -> list[Check]: [g, "test", "-count=1", "-json", "./..."], env=env, judge=judge_go_tests), Check("tests-web", "前端测试(vitest,必须真跑)", [py3, "scripts/ci_checks.py", "--internal-web-test"], env=env), - Check("contracts", "版本与变更记录契约(不许 SKIP 后算过)", + Check("contracts", "版本与变更记录契约(不许 SKIP;开发构建不许自称正式版)", [py3, "scripts/ci_checks.py", "--internal-contracts", g], env=env), - Check("version", "CHANGELOG 与版本记录(四节齐备 + 正式 tag 与提交内版本一致)", + Check("version", "CHANGELOG 与版本记录(四类小节无空栏目 + 正式 tag 与提交内版本一致)", [py3, "scripts/check_changelog.py", "--tags"]), Check("security-secrets", "密钥泄漏扫描(含扫描器自检)", [py3, "scripts/check_secrets.py"]), @@ -287,22 +287,47 @@ def cmd_internal_deps(out_dir: str) -> int: return 0 +def build_identity() -> tuple[dict | None, str]: + """构建身份(`scripts/version.py --identity`)。 + + ⚠️ 刻意**不**跑裸的 `scripts/version.py`:那个在"还没有正式版本"时会非 0 退出, + 而开发构建**必须**能正常产出身份(release_version=null / display_version=dev+g<短SHA>)。 + """ + p = subprocess.run(py("scripts/version.py", "--identity"), cwd=ROOT, capture_output=True, text=True) + if p.returncode: + return None, ((p.stderr or p.stdout).strip().splitlines() or [f"退出码 {p.returncode}"])[0][:400] + try: + return json.loads(p.stdout), "" + except ValueError as e: + return None, f"--identity 的输出不是 JSON:{e}" + + +def ldflags_for(ident: dict, *, build_kind: str | None = None, + release_version: str | None = None) -> str: + """把构建身份编成 -ldflags(负例可以覆盖 kind / release_version)。""" + kind = build_kind or str(ident.get("build_kind") or "development") + rel = ident.get("release_version") if release_version is None else release_version + return " ".join([ + f"-X knowledge-governance/internal/version.Number={rel or 'dev'}", + f"-X knowledge-governance/internal/version.ReleaseVersion={rel or ''}", + f"-X knowledge-governance/internal/version.BuildKind={kind}", + f"-X knowledge-governance/internal/version.CommitSHA={ident.get('commit_sha') or 'unknown'}", + f"-X knowledge-governance/internal/version.BuildTime={ident.get('built_at') or 'unknown'}", + ]) + + def cmd_internal_build(out_dir: str) -> int: out = Path(out_dir) out.mkdir(parents=True, exist_ok=True) - version = subprocess.run(py("scripts/version.py"), cwd=ROOT, capture_output=True, - text=True).stdout.strip() or "dev" - sha = subprocess.run(["git", "rev-parse", "--short=12", "HEAD"], cwd=ROOT, - capture_output=True, text=True).stdout.strip() or "unknown" - ts = dt.datetime.now(dt.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ") - ldflags = " ".join([ - f"-X knowledge-governance/internal/version.Number={version}", - f"-X knowledge-governance/internal/version.CommitSHA={sha}", - f"-X knowledge-governance/internal/version.BuildTime={ts}", - ]) + ident, err = build_identity() + if ident is None: + print(f"❌ 拿不到构建身份:{err}", file=sys.stderr) + return 1 + ldflags = ldflags_for(ident) p = subprocess.run([go_bin(), "build", "-trimpath", "-ldflags", ldflags, "-o", f"{out}/", "./cmd/..."], cwd=ROOT, env=go_env(), capture_output=True, text=True) - print(f"-- go build(版本 {version} / 提交 {sha})--") + print(f"-- go build(显示版本 {ident['display_version']}|{ident['build_kind']}|" + f"提交 {str(ident['commit_sha'])[:12]})--") print(p.stdout[-2000:] if p.stdout else "", end="") if p.returncode: print(f"❌ 构建失败:{(p.stderr or '')[:2000]}", file=sys.stderr) @@ -327,31 +352,49 @@ def cmd_internal_web_test() -> int: def cmd_internal_contracts(go: str) -> int: - """版本契约:注入进二进制的号必须等于 CHANGELOG 顶部,而且**必须真的 PASS**。""" + """版本契约:结构 + 注入身份必须**真 PASS**(SKIP 判红), + 并且**开发构建不许自称正式版**(负例:标成 release ⇒ 必须红)。""" rc = subprocess.run(py("scripts/check_changelog.py"), cwd=ROOT).returncode if rc: return 1 - v = subprocess.run(py("scripts/version.py"), cwd=ROOT, capture_output=True, text=True) - version = v.stdout.strip() - if v.returncode or not version: - print("❌ CHANGELOG 顶部解析不到版本号:没有条目就没有版本号,不许回落成假版本", file=sys.stderr) + ident, err = build_identity() + if ident is None: + print(f"❌ 拿不到构建身份:{err}", file=sys.stderr) return 1 - print(f"-- 版本契约:CHANGELOG 顶部 = {version} --") - p = subprocess.run([go, "test", f"-ldflags=-X knowledge-governance/internal/version.Number={version}", - "-count=1", "-run", "TestNumberMatchesChangelog", "-v", "-json", - "./internal/version/..."], - cwd=ROOT, env=go_env(), capture_output=True, text=True) - text = p.stdout + p.stderr - print(text[-3000:], end="") + print(f"-- 版本契约:显示版本 {ident['display_version']}({ident['build_kind']}" + f"|release_version={ident['release_version']!r})--") + tests = ("TestNumberMatchesChangelog", "TestDevBuildDoesNotClaimRelease") + + def run(ld: str) -> tuple[int, str]: + p = subprocess.run([go, "test", f"-ldflags={ld}", "-count=1", "-run", "Test", "-v", "-json", + "./internal/version/..."], cwd=ROOT, env=go_env(), + capture_output=True, text=True) + return p.returncode, (p.stdout + p.stderr).replace("\\n", "\n") + + rc1, text = run(ldflags_for(ident)) + print(text[-2000:], end="") # ⚠️ 被跳过的断言等于没有断言:必须看到 PASS,SKIP 一律判红。 # 用 in 而不是 `| grep -q`:pipefail 下 grep -q 会因 SIGPIPE 谎报失败(trap-7)。 - if '--- PASS: TestNumberMatchesChangelog' not in text.replace("\\n", "\n"): - print("❌ 版本契约没有真正 PASS(被 SKIP 或没跑到)—— 缺 -ldflags,或 CHANGELOG 解析失败", file=sys.stderr) + for name in tests: + if f"--- PASS: {name}" not in text: + print(f"❌ 版本契约 {name} 没有真正 PASS(被 SKIP 或没跑到)—— " + f"缺 -ldflags,或 CHANGELOG / 构建身份有问题", file=sys.stderr) + return 1 + if f"--- SKIP: {name}" in text: + print(f"❌ 版本契约 {name} 被跳过(构建身份没注入)—— 跳过不算通过", file=sys.stderr) + return 1 + + # 负例:把开发构建标成正式版(ReleaseVersion 指向 CHANGELOG 里没有的号)⇒ **必须红**。 + # 没有这条,"开发版沿用正式版号"这个病会静默回归。 + bogus = "9.9.9" if ident.get("release_version") != "9.9.9" else "8.8.8" + rc2, _ = run(ldflags_for(ident, build_kind="release", release_version=bogus)) + if rc2 == 0: + print(f"❌ 把构建标成正式版(BuildKind=release / ReleaseVersion={bogus})竟然还是绿的 —— " + f"这条断言是死的", file=sys.stderr) return 1 - if "--- SKIP: TestNumberMatchesChangelog" in text: - print("❌ 版本契约被跳过(未注入版本号)—— 跳过不算通过", file=sys.stderr) - return 1 - print("✅ 版本契约成立:注入 == CHANGELOG 顶部,且断言真的执行了") + print(f"-- 负例确认:自称正式版({bogus})⇒ 红 ✓ --") + print("✅ 版本契约成立:注入 == CHANGELOG 顶部(没有正式版本时为空)," + "开发构建带 dev 标识,且断言真的执行了") return 0 diff --git a/scripts/test-scope.json b/scripts/test-scope.json index 685e8ba..b0d6858 100644 --- a/scripts/test-scope.json +++ b/scripts/test-scope.json @@ -43,6 +43,11 @@ "package": "knowledge-governance/internal/version", "test": "TestNumberMatchesChangelog", "reason": "未注入版本号时按设计 SKIP(本地跑全量测试不该被迫先构建);**它的强制点在 contracts 项**:那里带 -ldflags 跑它并断言真的 PASS、且出现 SKIP 就判红" + }, + { + "package": "knowledge-governance/internal/version", + "test": "TestDevBuildDoesNotClaimRelease", + "reason": "构建身份未注入时按设计 SKIP(本地跑全量测试不该被迫先构建);**它的强制点在 contracts 项**:那里带 -ldflags 跑它并断言真的 PASS、且出现 SKIP 就判红" } ] -} \ No newline at end of file +} diff --git a/scripts/version.py b/scripts/version.py index 0567762..aee67ff 100755 --- a/scripts/version.py +++ b/scripts/version.py @@ -1,22 +1,35 @@ #!/usr/bin/env python3 -"""打印版本号 —— 唯一来源是仓库根的 CHANGELOG.md。 +"""版本与构建身份 —— 版本号的唯一来源是仓库根的 CHANGELOG.md。 -为什么是它而不是 git tag:CI 检出是 `git fetch --depth 50`,**取不到 tag**, -`git describe --tags` 会失败或者给出误导性的结果。仓库里的文件则一定在。 +为什么是它而不是 git tag:**日常检出不做 `git describe`**(CI 检出是 `git fetch --depth 50`, +`git describe --tags` 会失败或给出误导结果)。正式 tag 的**创建**是人工批准的发布动作, +CI 只做**核验**(tag 版本 == 它指到那个提交里的版本记录),见 `check_changelog.py --tags`。 +仓库里的文件则一定在。 -为什么不是另放一个 `VERSION` 文件:那是第二份副本,发版要改两处,忘一处就漂移 -(正本 §3.1)。CHANGELOG.md 里本来就必须写版本号,让它当源头,副本数为一。 +为什么不是另放一个 `VERSION` 文件:那是第二份副本,发版要改两处,忘一处就漂移。 用法: - python3 scripts/version.py # 打印版本号;解析不到就以非 0 退出 - python3 scripts/version.py --check # 同时跑结构自检(等价 check-changelog.py) + python3 scripts/version.py # 打印顶部「已发布」版本号;没有就非 0 退出 + python3 scripts/version.py --identity # 打印构建身份 JSON(**开发构建也能用**) + python3 scripts/version.py --identity --release # 声明发布构建;没有已发布版本 ⇒ 拒绝(rc=2) + python3 scripts/version.py --check # 打印版本号并跑结构自检(等价 check-changelog.py) -退出码非 0 表示"CHANGELOG 里没有已发布版本条目" —— 构建应当据此失败, -而不是回落成一个看起来正常的假版本号。 +构建身份字段(`--identity`): + release_version 正式版本基线;本仓还没有正式发布过 ⇒ `null` + build_kind development | release(**只有显式声明**才是 release,普通 main CI 永远不是) + commit_sha 完整 40 位提交 SHA(取不到 ⇒ `unknown`) + display_version 用户可见标识:`X.Y.Z` / `X.Y.Z-dev+g<短SHA>` / `dev+g<短SHA>` / `dev` + built_at 构建时间(`BUILT_AT` 环境变量,缺省取当前 UTC) + +⚠️ 开发构建**不能**只显示上一正式版本号(那正是要修的问题),也不许自称正式版。 """ from __future__ import annotations +import datetime as dt +import json +import os import re +import subprocess import sys from pathlib import Path @@ -25,6 +38,8 @@ CHANGELOG = ROOT / "CHANGELOG.md" # 已发布版本标题:`## [0.1.0] - 2026-10-10` / `## [0.1.0]`;`## [Unreleased]` 不算 RELEASE_HEADING = re.compile(r"^##\s*\[(\d+\.\d+\.\d+)\]", re.MULTILINE) +SEMVER = re.compile(r"^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$") +FULL_SHA = re.compile(r"^[0-9a-f]{40}$") def current_version(path: Path = CHANGELOG) -> str | None: @@ -35,12 +50,58 @@ def current_version(path: Path = CHANGELOG) -> str | None: return m.group(1) if m else None +def git_sha(root: Path = ROOT) -> str: + p = subprocess.run(["git", "rev-parse", "HEAD"], cwd=root, capture_output=True, text=True) + s = p.stdout.strip() + return s if FULL_SHA.match(s) else "unknown" + + +def display_version(release_version: str | None, kind: str, sha: str) -> str: + short = sha[:12] if FULL_SHA.match(sha) else "" + if kind == "release" and release_version: + return release_version + if release_version and short: + return f"{release_version}-dev+g{short}" + if release_version: + return f"{release_version}-dev" + return f"dev+g{short}" if short else "dev" + + +def identity(*, release: bool = False, built_at: str | None = None, + root: Path = ROOT, sha: str | None = None) -> dict: + """构建身份。`release=True` 但没有已发布版本 ⇒ 由调用方拒绝(见 main)。""" + 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 { + "release_version": rel, + "build_kind": kind, + "commit_sha": sha, + "display_version": display_version(rel, kind, sha), + "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"), + } + + def main(argv: list[str]) -> int: + 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) + return 2 + print(json.dumps(identity(release=release), ensure_ascii=False, indent=2)) + return 0 + v = current_version() if v is None: print( "❌ CHANGELOG.md 里找不到已发布版本条目(形如 `## [0.1.0] - 2026-10-10`)。\n" - " 版本号解析不到 ⇒ 构建应当失败,而不是回落成假版本号。", + " 本仓还没有正式发布过 ⇒ 没有正式版本号可用。\n" + " 要构建身份(开发构建也能用)请跑 `python3 scripts/version.py --identity`;\n" + " 发布构建必须先在 CHANGELOG.md 写下正式版本条目。", file=sys.stderr, ) return 1