From 7450e1f2b33489280f7c22e33ec96f141c530bf5 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Tue, 3 Nov 2026 01:49:49 +0900 Subject: [PATCH] =?UTF-8?q?test(features):=20=EA=B8=B0=EB=8A=A5=20?= =?UTF-8?q?=EC=B6=94=EA=B0=80=20=ED=85=8C=EC=8A=A4=ED=8A=B8=EC=97=90=20?= =?UTF-8?q?=EB=AC=B4=ED=9A=A8=ED=99=94=20topic=EC=9D=84=20=EB=84=A3?= =?UTF-8?q?=EA=B3=A0=20=ED=8F=B4=EB=8D=94=20=EB=B0=96=20=EC=88=98=EC=A0=95?= =?UTF-8?q?=20=ED=91=9C=EB=A5=BC=20=EA=B3=A0=EC=B9=9C=EB=8B=A4=20(1101/16-?= =?UTF-8?q?01)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제 - starter-experience.md "Adding a feature"의 폴더 밖 수정 표가 실제와 다르다. 라우트마다 필요한 수동 a11y 기록이 없고, 어느 검사가 실패하는지도 적지 않는다. - 이 주장을 지키는 second-api-feature-registries 테스트는 무효화 topic이 없는 기능만 넣는다. 그래서 topic 추가가 기준선 재승인을 요구하던 결함을 보지 못했다. - http-operation-v2-v3-parity 테스트는 스키마 ID "NoRequest"를 "입력 없음" 표시로 고정해 쓴다. 스키마 ID는 전역이라 두 번째 기능은 다른 이름(예: OrderNoRequest)을 써야 한다. 그러면 이 테스트가 그 기능의 path·request 스키마를 둘 다 입력으로 세어 실패한다(16-02 작업자 발견). 고른 방법 - 표를 지금 코드 기준으로 다시 썼다. 열은 파일 / 언제 / 없으면 무엇이 실패하나. 리뷰 실험 E의 ①~⑨ 중 이번 라운드 앞 커밋이 없앤 것은 뺐다: governance allowlist(0929/07-03), 기준선 재승인(앞 커밋, 결정 1), README· 체크리스트 route ID 목록(14-05), 인증 프로필 이름(16-03, EXTERNAL_BEARER 재사용), MSW 카탈로그와 무관한 테스트 3개(16-02). runtime-adapters.ts는 product-composition.ts로 바뀌었다(09-02). - 남은 것: context 선언, 라우트별 a11y 기록, 경로 파라미터가 :resourceId가 아니거나 빈 배열 응답으로 그려지지 않는 페이지의 e2e a11y spec, 제품 capability·인증 프로필·설정 키(제품 소유 파일 2개), 선택인 FEATURE_OVERRIDES, 계약 패키지를 npm 의존성으로 들일 때의 의존성 검토 증거. 계약 출처(EXTERNAL_PACKAGE)는 기능 계약의 contractPackages에 선언하므로 폴더 밖 수정이 아니다. - 표 아래에 레지스트리 추가는 기준선을 바꾸지 않는다는 것, 전역 ID에 기능 접두어를 붙인다는 것, 기능의 MSW 시나리오는 createHttpScenarioHandler로 만든다는 것을 적었다. - second-api 기능에 무효화 topic·namespace·edge·topicVersion을 더하고, 무효화 그래프 변경 3건이 additive인지 단언한다. 라우트는 0929/07-03이 이미 넣었으므로(SECOND_ITEM_LIST) 더하지 않았다. - second-api의 통과 codec은 검증을 생략하므로 1101/07-03의 unvalidatedPayload로 만든다. - parity 테스트는 V2 행에서 입력이 있는 쪽을 읽는다. path 스키마는 pathParameterNames가 있을 때, request 스키마는 requestSource가 "none"이 아닐 때 입력이다. 둘 다 없으면 행의 requestSchema(그 기능의 빈 입력 스키마)를 기대한다. 버린 대안 - 표만 고치기(리뷰 대안 a): 테스트가 계속 좁은 모양만 증명한다. - 참조 기능의 NoRequest를 ReferenceNoRequest로 바꾸기: FE-REG-API 행의 requestSchema·pathSchema가 바뀌어 기준선 재승인이 필요하고 범위 밖이다. - parity 테스트에서 이름 끝이 NoRequest인 스키마를 빈 입력으로 보기: 이름 관례에 기대는 규칙이라 다른 이름을 쓰면 다시 깨진다. - second-api 기능에 V3 기여를 넣어 parity를 그 사본에서 돌리기: 1101/07-02(3c31576)가 같은 이유로 버렸다(사본에서는 check:registries만 돈다). 위험·한계 - e2e a11y spec 행은 코드(:resourceId만 치환, 모든 API에 [] 응답)를 읽고 적었다. 다른 파라미터를 가진 라우트로 test:a11y를 실제로 돌려 보지는 않았다. - 의존성 행은 직접 production 의존성을 더하면 generate:supply-chain이 "high-risk dependency missing review"로 실패한다는 코드를 읽고 적었다. 실행하지 않았다. - 초기 JS 예산은 표에 넣지 않았다. 기능 하나가 초기 JS를 늘리지만 예산은 기능이 고칠 파일이 아니다. 이번에 측정하지 않았다. - 표의 완전성은 테스트가 지키지 않는다. 생성 명령(U7)의 게이트 실행이 이 표를 실행으로 확인할 자리다. 검증 - RED: 넓힌 second-api 테스트를 결정 1 전 분류기(HEAD~1의 registry-compatibility.ts)로 돌리면 실패한다. check-registries stderr "breaking change missing evidence: FE-REG-QUERY-INVALIDATION:invalidation-graph:{edges,namespaces,topics}:field-changed". parity 테스트는 참조 기능의 NoRequest를 ReferenceNoRequest로 바꾼 변이(커밋 안 함)에서 "LIST_REFERENCE_RESOURCES: V2 declares both a path and a request schema" 실패. - GREEN: second-api 1/1, 같은 변이에서 parity 2/2, 변이 없이 2/2 통과. V3 inputValidator schemaId를 바꾼 변이는 여전히 inputSchema 차이로 실패한다. - 회귀: tests/unit 178파일 중 177 통과. 실패 1건 feature-shape-growth(초기 JS 증가 1 KiB 초과)는 기준 커밋에서도 실패한다. tsc app·test rc=0, 바꾼 테스트 eslint rc=0, verify-documentation-readiness PASS_SCOPED, check-registries PASS(compatibility=none). - 미실행: check:architecture(pnpm 필요), test:a11y, test:sample-removal. Refs: docs/reviews/2026-11-01-maturity-review/16-structure-patterns.md 16-01, 8.1, 8.2 --- docs/architecture/starter-experience.md | 35 +++++++++---- .../unit/http-operation-v2-v3-parity.test.ts | 20 ++++---- .../second-api-feature-registries.test.ts | 49 ++++++++++++++++--- 3 files changed, 77 insertions(+), 27 deletions(-) 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); });