type-keeperlisted

# type-keeper 修复存量代码的类型安全问题，使其符合 TS 类型安全规范。核心原则：**让编译器替你抓错误，而不是绕过它**——类型改动以 `tsc --noEmit` 为硬门禁，编译不绿不交付。 ## 参考规范（开始前必须加载） 按顺序读取以下两份文档，作为本次调整的唯一依据： 1. `~/.claude/rules/ts-types.md` —— 强制规则（精简版） 2. `~/.claude/docs/ts-types-guide.md` —— 类型安全详细指南（快速参考卡片、收窄策略、运行时校验、反模式示例） 若第二份缺失，提示用户先运行 `lab deploy docs/ts-code-guide`，不跳过规范直接动手。 ## 确定改动范围 ### 模式一：默认（git diff 变更文件） ```bash git diff --name-only HEAD # 已暂存 + 未暂存的修改 git status --porcelain # 检出 untracked 新增文件 ``` 合并结果，过滤出 `.ts` / `.tsx` / `.d.ts` 文件（含 `.test.ts` / `.spec.ts`），排除 `node_modules/`、构建产物目录。无 TS 文件时告知用户并结束。 ### 模式二：手动指定 | 参数 | 处理方式 | | --- | --- | | 文件路径 | 只处理该文件 | | 目录路径 | 递归处理目录下所有 `.ts` / `.tsx` / `.d.ts`（排除 `node_modules/`、构建产物） | ## 逐文件修复流程 对每个文件对照规则逐项扫描，**按风险分级处理**： ### 低风险（编译期语义，直接做） 1. **`@ts-ignore` → `@ts-expect-error` + FIXME 说明**：若该行报错已消除则直接删除整行指令；替换后若出现"未使用的 ts-expect-error"报错，说明问题已修复，删除指令即可 2. **值导入引用类型 → `import type`**（仅作类型引用时；值与类型混用时不可拆） 3. **type / interface 场景校正**：仅被实现/扩展、对外 API 响应用 `interface`；联合/元组/映射类型用 `type`；React Props 用 `type`。纯类型别名互换编译期等价 4. **泛型补 `extends` 约束**：消除隐式 any；`any` 泛型默认值改为 `unknown` 或具体类型 5. **双重断言 `as unknown as X`**：确有必要的补注释说明原因；可避免的（如先收窄再断言）重构为收窄路径 ### 中风险（需行为等价验证，验证通过才做） 6. **显式 `any` → `unknown` + 收窄**（指南第二章）： - 函数参数/返回值的 `any` → `unknown`，函数体内用 `typeof` 检查 / 类型守卫 / 判别联合收窄到确定类型后再使用 - `any` 返回值不得继续传播（指南禁止行为）——收窄后下游调用点同步核对类型 - **等价验证**：收窄分支必须覆盖原有调用路径的所有输入形态；输入形态无法确定时，保留宽松处理并列待确认清单，不臆造校验逻辑 7. **非空断言 `!` 消除**（指南第五章）：优先用运行时校验或收窄替代；`asserts` 守卫函数适用于"先校验