SuperAPI AI 工具集

setup-ts-deep-modules

通用与其它

查看项目

更新于 10-16 06:15

技能介绍

用途:把仓库中每个 package 变成“深层模块”——大量行为藏在小接口之后。包的公共面是其根目录的入口文件,子文件夹内容一律私有。本技能安装 dependency-cruiser 并配置规则,使入口文件成为外部进入包的唯一途径,并实际验证规则会报错。

主要能力:配置四条 error 级规则——入口边界(包外代码只能导入该包根目录的入口文件)、包内自由(包自身文件可互相导入)、测试走入口(tests/ 下文件只能导入任意包的入口及其自身 tests/ 夹具,不得深导入任何包子文件夹,包括自己的)、禁止循环依赖。公共面是包的所有根文件而非单一 index.ts,因此一个包可暴露多个小入口(index.ts、client.ts、server.ts),不鼓励 barrel 文件。分层(哪些包可依赖哪些)不在本技能范围,配置中留作注释桩。

使用方式:先探测环境(依据 lock 文件判断包管理器;有 src/ 用 src/packages,否则 packages;检查已有 .dependency-cruiser.* 配置,存在则合并不覆盖)。将 dependency-cruiser 作为 devDependency 安装,把配置复制为根目录 .dependency-cruiser.cjs 并设置 PACKAGES_ROOT,添加 lint:boundaries 脚本(depcruise <packages-root>),并入已有的 typecheck 总检查命令,不改 tsconfig、不加路径别名。创建可复制的 example 包(根入口 index.ts 委托给 lib/impl.ts,tests/example.test.ts 只从入口导入),并可写入包目录 README.md 说明约定,同时在 CLAUDE.md(否则 AGENTS.md)中加一行指向该 README。

验证:先跑 lint:boundaries 应通过;临时在测试中加一个深导入(如从 ../lib/impl 导入),再跑必须报 tests-through-entrypoints 失败;还原后再次通过。没有观察到失败说明规则未接好,需先修复。

限制:包为扁平结构,根下只有一层子包,包内可任意嵌套但包中不能含包;配置用 .cjs 以保证 module.exports 在 type:module 仓库中可用;公开/私有按路径深度判定,约定 lib/ 放实现、tests/ 放测试,任何子文件夹都私有,因此新增文件夹无需改配置。其余平台、收费等信息暂未提供。