3D engine that AI agents drive
Merge branch coverage stably across shards and run 12 unit shards (#1004)
Nguyen Xuan An1eb32cd9a816
diff --git a/.github/workflows/test.yml b/.github/workflows/test.ymlindex 032a9fb3..315d3b55 100644--- a/.github/workflows/test.yml+++ b/.github/workflows/test.yml@@ -64,20 +64,20 @@ jobs:- run: npm run tool-cost -- --base "$SIZE_BASE_REF"# `node --test` already runs every file in its own process (Node 24 default, --test-isolation=process), so one pass over- # the files is also the isolation check. Eight shards of hashed file names (scripts/shard-test-files.mjs). The light bake tests are heavy, so one shard of three took twice as long as the others.+ # the files is also the isolation check. Twelve shards balanced by measured time (scripts/shard-test-files.mjs). The light bake tests are heavy, so one shard of three took twice as long as the others.unit:runs-on: ubuntu-latesttimeout-minutes: 15strategy:fail-fast: falsematrix:- shard: [1, 2, 3, 4, 5, 6, 7, 8]+ shard: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12]steps:- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1- uses: ./.github/actions/setup# The live MCP tests need build/ and build/mcp.- run: npm run build:lib- - run: mkdir -p coverage && npm run test:coverage -- --test-reporter=spec --test-reporter-destination=stdout --test-reporter=lcov --test-reporter-destination=coverage/shard-${{ matrix.shard }}.info --test-reporter=./scripts/test-timing-reporter.mjs --test-reporter-destination=coverage/timings-${{ matrix.shard }}.json $(node scripts/shard-test-files.mjs ${{ matrix.shard }} 8)+ - run: mkdir -p coverage && npm run test:coverage -- --test-reporter=spec --test-reporter-destination=stdout --test-reporter=lcov --test-reporter-destination=coverage/shard-${{ matrix.shard }}.info --test-reporter=./scripts/test-timing-reporter.mjs --test-reporter-destination=coverage/timings-${{ matrix.shard }}.json $(node scripts/shard-test-files.mjs ${{ matrix.shard }} 12)- uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2if: always()with:diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex be3f21fd..cfdee39f 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -63,7 +63,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 run tool-cost`, `npm test` (with coverage, eight shards; Node runs each 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.+Every pull request runs `npm audit`, `npm run size`, `npm run tool-cost`, `npm test` (with coverage, twelve shards; Node runs each 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-ceilings.json` holds fixed absolute ceilings (the schema total, each tool and the default `scene_capabilities` answer) that fail the check whatever the growth. Put field detail in a `scene_capabilities` topic and keep only the common fields in the tool schema. `bench/tool-cost/README.md` has the details.diff --git a/coverage-baseline.json b/coverage-baseline.jsonindex 1240896c..31d75572 100644--- a/coverage-baseline.json+++ b/coverage-baseline.json@@ -1 +1 @@-{"lines":93.79,"branches":78.45,"functions":92.28}+{"lines":93.79,"branches":89.7,"functions":92.28}diff --git a/docs/ci.md b/docs/ci.mdindex 3867470c..197b8383 100644--- a/docs/ci.md+++ b/docs/ci.md@@ -10,7 +10,7 @@ All jobs start at once.| --- | --- || `audit` | `npm audit --audit-level=high` || `size` | `npm run size` and `npm run tool-cost` against the pull request base (pull requests only; a release has no base) |-| `unit` (8 shards balanced by measured time, `scripts/shard-test-files.mjs` and `test-timings.json`) | `npm run build:lib`, then `npm run test:coverage` on one eighth of the test files; uploads its lcov and per-file timings |+| `unit` (12 shards balanced by measured time, `scripts/shard-test-files.mjs` and `test-timings.json`) | `npm run build:lib`, then `npm run test:coverage` on one twelfth of the test files; uploads its lcov and per-file timings || `coverage` | merges the shard lcov files, writes the summary, compares with `coverage-baseline.json`, uploads `lcov` || `package` | `prepare:release`, `check:links:package`, `smoke:package`, `smoke:mcp-package` || `bun` | `smoke:mcp-package` with `MCP_SERVER_RUNTIME=bun`: the packed MCP server runs under bun, the way `bunx 67js-mcp` starts it |diff --git a/scripts/coverage-gate.mjs b/scripts/coverage-gate.mjsindex 01228983..b2847b8f 100644--- a/scripts/coverage-gate.mjs+++ b/scripts/coverage-gate.mjs@@ -2,6 +2,7 @@// any figure falls more than the allowed margin below the committed baseline (coverage-baseline.json).// Raising the baseline is a manual edit of that file. The function figure counts each function once per source line,// so the baseline was re-measured (93.4 to 92.28 on the same commit) when unnamed functions stopped being counted per shard.+// The branch figure counts each branch once per source line and position on that line, for the same reason (see branchKey).// Usage: node scripts/coverage-gate.mjs <lcov file or folder>... [--baseline coverage-baseline.json] [--merged-out merged.lcov]import { appendFileSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';import { join, resolve } from 'node:path';@@ -52,11 +53,24 @@ function functionEntry(record, key, line, name) {return record.functions.get(key);}+// V8 numbers the blocks of a file per process, in the order it reports them, and a shard that never runs a function reports+// that function as one range instead of its nested blocks. The same block id therefore points at different branches in+// different shards, and keying by it counted one branch once per shard layout (more shards, lower figure). A branch is+// identified by its line and by its position among the branches reported for that line, which every shard agrees on+// for the branches it reports. A shard that reports fewer branches on a line only adds hits to the first ones.+function branchKey(line, branch, positionByLine) {+ const lineAndBranch = `${line},${branch}`;+ const position = positionByLine.get(lineAndBranch) ?? 0;+ positionByLine.set(lineAndBranch, position + 1);+ return `${line},${position},${branch}`;+}+export function mergeLcov(texts) {const files = new Map();for (const text of texts) {let record = null;let keyByName = new Map();+ let branchPositionByLine = new Map();for (const row of text.split(/\r?\n/)) {const separator = row.indexOf(':');const tag = separator < 0 ? row : row.slice(0, separator);@@ -64,14 +78,15 @@ export function mergeLcov(texts) {if (tag === 'SF') {record = fileRecord(files, value);keyByName = new Map();+ branchPositionByLine = new Map();} else if (!record) {continue;} else if (tag === 'DA') {const [line, hits] = value.split(',');addHits(record.lines, line, Number(hits));} else if (tag === 'BRDA') {- const [line, block, branch, hits] = value.split(',');- addHits(record.branches, `${line},${block},${branch}`, hits === '-' ? 0 : Number(hits));+ const [line, , branch, hits] = value.split(',');+ addHits(record.branches, branchKey(line, branch, branchPositionByLine), hits === '-' ? 0 : Number(hits));} else if (tag === 'FN') {const [line, name] = value.split(',');const key = functionKey(line, name);diff --git a/tests/coverage-gate.test.js b/tests/coverage-gate.test.jsindex acfe8d66..60ea0ed0 100644--- a/tests/coverage-gate.test.js+++ b/tests/coverage-gate.test.js@@ -29,3 +29,20 @@ test('a function hit in only one shard counts as covered', () => {const { totals } = totalsOf(mergeLcov([firstShard, secondShard]));assert.deepEqual(totals.functions, [1, 1]);});++// Real V8 shards number the blocks of a file in the order they report them, so one branch carries different block ids in+// different shards and a shard that never runs a function reports it as a single range.+const branchShardA = ['SF:src/example.js', 'BRDA:10,0,0,4', 'BRDA:10,1,0,0', 'BRDA:20,2,0,1', 'end_of_record'].join('\n');+const branchShardB = ['SF:src/example.js', 'BRDA:5,0,0,0', 'BRDA:10,1,0,0', 'BRDA:10,2,0,2', 'BRDA:20,3,0,0', 'end_of_record'].join('\n');+const branchShardC = ['SF:src/example.js', 'BRDA:10,7,0,0', 'end_of_record'].join('\n');++test('a branch counts once however the shards number their blocks', () => {+ const { totals } = totalsOf(mergeLcov([branchShardA, branchShardB, branchShardC]));+ assert.deepEqual(totals.branches, [3, 4]);+});++test('the branch total does not depend on how the same shards are grouped', () => {+ const allApart = totalsOf(mergeLcov([branchShardA, branchShardB, branchShardC])).totals.branches;+ const together = totalsOf(mergeLcov([[branchShardA, branchShardB].join('\n'), branchShardC])).totals.branches;+ assert.deepEqual(allApart, together);+});