用途:把 TypeScript 仓库中的每个 package 变成深度模块——小接口背后隐藏大量行为。package 的公开表面是其根目录下的入口点文件,子文件夹中的内容全部私有。
主要能力:安装 dependency-cruiser 并写入四条 error 级规则——入口点边界(package 外部只能导入其根文件)、包内自由(package 内部文件可互相导入)、测试通过入口点(tests/ 只能导入入口点与自身 fixtures,不能深路径导入)、无循环依赖。规则基于路径深度且与扩展名无关,新增子文件夹无需改配置。
使用方式:先探测包管理器(pnpm-lock.yaml→pnpm、yarn.lock→yarn、bun.lockb→bun,否则 npm)与 packages 根目录(有 src/ 用 src/packages,否则 packages),检查是否已有 .dependency-cruiser.* 配置(有则合并而非覆盖)。将 dependency-cruiser 装为 devDependency,把配置复制为根目录 .dependency-cruiser.cjs 并设置 PACKAGES_ROOT。新增 lint:boundaries 脚本(depcruise <packages-root> 或 depcruise src),并入已有的总检查命令(如 check/ci/validate),不改 tsconfig、不加路径别名。创建可提交的示例 package 作为模板,并验证规则:干净时通过,临时加入深路径导入须以 tests-through-entrypoints 报错,撤销后再次通过。最后在 packages 目录写 README.md 说明结构与运行方式,并在 CLAUDE.md/AGENTS.md 加一行指针。
适用场景:需要强制 package 边界、避免深路径导入与桶文件的 TypeScript 仓库。
限制:分层(哪些 package 可依赖哪些)仅以注释桩留在配置中,需自行填充;package 为扁平结构,内部不可再放 package;配置须用 .cjs 以兼容 "type": "module";不要拆散 $1 反向引用规则。