Merge pull request 'feat(scale): precache 상한을 기능 모양 기록에 재고 R9-D7 후보 ID를 태그로 적는다' (#44) from donghyeon.kang/fix/r9-precache-bound-diagnostics into main
frontend-quality-gates / merge / static checks (push) Canceled after 0s
frontend-quality-gates / merge / tests (push) Canceled after 0s
frontend-quality-gates / merge / browser tests (push) Canceled after 0s
frontend-quality-gates / FE-GATE-014 / config-compatibility (push) Canceled after 0s
frontend-quality-gates / FE-GATE-028 / manual-accessibility-review (push) Canceled after 0s
frontend-quality-gates / FE-GATE-026 / lab-performance (push) Canceled after 0s
frontend-quality-gates / FE-GATE-015 / immutable-release-candidate (push) Canceled after 0s
frontend-quality-gates / external-vulnerability-provider (push) Canceled after 0s
frontend-quality-gates / external-provenance-provider (push) Canceled after 0s
frontend-quality-gates / promote-verified-immutable-candidate (push) Canceled after 0s
frontend-quality-gates / deploy-promoted-release (push) Canceled after 0s
frontend-quality-gates / FE-GATE-019 / hosting-header (push) Canceled after 0s
frontend-quality-gates / FE-GATE-021 / runbook-boot-config (push) Canceled after 0s
frontend-quality-gates / FE-GATE-022 / runbook-chunk-mismatch (push) Canceled after 0s
frontend-quality-gates / FE-GATE-023 / runbook-api-degradation (push) Canceled after 0s
frontend-quality-gates / FE-GATE-024 / runbook-telemetry (push) Canceled after 0s
frontend-quality-gates / FE-GATE-025 / runbook-release-rollback (push) Canceled after 0s
frontend-quality-gates / FE-GATE-018 / field-web-vitals (push) Canceled after 0s
frontend-quality-gates / FE-GATE-017 / diagram-review (push) Canceled after 0s
frontend-quality-gates / main / self-tests and removal drills (push) Canceled after 0s

This commit was merged in pull request #44.
This commit is contained in:
2026-11-13 08:28:36 +00:00
6 changed files with 198 additions and 26 deletions
+13 -1
View File
@@ -5,7 +5,7 @@
"contextMaxFeatures": 200,
"appMaxContexts": 20
},
"summary": "상한은 개수를 제한할 뿐, 검증된 수용량이 아니다. 앱 하나의 실제 한계는 먼저 초기 JavaScript budget이고, 그다음 typecheck 메모리다. 400개 feature는 재지 않았다(D-18이 선택 사항으로 둔다).",
"summary": "상한은 개수를 제한할 뿐, 검증된 수용량이 아니다. 앱 하나의 실제 한계는 먼저 초기 JavaScript budget이고, 그다음 typecheck 메모리다. Service Worker를 켜면(SERVICE_WORKER: ACTIVE) 그 전에 precache 자산 수 상한(SERVICE_WORKER_BOUNDS.assets)이 올 수 있다. 기능마다 lazy 청크가 늘고 그 전부를 precache하기 때문이다. 기능 하나가 더하는 파일 수는 아래 serviceWorkerPrecache에 있다. 400개 feature는 재지 않았다(D-18이 선택 사항으로 둔다).",
"axes": [
{
"axis": "Typecheck of one app",
@@ -31,6 +31,12 @@
"condition": "위와 같음",
"notVerified": "lazy 파일이 많을 때의 다운로드 비용"
},
{
"axis": "Service Worker precache",
"verified": "Service Worker를 켜면(SERVICE_WORKER: ACTIVE) dist/assets의 해시 파일을 모두 precache한다. 아래 serviceWorkerPrecache에 지금 템플릿 빌드의 파일 수(assets), 첫 feature가 한 번 더하는 수(firstFeatureAssets), 기존 context에 feature 하나를 더할 때 느는 수(perFeatureAssets), 두 번째 context가 더하는 수(perContextAssets)가 있다. tests/unit/feature-shape-growth.test.ts가 unit 실행마다 Initial JavaScript와 같은 빌드로 잰다",
"condition": "Initial JavaScript와 같은 빌드. 그 빌드는 Service Worker를 끈 것이라, 켠 빌드는 등록 코드의 파일만큼 더 많다",
"notVerified": "feature가 몇 개까지 precache 자산 수 상한(src/contracts/service-worker.ts의 SERVICE_WORKER_BOUNDS.assets) 안에 드는지. 상한에서 assets와 firstFeatureAssets를 빼고 perFeatureAssets로 나눈 값이다(새 context마다 perContextAssets를 더한다). 상한과 precache 범위는 Service Worker 계약이다"
},
{
"axis": "Routes",
"verified": "feature 하나에 3개(list, detail, create). 충돌 없이 조합된다",
@@ -44,5 +50,11 @@
"firstFeatureGzipBytes": 6355,
"perFeatureGzipBytes": 528,
"perContextGzipBytes": 21
},
"serviceWorkerPrecache": {
"assets": 24,
"firstFeatureAssets": 14,
"perFeatureAssets": 12,
"perContextAssets": 0
}
}
+1 -1
View File
@@ -64,7 +64,7 @@
| round9 R9-D4 짝 계약 pin | 2026-11-12 | 권하는 안으로 정함(2026-11-12, 총괄). pin을 짝 백엔드 main으로 옮기고 drift 5건을 대조한다. 버린 안: 문서만 pin 기준으로 | 같음, 1112/02-05·08-18 |
| round9 R9-D5 `loadingSurface` | 2026-11-12 | 권하는 안으로 정함(2026-11-12, 총괄). 계약 값은 그대로, 매뉴얼·렌즈 문장을 실제 동작(로딩 모양을 고르지 않는 이름표)에 맞춘다. 버린 안: 닫힌 union으로 계약 변경 | 같음, 1112/04-04 |
| round9 R9-D6 primitive `className`·`style` | 2026-11-12 | 권하는 안으로 정함(2026-11-12, 총괄). 공개 props는 그대로 두고 `check:design-system`이 호출부의 날 색·간격을 잡는다(비파괴). 버린 안: `style` 제거(BREAKING) | 같음, 1112/04-14 |
| round9 R9-D7 수동 접근성 후보 ID | 2026-11-12 | 권하는 안으로 정함(2026-11-12, 총괄). FE-GATE-028이 기록의 Release ID를 release 후보 ID와 대조한다. workflow 쪽은 CI 세션이 맞춘다. 버린 안: 그대로 | 같음, 1112/05-01 |
| round9 R9-D7 수동 접근성 후보 ID | 2026-11-12 | 권하는 안으로 정함(2026-11-12, 총괄). FE-GATE-028이 기록의 Release ID를 release 후보 ID와 대조한다. 후보 ID는 릴리스 태그다(2026-11-13 세부: release 단계 env `RELEASE_TAG`, 비면 실패. 빌드의 `releaseId`는 run마다 달라 쓰지 않는다). workflow 쪽은 CI 세션이 맞춘다. 버린 안: 그대로 | 같음, 1112/05-01 |
| round9 R9-D8 시각 골든 허용치 | 2026-11-12 | 권하는 안으로 정함(2026-11-12, 총괄). 실험으로 흔들림 없는 값을 재서 낮춘다(검사 강화). 버린 안: 그대로 | 같음, 1112/04-11 |
| round9 R9-D9 WCAG 2.2 | 2026-11-12 | 권하는 안으로 정함(2026-11-12, 총괄). axe `wcag22aa` 태그를 더하고, 수동 기록 양식에 2.4.11·2.5.8 칸을 더한다(생성 출력이 바뀐다, CHANGELOG 안내). 버린 안: 태그만 | 같음, 1112/05-05 |
| round9 R9-D10 예산과 advisory | 2026-11-12 | 권하는 안으로 정함(2026-11-12, 총괄). D1을 먼저 정한다: zod·react-router 갱신이 지금 초기 JS 예산 안에 들어가므로 갱신하고, 드릴을 다시 재서 D9 규칙으로 예산을 정한다. 버린 안: 예산만 먼저 내림 | 같음, 1106/15-01, 1103/13-03 |
+34 -9
View File
@@ -69,13 +69,8 @@ export async function collectStaticAssets(
const assets: StaticAssetManifestV1["assets"][number][] = [];
for (const relative of files.sort()) {
const base = path.basename(relative);
if (!relative.split(path.sep).join("/").startsWith(BUILD_ASSET_DIRECTORY)) {
continue;
}
if (EXCLUDED_FILES.has(base)) continue;
const contentType = CACHEABLE_EXTENSIONS[path.extname(base).toLowerCase()];
if (!contentType || !HASHED_NAME.test(base)) continue;
const contentType = precachedContentType(relative);
if (!contentType) continue;
const absolute = path.join(distDirectory, relative);
const bytes = await readFile(absolute);
@@ -99,12 +94,19 @@ export async function collectStaticAssets(
});
}
// 1112/06-02. The count and the bound, so the failure says how far over
// it is. Each generated feature adds its lazy chunks here: with the Service
// Worker on, the asset bound can come before the initial JavaScript budget.
if (assets.length > SERVICE_WORKER_BOUNDS.assets) {
throw new Error("Static asset count exceeds its bound.");
throw new Error(
`Static asset count ${assets.length} exceeds its bound ${SERVICE_WORKER_BOUNDS.assets} (SERVICE_WORKER_BOUNDS.assets, src/contracts/service-worker.ts): every hashed file under ${BUILD_ASSET_DIRECTORY} is precached.`,
);
}
const totalBytes = assets.reduce((sum, asset) => sum + asset.bytes, 0);
if (totalBytes > SERVICE_WORKER_BOUNDS.assetSetBytes) {
throw new Error("Static asset set exceeds its byte bound.");
throw new Error(
`Static asset set ${totalBytes} bytes exceeds its byte bound ${SERVICE_WORKER_BOUNDS.assetSetBytes} (SERVICE_WORKER_BOUNDS.assetSetBytes, src/contracts/service-worker.ts).`,
);
}
// SW-05. The canonical byte serialization lives in the shared runtime-neutral
@@ -133,6 +135,29 @@ export async function collectStaticAssets(
}
/**
* The content type of a dist file the worker precaches, or undefined: a
* content-hashed name with a cacheable type under `BUILD_ASSET_DIRECTORY`,
* not one of `EXCLUDED_FILES`.
*/
function precachedContentType(relative: string): string | undefined {
const base = path.basename(relative);
if (!relative.split(path.sep).join("/").startsWith(BUILD_ASSET_DIRECTORY)) return undefined;
if (EXCLUDED_FILES.has(base) || !HASHED_NAME.test(base)) return undefined;
return CACHEABLE_EXTENSIONS[path.extname(base).toLowerCase()];
}
/**
* 1112/06-02. How many files of a dist the worker would precache, by the
* rule collectStaticAssets applies, without its bounds. The feature-shape
* measurement records it per feature.
*/
export async function countPrecachedAssets(distDirectory: string): Promise<number> {
return (await walk(distDirectory, distDirectory)).filter(
(relative) => precachedContentType(relative) !== undefined,
).length;
}
async function walk(root: string, current: string): Promise<string[]> {
const entries = await readdir(current, { withFileTypes: true });
const files: string[] = [];
+53 -11
View File
@@ -7,6 +7,7 @@ import { gzipSync } from "node:zlib";
import { PLATFORM_ROUTE_REGISTRY } from "../../src/contracts/routes.ts";
import { planFeature, type InstalledFacts } from "../create-feature.ts";
import { countPrecachedAssets } from "../generate-service-worker-assets.ts";
import { classifyViteJavascript } from "../lib/classify-vite-bundle.ts";
import { linkFixtureNodeModules } from "../lib/fixture-node-modules.ts";
import { VITE_BUILD_INPUTS } from "../lib/vite-build-inputs.ts";
@@ -192,14 +193,18 @@ async function javascriptGzipBytes(root: string, files: readonly string[]) {
async function measureInitialJavascript(
features: number,
featuresPerContext = FEATURES_PER_CONTEXT,
): Promise<Readonly<{ gzipBytes: number; files: number }>> {
): Promise<Readonly<{ gzipBytes: number; files: number; precacheAssets: number }>> {
const root = await createFixture(features, featuresPerContext);
try {
run(process.execPath, [path.resolve("scripts/generate-product-feature-index.ts"), `--root=${root}`], root);
run(path.resolve("node_modules/.bin/vite"), ["build", "--logLevel", "error"], root);
const manifest = JSON.parse(await readFile(path.join(root, "dist/.vite/manifest.json"), "utf8"));
const { initialFiles } = classifyViteJavascript(manifest);
return { gzipBytes: await javascriptGzipBytes(root, initialFiles), files: initialFiles.length };
return {
gzipBytes: await javascriptGzipBytes(root, initialFiles),
files: initialFiles.length,
precacheAssets: await countPrecachedAssets(path.join(root, "dist")),
};
} finally {
await rm(root, { recursive: true, force: true });
}
@@ -224,20 +229,55 @@ export type InitialJavascriptCosts = Readonly<{
perContextGzipBytes: number;
}>;
export async function measureInitialJavascriptCosts(): Promise<InitialJavascriptCosts> {
/**
* 1112/06-02. With the Service Worker on, it precaches every hashed file
* under `assets/` (collectStaticAssets), so each feature's lazy chunks count
* towards the precache asset bound (`SERVICE_WORKER_BOUNDS.assets`). The
* same builds as the initial JavaScript, counted by the worker's rule. The
* builds leave the worker off: a build with it on adds the files of its own
* registration code.
*/
export type PrecacheCosts = Readonly<{
assets: number;
firstFeatureAssets: number;
perFeatureAssets: number;
perContextAssets: number;
}>;
export type FeatureShapeCosts = Readonly<{
initialJavascript: InitialJavascriptCosts;
serviceWorkerPrecache: PrecacheCosts;
}>;
export async function measureFeatureShapeCosts(): Promise<FeatureShapeCosts> {
const none = await measureInitialJavascript(0);
const one = await measureInitialJavascript(1);
const twoInOneContext = await measureInitialJavascript(2);
const twoInTwoContexts = await measureInitialJavascript(2, 1);
return {
gzipBytes: none.gzipBytes,
files: none.files,
firstFeatureGzipBytes: one.gzipBytes - none.gzipBytes,
perFeatureGzipBytes: twoInOneContext.gzipBytes - one.gzipBytes,
perContextGzipBytes: twoInTwoContexts.gzipBytes - twoInOneContext.gzipBytes,
initialJavascript: {
gzipBytes: none.gzipBytes,
files: none.files,
firstFeatureGzipBytes: one.gzipBytes - none.gzipBytes,
perFeatureGzipBytes: twoInOneContext.gzipBytes - one.gzipBytes,
perContextGzipBytes: twoInTwoContexts.gzipBytes - twoInOneContext.gzipBytes,
},
serviceWorkerPrecache: {
assets: none.precacheAssets,
firstFeatureAssets: one.precacheAssets - none.precacheAssets,
perFeatureAssets: twoInOneContext.precacheAssets - one.precacheAssets,
perContextAssets: twoInTwoContexts.precacheAssets - twoInOneContext.precacheAssets,
},
};
}
/** 1112/06-02. Fields of the precache record that differ from the build: counts are exact. */
export function precacheRecordDrift(measured: PrecacheCosts, record: PrecacheCosts): string[] {
return (Object.keys(measured) as (keyof PrecacheCosts)[])
.filter((field) => record[field] !== measured[field])
.map((field) => `${field}: record ${record[field]}, build ${measured[field]}`);
}
/**
* 1105/15-02. How far the total may be from the record, in gzip bytes. The
* total moves by tens of bytes with the build id (CI and local builds
@@ -364,11 +404,13 @@ function version(bin: string): string {
* the initial JavaScript.
*/
async function writeInitialBaseline(): Promise<void> {
const measured = await measureInitialJavascriptCosts();
process.stdout.write(`initial JavaScript: ${JSON.stringify(measured)}\n`);
const measured = await measureFeatureShapeCosts();
process.stdout.write(`initial JavaScript: ${JSON.stringify(measured.initialJavascript)}\n`);
process.stdout.write(`service worker precache: ${JSON.stringify(measured.serviceWorkerPrecache)}\n`);
if (!process.argv.includes("--write")) return;
const ceilings = JSON.parse(await readFile(FEATURE_SHAPE_CEILINGS_PATH, "utf8")) as Record<string, unknown>;
ceilings["initialJavascript"] = measured;
ceilings["initialJavascript"] = measured.initialJavascript;
ceilings["serviceWorkerPrecache"] = measured.serviceWorkerPrecache;
await writeFile(FEATURE_SHAPE_CEILINGS_PATH, `${JSON.stringify(ceilings, null, 2)}\n`);
process.stdout.write(`feature-shape initial baseline: ${FEATURE_SHAPE_CEILINGS_PATH}\n`);
}
+26 -4
View File
@@ -7,11 +7,13 @@ import {
FEATURE_SHAPE_CEILINGS_PATH,
FEATURES_PER_CONTEXT,
initialJavascriptRecordDrift,
measureInitialJavascriptCosts,
measureFeatureShapeCosts,
planShapeFeatures,
precacheRecordDrift,
SHAPE_FEATURE_COMMAND,
shapeFeature,
type InitialJavascriptCosts,
type PrecacheCosts,
} from "../../scripts/scale/measure-feature-shape-growth.ts";
import { APP_MAX_CONTEXTS } from "../../src/apps/template-app/app-module.ts";
import { childProcessTimeout } from "../helpers/child-process-timeout.ts";
@@ -151,12 +153,23 @@ describe("feature-shape growth measurement (11-04)", () => {
* hand, it went stale twice; it now has to match this build.
*/
it("bounds what one more feature and one more context add, and matches the record (15-01)", async () => {
const measured = await measureInitialJavascriptCosts();
const { initialJavascript: record } = JSON.parse(
const { initialJavascript: measured, serviceWorkerPrecache: precache } =
await measureFeatureShapeCosts();
const { initialJavascript: record, serviceWorkerPrecache: precacheRecord } = JSON.parse(
await readFile(FEATURE_SHAPE_CEILINGS_PATH, "utf8"),
) as { initialJavascript: InitialJavascriptCosts };
) as { initialJavascript: InitialJavascriptCosts; serviceWorkerPrecache?: PrecacheCosts };
const observed = `measured ${JSON.stringify(measured)}`;
// 1112/06-02. With the Service Worker on, each feature's lazy chunks are
// precached too; the record says how many, so the feature count where
// the precache asset bound comes is read, not guessed.
expect(precache.perFeatureAssets, `precache ${JSON.stringify(precache)}`).toBeGreaterThan(0);
expect(
precacheRecord === undefined ? ["serviceWorkerPrecache: no record"] : precacheRecordDrift(precache, precacheRecord),
`${FEATURE_SHAPE_CEILINGS_PATH} serviceWorkerPrecache is stale (measured ${JSON.stringify(precache)}); ` +
"rewrite it with node scripts/scale/measure-feature-shape-growth.ts --initial-baseline --write",
).toEqual([]);
expect(measured.perFeatureGzipBytes, `one more feature in an existing context: ${observed}`)
.toBeLessThanOrEqual(1_024);
expect(measured.perContextGzipBytes, `one more context: ${observed}`)
@@ -175,6 +188,15 @@ describe("feature-shape growth measurement (11-04)", () => {
* record. Now a few hundred bytes are enough to fail: above the build id
* spread (tens of bytes), below one feature.
*/
// 1112/06-02. File counts repeat exactly: any difference is a stale record.
it("reports a precache record that differs from the build by one file", () => {
const measured = { assets: 20, firstFeatureAssets: 12, perFeatureAssets: 9, perContextAssets: 1 };
expect(precacheRecordDrift(measured, measured)).toEqual([]);
expect(precacheRecordDrift({ ...measured, perFeatureAssets: 10 }, measured)).toEqual([
"perFeatureAssets: record 9, build 10",
]);
});
it("reports a record a few hundred bytes off the build, or a different file count", () => {
const measured = {
gzipBytes: 200_000,
@@ -0,0 +1,71 @@
import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
import path from "node:path";
import { afterEach, describe, expect, it } from "vitest";
import {
collectStaticAssets,
countPrecachedAssets,
} from "../../scripts/generate-service-worker-assets.ts";
import { SERVICE_WORKER_BOUNDS } from "../../src/contracts/service-worker.ts";
/**
* 1112/06-02. With the Service Worker on, a product with about 25 generated
* features passes the precache asset bound and the build stops. The failure
* said "Static asset count exceeds its bound." with neither the count nor
* the bound, so nobody could tell how far over it was or which number to
* look up.
*/
const roots: string[] = [];
afterEach(async () => {
await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
});
async function distWith(count: number, bytes = 16): Promise<string> {
const root = await mkdtemp(path.join(tmpdir(), "sw-asset-bounds-"));
roots.push(root);
await mkdir(path.join(root, "assets"), { recursive: true });
for (let index = 0; index < count; index += 1) {
await writeFile(path.join(root, "assets", `chunk${index}-Abcdefgh.js`), "x".repeat(bytes));
}
return root;
}
describe("Service Worker precache bounds", () => {
it("names the count and the bound when there are too many assets", async () => {
const over = SERVICE_WORKER_BOUNDS.assets + 1;
const dist = await distWith(over);
await expect(collectStaticAssets(dist, "build-1", "release-1")).rejects.toThrow(
new RegExp(`${over}\\b.*\\b${SERVICE_WORKER_BOUNDS.assets}\\b`, "u"),
);
});
it("names the bytes and the bound when the set is too large", async () => {
const each = SERVICE_WORKER_BOUNDS.singleAssetBytes;
const count = Math.ceil(SERVICE_WORKER_BOUNDS.assetSetBytes / each) + 1;
const dist = await distWith(count, each);
await expect(collectStaticAssets(dist, "build-1", "release-1")).rejects.toThrow(
new RegExp(`\\b${count * each}\\b.*\\b${SERVICE_WORKER_BOUNDS.assetSetBytes}\\b`, "u"),
);
});
});
// 1112/06-02. The feature-shape measurement counts what the worker would
// precache with the same rule: hashed names under assets/ with a cacheable
// type, the worker, the page and public files left out.
describe("countPrecachedAssets", () => {
it("counts the files collectStaticAssets precaches", async () => {
const dist = await distWith(3);
await writeFile(path.join(dist, "index.html"), "<html></html>");
await writeFile(path.join(dist, "android-chrome-192x192.png"), "png");
await writeFile(path.join(dist, "assets", "unhashed.js"), "x");
await writeFile(path.join(dist, "assets", "notes-Abcdefgh.txt"), "x");
const { assets } = await collectStaticAssets(dist, "build-1", "release-1");
expect(await countPrecachedAssets(dist)).toBe(assets.length);
expect(assets).toHaveLength(3);
});
});