ts-module-boundaries
Make each package in a TypeScript repo reachable only through its entry-point files, enforced by a dependency-linter check in CI and proven to bite with a deliberate bad import. Use when the decider asks for enforced module boundaries or deep modules, when a codebase-review bound
Install
npx skills add https://github.com/timharris707/skills/tree/main/skills/in-progress/ts-module-boundaries
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install timharris707-skills@llmmart
git clone https://github.com/timharris707/skills.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole timharris707/skills collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
TypeScript module boundaries
A package is a module, and its entry points (the one or few files other code may import from it) are where its interface lives. Everything behind them is implementation. This skill installs the check that makes that true: a dependency linter (a tool that reads every import and fails the build on one that breaks a rule), run in CI, that fails any import reaching past an entry point, then proves the check fails when it should.
Terms follow the design vocabulary: module, interface, seam, depth. The entry points are the package's seam, and the check keeps imports from crossing anywhere else. It is the enforcement half of codebase-review's boundaries-vs-reality lens: the lens finds where change bypasses the declared layout, and this skill makes the declared layout hold. Layering (which package may depend on which) is a different concern and stays out.
Read the team-workflow binding doc first: its verify commands, memory home, and agent-context docs are what this skill writes to. A repo with no binding doc runs on its own scripts, and the hand-back names the unbound slots.
The rules the check enforces
All error:
- From outside. Code outside every package (apps, scripts, root tests) imports a package only through its entry points.
- Across packages. A package's own files import each other freely and reach another package only through its entry points.
- Tests (opt-in). For repos where each package keeps its tests in a private
tests/folder: tests import any package's entry points and their owntests/fixtures, never any package's internals (not even their own), and nothing outside atests/folder imports one. The interface is the test surface. - No runtime cycles. Type-only imports do not count.
- Every import resolves. An import the linter cannot resolve fails the check. Left unresolved it matches no rule above and passes, so a gap in resolution would let a deep import through.
Entry points come in three shapes, set by the config's ENTRY_POINTS constant: one file per package (src/index.ts, for a workspace package whose main points there; an exports "." entry, when present, wins over main), several named files, or every file at the package root with the code in subfolders. A non-code export, such as a stylesheet, is listed by name with its extension (styles\\.css). Prefer several small entry points to a barrel that re-exports a whole subtree: a barrel makes the interface nearly as wide as the implementation, which is what shallow means.
Steps
1. Read the ground
Detect from the repo, with file evidence for each:
- Package manager: the lockfile.
- Packages and their entry points: workspace globs (
workspacesinpackage.json,pnpm-workspace.yaml), each package'smainandexports(a non-code export such as a stylesheet is an entry point too); failing that, folders shaped<root>/<name>/index.ts. - Importer directories: every directory holding code that imports a package (apps, scripts, root tests). This is the check's scope.
- Alias tsconfig: the tsconfig that holds the
pathsaliases. - Existing boundary tooling: a dependency-cruiser config,
eslint-plugin-boundariesorno-restricted-importsrules, Fallowboundaries, Nx, Sheriff, Steiger, alint:boundariesscript. Put it to the decider: extend it, or replace it with this skill's config. One rule never runs under two linters. - TypeScript version: dependency-cruiser supports a bounded range, and a version outside it skips every
.tsfile and still exits 0 (the linter's own warning names the range). Outside the range, stop and report to the decider; do not downgrade TypeScript or swap tools unasked. Step 3 installs a guard so a later bump fails the check instead of passing it.
Done when: each item is written down with its evidence, the existing-tooling question is answered (or the repo has none), and the TypeScript version is inside the linter's range.
2. Settle the shape with the decider
Brief the decider in plain words, with a recommendation and the step 1 evidence for each:
- Entry-point shape: one file per package, several named files, or every root file.
- Tests: beside the code they test (the opt-in rule stays off), or in a private
tests/folder per package (it goes on).
A repo with no package yet has nothing to enforce. The decider names the areas that become packages, with codebase-review's shallow-modules lens as the source of candidates, or approves the scaffold in step 6.
Done when: the shape and tests answers are the decider's, recorded as a decision record with its load-bearing reason where the binding names a domain-memory home, otherwise in the PR description.
3. Install and configure
- Install
dependency-cruiseras a devDependency with the detected package manager. - Copy references/dependency-cruiser.config.cjs to
.dependency-cruiser.cjs(.cjsso it loads in a"type": "module"repo). Set its three constants to the step 2 answers andtsConfig.fileNameto the alias tsconfig. - Copy references/check-typescript-support.mjs to
scripts/check-typescript-support.mjs(or the repo's equivalent scripts folder). It exits 1 when dependency-cruiser cannot read TypeScript, which step 4 puts in front of every run. - The config resolves a package-name import through the package's
exportsmap, so a second entry such as@pkg/billing/testingresolves. This changes how every package-name import resolves, so the first run in step 5 may surface failures the repo never saw: an import that never resolved, or a package subpath that now resolves and meets the boundary rules for the first time. - Merge into an existing
.dependency-cruiser.*and report what was added; the existing file is never overwritten. - Leave
tsconfigand the repo's path aliases as they are.
Done when: .dependency-cruiser.cjs exists with constants matching the decided shape, depcruise runs, and the guard exits 0.
4. Wire it into CI
- Add a
lint:boundariesscript:node scripts/check-typescript-support.mjs && depcruise <every importer directory from step 1>. A scope narrower than the importers sees no outside code, so rule 1 never fires. The guard comes first because dependency-cruiser warns about an unsupported TypeScript and still exits 0: without it, a later TypeScript bump turns the merge gate into a pass. - Fold it into the umbrella check that already runs typecheck, where one exists.
- Add the same command as a step in a CI job that gates merge, or make its job a required check. CI runs the
lint:boundariesscript, never baredepcruise, so the guard stays in the path. A check outside the merge gate advises and enforces nothing.
Done when: a CI workflow runs lint:boundaries in a gating job, and the hand-back names the file and job.
5. Settle the violations already there
Run lint:boundaries once. A repo that never had the check usually fails it. Take each violation to the decider as fix or baseline:
- Fix: route the import through an entry point, by exporting from the entry or by opening a second entry named for its audience (
testing,server). - Baseline: record it as known with
node scripts/check-typescript-support.mjs && depcruise <dirs> --baseline(writes.dependency-cruiser-known-violations.json), put--ignore-knownin thelint:boundariesscript, file a ticket per cluster (to-tickets), and ratchet with--baseline-mode shrink-onlyas fixes land.
The rules, scope, and pathNot entries stay as step 2 decided; a violation is fixed or baselined, never excluded.
Done when: lint:boundaries exits 0 and every violation that was present is fixed or in the committed baseline with a ticket.
6. Prove it bites
Observe each outcome; assume none.
- Run
lint:boundaries: it passes. - Add a deliberate bad import in a real importer file, once per enabled rule and once per import style the repo uses (relative path, alias, package name). Write each probe in a
.tsor.tsxfile: a module count proves nothing about TypeScript, because dependency-cruiser counts plain.jsand.mjsfiles while skipping every.tsfile it cannot read, so only a probe that fails in a TypeScript file shows TypeScript is being read. Each run fails naming the rule:entrypoint-boundary-from-outside,entrypoint-boundary-across-packages,tests-through-entrypoints,tests-folder-is-private(probe it from a package's own non-test file importing its owntests/folder; an outside file would also tripentrypoint-boundary-from-outsideand prove less), for a two-file import loop,no-circular, and, for an import of a file that does not exist,not-to-unresolvable. A package-name probe into a package whosepackage.jsonhas anexportsmap also fails asnot-to-unresolvable, because the map does not list the deep path: the check is holding. The same probe into a package with onlymainfails asentrypoint-boundary-from-outsidewhen it sits outside every package, and asentrypoint-boundary-across-packageswhen it sits inside another package. - Revert every probe and run again: it passes, and
git diffshows no trace of them.
A repo with no package yet scaffolds <packages-root>/example/ in the decided shape: an entry file exporting a function that delegates to an internal file in a subfolder, and, with the tests rule on, a test importing only the entry. It is the copy-me template and the probe target, and nothing else in the repo is enforced until code lives in packages; say so plainly.
Done when: you have seen a pass, a named fail for every probe (each in a TypeScript file), and a pass again. A probe that does not fail means the check is not wired: fix it before finishing.
7. Put the rule where agents meet it
- Write
README.mdin the packages folder: the layout, one sentence per enabled rule, how to runlint:boundaries, and the barrel preference. - Add one context-pointer line to the repo's agent-instructions file (
CLAUDE.md, elseAGENTS.md, created if neither exists) naming that README, so an agent finds the rule before it trips on it. - The new check is a changed verify command. Tell the decider to re-run setup, whose diff of the binding doc's verify commands picks it up and puts it into every brief's verification set.
Done when: the README exists and states the barrel preference, the pointer is in the agent-instructions file, and the decider has been told to re-run setup.
When structure blocks the rules
A package whose code is one flat folder has nothing to hide, and an entry point over it hides nothing. Report that as a shallow-modules candidate to codebase-review rather than restructuring inside this lane's diff (implement's file-don't-fix rule).
Done when (checkable: verify each line before reporting complete)
- Every step 1 item has file evidence, and the TypeScript version is inside the linter's range (or the run stopped there with a report).
- The entry-point shape and the tests answer are the decider's, on record.
.dependency-cruiser.cjscarries constants matching those answers and an alias tsconfig that resolves the repo's aliased imports.lint:boundariescovers every importer directory, starts with the TypeScript guard, and runs in a CI job that gates merge; the file and job are named.lint:boundariesexits 0, and every pre-existing violation is fixed or in the committed baseline with a ticket.- A pass, then a named fail for each probe (every enabled rule including the unresolved-import rule, every import style in use, each probe in a TypeScript file), then a pass, were all observed; the working tree holds no probe.
- The README and the context pointer exist, and the decider was told to re-run setup.
- The diff holds the config, the guard, the script, the CI step, the docs, and the dependency-cruiser devDependency with its lockfile change, plus the baseline if step 5 baselined any violation, the decider-approved import fixes if step 5 fixed any, and the
<packages-root>/example/scaffold if the repo had no package, and nothing else.
Attribution
Adapted from Matt Pocock's setup-ts-deep-modules (MIT, in progress upstream). The model is his: a package as a deep module whose entry points are its public surface and whose subfolders are private, enforced with dependency-cruiser group back-references so a package reaches its own internals while outsiders cannot, tests held to the entry points, several small entry points over a barrel, a deliberate bad import as the completion criterion, and a README plus a context pointer so agents find the rule.
What this repo changes: existing repos come first (the entry-point shape and the tests rule are settings read from the repo and confirmed by the decider, not a fixed src/packages/<name>/{lib,tests} layout, and the scaffold is only for a repo with no packages); an existing boundary tool and an unsupported TypeScript version are checked before anything is installed, and a guard keeps a later TypeScript bump from turning the check into a pass; the check's scope is every importer directory and it runs in a merge-gating CI job; violations already present are fixed or baselined with tickets; the proof runs once per rule and import style, each probe in a TypeScript file; type-only and unused imports are counted, because upstream's config let both pass (its own example probe, an unused deep import, never fails); the decision is recorded through domain-memory; the new check reaches the binding doc through a setup re-run; the vocabulary and the structural handoff come from codebase-review; and the rules are listed once, where upstream's text says four and its config holds five.
Files (skills)
-
references
-
check-typescript-support.mjs 836 B · in bundle
-
dependency-cruiser.config.cjs 5.9 KB · in bundle
-
-
CHANGELOG.md 4.1 KB
Loading… -
SKILL.md 14.4 KB
--- name: ts-module-boundaries description: "Make each package in a TypeScript repo reachable only through its entry-point files, enforced by a dependency-linter check in CI and proven to bite with a deliberate bad import. Use when the decider asks for enforced module boundaries or deep modules, when a codebase-review boundaries-vs-reality finding is adopted for a TypeScript repo, or when code keeps importing past a package's entry points." --- # TypeScript module boundaries A package is a module, and its **entry points** (the one or few files other code may import from it) are where its interface lives. Everything behind them is implementation. This skill installs the check that makes that true: a dependency linter (a tool that reads every import and fails the build on one that breaks a rule), run in CI, that fails any import reaching past an entry point, then proves the check fails when it should. Terms follow the [design vocabulary](../../investigate/codebase-review/references/design-vocabulary.md): module, interface, seam, depth. The entry points are the package's seam, and the check keeps imports from crossing anywhere else. It is the enforcement half of [codebase-review](../../investigate/codebase-review/SKILL.md)'s boundaries-vs-reality lens: the lens finds where change bypasses the declared layout, and this skill makes the declared layout hold. Layering (which package may depend on which) is a different concern and stays out. Read the team-workflow binding doc first: its verify commands, memory home, and agent-context docs are what this skill writes to. A repo with no binding doc runs on its own scripts, and the hand-back names the unbound slots. ## The rules the check enforces All `error`: 1. **From outside.** Code outside every package (apps, scripts, root tests) imports a package only through its entry points. 2. **Across packages.** A package's own files import each other freely and reach another package only through its entry points. 3. **Tests (opt-in).** For repos where each package keeps its tests in a private `tests/` folder: tests import any package's entry points and their own `tests/` fixtures, never any package's internals (not even their own), and nothing outside a `tests/` folder imports one. The interface is the test surface. 4. **No runtime cycles.** Type-only imports do not count. 5. **Every import resolves.** An import the linter cannot resolve fails the check. Left unresolved it matches no rule above and passes, so a gap in resolution would let a deep import through. Entry points come in three shapes, set by the config's `ENTRY_POINTS` constant: one file per package (`src/index.ts`, for a workspace package whose `main` points there; an `exports` "." entry, when present, wins over `main`), several named files, or every file at the package root with the code in subfolders. A non-code export, such as a stylesheet, is listed by name with its extension (`styles\\.css`). Prefer several small entry points to a barrel that re-exports a whole subtree: a barrel makes the interface nearly as wide as the implementation, which is what shallow means. ## Steps ### 1. Read the ground Detect from the repo, with file evidence for each: - **Package manager**: the lockfile. - **Packages and their entry points**: workspace globs (`workspaces` in `package.json`, `pnpm-workspace.yaml`), each package's `main` and `exports` (a non-code export such as a stylesheet is an entry point too); failing that, folders shaped `<root>/<name>/index.ts`. - **Importer directories**: every directory holding code that imports a package (apps, scripts, root tests). This is the check's scope. - **Alias tsconfig**: the tsconfig that holds the `paths` aliases. - **Existing boundary tooling**: a dependency-cruiser config, `eslint-plugin-boundaries` or `no-restricted-imports` rules, Fallow `boundaries`, Nx, Sheriff, Steiger, a `lint:boundaries` script. Put it to the decider: extend it, or replace it with this skill's config. One rule never runs under two linters. - **TypeScript version**: dependency-cruiser supports a bounded range, and a version outside it skips every `.ts` file and still exits 0 (the linter's own warning names the range). Outside the range, stop and report to the decider; do not downgrade TypeScript or swap tools unasked. Step 3 installs a guard so a later bump fails the check instead of passing it. **Done when:** each item is written down with its evidence, the existing-tooling question is answered (or the repo has none), and the TypeScript version is inside the linter's range. ### 2. Settle the shape with the decider Brief the decider in plain words, with a recommendation and the step 1 evidence for each: - **Entry-point shape**: one file per package, several named files, or every root file. - **Tests**: beside the code they test (the opt-in rule stays off), or in a private `tests/` folder per package (it goes on). A repo with no package yet has nothing to enforce. The decider names the areas that become packages, with [codebase-review](../../investigate/codebase-review/SKILL.md)'s shallow-modules lens as the source of candidates, or approves the scaffold in step 6. **Done when:** the shape and tests answers are the decider's, recorded as a decision record with its load-bearing reason where the binding names a [domain-memory](../../orient/domain-memory/SKILL.md) home, otherwise in the PR description. ### 3. Install and configure - Install `dependency-cruiser` as a devDependency with the detected package manager. - Copy [references/dependency-cruiser.config.cjs](references/dependency-cruiser.config.cjs) to `.dependency-cruiser.cjs` (`.cjs` so it loads in a `"type": "module"` repo). Set its three constants to the step 2 answers and `tsConfig.fileName` to the alias tsconfig. - Copy [references/check-typescript-support.mjs](references/check-typescript-support.mjs) to `scripts/check-typescript-support.mjs` (or the repo's equivalent scripts folder). It exits 1 when dependency-cruiser cannot read TypeScript, which step 4 puts in front of every run. - The config resolves a package-name import through the package's `exports` map, so a second entry such as `@pkg/billing/testing` resolves. This changes how every package-name import resolves, so the first run in step 5 may surface failures the repo never saw: an import that never resolved, or a package subpath that now resolves and meets the boundary rules for the first time. - Merge into an existing `.dependency-cruiser.*` and report what was added; the existing file is never overwritten. - Leave `tsconfig` and the repo's path aliases as they are. **Done when:** `.dependency-cruiser.cjs` exists with constants matching the decided shape, `depcruise` runs, and the guard exits 0. ### 4. Wire it into CI - Add a `lint:boundaries` script: `node scripts/check-typescript-support.mjs && depcruise <every importer directory from step 1>`. A scope narrower than the importers sees no outside code, so rule 1 never fires. The guard comes first because dependency-cruiser warns about an unsupported TypeScript and still exits 0: without it, a later TypeScript bump turns the merge gate into a pass. - Fold it into the umbrella check that already runs typecheck, where one exists. - Add the same command as a step in a CI job that gates merge, or make its job a required check. CI runs the `lint:boundaries` script, never bare `depcruise`, so the guard stays in the path. A check outside the merge gate advises and enforces nothing. **Done when:** a CI workflow runs `lint:boundaries` in a gating job, and the hand-back names the file and job. ### 5. Settle the violations already there Run `lint:boundaries` once. A repo that never had the check usually fails it. Take each violation to the decider as fix or baseline: - **Fix**: route the import through an entry point, by exporting from the entry or by opening a second entry named for its audience (`testing`, `server`). - **Baseline**: record it as known with `node scripts/check-typescript-support.mjs && depcruise <dirs> --baseline` (writes `.dependency-cruiser-known-violations.json`), put `--ignore-known` in the `lint:boundaries` script, file a ticket per cluster ([to-tickets](../../run/to-tickets/SKILL.md)), and ratchet with `--baseline-mode shrink-only` as fixes land. The rules, scope, and `pathNot` entries stay as step 2 decided; a violation is fixed or baselined, never excluded. **Done when:** `lint:boundaries` exits 0 and every violation that was present is fixed or in the committed baseline with a ticket. ### 6. Prove it bites Observe each outcome; assume none. 1. Run `lint:boundaries`: it passes. 2. Add a deliberate bad import in a real importer file, once per enabled rule and once per import style the repo uses (relative path, alias, package name). Write each probe in a `.ts` or `.tsx` file: a module count proves nothing about TypeScript, because dependency-cruiser counts plain `.js` and `.mjs` files while skipping every `.ts` file it cannot read, so only a probe that fails in a TypeScript file shows TypeScript is being read. Each run fails naming the rule: `entrypoint-boundary-from-outside`, `entrypoint-boundary-across-packages`, `tests-through-entrypoints`, `tests-folder-is-private` (probe it from a package's own non-test file importing its own `tests/` folder; an outside file would also trip `entrypoint-boundary-from-outside` and prove less), for a two-file import loop, `no-circular`, and, for an import of a file that does not exist, `not-to-unresolvable`. A package-name probe into a package whose `package.json` has an `exports` map also fails as `not-to-unresolvable`, because the map does not list the deep path: the check is holding. The same probe into a package with only `main` fails as `entrypoint-boundary-from-outside` when it sits outside every package, and as `entrypoint-boundary-across-packages` when it sits inside another package. 3. Revert every probe and run again: it passes, and `git diff` shows no trace of them. A repo with no package yet scaffolds `<packages-root>/example/` in the decided shape: an entry file exporting a function that delegates to an internal file in a subfolder, and, with the tests rule on, a test importing only the entry. It is the copy-me template and the probe target, and nothing else in the repo is enforced until code lives in packages; say so plainly. **Done when:** you have seen a pass, a named fail for every probe (each in a TypeScript file), and a pass again. A probe that does not fail means the check is not wired: fix it before finishing. ### 7. Put the rule where agents meet it - Write `README.md` in the packages folder: the layout, one sentence per enabled rule, how to run `lint:boundaries`, and the barrel preference. - Add one context-pointer line to the repo's agent-instructions file (`CLAUDE.md`, else `AGENTS.md`, created if neither exists) naming that README, so an agent finds the rule before it trips on it. - The new check is a changed verify command. Tell the decider to re-run [setup](../../orient/setup/SKILL.md), whose diff of the binding doc's verify commands picks it up and puts it into every brief's verification set. **Done when:** the README exists and states the barrel preference, the pointer is in the agent-instructions file, and the decider has been told to re-run setup. ## When structure blocks the rules A package whose code is one flat folder has nothing to hide, and an entry point over it hides nothing. Report that as a shallow-modules candidate to [codebase-review](../../investigate/codebase-review/SKILL.md) rather than restructuring inside this lane's diff ([implement](../../run/implement/SKILL.md)'s file-don't-fix rule). ## Done when (checkable: verify each line before reporting complete) - Every step 1 item has file evidence, and the TypeScript version is inside the linter's range (or the run stopped there with a report). - The entry-point shape and the tests answer are the decider's, on record. - `.dependency-cruiser.cjs` carries constants matching those answers and an alias tsconfig that resolves the repo's aliased imports. - `lint:boundaries` covers every importer directory, starts with the TypeScript guard, and runs in a CI job that gates merge; the file and job are named. - `lint:boundaries` exits 0, and every pre-existing violation is fixed or in the committed baseline with a ticket. - A pass, then a named fail for each probe (every enabled rule including the unresolved-import rule, every import style in use, each probe in a TypeScript file), then a pass, were all observed; the working tree holds no probe. - The README and the context pointer exist, and the decider was told to re-run setup. - The diff holds the config, the guard, the script, the CI step, the docs, and the dependency-cruiser devDependency with its lockfile change, plus the baseline if step 5 baselined any violation, the decider-approved import fixes if step 5 fixed any, and the `<packages-root>/example/` scaffold if the repo had no package, and nothing else. ## Attribution Adapted from Matt Pocock's [`setup-ts-deep-modules`](https://github.com/mattpocock/skills/tree/main/skills/in-progress/setup-ts-deep-modules) (MIT, in progress upstream). The model is his: a package as a deep module whose entry points are its public surface and whose subfolders are private, enforced with dependency-cruiser group back-references so a package reaches its own internals while outsiders cannot, tests held to the entry points, several small entry points over a barrel, a deliberate bad import as the completion criterion, and a README plus a context pointer so agents find the rule. What this repo changes: existing repos come first (the entry-point shape and the tests rule are settings read from the repo and confirmed by the decider, not a fixed `src/packages/<name>/{lib,tests}` layout, and the scaffold is only for a repo with no packages); an existing boundary tool and an unsupported TypeScript version are checked before anything is installed, and a guard keeps a later TypeScript bump from turning the check into a pass; the check's scope is every importer directory and it runs in a merge-gating CI job; violations already present are fixed or baselined with tickets; the proof runs once per rule and import style, each probe in a TypeScript file; type-only and unused imports are counted, because upstream's config let both pass (its own example probe, an unused deep import, never fails); the decision is recorded through domain-memory; the new check reaches the binding doc through a setup re-run; the vocabulary and the structural handoff come from codebase-review; and the rules are listed once, where upstream's text says four and its config holds five.
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.