【免费下载链接】gsd-coreGit. Ship. Done - Core项目地址https://gitcode.com/gh_mirrors/ge/gsd-core点击查看免费下载本篇以 gsd-core 仓库归档 changeset.changeset/archived/3740-consolidate-phase-tests.md为核心深入剖析一次典型的测试集群合并工程实践Phase Lifecycle Module 的测试文件如何从 20 个收敛为 4 个同时满足lint-test-file-count的 allowlist ceiling 约束。读者将从中掌握该仓库测试文件数量门控的底层原理身份棘轮 identity ratchet、测试文件正确归并/重命名的判定准则以及如何把这一套治理方法复用到其他模块的测试集群中。一、背景为什么 gsd-core 要限制每个模块的测试文件数量gsd-core 的脚本目录中存在一个专门的 lint 门禁 scripts/lint-test-file-count.cjs其 allowlist 基线文件 scripts/lint-test-file-count.allowlist.json 的_doc字段明确说明Baseline of modules currently exceeding the 2-test-file limit. Each entry locks in TODAYs exact test filenames as the allowlisted set (identity ratchet). Adding a NEW test file to a capped module fails (novel). Removing one requires pruning this list (stale, ratchet-down). When a cluster drops to ≤ 2, remove its entry entirely. New entries require justification in PR description.这段描述浓缩了整套治理规则的四个要点数量上限默认情况下仓库要求每个模块以测试文件名的前缀归并如phase、milestone、config最多只有2 个测试文件allowlist 是例外名单历史上已经超出上限的模块被锁定进 allowlist锁定的是当天的确切文件名集合而不是单纯的文件数量身份棘轮identity ratchet向一个已被封顶capped的模块新增任何测试文件都会直接失败标记为novel反过来如果文件被删除导致数量回落到 ≤2该条目又必须整个从 allowlist 中移除标记为stale即 ratchet-down只允许往下收紧、不允许往上放宽新增条目需要理由想给某个模块新增 allowlist 许可必须在 PR 描述中给出 justification。因此当一个模块的测试文件数量持续膨胀时正确做法不是再申请一个更大的 allowlist而是像 PR #3740 这样主动合并测试集群在不改变上限的前提下把文件数量压下来。二、合并清单解读从 20 个文件到 4 个该 changeset 的 Summary 第一句话点明了目标将 Phase Lifecycle Module 的测试集群从 20 个文件合并为 4 个从而满足lint-test-file-count的 allowlist ceiling。具体动作分为三类2.1 10 个小体积 CJS bug-fix 测试文件并入phase.test.cjs合并的最大头是将 10 个小型 CJS bug-fix 测试文件全部并入 tests/phase.test.cjs。从当前仓库状态看这个合并的产物是一个体量相当可观的测试文件——tests/phase.test.cjs 全文件约 1.6 万行正是多份 bug-fix 测试内容合并到单一文件后的典型形态。这类合并之所以可行是因为这 10 个文件全部指向同一个生产 seamPhase Lifecycle 的 CJS 入口phase.cjs合并后测试仍能在同一个describe/test命名空间下运行且不改变任何被测行为。2.2 SDK 测试文件的合并历史记录changeset 还记录了 SDK 侧的合并动作将sdk/src/phase-runner-types.test.ts和sdk/src/phase-prompt.test.ts合并进sdk/src/phase-runner.test.ts。这里需要说明一个仓库现状根据 CONTEXT.md 中 Phase Lifecycle Module 条目的记载phase-runner.ts、phase-prompt.ts以及types.ts中的事件定义均已随 SDK 包按 ADR-0174 退休当前仓库已不存在sdk/目录。因此这部分合并属于该 changeset 归档时的历史记录反映了SDK 尚未退休时代的同类治理动作——即便在 SDK 侧测试文件同样遵循数量收敛的纪律。2.3 4 个归属错误测试文件的重命名changeset 明确列出 4 个被重命名的测试文件其共同特征是其生产 seam 并不是phase.cjs/phase.ts此前以phase-前缀命名属于误归属原文件名重命名后说明phase-researcher-app-awaregsd-researcher-app-aware生产 seam 属于 researcher而非 phasephase-researcher-flow-diagramgsd-researcher-flow-diagram生产 seam 属于 researcherfeat-3023-phase-type-modelsfeat-3023-model-phase-types主题是 model 的类型模型而非 phasephase-6-cjs-sdk-seam-contractscjs-sdk-bridge-seam-contracts契约对象是 CJS/SDK bridge seam这一重命名动作的价值在于lint-test-file-count按文件名前缀将测试文件归并到模块如phase-*、milestone-*一个实际测试 researcher 行为的文件若顶着phase-前缀会被错误地计入 Phase 模块的测试数量既虚增了该模块的 count又掩盖了它真正归属模块的测试覆盖情况。重命名让文件名 → 生产 seam → allowlist 归并三者重新对齐。三、顺带修复phasePlanIndex诊断通道改为warnings[]数组#3430合并测试的同时该 changeset 还修复了一个诊断通道的缺陷issue #3430非规范 plan 文件名的告警原本通过一个独立的单数warning字段透出现改为流经warnings[]数组与其他诊断信息并列输出。这一改动的工程意义在于单一数据通道调用方不再需要同时检查warning和warnings[]两处字段只要统一消费warnings[]即可拿到全部诊断一致性其他诊断如 phase-id 校验、STATE.md 陈旧检测等都走warnings[]phasePlanIndex此前是唯一的例外通道合并后消除了通道分裂。从仓库测试可找到对应佐证tests/planning-inspect.test.cjs 中存在phasePlanIndexAndPlanningInspectAgreeOnPlanObjectiveAndTaskCount与phasePlanIndexBehaviorUnchangedByPlanDocumentExtraction两个测试用例前者验证phasePlanIndex与planning-inspect在计划目标与任务计数上保持一致后者专门验证提取 plan 文档后phasePlanIndex行为不变——这正呼应了 changeset 中合并/重构不得改变对外行为的回归测试要求。四、allowlist ceiling 更新从 20 到 4以及当前仓库状态changeset 同步更新了 scripts/lint-test-file-count.allowlist.json将phase条目的 ceiling 从20 下调到 4——这是ratchet-down只降不升精神的直接体现测试集群收敛后允许的上限必须同步收紧而不是维持原状。从当前仓库的 allowlist 状态看phase条目现在允许的文件清单为 6 个文件以 issue 3186 为依据其中 tests/phase.test.cjs 正是本次合并的核心产物。可以推断归档后该模块的测试集群又经历了后续的少量增补但整体上远低于合并前的 20 个文件量级——这从侧面说明本次合并对 Phase 测试集群的收敛是持久且显著的。此外该 changeset 头部带有!-- docs-exempt: internal test refactor only — no user-facing surface changed --注释向仓库的文档守卫docs-exempt 机制声明本次变更属于内部测试重构未改变任何用户可见表面因此不需要伴随文档更新。这同样是一个值得借鉴的仓库规范——测试重构与功能变更在文档义务上被明确区分。五、CONTEXT.md 词汇表Phase Lifecycle Module 条目合并的同时changeset 为 CONTEXT.md 新增了Phase Lifecycle Module的词汇表条目。该条目位于 CONTEXT.md 的模块索引区记载了该模块的完整职责边界职责范围phase 的 create、rename、complete、remove、list 与 plan-index 操作以及 phase-dir 前缀校验、STATE.md 陈旧检测与自动清理auto-prune入口 seamgsd-core/bin/lib/phase.cjsCJS 表面类型化事件GSDPhaseStartEvent、GSDPhaseStepStartEvent、GSDPhaseStepCompleteEvent、GSDPhaseCompleteEvent历史边界SDK 原生查询表面、types.ts事件定义、phase-runner.ts、phase-prompt.ts均已随 SDK 退休ADR-0174。这解释了为何本次合并要同时处理 SDK 测试模块的测试集群定义并不局限于单一运行时只要共享同一个模块主题Phase Lifecycle无论其测试挂在 CJS seam 还是当时的SDK seam 下都统一纳入集群数量核算。六、同一治理模式的系列实践不止 Phase 一个模块3740并不是孤例。在 .changeset/archived/ 目录下可以找到同一批测试集群合并主题的姊妹 changeset.changeset/archived/3742-consolidate-worktree-tests.md——worktree 测试集群合并.changeset/archived/3753-consolidate-milestone-tests.md——milestone 测试集群合并CONTEXT.md 中对应记载为 PR #375310 文件 → 4 文件.changeset/archived/3755-consolidate-init-tests.md——init 测试集群合并.changeset/archived/3757-consolidate-runtime-artifact-layout.md、.changeset/archived/3758-consolidate-installer-tests.md、.changeset/archived/3761-consolidate-graphify-tests.md 等。可以看出这是一轮有计划、成体系的测试治理专项多个超限模块在同一时期被统一收敛。这套方法可以概括为三条可复用的操作准则合并优先于扩容模块测试文件超限时先按生产 seam 归类合并小文件同 seam 的 bug-fix 测试可以安全并入主测试文件而不是向 allowlist 申请更大额度重命名对齐归属凡生产 seam 不属于该模块前缀的文件一律重命名为其真实 seam 的命名如phase-*→gsd-*避免污染模块计数同步 ratchet-down合并完成后allowlist 的 ceiling 必须同步下调20 → 4并配套更新 CONTEXT.md 词汇表与回归测试形成代码收敛 门禁收紧 文档同步的完整闭环。七、实践启示如何在自己的 PR 中安全地执行测试合并结合 scripts/lint-test-file-count.cjs 与 tests/lint-test-file-count.test.cjs 中的行为验证执行同类合并时需注意以下门禁行为新增文件即失败只要模块仍在 allowlist 中向该模块添加任何新测试文件都会被判定为FAIL_NOVEL_FILES即使总数量没变测试用例明确覆盖了删除一个旧文件、新增一个新文件、数量不变但身份变了的场景——身份棘轮按文件名集合比对而非数量删到上限以下必须清空条目若模块文件数回落到 ≤2 而 allowlist 条目仍在会触发FAIL_STALE_ALLOWLIST整个条目必须被移除allowlist 判定状态允许的模块返回OK_IN_ALLOWLIST未超限的普通模块正常通过超限且不在 allowlist 的模块直接失败——因此在做合并时务必保证最终文件集合与 allowlist 记录逐字节一致。实操上一个完整的合并 PR 应包含合并后的主测试文件行为不变的回归内容、被重命名的文件、allowlist ceiling 的下调、CONTEXT.md 词汇表条目以及若涉及诊断字段调整对应的契约测试如 tests/planning-inspect.test.cjs 中验证phasePlanIndex行为不变的用例。这正是 changeset3740-consolidate-phase-tests所展示的完整样板以一次内部重构同时完成测试数量收敛、模块归属纠正、诊断通道统一与门禁收紧且全程不触碰任何用户可见行为。赞分享【免费下载链接】gsd-coreGit. Ship. Done - Core项目地址https://gitcode.com/gh_mirrors/ge/gsd-core点击查看免费下载相关推荐Get Shit Done Worktree 测试集群合并实战从 13 个文件收敛到 3 个由 lint-test-file-count 棘轮治理驱动Get Shit Done Worktree 测试集群合并实战从 13 个文件收敛到 3 个由 lint test file count 棘轮治理驱动 本篇人工智能AI 应用提示工程开发工具工作流自动化AI Agentgsd-core Worktree 测试集群合并重构从 13 个文件到 3 个文件的收敛实践gsd core Worktree 测试集群合并重构从 13 个文件到 3 个文件的收敛实践 本篇技术指南聚焦 gsd core 仓库中一次典型的测试维护重构OmniRoute 测试覆盖率治理计划从 56.95% 到 90% 的分阶段攀升与棘轮机制OmniRoute 测试覆盖率治理计划从 56.95% 到 90% 的分阶段攀升与棘轮机制 导读 本文基于 OmniRoute 仓库中的 Test Cover后端API网关LLM 网关人工智能大模型MCP 服务桌面应用创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考