diff --git a/docs/architecture/starter-experience.md b/docs/architecture/starter-experience.md index 33d0c8fb..a5cfeadb 100644 --- a/docs/architecture/starter-experience.md +++ b/docs/architecture/starter-experience.md @@ -171,15 +171,19 @@ selected app. Every build and check script runs it first; run it yourself with 7. Run `corepack pnpm test:sample-removal -- --feature=` to prove the product still builds and passes its gates without the feature. -Files outside the feature directory: +Files outside the feature directory. Everything else a feature needs is in +`src/features//` and `tests/features//`. -| File | Change | -| --- | --- | -| `src/.generated/*` | regenerated automatically | -| `src/contexts//context-module.ts` | only when the feature needs a new context | -| `config/runtime/.json` | optional `FEATURE_OVERRIDES` entry to switch the feature off | -| `src/bootstrap/product-composition.ts` (product-owned) | only when `needs` names a capability the template does not build: augment `FeaturePlatformCapabilities` and return the capability here. `indexedDb` is built as in `recipes/frontend-capabilities/indexeddb-feature-capability.ts`. Credentials for a product auth profile are returned here too | -| `src/contracts/product-contracts.ts` (product-owned) | only for a product auth profile or a product runtime-config key | +| File | When | What fails without it | +| --- | --- | --- | +| `src/.generated/*` | never by hand: every build and check script regenerates it | — | +| `src/contexts//context-module.ts` | the feature needs a new context | `generate:feature-index`: `Feature belongs to undeclared context ` | +| `artifacts/tests/a11y-manual/.md` | every route the feature adds. Copy a record and reset it to `Status: pending-manual-review` | `test:unit` (`tests/unit/manual-a11y-evidence.test.ts`), `verify:documentation` (names the route IDs) and FE-GATE-009 (`review:a11y-manual -- --format-only`). FE-GATE-028 requires the signed review at release | +| `tests/e2e/accessibility.spec.ts` | a route path has a parameter other than `:resourceId`, or a protected page cannot render while every API answers `[]` | `test:a11y` (FE-GATE-009): the spec fills in only `:resourceId` and answers every API with `[]` | +| `src/bootstrap/product-composition.ts` (product-owned) | `needs` names a capability the template does not build: augment `FeaturePlatformCapabilities` and return the capability here. `indexedDb` is built as in `recipes/frontend-capabilities/indexeddb-feature-capability.ts`. Credentials for a product auth profile are returned here too | `check:types`; at runtime `feature needs , which the host did not provide` | +| `src/contracts/product-contracts.ts` (product-owned) | a product auth profile or a product runtime-config key | auth profile: every gate that loads the operation, with `REST security profiles are incoherent for : unknown authProfileId …`. Config key: `check:types` where it is read | +| `config/runtime/.json` | optional: a `FEATURE_OVERRIDES` entry switches the feature off | nothing | +| `package.json`, the lockfile, `config/security/dependency-change-evidence.json` | the contract contribution imports a generated `@org-contracts/*` package as a production dependency | `generate:supply-chain` (in `check:bundle`): `high-risk dependency missing review: add:` | The central catalogs (`src/features/installed-*.ts`) and the registry governance file do not change: consumer directories there are globs over every @@ -187,9 +191,20 @@ feature (`src/features/*/adapters`, `config/contracts/registry-governance.json`) A route's params/search schema ids are checked against the schemas the feature registers, and its `loadingSurface` only has to be a kebab-case name, so a route with its own schema and loading surface needs no governance edit either. +The registry baseline does not change either. New routes, API operations, +schemas and invalidation topics, namespaces and edges are additive registry +changes; `update:registry-baseline` or breaking evidence is needed only to +remove or change a row or graph item. `tests/unit/second-api-feature-registries.test.ts` adds such a feature (an API -operation and a route with its own search schema and loading surface) to a copy -of the repository and runs `check:registries` on it. +operation, a route with its own search schema and loading surface, and an +invalidation topic) to a copy of the repository and runs `check:registries` on +it. + +Schema, operation, mapper, route and chunk ids and invalidation topics are +global. Prefix them with the feature; `NoRequest` already belongs to the +sample. MSW scenarios for the feature's own operations come from +`createHttpScenarioHandler` (`tests/mocks/handlers/http-scenarios.ts`) with +the feature's installed contract; the shared scenario catalog does not change. ### Before shipping diff --git a/tests/unit/http-operation-v2-v3-parity.test.ts b/tests/unit/http-operation-v2-v3-parity.test.ts index 287a747f..4ada352c 100644 --- a/tests/unit/http-operation-v2-v3-parity.test.ts +++ b/tests/unit/http-operation-v2-v3-parity.test.ts @@ -30,20 +30,22 @@ const v2Rows = (Object.values(API_OPERATIONS) as readonly ApiOperation[]).filter ); // V3 validates the whole canonical input with one schema; V2 splits it into a -// path schema and a request (search or body) schema, "NoRequest" when absent. -// An operation that needs both has no rule yet and fails here until one is -// written down. -const NO_REQUEST = "NoRequest"; - +// path schema and a request (search or body) schema. The row says which of +// the two carry input: path parameters, and a request source other than +// "none". The other one names the feature's empty-input schema, whatever the +// feature calls it (schema ids are global, so a second feature cannot reuse +// the sample's `NoRequest`). An operation that needs both has no rule yet and +// fails here until one is written down. function v2InputSchema(row: RestOperationV2): string { - const declared = [row.pathSchema, row.requestSchema].filter( - (schemaId) => schemaId !== NO_REQUEST, - ); + const declared = [ + ...(row.pathParameterNames.length > 0 ? [row.pathSchema] : []), + ...(row.requestSource !== "none" ? [row.requestSchema] : []), + ]; expect( declared.length, `${row.operationId}: V2 declares both a path and a request schema; decide which V3 input schema matches them`, ).toBeLessThanOrEqual(1); - return declared[0] ?? NO_REQUEST; + return declared[0] ?? row.requestSchema; } describe("HTTP operation V2 rows and V3 descriptors", () => { diff --git a/tests/unit/second-api-feature-registries.test.ts b/tests/unit/second-api-feature-registries.test.ts index f1db18aa..83527db0 100644 --- a/tests/unit/second-api-feature-registries.test.ts +++ b/tests/unit/second-api-feature-registries.test.ts @@ -16,25 +16,32 @@ import { linkFixtureNodeModules } from "../../scripts/lib/fixture-node-modules.t * 0929/07-03. The feature also owns a route with its own search schema and its * own loading surface name, the values FE-REG-ROUTE once kept in a central * allowlist. + * 1101/16-01. And an invalidation topic, namespace and edge: every feature + * with server state has them, and adding them is additive. */ const FEATURE_ID = "second-api-feature"; const CONTEXT_ID = "second-api-context"; +const TOPIC_ID = "qinv.01kb3m8q2v6t4r9s1n5p7c0w"; const FEATURE_CONTRACT = `import { defineRestOperation } from "../../../contracts/api-operations.ts"; import type { InstalledBoundaryMapper } from "../../../contracts/boundary-mapper.ts"; import { mappingFailure, mappingSuccess } from "../../../contracts/boundary-mapper.ts"; +import { unvalidatedPayload } from "../../../contracts/external-contract-runtime.ts"; +import { defineQueryInvalidationTopic } from "../../../contracts/query-invalidation.ts"; +import { defineQueryNamespaceIdentity } from "../../../contracts/query-keys.ts"; import { runtimeSchemaCodecFromValidator } from "../../../contracts/schema-registry.ts"; const OWNER = "feature-frontend-second-api-feature"; +const SECOND_ITEM_TOPIC = defineQueryInvalidationTopic("${TOPIC_ID}"); +const SECOND_ITEM_NAMESPACE = defineQueryNamespaceIdentity("second-item", 1); const schema = (schemaId: string, boundary: string, direction: string) => Object.freeze({ schemaId, boundary, owner: OWNER, runtime: "zod", schemaVersion: 1, direction }); const codec = (schemaId: string) => - runtimeSchemaCodecFromValidator({ - schemaId, - safeParse: (value: unknown) => Object.freeze({ success: true as const, data: value }), - }); + runtimeSchemaCodecFromValidator( + unvalidatedPayload(schemaId, "registry fixture: only check-registries reads it"), + ); const ROUTES = Object.freeze({ SECOND_ITEM_LIST: Object.freeze({ @@ -64,8 +71,16 @@ export const SECOND_API_CONTRACT = Object.freeze({ searchCodec: "SecondItemListQuery", }), }), - invalidation: { topics: Object.freeze([]), namespaces: Object.freeze([]), edges: Object.freeze([]) }, - topicVersions: Object.freeze([]), + invalidation: Object.freeze({ + topics: Object.freeze([SECOND_ITEM_TOPIC]), + namespaces: Object.freeze([SECOND_ITEM_NAMESPACE]), + edges: Object.freeze([ + Object.freeze({ topicId: SECOND_ITEM_TOPIC, namespace: SECOND_ITEM_NAMESPACE }), + ]), + }), + topicVersions: Object.freeze([ + Object.freeze({ topicId: SECOND_ITEM_TOPIC, topicVersion: 1 }), + ]), contractPackages: Object.freeze([]), } as const); @@ -175,7 +190,7 @@ afterAll(async () => { await Promise.all(roots.map((root) => rm(root, { recursive: true, force: true }))); }); -describe("adding a feature with an API operation and a route (F-3, 09-07, 0929/07-03)", () => { +describe("adding a feature with an API operation, a route and an invalidation topic (F-3, 09-07, 0929/07-03, 1101/16-01)", () => { it("passes check-registries without edits outside the feature and its context", async () => { const root = await mkdtemp(path.join(tmpdir(), "second-api-feature-")); roots.push(root); @@ -220,7 +235,10 @@ describe("adding a feature with an API operation and a route (F-3, 09-07, 0929/0 expect(checked.status).toBe(0); const report = JSON.parse( await readFile(path.join(root, "artifacts/quality/registries.json"), "utf8"), - ) as { registries: { registryId: string; rows: Record }[] }; + ) as { + registries: { registryId: string; rows: Record }[]; + compatibility: { changes: { registryId: string; field: string; impact: string }[] }; + }; const api = report.registries.find(({ registryId }) => registryId === "FE-REG-API"); expect(Object.keys(api?.rows ?? {})).toContain("GET_SECOND_ITEM"); const routes = report.registries.find(({ registryId }) => registryId === "FE-REG-ROUTE"); @@ -228,5 +246,20 @@ describe("adding a feature with an API operation and a route (F-3, 09-07, 0929/0 searchSchema: "SecondItemListQuery", loadingSurface: "second-item-list", }); + const graph = report.registries.find( + ({ registryId }) => registryId === "FE-REG-QUERY-INVALIDATION", + ); + expect(graph?.rows["invalidation-graph"]).toMatchObject({ + topics: expect.arrayContaining([TOPIC_ID]), + }); + expect( + report.compatibility.changes + .filter(({ registryId }) => registryId === "FE-REG-QUERY-INVALIDATION") + .map(({ field, impact }) => [field, impact]), + ).toEqual([ + ["edges", "additive"], + ["namespaces", "additive"], + ["topics", "additive"], + ]); }, 60_000); });