docsync

Overview ¶

baseline.go —— README「工程底座」表的机械判定（issue #31）。

为什么这张表需要门禁 ¶

它是本仓第二张规模声明表，历史上**八轮**全部靠「作者记得回来手算」： 11,491 → 13,336 → 16,974 → 18,100 → 18,678 → 19,573 → 19,679 → 19,624， 每轮都漂几十到上千行，期间没有任何信号。这正是本仓那条纪律的反面案例： **没人负责的东西会静默失真**。

更糟的是它连「测得准」都做不到：2026-11-06 同一批用例、生产代码一行未改， 覆盖率量出 85.5 / 85.0 / 87.0 三个值——因为覆盖率随**测的是哪个用例集合**变。 故本条只判**确定性量**（行数 / 文件数），覆盖率一格从表里删掉手抄的百分数 （改为「以 make cover-gate 输出为准」）：让散文去复述一个由门禁实时给出的 数字，只会制造两处不一致。

判据 ¶

三项都是确定值，**直接判相等，不留容差**。包表那 25% 容差是给「逐行涨落」留的 噪声滤波，而这表一旦容差就又能漂——它的历史漂移量本来就落在容差里。

三项口径与 README 里那三条重算命令逐字一致（非 _test.go 的 .go 文件数 / 行数、 _test.go 文件数；排除隐藏目录与 vendor）。

不判什么（写明，而不是假装覆盖） ¶

• 覆盖率：依赖跑的是哪个用例集合，是**测量**不是**声明**，见上。
• 结构阈值 / 门禁条数 / 例外登记数那几格：它们各自有执行体（policy + 门禁）， 数字写错不会让门禁失效，只是描述不准——判定成本高于收益。

表不在时怎么办 ¶

本条的语义是「**你声明了就必须是真的**」：README 里没有「工程底座」小节 ⇒ docsync 不判它（不声明就不会失真）。但小节存在而**行解析不出来**一定是坏了 （表被截断/改名/列数变了）⇒ 当场红，不能靠「没有行就没有比对」静默变绿。

Command docsync 校验 README 的两张声明表与仓库实际状态一致：

• 包清单表：包名 / 生产行数（相对容差）/ 外部依赖（见 pkgtable.go）
• 「工程底座」表：生产行数、生产文件数、测试文件数（**判相等**，见 baseline.go）

为什么要有这个命令 ¶

README 的包表是本仓唯一的对外规模声明，历史上长期手工维护，已经漂到 「netguard 声称 ~86 行 / 纯 stdlib 叶子层」而实际是 412 行且依赖 guardx 这种程度——而 make check 完全不覆盖文档，漂移没有任何信号。

按本仓既有的门禁口径（见 architecture-policy.yaml 头注：门禁不认文档里 说过要迁，不写进机器约束的约定半年后必然回退），这张表也必须有机器校验。

判定口径 ¶

• 生产行数：pkg/*.go 且不含 _test.go（表头已声明该口径）
• 外部依赖：生产代码 import 的仓外模块，取 module 前两段归并
• 本仓自身 import（github.com/yi-nology/goagent-kernel/...）不算外部依赖

两张表用**两套口径**是刻意的：包表的行数是约数（25% 容差滤逐行涨落）， 工程底座的三个数是声明值（判相等）。混用一套口径，等于让「跨量级的误述」 与「差一行」享受同一个宽容度——而后者正是前者藏身的地方。

pkgtable.go —— 包表的一侧：实测与比对（run() 的另一半见 main.go， 工程底座表的判定见 baseline.go）。

与 main.go 分开是因为一个文件装两件事会撞 max_file_lines（400）。拆的时候 按**判据的一侧**切，不是按行数切：这里处理的都是「包 → 行数 / 外部依赖」的 实测与集合比对，main.go 只留流程（读 README → 逐行判定 → 汇总问题）。