migrate-to-shoehorn

迁移到 Shoehorn

将测试文件中的 as 类型断言迁移到 @total-typescript/shoehorn。用户提到 shoehorn、想在测试中替换 as，或需要部分测试数据时使用。

此技能从 mattpocock/skills（MIT）导入，上游通过模型调用。

何时使用此技能

• 将测试文件中的 as 类型断言迁移到 @total-typescript/shoehorn。
• 用户提到 shoehorn、想在测试中替换 as，或需要部分测试数据时使用。

说明

迁移到 Shoehorn

为什么使用 shoehorn？

shoehorn 让你可以在测试中传入部分数据，同时确保 TypeScript 检查通过。它使用类型安全的替代方式取代 as 断言。

仅用于测试代码。 切勿在生产代码中使用 shoehorn。

测试中使用 as 的问题：

• 已经受过不使用它的训练
• 必须手动指定目标类型
• 对于有意传入错误数据的情况，需要双重断言（as unknown as Type）

安装

npm i @total-typescript/shoehorn

迁移模式

只需要少数属性的大型对象

之前：

type Request = {
  body: { id: string };
  headers: Record<string, string>;
  cookies: Record<string, string>;
  // ...20 more properties
};

it("gets user by id", () => {
  // Only care about body.id but must fake entire Request
  getUser({
    body: { id: "123" },
    headers: {},
    cookies: {},
    // ...fake all 20 properties
  });
});

之后：

import { fromPartial } from "@total-typescript/shoehorn";

it("gets user by id", () => {
  getUser(
    fromPartial({
      body: { id: "123" },
    }),
  );
});

as Type → fromPartial()

之前：

getUser({ body: { id: "123" } } as Request);

之后：

import { fromPartial } from "@total-typescript/shoehorn";

getUser(fromPartial({ body: { id: "123" } }));

as unknown as Type → fromAny()

之前：

getUser({ body: { id: 123 } } as unknown as Request); // wrong type on purpose

之后：

import { fromAny } from "@total-typescript/shoehorn";

getUser(fromAny({ body: { id: 123 } }));

何时使用各函数

函数	使用场景
fromPartial()	传入仍能通过类型检查的部分数据
fromAny()	传入有意设置的错误数据（保留自动补全）
fromExact()	强制要求完整对象（之后可替换为 fromPartial）

工作流

1. 收集需求 - 询问用户：

   • 哪些测试文件中的 as 断言导致了问题？
   • 是否在处理只需关注部分属性的大型对象？
   • 是否需要传入有意设置的错误数据来测试错误？

2. 安装并迁移：

   • 安装：npm i @total-typescript/shoehorn
   • 查找包含 as 断言的测试文件：grep -r " as [A-Z]" --include="*.test.ts" --include="*.spec.ts"
   • 将 as Type 替换为 fromPartial()
   • 将 as unknown as Type 替换为 fromAny()
   • 从 @total-typescript/shoehorn 添加导入
   • 运行类型检查进行验证

示例

• 先将此技能用于一个范围较小的任务，确认输出符合上述形式，再扩展到完整任务。
• 如果某个步骤需要了解仓库或环境中的信息，请先查找，而不是询问用户。

最佳实践

• 保持上游流程不变；如有偏差，请明确记录，不要擅自变更。
• 在此技能标记为由用户决定的每个决策点，暂停并将控制权交还给用户。
• 优先进行小幅、可逆的更改，并明确说明假设，不要将其隐藏起来。

参考

• 上游技能：mattpocock/skills skills/misc/migrate-to-shoehorn/SKILL.md（提交 3cca18b，MIT）
• 项目规范：.agent-skills/skill-standardization/SKILL.md
• 验证脚本：.agent-skills/skill-standardization/scripts/validate_skill.sh