feat(conformance): wire cross-feature reader pattern into docs and schema
Add reads field to UseCaseManifest, update CLAUDE.md with Q0-Q3 rules, add ./reader subpath to AGENTS.md exports table, and cascade reader conventions through conformance quickref, adding-a-feature guide, and scaffolding guide. Moves gen reader from deferred to planned.
This commit is contained in:
@@ -29,7 +29,7 @@ per-use-case patterns below.
|
||||
|
||||
For any new use case, follow these four steps in order:
|
||||
|
||||
1. **Manifest entry** — declare the use case in `src/feature.manifest.ts` with its `mutates` flag and (initially empty) `audits` / `publishes` / `consumes` arrays.
|
||||
1. **Manifest entry** — declare the use case in `src/feature.manifest.ts` with its `mutates` flag and (initially empty) `audits` / `publishes` / `consumes` / `reads` arrays.
|
||||
2. **Contracts** — export `xInputSchema`, `xOutputSchema`, and the `IXUseCase` type alias from the use-case file. Factory body starts as `throw new Error("not implemented")`.
|
||||
3. **Tests (red)** — write the failing test that exercises the contract via the factory + a mock repository.
|
||||
4. **Implementation (green)** — fill the factory body until the tests pass.
|
||||
@@ -55,6 +55,7 @@ Every feature package owns:
|
||||
| `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 |
|
||||
| `integrations/readers/` | `I<Feature>Reader` interface + implementation (when feature exposes cross-feature queries) |
|
||||
| `ui/` | Query builders and future React components (behind `./ui` subpath) |
|
||||
| `__factories__/` | Test data factories |
|
||||
| `__contracts__/` | Contract suites shared by mock and real repository tests |
|
||||
|
||||
@@ -21,6 +21,7 @@ export const fooManifest = defineFeature({
|
||||
audits: ["thing.created"],
|
||||
publishes: ["foo.thing-created"],
|
||||
consumes: [],
|
||||
reads: ["auth"], // cross-feature reader dependency
|
||||
},
|
||||
},
|
||||
realtimeChannels: [],
|
||||
@@ -40,6 +41,7 @@ Field reference:
|
||||
| `useCases.<name>.audits` | string[] | Audit event types this use case emits via `auditLog.record({ type: "X" })` |
|
||||
| `useCases.<name>.publishes` | string[] | Cross-feature events this use case publishes via `bus.publish("X")` |
|
||||
| `useCases.<name>.consumes` | string[] | Cross-feature events this use case consumes (via an event handler) |
|
||||
| `useCases.<name>.reads` | string[] | Other features whose readers this use case queries (e.g. `["auth"]`) |
|
||||
| `realtimeChannels` | string[] | Realtime channels this feature owns |
|
||||
| `jobs` | string[] | Job slugs this feature enqueues |
|
||||
| `requiresConsent` | ConsentCategory[] | Consent categories feature use cases require; drives `withConsent` wrapping + `no-undeclared-consent-check` |
|
||||
|
||||
@@ -111,6 +111,7 @@ pnpm turbo gen event consume # consumer handler + Payload event-task
|
||||
pnpm turbo gen job # background job + TaskConfig
|
||||
pnpm turbo gen realtime channel # realtime channel descriptor (ADR-016)
|
||||
pnpm turbo gen realtime handler # inbound realtime handler (ADR-016)
|
||||
pnpm turbo gen reader # cross-feature reader interface + implementation
|
||||
```
|
||||
|
||||
The event/job generators insert at six fixed `// <gen:*>` anchor comments. Generated features include four of them automatically (the `// <gen:job-tasks>` location is in `integrations/cms/index.ts`, which is manually authored as part of the post-scaffold wiring); pre-existing features were retrofitted in ADR-015.
|
||||
@@ -127,4 +128,5 @@ The realtime generators insert at three additional fixed `// <gen:realtime-*>` a
|
||||
- `docs/decisions/adr-013-input-output-unification.md` — schemas-in-use-case + presenter
|
||||
- `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-026-cross-feature-readers.md` — cross-feature synchronous readers
|
||||
- `docs/decisions/adr-016-realtime-layer.md` — Socket.IO realtime channels + handlers
|
||||
|
||||
Reference in New Issue
Block a user