【免费下载链接】gsd-coreGit. Ship. Done - Core项目地址https://gitcode.com/gh_mirrors/ge/gsd-core点击查看免费下载本篇围绕 migration-finalize-ts.md 这条变更记录展开它是 gsd-coreGit. Ship. Done - Core中 ADR-457「bin/libTypeScript 迁移」的最终收口动作。读完你能掌握这次收尾的三项核心变更——退役tsconfig.lint.json的checkJs临时方案、把 tsc 生成的config-types.cjs降级为 gitignore 构建产物、以及package-identity.cjs如何以 value-baked 例外长期保留——并能结合tsconfig.build.json与package.json的构建脚本链理解「TS 源码为唯一真源、.cjs为发布期产物」这一模型在仓库中的完整落地方式。一、这条 Changeset 记录了什么migration-finalize-ts.md 的 frontmatter 声明这是一条type: Changed的变更记录关联 PR #537。正文一句话概括了三个动作退役tsconfig.lint.json的checkJs临时方案——前提是每一个手写的bin/lib/*.cjs都已收敛collapsed为src/*.cts唯一真源把 tsc 生成的config-types.cjs视为 gitignore 的构建产物——与其余 tsc 输出同等对待package-identity.cjs保持 value-baked 状态——其类型契约通过src/package-identity.d.cts显式声明。变更记录尾部附有一条docs-exempt注释说明了免写文档的理由内部 ADR-457 的 build-at-publish 迁移收尾移除一个未使用的 stopgap tsconfig并将一个生成产物加入 gitignore无用户侧可见变更。这条注释本身就点出了收尾动作的性质纯内部工程动作不改变任何用户可感知的行为因此不触发文档强制要求。二、背景ADR-457 为什么选择「发布时构建」要理解这次收尾先看 ADR-457。该 ADR 解决的核心问题是bin/lib手写运行时代码的类型安全长期是「二等公民」——类型错误只能以 lint 发现的形式如果有的话出现而不是编译错误同时 lint 配置里存在一个并未真正接线的tsconfig.lint.jsonallowJscheckJs注释宣称「Type-aware via parserOptions.project」实际 ESLint 配置中并没有parser和parserOptions.project文件是在无类型信息的状态下被 lint 的。ADR-457 评估了三种「TS 源码与.cjs产物并存」的模型模型做法ADR 结论1. 双入库.ts源码与.cjs输出都提交进 git永久引入「两份副本必须一致」的不变量需要 parity 测试、双提交、drift gate而运行时收益为零。被否决2. 发布时构建build-at-publish.cjs是 gitignore 的构建产物由 tsc 从 TSsrc/树生成npm 发布构建输出采纳。无 drift 不变量、无 parity 测试、无双提交代价是本地开发和 CI 必须在运行前构建3. 安装时构建用户安装时编译被否决跨 Node 版本/平台脆弱且拖慢每次安装ADR 同时明确了一个关键区分value baking值烘焙与 transpilation转译是两种完全不同的「生成」技术。package-identity.cjs必须烘焙因为安装后的目录树里没有带.name的package.json相关 bug #378运行时根本读不到这些坐标值而bin/lib逻辑的 TS→CJS 转译删除后「什么都不回来」其全部价值在于编写期与 CI 的类型检查。因此 ADR 的决策第 5 条规定只有在最后一个手写.cjs消失时才退役tsconfig.lint.json——这正是本次 Changeset 执行的时机。三、收尾动作的仓库证据3.1tsconfig.lint.json已退役checkJs不再存在在当前仓库中find全库 tsconfig 只剩两个文件tsconfig.json 与 tsconfig.build.jsontsconfig.lint.json已经不存在。两者的分工被tsconfig.json顶部的注释写得很清楚{ //: Default editor/CI typecheck config. The emitting publish build stays in tsconfig.build.json., extends: ./tsconfig.build.json, compilerOptions: { noEmit: true }, include: [src/**/*.cts] }也就是说编辑器和 CI 的类型检查直接复用发布构建配置并叠加noEmit不再需要任何针对.cjs的allowJs/checkJs路径——因为已经没有手写.cjs需要检查了。类型感知 lint 也完成了从「假接线」到「真接线」的切换。eslint.config.mjs 中对src/**/*.cts的 lint 块现在使用tseslint.configs.recommendedTypeChecked并通过parserOptions.project: ./tsconfig.build.json把真实的 TS 工程喂给规则集。全库搜索已无任何checkJs或tsconfig.lint引用临时方案被彻底拆除。3.2 tsc 生成的.cjs一律是 gitignore 的构建产物tsconfig.build.json 是整个模型的工程载体其头部注释直接标注了出处{ //: ADR-457 build-at-publish: compile TS runtime sources in src/ to gitignored .cjs artifacts under gsd-core/bin/lib/. Source uses the .cts extension so tsc emits .cjs natively. As modules migrate, they move from hand-written bin/lib/*.cjs into src/*.cts here., compilerOptions: { rootDir: src, outDir: gsd-core/bin/lib, module: nodenext, moduleResolution: nodenext, target: ES2022, lib: [ES2022, ES2025.RegExp], types: [node], strict: true, esModuleInterop: true, noEmitOnError: true, incremental: true, tsBuildInfoFile: tsconfig.build.tsbuildinfo }, include: [src/**/*.cts] }几个关键设计点src/**/*.cts→gsd-core/bin/lib/*.cjs源码用.cts扩展名tsc 在nodenext解析模式下原生输出.cjs与require()消费方仓库没有type: module完全兼容strict: truenoEmitOnError: true编译错误会直接阻断产物输出保证进入bin/lib的.cjs必然来自一次通过类型检查的构建incrementaltsBuildInfoFile迁移期大量模块反复构建增量编译控制反馈延迟。config-types.cjs正是这种产物的一个实例其真源是 src/config-types.cts而.gitignore第 139 行显式列出/gsd-core/bin/lib/config-types.cjs。.gitignore中对这类产物甚至留有维护约定例如针对其他模块的注释# #4145: emitted artifact of src/pristine-baseline.cts — never edited.即「这是某个.cts的输出产物永远不要手改」。本次 Changeset 把config-types.cjs归入同一类统一了「生成产物不入库」的处理口径。3.3package-identity.cjs唯一长期 value-baked 的例外ADR-457 决策第 2 条要求「value baking 单独保留」本次收尾在类型层面完成了配套src/package-identity.d.cts 为这个不迁移的模块提供类型声明使严格模式下的src/*.cts源码能在nodenext模块解析下合法地导入它/** * Type declaration for package-identity.cjs — permanently hand-written, * not migrated per ADR-457. This .d.cts file allows strict TypeScript * sources (src/*.cts) to import it under nodenext moduleResolution. * ... */ export declare const packageName: string; export declare const PACKAGE_NAME: string; export declare const binName: string; export declare const repoSlug: string; export declare const repoUrl: string; export declare const changelogRawUrl: string; export declare function manualInstallCommand(opts?: { scope?: string; runtime?: string }): string;注意措辞是「permanently hand-written」——这与 ADR 的「deletion test」论证一致gsd-core/bin/lib/package-identity.cjs 顶部标注// generated by scripts/generate-package-identity.cjs from package.json — DO NOT EDIT.它由 scripts/generate-package-identity.cjs 从package.json读取并烘焙字面量坐标。之所以必须烘焙而非运行时读取是因为安装树中不存在带.name的真实package.jsonbug #378 的根因require(package.json).name在可解析处返回undefined、在不可解析处抛MODULE_NOT_FOUND。围绕这个唯一例外的防腐化机制有三层均可在仓库中验证parity 测试tests/package-identity.test.cjs 从package.json重新生成并断言提交的产物未过期drift lintscripts/lint-package-identity-drift.cjs 以check:identity-drift脚本暴露且该文件把「seam 文件、生成器、lint 脚本」三者绑定在一起做一致性校验生成检查lint:generated-sync链中包含node scripts/generate-package-identity.cjs --check保证 CI 能发现烘焙产物漂移。四、收尾后的构建与验证链路收尾之后「编辑src/*.cts→ 运行bin/lib/*.cjs」之间始终隔着一次构建这条链在 package.json 中被完整接线脚本命令作用build:libtsc -p tsconfig.build.json从src/**/*.cts编译出 gitignored 的gsd-core/bin/lib/*.cjsprepare/prepacknpm run build:lib本地npm installlink 场景与打 npm 包前自动构建覆盖 ADR「未构建 checkout 中消费者」的 open questionprepublishOnlynpm run build:lib npm run build:hooks发布前构建 TS 产物与 hooks 产物正是 ADR-457 选定的 build-at-publish 钩子pretestnpm run build:lib npm run lint:skill-deps落实 ADR「For testing」一节的结论测试依赖bin/lib/*.cjs必须先构建build串联generate:identity、build:lib、各gen:*与build:hooks完整构建入口先烘焙 identity再 tsc再生成其余注册表产物其中prepare与pretest两个钩子正是 ADR 后果分析中「成本」一侧的直接实现——本地开发与 CI 都在运行前构建从而彻底消灭了模型 1 需要维护的「双副本一致」问题产物从不入库就不存在漂移。五、收尾后的bin/lib现状与验证方式从当前仓库状态看gsd-core/bin/lib/下只剩 9 个.cjs文件capability-command-router.cjs、capability-registry.cjs、capability-validator.cjs、exit-code-registry.cjs、legacy-cleanup.cjs、loop-host-contract.cjs、package-identity.cjs、profile-pipeline-command-router.cjs、stale-bake-guard.cjs而src/目录已有约 210 个.cts真源文件。这些残留的.cjs分别属于两类非 tsc 场景注册表/契约类生成器产物如capability-registry.cjs由gen:capability-registry生成甚至在version脚本中被显式git add、exit-code-registry.cjsgen-exit-code-registry、loop-host-contract.cjsgen:loop-host-contract——它们由专用 Node 脚本生成而非 tsc 转译.gitignore中也以「emitted artifact, never edited」类注释标注value-baked 例外package-identity.cjs按前述 ADR-457 决策永久保留。这意味着 Changeset 中「每一个手写bin/lib/*.cjs已收敛为src/*.cts」的表述与仓库现状吻合需要checkJs去检查的手写 JS 面已经归零剩下的.cjs全部有各自的生成器或例外声明。验证这次收尾是否到位只需在仓库中执行npm run build:lib # tsc -p tsconfig.build.json确认 src 全量类型通过并产出 bin/lib npm run pretest # build:lib lint:skill-deps确认测试链路依赖构建 npm run lint # eslint .确认类型感知规则走 tsconfig.build.json无 checkJs 残留build:lib的noEmitOnError保证任何类型错误都会直接失败退出lint:generated-sync则持续守护烘焙产物与生成注册表的同步。六、小结这条看起来只有几句话的 Changeset实际上是一座「迁移完成度」的验收碑拆除tsconfig.lint.json与checkJs在最后一个手写.cjs消失的时点被移除符合 ADR-457 决策第 5 条预设的退役条件类型感知 lint 改接真实的tsconfig.build.json工程。归类tsc 生成的.cjs如config-types.cjs统一成为 gitignore 的构建产物「源码入库、产物不入库」的口径在.gitignore中逐一落实。保留package-identity.cjs作为 value-baked 的深 seam 被显式豁免迁移并通过src/package-identity.d.cts声明、parity 测试与 drift lint 三重机制锁住其一致性。其方法论价值在于当一个「生成管线」只服务于编写期收益类型检查而非运行时收益时把产物变成构建期垃圾而非入库资产可以整片消灭 drift 治理机制——这正是 ADR-457 用「build-at-publish」换取「无 parity 测试、无双提交」的核心取舍而本次收尾让它从纸面决策变成了仓库里可复现的事实。赞分享【免费下载链接】gsd-coreGit. Ship. Done - Core项目地址https://gitcode.com/gh_mirrors/ge/gsd-core点击查看免费下载相关推荐gsd-core ADR-457 TypeScript 源码迁移实录10 个运行时模块从手写 CommonJS 到 tsc 构建产物gsd core ADR 457 TypeScript 源码迁移实录10 个运行时模块从手写 CommonJS 到 tsc 构建产物 本篇以归档 changegsd-core 的 ADR-457 构建即发布实践commands 与 state 枢纽模块的 TypeScript 迁移Batch 14gsd core 的 ADR 457 构建即发布实践commands 与 state 枢纽模块的 TypeScript 迁移Batch 14 本文以 gsgsd-core ADR-457 构建期迁移实战第 6 批五个运行时模块如何从手写 CommonJS 收敛为 TypeScript 单一真源gsd core ADR 457 构建期迁移实战第 6 批五个运行时模块如何从手写 CommonJS 收敛为 TypeScript 单一真源 本文以归档变更集上一篇Huihui-GLM-5.2-abliterated-GGUF常见问题解答从下载到运行的10个实用技巧下一篇最完整的React Native Firebase数据分析实战从埋点到驱动产品决策的全流程指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
