Setup TS Deep Modules

设置 TS 深度模块

让此仓库中的每个 package 都成为一个深度模块：小接口背后隐藏大量行为。一个 package 的公开表面是其入口点：package 根目录下的文件：而其子文件夹中的所有内容都是隐藏的。本技能安装 dependency-cruiser 与让入口点成为唯一通路的规则，然后验证规则确实起作用。

关于相关词汇（深度模块、接口、接缝、depth），请调用 Skill 工具并传入 "codebase-design"：在后续内容中使用它的术语。

它强制形成的结构

src/packages/
  <name>/
    index.ts        ← 一个入口点（公开）。外部从这里导入。
    client.ts       ← 另一个入口点。Package 可以暴露多个。
    lib/            ← 实现：对外部隐藏，内部可以自由相互导入。
    tests/          ← 与实现并列的测试与 fixtures（一个子文件夹，所以是私有的）。

公开表面是 package 的根文件，而不是某个指定的 index.ts。按惯例实现放在 lib/，测试放在 tests/，让每个 package 都拥有相同的"两个子文件夹"结构。不过规则本身是普适的：任何子文件夹里的任何文件都是私有的，所以你永远不需要为了新增文件夹而扩展配置。

四条规则，全部为 error：

1. 入口点边界：package 外部的代码（应用代码或其他 package）只能导入该 package 的入口点（即其根文件），绝不能导入其子文件夹中的任何内容。
2. 包内自由：package 自己的文件可以自由地相互导入。
3. 测试通过入口点：<pkg>/tests/ 下的文件可以导入任何 package 的入口点以及它自己的 tests/ fixtures，但不能导入任何 package 的子文件夹内部内容（包括它自己的）。跨 package 的集成测试可以，但深路径导入不行。
4. 无循环依赖：不允许存在依赖循环。

入口点，而非桶文件（barrel）。 由于公开表面是每个根文件，所以一个 package 可以暴露多个小型入口点（index.ts、client.ts、server.ts），而不是把一切都集中塞进一个巨大的 index.ts。不要用桶文件来再导出整棵子树；保持入口点小而精，把实现藏在子文件夹里。

分层（哪些 package 可以依赖哪些 package）是另一回事，本仓库把它以注释桩（commented stub）的形式留在配置里供填充。

流程

1. 探测环境

• 包管理器：pnpm-lock.yaml → pnpm；yarn.lock → yarn；bun.lockb → bun；否则 npm。后续所有命令都使用该包管理器（pnpm / yarn / npm run / bunx）。
• packages 根目录：如果存在 src/ 则使用 src/packages，否则使用 packages。如果仓库已经有明显不同的约定，请与用户确认。
• 已有配置：检查是否存在 .dependency-cruiser.* 文件。若已有，不要覆盖：把四条规则与 options 合并进去，并告知用户你新增了什么。

**完成条件：**包管理器、packages 根目录、是否有已有配置：这三项都已确认。

2. 安装 dependency-cruiser

使用上面探测到的包管理器，把 dependency-cruiser 安装为 devDependency。

完成条件：dependency-cruiser 已出现在 devDependencies 中。

3. 写入配置

将 dependency-cruiser.config.cjs 复制到仓库根目录，命名为 .dependency-cruiser.cjs。把 PACKAGES_ROOT 设置为步骤 1 探测到的根目录。规则是基于路径深度且与扩展名无关的，所以不需要做其他适配。

完成条件：.dependency-cruiser.cjs 存在，PACKAGES_ROOT 正确，且四条禁用规则都已写入。

4. 接入检查流程

• 新增 lint:boundaries 脚本：depcruise <packages-root>（或 depcruise src）。
• 将其并入仓库的"总检查"命令：那个已经运行 typecheck 的命令（例如 check / ci / validate 脚本）。不要改动 tsconfig，也不要新增路径别名。
• 如果没有总检查脚本，就新增 lint:boundaries 并告诉用户在 CI 中加入它。

完成条件：lint:boundaries 已存在，并作为与 typecheck 同一条命令的一部分运行。

5. 搭建示例 package

创建一个会被提交的 <packages-root>/example/，作为"复制即用"的模板：

• index.ts 是一个入口点。导出一个委托给内部文件的函数（这样 package 看起来就是深的，而不是一个简单的透传）。
• lib/impl.ts：一个位于子文件夹中的内部文件，被 index.ts 导入，从外部无法触达。
• tests/example.test.ts 只导入 ../index（一个入口点），并针对公开函数进行断言。

告诉用户这是一个可以复制或删除的起始模板。

**完成条件：**示例 package 已存在，通过根入口点暴露行为，并把 impl 隐藏在子文件夹中。

6. 验证规则确实起作用

这是整项技能的完成判定标准：一个在违反时不会失败的配置毫无价值。

1. 运行 lint:boundaries。在干净的示例上必须通过。
2. 临时向 tests/example.test.ts 中添加一个深路径导入（例如 import { thing } from "../lib/impl"）。再次运行 lint:boundaries；它必须以 tests-through-entrypoints 报错失败。
3. 撤销那个深路径导入。再运行一次，必须通过。

**完成条件：**你已经观察到了"通过 → 在深路径导入时失败 → 再撤销后又通过"这一完整流程。如果步骤 2 没有失败，说明规则没有正确接入，请修复后再结束。

7. 把约定写下来

在 packages 文件夹中写一份 README.md（即 <packages-root>/README.md，放在它所管辖的 packages 旁边），内容覆盖：src/packages/<name>/ 的目录结构（根目录的入口点、lib/ 放实现、tests/ 放测试）、"只能通过 package 的入口点（即根文件）导入"以及如何运行 lint:boundaries。显式劝阻桶文件：暴露多个小型入口点，而不是通过一个 index 再导出一整棵子树。控制在"复制即用片段 + 四条规则各一段"的范围。

然后在仓库的 agent-instructions 文件（优先 CLAUDE.md，否则 AGENTS.md，若两者都不存在则新建 AGENTS.md）中添加一个上下文指针指向它。一行就够，例如 Packages are deep modules: see [src/packages/README.md](./src/packages/README.md) before adding or importing one. 这正是让 agent 在踩到边界规则之前先发现它的关键。

完成条件：<packages-root>/README.md 存在且劝阻桶文件，且仓库的 CLAUDE.md/AGENTS.md 中有指向它的链接。

备注

• 配置中的 $1 反向引用（dependency-cruiser 的 group matching）正是让一个 package 可以触达自己的内部、而外部却不能触达的关键。不要把它们拆成多个独立的 per-package 规则。
• 公开 vs 私有由深度决定：package 的根文件是入口点；任何子文件夹里的内容都是私有的。约定俗成的子文件夹是 lib/（实现）和 tests/，但规则并未硬编码它们：任何子文件夹都是私有的，所以新增文件夹永远不需要改配置。新增入口点只是新增一个根文件（不需要桶文件）。
• Package 是扁平的：根目录下只有一层直接的子目录。Package 的内部可以嵌套任意深度；但 package 内不能再放另一个 package。
• 使用 .cjs（而不是 .js），这样即使在 "type": "module" 的仓库里，配置中的 module.exports 也能正常工作。