【免费下载链接】gsd-coreGit. Ship. Done - Core项目地址https://gitcode.com/gh_mirrors/ge/gsd-core点击查看免费下载导读本文基于 gsd-core 仓库中 .changeset/archived/3753-consolidate-milestone-tests.md 这一归档 changelog 片段剖析 PR #3753 完成的Milestone 模块测试簇收敛重构将 10 个测试文件合并为 4 个在不丢失任何断言的前提下把该模块的测试文件数压回lint-test-file-count允许列表allowlist上限之内。读完本文你将理解 gsd-core 的测试文件数量闸门cap allowlist 棘轮机制如何运作、这次收敛的具体拆并映射以及每个合并后的测试文件实际覆盖的 Milestone 模块行为归档布局、代码块边界解析、阶段过滤、版本透传等。一、背景changeset 片段与内部测试重构的定位该文档是 gsd-core 基于 .changeset/README.md 所述机制写入的per-PR CHANGELOG 片段。这类片段以形容词-名词-名词.md随机命名以避免并发 PR 在编辑CHANGELOG.md时冲突释放时自动并入顶层变更日志。本片段前导元数据如下--- type: Fixed pr: 3753 ---并在注释中明确声明docs-exempt: internal test refactor only — no user-facing surface changed——即这是纯内部测试重构不改变任何用户可见的命令行为因此不需要额外的文档变更。它属于type: FixedKeep a Changelog 允许的六种类型之一表示修复的是仓库自身的工程结构问题而非用户功能缺陷。从归档目录.changeset/archived/可以看到同一时期存在一批兄弟收敛PR3740-consolidate-phase-tests.md、3742-consolidate-worktree-tests.md、3755-consolidate-init-tests.md、3757-consolidate-runtime-artifact-layout.md、3758-consolidate-installer-tests.md、3761-consolidate-graphify-tests.md 等。可见这是一场跨模块的测试簇收敛运动Milestone 只是其中一站——PR #3753 使该模块成为这场运动中的一环。二、闸门机制lint-test-file-count 的 cap 与 allowlist 棘轮PR #3753 的动机直接指向scripts/lint-test-file-count.cjs。该脚本的注释给出了明确规则max 2 test files per production module … Cap is 2 (primary one integration). Over-limit clusters must be in the allowlist with the EXACT set of test filenames grandfathered (identity ratchet via allowlist-ratchet.cjs).核心要点默认上限每个生产模块扫描sdk/src/query/、sdk/src/、gsd-core/bin/lib/、bin/下源码最多对应2 个测试文件主测试 一个集成测试allowlist 豁免历史遗留的超限簇可以进入 scripts/lint-test-file-count.allowlist.json但必须精确列出现有测试文件名——这是一个身份棘轮只允许收敛减少文件数不允许新增文件后再挂靠豁免四种裁决OK_UNDER_LIMIT低于上限、OK_IN_ALLOWLIST与 allowlist 精确匹配、FAIL_EXCEEDS_LIMIT超限且无豁免、FAIL_NOVEL_FILES新增了 allowlist 之外的文件。此外还有FAIL_STALE_ALLOWLIST——当簇已收敛到默认上限以内时整个 allowlist 条目反而成为过期必须删除这是向下收紧的失败信号防止豁免被永久保留。PR #3738 引入了这一上限机制后Milestone 模块当时以 10 个测试文件处于超限状态PR #3753 的任务就是把它收敛回阈值之内。从当前 scripts/lint-test-file-count.allowlist.json 的milestone条目看簇内现在保留 8 个文件milestone.test.cjs、milestone-archive.test.cjs、milestone-helper.test.cjs、milestone-prefixed-convention.test.cjs、milestone-summary.test.cjs、milestone-window-drift-guard.test.cjs、milestone-window-single-owner.test.cjs、milestone-archive-hygiene.test.cjs条目issue字段记录为 3216——可以推断 PR #3753 合并后模块又因后续新增测试而重新进入 allowlist说明上限 豁免是持续演进的平衡机制而非一次性收敛。三、收敛映射10 个文件如何合并为 4 个片段明确列出了四步合并动作这是全文的技术骨架动作结果文件吸收来源覆盖行为重写tests/milestone.test.cjs869 → 720 行milestone-regex-global.test.cjs、bug-3043-milestone-complete-scope.test.cjs引入紧凑共享 helper整合 regex-global 修复与版本作用域回归新建tests/milestone-archive.test.cjs505 行bug-2684、bug-2787、bug-3164、bug-3600里程碑归档布局、围栏代码块解析、阶段过滤器、版本透传扩充tests/milestone-summary.test.cjs471 行milestone-audit.test.cjs里程碑摘要与审计不动sdk/src/milestone-runner.test.ts421 行—SDK 侧断言原样保留注意片段中标注的行数是PR #3753 合并时刻的快照。当前仓库中这些文件已随项目演进继续增长——例如 tests/milestone.test.cjs 现为 2731 行、tests/milestone-archive.test.cjs现为 1362 行、tests/milestone-summary.test.cjs 现为 500 行。因此引用这些数字时应当理解为当时的合并基线而非当前规模。四、合并后的每个文件实际覆盖什么结合仓库源码4.1 tests/milestone.test.cjs —— 主测试簇文件头注释声明其职责Covers: milestone complete command, phases clear command, requirements mark-complete command (regex-global fix), new-milestone workflow verification gate, milestone complete version scoping (#3043).结合当前源码它内部通过runGsdTools直接驱动 CLI、以临时工程createTempProject为夹具覆盖的关键断言包括#2111 current_phase 保全seed STATE.md 使current_phase只存在于 frontmatter跑milestone complete v0.5 --name Test --confirm后断言 frontmatter 中的current_phase仍为19——防止未锚定的解析器从版本字符串里挖出数字并覆盖真实阶段号归档主路径milestone complete v1.0 --name MVP Foundation --confirm后断言output.version v1.0、output.phases 1、output.archived.roadmap/requirements为真且磁盘上确实生成milestones/v1.0-ROADMAP.md、milestones/v1.0-REQUIREMENTS.md与MILESTONES.mdMILESTONES.md内容同时包含里程碑名与阶段 oneliner#2118 --dry-run 零副作用不产生归档、不重写 STATE.md、不移动阶段目录。4.2 tests/milestone-archive.test.cjs —— 归档布局与阶段过滤器文件头注释点名了四个被吸收的 bugbug #2684: milestone.complete forwards version to phases.archive / bug #2787: extractCurrentMilestone fenced code block boundary / bug #3164: validate consistency/health/find-phase with milestone-archive layout / bug #3600: getMilestonePhaseFilter with project-code-prefixed directories其中值得展开的两个核心行为#2684 版本透传milestone.complete v1.0不再抛 version required--archive-phases时版本正确转发到归档路径生成milestones/v1.0-phases目录同时锁定phases.archive不再是直接公开子命令调用会得到Unknown phases subcommand只能经由milestone.complete触发——测试用负例固化了这一接口收紧#2787 围栏代码块边界extractCurrentMilestone必须跟踪 Markdown 围栏fenced code block边界。测试构造一个在代码块内部出现形似里程碑结束标题的行断言roadmap analyze仍返回全部阶段——防止代码块内的标题被误判为里程碑边界。4.3 tests/milestone-summary.test.cjs —— 摘要命令与审计该文件合并了milestone-audit.test.cjs其头注释说明职责Validates the milestone-summary command, milestone-audit module (#2158), workflow audit gates (complete-milestone, verify-work), and STATE.md template.它除了对 commands/gsd/milestone-summary.md 与 gsd-core/workflows/milestone-summary.md 做文档契约检查frontmattername: gsd:milestone-summary、execution_context引用 workflow、可选[version]参数带argument-hint还验证complete-milestone、verify-work工作流中的审计闸门——这正对应CONTEXT.md词条中 Milestone 模块审计侧面的工程约束。4.4 SDK 侧保持不变milestone-runner.test.ts421 行不在收敛范围内保留了 SDK 查询面的 11 条断言。这体现了本次重构的原则只合并同质的 CJS 集成测试不触碰 SDK 独立测试面把改动面控制在最小。五、无回归保证断言保全与 Glossary 词条片段给出两个硬性保全数字99 条 CJS 断言全部保留原 10 个文件中的断言总量11 条 SDK 断言不变。这正是收敛而非删减的验收标准——测试文件数量下降但覆盖面不缩水行数的下降如 869 → 720来自共享 helper 抽取紧凑化writeState、writeRoadmap、mkPhaseDir等夹具工厂而不是删除断言。当前 tests/milestone.test.cjs 顶部仍能看到这套共享 helperwriteState/writeRoadmap/mkPhaseDir印证了该模式被保留并持续演进。同时PR 为CONTEXT.md增加了Milestone Module 词条。CONTEXT.md 的 Glossary — Domain modules and seams 一节中该词条定义了模块边界Module owningmilestone complete归档 roadmap/requirements/phases、构建 MILESTONES.md 条目、更新 STATE.md、requirements mark-completecheckbox 表格更新含 regex-global-state 修复、phases clear。关键行为milestone-phase 作用域从 ROADMAP.md 里程碑切片提取阶段、支持CK-01-name这类 project-code 前缀目录、排除先前里程碑阶段、milestone-archive 布局.planning/phases/缺失时从.planning/milestones/v*-phases/解析阶段目录、extractCurrentMilestone中的围栏代码块边界追踪。Source of truth:gsd-core/bin/lib/milestone.cjs。可见测试收敛与领域词条是配套动作测试文件是模块行为的锁词条是模块边界的文档化声明二者共同构成 Milestone 模块的契约 证据双保险。六、演进与现状从 4 文件到 8 文件片段末尾提到一个细节allowlist 更新推迟到 PR #3738 合并后的 rebase 中执行rebase 前milestone条目会从 10 → 4。这与 lint 脚本的棘轮语义一致——FAIL_STALE_ALLOWLIST要求簇收敛后必须同步修剪 allowlist 条目否则会以过期豁免的形式继续失败。从当前仓库状态看收敛后的 4 个文件随后又因新增覆盖milestone-window-*系列、milestone-helper、milestone-prefixed-convention、milestone-archive-hygiene等扩展为 8 个并重新进入 allowlist。这说明该闸门的设计目标是防止无限蔓延而非冻结测试规模新行为可以继续加测试但每一次扩展都要显式登记豁免让测试文件的增长始终处于可见、可审计的状态。七、可复用经验测试簇收敛的正确姿势是断言保全 夹具共享合并文件时优先抽取共享 fixture 工厂临时工程、STATE.md/ROADMAP.md 种子、阶段目录构造而不是删除或弱化断言PR #3753 的 9911 断言保全就是验收线接口收紧要用负例锁定phases.archive从公开子命令变为内部转发后立即用调用即Unknown phases subcommand的断言固化行为防止日后被重新暴露回归测试要带 bug 编号#2684/#2787/#3164/#3600直接写进文件头与测试名让每个断言可追溯到具体缺陷也方便后来者理解这个文件为什么存在数量闸门配合文档词条lint-test-file-count管住文件爆炸CONTEXT.md词条管住职责漂移二者缺一不可。对于希望为 gsd-core 新增 Milestone 相关测试的贡献者建议先查看 scripts/lint-test-file-count.cjs 确认当前milestone条目状态再决定是扩充现有文件推荐避免触发FAIL_NOVEL_FILES还是新增文件并显式申请 allowlist 登记。赞分享【免费下载链接】gsd-coreGit. Ship. Done - Core项目地址https://gitcode.com/gh_mirrors/ge/gsd-core点击查看免费下载相关推荐gsd-core 测试治理实践Phase Lifecycle 测试集群 20→4 合并与 lint-test-file-count 身份棘轮机制gsd core 测试治理实践Phase Lifecycle 测试集群 20→4 合并与 lint test file count 身份棘轮机制 本篇以 gsGet 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 仓库中一次典型的测试维护重构上一篇从部署失败到秒启动Hoppscotch环境配置全案解析下一篇解决Vue Pure Admin角色切换难题Pinia Store状态管理终极指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
