# Setup Ts Deep Modules

在 TypeScript repo 中接入 dependency-cruiser，让每个 package 成为 deep module：implementation 隐藏在...

- Repository: https://github.com/vinvcn/mattpocock-skills-zh-CN (5461 stars)
- Category: Engineering
- License: MIT
- Last updated: 2026-10-28
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add vinvcn/mattpocock-skills-zh-CN --skill setup-ts-deep-modules -g -a claude-code -y`
Codex: `npx skills add vinvcn/mattpocock-skills-zh-CN --skill setup-ts-deep-modules -g -a codex -y`
Cursor: `npx skills add vinvcn/mattpocock-skills-zh-CN --skill setup-ts-deep-modules -g -a cursor -y`
Gemini CLI: `npx skills add vinvcn/mattpocock-skills-zh-CN --skill setup-ts-deep-modules -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add vinvcn/mattpocock-skills-zh-CN`

## Description

在 TypeScript repo 中接入 dependency-cruiser，让每个 package 成为 deep module：implementation 隐藏在 subfolders 中，只能通过 entry-point files 访问。User-invoked。

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Setup TS Deep Modules

让 repo 中每个 package 成为 **deep module**：用小 interface 隐藏大量 behaviour。Package 的 public surface 是其 **entry points**（package root 中的 files），所有 subfolders 都隐藏。这个 skill 会安装 [dependency-cruiser](https://github.com/sverweij/dependency-cruiser)，加入强制只能通过 entry points 访问的 rules，并证明这些 rules 确实会拦截违规。

Vocabulary（deep module、interface、seam、depth）来自调用 Skill 工具并指定 `codebase-design`；整个过程都使用它的语言。

## The shape this enforces

```
src/packages/
  <name>/
    index.ts        ← an entry point (public). Import this from outside.
    client.ts       ← another entry point. Packages may expose SEVERAL.
    lib/            ← implementation: hidden from outside, free to import each other.
    tests/          ← co-located tests + fixtures (a subfolder, so private).
```

Public surface 是 package 的 **root files**，并非指定的单个 `index.ts`。按 convention，implementation 放在 `lib/`，tests 放在 `tests/`，使所有 packages 采用相同的 two-folder shape。Rule 本身是通用的：*任何* subfolder 中的*任何*内容都是 private，因此永远无需为了新增 folder 扩展 config。

四条 rules，全部为 `error`：

1. **Entry-point boundary**, package 外的 code（app code 或其他 package）只能 import 该 package 的 entry points（root files），不能 import subfolder 中的任何内容。
2. **Intra-package freedom**, package 自己的 files 可以自由互相 import。
3. **Tests through the entry points**, `<pkg>/tests/` 下的 files 可以 import 任意 package 的 entry points 和自己的 `tests/` fixtures，但不能 import 任何 package 的 subfolder internals（包括自己的）。允许跨 package integration tests，不允许 deep imports。
4. **No cycles**, 不允许 dependency cycles。

**Entry points, not a barrel.** Public surface 是每个 root file，因此 package 可以提供多个小 entry points（`index.ts`、`client.ts`、`server.ts`），不必把一切汇入巨大的 `index.ts`。不鼓励 re-export 整个 subtree 的 barrel files；entry points 要小，implementation 隐藏在 subfolders。

Layering（哪些 packages 可以依赖哪些）是另一个 concern，在 config 中保留 commented stub，由当前 repo 填写。

## Steps

### 1. Detect the environment

The rest: https://github.com/vinvcn/mattpocock-skills-zh-CN/blob/HEAD/skills/in-progress/setup-ts-deep-modules/SKILL.md