SuperAPI AI 工具集

convert-internal-package-to-typescript

编程与开发

查看项目

更新于 10-16 06:43

技能介绍

用途:把 Ghost 工作区内仅内部使用的旧版包从 JavaScript/CommonJS 转换为仓库既定的 TypeScript 和 ESM 标准路径,且不混淆机械性移动与语义改动,避免破坏文件历史。

主要能力:以 packages/README.md 为包生命周期架构的权威依据,技能只负责转换工作流。流程包括:确认适用范围——完整阅读 packages/README.md,检查该包、其消费者与同类现行包,确认它是纯内部包并可采用文档所述的单构建 TypeScript/ESM 契约;编辑前盘点所有 import、require()、export、运行时资源和路径引用,检查元数据、构建与测试配置、发布/归档包含情况以及动态模块加载,运行既有测试与代表性消费者检查建立基线,找出无法加载标准 ESM 输出的受支持消费者。若包有活跃的独立发布或第三方支持契约,或需要与标准路径冲突的格式,应停止并先建立其支持契约,而非机械套用。已弃用的历史 npm 版本本身不构成阻碍。

使用方式:规划提交前完整阅读 references/history-and-verification.md。用三个聚焦提交保留谱系,每个提交独立有效,移动前验证重命名检测,机械性提交中不做格式化或顺手清理。第一步用 git mv 将源码从 lib 移到 src,仅更新必须随新路径变化的引用,不改模块语法、扩展名或实现,提交主题为 Moved <package> sources from lib to src。第二步用 git mv 将 .js 改名为 .ts,仅添加让源码可解析的最小配置与语法调整,保留行为,推迟类型化与 ESM 转换,主题为 Changed <package> file extensions to TypeScript。第三步按 packages/README.md 应用包契约:共享配置包、最小包内配置、ESM 元数据与导出、标准脚本、单一编译输出(除非已验证的消费者需要例外);仅在全部机械性标准路径检查通过后,将迁移状态替换为 ghostPackage.goldenPath: compliant,主题为 Converted <package> to TypeScript。

生产标准:建模真实的输入、输出与注册表形态,不用 any 填补缺失类型;仅在真正不可信边界使用 unknown 并及时收窄;不得用宽泛断言、非空断言、@ts-ignore 或禁用 lint 来压制编译器;除非 API 变更明确在范围内且所有消费者已更新,否则保留运行时 API;在仓库 NodeNext 配置下,相对 TypeScript 导入使用显式 .ts 扩展名;ESM 无法安全表达旧加载模式时,用显式类型化注册表替代动态 CommonJS 发现;确保 JSON 等运行时资源被输出到 build/ 且可用;避免顶层 await,以便受支持的 CommonJS 消费者使用 Node 的 require(esm) 互操作;不得为通过转换而弱化共享 TypeScript、ESLint 或 Vitest 规则。

验证:运行 packages/README.md 要求的构建、测试和 lint 命令;用真实 import 或 require() 路径实际操作代表性消费者;在两者都被使用时测试原始源码解析与编译输出;当 exports、运行时资源或归档包含变化时检查打包后的包或 Ghost 发布组件;工作区构建图变化时运行仓库构建;对每个机械性提交运行 git diff --summary,对代表性文件运行 git log --follow 确认谱系仍可读。当代提交独立有效且顺序有意时,现代化 PR 可用 rebase-merge 合并;这不改变此前子树历史导入对合并提交的要求。

适用场景:Ghost 内部包的 TypeScript/ESM 现代化改造。

限制:不适合有活跃独立发布或第三方支持契约、或需要与标准路径冲突格式的包;具体命令、配置细节与文件内容暂未在资料中提供。