开源项目archify的源码分析四：源码证据与测试体系

flash俊杰
2 阅读4分钟

源码证据与测试体系

Git 固定提交证据

架构图可以完全来自描述，也可以选择携带源码依据。证据是显式开启的能力：IR 中声明 meta.repository 与节点 sources，渲染命令加 --repo-root，校验才会执行。v3.0 起五种图表类型都支持证据，各自挂在本类型的节点集合上（components、nodes、participants、states）。

校验在 renderers/shared/repository-evidence.mjs 中实现，全部通过本地 Git 完成：

  1. 仓库身份：确认 repo-root 的 Git 顶层目录、远端来源与 IR 声明一致；远端 URL 在校验日志和回执中脱敏（redactRepositoryRemote），区分 GitHub、Gitee 与 link_mode: "local-only" 三种链接模式。
  2. 固定修订：证据必须钉在 40 位完整 SHA 上。所有 Git 调用统一带 --no-replace-objects，忽略本地 replacement refs，始终读取该提交的原始对象，防止被替换的文件内容或行范围造成误接受。
  3. 批量对象读取：先在一次 git cat-file --batch-check 会话中核对全部引用对象的类型，再只对需要验证行内容的 blob 执行 --batch 读取，路径级引用不加载文件内容；批量读取失败时按源顺序回退到单文件路径，保留各自大小限制。单个 blob 上限 16MB。
  4. 路径包含与行界：引用路径必须包含在仓库内，引用行必须落在该固定 blob 的真实行数范围内；控制字符等非法路径直接拒绝。
  5. 负载键控：通过校验的证据以节点 id 为键进入产物，Viewer 中表现为节点上的 SRC n 胶囊，链接指向固定 commit 的文件与行号。

证据只陈述"作者在该提交读到了这些文件与行"，不推断代码当前行为，也不参与拓扑生成。

测试规模

archify/test/ 下约 170 个测试文件、6.4 万行测试代码，与约 4 万行实现代码形成约 1.6:1 的比例。测试与实现同构：渲染器共享层的每个模块几乎都有同名测试文件（如 geometry.test.mjs、spatial-grid.test.mjs、path-semantics.test.mjs、i18n.test.mjs）。

测试基于 Node.js 内置测试运行器（node --test），不引入测试框架依赖。

测试分层

纯逻辑单元测试覆盖几何与规则的确定性：矩形重叠容差、自动端口展开、交叉消解、标签避让、折线节奏、时序列宽、生命周期泳道规划、workflow 编译器契约。这一层数量最大、运行最快。

契约测试锁定机器可读的边界：CLI 输出类型、诊断码与字段、sidecar 路径长度、交付契约、更新契约、Skill 元数据。Agent 依赖的稳定回执就是靠这些测试冻结的。

文件系统与原子性测试针对真实磁盘行为：原子写入恢复、渲染器原子写、finalize 路径、sidecar 命名、可移植路径、checkout 换行符。atomic-output-recovery.test.mjs 等用例专门制造崩溃与竞争场景。

Golden 测试（test/golden.mjs）对比提交在仓库中的示例产物，任何非预期的渲染字节变化都会被发现；生成物更新必须显式重建。

真实浏览器测试以 -browser.test.mjs 命名，经 test/helpers/desktop-browser.mjs 驱动桌面 Chrome，验证 Viewer 相机、语义透镜、护照移动、读者布局沉降、字体加载、动效治理、导出清理等只能在浏览器中复现的行为。浏览器测试由 scripts/run-browser-tests.mjs 统一编排，CI 工作流定义在 .github/workflows/ci.yml。

烟雾测试覆盖浏览器外的产物面：webm-artifact.smoke.mjs 验证视频导出，site-language-integration.mjs 验证语言集成。

生成物一致性检查

package.json 的 test 脚本在跑测试前先跑四组检查：

check:viewer            # Viewer 生成物与模板同步
check:brand-marks       # 品牌标记生成物同步
check:validators        # AJV 验证器生成物同步
check:release-identity  # 版本徽章与发布身份一致

生成代码（验证器、品牌标记、Viewer）全部提交在仓库中，检查脚本用 --check 模式比对重新生成的结果，防止 Schema 改了但忘记重新生成这类漂移。

基准与修复实验

benchmarks/ 下有两组持续性实验：

  • ordinary-model-floor/：用同一批五个场景测量普通模型一次性产出合格 IR 的下限，保存不同模型与策略的结果 JSON，支撑"不依赖顶尖模型也能用"的产品判断。
  • repair-rounds/：用缺陷清单、修复算子和 token 计量衡量门禁引导下的修复轮次，验证"两轮聚焦修复上限"在真实缺陷集上的表现。

这些数据是工程决策依据而不是营销素材；journal/ 目录保留了各轮视觉演进与特性研究的研究记录。

avatar
文章
阅读
粉丝