chore(review): 1105 성능·구조 조치 브랜치를 합친다

합치며 고친 것: 두 브랜치가 따로는 맞고 합치면 어긋나는 곳 둘.
- 1105/12-04(실행 격리 브랜치)는 `vite.config.ts`가
  `scripts/lib/run-isolation.ts`를 가져오게 해, 저장소를 임시 루트에 복사해
  빌드하는 두 목록(`scripts/scale/measure-feature-shape-growth.ts`,
  `tests/unit/product-feature-selection-build.test.ts`)에 그 파일을 더했다.
  1105/15-03(이 브랜치)은 두 목록을 `scripts/lib/vite-build-inputs.ts` 하나로
  옮겼다. 두 파일의 충돌은 15-03 쪽으로 풀고, 옮긴 목록에
  `scripts/lib/run-isolation.ts`를 더한다. 더하지 않으면
  `tests/unit/vite-build-inputs.test.ts`가 그 파일 이름을 대며 실패하고,
  임시 루트 빌드 두 곳이 "Could not resolve './scripts/lib/run-isolation.ts'"로
  실패한다.
- `scripts/lib/removal-fixture.ts`의 문서 테스트 목록에 03-01(HTTP 판정
  브랜치)과 16-01(이 브랜치)이 각자 한 줄씩 더했다. 두 줄을 모두 둔다.

검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/vite-build-inputs.test.ts tests/unit/feature-shape-growth.test.ts tests/unit/product-feature-selection-build.test.ts

