Skip to content

armgit / 67.js

Public Imported from GitHub
0

3D engine that AI agents drive

Measure the package archive against the base branch

Nguyen Xuan An4a6616e61594
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 57a1809d..acbcc610 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -33,7 +33,7 @@ jobs:
- 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', 'scripts/*tool-cost*.mjs', 'package-lock.json') }}
+ key: size-base-${{ steps.base.outputs.sha }}-${{ hashFiles('scripts/measure-size.mjs', 'scripts/size-*.mjs', 'scripts/*tool-cost*.mjs', 'scripts/measure-archive.mjs', 'scripts/build-mcp.mjs', 'vite.lib.config.js', 'package-lock.json') }}
- run: npm run size -- --base "$SIZE_BASE_REF"
- run: npm run tool-cost -- --base "$SIZE_BASE_REF"
- run: npm test
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index f5ed9676..1562588e 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 l
A 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 run tool-cost`, `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.
+Every pull request runs `npm audit`, `npm run size`, `npm run tool-cost`, `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, 2% for the npm archive), 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.
`npm run tool-cost` does the same for what the MCP tools cost an agent. If a tool schema grows by more than 64 bytes, a typical result by more than 128 bytes, or the schema total by more than 128 bytes, first move rare detail into `scene_capabilities` or a shared schema. If the growth is worth it, add a line to `changes/<issue>.size.md`, such as `- tool:scene_create: <why it is worth the bytes>`, `- tool-total: <why>` or `- result:scene_capabilities: <why>`. Never edit `bench/tool-cost-budgets.json` in a pull request. `bench/tool-cost/README.md` has the details.
diff --git a/bench/size/README.md b/bench/size/README.md
index 81609cc2..b2e81747 100644
--- a/bench/size/README.md
+++ b/bench/size/README.md
@@ -81,7 +81,9 @@ Release steps in `CONTRIBUTING.md` run `npm run changes:fold`, which deletes the
## 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 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.
+`npm run smoke:package` checks the npm archive that `npm pack` makes, after `npm run prepare:release`. It measures the archive of the base branch the same way as the bundles. It unpacks the base, builds the library and the MCP server there, and asks `npm pack --dry-run` for the size. That takes about ten seconds, and CI caches the result by base with the bundle sizes. The archive may grow by 2% of the base archive. A pull request that grows it more accepts it with an `archive` line in its size note. Two pull requests that each stay inside 2% never fail each other, because each one is compared with its own base.
+
+`archiveBytes` in `budgets.json` is the release ceiling. `smoke:package` reports it, and `npm run smoke:package -- --absolute` enforces it. `npm run size:release` resets it to 2% over the archive of the current build. A pull request never edits it. 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/345.md b/changes/345.md
index 6059efaa..5fbac36f 100644
--- a/changes/345.md
+++ b/changes/345.md
@@ -1 +1 @@
-- Measure tool schema and result bytes against the base branch with `npm run tool-cost` (issue #345). A pull request that grows a tool by more than 64 bytes, a result by more than 128 or the total by more than 128 accepts it in its own `changes/<issue>.size.md`, so `bench/tool-cost-budgets.json` no longer conflicts. The `measured` history string is gone and the absolute budgets are release ceilings, refreshed by `npm run tool-cost:release`.
+- Measure tool schema and result bytes against the base branch with `npm run tool-cost` (issue #345). A pull request that grows a tool by more than 64 bytes, a result by more than 128 or the total by more than 128 accepts it in its own `changes/<issue>.size.md`, so `bench/tool-cost-budgets.json` no longer conflicts. The `measured` history string is gone and the absolute budgets are release ceilings, refreshed by `npm run tool-cost:release`. The npm archive is measured the same way (issue #337): it may grow by 2% of the base branch archive, and an `archive` line in a size note accepts more, so one stale ceiling no longer fails every later pull request.
diff --git a/scripts/measure-archive.mjs b/scripts/measure-archive.mjs
new file mode 100644
index 00000000..e0f98201
--- /dev/null
+++ b/scripts/measure-archive.mjs
@@ -0,0 +1,39 @@
+// Packs the library the way a release does and prints the archive size: node scripts/measure-archive.mjs --json
+// The base measurement of the size check runs it inside a checkout of the base branch, so the numbers come from the base source.
+// It builds the library and the MCP server like prepare-release.mjs, then asks npm for the size of the archive without writing one.
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+
+const MAX_OUTPUT_BYTES = 64 * 1024 * 1024;
+
+function run(arguments_, capture = false) {
+ const result = spawnSync(process.execPath, arguments_, { encoding: 'utf8', windowsHide: true, stdio: capture ? 'pipe' : ['ignore', 2, 2], maxBuffer: MAX_OUTPUT_BYTES });
+ if (result.status !== 0) throw new Error(`${arguments_.join(' ')} failed: ${result.stderr ?? ''}`);
+ return result.stdout;
+}
+
+// The MCP build records the source commit and refuses a folder that is not a repository. The unpacked base branch is one folder
+// of files, so it gets a throwaway repository with one commit, which is clean like a release checkout.
+function ensureRepository() {
+ if (existsSync('.git')) return;
+ const identity = ['-c', 'user.name=archive', '-c', '[email protected]', '-c', 'commit.gpgsign=false'];
+ for (const command of [['init', '-q'], ['add', '-A'], [...identity, 'commit', '-q', '-m', 'base']]) {
+ const result = spawnSync('git', command, { encoding: 'utf8', windowsHide: true, maxBuffer: MAX_OUTPUT_BYTES });
+ if (result.status !== 0) throw new Error(`git ${command.join(' ')} failed: ${result.stderr}`);
+ }
+}
+
+export function measureArchiveBytes() {
+ ensureRepository();
+ run(['node_modules/vite/bin/vite.js', 'build', '--config', 'vite.lib.config.js']);
+ run(['scripts/build-mcp.mjs']);
+ const npmCli = process.env.npm_execpath ?? resolve(dirname(process.execPath), 'node_modules/npm/bin/npm-cli.js');
+ const packResult = JSON.parse(run([npmCli, 'pack', '--ignore-scripts', '--dry-run', '--json'], true));
+ const packed = Array.isArray(packResult) ? packResult[0] : Object.values(packResult)[0];
+ return packed.size;
+}
+
+if (process.argv.includes('--json')) {
+ process.stdout.write(JSON.stringify({ archiveBytes: measureArchiveBytes() }));
+}
diff --git a/scripts/measure-size.mjs b/scripts/measure-size.mjs
index aa2c31d8..f21bc20c 100644
--- a/scripts/measure-size.mjs
+++ b/scripts/measure-size.mjs
@@ -8,6 +8,7 @@ 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 { measureArchiveBytes } from './measure-archive.mjs';
import { DEFAULT_BASE_REF, baseRefExists, measureBase, readAcceptedBundles } from './size-base.mjs';
const BUDGETS_PATH = 'bench/size/budgets.json';
@@ -188,7 +189,10 @@ 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')) {
+ budgetFile.budgets = budgetsFrom(measured);
+ budgetFile.archiveBytes = Math.ceil(measureArchiveBytes() * 1.02);
+}
if (flags.has('--set-budgets') || flags.has('--update-baseline')) {
const threeManifest = await readJson('node_modules/three/package.json');
await writeJson(BUDGETS_PATH, budgetFile);
diff --git a/scripts/size-base.mjs b/scripts/size-base.mjs
index cf2e143d..c460e6bf 100644
--- a/scripts/size-base.mjs
+++ b/scripts/size-base.mjs
@@ -50,6 +50,9 @@ export function readAcceptedBundles(baseRef, cwd = process.cwd()) {
return accepted;
}
+// The archive: the base branch is built and packed in its own checkout by this checkout's script.
+export const ARCHIVE_METHOD = { script: join(SCRIPTS_FOLDER, 'measure-archive.mjs'), runInBase: false, files: ['measure-archive.mjs', 'size-base.mjs', '../vite.lib.config.js', 'build-mcp.mjs'] };
+
// The cache key holds everything that decides the base numbers: the base commit, the measuring method and the lock file.
function cacheFileFor(baseRef, method) {
const hash = createHash('sha256');
@@ -90,3 +93,8 @@ export async function measureBase(baseRef, method = SIZE_METHOD) {
writeFileSync(cacheFile, JSON.stringify(measured));
return measured;
}
+
+// The size in bytes of the npm archive of the base branch, cached by base commit like the bundle sizes.
+export async function measureBaseArchive(baseRef) {
+ return (await measureBase(baseRef, ARCHIVE_METHOD)).archiveBytes;
+}
diff --git a/scripts/size-growth.mjs b/scripts/size-growth.mjs
index ce670d89..dd15895b 100644
--- a/scripts/size-growth.mjs
+++ b/scripts/size-growth.mjs
@@ -62,8 +62,21 @@ export function formatGrowthRows(rows) {
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)}`;
+// The packed archive is measured like a bundle, against the archive of the base branch. It gets 2% of that archive, because
+// every consumer downloads it and 2% is what the other entries get. An archive line in a size note accepts more.
+export function archiveAllowance(baseBytes) {
+ return Math.floor(baseBytes * OTHER_ALLOWANCE_FRACTION);
+}
+
+export function archiveGrowthProblem(archiveBytes, baseBytes, accepted = new Map()) {
+ const allowance = archiveAllowance(baseBytes);
+ const growth = archiveBytes - baseBytes;
+ if (growth <= allowance || accepted.has(ARCHIVE_NAME)) return null;
+ return `The source package is ${archiveBytes} bytes, ${growth} more than the ${baseBytes} bytes of the base branch, over its allowance of ${allowance}. ${acceptInstruction(ARCHIVE_NAME)}`;
+}
+
+// The ceiling in bench/size/budgets.json is a release report like the other absolute budgets. --absolute enforces it.
+export function archiveCeilingProblem(archiveBytes, ceiling) {
+ if (archiveBytes <= ceiling) return null;
+ return `The source package is ${archiveBytes} bytes, over its release ceiling of ${ceiling} in bench/size/budgets.json by ${archiveBytes - ceiling}. A release refreshes it.`;
}
diff --git a/scripts/smoke-package.mjs b/scripts/smoke-package.mjs
index 85e0b0e5..768d4b39 100644
--- a/scripts/smoke-package.mjs
+++ b/scripts/smoke-package.mjs
@@ -4,8 +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';
+import { DEFAULT_BASE_REF, baseRefExists, measureBaseArchive, readAcceptedBundles } from './size-base.mjs';
+import { archiveCeilingProblem, archiveGrowthProblem } from './size-growth.mjs';
const metadata = JSON.parse(await readFile('package.json', 'utf8'));
const release = JSON.parse(await readFile('public/release.json', 'utf8'));
@@ -18,6 +18,21 @@ assert.equal(release.packageAlias, '67js');
assert.equal(release.integrity, `sha512-${createHash('sha512').update(binary).digest('base64')}`);
assert.ok(binary.length < 1024 * 1024, 'Library and optional addon wrappers must fit within a 1 MiB archive.');
assert.ok((await readFile('build/67.module.js')).length < 150000, 'The core must exclude the optional asset decoder.');
+// The archive is measured against the base branch like a bundle. The release ceiling in budgets.json is reported, and
+// npm run smoke:package -- --absolute enforces it.
+async function checkArchiveSize(archiveBytes) {
+ const baseRef = process.env.SIZE_BASE_REF ?? DEFAULT_BASE_REF;
+ if (baseRefExists(baseRef)) {
+ const accepted = readAcceptedBundles(baseRef);
+ const growthFailure = archiveGrowthProblem(archiveBytes, await measureBaseArchive(baseRef), accepted);
+ assert.ok(!growthFailure, growthFailure);
+ } else {
+ console.log(`No ${baseRef} to compare the archive with, so the archive growth check is skipped. Fetch it, or set SIZE_BASE_REF.`);
+ }
+ const ceilingFailure = archiveCeilingProblem(archiveBytes, sizeBudgets.archiveBytes);
+ if (ceilingFailure && process.argv.includes('--absolute')) assert.fail(ceilingFailure);
+ if (ceilingFailure) console.log(ceilingFailure);
+}
const consumer = await mkdtemp(resolve(tmpdir(), '67js-consumer-'));
await writeFile(resolve(consumer, 'package.json'), JSON.stringify({ private: true, type: 'module' }));
const npmCli = process.env.npm_execpath ?? resolve(dirname(process.execPath), 'node_modules/npm/bin/npm-cli.js');
@@ -34,8 +49,7 @@ 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.');
- const archiveFailure = archiveProblem(packedSource.size, sizeBudgets.archiveBytes, readAcceptedBundles(process.env.SIZE_BASE_REF ?? DEFAULT_BASE_REF));
- assert.ok(!archiveFailure, archiveFailure);
+ await checkArchiveSize(packedSource.size);
const sourceArchive = resolve(consumer, packedSource.filename);
installTarget = `67js@file:${sourceArchive.replaceAll('\\', '/')}`;
}
diff --git a/tests/size-growth.test.js b/tests/size-growth.test.js
index 8828a808..44755e5c 100644
--- a/tests/size-growth.test.js
+++ b/tests/size-growth.test.js
@@ -5,7 +5,7 @@ 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';
+import { archiveAllowance, archiveCeilingProblem, archiveGrowthProblem, compareToBase, growthAllowance, parseSizeNote } from '../scripts/size-growth.mjs';
const size = gzip => ({ min: gzip * 3, gzip });
@@ -42,10 +42,28 @@ test('a size note accepts only the bundles it names', () => {
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);
+test('the archive gets 2% of the base archive, and a note accepts more', () => {
+ assert.equal(archiveAllowance(750000), 15000);
+ assert.match(archiveGrowthProblem(765001, 750000), /765001 bytes, 15001 more than the 750000 bytes of the base branch, over its allowance of 15000\. Reduce it, or accept it/);
+ assert.match(archiveGrowthProblem(765001, 750000), /- archive: <why it is worth the bytes>/);
+ assert.equal(archiveGrowthProblem(765000, 750000), null);
+ assert.equal(archiveGrowthProblem(700000, 750000), null);
+ assert.equal(archiveGrowthProblem(790000, 750000, new Map([['archive', 'ships the new guide']])), null);
+});
+
+test('two pull requests that each grow the archive within the allowance both pass against their own base', () => {
+ const mainBase = 750000;
+ const firstPull = archiveGrowthProblem(mainBase + 14000, mainBase);
+ const mainAfterFirst = mainBase + 14000;
+ const secondPull = archiveGrowthProblem(mainAfterFirst + 14000, mainAfterFirst);
+ assert.equal(firstPull, null);
+ assert.equal(secondPull, null);
+ assert.match(archiveGrowthProblem(mainAfterFirst + 16000, mainAfterFirst), /over its allowance of 15280/);
+});
+
+test('the release ceiling is a report that names the number a release refreshes', () => {
+ assert.match(archiveCeilingProblem(741000, 740000), /over its release ceiling of 740000 in bench\/size\/budgets\.json by 1000/);
+ assert.equal(archiveCeilingProblem(739000, 740000), null);
});
function git(folder, ...args) {