JianFeeeee
d562f55d78
★ 背景: 我上封把"调用者既不 export 表、又忘了调 report"记为**边界**，理由是"闭合它要本文件
知道调用者控制流 —— 做不到"。pi 指出**前提可以换掉**（我复核采纳）:
病根不是"控制流不可知"，而是"**声明**（赋值）与**检查**（调用）是两个可分离的动作"。
⇒ 把声明做成**动作**: `agentmail_require <命令…>` = 赋值 + 立刻检查 ⇒ 该状态**不存在**。
★ 改动:
· env-defaults.sh 加 `agentmail_require()`（内部就是赋值 + agentmail_env_check_require）
· 三个调用者由 `AGENTMAIL_REQUIRE="…"` 改为 `agentmail_require …`（各 1 行）
也顺带把"重新导出为环境变量"的写法去掉了 —— 表只在本进程内被 ③b 读，不需要 export
· 新判据 `deploy/check-require-declaration.sh`（755）: deploy/ 下的**调用者**不得写裸赋值
· install.sh 接线，走 `CHECK_GATE_RC` **累积**通道（照 check-file-modes.sh 的既有做法:
直接调会在 set -e 下中止，把后面的收尾诊断全吃掉）
★★ 判据自己的两个 bug，都是**实测**抓出来的（不是审出来的）:
① 假红: 我第一版按"`deploy/**/*.sh` 全扫"划范围 ⇒ 立刻把 `env-defaults.sh:449`
（`agentmail_require()` 函数体里的 `AGENTMAIL_REQUIRE="$*"` —— **动作自己的实现**）
判成违规。⇒ 改为按**性质**划: "调用者"= **真的 source 了本库**的文件，
减去定义动作的那个库自己（"调用者"这个身份由 source 这个动作定义，不由目录猜）。
② ★ 假阴且**不稳定**: `strip_comments "$f" | grep -q …` 在 `set -o pipefail` 下，
`grep -q` 一命中就退出 ⇒ `sed` 收 SIGPIPE（rc=141）⇒ **管道整体 141** ⇒ if 判假 ⇒ 漏文件。
实测同一个脚本两次分别找到 **2** 个与 **1** 个调用者（实际 3 个），
而 rc=141 被 if 静默吞掉 ⇒ 集合**偏少且不稳** ⇒ "裸赋值 0 处"会是**假绿**。
⇒ 改为先收集到变量、再 `grep <<<"$body"`（无管道）。修后重复 10 次**稳定 3 个**。
★ 验证（全部真跑）:
· 基线 rc=0（3 个调用者，裸赋值 0 处）；重复 10 次稳定 3
· 变异①: 把 redeploy-plugin.sh 改回裸赋值 ⇒ rc=**1** ✓
· 变异②: 注释掉一个调用者的 source（仍剩 2）⇒ rc=0 ✓ 非空转
· 变异③: 三个 source 全注释 ⇒ **集合空** ⇒ rc=**1** ✓（防空转，不是恒绿）
· 每个变异后**还原**并复测 rc=0；`git diff --numstat` 确认只有预期行
· criteria-hygiene **7/7** 绿（新 check-*.sh 已被 install.sh 真调用）
· pi 的 env-guard **17/17** 绿；五个脚本 bash -n 全过；生产未动
★ 残留（判据头已如实写）: 盖"字面裸赋值"，**不盖间接赋值**（经 eval/read/env 注入）——
补它需 shell 语义分析，超出"一条 grep 型判据"的射程。
128 lines
6.6 KiB
Bash
Executable File
128 lines
6.6 KiB
Bash
Executable File
#!/usr/bin/env bash
|
||
# 政策：**调用者**声明"我依赖哪些外部命令"**必须**走动作 `agentmail_require`，
|
||
# 不许写裸赋值 `AGENTMAIL_REQUIRE="…"`。
|
||
#
|
||
# # 为什么有这条（一个实测出来的活缺陷）
|
||
#
|
||
# `deploy/lib/env-defaults.sh` 的 ③b 会检查调用者声明的命令在不在，
|
||
# 缺一个就 `exit 2` + 人话（"命令不在"与"命令在但输出为空"必须分开 ——
|
||
# 后者会让下游把"工具缺失"读成"检查通过"，见该文件里 journalctl 那两处假绿）。
|
||
#
|
||
# ★ 而那段检查**原先只在 `source` 期跑**，三个调用者却都是**先 source 后赋值**：
|
||
# install.sh source 131 / 赋值 135
|
||
# redeploy-gateway.sh source 42 / 赋值 46
|
||
# redeploy-plugin.sh source 52 / 赋值 56
|
||
# ⇒ source 那一刻表是**空的** ⇒ `[ -n "${AGENTMAIL_REQUIRE:-}" ]` 直接跳过
|
||
# ⇒ **那张表从未被检查过**。实测 A/B：
|
||
# AGENTMAIL_REQUIRE=__no_such_cmd . env-defaults.sh ⇒ rc=2（检查本身是好的）
|
||
# . env-defaults.sh; AGENTMAIL_REQUIRE=__no_such_cmd ⇒ rc=0（**漏过**）
|
||
#
|
||
# 修法是两处都挂检查（source 期 + report 内）。但那只堵住"**恰好忘了调 report**"——
|
||
# 病根是"**声明**（赋值）与**检查**（调用）是两个可分离的动作"。
|
||
# ⇒ 把声明本身做成**动作**：`agentmail_require <命令…>` —— 想声明就**必然**检查，
|
||
# "赋了值但那次检查没跑"这个状态**从表示上不存在**。
|
||
#
|
||
# # 为什么需要**这条判据**（而不是只靠"大家都记得用动作"）
|
||
#
|
||
# 下一个新调用者仍可能写裸赋值 —— 而裸赋值**不报错、不警告**：
|
||
# 它只是让那张表在 source 后才存在，于是检查又一次静默失效（与上面那个缺陷同形）。
|
||
# ⇒ 判据的作用是**让"写裸赋值"立刻变红**，而不是靠人记住。
|
||
#
|
||
# # 射程（pi 2026-09-25 §四 要求写清它管什么、不管什么）
|
||
#
|
||
# **管的集合 = "调用者"**，定义为：`deploy/` 下 `*.sh` 里**真的 source 了**
|
||
# `env-defaults.sh` 的那些文件，**减去定义动作的那个库自己**。
|
||
# ⇒ 理由是"调用者"这个身份**由 source 这个动作定义**，不由文件名或目录猜。
|
||
# ⚠️ 我第一版按"`deploy/**/*.sh` 全扫"划范围，**实测立刻假红**：
|
||
# 它把 `env-defaults.sh:449`（`agentmail_require()` 函数体里的
|
||
# `AGENTMAIL_REQUIRE="$*"` —— **动作自己的实现**）判成违规。
|
||
# ⇒ 那是"动作的定义点"，不是"调用者的使用点"，两者必须分开。
|
||
#
|
||
# 管：调用者里**行首**的裸赋值 `AGENTMAIL_REQUIRE=…`（去掉注释后匹配）
|
||
# 不管：
|
||
# · 定义动作的那个库（`deploy/lib/env-defaults.sh`）—— **它不是自己的调用者**，
|
||
# 且它的 `agentmail_require()` 体内**必须**有那行赋值（那是实现，不是违规）
|
||
# · `AGENTMAIL_REQUIRE_SELF=…`（**不同名**，与 `=` 匹配天然不撞）
|
||
# · 注释里提到 `AGENTMAIL_REQUIRE` 的文字（strip 注释后再匹配 ⇒ 不误伤）
|
||
# · **没 source 本库的文件**：它们拿不到 ③b 检查，故"用哪种写法"与本政策无关
|
||
# （本政策只保证"**声明了就被检查**"，不保证"人人都会声明"）
|
||
# · **间接**赋值（`v=AGENTMAIL_REQUIRE; eval "$v=…"`、经 `read`/`env` 注入等）
|
||
# ⇒ 这类绕过本判据**仍可漏**。本判据盖"字面裸赋值"，不声称盖住全部写法。
|
||
#
|
||
# 退出码：0 = 全走动作式；1 = 有裸赋值 **或**集合为空（防"判据静默空转"）；2 = 环境不足
|
||
|
||
set -uo pipefail
|
||
|
||
REPO="${AGENTMAIL_REPO:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}"
|
||
cd "$REPO" || { echo " [FAIL] 进不去仓库根 $REPO" >&2; exit 2; }
|
||
|
||
for c in grep awk sed find; do
|
||
command -v "$c" >/dev/null 2>&1 || { echo " [FAIL] 环境不足：缺少 $c" >&2; exit 2; }
|
||
done
|
||
|
||
LIB_REL='deploy/lib/env-defaults.sh'
|
||
|
||
# ★★ 不要写 `strip_comments "$f" | grep -q …`：`set -o pipefail` 下 `grep -q`
|
||
# 一命中就退出，`sed` 随即收到 SIGPIPE（rc=141），**管道整体返回 141** ⇒
|
||
# `if` 判**假** ⇒ 该文件被漏掉。而它退出的时机取决于缓冲区 ⇒ **结果不稳定**。
|
||
# 实测（我第一版）：同一条命令两次分别找到 **2** 个与 **1** 个调用者
|
||
# （三个调用者只认出一两个），而 `rc=141` 被 `if` 静默吞掉 ——
|
||
# 一个**不稳定且偏少**的集合，正好会让"裸赋值 0 处"变成假绿。
|
||
# ⇒ 正确做法：先把去注释结果**收集到变量**，再对它做匹配（无管道、无 SIGPIPE）。
|
||
strip_comments() { sed 's/#.*$//' "$1"; }
|
||
|
||
# ① 找"调用者"：非注释行里以 `. ` 或 `source ` 起头、且提到 env-defaults.sh 的文件。
|
||
callers=""
|
||
for f in $(find deploy -name '*.sh' -type f | sort); do
|
||
[ "$f" = "$LIB_REL" ] && continue # 定义点不是调用点（见射程）
|
||
body="$(strip_comments "$f")"
|
||
case "$body" in
|
||
*env-defaults.sh*)
|
||
# 无管道匹配：`grep` 读文件而非读管道 ⇒ 不会因 SIGPIPE 造出不稳定的 rc。
|
||
if grep -qE '^[[:space:]]*(\.|source)[[:space:]].*env-defaults\.sh' <<< "$body"; then
|
||
callers="$callers $f"
|
||
fi
|
||
;;
|
||
esac
|
||
done
|
||
unset body
|
||
# shellcheck disable=SC2086
|
||
set -- $callers
|
||
n_callers=$#
|
||
|
||
# ② 防空转：集合为空 ⇒ 判**红**，不是"通过"
|
||
if [ "$n_callers" -lt 1 ]; then
|
||
echo " [FAIL] 一个 source env-defaults.sh 的调用者都没找到 —— 大概率是路径/目录变了。" >&2
|
||
echo " 本判据的集合是「调用者」，集合空了它就**静默空转**（恒绿）⇒ 必须判红。" >&2
|
||
exit 1
|
||
fi
|
||
|
||
fails=0
|
||
for f in "$@"; do
|
||
hits="$(strip_comments "$f" | grep -nE '^[[:space:]]*AGENTMAIL_REQUIRE=' || true)"
|
||
[ -z "$hits" ] && continue
|
||
while IFS= read -r h; do
|
||
[ -z "$h" ] && continue
|
||
printf ' [FAIL] %s:%s 用了裸赋值（应改为 `agentmail_require <命令…>`）\n' "$f" "${h%%:*}" >&2
|
||
fails=$((fails + 1))
|
||
done <<< "$hits"
|
||
done
|
||
|
||
if [ "$fails" -gt 0 ]; then
|
||
cat >&2 <<'MSG'
|
||
|
||
为什么必须走动作：`AGENTMAIL_REQUIRE="…"` 只是**赋值**，而检查在
|
||
`env-defaults.sh` 的 ③b（source 期）—— 赋值在它**之后** ⇒ 那次检查读到空表
|
||
⇒ **整张表从未被检查过**（2026-09-25 实测的活缺陷）。
|
||
后续那次检查（report 内）只接住"**记得调 report**"的情形；
|
||
写成动作则"赋值与检查"**不可分离** ⇒ 忘不忘都不影响。
|
||
|
||
改成：
|
||
agentmail_require git go npm node curl systemctl flock
|
||
MSG
|
||
exit 1
|
||
fi
|
||
|
||
awk -v n="$n_callers" 'BEGIN{printf " 通过 调用者声明全走 `agentmail_require` 动作（%d 个调用者，裸赋值 0 处）\n", n}'
|
||
exit 0
|