test(features): 기능 추가 테스트에 무효화 topic을 넣고 폴더 밖 수정 표를 고친다 (1101/16-01)

문제
- 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
This commit is contained in:
DongHyeonka
2026-11-03 01:50:12 +09:00
parent 605fd17d9f
commit 7450e1f2b3
3 changed files with 77 additions and 27 deletions
+25 -10
View File
@@ -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=<feature id>` 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/<feature>/` and `tests/features/<feature>/`.
| File | Change |
| --- | --- |
| `src/.generated/*` | regenerated automatically |
| `src/contexts/<context>/context-module.ts` | only when the feature needs a new context |
| `config/runtime/<profile>.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>/context-module.ts` | the feature needs a new context | `generate:feature-index`: `Feature <id> belongs to undeclared context <context>` |
| `artifacts/tests/a11y-manual/<ROUTE_ID>.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 <id> needs <capability>, 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 <operationId>: unknown authProfileId …`. Config key: `check:types` where it is read |
| `config/runtime/<profile>.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:<package>` |
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
+11 -9
View File
@@ -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", () => {
@@ -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<string, unknown> }[] };
) as {
registries: { registryId: string; rows: Record<string, unknown> }[];
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);
});