fix(contracts): 참조 기능 밖의 TEMPLATE_FIXTURE 기여를 거부한다 (07-04)
문제
조립기(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<revision>"
꼴이라는 이름 규칙에 기댄다. 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
This commit is contained in:
@@ -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/<feature>/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
|
||||
|
||||
@@ -695,6 +695,7 @@ export function composeContractContributions(
|
||||
const packagesById = new Map<string, InstalledContractPackageIdentity>();
|
||||
const contributionIds = new Set<string>();
|
||||
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<revision>`) 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`);
|
||||
}
|
||||
|
||||
@@ -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",
|
||||
);
|
||||
});
|
||||
});
|
||||
@@ -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]),
|
||||
},
|
||||
|
||||
@@ -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<unknown> => ({
|
||||
schemaId: "Malformed",
|
||||
|
||||
Reference in New Issue
Block a user