Skip to content

armgit / 67.js

Public Imported from GitHub
0

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.yml
index 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-latest
timeout-minutes: 15
strategy:
fail-fast: false
matrix:
- 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.2
if: always()
with:
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 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 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` (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.json
index 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.md
index 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.mjs
index 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.js
index 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);
+});