From c06338956ee19e3e0b3fa25ea00dea45bc1b22f8 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sun, 1 Nov 2026 22:02:31 +0900 Subject: [PATCH] =?UTF-8?q?fix(contracts):=20=EC=B0=B8=EC=A1=B0=20?= =?UTF-8?q?=EA=B8=B0=EB=8A=A5=20=EB=B0=96=EC=9D=98=20TEMPLATE=5FFIXTURE=20?= =?UTF-8?q?=EA=B8=B0=EC=97=AC=EB=A5=BC=20=EA=B1=B0=EB=B6=80=ED=95=9C?= =?UTF-8?q?=EB=8B=A4=20(07-04)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제 조립기(composeContractContributions)의 TEMPLATE_FIXTURE 분기는 fixtureId·revision·이벤트 0개만 보고 featureId를 보지 않는다. 참조 기여 파일을 복사한 제품 기능(order)이 fixture 출처 그대로 조립을 통과한다. fixture 기여는 계약 집합(externalPackages)에 들어가지 않으므로 그 API는 실행되지만 부팅 때 릴리스 계약 정합 검사에서 경고 없이 빠진다. 설계서 §4.8은 "product feature는 반드시 EXTERNAL_PACKAGE", §24.5는 정적 검사가 product TEMPLATE_FIXTURE를 거부한다고 적지만 구현이 없다. 고른 방법 - 조립기 fixture 분기에서 featureId가 fixture의 주인과 다르면 ContractContributionError로 실패한다. 메시지가 EXTERNAL_PACKAGE를 쓰라고 안내한다. - fixture 기여가 둘 이상이면 실패한다(설계서의 "유일한 예외"). - 15-01 뒤 조립은 기능 적재 때마다 전체를 다시 조립하므로 두 검사 모두 기능이 따로 적재돼도 걸린다. registry.install의 featureId 일치 검사가 있어 다른 기능이 참조 기능 id를 빌려 쓰는 길도 막혀 있다. - 주인 featureId는 리터럴로 쓰지 않고 fixtureId에서 만든다 (REFERENCE_FEATURE_V1 -> 대문자 스네이크를 소문자 kebab으로, _V1 제거). 이유를 주석에 적었다. - starter-experience.md "Adding a feature"에 제품 기여는 EXTERNAL_PACKAGE라는 문장을 넣었다. - contract-snapshot-bypass의 "iterator에 숨긴 이벤트" 테스트는 featureId test-feature의 fixture를 썼다. 새 검사가 그 행을 먼저 막아 테스트가 아무것도 확인하지 못하게 되므로 EXTERNAL_PACKAGE 출처로 바꿨다. 패키지 출처는 이벤트를 받으므로 숨긴 이벤트를 읽으면 설치되어 단언이 실패한다. 예전 fixture 출처는 이벤트가 하나라도 있으면 던져서 읽었는지 아닌지를 구분하지 못했다. 버린 대안 - 리뷰 문서 그대로 featureId !== "reference-feature" 리터럴 비교: test:sample-removal이 샘플 제거 뒤 src/·tests/ 전체에서 /REFERENCE_RESOURCE|reference-feature|reference-resource/i를 찾아 잔여물로 실패시킨다(scripts/test-sample-removal.ts:95). 플랫폼 코드와 남는 단위 테스트에 그 id를 쓰면 이 게이트가 깨진다. - 조립기에 허용 featureId 인자를 추가하거나 feature module에 fixture 표시 필드를 추가: 공개 함수·타입 변경이라 이번 범위를 넘는다. - 정적 검사(dependency-cruiser) 규칙: 출처 종류는 import가 아니라 값이라 depcruise로 볼 수 없다. 위험·한계 - 실패 시점은 15-01 구조에 따라 부팅이 아니라 그 기능의 런타임 적재 (라우트 진입) 때다. Node 쪽 loaded-feature-runtimes와 레지스트리 스크립트는 import 때 전부 조립하므로 CI에서는 바로 드러난다. - scripts/scale/measure-feature-shape-growth.ts는 참조 기능을 이름만 바꿔 복사하고 REFERENCE_FEATURE_V1을 그대로 둔다. 그 복사본은 이제 조립에서 거부된다. 이 스크립트는 tsc와 vite build만 하고 기여를 조립하지 않아 측정에는 영향이 없다(실행하지 않음). - 주인 id 유도는 fixtureId가 "<기능 id 대문자 스네이크>_V" 꼴이라는 이름 규칙에 기댄다. fixtureId는 닫힌 리터럴 하나라 지금은 참조 기능 id 하나로만 풀린다. 검증 - RED(수정 전 조립기): 새 테스트 2건 실패. external-contract-runtime "rejects a fixture copied into a product feature" -> "Expected contract composition to fail." reference-fixture-provenance "rejects a second fixture contribution" -> "expected undefined to be 'reference-feature: only one TEMPLATE_FIXTURE contribution is allowed'". - GREEN: 같은 3파일 22/22 통과. - 회귀(298201f 위로 rebase 뒤): run-vitest tests/unit tests/features tests/platform tests/component tests/contract tests/runtime-schema tests/integration (pnpm·corepack을 띄우는 fixture-node-modules, security-followup-archive, deployment-admission, lab-performance 제외) 267 files / 3107 tests 중 3106 통과. 실패 1건은 provider-guardian-transaction(guardian exit=126, 단독 실행도 같음)으로 scripts/lib 프로세스 테스트라 이 변경과 무관하다. tsc app/test rc=0. 바꾼 파일 eslint rc=0. - 바꾼 src·tests/unit 파일에 샘플 잔여물 정규식 일치 0건(grep). - 미실행: test:sample-removal, check:architecture(pnpm 필요). Refs: docs/reviews/2026-11-01-maturity-review/07-contracts.md --- docs/architecture/starter-experience.md | 3 ++ src/contracts/external-contract-runtime.ts | 23 ++++++++++++ .../reference-fixture-provenance.test.ts | 37 +++++++++++++++++++ tests/unit/contract-snapshot-bypass.test.ts | 11 +++--- tests/unit/external-contract-runtime.test.ts | 22 +++++++++++ 5 files changed, 90 insertions(+), 6 deletions(-) create mode 100644 tests/features/reference-feature/reference-fixture-provenance.test.ts diff --git a/docs/architecture/starter-experience.md b/docs/architecture/starter-experience.md index 787fa916..99d56352 100644 --- a/docs/architecture/starter-experience.md +++ b/docs/architecture/starter-experience.md @@ -129,6 +129,9 @@ selected app. Every build and check script runs it first; run it yourself with entered. Do not import it statically from anywhere: each feature would add its whole executable code to the initial chunk again, about 3.9 KB gzip (`tests/unit/feature-shape-growth.test.ts` bounds one feature at 1 KiB). + A product feature's contract contribution uses an `EXTERNAL_PACKAGE` + source. `TEMPLATE_FIXTURE` belongs to `reference-feature` only and never + joins the release contract set; the composer rejects it anywhere else. 3. Create `src/features//context-routes.ts` exporting `FEATURE_CONTEXT_ROUTES`. Page components are imported lazily here, and each route handle carries the route's params/search `codecs`; the owning context diff --git a/src/contracts/external-contract-runtime.ts b/src/contracts/external-contract-runtime.ts index 31e1333f..0d2d96c2 100644 --- a/src/contracts/external-contract-runtime.ts +++ b/src/contracts/external-contract-runtime.ts @@ -695,6 +695,7 @@ export function composeContractContributions( const packagesById = new Map(); const contributionIds = new Set(); const installedContributions: InstalledContractContribution[] = []; + let fixtureInstalled = false; for (const raw of rows) { if (!raw || typeof raw !== "object") { @@ -794,6 +795,28 @@ export function composeContractContributions( ) { fail(`${featureId}: template fixture identity`); } + // §4.8, §24.5 (07-04). The fixture is the sample vertical's test data, + // not a product contract: it never joins the contract set, so a fixture + // copied into a product feature would drop that API from the release + // check without a word. Only the feature the fixture is named after may + // install it; every other feature pins an EXTERNAL_PACKAGE. + // The owner is derived from the fixture id (upper snake case feature id + // plus `_V`) instead of being written out, because + // test:sample-removal rejects the sample feature's id anywhere in src/ + // once the sample is gone. + const fixtureOwner = fixture.fixtureId + .slice(0, -`_V${fixture.revision}`.length) + .toLowerCase() + .replaceAll("_", "-"); + if (featureId !== fixtureOwner) { + fail( + `${featureId}: TEMPLATE_FIXTURE ${fixture.fixtureId} belongs to ${fixtureOwner} only; pin an EXTERNAL_PACKAGE`, + ); + } + if (fixtureInstalled) { + fail(`${featureId}: only one TEMPLATE_FIXTURE contribution is allowed`); + } + fixtureInstalled = true; if (eventRows.length !== 0) { fail(`${featureId}: template fixture must not contribute events`); } diff --git a/tests/features/reference-feature/reference-fixture-provenance.test.ts b/tests/features/reference-feature/reference-fixture-provenance.test.ts new file mode 100644 index 00000000..c02f1caa --- /dev/null +++ b/tests/features/reference-feature/reference-fixture-provenance.test.ts @@ -0,0 +1,37 @@ +import { describe, expect, it } from "vitest"; + +import { + ContractContributionError, + composeContractContributions, +} from "../../../src/contracts/external-contract-runtime.ts"; +import { REFERENCE_FEATURE_TEMPLATE_CONTRIBUTION } from "../../../src/features/reference-feature/contracts/reference-feature-contract-contribution.ts"; + +// 07-04 (§4.8). The product-feature rejection is in +// tests/unit/external-contract-runtime.test.ts. +describe("reference template fixture provenance", () => { + it("installs the fixture outside the release contract set", () => { + const composed = composeContractContributions([ + REFERENCE_FEATURE_TEMPLATE_CONTRIBUTION, + ]); + expect(composed.contributions).toHaveLength(1); + expect(composed.externalPackages).toHaveLength(0); + }); + + it("rejects a second fixture contribution from the same feature", () => { + const second = Object.freeze({ + ...REFERENCE_FEATURE_TEMPLATE_CONTRIBUTION, + contributionId: "reference-feature-http-v2", + http: Object.freeze([]), + }); + let reason: string | undefined; + try { + composeContractContributions([REFERENCE_FEATURE_TEMPLATE_CONTRIBUTION, second]); + } catch (error) { + expect(error).toBeInstanceOf(ContractContributionError); + reason = (error as ContractContributionError).reason; + } + expect(reason).toBe( + "reference-feature: only one TEMPLATE_FIXTURE contribution is allowed", + ); + }); +}); diff --git a/tests/unit/contract-snapshot-bypass.test.ts b/tests/unit/contract-snapshot-bypass.test.ts index cbc3825c..79304b44 100644 --- a/tests/unit/contract-snapshot-bypass.test.ts +++ b/tests/unit/contract-snapshot-bypass.test.ts @@ -65,13 +65,12 @@ describe("external contract composition", () => { try { composed = composeContractContributions([ { - contributionId: "fixture-v1", + contributionId: "smuggled-events-v1", featureId: "test-feature", - source: { - kind: "TEMPLATE_FIXTURE", - fixtureId: "REFERENCE_FEATURE_V1", - revision: 1, - }, + // 07-04. A package source accepts events, so a hidden event that was + // read would be installed and fail the assertion below. A fixture + // source throws on any event, which hid whether it was read. + source: TEST_CONTRACT_CONTRIBUTION.source, http: [], events: iteratorSmuggling([], [smuggled]), }, diff --git a/tests/unit/external-contract-runtime.test.ts b/tests/unit/external-contract-runtime.test.ts index 421dfe87..c98b1348 100644 --- a/tests/unit/external-contract-runtime.test.ts +++ b/tests/unit/external-contract-runtime.test.ts @@ -86,6 +86,28 @@ describe("external contract contribution composition", () => { }); }); +// The sample feature's own cases (its fixture composes, a second one does not) +// live in tests/features so they leave with the sample. +describe("template fixture provenance (07-04, §4.8)", () => { + it("rejects a fixture copied into a product feature, which would leave the contract set silently", () => { + const copied = Object.freeze({ + ...contribution("order-http-v1", TEST_CONTRACT_CONTRIBUTION.http), + featureId: "order", + source: Object.freeze({ + kind: "TEMPLATE_FIXTURE" as const, + fixtureId: "REFERENCE_FEATURE_V1" as const, + revision: 1 as const, + }), + }); + const error = captureContributionError(() => + composeContractContributions([copied]), + ); + expect(error.reason).toMatch( + /^order: TEMPLATE_FIXTURE REFERENCE_FEATURE_V1 belongs to .+ only; pin an EXTERNAL_PACKAGE$/u, + ); + }); +}); + describe("validator invocation (07-06)", () => { const returning = (result: unknown): RuntimeValidator => ({ schemaId: "Malformed",