docs: reflect tooling-package rename + Turbo boundaries enforcement
- Rename eslint-config → core-eslint, typescript-config → core-typescript in all docs (package map, AGENTS.md, overview.md, dependency-flow.md, etc.) - Document the five-tag model (app, feature, core, core-composition, tooling) — refinement of ADR-006's three-tag mention - Document core-trpc's core-composition tag (transitively reaches features through core-api's AppRouter type) - Note Turborepo boundaries as a second enforcement layer alongside ESLint - Add ADR-010 explaining the two-layer enforcement decision and five-tag refinement Files updated: - docs/architecture/overview.md: package map, enforcement layers, five-tag section - docs/architecture/dependency-flow.md: boundary rules, enforcement strategy - docs/architecture/vertical-feature-spec.md: package names, five-tag model - AGENTS.md: package map, boundary rules, commands - CLAUDE.md: tooling package names, quick-start command - packages/core-eslint/AGENTS.md: tag clarification - packages/core-typescript/AGENTS.md: tag clarification - packages/core-api/AGENTS.md: core-composition tag - packages/core-cms/AGENTS.md: core-composition tag - packages/core-trpc/AGENTS.md: core-composition tag + rationale - docs/decisions/adr-010-turbo-boundaries.md: new ADR Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -21,13 +21,16 @@
|
||||
| shared | | | | |
|
||||
+--------+ +-----------+ +----------------+
|
||||
|
||||
Boundary rules (enforced by eslint-plugin-boundaries):
|
||||
app → app, core, feature, core-composition (any)
|
||||
feature → core (any), but NOT other features, NOT app
|
||||
core → core, but NOT feature, NOT app
|
||||
core-composition → core, feature subpath exports only (`/cms`, `/api`)
|
||||
core-api → @repo/<feature>/api
|
||||
core-cms → @repo/<feature>/cms
|
||||
Boundary rules (enforced by ESLint + Turborepo boundaries):
|
||||
app → app, core, core-composition, feature, tooling
|
||||
feature → core, tooling
|
||||
core → core, core-composition, tooling
|
||||
core-composition → core, core-composition, feature, tooling
|
||||
tooling → tooling
|
||||
|
||||
Composition exceptions:
|
||||
core-api → @repo/<feature>/api (subpath only)
|
||||
core-cms → @repo/<feature>/cms (subpath only)
|
||||
```
|
||||
|
||||
## Concrete examples
|
||||
@@ -65,6 +68,14 @@ import { blogRouter } from "@repo/blog/api"; // ❌ core → feature
|
||||
import { someBlogThing } from "@repo/blog"; // ❌ core → feature (only core-api/core-cms have exception)
|
||||
```
|
||||
|
||||
## Three-layer enforcement
|
||||
## Enforcement strategy
|
||||
|
||||
ESLint catches accidental cross-package imports at lint time. The `package.json` `exports` map blocks deep imports at module-resolution time. Workspace `dependencies` declarations make the package graph itself the source of truth — if you didn't declare it, you can't import it.
|
||||
Three layers work in tandem:
|
||||
|
||||
1. **`package.json` dependencies** — if you didn't declare it, you can't import it
|
||||
2. **`exports` map** — blocks deep imports; only public subpaths are accessible
|
||||
3. **Two parallel automated checks** (both enforcing the same five-tag model):
|
||||
- **ESLint `eslint-plugin-boundaries`** runs at lint time, catching direct-import violations
|
||||
- **Turborepo `boundaries`** runs at build time, validating the entire workspace graph including transitive dependencies
|
||||
|
||||
The two enforcement layers are independent but complementary. ESLint is stricter on per-import context (e.g., file-specific exemptions via `// @boundaries-ignore`), while Turborepo catches transitive issues that lint-time checking misses. Run `pnpm lint` and `pnpm turbo boundaries` in CI to catch all violations.
|
||||
|
||||
@@ -21,8 +21,8 @@ packages/
|
||||
navigation/ Header global + menu items
|
||||
|
||||
# Tooling
|
||||
eslint-config/ Shared ESLint flat config + boundary rules
|
||||
typescript-config/ Shared tsconfig + vitest base
|
||||
core-eslint/ Shared ESLint flat config + boundary rules
|
||||
core-typescript/ Shared tsconfig + vitest base
|
||||
```
|
||||
|
||||
## Data flow
|
||||
@@ -47,7 +47,36 @@ Payload Local API → Postgres
|
||||
|
||||
1. **`package.json` deps** — only declare allowed deps
|
||||
2. **`exports` map** — each package exposes a small public surface (`.`, `./cms`, `./api`, `./di/bind-production`)
|
||||
3. **ESLint `eslint-plugin-boundaries`** — three tags (`app`, `feature`, `core`); two composition exceptions (`core-api` may import `@repo/<feature>/api`; `core-cms` may import `@repo/<feature>/cms`)
|
||||
3. **Two parallel automated checks**:
|
||||
- **ESLint `eslint-plugin-boundaries`** (lint-time) — enforces boundary rules at linting
|
||||
- **Turborepo `boundaries`** (build-graph time) — validates entire workspace dependency graph, including transitive reaches
|
||||
|
||||
Both use the same five-tag model; see "Five tags" section below.
|
||||
|
||||
## Five tags
|
||||
|
||||
The workspace is organized into five mutually exclusive tags:
|
||||
|
||||
- **app** (4 packages): `apps/cms`, `apps/web-next`, `apps/web-tanstack`, `apps/storybook`
|
||||
- **core-composition** (3 packages): `packages/core-api`, `packages/core-cms`, `packages/core-trpc`
|
||||
- **core** (2 packages): `packages/core-shared`, `packages/core-ui`
|
||||
- **feature** (5 packages): `packages/auth`, `packages/blog`, `packages/media`, `packages/marketing-pages`, `packages/navigation`
|
||||
- **tooling** (2 packages): `packages/core-eslint`, `packages/core-typescript`
|
||||
|
||||
**Allowed dependency directions:**
|
||||
|
||||
| Tag | May depend on |
|
||||
|---|---|
|
||||
| app | app, core, core-composition, feature, tooling |
|
||||
| core-composition | core, core-composition, feature, tooling |
|
||||
| core | core, core-composition, tooling |
|
||||
| feature | core, tooling |
|
||||
| tooling | tooling |
|
||||
|
||||
**Composition exceptions:**
|
||||
- `core-api` may import from `@repo/<feature>/api` subpath exports only
|
||||
- `core-cms` may import from `@repo/<feature>/cms` subpath exports only
|
||||
- `core-trpc` reaches features transitively through `core-api`'s `AppRouter` type
|
||||
|
||||
## Per-feature DI containers
|
||||
|
||||
|
||||
@@ -40,7 +40,7 @@ The refactor preserves Clean Architecture layering *inside* each feature (the ex
|
||||
|
||||
- Five `core-*` packages: `core-shared`, `core-cms`, `core-api`, `core-trpc`, `core-ui`
|
||||
- Five feature packages: `auth`, `blog`, `media`, `marketing-pages`, `navigation`
|
||||
- Two tooling packages unchanged: `eslint-config`, `typescript-config`
|
||||
- Two tooling packages renamed: `eslint-config` → `core-eslint`, `typescript-config` → `core-typescript`
|
||||
- Three apps unchanged in name: `apps/web-next`, `apps/web-tanstack`, `apps/cms`
|
||||
- Packages deleted: `packages/core`, `packages/api`, `packages/api-client`, `packages/cms-core`, `packages/cms-client`, `packages/ui`
|
||||
- Per-feature InversifyJS containers (no shared container)
|
||||
@@ -124,9 +124,9 @@ repo/
|
||||
marketing-pages/ # pages collection + SiteSettings global
|
||||
navigation/ # header global
|
||||
|
||||
# ─── TOOLING (untagged) ───
|
||||
eslint-config/
|
||||
typescript-config/
|
||||
# ─── TOOLING (tagged "tooling") ───
|
||||
core-eslint/
|
||||
core-typescript/
|
||||
|
||||
docs/
|
||||
architecture/
|
||||
@@ -392,44 +392,47 @@ export default buildConfig({
|
||||
|
||||
## 9. Boundaries + enforcement
|
||||
|
||||
### 9.1 Tags
|
||||
### 9.1 Five tags
|
||||
|
||||
Package-level `turbo.json` tags:
|
||||
Package-level `turbo.json` tags (refined from earlier ADR-006's three-tag model):
|
||||
|
||||
| Tag | Packages |
|
||||
|---|---|
|
||||
| `app` | `apps/web-next`, `apps/web-tanstack`, `apps/cms` |
|
||||
| `app` | `apps/web-next`, `apps/web-tanstack`, `apps/cms`, `apps/storybook` |
|
||||
| `core-composition` | `packages/core-api`, `core-cms`, `core-trpc` |
|
||||
| `core` | `packages/core-shared`, `core-ui` |
|
||||
| `feature` | `packages/auth`, `blog`, `media`, `marketing-pages`, `navigation` |
|
||||
| `core` | `packages/core-shared`, `core-cms`, `core-api`, `core-trpc`, `core-ui` |
|
||||
| (untagged) | `packages/eslint-config`, `packages/typescript-config` |
|
||||
| `tooling` | `packages/core-eslint`, `core-typescript` |
|
||||
|
||||
Note: `core-trpc` is `core-composition` (not plain `core`) because it transitively reaches features through `core-api`'s `AppRouter` type.
|
||||
|
||||
### 9.2 Allowed dependency directions
|
||||
|
||||
```
|
||||
app → feature, core
|
||||
feature → core
|
||||
core → core (restricted; see exceptions)
|
||||
```
|
||||
|
||||
Disallowed: `core → feature`, `core → app`, `feature → app`, `feature → feature`.
|
||||
| Tag | May depend on |
|
||||
|---|---|
|
||||
| app | app, core, core-composition, feature, tooling |
|
||||
| core-composition | core, core-composition, feature, tooling |
|
||||
| core | core, core-composition, tooling |
|
||||
| feature | core, tooling |
|
||||
| tooling | tooling |
|
||||
|
||||
### 9.3 Composition exceptions
|
||||
|
||||
- `core-cms` may import `@repo/<feature>/cms` subpath exports only.
|
||||
- `core-api` may import `@repo/<feature>/api` subpath exports only.
|
||||
- No other `core-*` package may import any feature package under any export.
|
||||
- No other package may deviate from the five-tag rules.
|
||||
|
||||
### 9.4 Three enforcement layers
|
||||
### 9.4 Four enforcement layers
|
||||
|
||||
1. **`package.json` dependencies** — only allowed deps declared.
|
||||
2. **`exports` maps** — feature packages expose `.`, `./cms`, `./api` only (no deep source paths).
|
||||
3. **ESLint `eslint-plugin-boundaries`** — configured in `packages/eslint-config/` flat config:
|
||||
- Feature packages may import other packages only through public subpath exports.
|
||||
- `core-shared`, `core-trpc`, `core-ui` may not import feature packages.
|
||||
- `core-api` restricted to `@repo/<feature>/api`.
|
||||
- `core-cms` restricted to `@repo/<feature>/cms`.
|
||||
- No `../../../` cross-package source imports.
|
||||
4. **TypeScript path aliases** (`tsconfig.base.json`) — only `@repo/<feature>`, `@repo/<feature>/cms`, `@repo/<feature>/api`; no `@repo/<feature>/src/...` paths exist, blocking deep imports at editor level.
|
||||
3. **ESLint `eslint-plugin-boundaries`** (lint-time) — configured in `packages/core-eslint/` flat config:
|
||||
- Enforces the five-tag rules (same rules as Turbo boundaries)
|
||||
- File-specific exemptions via `// @boundaries-ignore` comments
|
||||
4. **Turborepo `boundaries`** (build-graph time) — configured in root `turbo.json`:
|
||||
- Validates the entire workspace dependency graph, including transitive dependencies
|
||||
- Catches issues that lint-time checking misses (e.g., transitive feature reaches)
|
||||
- Run `pnpm turbo boundaries` to validate
|
||||
|
||||
### 9.5 Root `turbo.json` (unchanged concept)
|
||||
|
||||
@@ -469,7 +472,7 @@ Tags govern architectural boundaries; `dependsOn: ["^build"]` governs task execu
|
||||
### 10.2 Vitest
|
||||
|
||||
- Each package has its own `vitest.config.ts`.
|
||||
- Shared base in `packages/typescript-config/vitest.base.ts`; packages extend it and pick `environment: 'jsdom' | 'node'` per need.
|
||||
- Shared base in `packages/core-typescript/vitest.base.ts`; packages extend it and pick `environment: 'jsdom' | 'node'` per need.
|
||||
- Turbo `test` task runs `vitest run` per package.
|
||||
|
||||
### 10.3 DI in tests (per-feature container)
|
||||
|
||||
123
docs/decisions/adr-010-turbo-boundaries.md
Normal file
123
docs/decisions/adr-010-turbo-boundaries.md
Normal file
@@ -0,0 +1,123 @@
|
||||
# ADR-010: Turborepo boundaries alongside ESLint enforcement
|
||||
|
||||
**Status:** Accepted
|
||||
**Date:** 2026-05-04
|
||||
**Supersedes:** ADR-006 (partial refinement; not a contradiction)
|
||||
|
||||
## Context
|
||||
|
||||
ADR-006 established the vertical-feature monorepo with three tags (`app`, `feature`, `core`). ESLint with `eslint-plugin-boundaries` was introduced to enforce direct-import boundaries at lint time, catching violations like:
|
||||
|
||||
- Feature package importing from another feature
|
||||
- Core package importing from a feature
|
||||
- Deep imports past public `exports` map boundaries
|
||||
|
||||
However, ESLint has two intrinsic limitations:
|
||||
|
||||
1. **No transitive enforcement** — If `core-trpc` imports `core-api` (which imports feature routers), ESLint sees only the direct edge `core-trpc` → `core-api`. The transitive reach into features is invisible. A package can declare `@repo/feature-x` as a dependency without ever importing it directly.
|
||||
|
||||
2. **No declared-dep enforcement** — A `package.json` dependency that doesn't match an actual import goes undetected. Conversely, a `package.json` dependency might be missing but the transitive graph still allows the code to work.
|
||||
|
||||
The result: two types of dependency drift escape lint-time checking:
|
||||
|
||||
- A composition package's transitive reach into features (real problem: `core-trpc` → `core-api` → `feature-blog-routers`)
|
||||
- Incorrect or missing `package.json` declarations
|
||||
|
||||
## Decision
|
||||
|
||||
Add Turborepo's `boundaries` feature as a second enforcement layer running at **build-graph time** (before build), parallel to ESLint's lint-time checks.
|
||||
|
||||
### Five-tag model (refined from ADR-006)
|
||||
|
||||
ADR-006 mentioned three tags. This ADR refines the model to five, distinguishing composition packages explicitly:
|
||||
|
||||
- **app** — `apps/web-next`, `apps/web-tanstack`, `apps/cms`, `apps/storybook`
|
||||
- **core** — `packages/core-shared`, `core-ui` (pure foundation, no transitive feature reach)
|
||||
- **core-composition** — `packages/core-api`, `core-cms`, `core-trpc` (composition or transitively reach features)
|
||||
- **feature** — `packages/auth`, `blog`, `media`, `marketing-pages`, `navigation`
|
||||
- **tooling** — `packages/core-eslint`, `core-typescript`
|
||||
|
||||
Why `core-trpc` is `core-composition`:
|
||||
- `core-trpc` imports `@repo/core-api` (the tRPC app router)
|
||||
- `core-api` imports feature routers from `@repo/<feature>/api`
|
||||
- Therefore, `core-trpc` transitively depends on features through the `AppRouter` type
|
||||
- This violates ADR-006's "core → NOT feature" rule if we treat `core-trpc` as plain `core`
|
||||
- Solution: tag `core-trpc` as `core-composition` to make the transitive reach explicit and allowed
|
||||
|
||||
### Implementation
|
||||
|
||||
1. **Root `turbo.json`** declares boundary rules as a `boundaries.tags` config:
|
||||
```json
|
||||
{
|
||||
"boundaries": {
|
||||
"tags": {
|
||||
"app": { "dependencies": { "allow": ["app", "core", "core-composition", "feature", "tooling"] } },
|
||||
"core-composition": { "dependencies": { "allow": ["core", "core-composition", "feature", "tooling"] } },
|
||||
"core": { "dependencies": { "allow": ["core", "core-composition", "tooling"] } },
|
||||
"feature": { "dependencies": { "allow": ["core", "tooling"] } },
|
||||
"tooling": { "dependencies": { "allow": ["tooling"] } }
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
2. **Per-package `turbo.json`** declares the package's tag:
|
||||
```json
|
||||
// packages/blog/turbo.json
|
||||
{ "extends": ["../../../turbo.json"], "tasks": { /* ... */ } }
|
||||
// package.json
|
||||
{ "turbo": { "tasks": { "build": { /* ... */ } }, "tags": ["feature"] } }
|
||||
```
|
||||
|
||||
3. **CLI validation** — `pnpm turbo boundaries` runs the check in <1 second without building anything
|
||||
|
||||
### Two layers, not one
|
||||
|
||||
Both ESLint and Turborepo enforce the same five-tag rules, but for different reasons:
|
||||
|
||||
| Layer | Runs | Sees | Exempts via |
|
||||
|---|---|---|---|
|
||||
| ESLint `eslint-plugin-boundaries` | lint-time | Direct imports per file | `// @boundaries-ignore` comments |
|
||||
| Turborepo `boundaries` | build-graph time | Entire workspace dependency graph including transitives | None (graph-based, not per-import) |
|
||||
|
||||
**Why both?**
|
||||
- **ESLint** provides fine-grained control (file-level exemptions) and immediate feedback during development
|
||||
- **Turborepo** catches transitive issues (e.g., feature reach through composition packages) and missing declarations
|
||||
|
||||
**Enforcement** — CI runs both: `pnpm lint` (includes ESLint) and `pnpm turbo boundaries`.
|
||||
|
||||
## Consequences
|
||||
|
||||
1. **Two independent checks** — developers get immediate ESLint feedback and a final Turbo gate in CI
|
||||
2. **Both must stay in sync** — when adding a new tag rule, update both:
|
||||
- `packages/core-eslint/base.js` (ESLint `eslint-plugin-boundaries` config)
|
||||
- Root `turbo.json` (`boundaries.tags` config)
|
||||
- Per-package `package.json` `turbo.tags` declaration
|
||||
3. **Stricter than before** — Turborepo sees transitives; some patterns that pass ESLint may fail Turbo:
|
||||
- Example: `packages/cms` might try to use `@repo/<dep>` indirectly (not importing, but depending)
|
||||
- Solution: declare the dependency explicitly or restructure the import
|
||||
4. **The five-tag model is a refinement, not a contradiction** — ADR-006 mentioned three tags; this ADR adds `core-composition` and `tooling` explicitly and moves them into the boundary enforcement
|
||||
5. **`core-trpc`'s new tag** — previously thought of as `core`, now explicitly `core-composition` to match its transitive reach; any code assuming `core-trpc` is `core` must be updated
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
1. **ESLint only** — Simple, immediate feedback. Downside: misses transitive issues; no build-graph validation.
|
||||
2. **Turborepo only** — Catches everything eventually, but slower feedback cycle; less granular exemptions.
|
||||
3. **Both in series** — ESLint first (fast), Turbo second (thorough). Chosen.
|
||||
4. **Custom graph validator** — Over-engineered; Turborepo's built-in feature is stable and designed for this.
|
||||
|
||||
## Related
|
||||
|
||||
- **ADR-006:** Vertical feature packages (the original three-tag model)
|
||||
- **ADR-009:** Integrations folder naming
|
||||
- **`packages/core-eslint/base.js`** — ESLint configuration
|
||||
- **Root `turbo.json`** — Turborepo configuration with boundaries rules
|
||||
- **`docs/architecture/overview.md`** — Package map and five-tag summary
|
||||
- **`docs/architecture/dependency-flow.md`** — Enforcement layers and rules
|
||||
- **`AGENTS.md`** — Per-package boundary documentation
|
||||
|
||||
## Timeline
|
||||
|
||||
- **2026-05-04** — Turborepo boundaries added alongside existing ESLint enforcement
|
||||
- **CI integration** — `pnpm turbo boundaries` added to lint stage
|
||||
- **Documentation** — Updated AGENTS.md, overview.md, dependency-flow.md, vertical-feature-spec.md
|
||||
Reference in New Issue
Block a user