Review TypeScript Module Boundaries

---
name: "typescript-module-boundary-review"
description: "Review TypeScript modules for dependency direction, public APIs, circular dependencies, and import leakage, then strengthen boundaries with the smallest useful refactor."
---

# Review TypeScript Module Boundaries

Use this skill when deep imports, circular dependencies, vague shared folders, or cross-feature coupling make a TypeScript codebase harder to change safely.

## Workflow

1. Identify the scope and intended public entry points of each module.
2. Map incoming and outgoing imports as a dependency graph.
3. Flag consumers that reach into another module's private file layout.
4. Reduce each circular dependency to the smallest explainable cycle.
5. Assign ownership of types, services, and utilities by their reason to change.
6. Define the smallest public API required by real consumers.
7. Fix import direction before moving large groups of files.
8. Run the repository's available type checks, linting, tests, and build.

## Decision rules

- Do not use `shared` as a default home for uncertain ownership.
- Do not create an abstraction only to make an import look cleaner.
- Distinguish type-only dependencies from runtime dependencies.
- A public API should protect consumers from internal file layout changes.
- Do not hide cycles behind service locators or global singletons.
- Preserve healthy repository conventions unless evidence supports changing them.

## Expected output

```text
Boundary finding:
Evidence:
Direction today:
Desired direction:
Smallest change:
Risk:
Validation:
```

Finish with a compact dependency map, remaining cycles, changed public contracts, and any regression-prevention rule that is justified by a repeated problem. Recommend new lint rules or tooling only when the codebase has enough evidence to justify the maintenance cost.