测试：验证套件

运行

just test
# or
python3 tests/validate.py

它可以从任何位置运行，只需要 Python 3（无第三方包，无需网络）。它为每项检查打印一行，只要有一项检查失败，就以非零状态退出， 因此适用于 CI，也适合作为 pre-commit 钩子。

它检查什么

• 预期的主题数量（脚本顶部的一个常量）。
• 每个部分内连续的编号，从 N.0 开始。
• 每个主题的 H1 与文件名中的小数一致。
• H1 标题与 spec/structure.md 一致，逐字符比对，而不只是开头的小数。
• 每个内容主题（第 1 至 8 部分，主题 N.1 及以上）中存在必需的部分，顺序与模板完全一致。
• 每个内容主题的最低字数（1,500 词），脚本中有一份允许名单，用于有意的例外。
• 任何 Markdown 文件中没有长破折号。
• 短破折号只出现在数字之间，因此“2.1–2.8”通过，其他则失败。
• 没有被禁用的措辞（“not only”、“but also”、“load-bearing”）。
• 所有内部 .md 链接都能解析。
• 正文中的交叉引用指向真实存在的主题：引用了磁盘上没有对应文件的主题编号会失败，所用的引用模式与 已发布站点自动为主题加链接时使用的相同。
• 维基百科链接形式正确（https://en.wikipedia.org/wiki/...）。
• spec/structure.md 与磁盘上的文件一致，双向。
• README、主页和内容页链接到每个主题。

检查失败时

失败的那一行会指出文件和问题。常见修复：

• 发现长破折号：改写句子以去掉“—”。不要只是删掉它。
• 缺少部分：从主题模板添加缺失的 ## 部分。
• 结构不匹配：你添加或重命名了主题却没有更新 spec/structure.md，或者反过来。让它们重新对齐。
• 链接损坏：修正路径，或在重命名之后更新它。
• 编号缺口：重新编号，使该部分从 N.0 起连续。

验证套件之外

• just spell 在仓库上运行 codespell。配置（包括误报忽略列表） 是 pyproject.toml 中的 [tool.codespell] 部分。
• just stats 从 tools/stats.py 打印一份 Markdown 报告（各主题字数、偏薄的主题、维基百科链接、参考文献条目）。

持续集成

• .github/workflows/test.yml 在每个拉取请求以及推送到非 main 分支时运行：验证套件和 codespell。这个仓库不构建 也不部署站点；渲染发生在独立的 software-engineering-metrics.github.io 仓库。
• .github/workflows/links.yml 每周用 lychee 检查外部链接（忽略模式在 .lycheeignore），并把结果保存在 一个“Link checker report”issue 中。外部链接被有意排除在 PR 路径之外。

测试不涵盖的内容

套件检查结构和风格，而不是真实性。它无法知道某条参考文献是否真实，或正文是否准确。请手工或通过调研核实引文和事实。 维基百科链接是否存在（与其形式不同）同样需要网络检查，套件有意把它省去，以便能够离线运行。