Refs: 1105/12-04, 1105/15-03, 1105/03-01, 1105/16-01
This commit is contained in:
DongHyeonka
2026-11-06 02:59:02 +09:00
43 changed files with 1151 additions and 110 deletions
+36 -8
View File
@@ -18,25 +18,41 @@ import {
* 1. the table excerpt (`tables.backendExcerpt`) is word for word the
* backend document's tables at the pinned commit,
* 2. the answer table JSON matches that excerpt (test:unit checks this too),
* 3. the document has not changed between the pin and the backend's HEAD.
* 3. the document has not changed between the pin and the backend's HEAD,
* 4. 1105/16-02: neither have the backend scaffold files
* (`backend.scaffoldSources`) that `create:feature --with-create` copies
* four facts from (path plural rule, name limit, error codes, check
* order). Each changed file names the frontend copy to recheck.
*
* corepack pnpm check:backend-contract-drift [--backend <dir>] [--write-excerpt]
*
* `--write-excerpt` copies the excerpt from the pinned commit first: run it
* after moving the pin, then fix the answer table until this passes.
*
* Exit 0: all three hold. Exit 1: one does not; the output names the rows.
* Recheck the frontend contract 6.1 table, the answer table, the excerpt and
* the pin in one change. Exit 2: nothing was compared (no checkout, or the
* pinned commit or document is missing), which is not a pass.
* Exit 0: all four hold. Exit 1: one does not; the output names the rows or
* files. Recheck the frontend contract 6.1 table, the answer table, the
* excerpt, the generator copies and the pin in one change. Exit 2: nothing
* was compared (no checkout, or the pinned commit or document is missing),
* which is not a pass.
*
* Without `--backend` the checkout is looked for beside the main checkout of
* this repository, so a linked worktree (`.claude/worktrees/<name>`) finds
* the same one.
*/
type ScaffoldSource = Readonly<{
path: string;
fact: string;
copiedTo: Readonly<{ file: string; symbol: string }>;
}>;
type Pin = Readonly<{
backend: Readonly<{ repository: string; commit: string; document: string }>;
backend: Readonly<{
repository: string;
commit: string;
document: string;
scaffoldSources?: readonly ScaffoldSource[];
}>;
tables: Readonly<{ idempotencyAnswers: string; backendExcerpt: string }>;
notCopied: readonly NotCopiedRow[];
}>;
@@ -86,6 +102,7 @@ function main(): void {
const pin = readJson<Pin>(PIN_PATH);
const directory = backendDirectory(pin);
const { commit, document } = pin.backend;
const scaffoldSources = pin.backend.scaffoldSources ?? [];
if (!existsSync(path.join(directory, ".git"))) {
cannotCompare(
`No ${pin.backend.repository} checkout at ${directory}; pass --backend <dir>. test:unit holds the answer table to ${pin.tables.backendExcerpt}, and only this script holds that copy to the backend.`,
@@ -149,20 +166,31 @@ function main(): void {
failures.push(" (no copied table row changed; read the other changes with git diff)");
}
}
// 1105/16-02. The generator's copies of backend scaffold facts.
for (const scaffold of scaffoldSources) {
const scaffoldDiff = git(directory, "diff", "--unified=0", `${commit}..HEAD`, "--", scaffold.path);
if (scaffoldDiff.stdout.trim() === "") continue;
failures.push(
`scaffold source ${scaffold.path} changed between the pin ${commit.slice(0, 12)} and HEAD ${headCommit.slice(0, 12)}`,
);
failures.push(
` the generator copies "${scaffold.fact}" from it: recheck ${scaffold.copiedTo.symbol} in ${scaffold.copiedTo.file}`,
);
}
}
if (failures.length === 0) {
console.log(
headCommit === commit
? `Backend contract drift: ${directory} is at the pinned ${commit.slice(0, 12)}; the excerpt and the answer table match it`
: `Backend contract drift: HEAD ${headCommit.slice(0, 12)} is past the pin ${commit.slice(0, 12)}, ${document} unchanged; the excerpt and the answer table match it`,
: `Backend contract drift: HEAD ${headCommit.slice(0, 12)} is past the pin ${commit.slice(0, 12)}, ${document} and ${scaffoldSources.length} scaffold sources unchanged; the excerpt and the answer table match it`,
);
return;
}
console.error("Backend contract drift:");
for (const failure of failures) console.error(` ${failure}`);
console.error(
`Recheck docs/architecture/backend-api-and-server-state-contract.md 6.1, ${pin.tables.idempotencyAnswers}, ${pin.tables.backendExcerpt} and ${PIN_PATH} together.`,
`Recheck docs/architecture/backend-api-and-server-state-contract.md 6.1, ${pin.tables.idempotencyAnswers}, ${pin.tables.backendExcerpt}, the generator copies of changed scaffold sources and ${PIN_PATH} together.`,
);
process.exitCode = 1;
}
+6
View File
@@ -14,6 +14,12 @@
* `--keyed` is for a backend create made KEYED with its IdempotencyExecutor
* (its docs/manual/05-idempotency.md). Like the rest of the command, nothing
* here imports a sample feature.
*
* 1105/16-02. The backend scaffold facts copied here (name limit, error
* codes, 201 and the endpoints, the check order behind refusedBeforeWrite)
* and the path rule in create-feature.ts are listed with their backend
* files in config/contracts/backend-contract-pin.json `scaffoldSources`;
* `check:backend-contract-drift` says when one of those files changes.
*/
export type WriteSemantics = "NEVER" | "KEYED";
+26 -2
View File
@@ -794,8 +794,9 @@ export const ${operationId}_CONTRACT = Object.freeze({
responseBody: "REQUIRED_JSON" as const,
// The paired backend wraps every JSON body (http-contract.md §1). Every
// operation of this contribution says so (1103/16-01: composition refuses
// one that does not). Drop the line from all of them for a backend that
// sends the DTO and problem details bare.
// one that does not, and check:types one without the line). Write
// "NONE" on all of them for a backend that sends the DTO and problem
// details bare.
responseEnvelope: "ENVELOPE_V1" as const,
commandRecovery: null,
commandEffect: null,
@@ -1691,6 +1692,27 @@ async function readInstalledFacts(root: string): Promise<InstalledFacts> {
});
}
/**
* 1105/16-01. Tracked template files that change with every added feature,
* and the command that writes each. A feature branch commits them with the
* feature; two feature branches change the same lines, and the merge takes
* the command again instead of a hand-merged value. docs/manual/03 (A) and
* the "Adding a feature" table in docs/architecture/starter-experience.md
* list them (tests/unit/feature-tracked-files.test.ts).
*/
export const FEATURE_TRACKED_FILE_REWRITES = Object.freeze([
Object.freeze({
path: "public/release-manifest.json",
command: "node scripts/write-dev-release-manifest.ts",
when: "create:feature runs it: the dev server's manifest names the installed contract packages",
}),
Object.freeze({
path: "config/scale/feature-shape-ceilings.json",
command: "node scripts/scale/measure-feature-shape-growth.ts --initial-baseline --write",
when: "by hand while the sample is installed (the file goes with it): test:unit compares it with a build",
}),
]);
const USAGE =
"Usage: pnpm create:feature <id> [--context <context id>] [--with-create [--keyed]] " +
"[--package @scope/name@x.y.z --digest sha256:<64 hex> --revision <hex>]";
@@ -1752,6 +1774,8 @@ function report(plan: FeaturePlan): string {
" A failing gate's log is artifacts/quality/gates/FE-GATE-<NNN>.txt. Locally FE-GATE-013 needs VITE_COMMIT_SHA=$(git rev-parse HEAD); to run them as CI does, set CI=true and the CI build identity (README).",
" 3. The initial JavaScript changes. While config/scale/feature-shape-ceilings.json exists (the sample is installed), rewrite it with node scripts/scale/measure-feature-shape-growth.ts --initial-baseline --write and commit it with the feature; test:unit compares it with a build. corepack pnpm check:bundle checks the budget.",
" public/release-manifest.json (the dev server's manifest) now names the feature's contract package; commit it with the feature.",
" Two feature branches change the same lines of these files. On a merge conflict, take either side and run the command again:",
...FEATURE_TRACKED_FILE_REWRITES.map((file) => ` ${file.path}: ${file.command}`),
" The registry baseline does not change: new routes, operations, schemas and invalidation topics are additive.",
];
return `${lines.join("\n")}\n`;
+1
View File
@@ -287,6 +287,7 @@ async function physicalAttempts(
retrySemantics,
requestBody: read ? ("NONE" as const) : ("JSON" as const),
responseBody: "REQUIRED_JSON" as const,
responseEnvelope: "NONE" as const,
commandRecovery: null,
commandEffect: read
? null
+62
View File
@@ -0,0 +1,62 @@
import { readdir, readFile } from "node:fs/promises";
import path from "node:path";
/**
* 1105/16-04. What a product feature leaves behind after
* `test:sample-removal -- --feature=<id>` deleted its folders, in the copy the
* drill made.
*
* - `src/`: any file whose path or text still names the feature ID or its
* folder. Platform source never names a product feature, so a name left
* there is a reference the type checker cannot see (a catalog key, a
* runtime override, a link).
* - `tests/`: a file named after the feature, or one that imports from the
* feature's `src/features/<dir>/` or `tests/features/<dir>/`. The test
* text is not searched for the bare name: the template's own tests use
* example IDs as data (`tests/unit/create-feature.test.ts` writes
* `invoice-feature`, the manual's example, 51 times), and the drill flagged
* them as residue of a product feature that took that name. A test that
* still depends on the removed feature fails `test:all`, which the drill
* runs.
*
* The reference sample keeps its own, wider pattern in
* scripts/test-sample-removal.ts: the template owns all of its files.
*/
function escapeRegExp(value: string): string {
return value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
}
async function filesUnder(directory: string): Promise<string[]> {
const entries = await readdir(directory, { withFileTypes: true }).catch(() => []);
const nested = await Promise.all(
entries.map((entry) => {
const target = path.join(directory, entry.name);
return entry.isDirectory() ? filesUnder(target) : Promise.resolve([target]);
}),
);
return nested.flat();
}
export async function productFeatureResidue(
root: string,
featureId: string,
directory: string,
): Promise<string[]> {
const names = [...new Set([featureId, directory])].map(escapeRegExp).join("|");
const named = new RegExp(names, "iu");
const imported = new RegExp(
String.raw`(?:\bfrom\s*|\bimport\s*\(\s*|\bimport\s+|\bmock\s*\(\s*)["'][^"'\n]*/features/(?:${names})/`,
"u",
);
const residue: string[] = [];
const relative = (file: string) => path.relative(root, file).split(path.sep).join("/");
for (const file of await filesUnder(path.join(root, "src"))) {
const name = relative(file);
if (named.test(`${name}\n${await readFile(file, "utf8")}`)) residue.push(name);
}
for (const file of await filesUnder(path.join(root, "tests"))) {
const name = relative(file);
if (named.test(name) || imported.test(await readFile(file, "utf8"))) residue.push(name);
}
return residue.sort();
}
+44
View File
@@ -23,6 +23,50 @@ export function previewArguments(port: number): readonly string[] {
];
}
/**
* 1105/15-05. Playwright starts Chromium with `--hide-scrollbars`, so the lab
* measured layout shift in a browser without the classic scrollbar most
* Windows and Linux desktops draw. A first render that made one appear
* moved the header 15 px and the lab reported CLS 0. The lab runs with
* scrollbars, as those users see the page.
*/
export function labBrowserLaunchOptions(): { ignoreDefaultArgs: string[] } {
return { ignoreDefaultArgs: ["--hide-scrollbars"] };
}
export type LabRoute = Readonly<{
routeId: string;
path: string;
access: "public" | "session-required";
title: string;
navigationLabel: string | null;
navigationOrder: number | null;
}>;
/**
* 1105/15-04. The feature route the lab times next to its platform target:
* the first one in the navigation that an installed feature owns and a
* visitor without a session can open. The platform target loads no feature
* code, so its number stayed flat while a feature route's first entry (the
* context route module, then the page chunk) took 2.7 times as long and no
* gate measured it. `null` when no installed feature has such a route; the
* lab then records that it measured none.
*/
export function labFeatureRoute(
routes: readonly LabRoute[],
owners: Readonly<Record<string, string>>,
): LabRoute | null {
const candidates = routes.filter(
(route) =>
owners[route.routeId] !== undefined &&
route.access === "public" &&
route.navigationLabel !== null &&
route.navigationOrder !== null,
);
candidates.sort((left, right) => left.navigationOrder! - right.navigationOrder!);
return candidates[0] ?? null;
}
export type SampleSummary = Readonly<{
median: number;
min: number;
+25 -1
View File
@@ -62,10 +62,30 @@ export function describeBundleBudgetFailures(
return lines;
}
/**
* 1105/15-01. `targetDeepLinkCls` is the CLS of a direct visit to the lab's
* target route, judged against the same `cls` threshold. The click run
* cannot see a shift the target makes while it fills in: one within 500 ms
* of the click is input-driven by definition.
*/
export type LabMetrics = Readonly<{
lcpMs: number;
cls: number;
namedInteractionMs: number;
targetDeepLinkCls: number;
/**
* 1105/15-04. Click to heading on the first public navigation route an
* installed feature owns (`labFeatureRoute`). `null` when there is none:
* nothing to judge.
*/
featureRouteInteractionMs: number | null;
}>;
export type LabThresholds = Readonly<{
lcpMs: number;
cls: number;
namedInteractionMs: number;
featureRouteInteractionMs: number;
}>;
export function evaluateLabBudget(
@@ -73,7 +93,7 @@ export function evaluateLabBudget(
context?: Readonly<Record<string, unknown>>;
metrics: LabMetrics;
}>,
thresholds: LabMetrics,
thresholds: LabThresholds,
) {
const requiredContext = [
"runner",
@@ -92,6 +112,10 @@ export function evaluateLabBudget(
cls: report.metrics.cls <= thresholds.cls,
namedInteraction:
report.metrics.namedInteractionMs <= thresholds.namedInteractionMs,
targetDeepLinkCls: report.metrics.targetDeepLinkCls <= thresholds.cls,
featureRouteInteraction:
report.metrics.featureRouteInteractionMs === null ||
report.metrics.featureRouteInteractionMs <= thresholds.featureRouteInteractionMs,
};
return Object.freeze({
missingContext: Object.freeze(missingContext),
+2
View File
@@ -72,6 +72,8 @@ export const REMOVAL_FIXTURE_DOCUMENT_TESTS = Object.freeze([
"tests/unit/documentation-readiness.test.ts",
// 1105/03-01. Reads the 6.1 table of the frontend contract document.
"tests/unit/backend-contract-pin.test.ts",
// 1105/16-01. Reads the 03 manual and docs/architecture/starter-experience.md.
"tests/unit/feature-tracked-files.test.ts",
] as const);
/** The tests a fixture copied from `copyTargets` cannot run. */
+21
View File
@@ -0,0 +1,21 @@
/**
* 1105/15-03. The files `vite build` reads from the repository root, for the
* measurements and tests that copy them into a temporary root and build
* there: scripts/scale/measure-feature-shape-growth.ts (initial JavaScript
* record) and tests/unit/product-feature-selection-build.test.ts
* (`VITE_PRODUCT_FEATURES=none`). Each used to keep its own copy of this list;
* a new local import in vite.config.ts broke both, and both had to be edited
* (7f9a515, 799ab7f). tests/unit/vite-build-inputs.test.ts fails, naming the
* file, when vite.config.ts imports a local file this list does not cover.
*/
export const VITE_BUILD_INPUTS = Object.freeze([
"src",
"public",
"index.html",
"package.json",
"vite.config.ts",
"tsconfig.base.json",
"tsconfig.app.json",
"scripts/lib/run-isolation.ts",
"scripts/lib/vite-module-inventory.ts",
] as const);
+23 -23
View File
@@ -7,6 +7,7 @@ import { gzipSync } from "node:zlib";
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";
import { parseTscExtendedDiagnostics, type TscDiagnostics } from "./collect-tsc-diagnostics.ts";
/**
@@ -37,17 +38,6 @@ export const FEATURE_SHAPE_CEILINGS_PATH = "config/scale/feature-shape-ceilings.
const SOURCE_FEATURE = "src/features/reference-feature";
const FEATURES_PER_CONTEXT = 200;
const BUILD_INPUTS = [
"src",
"public",
"index.html",
"package.json",
"vite.config.ts",
"tsconfig.base.json",
"tsconfig.app.json",
"scripts/lib/run-isolation.ts",
"scripts/lib/vite-module-inventory.ts",
] as const;
// Platform-owned names that only happen to contain "reference".
const PLATFORM_TOKENS = [
"REFERENCE_FEATURE_V1",
@@ -111,7 +101,7 @@ async function copyRenamed(from: string, to: string, rename: (text: string) => s
async function createFixture(features: number): Promise<string> {
const root = await mkdtemp(path.join(tmpdir(), `feature-shape-${features}-`));
for (const input of BUILD_INPUTS) {
for (const input of VITE_BUILD_INPUTS) {
await mkdir(path.dirname(path.join(root, input)), { recursive: true });
await cp(path.resolve(input), path.join(root, input), { recursive: true });
}
@@ -226,24 +216,34 @@ export async function measureInitialJavascriptCosts(): Promise<InitialJavascript
}
/**
* Fields of the record that no longer describe the build. The total moves
* by tens of bytes with the build id (CI and local builds differ), so it may
* be 1% off; the per-feature and per-context costs are differences of builds
* with the same id but only a few hundred bytes, so 10%; the file count is
* exact.
* 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
* differ: 6 B and 48 B between recorded runs), so it cannot be exact. It
* used to be 1% of the total, 2,029 B, which is more than the room left
* under the budget (1,873 B at 8a44226) and more than one feature (768 B):
* the record and the documents that cite it could claim room that was
* gone. 256 B is above the build id spread and below one feature.
*/
export const INITIAL_JAVASCRIPT_RECORD_TOLERANCE_BYTES = 256;
/**
* Fields of the record that no longer describe the build. The total may be
* INITIAL_JAVASCRIPT_RECORD_TOLERANCE_BYTES off; the per-feature and
* per-context costs are differences of builds with the same id but only a
* few hundred bytes, so 10%; the file count is exact.
*/
export function initialJavascriptRecordDrift(
measured: InitialJavascriptCosts,
record: InitialJavascriptCosts,
): string[] {
const tolerance: Readonly<Record<keyof InitialJavascriptCosts, number>> = {
gzipBytes: 0.01,
const allowed: Readonly<Record<keyof InitialJavascriptCosts, number>> = {
gzipBytes: INITIAL_JAVASCRIPT_RECORD_TOLERANCE_BYTES,
files: 0,
perFeatureGzipBytes: 0.1,
perContextGzipBytes: 0.1,
perFeatureGzipBytes: Math.abs(measured.perFeatureGzipBytes) * 0.1,
perContextGzipBytes: Math.abs(measured.perContextGzipBytes) * 0.1,
};
return (Object.keys(tolerance) as (keyof InitialJavascriptCosts)[])
.filter((field) => Math.abs(record[field] - measured[field]) > Math.abs(measured[field]) * tolerance[field])
return (Object.keys(allowed) as (keyof InitialJavascriptCosts)[])
.filter((field) => Math.abs(record[field] - measured[field]) > allowed[field])
.map((field) => `${field}: record ${record[field]}, build ${measured[field]}`);
}
+153 -15
View File
@@ -3,18 +3,23 @@ import { mkdir, readFile } from "node:fs/promises";
import { cpus, loadavg } from "node:os";
import process from "node:process";
import { chromium, type Browser } from "@playwright/test";
import { chromium, type Browser, type Page } from "@playwright/test";
import {
assertPortUnused,
assertServedRelease,
DEFAULT_LAB_PORT,
DEFAULT_LAB_RUNS,
labBrowserLaunchOptions,
labFeatureRoute,
previewArguments,
summarizeSamples,
} from "./lib/lab-performance.ts";
import { evaluateLabBudget } from "./lib/performance-budgets.ts";
import { ROUTE_REGISTRY } from "../src/features/installed-feature-contracts.ts";
import {
ROUTE_FEATURE_OWNER,
ROUTE_REGISTRY,
} from "../src/features/installed-feature-contracts.ts";
import { labPerformanceArtifactSchema } from "./contracts/release-artifacts.ts";
import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
@@ -48,6 +53,8 @@ const targetLabel = target.navigationLabel;
if (!targetLabel) {
throw new Error("Performance route must be present in navigation.");
}
// 1105/15-04. A feature route's first entry, timed like the target.
const featureRoute = labFeatureRoute(Object.values(ROUTE_REGISTRY), ROUTE_FEATURE_OWNER);
// 11-07. A server already on the port used to be measured in place of this
// build: vite moved to another port and the gate never noticed.
@@ -77,10 +84,25 @@ async function waitForServer() {
throw new Error("Preview server did not become ready.");
}
type RunMetrics = { lcpMs: number; cls: number; namedInteractionMs: number; eventDurationMs: number | null };
type RunMetrics = {
lcpMs: number;
cls: number;
namedInteractionMs: number;
eventDurationMs: number | null;
/** 1105/15-01. CLS of a direct visit to the target route. */
targetDeepLinkCls: number;
/** 1105/15-04. Click to heading on `featureRoute`, null without one. */
featureRouteInteractionMs: number | null;
};
async function measureOnce(browser: Browser): Promise<RunMetrics> {
// Every run is a cold, isolated context.
type ClickMetrics = Omit<RunMetrics, "targetDeepLinkCls" | "featureRouteInteractionMs">;
/**
* A cold, isolated context with the lab's network and CPU throttling and the
* page-side evidence recorder. `title` is the heading whose arrival after a
* click ends the named interaction.
*/
async function openMeasuredPage(browser: Browser, title: string) {
const context = await browser.newContext({
viewport: { width: 1280, height: 720 },
});
@@ -96,7 +118,7 @@ async function measureOnce(browser: Browser): Promise<RunMetrics> {
connectionType: "cellular4g",
});
await cdp.send("Emulation.setCPUThrottlingRate", { rate: 4 });
await page.addInitScript((title: string) => {
await page.addInitScript((headingTitle: string) => {
const evidence: ContractPerformanceEvidence = {
lcpMs: 0,
cls: 0,
@@ -137,20 +159,45 @@ async function measureOnce(browser: Browser): Promise<RunMetrics> {
new MutationObserver((_records, observer) => {
if (evidence.clickAt === null) return;
const found = [...document.querySelectorAll("h1, h2")].some(
(heading) => heading.textContent?.trim() === title,
(heading) => heading.textContent?.trim() === headingTitle,
);
if (found) {
evidence.headingAt = performance.now();
observer.disconnect();
}
}).observe(document, { childList: true, subtree: true, characterData: true });
}, target.title);
}, title);
return { context, page };
} catch (error) {
await context.close();
throw error;
}
}
/** The evidence once the layout-shift observer has delivered its entries. */
async function settledEvidence(page: Page) {
return page.evaluate(async () => {
// Observer callbacks run as tasks after the frame that recorded them.
await new Promise((resolve) => requestAnimationFrame(() => requestAnimationFrame(resolve)));
await new Promise((resolve) => setTimeout(resolve, 0));
return (window as ContractPerformanceWindow).__contractPerformance;
});
}
/** From `/`, a click on `route`'s navigation link to its heading. */
async function measureClick(
browser: Browser,
route: Readonly<{ title: string; navigationLabel: string }>,
): Promise<ClickMetrics> {
// Every run is a cold, isolated context.
const { context, page } = await openMeasuredPage(browser, route.title);
try {
await page.goto(baseUrl, { waitUntil: "networkidle" });
// Playwright matches accessible names by substring, so the navigation entry
// "플랫폼 구성" also matched the home page's "플랫폼 구성 보기" call to
// action; `exact` keeps the locator on the navigation link.
await page.getByRole("link", { name: targetLabel, exact: true }).click();
await page.getByRole("heading", { name: target.title }).waitFor();
await page.getByRole("link", { name: route.navigationLabel, exact: true }).click();
await page.getByRole("heading", { name: route.title }).waitFor();
await page.waitForFunction(
() => (window as ContractPerformanceWindow).__contractPerformance?.headingAt !== null,
);
@@ -172,6 +219,28 @@ async function measureOnce(browser: Browser): Promise<RunMetrics> {
}
}
/**
* 1105/15-01. The click run cannot see a shift the target screen makes while
* it fills in: a shift within 500 ms of the click has `hadRecentInput` and
* is left out of CLS by definition, and the lab only opened `/`. The target
* screen used to push its content 21 px after its title (CLS 0.0046) and the
* lab reported 0. A direct visit has no input, so every shift until the
* network is idle after the heading counts.
*/
async function measureTargetDeepLink(browser: Browser): Promise<number> {
const { context, page } = await openMeasuredPage(browser, target.title);
try {
await page.goto(new URL(target.path, baseUrl).href, { waitUntil: "networkidle" });
await page.getByRole("heading", { name: target.title, exact: true }).waitFor();
await page.waitForLoadState("networkidle");
const evidence = await settledEvidence(page);
if (!evidence) throw new Error("Browser performance evidence was not initialized.");
return Number(evidence.cls.toFixed(4));
} finally {
await context.close();
}
}
const load = () => loadavg().map((value) => Math.round(value * 100) / 100);
try {
@@ -183,11 +252,26 @@ try {
const thresholds = JSON.parse(
await readFile("config/performance/budgets.json", "utf8"),
).lab;
const browser = await chromium.launch();
const browser = await chromium.launch(labBrowserLaunchOptions());
try {
const loadBefore = load();
const samples: RunMetrics[] = [];
for (let run = 0; run < runs; run += 1) samples.push(await measureOnce(browser));
for (let run = 0; run < runs; run += 1) {
const click = await measureClick(browser, { title: target.title, navigationLabel: targetLabel });
const targetDeepLinkCls = await measureTargetDeepLink(browser);
const featureClick =
featureRoute === null
? null
: await measureClick(browser, {
title: featureRoute.title,
navigationLabel: featureRoute.navigationLabel!,
});
samples.push({
...click,
targetDeepLinkCls,
featureRouteInteractionMs: featureClick?.namedInteractionMs ?? null,
});
}
const loadAfter = load();
// The served build must not have changed under the runs either.
await assertServedRelease(baseUrl, release);
@@ -196,6 +280,13 @@ try {
const interaction = summarizeSamples(
samples.map((sample) => sample.namedInteractionMs),
);
const deepLinkCls = summarizeSamples(
samples.map((sample) => sample.targetDeepLinkCls),
);
const featureSamples = samples.flatMap((sample) =>
sample.featureRouteInteractionMs === null ? [] : [sample.featureRouteInteractionMs],
);
const featureInteraction = featureSamples.length ? summarizeSamples(featureSamples) : null;
const eventDurations = samples.flatMap((sample) =>
sample.eventDurationMs === null ? [] : [sample.eventDurationMs],
);
@@ -208,7 +299,12 @@ try {
logicalCpus: cpus().length,
loadAverage: { before: loadBefore, after: loadAfter },
},
browser: { name: "chromium", version: await browser.version() },
// 1105/15-05. Classic scrollbars, not Playwright's hidden ones.
browser: {
name: "chromium",
version: await browser.version(),
scrollbars: "visible",
},
viewport: { width: 1280, height: 720 },
network: {
profile: "contract-fast-4g",
@@ -235,12 +331,32 @@ try {
clickEventDurationMs: eventDurations.length
? summarizeSamples(eventDurations)
: null,
// 1105/15-01. A cold direct visit to the target route in each run.
targetDeepLink: {
path: target.path,
clock: "navigation start to network idle after the target heading",
cls: deepLinkCls,
},
// 1105/15-04. The first public navigation route a feature owns, from
// `/` by its navigation link, with the same clock.
featureRoute:
featureRoute === null || featureInteraction === null
? { measured: false, reason: "no installed feature owns a public navigation route" }
: {
measured: true,
routeId: featureRoute.routeId,
path: featureRoute.path,
owner: ROUTE_FEATURE_OWNER[featureRoute.routeId] ?? null,
interactionMs: featureInteraction,
},
},
};
const metrics = {
lcpMs: lcp.median,
cls: cls.median,
namedInteractionMs: interaction.median,
targetDeepLinkCls: deepLinkCls.median,
featureRouteInteractionMs: featureInteraction?.median ?? null,
};
const result = evaluateLabBudget(
{ context: contextMetadata, metrics },
@@ -261,6 +377,20 @@ try {
thresholds,
).passed,
},
// 1105/15-04. The feature route budget can fail.
{
name: "feature-route-over-threshold",
passed: !evaluateLabBudget(
{
context: contextMetadata,
metrics: {
...metrics,
featureRouteInteractionMs: thresholds.featureRouteInteractionMs + 1,
},
},
thresholds,
).passed,
},
];
const passed = result.passed && fixtures.every((fixture) => fixture.passed);
await mkdir("artifacts/performance", { recursive: true });
@@ -280,12 +410,20 @@ try {
if (!passed) {
throw new Error(
`Lab performance failed (median of ${runs}): ${JSON.stringify(metrics)}; ` +
`interaction samples ${interaction.samples.join(",")}`,
`interaction samples ${interaction.samples.join(",")}` +
(featureInteraction === null
? ""
: `; feature route samples ${featureInteraction.samples.join(",")}`),
);
}
process.stdout.write(
`Lab performance: PASS, median of ${runs} (LCP ${metrics.lcpMs}ms, CLS ${metrics.cls}, interaction ${metrics.namedInteractionMs}ms ` +
`[${interaction.min}-${interaction.max}])\n`,
`[${interaction.min}-${interaction.max}], ${target.path} direct CLS ${metrics.targetDeepLinkCls} ` +
`[${deepLinkCls.min}-${deepLinkCls.max}], ` +
(featureRoute === null || featureInteraction === null
? "no feature route measured)\n"
: `feature route ${featureRoute.routeId} ${featureInteraction.median}ms ` +
`[${featureInteraction.min}-${featureInteraction.max}])\n`),
);
} finally {
await browser.close();
+13 -6
View File
@@ -11,6 +11,7 @@ import path from "node:path";
import { ROUTE_FEATURE_OWNER } from "../src/features/installed-feature-contracts.ts";
import { createFileSystemDeclarationSource } from "./generate-product-feature-index.ts";
import { productFeatureResidue } from "./lib/feature-residue.ts";
import { isProductionModulePath } from "./lib/risk-coverage.ts";
import {
createRemovalFixtureRoot,
@@ -419,14 +420,20 @@ try {
await regenerateRemovalFixtureWorkflow(fixtureRoot);
const residue: string[] = [];
for (const root of ["src", "tests"]) {
for (const file of await filesBelow(path.join(fixtureRoot, root))) {
const relative = path.relative(fixtureRoot, file);
const content = await readFile(file, "utf8");
if (extras.residue.test(`${relative}\n${content}`)) {
residue.push(relative);
if (isSample) {
for (const root of ["src", "tests"]) {
for (const file of await filesBelow(path.join(fixtureRoot, root))) {
const relative = path.relative(fixtureRoot, file);
const content = await readFile(file, "utf8");
if (extras.residue.test(`${relative}\n${content}`)) {
residue.push(relative);
}
}
}
} else {
// 1105/16-04. Template tests use example feature IDs as data; only what
// still points at the removed feature counts (scripts/lib/feature-residue.ts).
residue.push(...(await productFeatureResidue(fixtureRoot, featureId, located.directory)));
}
const missingCommonTests: string[] = [];