Skills

Setup Ts Deep Modules

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

Install

npx skills add vinvcn/mattpocock-skills-zh-CN --skill setup-ts-deep-modules -g -a claude-code -y
Category
Engineering
Updated
7d ago
License
MIT
Context cost
Lightabout 1,333 tokens
Runs scripts
No, instructions only

What it does

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

Setup TS Deep Modules

让 repo 中每个 package 成为 deep module:用小 interface 隐藏大量 behaviour。Package 的 public surface 是其 entry points(package root 中的 files),所有 subfolders 都隐藏。这个 skill 会安装 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

Read the whole SKILL.md on GitHub

More in Engineering