SuperAPI AI 工具集

setup-ts-deep-modules

通用与其它

查看项目

更新于 10-16 01:25

技能介绍

用途:在 TypeScript 仓库中把每个包改造成深模块——大量行为藏在小型接口之后。包的公开面是其根文件(入口点),子文件夹内容对外隐藏。该技能安装 dependency-cruiser 并写入规则,使入口点成为唯一进入方式,并验证规则确实生效。

主要能力:强制四条 error 级规则——入口点边界(包外代码只能导入包的根文件,不能导入子文件夹内容);包内自由(包自身文件可互相导入);测试走入口点(tests/ 下文件可导入任意包的入口点及自身 fixtures,但不能导入任何包的子文件夹内部);禁止循环依赖。公开面是包的所有根文件,而非单一 index.ts,因此一个包可暴露多个小入口点(index.ts、client.ts、server.ts),不鼓励 barrel 文件。分层(哪些包可依赖哪些包)属于另一关注点,配置中留作注释占位。

使用方式:先检测环境(依据 pnpm-lock.yaml/yarn.lock/bun.lockb 判断包管理器;有 src/ 则用 src/packages,否则 packages;检查已有 .dependency-cruiser.* 配置,存在则合并而非覆盖)。将 dependency-cruiser 安装为 devDependency。把 dependency-cruiser.config.cjs 复制为仓库根目录的 .dependency-cruiser.cjs,设置 PACKAGES_ROOT。添加 lint:boundaries 脚本:depcruise <packages-root>(或 depcruise src),并并入已有的 typecheck 总检查命令;不改 tsconfig、不加路径别名。创建可复制的示例包 <packages-root>/example/(index.ts 入口、lib/impl.ts 内部实现、tests/example.test.ts 仅导入 ../index)。验证规则:先跑 lint:boundaries 应通过;临时在测试中加入深层导入(如 import { thing } from "../lib/impl")应报 tests-through-entrypoints 失败;还原后应再次通过。最后在包目录写 README.md 说明约定并反对 barrel,并在 CLAUDE.md(否则 AGENTS.md)加一行指向它。

适用场景:需要为 TypeScript 多包仓库建立清晰模块边界、防止深层导入与循环依赖的团队。

限制:公开与私有由路径深度决定,任何子文件夹都视为私有;包为扁平结构,包内可任意嵌套但不能包含另一个包;配置须用 .cjs 以兼容 "type": "module" 仓库;配置中的 $1 反向引用不可拆成逐包规则。具体收费、价格与平台信息暂未提供。