문제
/examples/ui, /examples/states, /examples/auth(와 /examples/platform)는
플랫폼 라우트 레지스트리에 고정이었다. VITE_PRODUCT_FEATURES와
FEATURE_OVERRIDES는 기능만 빼므로 제품은 이 화면을 끌 수 없었다.
릴리스 게이트 FE-GATE-028은 ROUTE_REGISTRY의 모든 라우트에 서명된
수동 접근성 기록을 요구해서, 제품은 템플릿 갤러리를 운영 메뉴에 두고
서명하거나 템플릿 파일 5개와 src/presentation/examples/를 지워야 했다.
고른 방법
- UI 갤러리·화면 상태·인증 연동을 platform-examples-feature로 옮겼다.
자기 context platform-examples-context(루트 examples/*)에 산다.
reference-context의 examples/reference-resources/*와 플랫폼 라우트
/examples/platform이 더 구체적이라 그 URL은 그대로 간다.
- 라우트 ID·경로·청크 ID·표면은 바꾸지 않았다. 시각·e2e 테스트와 a11y
기록(artifacts/tests/a11y-manual/EXAMPLES_*.md)이 그대로 이 이름을
쓴다. 기능을 빼면 a11y 목록은 ROUTE_REGISTRY에서 오므로 같이 빠진다.
- 실행부는 비어 있다(스키마·adapter·계약 기여 없음). 페이지는 context
routes에서 페이지마다 lazy로 받는다.
- 플랫폼 구성 화면(EXAMPLES_PLATFORM)은 플랫폼 라우트로 남겼다. 처음에는
같이 옮겼다. 같은 호스트·같은 부하(15~19)에서 d99301b와 번갈아 잰
lab이 기능 라우트로는 443·432 ms FAIL이었다(d99301b 133·183 ms
PASS). 기능 라우트의 첫 진입은 context routes 모듈을 받은 뒤에 페이지
청크를 받는다(요청 추적: 939 B + 177 B 다음에 5,183 B + 3개). 페이지를
routes 모듈에 정적으로 넣으면 릴리스 매니페스트의 routeChunks 계약
(페이지마다 dynamic entry)이 깨진다. 15-01의 "예산을 올리지 않는다"를
지키려고 이 한 화면은 남겼다.
- 홈 화면은 예제 라우트 ID를 적지 않는다. 내비게이션의 처음 세 화면을
"{title} 보기"로 보여 준다. 템플릿에서는 예전과 같은 세 링크(플랫폼
구성·UI 구성요소·화면 상태)가 나오고, 예제를 뺀 제품에서는 그 제품의
화면이 나온다. home.starter.platform·ui·states 키를 home.starter.open
하나로 바꿨다. VITE_PRODUCT_FEATURES=none 빌드 검사
(product-feature-selection-build)가 홈 청크의 예제 라우트 ID를 잡았다.
- 예제 화면 component 테스트는 tests/features/platform-examples-feature/로
옮겼다. 제거 드릴이 같이 지운다. runtime-adapters 테스트는 API가 있는
기능만 센다(예제 기능은 API가 없다). context-route-roots 테스트의
"플랫폼 라우트와 같은 경로" 예는 /examples/platform으로 바꿨다.
- old-tab-chunk-recovery e2e는 페이지 소스를 빌드 A의 Vite manifest에서
찾는다(기능 폴더 이름을 적지 않음). UI 갤러리가 기능 라우트라 B 탭이
잃는 청크는 그 context routes 모듈이다. 허용 패턴에 넣었다.
- 예제 화면 문구는 08-07대로 한국어 고정이다. 화면 문구 ESLint 규칙의
예외에 새 폴더를 넣었다.
- 버린 대안: 빌드 변수로 숨김(선택 장치가 하나 더 생김), 예제 화면만
제품이 지우게 둠(동기화 충돌 자리가 남음).
위험·한계
- 공개 경로가 바뀌었다. src/presentation/examples/{ui-gallery,
state-gallery,auth-example}-page.tsx, PLATFORM_ROUTE_REGISTRY·
PLATFORM_ROUTE_RUNTIME(_CONTRACT)의 EXAMPLES_UI·STATES·AUTH,
home.starter.platform/ui/states 키를 쓰던 다운스트림은 깨진다.
- 플랫폼 구성 화면은 여전히 끌 수 없고 FE-GATE-028 서명 대상이다.
- tests/e2e와 tests/visual의 여러 spec이 예제 화면을 자기 페이지로 쓴다.
예제를 뺀 제품은 그 spec을 자기 화면으로 바꾸거나 지워야 한다
(starter-experience.md에 적음). 제거 드릴은 브라우저 테스트를 돌리지
않아 이것을 보지 않는다.
- 예제 기능 제거 드릴은 16-02(빈 ciScripts로 CI 기준선 사유가 공백)
때문에 그대로는 시작하자마자 실패한다. 아래 드릴 결과는 그 한 줄을
임시로 고친 상태에서 낸 것이다(커밋하지 않음).
- 기능 라우트 첫 진입이 이 lab 조건에서 약 430 ms라는 것은 어느 게이트도
재지 않는다.
검증
- product-feature-selection-build(VITE_PRODUCT_FEATURES=none 빌드):
홈 청크의 예제 라우트 ID 3건으로 실패한 것을 확인하고 홈 화면을 고친
뒤 통과.
- test:sample-removal -- --feature=platform-examples-feature(heavy lock,
16-02 한 줄 임시 패치): PASS, 13 checks(typecheck, architecture,
registries, test:all, coverage, test-evidence, ci, home-smoke, build,
route-absent, 잔여 ID 0). 첫 시도에서는 lab-performance 단위 테스트가
측정 라우트 조회가 포트 검사보다 먼저여서 실패했다(그 뒤 이 변경에서
측정 라우트를 플랫폼에 남겨 조회 변경 자체를 뺐다).
- test:unit 2,587, test:component 253, tests/features·platform·
architecture 383 통과. check:types, lint, check:architecture,
check:i18n, check:registries(additive), verify:documentation 통과.
- test:e2e 세 엔진 187 passed, 3 skipped(Firefox SW quarantine).
old-tab-chunk-recovery 포함. test:a11y 60 passed.
- build + check:bundle: 초기 JS 201,940 / 204,800 B(+92 B).
- lab(측정 라우트를 기능으로 옮긴 시도): 443·432 ms FAIL, 같은 묶음
d99301b 133·183 ms PASS(부하 15~19). 남긴 뒤 136·134 ms PASS.
Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-04
BREAKING CHANGE: 예제 라우트 EXAMPLES_UI·EXAMPLES_STATES·EXAMPLES_AUTH가
플랫폼 레지스트리에서 platform-examples-feature로 옮겨졌다. 페이지 파일은
src/features/platform-examples-feature/presentation/으로 갔고,
PLATFORM_ROUTE_REGISTRY·PLATFORM_ROUTE_RUNTIME_CONTRACT·
PLATFORM_ROUTE_RUNTIME에 이 키들이 없다. 홈 문구 키
home.starter.platform·ui·states는 home.starter.open({title})로 바뀌었다.
예제를 지운 다운스트림은 이 기능 폴더와 context를 지우면 된다.
182 lines
6.8 KiB
TypeScript
182 lines
6.8 KiB
TypeScript
import { mkdir, readFile, readdir } from "node:fs/promises";
|
|
|
|
import { i18nReportArtifactSchema } from "./contracts/release-artifacts.ts";
|
|
import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
|
|
import path from "node:path";
|
|
|
|
import { EN_MESSAGES, KO_MESSAGES, MESSAGE_CATALOGS } from "../src/presentation/i18n/catalog.ts";
|
|
|
|
const fixtureMode = process.argv.includes("--fixture");
|
|
const failures: string[] = [];
|
|
const sourceExtensions = /\.(?:ts|tsx|mts|cts)$/;
|
|
const rawFailureRender =
|
|
/(?<!\$)\{\s*(?:failure|error|response|backend)(?:\?\.|\.)[\w?.]*message\s*\}/;
|
|
|
|
async function listSourceFiles(directory: string): Promise<string[]> {
|
|
const result: string[] = [];
|
|
for (const entry of await readdir(directory, { withFileTypes: true })) {
|
|
const target = path.join(directory, entry.name);
|
|
if (entry.isDirectory()) result.push(...(await listSourceFiles(target)));
|
|
else if (sourceExtensions.test(entry.name)) result.push(target);
|
|
}
|
|
return result;
|
|
}
|
|
|
|
function placeholders(template: string): string[] {
|
|
return [...template.matchAll(/\{([a-zA-Z][a-zA-Z0-9]*)\}/g)]
|
|
.map((match) => match[1])
|
|
.sort();
|
|
}
|
|
|
|
if (!fixtureMode) {
|
|
const canonicalKeys = Object.keys(KO_MESSAGES).sort();
|
|
for (const [locale, catalog] of Object.entries(MESSAGE_CATALOGS)) {
|
|
const readableCatalog = catalog as Readonly<Record<string, string>>;
|
|
const canonicalCatalog = KO_MESSAGES as Readonly<Record<string, string>>;
|
|
const keys = Object.keys(catalog).sort();
|
|
if (JSON.stringify(keys) !== JSON.stringify(canonicalKeys)) {
|
|
failures.push(`${locale} catalog keys do not match ko-KR`);
|
|
}
|
|
for (const key of canonicalKeys) {
|
|
if (
|
|
JSON.stringify(placeholders(readableCatalog[key] ?? "")) !==
|
|
JSON.stringify(placeholders(canonicalCatalog[key] ?? ""))
|
|
) {
|
|
failures.push(`${locale}:${key} interpolation parameters do not match`);
|
|
}
|
|
}
|
|
}
|
|
if (Object.keys(EN_MESSAGES).length !== canonicalKeys.length) {
|
|
failures.push("en-US catalog key count does not match ko-KR");
|
|
}
|
|
}
|
|
|
|
// 0929/08-02. Whether screen code takes its words from the catalog is an
|
|
// ESLint rule now (eslint.config.ts, screenTextSelectors): this script looked
|
|
// for Hangul anywhere in a file, so it rejected Korean comments and let English
|
|
// copy through. Raw HTML is the FE-OC-019 ESLint rule. What stays here is
|
|
// catalog parity and rendering a backend message, which a selector cannot tell
|
|
// from an ordinary `.message` read. Fixture mode runs the ESLint rule on the
|
|
// fixture trees too, so this one gate shows the whole i18n contract rejecting
|
|
// every forbidden file and passing the allowed one.
|
|
// `src/presentation/examples` (the platform overview) and the example
|
|
// screens (`src/features/platform-examples-feature/presentation`, 1103/09-04)
|
|
// are workshop code and stay out of the ESLint rule's scope on purpose.
|
|
const forbiddenFixtureRoot = "tests/fixtures/i18n/forbidden";
|
|
const allowedFixtureRoot = "tests/fixtures/i18n/allowed";
|
|
const sourceRoot = fixtureMode ? forbiddenFixtureRoot : ".";
|
|
const commonDirectories = [
|
|
"src/presentation/boundaries",
|
|
"src/presentation/components",
|
|
"src/presentation/design-system",
|
|
"src/presentation/forms",
|
|
"src/presentation/layouts",
|
|
"src/presentation/pages",
|
|
"src/presentation/routes",
|
|
"src/presentation/templates",
|
|
];
|
|
|
|
async function featurePresentationDirectories(root: string): Promise<string[]> {
|
|
const features = path.join(root, "src/features");
|
|
const entries = await readdir(features, { withFileTypes: true }).catch(
|
|
() => [],
|
|
);
|
|
return entries
|
|
.filter((entry) => entry.isDirectory())
|
|
.map((entry) => path.join("src/features", entry.name, "presentation"));
|
|
}
|
|
|
|
async function existingSourceFiles(directory: string): Promise<string[]> {
|
|
return listSourceFiles(directory).catch((error: NodeJS.ErrnoException) => {
|
|
if (error.code === "ENOENT") return [];
|
|
throw error;
|
|
});
|
|
}
|
|
|
|
const sourceDirectories = [
|
|
...commonDirectories,
|
|
...(await featurePresentationDirectories(sourceRoot)),
|
|
].map((directory) => path.join(sourceRoot, directory));
|
|
const sources = (
|
|
await Promise.all(sourceDirectories.map(existingSourceFiles))
|
|
).flat();
|
|
|
|
async function rawFailureRenders(files: readonly string[]): Promise<string[]> {
|
|
const found: string[] = [];
|
|
for (const file of files) {
|
|
if (rawFailureRender.test(await readFile(file, "utf8"))) {
|
|
found.push(`raw backend/error message rendered in ${file}`);
|
|
}
|
|
}
|
|
return found;
|
|
}
|
|
|
|
/** ESLint errors in a fixture tree, one entry per error, ending in the file. */
|
|
async function lintErrors(root: string): Promise<string[]> {
|
|
const { ESLint } = await import("eslint");
|
|
const results = await new ESLint({ ignore: false }).lintFiles([root]);
|
|
return results.flatMap((result) =>
|
|
result.messages
|
|
.filter((message) => message.severity === 2)
|
|
.map(
|
|
(message) =>
|
|
`${message.ruleId ?? "eslint"} ${message.line}:${message.column} ${message.message} in ${path.relative(process.cwd(), result.filePath)}`,
|
|
),
|
|
);
|
|
}
|
|
|
|
failures.push(...(await rawFailureRenders(sources)));
|
|
if (fixtureMode) failures.push(...(await lintErrors(forbiddenFixtureRoot)));
|
|
const allowedFixtureFailures = fixtureMode
|
|
? [
|
|
...(await rawFailureRenders(await listSourceFiles(allowedFixtureRoot))),
|
|
...(await lintErrors(allowedFixtureRoot)),
|
|
]
|
|
: [];
|
|
|
|
const report = i18nReportArtifactSchema.parse({
|
|
schemaVersion: 1,
|
|
mode: fixtureMode ? "negative-fixture" : "source",
|
|
localeCount: Object.keys(MESSAGE_CATALOGS).length + 1,
|
|
messageKeyCount: Object.keys(KO_MESSAGES).length,
|
|
checkedFiles: sources.length,
|
|
failures,
|
|
passed: failures.length === 0,
|
|
});
|
|
await mkdir("artifacts/quality", { recursive: true });
|
|
await writeValidatedJsonArtifact({
|
|
path: fixtureMode
|
|
? "artifacts/quality/i18n-fixture.json"
|
|
: "artifacts/quality/i18n.json",
|
|
schema: i18nReportArtifactSchema,
|
|
value: report,
|
|
});
|
|
|
|
// Every fixture file must be rejected on its own; one rejected file must not
|
|
// hide a directory the discovery above stopped reaching.
|
|
const fixtureFiles = fixtureMode ? await listSourceFiles(sourceRoot) : [];
|
|
const unrejectedFixtures = fixtureFiles.filter(
|
|
(file) => !failures.some((failure) => failure.endsWith(file)),
|
|
);
|
|
if (fixtureMode && (fixtureFiles.length === 0 || unrejectedFixtures.length > 0)) {
|
|
process.stderr.write(
|
|
`I18n fixture was not rejected:\n${unrejectedFixtures.join("\n") || "(no fixture files found)"}\n`,
|
|
);
|
|
process.exit(2);
|
|
}
|
|
// A comment, punctuation or catalog words must not be rejected (0929/08-02).
|
|
if (allowedFixtureFailures.length > 0) {
|
|
process.stderr.write(
|
|
`I18n allowed fixture was rejected:\n${allowedFixtureFailures.join("\n")}\n`,
|
|
);
|
|
process.exit(2);
|
|
}
|
|
|
|
if (failures.length > 0) {
|
|
process.stderr.write(`I18n contract failed:\n${failures.join("\n")}\n`);
|
|
process.exit(1);
|
|
}
|
|
process.stdout.write(
|
|
`I18n contract: ${report.messageKeyCount} keys across ${report.localeCount} locales PASS\n`,
|
|
);
|