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:
@@ -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;
|
||||
}
|
||||
|
||||
@@ -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";
|
||||
|
||||
@@ -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`;
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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();
|
||||
}
|
||||
@@ -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;
|
||||
|
||||
@@ -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),
|
||||
|
||||
@@ -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. */
|
||||
|
||||
@@ -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);
|
||||
@@ -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
@@ -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();
|
||||
|
||||
@@ -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[] = [];
|
||||
|
||||
Reference in New Issue
Block a user