diff --git a/AGENTS.md b/AGENTS.md index d9d7194..61cec71 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -84,7 +84,7 @@ No other cross-package boundary deviations are permitted. ## Adding a Feature -**Fast path — use the generator.** `pnpm turbo gen feature` scaffolds a Lazar-conformant package under `packages//` (single entity, single `getX` use case) matching the `navigation` reference shape. It emits package files, entities, use case + controller (with input/output schemas + presenter), mock + real repositories (real one is a Phase-1 stub), DI container, both binders (`bind-production` / `bind-dev-seed`), tRPC procedures + router with tests, contract suite, dev seed, and an empty `ui/` barrel — all wired with the span + capture sandwich at bind time. +**Fast path — use the generator.** `pnpm turbo gen feature` scaffolds a package under `packages//` (single entity, single `getX` use case) matching the `navigation` reference shape. It emits package files, entities, use case + controller (with input/output schemas + presenter), mock + real repositories, DI container, both binders (`bind-production` / `bind-dev-seed`), tRPC procedures + router with tests, contract suite, dev seed, and an empty `ui/` barrel — all wired with the span + capture sandwich at bind time. ```bash pnpm turbo gen feature # interactive @@ -93,7 +93,7 @@ pnpm turbo gen feature --args widgets Widget widgets # non-interactive: These conventions reflect the post-Plan-8 (Lazar conformance) and post-Plan-9 (input/output unification) state. > Canonical summary: `CLAUDE.md` § Key Conventions. -> Refactor logs: `docs/superpowers/refactor-logs/2026-05-05-lazar-pattern-conformance.md` (Plan 8) and `docs/superpowers/refactor-logs/2026-05-06-input-output-unification.md` (Plan 9). -> Decision records: `docs/decisions/adr-012-lazar-conformance.md` and `docs/decisions/adr-013-input-output-unification.md`. +> Decision records: `docs/decisions/adr-012-feature-conventions.md` and `docs/decisions/adr-013-input-output-unification.md`. ### Source files use RELATIVE imports (not @/) @@ -189,7 +187,7 @@ TypeScript configs must set `"rootDir": "."` to allow both `src/` and test files } ``` -### Use cases own input + output schemas (Plan 9, R1–R5) +### Use cases own input + output schemas Every use-case file exports its Zod schemas and inferred types. The use case body validates its output before returning — a misbehaving repository fails loudly at the layer that owns the contract. @@ -230,7 +228,7 @@ const useCase = getArticlesUseCase(repo); const articles = await useCase({ status: "published" }); ``` -### Controllers receive `unknown` + presenter (Plan 9, R7–R12) +### Controllers receive `unknown` + presenter Controllers `safeParse(xInputSchema)` from the use-case file and throw `InputParseError` on failure. Every non-void controller defines a top-level `function presenter(value: XOutput)` and returns `Promise>`. Identity is fine — `return value` — but the function form is always present so adding a transform later is a one-line edit. @@ -271,7 +269,7 @@ bind(BLOG_SYMBOLS.IGetArticlesUseCase).toDynamicValue( ); ``` -### Feature-scoped tRPC error mapping (Plan 9, R13–R17) +### Feature-scoped tRPC error mapping Each feature owns `integrations/api/procedures.ts` that wires domain errors to tRPC codes. `core-shared` provides the `defineErrorMiddleware` factory but never enumerates feature error classes. @@ -292,7 +290,7 @@ export const blogProcedure = t.procedure.use( The router then uses `blogProcedure.input(xInputSchema)` for every procedure — schemas are imported from the use-case file, never redefined inline. Unmapped errors still surface as `TRPCError(code: INTERNAL_SERVER_ERROR)`; the original domain error is preserved as `.cause`. -### Per-feature public-API surface (Plan 9, R18–R21) +### Per-feature public-API surface Each feature package exposes exactly these subpath exports: @@ -407,7 +405,7 @@ See `docs/guides/conformance-quickref.md` for the canonical pattern; the generat --- -### Cross-feature events and background jobs (Plan 10, ADR-015) +### Cross-feature events and background jobs (ADR-015) Three rules: @@ -516,11 +514,11 @@ const wrappedCtrl = withSpan( | Controller | `InputParseError` from `safeParse` failure (via `withCapture`) | Errors from use cases — flag set, `withCapture` bails | | `defineErrorMiddleware` | Nothing — maps domain → TRPCError only | — | -**Boundary rules (eslint-enforced, R40 + R52):** +**Boundary rules (eslint-enforced):** Feature packages MUST NOT `import "@sentry/*"` or `import "@opentelemetry/sdk-*"`. Allowlists: -- R40 (`@sentry/*`): `**/instrumentation/otel/sentry-bridge.{ts,js}`, `**/instrumentation/sentry/init-client*.{ts,js}`, `**/instrumentation/sentry/init-server*.{ts,js}`, `**/setup/no-instrumentation.{ts,js}`, `apps/*/instrumentation*.{ts,mjs,js}`, `apps/*/next.config.{mjs,ts,js}`, `apps/*/vite.config.{ts,mjs,js}` -- R52 (`@opentelemetry/sdk-*`, `@opentelemetry/instrumentation-*`, `@opentelemetry/resources`, `@opentelemetry/semantic-conventions`, `@sentry/opentelemetry`): `**/instrumentation/otel/**` +- `@sentry/*`: `**/instrumentation/otel/sentry-bridge.{ts,js}`, `**/instrumentation/sentry/init-client*.{ts,js}`, `**/instrumentation/sentry/init-server*.{ts,js}`, `**/setup/no-instrumentation.{ts,js}`, `apps/*/instrumentation*.{ts,mjs,js}`, `apps/*/next.config.{mjs,ts,js}`, `apps/*/vite.config.{ts,mjs,js}` +- `@opentelemetry/sdk-*`, `@opentelemetry/instrumentation-*`, `@opentelemetry/resources`, `@opentelemetry/semantic-conventions`, `@sentry/opentelemetry`: `**/instrumentation/otel/**` The vendor-neutral API packages (`@opentelemetry/api`, `@opentelemetry/api-logs`) are unrestricted within `core-shared/instrumentation/`. diff --git a/CLAUDE.md b/CLAUDE.md index 6385f7c..0c83d56 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -76,7 +76,7 @@ See `docs/architecture/agent-first-workflow-and-conformance.md` for the full des - **`@/` alias in tests** — Test files (`*.test.ts`) use `@/` to import from `src/` - **`vitest.config.ts`** — Every package must define `resolve.alias: { "@": path.resolve(__dirname, "./src") }` - **`tsconfig.json` rootDir** — Set `"rootDir": "."` so TypeScript finds both `src/` and test files -- **Lazar-conformant file layout** — Entities live at `entities/models/.ts`; errors at `entities/errors/.ts` + `entities/errors/common.ts`; mock siblings use the `.mock.ts` suffix (`.repository.mock.ts`); real repository impls drop the `payload-` prefix (`.repository.ts`); interface filenames are dot-separated (`.repository.interface.ts`) +- **File layout convention** — Entities live at `entities/models/.ts`; errors at `entities/errors/.ts` + `entities/errors/common.ts`; mock siblings use the `.mock.ts` suffix (`.repository.mock.ts`); real repository impls drop the `payload-` prefix (`.repository.ts`); interface filenames are dot-separated (`.repository.interface.ts`) - **Factory-function use cases & controllers** — Every use case and controller is `(deps) => async (input) => result`; each exports `export type I*UseCase = ReturnType` (and the analogous `I*Controller`); one controller per use case (no multi-method controllers) - **DI uses `.toDynamicValue()` for factories** — `bind(SYMBOL).toDynamicValue((ctx) => xUseCase(ctx.container.get(...)))`; mocks remain the default binding - **Tests inject mocks directly** — Construct `MockXRepository` and pass into the factory: `signInUseCase(mockUsers, mockAuth)(input)`. No container rebinding in unit tests @@ -88,10 +88,10 @@ See `docs/architecture/agent-first-workflow-and-conformance.md` for the full des - **Three binding modes per feature** — Each feature exports two binders: `./di/bind-production` (real Payload) and `./di/bind-dev-seed` (populated mock). The app's `bindAll()` dispatcher in `apps/web-next/src/server/bind-production.ts` picks one by env: `USE_DEV_SEED="true"` → dev seed; `NODE_ENV="production"` → production; otherwise → dev seed (developer default so `pnpm dev` boots without Payload). Dev seed lives in `src/__seeds__/dev.ts` as a lazy `buildDev()` function that uses the feature's existing factory - **Binders take a `ctx` arg from `core-shared/di`** — `bindProductionX(ctx: BindProductionContext)` for production binders; `bindDevSeedX(ctx: BindContext)` for dev-seed. Required fields: `tracer`, `logger`, plus `config` for production. Optional fields: `bus`, `queue`, `realtime`, `realtimeRegistry` (correspond to optional core packages — guard with `?.` or `if (bus) { ... }` when used; use-case signatures should accept the protocol type when they only need protocol methods, not the full concrete interface). Aggregator builds one ctx object and passes it to all feature binders - **App bootstrap** — Each app calls `bindAll()` from a server entry point (page server component, route handler) before resolving any feature controller. The dispatcher is idempotent -- **Instrumentation lives in `core-shared/instrumentation/`** — Three interfaces (`ITracer`, `ILogger`, `IMetrics`), three implementation pairs (`Noop*`, `Otel*`, and `Recording*` from `core-testing`). The OTel SDK is the substrate; Sentry is wired as the exporter via `@sentry/opentelemetry`. Feature packages MUST NOT import `@opentelemetry/sdk-*` or `@sentry/*` directly (R40 + R52, ESLint-enforced); the vendor-neutral `@opentelemetry/api` family is the import surface for advanced cases (ADR-017) -- **Spans + capture composed at DI bind time** — Use cases + controllers wrapped via `withSpan(tracer, spanOpts, withCapture(logger, tags, factory(deps)))` inside `bind-production` / `bind-dev-seed`. `withSpan` is outermost so an errored span's timing reflects the capture-and-rethrow. Repository methods are different — they call `this.tracer.startSpan(...)` and `this.logger.captureException(...)` inline per method because they own per-call attributes (R41, R42) -- **Capture at throw sites only, with double-report guard** — Repos capture infra errors inline; use cases + controllers capture via `withCapture` at bind time; `defineErrorMiddleware` never captures (R43, R44). Each error gets a non-enumerable `__sentryReported` flag the first time it's captured; `withCapture`, `OtelLogger`, and `RecordingLogger` all bail if the flag is set, so a bubbled error surfaces exactly once with the inner-most layer's tags (helper at `core-shared/instrumentation/reported-flag.ts`) -- **PII handling is non-negotiable** — `sendDefaultPii: false` everywhere (R31, CI grep gate); replay default-masks all text/inputs/media (R34, R35, allowlist starts empty); `setUser({ id })` only — no email/username (R36); server-side PII scrubbing happens at the OTel processor layer (`PiiScrubSpanProcessor` + `PiiScrubLogRecordProcessor`) before any exporter sees the data (R32, R33, ADR-017 §7) +- **Instrumentation lives in `core-shared/instrumentation/`** — Three interfaces (`ITracer`, `ILogger`, `IMetrics`), three implementation pairs (`Noop*`, `Otel*`, and `Recording*` from `core-testing`). The OTel SDK is the substrate; Sentry is wired as the exporter via `@sentry/opentelemetry`. Feature packages MUST NOT import `@opentelemetry/sdk-*` or `@sentry/*` directly (ESLint-enforced); the vendor-neutral `@opentelemetry/api` family is the import surface for advanced cases (ADR-017) +- **Spans + capture composed at DI bind time** — Use cases + controllers wrapped via `withSpan(tracer, spanOpts, withCapture(logger, tags, factory(deps)))` inside `bind-production` / `bind-dev-seed`. `withSpan` is outermost so an errored span's timing reflects the capture-and-rethrow. Repository methods are different — they call `this.tracer.startSpan(...)` and `this.logger.captureException(...)` inline per method because they own per-call attributes +- **Capture at throw sites only, with double-report guard** — Repos capture infra errors inline; use cases + controllers capture via `withCapture` at bind time; `defineErrorMiddleware` never captures. Each error gets a non-enumerable `__sentryReported` flag the first time it's captured; `withCapture`, `OtelLogger`, and `RecordingLogger` all bail if the flag is set, so a bubbled error surfaces exactly once with the inner-most layer's tags (helper at `core-shared/instrumentation/reported-flag.ts`) +- **PII handling is non-negotiable** — `sendDefaultPii: false` everywhere (CI grep gate); replay default-masks all text/inputs/media (allowlist starts empty); `setUser({ id })` only — no email/username; server-side PII scrubbing happens at the OTel processor layer (`PiiScrubSpanProcessor` + `PiiScrubLogRecordProcessor`) before any exporter sees the data (ADR-017 §7) - **Three apps, three Sentry projects** — `WEB_NEXT_SENTRY_DSN`, `CMS_SENTRY_DSN`, `WEB_TANSTACK_SENTRY_DSN`. Browser DSNs use `NEXT_PUBLIC_` (web-next) and `VITE_` (web-tanstack) prefixes - **Instrumentation binding is orthogonal to repo binding** — `bindAll()`'s Rule 0 (DSN → OTel+Sentry vs Noop) is independent of `USE_DEV_SEED` / `NODE_ENV`. Run `pnpm dev` with `WEB_NEXT_SENTRY_DSN` set to test the integration locally - **Cross-feature events go through `IEventBus` (E0)** — In-feature reactions are direct use-case calls, not bus publishes. The bus is for _crossing_ feature boundaries (e.g. `auth` → `marketing-pages` welcome email) diff --git a/README.md b/README.md index 6e163ea..e0c68db 100644 --- a/README.md +++ b/README.md @@ -35,7 +35,7 @@ docker compose up -d # Start PostgreSQL ## Scaffolding ```bash -pnpm turbo gen feature # Lazar-conformant feature (manifest + contracts + tests) +pnpm turbo gen feature # Scaffold a feature (manifest + contracts + tests) pnpm turbo gen event # Event contract or handler (requires gen core-package events) pnpm turbo gen job # Background job pnpm turbo gen realtime # Realtime channel (requires gen core-package realtime) diff --git a/docs/guides/adding-a-feature.md b/docs/guides/adding-a-feature.md index 74c525c..8af4a8b 100644 --- a/docs/guides/adding-a-feature.md +++ b/docs/guides/adding-a-feature.md @@ -5,7 +5,7 @@ tRPC router, CMS collection, DI container, and query builders — all owned by one package under `packages//`. > **Prefer the generator.** `pnpm turbo gen feature` produces a -> Lazar-conformant single-entity / single-use-case package matching the +> A single-entity / single-use-case package matching the > `navigation` reference shape (DI, tRPC router with tests, span + capture > sandwich, dev seed, contract suite). See > [Scaffolding a Feature](./scaffolding-a-feature.md). Use this guide when @@ -44,20 +44,20 @@ For the fast path, run `pnpm turbo gen feature ` — the generator emits t Every feature package owns: -| Layer | What lives there | -|---|---| -| `entities/models/` | Zod schemas + inferred TypeScript types | -| `entities/errors/` | Domain error classes (`this.name` required); `common.ts` for `InputParseError` | -| `application/repositories/` | Repository interface (no implementation) | -| `application/use-cases/` | One factory per operation; owns `xInputSchema`, `xOutputSchema`, and `xOutputSchema.parse()` | -| `infrastructure/repositories/` | Real (`.repository.ts`) and mock (`.repository.mock.ts`) siblings | -| `interface-adapters/controllers/` | One factory per use case; accepts `unknown`, calls `safeParse`, runs presenter | -| `di/` | `symbols.ts` + `module.ts` + `container.ts` + `bind-production.ts` | -| `integrations/api/` | `procedures.ts` (feature error map) + `router.ts` (uses `xProcedure.input(xInputSchema)`) | -| `integrations/cms/` | Payload collection/global configs | -| `ui/` | Query builders and future React components (behind `./ui` subpath) | -| `__factories__/` | Test data factories | -| `__contracts__/` | Contract suites shared by mock and real repository tests | +| Layer | What lives there | +| --------------------------------- | -------------------------------------------------------------------------------------------- | +| `entities/models/` | Zod schemas + inferred TypeScript types | +| `entities/errors/` | Domain error classes (`this.name` required); `common.ts` for `InputParseError` | +| `application/repositories/` | Repository interface (no implementation) | +| `application/use-cases/` | One factory per operation; owns `xInputSchema`, `xOutputSchema`, and `xOutputSchema.parse()` | +| `infrastructure/repositories/` | Real (`.repository.ts`) and mock (`.repository.mock.ts`) siblings | +| `interface-adapters/controllers/` | One factory per use case; accepts `unknown`, calls `safeParse`, runs presenter | +| `di/` | `symbols.ts` + `module.ts` + `container.ts` + `bind-production.ts` | +| `integrations/api/` | `procedures.ts` (feature error map) + `router.ts` (uses `xProcedure.input(xInputSchema)`) | +| `integrations/cms/` | Payload collection/global configs | +| `ui/` | Query builders and future React components (behind `./ui` subpath) | +| `__factories__/` | Test data factories | +| `__contracts__/` | Contract suites shared by mock and real repository tests | The walkthrough below builds a minimal `comments` feature from scratch. All concrete code mirrors the `blog` package (the most fully developed @@ -108,7 +108,7 @@ packages/comments/ api/ procedures.ts # commentsProcedure with feature error map router.ts # commentsProcedure.input(xInputSchema) - router.test.ts # includes R26 error-mapping assertions + router.test.ts # includes error-mapping assertions index.ts cms/ collections/ @@ -245,7 +245,13 @@ describe("commentSchema", () => { it("rejects an empty body", () => { expect(() => - commentSchema.parse({ id: "c-1", articleId: "a-1", body: "", authorId: "u-1", createdAt: new Date() }), + commentSchema.parse({ + id: "c-1", + articleId: "a-1", + body: "", + authorId: "u-1", + createdAt: new Date(), + }), ).toThrow(); }); }); @@ -285,7 +291,7 @@ pnpm test --filter @repo/comments -- comment.test.ts # GREEN export class CommentNotFoundError extends Error { constructor(message = "Comment not found", options?: ErrorOptions) { super(message, options); - this.name = "CommentNotFoundError"; // required — R6 + this.name = "CommentNotFoundError"; // required — R6 } } ``` @@ -295,7 +301,7 @@ export class CommentNotFoundError extends Error { export class InputParseError extends Error { constructor(message: string, options?: ErrorOptions) { super(message, options); - this.name = "InputParseError"; // required — R6 + this.name = "InputParseError"; // required — R6 } } ``` @@ -364,6 +370,7 @@ export const commentFactory = defineFactory(({ sequence }) => ({ ### Step 9: Use case — factory function with input/output schemas (RED → GREEN) Every use case exports: + - `xInputSchema` — a `z.ZodObject` with `.strict()` (use `z.object({}).strict()` for void inputs) - `xOutputSchema` — for non-void use cases - `XInput` / `XOutput` types @@ -404,14 +411,16 @@ describe("getCommentsUseCase", () => { }); }); -// R25 — output validation -describe("getCommentsUseCase output validation (R25)", () => { +// output validation +describe("getCommentsUseCase output validation", () => { it("throws ZodError when the repository returns malformed data", async () => { const repo = new MockCommentsRepository(); (repo as unknown as { _comments: unknown[] })._comments.push({ id: 123 }); const useCase = getCommentsUseCase(repo); - await expect(useCase({ articleId: "a-1" })).rejects.toBeInstanceOf(ZodError); + await expect(useCase({ articleId: "a-1" })).rejects.toBeInstanceOf( + ZodError, + ); }); it("exports getCommentsOutputSchema that validates Comment[]", () => { @@ -448,7 +457,9 @@ export type IGetCommentsUseCase = ReturnType; export const getCommentsUseCase = (commentsRepository: ICommentsRepository) => async (input: GetCommentsInput): Promise => { - const result = await commentsRepository.getCommentsForArticle(input.articleId); + const result = await commentsRepository.getCommentsForArticle( + input.articleId, + ); return getCommentsOutputSchema.parse(result); }; ``` @@ -586,7 +597,9 @@ describe("getCommentsController", () => { it("throws InputParseError on unknown extra fields (strict)", async () => { const repo = new MockCommentsRepository(); const ctrl = getCommentsController(getCommentsUseCase(repo)); - await expect(ctrl({ articleId: "a-1", extra: true })).rejects.toBeInstanceOf(InputParseError); + await expect( + ctrl({ articleId: "a-1", extra: true }), + ).rejects.toBeInstanceOf(InputParseError); }); }); ``` @@ -617,7 +630,9 @@ export const getCommentsController = async (input: unknown): Promise> => { const parsed = getCommentsInputSchema.safeParse(input); if (!parsed.success) { - throw new InputParseError("Invalid get-comments input", { cause: parsed.error }); + throw new InputParseError("Invalid get-comments input", { + cause: parsed.error, + }); } const result = await getCommentsUseCase(parsed.data); return presenter(result); @@ -659,17 +674,27 @@ import { import { COMMENTS_SYMBOLS } from "./symbols"; export const CommentsModule = new ContainerModule((bind: interfaces.Bind) => { - bind(COMMENTS_SYMBOLS.ICommentsRepository).to(MockCommentsRepository); + bind(COMMENTS_SYMBOLS.ICommentsRepository).to( + MockCommentsRepository, + ); - bind(COMMENTS_SYMBOLS.IGetCommentsUseCase).toDynamicValue((ctx) => + bind( + COMMENTS_SYMBOLS.IGetCommentsUseCase, + ).toDynamicValue((ctx) => getCommentsUseCase( - ctx.container.get(COMMENTS_SYMBOLS.ICommentsRepository), + ctx.container.get( + COMMENTS_SYMBOLS.ICommentsRepository, + ), ), ); - bind(COMMENTS_SYMBOLS.IGetCommentsController).toDynamicValue((ctx) => + bind( + COMMENTS_SYMBOLS.IGetCommentsController, + ).toDynamicValue((ctx) => getCommentsController( - ctx.container.get(COMMENTS_SYMBOLS.IGetCommentsUseCase), + ctx.container.get( + COMMENTS_SYMBOLS.IGetCommentsUseCase, + ), ), ); }); @@ -695,15 +720,21 @@ import { COMMENTS_SYMBOLS } from "@/di/symbols"; describe("commentsContainer", () => { it("resolves ICommentsRepository", () => { - expect(commentsContainer.get(COMMENTS_SYMBOLS.ICommentsRepository)).toBeDefined(); + expect( + commentsContainer.get(COMMENTS_SYMBOLS.ICommentsRepository), + ).toBeDefined(); }); it("resolves IGetCommentsUseCase", () => { - expect(commentsContainer.get(COMMENTS_SYMBOLS.IGetCommentsUseCase)).toBeDefined(); + expect( + commentsContainer.get(COMMENTS_SYMBOLS.IGetCommentsUseCase), + ).toBeDefined(); }); it("resolves IGetCommentsController", () => { - expect(commentsContainer.get(COMMENTS_SYMBOLS.IGetCommentsController)).toBeDefined(); + expect( + commentsContainer.get(COMMENTS_SYMBOLS.IGetCommentsController), + ).toBeDefined(); }); }); ``` @@ -733,9 +764,10 @@ export const commentsProcedure = t.procedure.use( --- -### Step 14: tRPC router (RED → GREEN, includes R26 error-mapping test) +### Step 14: tRPC router (RED → GREEN, includes error-mapping test) The router: + - uses `commentsProcedure` (never bare `publicProcedure`) - calls `.input(xInputSchema)` importing from the use-case file — never redefines the schema inline - resolves controllers from the container @@ -758,7 +790,9 @@ describe("commentsRouter", () => { }); it("exposes getComments procedure", () => { - expect(Object.keys(commentsRouter._def.procedures)).toContain("getComments"); + expect(Object.keys(commentsRouter._def.procedures)).toContain( + "getComments", + ); }); it("getComments returns empty array by default", async () => { @@ -767,8 +801,8 @@ describe("commentsRouter", () => { }); }); -// R26 — error mapping -describe("commentsRouter (R26 error mapping)", () => { +// error mapping +describe("commentsRouter error mapping", () => { beforeEach(() => { commentsContainer.unbindAll(); commentsContainer.load(CommentsModule); @@ -871,7 +905,11 @@ export class CommentsRepository implements ICommentsRepository { async getComment(id: string): Promise { const payload = await getPayload({ config: this.config }); try { - const doc = await payload.findByID({ collection: "comments", id, overrideAccess: true }); + const doc = await payload.findByID({ + collection: "comments", + id, + overrideAccess: true, + }); return mapDoc(doc as PayloadCommentDoc); } catch { return undefined; @@ -892,7 +930,11 @@ export class CommentsRepository implements ICommentsRepository { const payload = await getPayload({ config: this.config }); const created = await payload.create({ collection: "comments", - data: { articleId: input.articleId, body: input.body, author: input.authorId } as never, + data: { + articleId: input.articleId, + body: input.body, + author: input.authorId, + } as never, overrideAccess: true, }); return mapDoc(created as PayloadCommentDoc); @@ -917,13 +959,17 @@ describe("CommentsRepository", () => { const store = new Map>(); const stub = { findByID: vi.fn(async ({ id }: { id: string }) => store.get(id)), - find: vi.fn(async ({ where }: { where?: { articleId?: { equals: string } } }) => { - let docs = Array.from(store.values()); - if (where?.articleId) { - docs = docs.filter((d) => d["articleId"] === where.articleId?.equals); - } - return { docs }; - }), + find: vi.fn( + async ({ where }: { where?: { articleId?: { equals: string } } }) => { + let docs = Array.from(store.values()); + if (where?.articleId) { + docs = docs.filter( + (d) => d["articleId"] === where.articleId?.equals, + ); + } + return { docs }; + }, + ), create: vi.fn(async ({ data }: { data: Record }) => { const doc = { id: `stub-${store.size + 1}`, ...data }; store.set(String(doc.id), doc); @@ -996,7 +1042,12 @@ export const comments: CollectionConfig = { fields: [ { name: "articleId", type: "text", required: true }, { name: "body", type: "textarea", required: true }, - { name: "author", type: "relationship", relationTo: "users", required: true }, + { + name: "author", + type: "relationship", + relationTo: "users", + required: true, + }, ], }; ``` @@ -1089,7 +1140,9 @@ Add path aliases to `tsconfig.base.json`: "@repo/comments/api": ["packages/comments/src/integrations/api/index.ts"], "@repo/comments/ui": ["packages/comments/src/ui/index.ts"], "@repo/comments/cms": ["packages/comments/src/integrations/cms/index.ts"], - "@repo/comments/di/bind-production": ["packages/comments/src/di/bind-production.ts"] + "@repo/comments/di/bind-production": [ + "packages/comments/src/di/bind-production.ts" + ] } } } @@ -1131,14 +1184,14 @@ All must pass before shipping. ## 4. Configuration Checklist -| File | Key items | -|---|---| -| `package.json` | `"type": "module"`; exports map with `.`, `./ui`, `./api`, `./cms`, `./di/bind-production`; `@repo/core-shared`, `inversify`, `zod`, `payload` in deps | -| `tsconfig.json` | `"rootDir": "."` (covers both `src/` and `tests/`); `"outDir": "dist"` | -| `vitest.config.ts` | `resolve.alias: { "@": path.resolve(__dirname, "./src") }` | -| `eslint.config.js` | extends `@repo/core-eslint`; tag set to `"feature"` in Turborepo `turbo.json` | -| `tsconfig.base.json` | path aliases for every subpath export | -| `turbo.json` | feature package must appear (or be glob-matched) in the workspace graph | +| File | Key items | +| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `package.json` | `"type": "module"`; exports map with `.`, `./ui`, `./api`, `./cms`, `./di/bind-production`; `@repo/core-shared`, `inversify`, `zod`, `payload` in deps | +| `tsconfig.json` | `"rootDir": "."` (covers both `src/` and `tests/`); `"outDir": "dist"` | +| `vitest.config.ts` | `resolve.alias: { "@": path.resolve(__dirname, "./src") }` | +| `eslint.config.js` | extends `@repo/core-eslint`; tag set to `"feature"` in Turborepo `turbo.json` | +| `tsconfig.base.json` | path aliases for every subpath export | +| `turbo.json` | feature package must appear (or be glob-matched) in the workspace graph | --- @@ -1168,7 +1221,7 @@ All must pass before shipping. `Promise>`. Identity (`return value`) is fine, but the function must exist. Skipping it makes adding a view transform later a structural change instead of a one-line edit - (ADR-013 R11). + (ADR-013). 5. **Adding feature error classes to `core-shared`.** `core-shared` must stay boundary-clean — it provides `defineErrorMiddleware` but knows @@ -1194,22 +1247,16 @@ All must pass before shipping. ## 6. Cross-References -- **ADR-012** (`docs/decisions/adr-012-lazar-conformance.md`) — factory-function +- **ADR-012** (`docs/decisions/adr-012-feature-conventions.md`) — factory-function use cases and controllers, entity layout, file naming, one-controller-per-use-case, `.toDynamicValue()` DI bindings, direct injection in tests. - **ADR-013** (`docs/decisions/adr-013-input-output-unification.md`) — use-case file as single source for `xInputSchema` + `xOutputSchema`; presenter pattern; per-feature `procedures.ts` error map; public surface split (`./` vs `./ui`). -- **Refactor log — Plan 8** (`docs/superpowers/refactor-logs/2026-05-05-lazar-pattern-conformance.md`) — - file-by-file inventory of every rename, split, and pattern change applied - to all existing features. -- **Refactor log — Plan 9** (`docs/superpowers/refactor-logs/2026-05-06-input-output-unification.md`) — - inventory of schema additions, presenter additions, `procedures.ts` additions, - and `./ui` subpath additions across all 5 features. - **CLAUDE.md** (root) — Key Conventions section is the quick-reference summary; this guide is the authoritative walkthrough. - **Architecture overview** (`docs/architecture/overview.md`) — canonical data-flow diagram showing the full request path from React component through tRPC, controller, use case, repository, and back. - **TDD Workflow** (`docs/guides/tdd-workflow.md`) — required reading on - RED → GREEN discipline, direct factory injection, and R25/R26 test obligations. + RED → GREEN discipline, direct factory injection, and test obligations per layer. diff --git a/docs/guides/runbook.md b/docs/guides/runbook.md index 8c6743a..7b5a58c 100644 --- a/docs/guides/runbook.md +++ b/docs/guides/runbook.md @@ -165,7 +165,7 @@ This emits: - `packages//src/feature.manifest.ts` — the conformance manifest (use cases, audits, publishes, consumes) - `packages//src/di/bind-production.ts` with `assertFeatureConformance(...)` at the tail (refuses to boot on drift) -- Mock repository, factory, seed, entity, use-case, controller, tests — full Lazar-conformant shape +- Mock repository, factory, seed, entity, use-case, controller, tests — full canonical shape - `packages//src/index.ts` exports After scaffolding, the four-step ordering for any new use case: diff --git a/docs/guides/scaffolding-a-feature.md b/docs/guides/scaffolding-a-feature.md index 8786747..a5b8bfc 100644 --- a/docs/guides/scaffolding-a-feature.md +++ b/docs/guides/scaffolding-a-feature.md @@ -1,6 +1,6 @@ # Scaffolding a feature -`turbo gen feature` produces a Lazar-conformant feature package under +`turbo gen feature` produces a feature package under `packages//` matching the shape of the reference `navigation` feature. ## Invoking the generator @@ -18,11 +18,11 @@ Non-interactive (positional bypass — order matches the prompts in pnpm turbo gen feature --args ``` -| Position | Prompt | Example | Conventions | -|---|---|---|---| -| `` | Feature package name | `widgets` | `kebab-case`, becomes `@repo/` and `packages//` | -| `` | Entity name | `Widget` | `PascalCase` singular, drives class/symbol/use-case names | -| `` | Entity plural slug | `widgets` | `kebab-case`, used for the future Payload collection slug | +| Position | Prompt | Example | Conventions | +| ------------------- | -------------------- | --------- | ----------------------------------------------------------- | +| `` | Feature package name | `widgets` | `kebab-case`, becomes `@repo/` and `packages//` | +| `` | Entity name | `Widget` | `PascalCase` singular, drives class/symbol/use-case names | +| `` | Entity plural slug | `widgets` | `kebab-case`, used for the future Payload collection slug | Example end-to-end: @@ -60,7 +60,7 @@ See `docs/guides/conformance-quickref.md` for the manifest field reference. - DI: `symbols.ts`, `module.ts`, `container.ts`, plus `bind-production.ts` and `bind-dev-seed.ts` that compose `withSpan(tracer, opts, withCapture(logger, tags, factory(deps)))` at - bind time (post-R44 sandwich pattern) + bind time (span + capture sandwich pattern) - tRPC integration: `procedures.ts` (feature-scoped error middleware) and `router.ts` exposing `get` with full router tests including `BAD_REQUEST` / `NOT_FOUND` mapping @@ -123,8 +123,8 @@ The realtime generators insert at three additional fixed `// ` a schemas-in-use-case, three binding modes per feature, span + capture sandwich) - `packages/navigation/AGENTS.md` — canonical reference shape the templates mirror - `docs/architecture/vertical-feature-spec.md` — design rationale for the layout -- `docs/decisions/adr-012-lazar-conformance.md` — file naming + factory pattern +- `docs/decisions/adr-012-feature-conventions.md` — file naming + factory pattern - `docs/decisions/adr-013-input-output-unification.md` — schemas-in-use-case + presenter -- `docs/decisions/adr-014-instrumentation-sentry.md` — span + capture wiring (R41–R44) +- `docs/decisions/adr-014-instrumentation-sentry.md` — span + capture wiring - `docs/decisions/adr-015-events-and-jobs.md` — cross-feature events + background jobs - `docs/decisions/adr-016-realtime-layer.md` — Socket.IO realtime channels + handlers diff --git a/docs/guides/tdd-workflow.md b/docs/guides/tdd-workflow.md index 265ab34..4686950 100644 --- a/docs/guides/tdd-workflow.md +++ b/docs/guides/tdd-workflow.md @@ -24,7 +24,9 @@ describe("getArticleBySlugController", () => { it("returns the article when the slug exists", async () => { const repo = new MockArticlesRepository(); articleFactory.reset(); - await repo.createArticle(articleFactory.build({ slug: "hello-world", authorId: "u1" })); + await repo.createArticle( + articleFactory.build({ slug: "hello-world", authorId: "u1" }), + ); const useCase = getArticleBySlugUseCase(repo); const controller = getArticleBySlugController(useCase); @@ -38,9 +40,9 @@ describe("getArticleBySlugController", () => { const useCase = getArticleBySlugUseCase(repo); const controller = getArticleBySlugController(useCase); - await expect( - controller({ slug: "no-such-slug" }), - ).rejects.toBeInstanceOf(ArticleNotFoundError); + await expect(controller({ slug: "no-such-slug" })).rejects.toBeInstanceOf( + ArticleNotFoundError, + ); }); }); ``` @@ -60,23 +62,31 @@ pnpm test --filter @repo/blog -- get-article-by-slug.controller.test.ts ```typescript // packages/blog/src/interface-adapters/controllers/get-article-by-slug.controller.ts -import type { IGetArticleBySlugUseCase, GetArticleBySlugOutput } from - "../application/use-cases/get-article-by-slug.use-case"; +import type { + IGetArticleBySlugUseCase, + GetArticleBySlugOutput, +} from "../application/use-cases/get-article-by-slug.use-case"; import { getArticleBySlugInputSchema } from "../application/use-cases/get-article-by-slug.use-case"; import { InputParseError } from "../entities/errors/common"; -function presenter(value: GetArticleBySlugOutput) { return value; } +function presenter(value: GetArticleBySlugOutput) { + return value; +} export function getArticleBySlugController(useCase: IGetArticleBySlugUseCase) { return async (input: unknown): Promise> => { const parsed = getArticleBySlugInputSchema.safeParse(input); if (!parsed.success) - throw new InputParseError("Invalid get-article-by-slug input", { cause: parsed.error }); + throw new InputParseError("Invalid get-article-by-slug input", { + cause: parsed.error, + }); return presenter(await useCase(parsed.data)); }; } -export type IGetArticleBySlugController = ReturnType; +export type IGetArticleBySlugController = ReturnType< + typeof getArticleBySlugController +>; ``` **Run again — confirm GREEN:** @@ -140,6 +150,7 @@ describe("getArticleBySlugController", () => { ``` Rules: + - `describe` names the class or function under test — not the file. - `it` uses active voice: `returns`, `throws`, `filters`, `creates`. - Conditions go after `when`: `it("returns undefined when slug is missing")`. @@ -232,15 +243,15 @@ The rule: mock the thing your layer depends on, never the thing under test. ## 5. Test Pyramid for This Monorepo -| Layer | Tool | Target ratio | Location pattern | -|---|---|---|---| -| Entity (schema, type guards) | Vitest | Highest — every entity | `src/entities/models/*.test.ts` | -| Use case (business logic) | Vitest + mock repo | High — every use case | `src/application/use-cases/*.test.ts` | -| Controller (input parsing) | Vitest + mock repo | High — every controller | `src/interface-adapters/controllers/*.test.ts` | -| Repository contract | Vitest + contract suite | One per impl | `src/infrastructure/repositories/*.test.ts` | -| Feature integration (tRPC) | Vitest + createCaller | Medium — happy path + error | `src/integrations/api/router.test.ts` | -| Component | Vitest + RTL | Per UI component | `src/ui/**/*.test.tsx` | -| E2E | Playwright | Few — smoke + critical flows | `apps/web-next/e2e/*.spec.ts` | +| Layer | Tool | Target ratio | Location pattern | +| ---------------------------- | ----------------------- | ---------------------------- | ---------------------------------------------- | +| Entity (schema, type guards) | Vitest | Highest — every entity | `src/entities/models/*.test.ts` | +| Use case (business logic) | Vitest + mock repo | High — every use case | `src/application/use-cases/*.test.ts` | +| Controller (input parsing) | Vitest + mock repo | High — every controller | `src/interface-adapters/controllers/*.test.ts` | +| Repository contract | Vitest + contract suite | One per impl | `src/infrastructure/repositories/*.test.ts` | +| Feature integration (tRPC) | Vitest + createCaller | Medium — happy path + error | `src/integrations/api/router.test.ts` | +| Component | Vitest + RTL | Per UI component | `src/ui/**/*.test.tsx` | +| E2E | Playwright | Few — smoke + critical flows | `apps/web-next/e2e/*.spec.ts` | Entities and use cases have the highest ratio because they encode business rules. E2E tests have the lowest ratio because they are slow and test the full stack. @@ -260,13 +271,13 @@ Entities and use cases have the highest ratio because they encode business rules ## 7. Coverage Targets -| Scope | Statements | Branches | Functions | Lines | -|---|---|---|---|---| -| Baseline (all packages) | 80% | 75% | 80% | 80% | -| Entities | 100% | 100% | 100% | 100% | -| Use cases | 100% | 100% | 100% | 100% | -| Controllers | 100% | 100% | 100% | 100% | -| Infrastructure (repos) | 80% | 75% | 80% | 80% | +| Scope | Statements | Branches | Functions | Lines | +| ----------------------- | ---------- | -------- | --------- | ----- | +| Baseline (all packages) | 80% | 75% | 80% | 80% | +| Entities | 100% | 100% | 100% | 100% | +| Use cases | 100% | 100% | 100% | 100% | +| Controllers | 100% | 100% | 100% | 100% | +| Infrastructure (repos) | 80% | 75% | 80% | 80% | **Inspect coverage locally:** @@ -339,21 +350,24 @@ The `defineFactory` function lives in `packages/core-testing/src/factory/define- --- -## 9. Output Validation Tests (R25) +## 9. Output Validation Tests -Every **non-void** use case must have an R25 test that injects a malformed mock response and asserts the use case throws `ZodError`. This verifies that the `xOutputSchema.parse(result)` at the end of each use case actually guards against misbehaving repositories. +Every **non-void** use case must have an output-validation test that injects a malformed mock response and asserts the use case throws `ZodError`. This verifies that the `xOutputSchema.parse(result)` at the end of each use case actually guards against misbehaving repositories. -**Void use cases are exempt:** `signOutUseCase`, `deleteMediaUseCase`, and any future use case returning `Promise` skip R25 — they have no output schema. +**Void use cases are exempt:** `signOutUseCase`, `deleteMediaUseCase`, and any future use case returning `Promise` — they have no output schema. **Pattern A — reach into `_articles` (or equivalent backing array) when the typed API prevents you from inserting bad data:** ```typescript // packages/blog/src/application/use-cases/get-articles.use-case.test.ts import { ZodError } from "zod"; -import { getArticlesUseCase, getArticlesOutputSchema } from "@/application/use-cases/get-articles.use-case"; +import { + getArticlesUseCase, + getArticlesOutputSchema, +} from "@/application/use-cases/get-articles.use-case"; import { MockArticlesRepository } from "@/infrastructure/repositories/articles.repository.mock"; -describe("getArticlesUseCase output validation (R25)", () => { +describe("getArticlesUseCase output validation", () => { it("throws when the repository returns a malformed article", async () => { const repo = new MockArticlesRepository(); // bypass typed createArticle by reaching into the backing array directly @@ -376,7 +390,7 @@ describe("getArticlesUseCase output validation (R25)", () => { // packages/auth/src/application/use-cases/sign-in.use-case.test.ts import type { IAuthenticationService } from "@/application/services/authentication.service.interface"; -describe("signInUseCase output validation (R25)", () => { +describe("signInUseCase output validation", () => { it("throws when authenticationService returns a malformed session", async () => { const users = new MockUsersRepository([]); await users.createUser(userFactory.build({ username: "alice" })); @@ -387,16 +401,18 @@ describe("signInUseCase output validation (R25)", () => { } as unknown as IAuthenticationService; const useCase = signInUseCase(users, auth); - await expect(useCase({ username: "alice", password: "x" })).rejects.toBeInstanceOf(ZodError); + await expect( + useCase({ username: "alice", password: "x" }), + ).rejects.toBeInstanceOf(ZodError); }); }); ``` -Group R25 tests in a separate `describe` block labelled `" output validation (R25)"` so they are easy to grep. +Group output-validation tests in a separate `describe` block labelled `" output validation"` so they are easy to grep. --- -## 10. Router Error-Mapping Tests (R26) +## 10. Router Error-Mapping Tests Each feature's `router.test.ts` must assert that thrown domain errors become `TRPCError` with the correct code. The router test uses `xRouter.createCaller({})` and calls real procedures backed by the default mock bindings. @@ -410,7 +426,7 @@ import { blogContainer } from "@/di/container"; import { BlogModule } from "@/di/module"; import { blogRouter } from "@/integrations/api/router"; -describe("blogRouter (R26 error mapping)", () => { +describe("blogRouter error mapping", () => { beforeEach(() => { blogContainer.unbindAll(); blogContainer.load(BlogModule); @@ -450,10 +466,14 @@ For features where a domain error can only be triggered by an empty store (e.g. it("translates HeaderNotFoundError → NOT_FOUND", async () => { @injectable() class NullHeaderRepository implements IHeaderRepository { - async getHeader() { return undefined; } + async getHeader() { + return undefined; + } } navigationContainer.unbind(NAVIGATION_SYMBOLS.IHeaderRepository); - navigationContainer.bind(NAVIGATION_SYMBOLS.IHeaderRepository).to(NullHeaderRepository); + navigationContainer + .bind(NAVIGATION_SYMBOLS.IHeaderRepository) + .to(NullHeaderRepository); const caller = navigationRouter.createCaller({}); try { @@ -470,7 +490,7 @@ Every feature needs at least one `NOT_FOUND` (or domain-error) test and one `BAD --- -## 11. Presenter Shape Tests (R27/R28) +## 11. Presenter Shape Tests When a controller's presenter **reshapes** the use-case output (rather than returning it unchanged), the controller test must assert the **view shape** — not the full use-case output. @@ -485,13 +505,19 @@ describe("signInController", () => { const users = new MockUsersRepository([]); const auth = new MockAuthenticationService(users); await users.createUser( - userFactory.build({ username: "alice", passwordHash: "hashed_testpassword" }), + userFactory.build({ + username: "alice", + passwordHash: "hashed_testpassword", + }), ); const useCase = signInUseCase(users, auth); const controller = signInController(useCase); - const result = await controller({ username: "alice", password: "testpassword" }); + const result = await controller({ + username: "alice", + password: "testpassword", + }); // assert the VIEW shape (cookie), not the use-case output ({ session, cookie }) expect(result.name).toBe("session"); expect(result.value).toBeTruthy(); @@ -501,7 +527,7 @@ describe("signInController", () => { **Identity presenters skip this.** Blog, marketing-pages, navigation, and media controllers all use identity presenters (`return value`). Their controller tests assert on the same fields the use case would return — that is fine, because the presenter does not transform. -**Rule of thumb:** if `presenter(value)` does anything other than `return value`, write a test that cannot pass by accident — assert a field that only exists on the *view*, not on `XOutput`. +**Rule of thumb:** if `presenter(value)` does anything other than `return value`, write a test that cannot pass by accident — assert a field that only exists on the _view_, not on `XOutput`. Void controllers (`signOutController`, `deleteMediaController`) return `Promise` and have no presenter — no view-shape test applies. @@ -580,6 +606,7 @@ describe("CommentsRepository", () => { The `buildSubject` pattern ensures each `run()` call supplies a fresh instance — every contract `it()` starts with a clean repository. **File naming convention (post-Plan-8):** + - Mock implementation: `.repository.mock.ts` (not `mock-.repository.ts`) - Mock test: `.repository.mock.test.ts` - Real implementation: `.repository.ts` (no `payload-` prefix) @@ -655,12 +682,15 @@ E2E tests live in `apps/web-next/e2e/`. The `webServer` block in `apps/web-next/ --- -## Asserting spans and captures (Plan 10) +## Asserting spans and captures Use cases, controllers, and repositories emit OpenTelemetry-style spans through the `ITracer` interface. Repositories also call `logger.captureException` inline; use cases and controllers get capture composed in via `withCapture` at DI bind time. Tests that need to assert either inject `RecordingTracer` + `RecordingLogger`: ```ts -import { RecordingTracer, RecordingLogger } from "@repo/core-testing/instrumentation"; +import { + RecordingTracer, + RecordingLogger, +} from "@repo/core-testing/instrumentation"; import { withSpan, withCapture } from "@repo/core-shared/instrumentation"; import { MockArticlesRepository } from "@/infrastructure/repositories/articles.repository.mock"; import { getArticlesUseCase } from "@/application/use-cases/get-articles.use-case"; diff --git a/docs/guides/testing-strategy.md b/docs/guides/testing-strategy.md index bc83220..5cfc70a 100644 --- a/docs/guides/testing-strategy.md +++ b/docs/guides/testing-strategy.md @@ -2,23 +2,23 @@ A layered approach: direct factory injection + colocated unit tests + Playwright e2e. -For the *how* of TDD (red-green-refactor cycle, when to mock, what NOT to test), see [tdd-workflow.md](./tdd-workflow.md). This document covers test *placement* and infrastructure. +For the _how_ of TDD (red-green-refactor cycle, when to mock, what NOT to test), see [tdd-workflow.md](./tdd-workflow.md). This document covers test _placement_ and infrastructure. -For the full R25 / R26 / R27 / R28 patterns with worked examples, see [tdd-workflow.md §4 (mock decision tree)](./tdd-workflow.md). +For the full output-validation, error-mapping, and view-shape patterns with worked examples, see [tdd-workflow.md §4 (mock decision tree)](./tdd-workflow.md). -Related ADRs: [ADR-012](../decisions/adr-012-lazar-conformance.md) — Clean Architecture conformance; [ADR-013](../decisions/adr-013-input-output-unification.md) — input/output unification + presenter + error middleware. +Related ADRs: [ADR-012](../decisions/adr-012-feature-conventions.md) — Clean Architecture conformance; [ADR-013](../decisions/adr-013-input-output-unification.md) — input/output unification + presenter + error middleware. ## Test placement -| Level | Location | Tool | Example | -|---|---|---|---| -| **Unit (colocated)** | `packages//src/entities/models/.test.ts` | Vitest | Schema validation, type guards | -| **Use case** | `packages//src/application/use-cases/.use-case.test.ts` | Vitest | Direct factory injection + R25 output-validation | -| **Controller** | `packages//src/interface-adapters/controllers/.controller.test.ts` | Vitest | Direct factory injection + R10 input validation + R27/R28 view shape | -| **Repository contract** | `packages//src/infrastructure/repositories/.repository.test.ts` | Vitest + contract suite | Interface conformance | -| **Router (integration)** | `packages//src/integrations/api/router.test.ts` | Vitest + container | R26 domain → TRPCError mapping | -| **Feature level** | `packages//tests/.feature.test.ts` | Vitest | Cross-layer integration via direct injection | -| **E2E (app)** | `apps/web-next/e2e/.spec.ts` | Playwright | Full user flow across frontend + backend | +| Level | Location | Tool | Example | +| ------------------------ | --------------------------------------------------------------------------------- | ----------------------- | -------------------------------------------------------- | +| **Unit (colocated)** | `packages//src/entities/models/.test.ts` | Vitest | Schema validation, type guards | +| **Use case** | `packages//src/application/use-cases/.use-case.test.ts` | Vitest | Direct factory injection + output-validation | +| **Controller** | `packages//src/interface-adapters/controllers/.controller.test.ts` | Vitest | Direct factory injection + input validation + view shape | +| **Repository contract** | `packages//src/infrastructure/repositories/.repository.test.ts` | Vitest + contract suite | Interface conformance | +| **Router (integration)** | `packages//src/integrations/api/router.test.ts` | Vitest + container | Domain → TRPCError mapping | +| **Feature level** | `packages//tests/.feature.test.ts` | Vitest | Cross-layer integration via direct injection | +| **E2E (app)** | `apps/web-next/e2e/.spec.ts` | Playwright | Full user flow across frontend + backend | **Colocated vs feature-level:** Colocated tests (`*.test.ts` next to source) test isolated units. Feature-level tests (`tests/` folder) wire the full chain via direct injection and test interactions between layers. @@ -39,10 +39,14 @@ describe("getArticlesUseCase", () => { it("filters by status", async () => { const repo = new MockArticlesRepository(); articleFactory.reset(); - await repo.createArticle(articleFactory.build({ id: "1", status: "draft" })); - await repo.createArticle(articleFactory.build({ id: "2", status: "published" })); + await repo.createArticle( + articleFactory.build({ id: "1", status: "draft" }), + ); + await repo.createArticle( + articleFactory.build({ id: "2", status: "published" }), + ); - const useCase = getArticlesUseCase(repo); // direct injection + const useCase = getArticlesUseCase(repo); // direct injection const result = await useCase({ status: "published" }); expect(result).toHaveLength(1); }); @@ -63,10 +67,13 @@ describe("signInController", () => { const users = new MockUsersRepository([]); const auth = new MockAuthenticationService(users); const useCase = signInUseCase(users, auth); - const controller = signInController(useCase); // direct injection + const controller = signInController(useCase); // direct injection - const result = await controller({ username: "alice", password: "testpassword" }); - expect(result.name).toBe("session"); // presenter view shape (R27) + const result = await controller({ + username: "alice", + password: "testpassword", + }); + expect(result.name).toBe("session"); // presenter view shape expect(result.value).toBeTruthy(); }); }); @@ -86,10 +93,10 @@ import { blogContainer } from "@/di/container"; import { BlogModule } from "@/di/module"; import { blogRouter } from "@/integrations/api/router"; -describe("blogRouter (R26 error mapping)", () => { +describe("blogRouter error mapping", () => { beforeEach(() => { blogContainer.unbindAll(); - blogContainer.load(BlogModule); // loads default mock bindings + blogContainer.load(BlogModule); // loads default mock bindings }); afterEach(() => { @@ -98,10 +105,9 @@ describe("blogRouter (R26 error mapping)", () => { it("translates ArticleNotFoundError → NOT_FOUND", async () => { const caller = blogRouter.createCaller({}); - await expect(caller.articleBySlug({ slug: "missing" })) - .rejects.toSatisfy((e: unknown) => - e instanceof TRPCError && e.code === "NOT_FOUND" - ); + await expect(caller.articleBySlug({ slug: "missing" })).rejects.toSatisfy( + (e: unknown) => e instanceof TRPCError && e.code === "NOT_FOUND", + ); }); }); ``` @@ -111,7 +117,9 @@ When a test needs a specific repo behaviour at the router level, bind it directl ```typescript beforeEach(() => { blogContainer.unbindAll(); - blogContainer.bind(BLOG_SYMBOLS.IArticlesRepository).toConstantValue(new AlwaysEmptyRepo()); + blogContainer + .bind(BLOG_SYMBOLS.IArticlesRepository) + .toConstantValue(new AlwaysEmptyRepo()); }); ``` @@ -137,12 +145,13 @@ The mock repository satisfies the repository interface without touching Payload ### Option 2: Router-level — use the feature's DI container -When testing the tRPC router (R26 error-mapping, procedure wiring), bind a mock or stub repository through the feature container in `beforeEach`: +When testing the tRPC router (error-mapping, procedure wiring), bind a mock or stub repository through the feature container in `beforeEach`: ```typescript beforeEach(() => { blogContainer.unbindAll(); - blogContainer.bind(BLOG_SYMBOLS.IArticlesRepository) + blogContainer + .bind(BLOG_SYMBOLS.IArticlesRepository) .toConstantValue(new MockArticlesRepository()); }); ``` @@ -156,25 +165,25 @@ vi.mock("payload", () => ({ getPayload: vi.fn() })); Then provide a stub via `stubPayloadConfig` from `@repo/core-testing/payload` (see [tdd-workflow.md §4](./tdd-workflow.md) for the full contract-suite pattern). -## Test obligations per layer (Plan 9) +## Test obligations per layer -| Layer | Test type | Required by spec | Example | -|---|---|---|---| -| Entity | Schema validation | — | `articleSchema.safeParse(...)` → accepts valid / rejects invalid | -| Use case (input) | Behavior | — | factory injection; assert result shape and filtering | -| Use case (output, R25) | Runtime guarantee | R25 | inject malformed mock output → `.rejects.toBeInstanceOf(ZodError)` | -| Controller (input, R10) | Validation | R10 | `controller({} as unknown)` → `.rejects.toBeInstanceOf(InputParseError)` | -| Controller (presenter, R27/R28) | View shape | R27/R28 (when reshaping) | `expect(result.name).toBe("session")` (not `result.session`) | -| Repository contract | Interface conformance | — | run `defineContractSuite` against mock + real impl | -| Router (R26) | Domain → TRPCError | R26 | `xRouter.createCaller({}).x(...)` → assert `TRPCError.code` | -| Feature-level (`tests/`) | Cross-layer integration | — | wire the chain via direct injection (no container) | -| E2E | Full user flow | — | Playwright | +| Layer | Test type | Required by spec | Example | +| ------------------------ | ----------------------- | ---------------- | ------------------------------------------------------------------------ | +| Entity | Schema validation | — | `articleSchema.safeParse(...)` → accepts valid / rejects invalid | +| Use case (input) | Behavior | — | factory injection; assert result shape and filtering | +| Use case (output) | Runtime guarantee | — | inject malformed mock output → `.rejects.toBeInstanceOf(ZodError)` | +| Controller (input) | Validation | — | `controller({} as unknown)` → `.rejects.toBeInstanceOf(InputParseError)` | +| Controller (presenter) | View shape | when reshaping | `expect(result.name).toBe("session")` (not `result.session`) | +| Repository contract | Interface conformance | — | run `defineContractSuite` against mock + real impl | +| Router | Domain → TRPCError | — | `xRouter.createCaller({}).x(...)` → assert `TRPCError.code` | +| Feature-level (`tests/`) | Cross-layer integration | — | wire the chain via direct injection (no container) | +| E2E | Full user flow | — | Playwright | -**R25** — Every non-void use case ends with `xOutputSchema.parse(result)`. The R25 test proves this: inject a mock that returns a structurally invalid object and assert `ZodError` propagates. +**Output validation** — Every non-void use case ends with `xOutputSchema.parse(result)`. The test proves this: inject a mock that returns a structurally invalid object and assert `ZodError` propagates. -**R26** — Every feature has `procedures.ts` with a `defineErrorMiddleware` error map. The R26 test calls the tRPC procedure through `router.createCaller({})` and asserts the correct `TRPCError.code` (e.g. `NOT_FOUND`, `BAD_REQUEST`, `UNAUTHORIZED`). +**Error mapping** — Every feature has `procedures.ts` with a `defineErrorMiddleware` error map. The router test calls the tRPC procedure through `router.createCaller({})` and asserts the correct `TRPCError.code` (e.g. `NOT_FOUND`, `BAD_REQUEST`, `UNAUTHORIZED`). -**R27/R28** — Controllers that reshape the use-case output (e.g. auth controllers that return a cookie instead of the full session object) must have a test asserting the view shape — not the raw use-case output. +**View shape** — Controllers that reshape the use-case output (e.g. auth controllers that return a cookie instead of the full session object) must have a test asserting the view shape — not the raw use-case output. ## Vitest setup per package @@ -308,18 +317,17 @@ Root `turbo.json`: 3. **E2E tests** prove the app works end-to-end (minimal smoke specs initially) 4. **Per-feature containers** are used at the **router level**; use-case + controller tests inject mocks directly into the factory (no container) -## R49 / R50 — Instrumentation testing (Plan 10) +## Instrumentation testing -**R49 — No real Sentry in tests.** The `core-testing/setup/no-sentry.ts` guard mocks `@sentry/nextjs`, `@sentry/node`, and `@sentry/react` at the module level, so any code that imports them gets a no-op surface during vitest runs. Tests that want to assert specific Sentry SDK calls add their own `vi.mock(...)` per file. +**No real Sentry in tests.** The `core-testing/setup/no-sentry.ts` guard mocks `@sentry/nextjs`, `@sentry/node`, and `@sentry/react` at the module level, so any code that imports them gets a no-op surface during vitest runs. Tests that want to assert specific Sentry SDK calls add their own `vi.mock(...)` per file. -**R50 — Repository contracts assert span shape.** Every `__contracts__/-repository.contract.ts` includes a `span emission (R50)` describe block enumerating one assertion per public method. Suites run against both mock and real (Payload-backed) implementations, ensuring span emission stays in sync. Wire the recording tracer at the call site: +**Repository contracts assert span shape.** Every `__contracts__/-repository.contract.ts` includes a `span emission` describe block enumerating one assertion per public method. Suites run against both mock and real (Payload-backed) implementations, ensuring span emission stays in sync. Wire the recording tracer at the call site: ```ts const tracer = new RecordingTracer(); -articlesRepositoryContract.run( - () => new MockArticlesRepository(tracer), - { tracer: () => tracer }, -); +articlesRepositoryContract.run(() => new MockArticlesRepository(tracer), { + tracer: () => tracer, +}); ``` **Capture vs span assertions:** @@ -330,5 +338,4 @@ articlesRepositoryContract.run( - `RecordingLogger.users` — every `setUser` call (history). - `RecordingAuditLog.entries` — every `record(entry)` call. Use to assert audit emissions in feature-package tests **without** importing `@repo/core-audit` (the recording double lives in `@repo/core-testing/instrumentation` and mirrors the `AuditEntry` shape inline to avoid the tooling→core boundary). Also exposes `RecordingAuditLog.erasures` for `eraseSubject` history. See ADR-018 and `docs/guides/audit-and-compliance.md` for what to assert. -**Test cleanup:** call `tracer.reset()`, `logger.reset()`, and `auditLog.reset()` in `beforeEach` if the test creates one shared instance across multiple cases. -5. **Mock repos** are the default; only use real Payload in dedicated infrastructure tests +**Test cleanup:** call `tracer.reset()`, `logger.reset()`, and `auditLog.reset()` in `beforeEach` if the test creates one shared instance across multiple cases. 5. **Mock repos** are the default; only use real Payload in dedicated infrastructure tests