migrate-better-result-3

将 better-result 迁移到 3.0

将编译器视为迁移台账：先盘点，再执行机械变更，然后按 API 分支逐一解决剩余错误。

1. 确定迁移范围

阅读仓库说明、包清单、锁文件、TypeScript 配置和验证命令。确认源版本为 better-result 2.x，并在可用时检查已安装的 3.0 声明；包源码优先于凭记忆得出的 API。

在生产代码和测试中搜索：

rg -n --glob '*.{ts,tsx,mts,cts}' \
  'TaggedError|Result\.(serialize|deserialize|hydrate|tryRecover|tryRecoverAsync|tryPromise|partition|gen)|matchError(Partial)?|TaggedErrorClass|Serialized(Result|Ok|Err)'

按照 references/v3-api-diff.md 中审核过的 API 变更，对每个命中项进行分类。还要包含结构上比较包含带标签错误的 Result 的测试。v3 中带标签错误会变为可迭代，即使 Result.gen 的签名没有变化。单独记录生成代码或 vendored 代码中的命中项，不要编辑它们。

完成条件： 按文件和迁移分支记录已安装的源版本、目标 3.0 API、验证命令、每个匹配的生产代码／测试位置，以及每个带标签错误 Result 断言。

2. 应用 TaggedError codemod

列出安全的尾随调用编辑：

node <skill-dir>/scripts/migrate-tagged-error-v3.mjs . --list

检查列出的类继承表达式，然后应用变更：

node <skill-dir>/scripts/migrate-tagged-error-v3.mjs . --write
node <skill-dir>/scripts/migrate-tagged-error-v3.mjs . --check

该转换只会更改 v2 的类继承形式：

class NotFoundError extends TaggedError("NotFoundError")<{ id: string }>() {}
// becomes
class NotFoundError extends TaggedError("NotFoundError")<{ id: string }> {}

它会保留构造函数、属性、格式和调用点。手动将导出的 TaggedErrorClass<Tag, Props> 注解更新为 v3 类类型 TaggedErrorClass<Tag>；将负载类型移到上方所示的子类应用中。

完成条件： 脚本的检查成功退出，并且搜索确认生成代码／vendor 代码之外不再有 v2 尾随工厂调用或双参数 TaggedErrorClass 用法。

3. 替换已移除的序列化辅助工具

如果盘点中包含 Result.serialize、Result.deserialize 或 Result.hydrate，请遵循 references/result-codec-migration.md。所属编解码器负责验证一项应用契约：某方法在两个方向上的实际 Ok 和 Err 负载。在不同编解码器之间共享 schema 片段、工厂和错误策略辅助工具；将不同的成功契约放在各自命名的编解码器中。

考虑控制流的变化：序列化现在可能返回 ResultSerializationError；反序列化会新增 ResultDeserializationError；同步／异步 schema 决定编解码器操作返回 Result 还是 Promise<Result>。当仓库同时拥有生产方和消费方、会一并版本化它们的 schema，并将契约不匹配视为缺陷时，优先使用 serializeUnsafe 和 deserializeUnsafe，以免编写处理编解码器错误的样板代码。serializeUnsafe 会通过 panic 移除 ResultSerializationError；deserializeUnsafe 只移除 ResultDeserializationError，同时保留有效解码出的领域 Err 值。在公开、独立版本化、持久化或其他不可信边界处，保留安全方法。

完成条件： 每个已移除的辅助工具调用都有一个特定于方法或边界、包含四种负载 schema 的编解码器；每个 wire Err 都会重建为预期的领域错误；并且每个编解码器错误或有意采用的 unsafe Panic 策略及异步返回值都在其边界处得到处理。

4. 协调推断变化与可选 API

完成机械式修改和编解码器变更后，执行类型检查。根据 references/v3-api-diff.md 解决诊断，尤其要注意：

• tryRecover 和 tryRecoverAsync 现在会保留原始成功类型，并将其与不同的恢复成功类型合并为联合类型。
• matchError、matchErrorPartial 以及新增的 TaggedError#match 方法，会根据返回值不同的处理器推断联合类型。穷尽匹配会将抛出异常的处理器转换为 Panic；match 是保留名称，因此请重命名 v3 类型检查拒绝的负载或子类冲突。
• matchErrorPartial 可以省略回退处理；此时，未处理的带标签错误会原样返回。
• Result.partition 现在支持异构输入；此外还新增了 all、allAsync 和 partitionAsync。
• Result.tryPromise 新增中止上下文、动态延迟和抖动，同时仍兼容有效的 v2 静态重试配置。
• 带标签错误支持迭代器，可在 Result.gen 中直接使用 yield*。请将对带标签错误进行结构化深度相等断言的做法，替换为分别断言 Result 状态以及错误身份或字段。

除非用户要求采用 3.0 的新功能，否则请保留现有运行时行为。优先使用准确扩展的类型和显式收窄，而非类型断言。

完成标准： 所有由 3.0 签名变更导致的编译器诊断均已解决；每个有意推断出的联合类型都已到达显式处理位置；无关行为保持不变。

5. 升级并验证迁移

将直接依赖和锁文件更新为准确的目标稳定版或预发布版 3.0 版本。诊断迁移行为期间，请固定使用该版本。

先运行一个针对性迁移测试。阅读包脚本和包管理器的参数传递规则，然后确认测试运行器收集的文件输出仅包含目标测试文件。运行代码格式化、lint、类型检查、完整测试套件以及仓库要求的构建命令。重复清单搜索和 codemod 检查。如果仓库级格式化工具报告了既有故障，请保留无关文件不变。

报告版本变更、按分支迁移的文件、编解码器和错误处理决策、采用的可选功能，以及验证证据。

完成标准： 针对性运行仅测试了目标文件；除已记录的生成代码或供应商代码外，不再有已移除的 API 或 v2 TaggedError 语法残留；所有清单中的位置均已处理；仍安装指定版本；并且所有仓库检查均通过，或已明确报告具体失败。