diff --git a/CHANGELOG.md b/CHANGELOG.md index b14b2d4..0840792 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -28,6 +28,50 @@ - 待合并:PR #2 —— 批量发布 / 建批即锁定 / 需下架逐条移除 / 数据源勾选改造(23 个提交,80 个文件) - 待合并:仓库卫生 —— 撤出误入库的 `node_modules/.vite/.../results.json` 与 8 个历史 `scripts/__pycache__/*.pyc` +### 改了什么(CI 接入这一批) + +**唯一权威门禁**:`make verify` = `python3 scripts/ci_checks.py` —— 一条命令跑完 14 项必需检查、 +串行、失败即停,产出结构化报告 `ci-report.json`。本地与 CI 跑的是**同一条命令**(不再各写一套)。 + +- 新增 14 项检查:`identity`(检出 == 事件完整 SHA)、`commits`、`deps-install`(按锁安装)、 + `format`(Go gofmt + 前端 prettier)、`static-go`(go vet)、`static-web`(tsc)、 + `build-go`(带版本注入)、`build-web`、`tests-go`、`tests-web`、`contracts`(版本契约**必须真 PASS**)、 + `security-secrets`、`security-deps`(govulncheck + npm audit 分级 + 例外)、`manifests-locked`。 +- 汇总按**清单**逐项核对:失败即停后剩下的记 `not_run`,**未运行/被跳过一律不算通过**。 +- `.gitea/workflows/build.yml` 改成**单作业**(避免跨作业 `/tmp` 状态传递的假契约):检出固定事件完整 SHA → + 环境与工具链 → `make verify` → 静态预览(**只在全部必需检查通过后**发布,且断言包里有 `index.html`、 + 报告里每个地址都 200)→ 上报 ci-bridge(**通知失败不改变质量结论**)。 +- 本 workflow **只做 CI**:删掉了 `deploy:test` 占位作业(原来它会打印 TODO 然后返回成功 = 假报成功)。 +- 新增脚本:`scripts/ci_checks.py`(门禁 + 汇总)、`scripts/check_format.py`(格式,含只能减的基线)、 + `scripts/check_secrets.py`(密钥扫描,带双向自检)、`scripts/check_deps_vuln.py`(依赖漏洞分级)。 + 四个脚本都带 `--self-test`(反向自检:故意弄坏必须红)。 +- `security/dependency-exceptions.json`:依赖漏洞例外登记(缺字段/过期/批准人是占位值 ⇒ 例外无效)。 +- 依赖:`vite` 7.1.3 → **7.3.7**、`vitest` 3.2.4 → **5.0.3**(清掉 npm audit 的 2 critical + 2 high + 1 moderate, + 现在全量 0 命中);新增 `prettier` 3.9.10;`web/package.json` 加 `format` / `format:check`。 +- 格式债:Go 侧 6 个文件 `gofmt -w`(存量清干净,Go 侧一条都不欠);前端 79 个文件的存量格式债 + 记入 `web/.prettier-baseline.json`(**列明 + 只能减 + 2026-12-31 到期**,不新增欠账即绿)。 +- `AGENTS.md` 的现状表**已过期**(写着"main 已启用分支保护",实际 `GET /branch_protections` = `[]`)—— + 修正稿已拟好,但该文件受写入保护,**待人工批准后应用**(见交付说明)。 + +### 怎么验收 + +```bash +# 1) 门禁自身可跑、且能证明自己会红(反向自检) +python3 scripts/ci_checks.py --self-test # 期望:✅ 汇总逻辑 7 个分支符合预期 +python3 scripts/check_format.py --self-test # 期望:✅ 6 个判定分支 +python3 scripts/check_secrets.py --self-test # 期望:✅ 7 条合成密钥全部命中,良性对照零误报 +python3 scripts/check_deps_vuln.py --self-test # 期望:✅ 9 个判据 + JSON 流解析器 + +# 2) 一条命令跑完全部门禁(约 1 分钟;会跑 npm ci,请留时间) +make verify +# 期望:末尾"总体:success(档案 local)",identity=skipped(本地无事件负载,已在清单里声明) + +# 3) 清单与真实结果对账 +make list # 期望:14 项,identity 标 ci +python3 -c "import json;d=json.load(open('ci-report.json'));print(d['overall_status'],len(d['checks']))" +# 期望:success 14 +``` + ## [0.1.0] - 2026-10-10 ### 改了什么 diff --git a/docs/agents/traps.md b/docs/agents/traps.md index 40e0dcc..2082258 100644 --- a/docs/agents/traps.md +++ b/docs/agents/traps.md @@ -109,4 +109,100 @@ remote,令牌来自 `secrets.GITHUB_TOKEN`)。 **修法**:用 `case "$OUT" in *PASS*) ... ;; esac`,或让 `grep` 直接读文件; 非用管道不可时用 `set +e; set +o pipefail` + `${PIPESTATUS[0]}`。 -**反例**:`if echo "$x" | grep -q y; then` —— 时红时绿,且方向完全错。 \ No newline at end of file +**反例**:`if echo "$x" | grep -q y; then` —— 时红时绿,且方向完全错。 + +## trap-8:`gofmt -l` 列出文件时**退出码仍是 0**(只看退出码=假绿) + +**症状**:门禁里写着 `gofmt -l .`(或 `step gofmt -l . || fail=1`),格式乱掉的文件明明被列出来了, +这一步却**通过**。整条门禁全绿,而仓库里躺着一堆没格式化的文件。 + +**根因**:`gofmt -l` 的正常行为就是"列出不合规的文件并返回 0" —— +它的退出码表达的是"我跑完了",不是"都合规"。用退出码当判据,等于没判。 + +**判据**:任何"输出即问题"的工具(`gofmt -l`、`prettier --list-different`、`git status --porcelain`) +都必须**判输出是否为空**,不能判退出码。 + +**修法**:`[ -z "$(gofmt -l <文件...>)" ]`,或者像本仓 `scripts/check_format.py` 那样解析输出; +并且给它一条**故意弄坏的夹具**证明它真的会红(否则"永远返回 0 的校验器"会一路绿灯)。 + +**反例**:`step gofmt -l . || fail=1` —— 生成器里就是这么写的,一直没人发现。 + +## trap-9:`tar -C dir .` 产生 `.` 根成员 ⇒ 预览 404 + +**症状**:打包与上传都成功、通知也发了,点开预览链接却是 404 或报错。 + +**根因**:`tar -czf x.tgz -C dir .` 会把 `.`(以及 `./index.html`)写进成员名。 +严格的解包器要么拒绝整包,要么解出一层多余的 `.`,于是 `index.html` 不在预期的位置上。 + +**判据**:`tar -tzf <包>` 的第一行若是 `.` 或 `./…`,即是这条。 + +**修法**:先 `cd` 进产物目录,再用通配展开成员名(`( cd "$WEB" && { shopt -s dotglob; tar -czf "$TAR" *; } )`), +并在发之前断言包里真的有 `index.html`(`tar -tzf "$TAR" | grep -qx 'index.html'`)。 + +**反例**:只看"打包成功 / 上传 HTTP 200"就当预览发好了 —— 那两步都不会因为包结构不对而失败。 + +## trap-10:依赖清单被静默改写 + +**症状**:一次 CI 通过之后,`go.mod` / `go.sum` / `package-lock.json` 与提交里的不一样了; +本地跑一遍还多了/少了几个依赖,没人改过它们。 + +**根因**:两个"顺手"的默认行为 —— `GOFLAGS=-mod=mod`(构建时自动补全/更新 `go.mod`)、 +以及缺锁文件时回落到 `npm install`(按 `package.json` 重算整棵依赖树并重写锁文件)。 +两者都让"依赖清单"变成**运行时产物**,而它本该是人 review 过的契约。 + +**判据**:夹具 = 门禁开始前后对这几个文件取 sha256;任何一步改写了它们 ⇒ 红。 + +**修法**:`GOFLAGS=-mod=readonly`;缺锁**直接失败**(不接受无约束安装); +`npm ci`(按锁装、锁与 `package.json` 不一致就报错)。见门禁的 `deps-install` 与 `manifests-locked` 两项。 + +**反例**:`if [ -f package-lock.json ]; then npm ci; else npm install; fi` —— 看起来"更健壮", +实际是给漂移开了后门。 + +## trap-11:汇总把「未运行 / 被跳过」当「通过」 + +**症状**:某个必需检查压根没跑(失败即停的后果、或运行时被 `if:` 跳过), +汇总却报"全绿";事后看报告,那一项**根本不在报告里**,谁都没发现。 + +**根因**:汇总逻辑只遍历"跑过的项"。没跑的项不出现 ⇒ 集合变小 ⇒ 全绿。 +另一种写法是 `skipped` 与 `success` 一起放行。 + +**判据**:给汇总喂一个"必需项缺失 / 必需项 skipped"的夹具,它**必须**非绿。 + +**修法**:清单里声明必需项集合,汇总按**清单**(不是按结果数组)逐项核对; +缺项记 `not_run` 并判红;`aggregate()` 只认 `success`。 +不适用要**在清单里声明**(本仓的 `required_in`),不能在运行时悄悄 skip。 + +**反例**:`status = "failure" if any(x == "failure" for x in results) else "success"`。 + +## trap-12:事件 SHA ≠ 检出 SHA + +**症状**:CI 里跑的是"分支当前 HEAD",而这次运行的事件指向的是**另一个提交**。 +表现是"我刚推的那一步好像没跑",或者更糟 —— 拿新代码的结论去解释旧代码的产物。 + +**根因**:工作流写 `git fetch --depth 50 origin "$BR" && git checkout -B "$BR" FETCH_HEAD`, +取的是**当时**的分支 HEAD。只要在事件产生之后又有人推了一次(或重跑旧运行),两者就分叉。 + +**判据**:`git rev-parse HEAD` 必须等于 `${GITHUB_SHA}`(**完整** SHA,不是短 sha)。 +不一致 ⇒ 红。 + +**修法**:检出后立刻核对;不一致时改按精确 SHA 取(`git fetch --depth 50 origin "$EVENT_SHA"`), +再取不到就失败。门禁的 `identity` 项会**再核对一次**(两道,故意的)。 + +**反例**:报告里只写"分支 main 的构建成功" —— 这个结论没有对应的提交。 + +## trap-13:密钥扫描规则过宽 ⇒ 永远的假红 + +**症状**:接入密钥扫描后立刻红,命中全是**正常代码**:`postgres://{u.quote(user)}:{u.quote(password)}@host/db` +(模板表达式)、`postgres://governance:***@postgres/governance`(脱敏占位)、 +`X-CI-Token: ${BRIDGE_TOKEN}`。 + +**根因**:规则用 `[^@\s]{6,}` 这种"很宽"的字符类去抓口令段,于是把变量插值、脱敏星号、 +模板表达式全部当成密钥。假红一旦出现,人就会把整个检查注释掉 —— 那比没有检查更糟。 + +**判据**:扫描器必须自带**双向夹具**:合成的真密钥要命中,**良性对照要零误报**, +而良性对照里要**钉住踩过的误报形状**(防回归)。 + +**修法**:只收"干净字符"的口令段(`[A-Za-z0-9+/=_\-]{6,}`),并对命中值做占位符判定 +(`${...}`、`<...>`、`***`、`changeme`…)。见 `scripts/check_secrets.py` 的 `RULES` 与 `--self-test`。 + +**反例**:为了让门禁变绿去放宽/注释规则 —— 那是降低规则换绿灯,规范 §4.2 明确禁止。 \ No newline at end of file