3D engine that AI agents drive
Measure bundle growth against the base branch so size budgets stop conflicting (closes #337)
Nguyen Xuan Ane8b6e1f09d53
diff --git a/.github/workflows/test.yml b/.github/workflows/test.ymlindex 6fb7e261..8811ea8a 100644--- a/.github/workflows/test.yml+++ b/.github/workflows/test.yml@@ -14,6 +14,8 @@ jobs:test:runs-on: ubuntu-latesttimeout-minutes: 20+ env:+ SIZE_BASE_REF: origin/${{ github.base_ref }}steps:- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0@@ -23,7 +25,16 @@ jobs:- run: npm install --global [email protected]- run: npm ci --ignore-scripts- run: npm audit --audit-level=high- - run: npm run size+ - name: Fetch the base branch for the size check+ id: base+ run: |+ git fetch --no-tags --depth=1 origin "${GITHUB_BASE_REF}:refs/remotes/${SIZE_BASE_REF}"+ echo "sha=$(git rev-parse "${SIZE_BASE_REF}")" >> "$GITHUB_OUTPUT"+ - uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0+ with:+ path: node_modules/.cache/size-base+ key: size-base-${{ steps.base.outputs.sha }}-${{ hashFiles('scripts/measure-size.mjs', 'scripts/size-*.mjs', 'package-lock.json') }}+ - run: npm run size -- --base "$SIZE_BASE_REF"- run: npm test- run: npm run test:isolated- run: npm run prepare:releasediff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 94bdce19..9ccc683d 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -35,7 +35,7 @@ Run `npm run smoke` or the `smoke:*` script for the area that you changed, and lA change to skinning, glTF loading, poses or IK also needs `npm run smoke:character`, which takes a real character through the MCP server. Run `npm run prepare:release` first.Screenshots and other output go to `artifacts/`, which Git ignores.-Every pull request runs `npm audit`, `npm run size`, `npm test`, `npm run test:isolated` (each test file in its own process), `prepare:release`, `smoke:package` and `smoke:mcp-package` in the `Test` workflow. `smoke:mcp-package` draws through the MCP server on SwiftShader in Chrome. `bench/size/README.md` says what to do when a size budget fails.+Every pull request runs `npm audit`, `npm run size`, `npm test`, `npm run test:isolated` (each test file in its own process), `prepare:release`, `smoke:package` and `smoke:mcp-package` in the `Test` workflow. `smoke:mcp-package` draws through the MCP server on SwiftShader in Chrome. `npm run size` compares every bundle with `origin/main`. If a bundle grows past its allowance (64 bytes gzip for core and the scenes), add `changes/<issue>.size.md` with the line `- entry:core: <why it is worth the bytes>` and say why in the pull request. Never edit `bench/size/budgets.json` or `baseline.json` in a pull request. `bench/size/README.md` has the details.Branch protection on `main` requires the `test` check to pass before a merge. Merge a pull request only when `GitGuardian Security Checks` also passes.@@ -74,11 +74,12 @@ Keep site assets out of the npm package: the `files` list in `package.json` deciMaintainers make releases. `package.json` holds the version, and the publish workflow runs when it changes on `main`.-1. Update the version in `package.json` and in `src/version.js`, then run `npm run changes:fold`. It writes the files in `changes/` into `CHANGELOG.md` as that version's section and deletes them. Read `npm run changes` first to see what it will fold.-2. Run `npm test`, `npm run build` and `npm run smoke:package`.-3. Commit and push to `main`.-4. Wait for the `Publish 67js` workflow. It tests the package and publishes the new version through the npm trusted publisher.-5. Run `npm run deploy`. It checks that the tree is clean and pushed, builds the site and verifies the live `/release.json`.+1. Update the version in `package.json` and in `src/version.js`, then run `npm run changes:fold`. It writes the files in `changes/` into `CHANGELOG.md` as that version's section and deletes them. Read `npm run changes` first to see what it will fold. It also deletes the `changes/*.size.md` notes.+2. Run `npm run size:release`. It resets the size budgets and the baseline to the release sizes. Read the diff of `bench/size/budgets.json`.+3. Run `npm test`, `npm run build` and `npm run smoke:package`.+4. Commit and push to `main`.+5. Wait for the `Publish 67js` workflow. It tests the package and publishes the new version through the npm trusted publisher.+6. Run `npm run deploy`. It checks that the tree is clean and pushed, builds the site and verifies the live `/release.json`.## Licensediff --git a/bench/size/README.md b/bench/size/README.mdindex 30f77d95..fa5f8c3a 100644--- a/bench/size/README.md+++ b/bench/size/README.md@@ -1,6 +1,6 @@# Bundle size budgets-`npm run size` bundles each package entry with esbuild, minified and tree-shaken, and compares its gzip size with a budget. The `Test` workflow runs it on every pull request.+`npm run size` bundles each package entry with esbuild, minified and tree-shaken, and compares its gzip size with the same bundle on the base branch. The `Test` workflow runs it on every pull request. A pull request never edits a size number, so two pull requests do not conflict over one.## What it measures@@ -22,24 +22,43 @@ Measured on 2026-10-31 with three.js 0.186.1. Sizes are bytes gzip.`bench/size/baseline.json` holds every size. The goals are proposals from issue 23.+## How the check decides++The check measures the base branch with the same script, then compares each bundle. In CI the base is the branch that the pull request targets. On your machine it is `origin/main`, from the commit where your branch left it. The base numbers are cached by base commit in `node_modules/.cache/size-base`, and CI caches that folder, so a run on an unchanged base skips the second measurement. The base is measured beside your own bundles, so a cold run costs little more than one measurement.++A bundle fails when it grows by more than its allowance:++- `entry:core` and every `scene:*` bundle, with their `+lazy` rows: 64 bytes gzip.+- Every other entry: 2% of its size on the base, and at least 64 bytes.++A bundle that the base does not have is reported and never fails. A bundle that shrinks never fails.++The table in the output shows each bundle, the base size, the growth and the allowance. The release budgets in `budgets.json` and the goals are printed as a report. They do not fail a pull request.+## When a check fails-The output names the bundle, its size and its budget.+The output names the bundle, how much it grew and its allowance.1. Find out why the bundle grew. A new import of a large module is the usual cause.2. If the growth is a mistake, remove it.-3. If the growth is worth its cost, raise the number in `bench/size/budgets.json`.-4. State the reason in the pull request. The budget change is then visible in the diff.+3. If the growth is worth its cost, accept it. Add `changes/<issue>.size.md` to your pull request, with one line for each bundle that you accept:++```md+- entry:core: the lighting pass costs 180 bytes and replaces two shaders+- archive: the new guide ships in the package+```++4. State the same reason in the pull request.-## After a change lands+A line needs a bundle name, a colon, a space and a reason. A bundle with no line still fails. The check reads only the size notes that your branch adds, so a note from another pull request never accepts your growth. Your note is a new file, so it conflicts with nobody. Use `archive` for the package archive.-Run `node scripts/measure-size.mjs --update-baseline` to record the new sizes, so the next pull request shows its own change. The budget does not move.+## At release-Use `--set-budgets` to reset every budget to 2% over the current size. Use it after work that makes bundles smaller, so that the saving stays. A reset also hides any growth since the last reset, so check the diff.+Release steps in `CONTRIBUTING.md` run `npm run changes:fold`, which deletes the size notes. Then run `npm run size:release`. It resets every budget to 2% over the current size and rewrites `baseline.json`. Run `npm run size -- --absolute` before it to see which bundles are past their release budget. Check the diff of `budgets.json`, because a reset hides growth since the last reset. Also review the sizes of the accepted bundles, since each accepted increase is small alone and they add up.## Package archive-`archiveBytes` in `budgets.json` caps the npm archive that `npm pack` makes. `npm run smoke:package` checks it, after `npm run prepare:release`. The archive was 904,975 bytes before the MCP preview shared the package's engine chunks and 666,214 after; features then grew it to 802,581, and one-line notices in each built file plus a stub for the SDK's unused Ajv shim brought it to 695,041. The budget is now 740,000 bytes (measured 2026-11-02 against `budgets.json`: lower it when the archive shrinks). Lower `archiveBytes` when work shrinks it.+`archiveBytes` in `budgets.json` caps the npm archive that `npm pack` makes. `npm run smoke:package` checks it, after `npm run prepare:release`. The archive has a ceiling and not a base measurement, because measuring the base archive needs a full build. A pull request that pushes the archive over the ceiling accepts it with an `archive` line in its size note. Only a release edits `archiveBytes`. The archive was 904,975 bytes before the MCP preview shared the package's engine chunks and 666,214 after; features then grew it to 802,581, and one-line notices in each built file plus a stub for the SDK's unused Ajv shim brought it to 695,041. The budget is now 740,000 bytes (measured 2026-11-02 against `budgets.json`: lower it when the archive shrinks). Lower `archiveBytes` when work shrinks it.Moving code into installed dependencies would shrink the archive further but adds install size to every consumer, including library users who never run MCP. Making `@modelcontextprotocol/server` and `zod` dependencies saved about 125 KB of archive for about 14.5 MB on disk, so it was not kept.diff --git a/changes/337.md b/changes/337.mdnew file mode 100644index 00000000..47830878--- /dev/null+++ b/changes/337.md@@ -0,0 +1 @@+- Stop size budget conflicts between pull requests (issue #337). `npm run size` now compares each bundle with the base branch and fails when core or a scene grows by more than 64 bytes gzip, or another entry by more than 2%, unless the pull request adds a `changes/<issue>.size.md` note that names the bundle and the reason. Pull requests no longer edit `bench/size/budgets.json` or `baseline.json`, and `npm run size:release` resets them at release. The base is measured beside the pull request and cached by base commit, and the measurement itself runs four builds at once.diff --git a/changes/README.md b/changes/README.mdindex 689d2b73..2fb910ee 100644--- a/changes/README.md+++ b/changes/README.md@@ -9,3 +9,5 @@ Each pull request adds one file here, such as `changes/issue-199.md`, with its cDo not edit `CHANGELOG.md` in a pull request. Two pull requests then never touch the same file, so GitHub has nothing to conflict on.`npm run changes` prints the pending notes. At release time `npm run changes:fold` writes them into `CHANGELOG.md` as the section for the version in `package.json` and deletes the files.++A size note, `changes/<issue>.size.md`, is not a changelog bullet. It accepts a bundle size increase, and `bench/size/README.md` says how. `changes:fold` leaves it out of the changelog and deletes it.diff --git a/package.json b/package.jsonindex 2ed1dd62..6ee4a37e 100644--- a/package.json+++ b/package.json@@ -141,6 +141,7 @@"parity": "node scripts/parity-report.mjs","reference": "node bench/reference/run.mjs","size": "node scripts/measure-size.mjs",+ "size:release": "node scripts/measure-size.mjs --set-budgets","benchmark:runtime": "node bench/runtime/run.mjs","check:tool-schemas": "node scripts/check-tool-schemas.mjs","check:links": "node scripts/check-links.mjs",diff --git a/scripts/changelog-fragments.mjs b/scripts/changelog-fragments.mjsindex 62f9eb5a..83455574 100644--- a/scripts/changelog-fragments.mjs+++ b/scripts/changelog-fragments.mjs@@ -8,7 +8,7 @@ const changelogPath = resolve(root, 'CHANGELOG.md');const semver = /^\d+\.\d+\.\d+(?:-[a-z0-9.-]+)?$/;function isFragmentName(name) {- return name.endsWith('.md') && name.toLowerCase() !== 'readme.md';+ return name.endsWith('.md') && !name.endsWith('.size.md') && name.toLowerCase() !== 'readme.md';}function trimBlankLines(text) {@@ -48,7 +48,10 @@ async function main() {const changelog = await readFile(changelogPath, 'utf8');await writeFile(changelogPath, foldIntoChangelog(changelog, version, fragments));for (const fragment of fragments) await rm(resolve(fragmentsFolder, fragment.name));- console.log(`Folded ${fragments.length} fragments into CHANGELOG.md as ${version}.`);+ // Size notes only matter to the pull request that adds them. The release refreshes the size numbers instead.+ const sizeNotes = (await readdir(fragmentsFolder)).filter((name) => name.endsWith('.size.md'));+ for (const name of sizeNotes) await rm(resolve(fragmentsFolder, name));+ console.log(`Folded ${fragments.length} fragments into CHANGELOG.md as ${version}, and removed ${sizeNotes.length} size notes. Run npm run size:release next.`);return;}if (fragments.length === 0) {diff --git a/scripts/measure-size.mjs b/scripts/measure-size.mjsindex 4df0f429..9f637a49 100644--- a/scripts/measure-size.mjs+++ b/scripts/measure-size.mjs@@ -1,11 +1,14 @@// Measures what an app pays for each package entry, and for small scenes against three.js: npm run size-// It fails when a bundle passes its budget in bench/size/budgets.json. --update-baseline rewrites the baseline after a-// merge-ready change, and --set-budgets also resets each budget to 2% over its current size.+// A pull request fails when a bundle grows past its allowance against the base branch (--base, default origin/main) unless+// its own changes/*.size.md accepts it. --absolute also enforces the release budgets in bench/size/budgets.json.+// --update-baseline and --set-budgets refresh the baseline and the budgets at release.import { readFile, writeFile } from 'node:fs/promises';import { relative, resolve } from 'node:path';import { brotliCompressSync, gzipSync } from 'node:zlib';import { build } from 'esbuild';import { budgetsFrom, compareToBudgets, formatRows, initialOutputPaths } from './size-budget.mjs';+import { compareToBase, formatGrowthRows } from './size-growth.mjs';+import { DEFAULT_BASE_REF, baseRefExists, measureBase, readAcceptedBundles } from './size-base.mjs';const BUDGETS_PATH = 'bench/size/budgets.json';const BASELINE_PATH = 'bench/size/baseline.json';@@ -93,15 +96,33 @@ function addMeasured(measured, name, sizes) {}async function measureAll() {- const measured = {};- for (const [name, path] of Object.entries(await packageEntries())) {+ const jobs = Object.entries(await packageEntries()).map(([name, path]) => {const absolute = resolve(path).replace(/\\/g, '/');- addMeasured(measured, `entry:${name}`, await measureSource(`export * from '${absolute}';`));- }- for (const [name, scene] of Object.entries(SCENES)) addMeasured(measured, `scene:${name}`, await measureSource(scene.engine));+ return { label: `entry:${name}`, source: `export * from '${absolute}';` };+ });+ for (const [name, scene] of Object.entries(SCENES)) jobs.push({ label: `scene:${name}`, source: scene.engine });+ const sizes = await mapWithLimit(jobs, job => measureSource(job.source));+ const measured = {};+ jobs.forEach((job, index) => addMeasured(measured, job.label, sizes[index]));return measured;}+// A few builds at once use the cores of a CI runner without holding every build in memory together.+const BUILDS_AT_ONCE = 4;++async function mapWithLimit(items, work) {+ const results = new Array(items.length);+ let next = 0;+ const lane = async () => {+ while (next < items.length) {+ const index = next++;+ results[index] = await work(items[index]);+ }+ };+ await Promise.all(Array.from({ length: BUILDS_AT_ONCE }, lane));+ return results;+}+async function measureThree() {const measured = {};for (const [name, scene] of Object.entries(SCENES)) {@@ -130,12 +151,37 @@ function printComparisonWithThree(measured, three, goals) {}}-const flags = new Set(process.argv.slice(2));+const argumentsGiven = process.argv.slice(2);+const flags = new Set(argumentsGiven);++function valueAfter(flag) {+ const index = argumentsGiven.indexOf(flag);+ return index === -1 ? undefined : argumentsGiven[index + 1];+}++// A child run for the base branch: print the measurement and stop.+if (flags.has('--json')) {+ process.stdout.write(JSON.stringify(await measureAll()));+ process.exit(0);+}++// The gate: growth against the base branch. An explicit --base must resolve. Without one, origin/main is used when it exists.+// The base is measured beside the pull request, and not at all when the run only refreshes the release numbers.+const requestedBase = valueAfter('--base');+const baseRef = requestedBase ?? DEFAULT_BASE_REF;+if (requestedBase && !baseRefExists(baseRef)) {+ console.error(`The base ref ${baseRef} does not exist. Fetch it first, for example: git fetch origin main`);+ process.exit(1);+}+const refreshing = flags.has('--set-budgets') || flags.has('--update-baseline');+const checkGrowth = baseRefExists(baseRef) && !refreshing;+const baseMeasurement = checkGrowth ? measureBase(baseRef) : null;const measured = await measureAll();const three = await measureThree();const budgetFile = await readJson(BUDGETS_PATH);const baselineFile = await readJson(BASELINE_PATH);+// Budgets and the baseline move at release, never in a feature pull request.if (flags.has('--set-budgets')) budgetFile.budgets = budgetsFrom(measured);if (flags.has('--set-budgets') || flags.has('--update-baseline')) {const threeManifest = await readJson('node_modules/three/package.json');@@ -143,12 +189,35 @@ if (flags.has('--set-budgets') || flags.has('--update-baseline')) {await writeJson(BASELINE_PATH, { threeVersion: threeManifest.version, three, bundles: measured });}-const { rows, problems } = compareToBudgets(measured, budgetFile.budgets, baselineFile.bundles);+const { rows, problems: ceilingProblems } = compareToBudgets(measured, budgetFile.budgets, baselineFile.bundles);+const problems = [];++if (checkGrowth) {+ const accepted = readAcceptedBundles(baseRef);+ const growth = compareToBase(measured, await baseMeasurement, accepted);+ console.log(`Growth against ${baseRef}, in bytes gzip:`);+ console.log(formatGrowthRows(growth.rows));+ for (const [name, reason] of accepted) console.log(`Accepted: ${name}, ${reason}`);+ problems.push(...growth.problems);+} else if (!refreshing) {+ console.log(`No ${baseRef} to compare with, so the growth check is skipped. Fetch it, or pass --base <ref>.`);+}++// The absolute budgets are the release ceilings. They are reported on a pull request and enforced with --absolute.+console.log('\nAgainst the release budgets:');console.log(formatRows(rows));printComparisonWithThree(measured, three, budgetFile.goals);+if (ceilingProblems.length) {+ if (flags.has('--absolute')) {+ problems.push(...ceilingProblems);+ } else {+ console.log(`\n${ceilingProblems.length} bundle(s) are past their release budget. A release refreshes the budgets with npm run size:release. List them with npm run size -- --absolute.`);+ }+}if (problems.length) {console.error(`\n${problems.length} size problem(s):`);for (const problem of problems) console.error(`- ${problem}`);process.exit(1);}-console.log('\nEvery bundle is within its budget.');+console.log('\nNo bundle grew past its allowance.');+diff --git a/scripts/size-base.mjs b/scripts/size-base.mjsnew file mode 100644index 00000000..00b03b85--- /dev/null+++ b/scripts/size-base.mjs@@ -0,0 +1,90 @@+// Finds the base branch measurement and the size notes of the current pull request. measure-size.mjs and smoke-package.mjs share it.+import { execFile, spawnSync } from 'node:child_process';+import { createHash } from 'node:crypto';+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';+import { tmpdir } from 'node:os';+import { join, resolve } from 'node:path';+import { promisify } from 'node:util';+import { fileURLToPath } from 'node:url';+import { parseSizeNote } from './size-growth.mjs';++export const DEFAULT_BASE_REF = 'origin/main';+const SIZE_NOTE_PATTERN = /^changes\/[^/]+\.size\.md$/;+const SCRIPTS_FOLDER = fileURLToPath(new URL('.', import.meta.url));+const MEASURE_SCRIPT = join(SCRIPTS_FOLDER, 'measure-size.mjs');+const METHOD_FILES = ['measure-size.mjs', 'size-base.mjs', 'size-budget.mjs', 'size-growth.mjs'];+// CI caches this folder, keyed by the base commit, so a run on an unchanged base skips the second measurement.+export const BASE_CACHE_FOLDER = 'node_modules/.cache/size-base';+const MAX_OUTPUT_BYTES = 256 * 1024 * 1024;+const execFileAsync = promisify(execFile);++function run(command, args, cwd = process.cwd()) {+ return spawnSync(command, args, { cwd, encoding: 'utf8', windowsHide: true, maxBuffer: MAX_OUTPUT_BYTES });+}++export function baseRefExists(baseRef, cwd = process.cwd()) {+ return run('git', ['rev-parse', '--verify', '--quiet', `${baseRef}^{commit}`], cwd).status === 0;+}++// The commit this branch grew from. On CI the checkout is the pull request merged into the base, so this is the base tip.+// On a branch that has not caught up with the base, it keeps work merged by others out of this branch's numbers.+export function mergeBaseOf(baseRef, cwd = process.cwd()) {+ const result = run('git', ['merge-base', baseRef, 'HEAD'], cwd);+ return result.status === 0 ? result.stdout.trim() : baseRef;+}++// The size notes this pull request adds. Notes already on the base branch belong to other pull requests.+export function addedSizeNoteFiles(baseRef, cwd = process.cwd()) {+ const committed = run('git', ['diff', '--name-only', '--diff-filter=A', mergeBaseOf(baseRef, cwd), 'HEAD', '--', 'changes'], cwd).stdout.split('\n');+ const uncommitted = run('git', ['ls-files', '--others', '--exclude-standard', '--', 'changes'], cwd).stdout.split('\n');+ return [...new Set([...committed, ...uncommitted].map(file => file.trim()))].filter(file => SIZE_NOTE_PATTERN.test(file));+}++export function readAcceptedBundles(baseRef, cwd = process.cwd()) {+ const accepted = new Map();+ if (!baseRefExists(baseRef, cwd)) return accepted;+ for (const file of addedSizeNoteFiles(baseRef, cwd)) {+ for (const [name, reason] of parseSizeNote(readFileSync(resolve(cwd, file), 'utf8'))) accepted.set(name, reason);+ }+ return accepted;+}++// The cache key holds everything that decides the base numbers: the base commit, the measuring method and the lock file.+function cacheFileFor(baseRef) {+ const hash = createHash('sha256');+ hash.update(mergeBaseOf(baseRef));+ for (const file of METHOD_FILES) hash.update(readFileSync(join(SCRIPTS_FOLDER, file)));+ if (existsSync('package-lock.json')) hash.update(readFileSync('package-lock.json'));+ return join(BASE_CACHE_FOLDER, `${hash.digest('hex').slice(0, 24)}.json`);+}++async function measureCheckout(baseRef) {+ const folder = mkdtempSync(join(tmpdir(), 'size-base-'));+ const checkout = join(folder, 'base');+ try {+ mkdirSync(checkout);+ // A scratch index and checkout-index give the files the same line endings as this checkout, so both sides match on any system.+ const environment = { ...process.env, GIT_INDEX_FILE: join(folder, 'index') };+ const indexed = spawnSync('git', ['read-tree', mergeBaseOf(baseRef)], { encoding: 'utf8', windowsHide: true, env: environment });+ if (indexed.status !== 0) throw new Error(`Could not read ${baseRef}: ${indexed.stderr}`);+ const extracted = spawnSync('git', ['checkout-index', '--all', '--force', `--prefix=${checkout}/`], { encoding: 'utf8', windowsHide: true, env: environment });+ if (extracted.status !== 0) throw new Error(`Could not unpack ${baseRef}: ${extracted.stderr}`);+ if (existsSync('node_modules')) symlinkSync(resolve('node_modules'), join(checkout, 'node_modules'), 'junction');+ const { stdout } = await execFileAsync(process.execPath, [MEASURE_SCRIPT, '--json'], { cwd: checkout, maxBuffer: MAX_OUTPUT_BYTES, windowsHide: true });+ return JSON.parse(stdout);+ } finally {+ rmSync(join(checkout, 'node_modules'), { force: true });+ rmSync(folder, { recursive: true, force: true });+ }+}++// Measures the base branch with this checkout's script, so both sides use the same method. It runs beside the+// measurement of the pull request, and a cached result for the same base commit skips it.+export async function measureBase(baseRef) {+ const cacheFile = cacheFileFor(baseRef);+ if (existsSync(cacheFile)) return JSON.parse(readFileSync(cacheFile, 'utf8'));+ const measured = await measureCheckout(baseRef);+ mkdirSync(BASE_CACHE_FOLDER, { recursive: true });+ writeFileSync(cacheFile, JSON.stringify(measured));+ return measured;+}diff --git a/scripts/size-budget.mjs b/scripts/size-budget.mjsindex d350d2ad..1181d0b6 100644--- a/scripts/size-budget.mjs+++ b/scripts/size-budget.mjs@@ -31,7 +31,7 @@ export function compareToBudgets(measured, budgets, baseline = {}) {return { rows, problems };}-function signedBytes(change) {+export function signedBytes(change) {if (change === null) return 'new';return change > 0 ? `+${change}` : String(change);}diff --git a/scripts/size-growth.mjs b/scripts/size-growth.mjsnew file mode 100644index 00000000..ce670d89--- /dev/null+++ b/scripts/size-growth.mjs@@ -0,0 +1,69 @@+// The growth gate. A pull request is measured against the base branch, so no pull request edits a number that another one edits.+import { signedBytes } from './size-budget.mjs';++const CORE_ALLOWANCE_BYTES = 64;+const OTHER_ALLOWANCE_FRACTION = 0.02;+const OTHER_ALLOWANCE_FLOOR_BYTES = 64;+export const ARCHIVE_NAME = 'archive';++function isTightBundle(name) {+ return name.startsWith('entry:core') || name.startsWith('scene:');+}++// Core and the scenes get a small fixed allowance, because every app pays for them. Other entries get a percentage.+export function growthAllowance(name, baseGzip) {+ if (isTightBundle(name)) return CORE_ALLOWANCE_BYTES;+ return Math.max(OTHER_ALLOWANCE_FLOOR_BYTES, Math.floor(baseGzip * OTHER_ALLOWANCE_FRACTION));+}++// Reads the lines of one size note, "- entry:core: why it is worth it". A line without a reason does not count.+export function parseSizeNote(text) {+ const accepted = new Map();+ for (const line of text.replace(/\r\n/g, '\n').split('\n')) {+ const match = line.match(/^\s*(?:[-*]\s+)?`?([\w:+.-]+)`?:\s+(\S.*)$/);+ if (match) accepted.set(match[1], match[2].trim());+ }+ return accepted;+}++export function acceptInstruction(name) {+ return `Reduce it, or accept it: add changes/<issue>.size.md to this pull request with the line "- ${name}: <why it is worth the bytes>", and say why in the pull request.`;+}++// Compares each bundle with the same bundle on the base branch. A bundle the base does not have is reported, not failed.+export function compareToBase(measured, baseMeasured, accepted = new Map()) {+ const rows = [];+ const problems = [];+ for (const [name, size] of Object.entries(measured)) {+ const baseGzip = baseMeasured[name]?.gzip;+ const growth = baseGzip === undefined ? null : size.gzip - baseGzip;+ const allowance = baseGzip === undefined ? null : growthAllowance(name, baseGzip);+ const isAccepted = accepted.has(name);+ rows.push({ name, min: size.min, gzip: size.gzip, base: baseGzip ?? null, growth, allowance, accepted: isAccepted });+ if (growth !== null && growth > allowance && !isAccepted) {+ problems.push(`${name} grew by ${growth} bytes gzip against the base branch (${baseGzip} to ${size.gzip}), over its allowance of ${allowance}. ${acceptInstruction(name)}`);+ }+ }+ return { rows, problems };+}++function noteFor(row) {+ if (row.growth === null) return 'new, reported only';+ if (row.growth <= row.allowance) return '';+ return row.accepted ? 'accepted' : 'OVER';+}++export function formatGrowthRows(rows) {+ const header = `${'bundle'.padEnd(30)}${'gzip'.padStart(10)}${'base'.padStart(10)}${'growth'.padStart(10)}${'allowed'.padStart(10)} note`;+ const lines = rows.map(row => [+ row.name.padEnd(30), String(row.gzip).padStart(10), String(row.base ?? '-').padStart(10),+ signedBytes(row.growth).padStart(10), String(row.allowance ?? '-').padStart(10), ` ${noteFor(row)}`,+ ].join(''));+ return [header, ...lines].join('\n');+}++// The packed archive has a ceiling instead of a base measurement, because measuring the base archive needs a full build.+export function archiveProblem(archiveBytes, ceiling, accepted = new Map()) {+ if (archiveBytes <= ceiling || accepted.has(ARCHIVE_NAME)) return null;+ return `The current source package is ${archiveBytes} bytes, over its archive ceiling of ${ceiling} in bench/size/budgets.json by ${archiveBytes - ceiling}. ${acceptInstruction(ARCHIVE_NAME)}`;+}diff --git a/scripts/smoke-package.mjs b/scripts/smoke-package.mjsindex b5230f15..85e0b0e5 100644--- a/scripts/smoke-package.mjs+++ b/scripts/smoke-package.mjs@@ -4,6 +4,8 @@ import { tmpdir } from 'node:os';import { resolve, dirname } from 'node:path';import { spawnSync } from 'node:child_process';import { createHash } from 'node:crypto';+import { DEFAULT_BASE_REF, readAcceptedBundles } from './size-base.mjs';+import { archiveProblem } from './size-growth.mjs';const metadata = JSON.parse(await readFile('package.json', 'utf8'));const release = JSON.parse(await readFile('public/release.json', 'utf8'));@@ -32,7 +34,8 @@ if (published) {const sourcePackResult = JSON.parse(sourcePack.stdout);const packedSource = Array.isArray(sourcePackResult) ? sourcePackResult[0] : sourcePackResult[metadata.name];assert.ok(packedSource?.filename, 'npm pack must return a source archive.');- assert.ok(packedSource.size <= sizeBudgets.archiveBytes, `The current source package is ${packedSource.size} bytes, over its archive budget of ${sizeBudgets.archiveBytes} in bench/size/budgets.json.`);+ const archiveFailure = archiveProblem(packedSource.size, sizeBudgets.archiveBytes, readAcceptedBundles(process.env.SIZE_BASE_REF ?? DEFAULT_BASE_REF));+ assert.ok(!archiveFailure, archiveFailure);const sourceArchive = resolve(consumer, packedSource.filename);installTarget = `67js@file:${sourceArchive.replaceAll('\\', '/')}`;}diff --git a/tests/changelog-fragments.test.js b/tests/changelog-fragments.test.jsindex 3a249859..e2cd6b4c 100644--- a/tests/changelog-fragments.test.js+++ b/tests/changelog-fragments.test.js@@ -18,7 +18,7 @@ async function withFragments(files, check) {}test('fragments are read in name order, skipping the README and empty files', async () => {- await withFragments({ 'b.md': '- B.\n', 'a.md': '\n- A.\n\n', 'README.md': 'Format.', 'empty.md': '\n' }, async (folder) => {+ await withFragments({ 'b.md': '- B.\n', 'a.md': '\n- A.\n\n', 'README.md': 'Format.', 'empty.md': '\n', '337.size.md': '- entry:core: why' }, async (folder) => {const fragments = await readFragments(folder);assert.deepEqual(fragments.map((fragment) => fragment.name), ['a.md', 'b.md']);});diff --git a/tests/size-growth.test.js b/tests/size-growth.test.jsnew file mode 100644index 00000000..8828a808--- /dev/null+++ b/tests/size-growth.test.js@@ -0,0 +1,93 @@+import assert from 'node:assert/strict';+import { spawnSync } from 'node:child_process';+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';+import { tmpdir } from 'node:os';+import { join } from 'node:path';+import test from 'node:test';+import { readAcceptedBundles } from '../scripts/size-base.mjs';+import { archiveProblem, compareToBase, growthAllowance, parseSizeNote } from '../scripts/size-growth.mjs';++const size = gzip => ({ min: gzip * 3, gzip });++test('core and the scenes get a small fixed allowance, other entries a percentage', () => {+ assert.equal(growthAllowance('entry:core', 80000), 64);+ assert.equal(growthAllowance('scene:lit-box+lazy', 60000), 64);+ assert.equal(growthAllowance('entry:water-reflection', 27000), 540);+ assert.equal(growthAllowance('entry:texture-set', 800), 64);+});++test('a pull request that grows core past the allowance fails with the accept instruction', () => {+ const { problems } = compareToBase({ 'entry:core': size(80100) }, { 'entry:core': size(80000) });+ assert.equal(problems.length, 1);+ assert.match(problems[0], /entry:core grew by 100 bytes gzip against the base branch \(80000 to 80100\), over its allowance of 64/);+ assert.match(problems[0], /Reduce it, or accept it: add changes\/<issue>\.size\.md/);+ assert.match(problems[0], /- entry:core: <why it is worth the bytes>/);+});++test('growth inside the allowance, a shrink and a new bundle all pass', () => {+ const measured = { 'entry:core': size(80064), 'entry:model': size(14000), 'entry:fresh': size(500) };+ const base = { 'entry:core': size(80000), 'entry:model': size(14500) };+ const { rows, problems } = compareToBase(measured, base);+ assert.deepEqual(problems, []);+ assert.deepEqual(rows.map(row => row.growth), [64, -500, null]);+});++test('a size note accepts only the bundles it names', () => {+ const accepted = parseSizeNote('- entry:core: the new lighting pass is worth it\r\nentry:gltf: loads KHR_lights\n\nNo colon here\n- entry:model:\n');+ assert.deepEqual([...accepted.keys()], ['entry:core', 'entry:gltf']);+ const measured = { 'entry:core': size(81000), 'scene:lit-box': size(70000) };+ const base = { 'entry:core': size(80000), 'scene:lit-box': size(66000) };+ const { problems } = compareToBase(measured, base, accepted);+ assert.equal(problems.length, 1);+ assert.match(problems[0], /scene:lit-box grew by 4000/);+});++test('the archive fails over its ceiling unless a note names it', () => {+ assert.match(archiveProblem(741000, 740000), /over its archive ceiling of 740000 in bench\/size\/budgets\.json by 1000\. Reduce it, or accept it/);+ assert.equal(archiveProblem(739000, 740000), null);+ assert.equal(archiveProblem(741000, 740000, new Map([['archive', 'ships the new guide']])), null);+});++function git(folder, ...args) {+ const result = spawnSync('git', ['-c', 'user.name=Test', '-c', '[email protected]', '-c', 'commit.gpgsign=false', '-c', 'core.autocrlf=false', ...args], { cwd: folder, encoding: 'utf8' });+ assert.equal(result.status, 0, `${args.join(' ')}: ${result.stderr}`);+ return result.stdout;+}++function commitFile(folder, path, text, message) {+ mkdirSync(join(folder, path, '..'), { recursive: true });+ writeFileSync(join(folder, path), text);+ git(folder, 'add', '.');+ git(folder, 'commit', '-q', '-m', message);+}++test('two pull requests that grow different entries merge in sequence without touching each other', () => {+ const folder = mkdtempSync(join(tmpdir(), 'size-sim-'));+ try {+ git(folder, 'init', '-q', '-b', 'main');+ commitFile(folder, 'src/model.js', 'export const model = 1;\n', 'base');+ commitFile(folder, 'src/nature.js', 'export const nature = 1;\n', 'base files');+ commitFile(folder, 'changes/100.size.md', '- entry:other: an earlier pull request, already merged\n', 'earlier note');+ git(folder, 'update-ref', 'refs/remotes/origin/main', 'HEAD');++ git(folder, 'checkout', '-q', '-b', 'grow-model');+ commitFile(folder, 'src/model.js', 'export const model = 2;\n', 'grow model');+ commitFile(folder, 'changes/201.size.md', '- entry:model: new joints\n', 'accept model');+ git(folder, 'checkout', '-q', 'main');+ git(folder, 'checkout', '-q', '-b', 'grow-nature');+ commitFile(folder, 'src/nature.js', 'export const nature = 2;\n', 'grow nature');+ commitFile(folder, 'changes/202.size.md', '- entry:nature: new trees\n', 'accept nature');++ assert.deepEqual([...readAcceptedBundles('origin/main', folder).keys()], ['entry:nature']);+ git(folder, 'checkout', '-q', 'grow-model');+ assert.deepEqual([...readAcceptedBundles('origin/main', folder).keys()], ['entry:model']);++ git(folder, 'checkout', '-q', 'main');+ git(folder, 'merge', '-q', '--no-ff', '-m', 'merge model', 'grow-model');+ git(folder, 'merge', '-q', '--no-ff', '-m', 'merge nature', 'grow-nature');+ assert.equal(readFileSync(join(folder, 'src/model.js'), 'utf8'), 'export const model = 2;\n');+ assert.equal(readFileSync(join(folder, 'src/nature.js'), 'utf8'), 'export const nature = 2;\n');+ } finally {+ rmSync(folder, { recursive: true, force: true });+ }+});