Skip to content

armgit / 67.js

Public Imported from GitHub
0

3D engine that AI agents drive

Contribution flow: templates, guide and a friendly PR check

Nguyen Xuan Anc525b5b7e89b
diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
new file mode 100644
index 00000000..20b288ff
--- /dev/null
+++ b/.github/CODEOWNERS
@@ -0,0 +1,2 @@
+# The maintainer reviews every change. Review is not required for a merge: see CONTRIBUTING.md#review-and-merge.
+* @anxuanng
diff --git a/.github/ISSUE_TEMPLATE/bug.yml b/.github/ISSUE_TEMPLATE/bug.yml
index 0f8a634d..4775825c 100644
--- a/.github/ISSUE_TEMPLATE/bug.yml
+++ b/.github/ISSUE_TEMPLATE/bug.yml
@@ -1,6 +1,6 @@
name: Bug report
description: Something renders wrong, throws, crashes or runs slower than it should.
-labels: [bug]
+labels: [bug, needs-triage]
body:
- type: markdown
attributes:
@@ -19,6 +19,16 @@ body:
- Other
validations:
required: true
+ - type: dropdown
+ id: goal
+ attributes:
+ label: Goal (optional)
+ description: Which part of the goal this touches. Choose "Not sure" and the maintainer sets it.
+ options:
+ - Not sure
+ - capable (it cannot do something it should)
+ - light (it is too big or too slow)
+ - ai (an agent trips on it)
- type: textarea
id: what-happened
attributes:
diff --git a/.github/ISSUE_TEMPLATE/feature.yml b/.github/ISSUE_TEMPLATE/feature.yml
index 5ecfc4d1..f52847bb 100644
--- a/.github/ISSUE_TEMPLATE/feature.yml
+++ b/.github/ISSUE_TEMPLATE/feature.yml
@@ -1,6 +1,6 @@
name: Feature request
description: Something 67js or its MCP tools should be able to do.
-labels: [enhancement]
+labels: [enhancement, needs-triage]
body:
- type: markdown
attributes:
@@ -24,12 +24,32 @@ body:
id: done-when
attributes:
label: Done when
- description: How we will know it works, as a checklist.
+ description: How we will know it works. Write one checkbox line for each result, starting with "- [ ]". Contributors copy this list into their pull request.
placeholder: |
- [ ] An agent can ... in one tool call
- [ ] A test covers ...
validations:
required: true
+ - type: dropdown
+ id: goal
+ attributes:
+ label: Goal (optional)
+ description: Which part of the goal this serves. Choose "Not sure" and the maintainer sets it.
+ options:
+ - Not sure
+ - capable (do more, like Blender)
+ - light (stay small and fast, like three.js)
+ - ai (make agents succeed in fewer calls)
+ - type: dropdown
+ id: priority
+ attributes:
+ label: Priority (optional)
+ description: How soon you need it. The maintainer sets the final priority.
+ options:
+ - Not sure
+ - must (blocks something)
+ - should (clearly useful)
+ - could (nice to have)
- type: checkboxes
id: contribute
attributes:
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
index 3091fac4..014f5e20 100644
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -2,16 +2,33 @@
<!-- One or two sentences: what a user or an agent can do now, or what got better. -->
+<!-- Write `Closes #123`. Use `Part of #123` when this is one step of a larger issue. CONTRIBUTING.md#link-the-issue -->
Closes #
+## Done when
+
+<!-- Copy the checklist from the issue and tick what this pull request does. -->
+
+- [ ]
+
## How I checked it
-- [ ] `npm run preflight` passed
-- [ ] `changes/<issue>.md` added (skip for CI, docs or test-only changes)
-- [ ] The guide in `docs/` describes the change
+<!-- Paste the commands you ran and what they printed. Coding agents too: show the commands and their results. -->
+
+## GPU or person checks
+
+<!-- Name each check from CONTRIBUTING.md#checks that applies and what you saw. If you could not run one, say so: a maintainer runs it and adds status:needs-gpu-check. Delete this section if none applies. -->
-<!-- Checks that need a GPU or a person (CONTRIBUTING.md#checks). Name the ones you ran and what you saw, or say why you could not. -->
+## Look change
+
+<!-- Only for shaders, lighting, materials, the default render or post steps. Add a before and an after picture. The label hold:look-approval is added by a bot, and only the owner removes it. Delete this section otherwise. -->
+
+## Tool schema or skill bench
+
+<!-- Only when you change an MCP tool, its schema or a skill. Paste the table from `bench/agent-modeling/compare-bench.mjs`. Without a Claude Code login, write that and a maintainer runs it. CONTRIBUTING.md#tool-schema-and-skill-changes. Delete this section otherwise. -->
## Size or tool cost
-<!-- Delete this section unless a bundle or an MCP tool grew. Say why it is worth the bytes; the line goes in changes/<issue>.size.md. -->
+<!-- Only when a bundle or an MCP tool grew. Say why it is worth the bytes. The line goes in changes/<issue>.size.md. Delete this section otherwise. -->
+
+Issues and pull requests are public, so keep local paths, tokens and personal data out of them. The maintainer sets the labels and the milestone.
diff --git a/.github/workflows/pr-metadata.yml b/.github/workflows/pr-metadata.yml
new file mode 100644
index 00000000..021cf145
--- /dev/null
+++ b/.github/workflows/pr-metadata.yml
@@ -0,0 +1,47 @@
+name: PR metadata
+
+# A friendly check of the pull request description, files and labels against CONTRIBUTING.md. It is not a required check.
+# It runs on pull_request_target so that it can comment on pull requests from forks. For that reason it NEVER checks out,
+# builds or runs the pull request's code: the checkout is the base branch (the default for this event), and the pull request
+# is read through the API only. Keep it that way. The hourly schedule sends the 24 hour reminder and closes pull requests
+# that stayed unfixed for 72 hours. How it works and how to test it: CONTRIBUTING.md#the-pull-request-check.
+on:
+ pull_request_target:
+ types: [opened, edited, synchronize, reopened, labeled, unlabeled, milestoned, demilestoned, ready_for_review]
+ schedule:
+ - cron: '17 * * * *'
+ workflow_dispatch:
+ inputs:
+ dry_run:
+ description: Log what the bot would do and change nothing
+ type: boolean
+ default: true
+
+permissions:
+ contents: read
+ pull-requests: write
+ issues: write
+
+concurrency:
+ group: pr-metadata-${{ github.event.pull_request.number || 'sweep' }}
+ cancel-in-progress: false
+
+jobs:
+ check:
+ runs-on: ubuntu-latest
+ timeout-minutes: 10
+ steps:
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+ with:
+ persist-credentials: false
+ - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+ with:
+ node-version: '24'
+ package-manager-cache: false
+ - uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+ env:
+ PR_METADATA_DRY_RUN: ${{ github.event_name == 'workflow_dispatch' && inputs.dry_run && '1' || '0' }}
+ with:
+ script: |
+ const { runPullRequestCheck } = await import(`${process.env.GITHUB_WORKSPACE}/scripts/pr-metadata-run.mjs`);
+ await runPullRequestCheck({ github, context, core });
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index eb1daa68..032a9fb3 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -22,6 +22,22 @@ jobs:
- uses: ./.github/actions/setup
- run: npm audit --audit-level=high
+ # The cheap gates of `npm run preflight` that need no tests: protected files and the change note. The pre-push hook runs them
+ # too, but `git push --no-verify` skips the hook, so CI is where they cannot be skipped. A release run has no base to compare.
+ change-note:
+ if: github.event_name == 'pull_request'
+ runs-on: ubuntu-latest
+ timeout-minutes: 5
+ steps:
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+ with:
+ fetch-depth: 2
+ - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+ with:
+ node-version: '24'
+ package-manager-cache: false
+ - run: npm run check:change-note
+
# Size and tool cost compare against the pull request base, which only a merge commit has, so a release run skips them.
size:
if: github.event_name == 'pull_request'
@@ -123,7 +139,7 @@ jobs:
test:
if: always()
- needs: [audit, size, unit, coverage, package, bun]
+ needs: [audit, change-note, size, unit, coverage, package, bun]
runs-on: ubuntu-latest
steps:
# A skipped size job is expected outside pull requests. Anything else that is not a success fails the check.
@@ -136,7 +152,7 @@ jobs:
const needs = JSON.parse(require("fs").readFileSync(0, "utf8"));
let failed = false;
for (const [name, { result }] of Object.entries(needs)) {
- const expectedSkip = name === "size" && process.env.EVENT_NAME !== "pull_request";
+ const expectedSkip = (name === "size" || name === "change-note") && process.env.EVENT_NAME !== "pull_request";
const ok = result === "success" || (result === "skipped" && expectedSkip);
console.log(`${ok ? "ok " : "FAIL"} ${name}: ${result}`);
if (!ok) failed = true;
diff --git a/AGENTS.md b/AGENTS.md
index 9e60f13b..8f2ac9bd 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -37,7 +37,10 @@ For one test file: `node --test tests/<area>.test.js`.
## Rules that fail a pull request
-- Add `changes/<issue>.md` with one bullet when you change `src/`, `bin/`, `packages/` or `skills/` ([changes/README.md](changes/README.md)).
+- Add `changes/<issue>.md` with one bullet when you change `src/`, `bin/`, `packages/` or `skills/` ([changes/README.md](changes/README.md) has the naming rule).
+- Name the branch `<issue>-<slug>` and the pull request `<imperative sentence> (#<issue>)`. Put `Closes #N` or `Part of #N` in the description and paste the commands you ran with their results.
+- A change to an MCP tool schema or a skill needs the Haiku bench table in the pull request ([CONTRIBUTING.md](CONTRIBUTING.md#tool-schema-and-skill-changes)).
+- Look changes (shaders, lighting, materials, default render, post steps) carry `hold:look-approval`. Never remove it and never merge: only the maintainer merges.
- Never edit `CHANGELOG.md`, `bench/size/budgets.json`, `bench/size/baseline.json` or `bench/tool-cost-budgets.json`. Maintainers reset them at release.
- A bundle that grows past its allowance needs a line in `changes/<issue>.size.md` that says why the bytes are worth it ([bench/size/README.md](bench/size/README.md)). The same file accepts tool cost growth ([bench/tool-cost/README.md](bench/tool-cost/README.md)).
- Coverage may not drop. Write the tests in the same commit as the code.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 44960081..ff0a8f7f 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,8 +1,10 @@
# Contributing to 67js
-This file covers setup, the checks a change must pass, the code style and the release flow.
+This file covers setup, how to send a change, the checks it must pass, the code style and the release flow.
Coding agents can start with [AGENTS.md](AGENTS.md), the short version. Everyone follows the [code of conduct](CODE_OF_CONDUCT.md).
To ask a question or report a bug, see [SUPPORT.md](SUPPORT.md).
+A maintainer gives a first answer to every issue and pull request within about 7 days.
+Coding agents are welcome to open pull requests. There is no disclosure box: the person who opens the pull request answers for it.
## Set up
@@ -16,18 +18,38 @@ The tests are in `tests/` and the guides are in `docs/`.
## Make a change
-1. For a large feature, open an issue first with the feature form, so that we agree on the design before you write it. Issues labelled `good first issue` are a good place to start.
-2. Create a branch from `main`.
-3. Write the change and its tests in the same commit.
-4. Update the guide in `docs/` that describes the feature.
-5. Add `changes/<issue-or-branch>.md` with your changelog bullet (format in `changes/README.md`). Do not edit `CHANGELOG.md`: two pull requests that edit it conflict on GitHub.
-6. Open a pull request. The template asks what changed and how you checked it.
+1. Pick an issue. Issues labelled `good first issue` or `help wanted` are good places to start. For a large feature with no issue, open one with the feature form first. We then agree on the design before you write it.
+2. Comment on the issue that you take it, so that two people do not build the same thing.
+3. Fork the repository (`gh repo fork codepawl/67.js --clone`) and create a branch from `main` named `<issue>-<short-slug>`, such as `412-mesh-bevel`.
+4. Write the change and its tests in the same commit, and update the guide in `docs/` that describes the feature.
+5. Add a change note (see [Change notes](#change-notes)). Do not edit `CHANGELOG.md`: two pull requests that edit it conflict on GitHub.
+6. Run `npm run preflight`, then push and open a pull request. The template asks what changed and how you checked it.
+
+Name the pull request `<imperative sentence> (#<issue>)`, such as `Add mesh bevel to scene_edit_mesh (#412)`. Keep one change in each pull request.
+
+### Link the issue
+
+Write `Closes #123` in the description when the pull request finishes the issue. Write `Part of #123` when it is one step of a larger issue. Issues are for work to do, so there is no tracking issue to link.
+
+### Change notes
+
+Every change under `src/`, `bin/`, `packages/` or `skills/` adds `changes/<issue>.md` with one changelog bullet. When one issue gets several pull requests, add a slug: `changes/<issue>-<slug>.md`. A size note is `changes/<issue>.size.md` or `changes/<issue>-<slug>.size.md`. CI, docs-only and test-only pull requests need no note. [changes/README.md](changes/README.md) has the format.
+
+The `Test` workflow runs this check on every pull request, so `git push --no-verify` does not skip it.
+
+### Describe how you checked it
+
+Under **How I checked it**, paste the commands you ran and what they printed. A line such as `npm run preflight: 14 checks ok` is enough. This applies to agents too: show the commands and their results.
+
+### Keep private data out
+
+Issues and pull requests are public. Leave out local paths (a Windows user folder, or a home folder under `/home` or `/Users`), tokens and personal data. Use a path inside the repository instead.
## Checks
Run `npm run preflight` before you open a pull request. It runs every check below that applies to the files you changed, plus the size, tool cost and coverage gates, keeps going after a failure and ends with one line per check and how to fix it. Logs go to `artifacts/preflight/`. `--skip-tests` skips the slow test pass while you iterate.
-`npm ci` points git at `.githooks/`, whose pre-push hook runs `npm run preflight -- --skip-tests` and stops the push when a gate fails. Pushing only tags or branch deletions skips it. `SKIP_PREFLIGHT=1 git push` skips it once. The unit tests stay out of the hook because they take minutes; run the full preflight before you open the pull request.
+`npm ci` points git at `.githooks/`, whose pre-push hook runs `npm run preflight -- --skip-tests` and stops the push when a gate fails. Pushing only tags or branch deletions skips it. To skip it once, run `SKIP_PREFLIGHT=1 git push` in Bash or `$env:SKIP_PREFLIGHT=1; git push` in PowerShell. `git push --no-verify` skips it too. The unit tests stay out of the hook because they take minutes; run the full preflight before you open the pull request.
The checks it runs, if you want one alone:
@@ -45,7 +67,7 @@ Every pull request runs `npm audit`, `npm run size`, `npm run tool-cost`, `npm t
`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.
-Branch protection on `main` requires the `test` check to pass before a merge. Merge a pull request only when `GitGuardian Security Checks` also passes.
+Branch protection on `main` requires the `test` check to pass before a merge. `GitGuardian Security Checks` is an external check that must also pass.
These checks need a GPU or a person's eyes, so they do not run on a pull request. The author runs each one that applies:
@@ -58,8 +80,62 @@ These checks need a GPU or a person's eyes, so they do not run on a pull request
| `scripts/blender-golden.py` | A case in `tests/fixtures/blender/cases.json`, or the Blender version |
| `scripts/blender-easing-golden.py` | An easing curve, or the Blender version |
+### Tool schema and skill changes
+
+A change to an MCP tool, its schema or a skill under `skills/` also needs the agent bench. A longer schema can lower how often an agent succeeds. Run Haiku alone, because it reacts first, and compare it with the baseline:
+
+```sh
+node bench/agent-modeling/bench.mjs --models haiku --runs 3 --label <branch> --backend cpu
+node bench/agent-modeling/compare-bench.mjs bench/agent-modeling/results/bench-baseline.json bench/agent-modeling/results/bench-<branch>.json
+```
+
+Paste the table into the pull request. The bench runs through a Claude Code login. Without one, say so in the pull request and a maintainer runs it. [bench/agent-modeling/README.md](bench/agent-modeling/README.md) has the details.
+
+### Look changes
+
+A change to shaders, lighting, materials, the default render or a post step changes how every scene looks. Add a before and an after picture to the pull request. A bot adds the label `hold:look-approval`. Only the owner removes it, and nothing with that label merges.
+
+### Who runs the GPU and person checks
+
+You run the checks in the table above that apply, when you can. When you cannot (for example, you have no GPU), say so in the pull request. A maintainer runs them and adds the label `status:needs-gpu-check`. The merge waits for them only for look and renderer changes.
+
Do not weaken a test to make it pass. If a test is flaky, find the cause and fix the test or the code.
+## Labels and milestones
+
+The maintainer sets labels and the milestone, so you do not need to. Every issue has one goal and one priority:
+
+- `goal:capable`, `goal:light` or `goal:ai` say which part of the [goal](docs/goal.md) the work serves.
+- `priority:must`, `priority:should` or `priority:could` say how soon.
+- `bug`, `enhancement` or `documentation` say what kind of work it is.
+
+The milestones are `0 Measure`, `1 Lighter`, `2 Modeling`, `3 Look`, `4 Motion and simulation`, `5 Agent surface` and `6 Games`. [docs/goal.md](docs/goal.md) explains each one. A pull request that misses a label or the milestone gets `needs-triage` until the maintainer sets them.
+
+## Review and merge
+
+Only the maintainer merges. There is no required review and no auto-merge. A pull request merges when the `test` check passes, `GitGuardian Security Checks` passes, and the maintainer has looked at it. [CODEOWNERS](.github/CODEOWNERS) lists the maintainer.
+
+## The pull request check
+
+The `PR metadata` workflow checks each pull request against this guide. It posts one friendly comment that lists what is missing, with a link to the section that explains each item. The checks are:
+
+- The description links an issue and says how you checked.
+- Shipped code has a change note.
+- Tool and skill changes have a bench table.
+- Look changes have a picture.
+- The description holds no local path.
+
+Docs-only, CI-only and test-only pull requests skip everything except the local path check.
+
+- The comment updates itself when you fix an item. One reminder follows when 24 hours are left.
+- If an item is still open 72 hours after the first comment, the bot closes the pull request. It invites you to reopen it once the item is fixed, and reopening starts the time again.
+- Pull requests from the owner, members, collaborators and bots never close by themselves. Drafts and pull requests labelled `needs-owner-decision` do not close either.
+- Labels and the milestone never count against you. The bot adds `needs-triage` when they are missing and `status:needs-author` while something of yours is missing.
+
+For maintainers: the workflow is `.github/workflows/pr-metadata.yml`, and the rules are the pure modules `scripts/pr-metadata-check.mjs` (what is missing) and `scripts/pr-metadata-flow.mjs` (the clock and the wording). The workflow runs on `pull_request_target`, so it never checks out or runs the code of the pull request. It reads the description and the file list through the API only. Do not change that. It is not a required check.
+
+To test a change to the rules, run `node --test tests/pr-metadata-check.test.js`. To see what the bot would do on the real repository without changing anything, run the workflow by hand: `gh workflow run pr-metadata.yml -f dry_run=true`, then read the log. A run with `dry_run=false` sweeps every open pull request.
+
## Code style
- Use descriptive full names. Write `positionCount`, not `n` or `cnt`. Short names are fine for small loop indices.
diff --git a/bench/size/README.md b/bench/size/README.md
index b5ea7a23..07527b38 100644
--- a/bench/size/README.md
+++ b/bench/size/README.md
@@ -63,7 +63,7 @@ A bundle that the base does not have is reported and never fails. A bundle that
The table in the output shows each bundle, the base size, the growth and the allowance. The release budgets in `budgets.json` are printed as a report and do not fail a pull request.
-The goals in `budgets.json` (`lit-box`, `gltf-box`, `agent-scene`) also gate: a goal scene that was at or under its goal on the base and goes over it fails, even inside its allowance, because many small accepted increases otherwise add up past the goal. Only a `- goal:<scene>: <why>` line accepts that, and An approves those lines. A `scene:<name>` line does not. A scene already over its goal on the base may not grow by more than 8 bytes (two builds of the same source differ by a few bytes gzip), even inside its allowance, until work brings it back under; the same `- goal:<scene>:` line is the only way past.
+The goals in `budgets.json` (`lit-box`, `gltf-box`, `agent-scene`) also gate: a goal scene that was at or under its goal on the base and goes over it fails, even inside its allowance, because many small accepted increases otherwise add up past the goal. Only a `- goal:<scene>: <why>` line accepts that, and the maintainer approves those lines. A `scene:<name>` line does not. A scene already over its goal on the base may not grow by more than 8 bytes (two builds of the same source differ by a few bytes gzip), even inside its allowance, until work brings it back under; the same `- goal:<scene>:` line is the only way past.
## When a check fails
diff --git a/changes/README.md b/changes/README.md
index 638d245d..e411f277 100644
--- a/changes/README.md
+++ b/changes/README.md
@@ -1,6 +1,13 @@
# Change notes
-Each pull request adds one file here, such as `changes/issue-199.md`, with its changelog bullet exactly as it should read in `CHANGELOG.md`:
+## Name the file
+
+- `changes/<issue>.md`, such as `changes/199.md`, is the note of a pull request that works on issue 199.
+- When one issue gets several pull requests, add a slug: `changes/199-edges.md`.
+- A size note adds `.size`: `changes/<issue>.size.md` or `changes/<issue>-<slug>.size.md`.
+- A pull request that changes only CI, docs or tests needs no note. Every change under `src/`, `bin/`, `packages/` or `skills/` needs one. The `Test` workflow checks that, and `npm run check:change-note` runs the same check on your machine.
+
+Other docs link here for the rule. Each note holds the changelog bullet exactly as it should read in `CHANGELOG.md`:
```md
- `bar` takes a `foo` option for X (#123)
@@ -12,4 +19,4 @@ Do not edit `CHANGELOG.md` in a pull request. Two pull requests then never touch
`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. Then edit that section by hand before the release: merge bullets about the same feature, drop internal ones (benchmark scripts, CI, refactors with no visible effect), and sort the rest under `### Highlights`, `### Agents and MCP`, `### Rendering`, `### glTF`, `### Animation and physics`, `### Tools, docs and site` and `### Breaking changes`. The site shows each `###` heading, and every entry under `Breaking changes` gets the breaking mark.
-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. The same note accepts a tool cost increase, with lines such as `- tool:scene_create: <reason>`, and `bench/tool-cost/README.md` says how.
+A size note 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. The same note accepts a tool cost increase, with lines such as `- tool:scene_create: <reason>`, and `bench/tool-cost/README.md` says how.
diff --git a/package.json b/package.json
index a8b84b26..49442cc8 100644
--- a/package.json
+++ b/package.json
@@ -225,6 +225,7 @@
"check:links": "node scripts/check-links.mjs",
"changes": "node scripts/changelog-fragments.mjs",
"changes:fold": "node scripts/changelog-fragments.mjs fold",
+ "check:change-note": "node scripts/check-change-note.mjs",
"check:links:package": "node scripts/check-links.mjs --package"
},
"peerDependencies": {
diff --git a/scripts/check-change-note.mjs b/scripts/check-change-note.mjs
new file mode 100644
index 00000000..ade4c494
--- /dev/null
+++ b/scripts/check-change-note.mjs
@@ -0,0 +1,44 @@
+// The cheap, test-free gates of `npm run preflight` that must also run on CI, because `git push --no-verify` skips the
+// pre-push hook: the protected files and the change note. Usage: npm run check:change-note
+// In CI it compares with the first parent of the merge commit (scripts/ci-base-sha.mjs). Elsewhere pass --base <ref>.
+import { spawnSync } from 'node:child_process';
+import { pathToFileURL } from 'node:url';
+import { resolve } from 'node:path';
+import { planChecks } from './preflight.mjs';
+import { pullRequestBaseOf } from './size-base.mjs';
+
+const gateNames = new Set(['protected files', 'change note']);
+
+// Returns the failing gates for a list of changed paths. Pure, so tests can call it without git.
+export function failingGatesFor(changedPaths) {
+ return planChecks(changedPaths, { skipTests: true })
+ .filter(check => gateNames.has(check.name) && check.failure)
+ .map(check => ({ name: check.name, failure: check.failure, fix: check.fix }));
+}
+
+function git(args) {
+ const result = spawnSync('git', args, { encoding: 'utf8' });
+ if (result.status !== 0) throw new Error(`git ${args.join(' ')} failed: ${result.stderr.trim()}`);
+ return result.stdout.trim();
+}
+
+function baseRefFromArguments() {
+ const flagIndex = process.argv.indexOf('--base');
+ if (flagIndex !== -1) return process.argv[flagIndex + 1];
+ return pullRequestBaseOf() ?? git(['rev-parse', 'HEAD^1']);
+}
+
+function main() {
+ const baseRef = baseRefFromArguments();
+ const changedPaths = git(['diff', '--name-only', baseRef, 'HEAD']).split('\n').filter(Boolean);
+ const failing = failingGatesFor(changedPaths);
+ for (const gate of failing) {
+ console.error(`FAIL ${gate.name}: ${gate.failure}\n Fix: ${gate.fix}`);
+ }
+ if (failing.length === 0) console.log(`ok: ${changedPaths.length} changed files pass the protected file and change note gates.`);
+ return failing.length === 0 ? 0 : 1;
+}
+
+if (import.meta.url === pathToFileURL(resolve(process.argv[1] ?? '')).href) {
+ process.exit(main());
+}
diff --git a/scripts/pr-metadata-check.mjs b/scripts/pr-metadata-check.mjs
new file mode 100644
index 00000000..6e085ca4
--- /dev/null
+++ b/scripts/pr-metadata-check.mjs
@@ -0,0 +1,188 @@
+// Checks the description and the files of a pull request against CONTRIBUTING.md. Pure: it reads no network and no disk,
+// so tests call it with plain objects. The `PR metadata` workflow (.github/workflows/pr-metadata.yml) runs it on the base branch.
+//
+// Input: { pr: { body, title, author, authorAssociation, labels, milestone, draft }, files: [{ filename, additions, deletions }] }
+// Output: { contributorFixes: [{ id, message, docsAnchor }], maintainerTodos: [string], addLabels: [string], removeLabels: [string] }
+//
+// A contributor fix is something the author can change. Labels and the milestone are the maintainer's job, so a gap there
+// becomes a maintainer todo and the `needs-triage` label, and never counts against the author.
+
+export const LOOK_HOLD_LABEL = 'hold:look-approval';
+export const NEEDS_TRIAGE_LABEL = 'needs-triage';
+export const NEEDS_AUTHOR_LABEL = 'status:needs-author';
+export const NEEDS_OWNER_DECISION_LABEL = 'needs-owner-decision';
+
+const OWNER_LOGIN = 'anxuanng';
+const TRUSTED_ASSOCIATIONS = new Set(['OWNER', 'MEMBER', 'COLLABORATOR']);
+
+const shippedPathPattern = /^(src|bin|packages|skills)\//;
+const toolOrSkillPathPattern = /^(src\/(agent-|mcp)|bin\/|skills\/)/;
+const lightPathPattern = /^(docs\/|\.github\/|tests\/|changes\/)|\.md$/;
+// A look change touches shaders, lighting, materials, the default render or a post step. A name part must stand alone, so
+// "flight" and "highlight" do not match "light".
+const lookNamePattern = /(^|[-_/.])(shaders?|glsl|lights?|lighting|materials?|environment|shadows?|tone|tonemap|fog|sky|post|bloom|ssao|taa|exposure)(?=$|[-_/.])/i;
+const lookRootPattern = /^(src|packages)\//;
+
+const linkedIssuePattern = /\b(?:closes|close|closed|fixes|fix|fixed|resolves|resolve|resolved|part of)\s+(?:#\d+|https:\/\/github\.com\/codepawl\/67\.js\/issues\/\d+)/i;
+const localPathPatterns = [
+ /[A-Za-z]:\\+(?:Users|Documents and Settings)\\/i,
+ /(?:^|[\s`"'(=])\/home\/[A-Za-z0-9._-]+/,
+ /(?:^|[\s`"'(=])\/Users\/[A-Za-z0-9._-]+/,
+];
+const imagePattern = /!\[[^\]]*\]\([^)]+\)|<img\b|github\.com\/user-attachments\//i;
+const benchOptOutPattern = /(?:no|without)\b[^.\n]*claude code login|maintainer\b[^.\n]*\b(?:run|runs)\b[^.\n]*\bbench/i;
+
+function stripHtmlComments(text) {
+ return text.replace(/<!--[\s\S]*?-->/g, '');
+}
+
+// The text under "## <heading>" up to the next "## " heading, or null when the section is missing.
+export function sectionOf(body, heading) {
+ const lines = stripHtmlComments(body).split(/\r?\n/);
+ const wanted = heading.toLowerCase();
+ const start = lines.findIndex(line => /^##\s+/.test(line) && line.replace(/^##\s+/, '').trim().toLowerCase() === wanted);
+ if (start === -1) return null;
+ const collected = [];
+ for (let index = start + 1; index < lines.length; index += 1) {
+ if (/^##\s+/.test(lines[index])) break;
+ collected.push(lines[index]);
+ }
+ return collected.join('\n');
+}
+
+function hasContent(sectionText) {
+ if (sectionText === null) return false;
+ const meaningful = sectionText
+ .split('\n')
+ .filter(line => !/^\s*[-*]\s+\[ \]/.test(line))
+ .join('\n')
+ .trim();
+ return meaningful.length >= 10;
+}
+
+function normalizePath(path) {
+ return path.replace(/\\/g, '/');
+}
+
+export function isLookPath(path) {
+ const normalized = normalizePath(path);
+ return lookRootPattern.test(normalized) && lookNamePattern.test(normalized);
+}
+
+// Docs, CI and test only pull requests skip every rule except the local path one.
+export function isLightPullRequest(files) {
+ return files.length > 0 && files.every(file => {
+ const path = normalizePath(file.filename);
+ return !shippedPathPattern.test(path) && lightPathPattern.test(path);
+ });
+}
+
+// Owner, maintainers, collaborators and bots are never closed by the bot. The check still reports for them.
+export function isAutoCloseExempt(pr) {
+ const author = (pr.author ?? '').toLowerCase();
+ return author === OWNER_LOGIN
+ || author.endsWith('[bot]')
+ || TRUSTED_ASSOCIATIONS.has(pr.authorAssociation ?? '');
+}
+
+function fix(id, message, docsAnchor) {
+ return { id, message, docsAnchor };
+}
+
+function contributorFixesFor(pr, files, light) {
+ const body = pr.body ?? '';
+ const visibleBody = stripHtmlComments(body);
+ const fixes = [];
+
+ if (localPathPatterns.some(pattern => pattern.test(body))) {
+ fixes.push(fix(
+ 'local-path',
+ 'The description has a path from your computer. Issues and pull requests are public, so swap it for a path inside the repository, or remove it.',
+ 'keep-private-data-out',
+ ));
+ }
+ if (light) return fixes;
+
+ if (!linkedIssuePattern.test(visibleBody)) {
+ fixes.push(fix(
+ 'missing-issue-link',
+ 'Add `Closes #123` to the description. Use `Part of #123` instead when this pull request is one step of a larger issue.',
+ 'link-the-issue',
+ ));
+ }
+ if (!hasContent(sectionOf(body, 'How I checked it'))) {
+ fixes.push(fix(
+ 'empty-how-checked',
+ 'Under **How I checked it**, paste the commands you ran and what they printed, such as `npm run preflight` and its last lines.',
+ 'describe-how-you-checked-it',
+ ));
+ }
+
+ const paths = files.map(file => normalizePath(file.filename));
+ const needsNote = paths.some(path => shippedPathPattern.test(path));
+ const hasNote = paths.some(path => /^changes\/\d+[^/]*\.md$/.test(path) && !path.endsWith('.size.md'));
+ if (needsNote && !hasNote) {
+ fixes.push(fix(
+ 'missing-change-note',
+ 'Add a file named `changes/<issue>.md` with one changelog bullet, such as ``- `bar` takes a `foo` option (#123)``.',
+ 'change-notes',
+ ));
+ }
+
+ const touchesToolOrSkill = paths.some(path => toolOrSkillPathPattern.test(path));
+ const hasBenchTable = /^\s*\|\s*:?-{3,}/m.test(visibleBody) && /bench|haiku|sonnet/i.test(visibleBody);
+ const benchOptOut = benchOptOutPattern.test(visibleBody);
+ if (touchesToolOrSkill && !hasBenchTable && !benchOptOut) {
+ fixes.push(fix(
+ 'missing-bench-table',
+ 'This changes an MCP tool or a skill, so paste the agent bench table in the description. Without a Claude Code login, say so and a maintainer will run it.',
+ 'tool-schema-and-skill-changes',
+ ));
+ }
+
+ const touchesLook = paths.some(isLookPath);
+ if (touchesLook && !imagePattern.test(body)) {
+ fixes.push(fix(
+ 'look-without-image',
+ 'This changes how a scene looks, so add a before and an after picture to the description.',
+ 'look-changes',
+ ));
+ }
+ return fixes;
+}
+
+function maintainerTodosFor(pr, files, contributorFixes) {
+ const labels = pr.labels ?? [];
+ const todos = [];
+ if (!labels.some(label => label.startsWith('goal:'))) todos.push('Set a goal label (goal:capable, goal:light or goal:ai).');
+ if (!labels.some(label => ['bug', 'enhancement', 'documentation'].includes(label))) todos.push('Set a type label (bug, enhancement or documentation).');
+ if (!pr.milestone) todos.push('Set a milestone.');
+ const paths = files.map(file => normalizePath(file.filename));
+ if (paths.some(isLookPath)) todos.push('Look change: only the owner removes hold:look-approval after seeing the pictures.');
+ const needsToolBench = paths.some(path => toolOrSkillPathPattern.test(path));
+ if (needsToolBench && contributorFixes.length === 0 && benchOptOutPattern.test(pr.body ?? '')) {
+ todos.push('Run the agent bench for this pull request (bench/agent-modeling).');
+ }
+ return todos;
+}
+
+export function checkPullRequest({ pr, files }) {
+ const labels = pr.labels ?? [];
+ const light = isLightPullRequest(files);
+ const contributorFixes = contributorFixesFor(pr, files, light);
+ const maintainerTodos = maintainerTodosFor(pr, files, contributorFixes);
+ const addLabels = [];
+ const removeLabels = [];
+
+ const classificationMissing = maintainerTodos.some(todo => /^Set a/.test(todo));
+ if (classificationMissing && !labels.includes(NEEDS_TRIAGE_LABEL)) addLabels.push(NEEDS_TRIAGE_LABEL);
+ if (!classificationMissing && labels.includes(NEEDS_TRIAGE_LABEL)) removeLabels.push(NEEDS_TRIAGE_LABEL);
+
+ if (files.some(file => isLookPath(file.filename)) && !labels.includes(LOOK_HOLD_LABEL)) addLabels.push(LOOK_HOLD_LABEL);
+
+ if (!isAutoCloseExempt(pr)) {
+ if (contributorFixes.length > 0 && !labels.includes(NEEDS_AUTHOR_LABEL)) addLabels.push(NEEDS_AUTHOR_LABEL);
+ if (contributorFixes.length === 0 && labels.includes(NEEDS_AUTHOR_LABEL)) removeLabels.push(NEEDS_AUTHOR_LABEL);
+ }
+ return { contributorFixes, maintainerTodos, addLabels, removeLabels };
+}
diff --git a/scripts/pr-metadata-flow.mjs b/scripts/pr-metadata-flow.mjs
new file mode 100644
index 00000000..a82f6bd1
--- /dev/null
+++ b/scripts/pr-metadata-flow.mjs
@@ -0,0 +1,104 @@
+// The time rules and the wording of the `PR metadata` bot. Pure, so tests call it without GitHub.
+// The bot keeps one status comment per pull request and finds it by a hidden marker. The marker also holds the time of the
+// first failing comment, which starts the 72 hour clock, and the time of the one reminder.
+import { NEEDS_OWNER_DECISION_LABEL } from './pr-metadata-check.mjs';
+
+export const STATUS_MARKER = 'pr-metadata-status';
+export const REMINDER_MARKER = 'pr-metadata-reminder';
+export const CLOSE_MARKER = 'pr-metadata-closed';
+export const HOUR_MS = 60 * 60 * 1000;
+export const REMINDER_AFTER_HOURS = 48;
+export const CLOSE_AFTER_HOURS = 72;
+
+const guideUrl = 'https://github.com/codepawl/67.js/blob/main/CONTRIBUTING.md';
+
+export function buildMarker(name, fields = {}) {
+ const pairs = Object.entries(fields)
+ .filter(([, value]) => value)
+ .map(([key, value]) => `${key}=${value}`);
+ return `<!-- ${[name, ...pairs].join(' ')} -->`;
+}
+
+// Reads `<!-- name key=value key=value -->` from a comment body, or returns null when the comment has no such marker.
+export function parseMarker(commentBody, name) {
+ const match = new RegExp(`<!--\\s*${name}((?:\\s+[a-zA-Z]+=\\S+)*)\\s*-->`).exec(commentBody ?? '');
+ if (!match) return null;
+ const fields = {};
+ for (const pair of match[1].trim().split(/\s+/).filter(Boolean)) {
+ const separator = pair.indexOf('=');
+ fields[pair.slice(0, separator)] = pair.slice(separator + 1);
+ }
+ return fields;
+}
+
+function formatDate(milliseconds) {
+ return new Date(milliseconds).toISOString().slice(0, 10);
+}
+
+function bulletsOf(contributorFixes) {
+ return contributorFixes
+ .map(({ message, docsAnchor }) => `- ${message} [How](${guideUrl}#${docsAnchor})`)
+ .join('\n');
+}
+
+export function renderStatusComment({ contributorFixes, firstFailedAt, reminderSentAt, exempt }) {
+ const marker = buildMarker(STATUS_MARKER, { firstFailedAt, reminderSentAt });
+ if (contributorFixes.length === 0) {
+ return `${marker}\nThank you. The pull request now has everything the guide asks for, and a maintainer will review it as soon as they can.`;
+ }
+ const closeDate = formatDate(Date.parse(firstFailedAt) + CLOSE_AFTER_HOURS * HOUR_MS);
+ const deadline = exempt
+ ? 'This is a maintainer pull request, so it will not close by itself.'
+ : `If these are still open on ${closeDate}, we close the pull request so the queue stays clear. You can reopen it any time after you fix them.`;
+ return [
+ marker,
+ 'Thank you for the pull request. A few small things are missing before a maintainer can review it:',
+ '',
+ bulletsOf(contributorFixes),
+ '',
+ `You can fix these by editing the description or pushing a commit. This comment updates itself when you do. ${deadline}`,
+ '',
+ `Stuck on any of it? Reply here and we will help. The whole flow is in the [contributing guide](${guideUrl}).`,
+ ].join('\n');
+}
+
+export function renderReminderComment({ contributorFixes, closeDate }) {
+ return [
+ buildMarker(REMINDER_MARKER),
+ `A small reminder: these items are still open, and we close the pull request on ${closeDate} if they stay that way.`,
+ '',
+ bulletsOf(contributorFixes),
+ '',
+ 'You can reopen it any time after you fix them. Reply here if you need help.',
+ ].join('\n');
+}
+
+export function renderCloseComment() {
+ return [
+ buildMarker(CLOSE_MARKER),
+ 'Thank you for the work on this. We are closing the pull request because the items above stayed open for 3 days. Nothing is lost.',
+ '',
+ `Once they are fixed, reopen it and the check runs again. Details are in the [contributing guide](${guideUrl}).`,
+ ].join('\n');
+}
+
+// Decides what the bot does with a pull request that has a status comment (or none).
+// previousState is the marker of the status comment: { firstFailedAt, reminderSentAt } or null.
+export function decideActions({ now, contributorFixes, previousState, exempt, draft, labels, reopened }) {
+ const failing = contributorFixes.length > 0;
+ if (!failing) {
+ return { statusState: previousState ? {} : null, remind: false, close: false };
+ }
+ const firstFailedAt = (!reopened && previousState?.firstFailedAt) || new Date(now).toISOString();
+ const reminderSentAt = reopened ? undefined : previousState?.reminderSentAt;
+ const elapsedHours = (now - Date.parse(firstFailedAt)) / HOUR_MS;
+ const protectedFromTimers = exempt || draft || labels.includes(NEEDS_OWNER_DECISION_LABEL);
+ const remind = !protectedFromTimers && !reminderSentAt && elapsedHours >= REMINDER_AFTER_HOURS && elapsedHours < CLOSE_AFTER_HOURS;
+ const close = !protectedFromTimers && elapsedHours >= CLOSE_AFTER_HOURS;
+ return {
+ statusState: { firstFailedAt, reminderSentAt: remind ? new Date(now).toISOString() : reminderSentAt },
+ remind,
+ close,
+ closeDate: formatDate(Date.parse(firstFailedAt) + CLOSE_AFTER_HOURS * HOUR_MS),
+ };
+}
diff --git a/scripts/pr-metadata-run.mjs b/scripts/pr-metadata-run.mjs
new file mode 100644
index 00000000..21799587
--- /dev/null
+++ b/scripts/pr-metadata-run.mjs
@@ -0,0 +1,140 @@
+// GitHub glue of the `PR metadata` workflow. It reads a pull request and its file list through the API, never checks out the
+// pull request's code, and runs the pure rules of pr-metadata-check.mjs and pr-metadata-flow.mjs on them.
+// `github` is the Octokit client that actions/github-script passes in. Tests pass a fake with the same few methods.
+import { checkPullRequest, isAutoCloseExempt, LOOK_HOLD_LABEL } from './pr-metadata-check.mjs';
+import {
+ CLOSE_MARKER,
+ REMINDER_MARKER,
+ STATUS_MARKER,
+ decideActions,
+ parseMarker,
+ renderCloseComment,
+ renderReminderComment,
+ renderStatusComment,
+} from './pr-metadata-flow.mjs';
+
+const BOT_LOGIN = 'github-actions[bot]';
+
+function toCheckInput(pullRequest, files) {
+ return {
+ pr: {
+ body: pullRequest.body ?? '',
+ title: pullRequest.title,
+ author: pullRequest.user?.login ?? '',
+ authorAssociation: pullRequest.author_association,
+ labels: pullRequest.labels.map(label => label.name),
+ milestone: pullRequest.milestone?.title ?? null,
+ draft: Boolean(pullRequest.draft),
+ },
+ files: files.map(file => ({ filename: file.filename, additions: file.additions, deletions: file.deletions })),
+ };
+}
+
+// The owner may remove hold:look-approval. Add it only if it was never added, so a removal sticks.
+async function labelWasEverAdded({ github, repo, number, label }) {
+ const events = await github.paginate(github.rest.issues.listEvents, { ...repo, issue_number: number, per_page: 100 });
+ return events.some(event => event.event === 'labeled' && event.label?.name === label);
+}
+
+export async function checkOnePullRequest({ github, repo, number, now, reopened, dryRun, log }) {
+ const { data: pullRequest } = await github.rest.pulls.get({ ...repo, pull_number: number });
+ if (pullRequest.state !== 'open') return { skipped: 'closed' };
+ const files = await github.paginate(github.rest.pulls.listFiles, { ...repo, pull_number: number, per_page: 100 });
+ const input = toCheckInput(pullRequest, files);
+ const result = checkPullRequest(input);
+ const exempt = isAutoCloseExempt(input.pr);
+ const comments = await github.paginate(github.rest.issues.listComments, { ...repo, issue_number: number, per_page: 100 });
+ const statusComment = comments.find(comment => comment.user?.login === BOT_LOGIN && parseMarker(comment.body, STATUS_MARKER));
+ const previousState = statusComment ? parseMarker(statusComment.body, STATUS_MARKER) : null;
+ const decision = decideActions({
+ now,
+ contributorFixes: result.contributorFixes,
+ previousState,
+ exempt,
+ draft: input.pr.draft,
+ labels: input.pr.labels,
+ reopened,
+ });
+
+ const act = async (description, action) => {
+ log(`${dryRun ? '[dry run] ' : ''}#${number}: ${description}`);
+ if (!dryRun) await action();
+ };
+
+ let addLabels = result.addLabels;
+ if (addLabels.includes(LOOK_HOLD_LABEL) && await labelWasEverAdded({ github, repo, number, label: LOOK_HOLD_LABEL })) {
+ addLabels = addLabels.filter(label => label !== LOOK_HOLD_LABEL);
+ }
+ if (addLabels.length > 0) {
+ await act(`add labels ${addLabels.join(', ')}`, () => github.rest.issues.addLabels({ ...repo, issue_number: number, labels: addLabels }));
+ }
+ for (const label of result.removeLabels) {
+ await act(`remove label ${label}`, async () => {
+ try {
+ await github.rest.issues.removeLabel({ ...repo, issue_number: number, name: label });
+ } catch (error) {
+ if (error.status !== 404) throw error;
+ }
+ });
+ }
+
+ // The owner, maintainers and bots get the report in the job summary only. A comment would read as a warning to them.
+ if (!exempt && decision.statusState) {
+ const body = renderStatusComment({ contributorFixes: result.contributorFixes, exempt, ...decision.statusState });
+ if (!statusComment) {
+ await act('post the status comment', () => github.rest.issues.createComment({ ...repo, issue_number: number, body }));
+ } else if (statusComment.body !== body) {
+ await act('update the status comment', () => github.rest.issues.updateComment({ ...repo, comment_id: statusComment.id, body }));
+ }
+ }
+ if (decision.remind) {
+ await act('post the reminder', () => github.rest.issues.createComment({
+ ...repo,
+ issue_number: number,
+ body: renderReminderComment({ contributorFixes: result.contributorFixes, closeDate: decision.closeDate }),
+ }));
+ }
+ if (decision.close) {
+ await act('close the pull request', async () => {
+ await github.rest.issues.createComment({ ...repo, issue_number: number, body: renderCloseComment() });
+ await github.rest.pulls.update({ ...repo, pull_number: number, state: 'closed' });
+ });
+ }
+ return { result, decision, exempt };
+}
+
+export async function runPullRequestCheck({ github, context, core, now = Date.now() }) {
+ const repo = context.repo;
+ const dryRun = process.env.PR_METADATA_DRY_RUN === '1';
+ const log = message => core.info(message);
+ const failures = [];
+
+ if (context.eventName === 'pull_request_target') {
+ const outcome = await checkOnePullRequest({
+ github,
+ repo,
+ number: context.payload.pull_request.number,
+ now,
+ reopened: context.payload.action === 'reopened',
+ dryRun,
+ log,
+ });
+ if (outcome.result?.contributorFixes.length) {
+ failures.push(...outcome.result.contributorFixes.map(item => `${item.id}: ${item.message}`));
+ }
+ } else {
+ const openPullRequests = await github.paginate(github.rest.pulls.list, { ...repo, state: 'open', per_page: 100 });
+ for (const pullRequest of openPullRequests) {
+ try {
+ await checkOnePullRequest({ github, repo, number: pullRequest.number, now, reopened: false, dryRun, log });
+ } catch (error) {
+ core.warning(`#${pullRequest.number}: ${error.message}`);
+ }
+ }
+ }
+
+ if (failures.length > 0) {
+ await core.summary.addHeading('Pull request metadata').addList(failures).write();
+ core.setFailed(`The pull request needs ${failures.length} fix${failures.length === 1 ? '' : 'es'}. Details are in the summary and the bot comment.`);
+ }
+}
diff --git a/scripts/size-growth.mjs b/scripts/size-growth.mjs
index 8e13f629..dc848348 100644
--- a/scripts/size-growth.mjs
+++ b/scripts/size-growth.mjs
@@ -58,7 +58,7 @@ export function goalProblems(measured, baseMeasured, goals, accepted = new Map()
const baseSize = baseMeasured[`scene:${scene}`]?.gzip;
if (size === undefined || baseSize === undefined || size <= goal) continue;
if (accepted.has(`goal:${scene}`)) continue;
- const acceptLine = `ask An to accept it with the line "- goal:${scene}: <why>" in changes/<issue>.size.md`;
+ const acceptLine = `ask the maintainer to accept it with the line "- goal:${scene}: <why>" in changes/<issue>.size.md`;
if (baseSize <= goal) {
problems.push(`scene:${scene} is ${size} bytes gzip, over its goal of ${goal}, which the base branch met (${baseSize}). Move code out of the core bundle, or ${acceptLine}.`);
} else if (size - baseSize > GOAL_NOISE_BYTES) {
diff --git a/tests/pr-metadata-check.test.js b/tests/pr-metadata-check.test.js
new file mode 100644
index 00000000..4b6743ad
--- /dev/null
+++ b/tests/pr-metadata-check.test.js
@@ -0,0 +1,306 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+ checkPullRequest,
+ isAutoCloseExempt,
+ isLightPullRequest,
+ isLookPath,
+ sectionOf,
+} from '../scripts/pr-metadata-check.mjs';
+import {
+ CLOSE_AFTER_HOURS,
+ HOUR_MS,
+ REMINDER_AFTER_HOURS,
+ buildMarker,
+ decideActions,
+ parseMarker,
+ renderStatusComment,
+} from '../scripts/pr-metadata-flow.mjs';
+import { checkOnePullRequest } from '../scripts/pr-metadata-run.mjs';
+import { failingGatesFor } from '../scripts/check-change-note.mjs';
+
+const goodBody = `## What changed
+
+Adds a thing.
+
+Closes #12
+
+## How I checked it
+
+\`npm run preflight\` passed, 14 checks ok.
+`;
+
+function pullRequest(overrides = {}) {
+ return {
+ body: goodBody,
+ title: 'Add a thing (#12)',
+ author: 'someone',
+ authorAssociation: 'NONE',
+ labels: ['goal:ai', 'enhancement'],
+ milestone: '5 Agent surface',
+ draft: false,
+ ...overrides,
+ };
+}
+
+function file(filename) {
+ return { filename, additions: 1, deletions: 0 };
+}
+
+const shippedFiles = [file('src/scene.js'), file('changes/12.md')];
+
+function fixIds(input) {
+ return checkPullRequest(input).contributorFixes.map(item => item.id);
+}
+
+test('a complete pull request has no fixes and no todos', () => {
+ const result = checkPullRequest({ pr: pullRequest(), files: shippedFiles });
+ assert.deepEqual(result, { contributorFixes: [], maintainerTodos: [], addLabels: [], removeLabels: [] });
+});
+
+test('a missing Closes or Part of line is a contributor fix', () => {
+ const body = goodBody.replace('Closes #12', 'Closes #');
+ assert.deepEqual(fixIds({ pr: pullRequest({ body }), files: shippedFiles }), ['missing-issue-link']);
+ const partOf = goodBody.replace('Closes #12', 'Part of #12');
+ assert.deepEqual(fixIds({ pr: pullRequest({ body: partOf }), files: shippedFiles }), []);
+});
+
+test('an issue link inside an HTML comment does not count', () => {
+ const body = goodBody.replace('Closes #12', '<!-- Closes #12 -->');
+ assert.deepEqual(fixIds({ pr: pullRequest({ body }), files: shippedFiles }), ['missing-issue-link']);
+});
+
+test('an empty or template-only "How I checked it" is a contributor fix', () => {
+ const emptyBody = goodBody.replace(/## How I checked it[\s\S]*$/, '## How I checked it\n\n<!-- Paste the commands. -->\n- [ ] preflight\n');
+ assert.deepEqual(fixIds({ pr: pullRequest({ body: emptyBody }), files: shippedFiles }), ['empty-how-checked']);
+ const missingSection = goodBody.replace(/## How I checked it[\s\S]*$/, '');
+ assert.deepEqual(fixIds({ pr: pullRequest({ body: missingSection }), files: shippedFiles }), ['empty-how-checked']);
+});
+
+test('shipped code without changes/<issue>.md is a contributor fix, and a size note does not count', () => {
+ assert.deepEqual(fixIds({ pr: pullRequest(), files: [file('src/scene.js')] }), ['missing-change-note']);
+ assert.deepEqual(fixIds({ pr: pullRequest(), files: [file('skills/a/SKILL.md'), file('changes/12.size.md')] }), ['missing-change-note', 'missing-bench-table']);
+ assert.deepEqual(fixIds({ pr: pullRequest(), files: [file('packages/x/index.js'), file('changes/12-edges.md')] }), []);
+});
+
+test('a local path in the body is a contributor fix, for every kind of path', () => {
+ const windowsPath = ['C:', 'Users', 'me', 'work'].join('\\');
+ for (const path of [windowsPath, '/home/me/work', '/Users/me/work']) {
+ const body = `${goodBody}\nSee ${path}/out.png\n`;
+ assert.deepEqual(fixIds({ pr: pullRequest({ body }), files: shippedFiles }), ['local-path'], path);
+ }
+ const placeholder = `${goodBody}\nUse /home/<name>/ as an example.\n`;
+ assert.deepEqual(fixIds({ pr: pullRequest({ body: placeholder }), files: shippedFiles }), []);
+});
+
+test('a tool schema or skill change needs a bench table, or a note that there is no Claude Code login', () => {
+ const files = [file('src/agent-tools.js'), file('changes/12.md')];
+ assert.deepEqual(fixIds({ pr: pullRequest(), files }), ['missing-bench-table']);
+ const table = `${goodBody}\n| task | before | after |\n| --- | --- | --- |\n| haiku bench | 20/28 | 22/28 |\n`;
+ assert.deepEqual(fixIds({ pr: pullRequest({ body: table }), files }), []);
+ const optOut = `${goodBody}\nI have no Claude Code login, so a maintainer can run the bench.\n`;
+ const result = checkPullRequest({ pr: pullRequest({ body: optOut }), files });
+ assert.deepEqual(result.contributorFixes, []);
+ assert.ok(result.maintainerTodos.some(todo => todo.includes('agent bench')));
+ assert.deepEqual(fixIds({ pr: pullRequest(), files: [file('skills/x/SKILL.md'), file('changes/12.md')] }), ['missing-bench-table']);
+});
+
+test('look paths are detected by whole name parts', () => {
+ for (const path of ['src/shaders.js', 'src/lighting.js', 'src/material-pbr.js', 'src/environment.js', 'src/post/bloom.js', 'packages/a/fog.js', 'src/shadow-map.glsl.js']) {
+ assert.ok(isLookPath(path), path);
+ }
+ for (const path of ['src/flight-path.js', 'src/highlight.js', 'docs/lighting.md', 'tests/lighting.test.js', 'src/mesh.js']) {
+ assert.ok(!isLookPath(path), path);
+ }
+});
+
+test('a look change adds hold:look-approval once and needs an image', () => {
+ const files = [file('src/lighting.js'), file('changes/12.md')];
+ const result = checkPullRequest({ pr: pullRequest(), files });
+ assert.deepEqual(result.contributorFixes.map(item => item.id), ['look-without-image']);
+ assert.ok(result.addLabels.includes('hold:look-approval'));
+ const withImage = `${goodBody}\n![after](https://github.com/user-attachments/assets/abc)\n`;
+ assert.deepEqual(fixIds({ pr: pullRequest({ body: withImage }), files }), []);
+ const held = checkPullRequest({ pr: pullRequest({ body: withImage, labels: ['goal:ai', 'enhancement', 'hold:look-approval'] }), files });
+ assert.ok(!held.addLabels.includes('hold:look-approval'));
+});
+
+test('docs-only, CI-only and test-only pull requests skip every rule except the local path', () => {
+ const bare = pullRequest({ body: '' });
+ for (const files of [[file('docs/guide.md')], [file('.github/workflows/test.yml')], [file('tests/a.test.js')], [file('README.md'), file('docs/a.md')]]) {
+ assert.ok(isLightPullRequest(files));
+ assert.deepEqual(fixIds({ pr: bare, files }), []);
+ }
+ assert.deepEqual(fixIds({ pr: pullRequest({ body: 'see /home/me/x' }), files: [file('docs/guide.md')] }), ['local-path']);
+ assert.ok(!isLightPullRequest([file('docs/a.md'), file('skills/a/SKILL.md')]));
+ assert.ok(!isLightPullRequest([]));
+});
+
+test('missing labels and milestone are maintainer todos and add needs-triage, never contributor fixes', () => {
+ const result = checkPullRequest({ pr: pullRequest({ labels: [], milestone: null }), files: shippedFiles });
+ assert.deepEqual(result.contributorFixes, []);
+ assert.equal(result.maintainerTodos.length, 3);
+ assert.deepEqual(result.addLabels, ['needs-triage']);
+ const fixed = checkPullRequest({ pr: pullRequest({ labels: ['goal:ai', 'bug', 'needs-triage'] }), files: shippedFiles });
+ assert.deepEqual(fixed.removeLabels, ['needs-triage']);
+});
+
+test('status:needs-author follows the contributor fixes, except for exempt authors', () => {
+ const failing = checkPullRequest({ pr: pullRequest({ body: '' }), files: shippedFiles });
+ assert.ok(failing.addLabels.includes('status:needs-author'));
+ const passing = checkPullRequest({ pr: pullRequest({ labels: ['goal:ai', 'bug', 'status:needs-author'] }), files: shippedFiles });
+ assert.deepEqual(passing.removeLabels, ['status:needs-author']);
+ const owner = checkPullRequest({ pr: pullRequest({ body: '', author: 'anxuanng' }), files: shippedFiles });
+ assert.ok(owner.contributorFixes.length > 0);
+ assert.ok(!owner.addLabels.includes('status:needs-author'));
+});
+
+test('owner, members, collaborators and bots are exempt from auto close', () => {
+ assert.ok(isAutoCloseExempt({ author: 'anxuanng', authorAssociation: 'NONE' }));
+ assert.ok(isAutoCloseExempt({ author: 'AnXuanNg', authorAssociation: 'NONE' }));
+ assert.ok(isAutoCloseExempt({ author: 'dependabot[bot]', authorAssociation: 'NONE' }));
+ for (const authorAssociation of ['OWNER', 'MEMBER', 'COLLABORATOR']) {
+ assert.ok(isAutoCloseExempt({ author: 'x', authorAssociation }));
+ }
+ assert.ok(!isAutoCloseExempt({ author: 'x', authorAssociation: 'FIRST_TIME_CONTRIBUTOR' }));
+});
+
+test('sectionOf reads a section up to the next heading', () => {
+ assert.equal(sectionOf('## A\none\n## B\ntwo', 'a').trim(), 'one');
+ assert.equal(sectionOf('## A\none', 'missing'), null);
+});
+
+const someFix = [{ id: 'x', message: 'Fix x.', docsAnchor: 'link-the-issue' }];
+
+test('the clock starts at the first failure, reminds once at 48 hours and closes at 72', () => {
+ const start = Date.parse('2026-11-01T00:00:00.000Z');
+ const base = { contributorFixes: someFix, exempt: false, draft: false, labels: [] };
+ const first = decideActions({ ...base, now: start, previousState: null });
+ assert.equal(first.statusState.firstFailedAt, '2026-11-01T00:00:00.000Z');
+ assert.ok(!first.remind && !first.close);
+ const state = first.statusState;
+ const early = decideActions({ ...base, now: start + (REMINDER_AFTER_HOURS - 1) * HOUR_MS, previousState: state });
+ assert.ok(!early.remind);
+ const reminder = decideActions({ ...base, now: start + REMINDER_AFTER_HOURS * HOUR_MS, previousState: state });
+ assert.ok(reminder.remind && !reminder.close);
+ assert.equal(reminder.closeDate, '2026-11-04');
+ const again = decideActions({ ...base, now: start + 50 * HOUR_MS, previousState: reminder.statusState });
+ assert.ok(!again.remind);
+ const closing = decideActions({ ...base, now: start + CLOSE_AFTER_HOURS * HOUR_MS, previousState: reminder.statusState });
+ assert.ok(closing.close);
+});
+
+test('exempt authors, drafts and needs-owner-decision are never reminded or closed', () => {
+ const previousState = { firstFailedAt: '2026-11-01T00:00:00.000Z' };
+ const now = Date.parse('2026-11-10T00:00:00.000Z');
+ const base = { contributorFixes: someFix, exempt: false, draft: false, labels: [], previousState, now };
+ assert.ok(decideActions(base).close);
+ for (const change of [{ exempt: true }, { draft: true }, { labels: ['needs-owner-decision'] }]) {
+ const decision = decideActions({ ...base, ...change });
+ assert.ok(!decision.close && !decision.remind, JSON.stringify(change));
+ }
+});
+
+test('a pull request that passes again clears the clock, and a reopened one starts a new clock', () => {
+ const previousState = { firstFailedAt: '2026-11-01T00:00:00.000Z', reminderSentAt: '2026-11-03T00:00:00.000Z' };
+ const now = Date.parse('2026-11-10T00:00:00.000Z');
+ const passing = decideActions({ now, contributorFixes: [], previousState, exempt: false, draft: false, labels: [] });
+ assert.deepEqual(passing.statusState, {});
+ const reopened = decideActions({ now, contributorFixes: someFix, previousState, exempt: false, draft: false, labels: [], reopened: true });
+ assert.equal(reopened.statusState.firstFailedAt, '2026-11-10T00:00:00.000Z');
+ assert.ok(!reopened.close);
+ assert.equal(decideActions({ now, contributorFixes: [], previousState: null, exempt: false, draft: false, labels: [] }).statusState, null);
+});
+
+test('the marker round trips and the comment stays warm and short', () => {
+ const marker = buildMarker('pr-metadata-status', { firstFailedAt: '2026-11-01T00:00:00.000Z' });
+ assert.deepEqual(parseMarker(marker, 'pr-metadata-status'), { firstFailedAt: '2026-11-01T00:00:00.000Z' });
+ assert.equal(parseMarker('no marker', 'pr-metadata-status'), null);
+ const comment = renderStatusComment({ contributorFixes: someFix, firstFailedAt: '2026-11-01T00:00:00.000Z', exempt: false });
+ assert.match(comment, /^<!-- pr-metadata-status firstFailedAt=2026-11-01T00:00:00.000Z -->/);
+ assert.match(comment, /Thank you/);
+ assert.match(comment, /CONTRIBUTING\.md#link-the-issue/);
+ assert.match(comment, /2026-11-04/);
+});
+
+function fakeGitHub({ pullRequest: pr, files = [], comments = [], events = [] }) {
+ const calls = [];
+ const record = name => async params => {
+ calls.push({ name, params });
+ return { data: pr };
+ };
+ return {
+ calls,
+ paginate: async method => (method === 'files' ? files : method === 'comments' ? comments : events),
+ rest: {
+ pulls: { get: record('get'), listFiles: 'files', update: record('closePullRequest') },
+ issues: {
+ listComments: 'comments',
+ listEvents: 'events',
+ addLabels: record('addLabels'),
+ removeLabel: record('removeLabel'),
+ createComment: record('createComment'),
+ updateComment: record('updateComment'),
+ },
+ },
+ };
+}
+
+function apiPullRequest(overrides = {}) {
+ return {
+ state: 'open',
+ body: '',
+ title: 'Add a thing',
+ user: { login: 'someone' },
+ author_association: 'NONE',
+ labels: [],
+ milestone: null,
+ draft: false,
+ ...overrides,
+ };
+}
+
+test('the runner posts one friendly comment for a new pull request and labels it', async () => {
+ const github = fakeGitHub({ pullRequest: apiPullRequest(), files: [{ filename: 'src/scene.js' }] });
+ const messages = [];
+ const outcome = await checkOnePullRequest({ github, repo: { owner: 'o', repo: 'r' }, number: 5, now: Date.parse('2026-11-01T00:00:00Z'), reopened: false, dryRun: false, log: line => messages.push(line) });
+ const names = github.calls.map(call => call.name);
+ assert.deepEqual(names.filter(name => name === 'createComment'), ['createComment']);
+ assert.ok(names.includes('addLabels'));
+ assert.ok(outcome.result.contributorFixes.length >= 3);
+ assert.ok(!names.includes('closePullRequest'));
+});
+
+test('the runner closes a pull request that stayed unfixed for 72 hours, and never an owner one', async () => {
+ const marker = buildMarker('pr-metadata-status', { firstFailedAt: '2026-11-01T00:00:00.000Z' });
+ const comments = [{ id: 9, user: { login: 'github-actions[bot]' }, body: `${marker}\nold` }];
+ const now = Date.parse('2026-11-05T00:00:00Z');
+ const contributor = fakeGitHub({ pullRequest: apiPullRequest(), files: [{ filename: 'src/scene.js' }], comments });
+ await checkOnePullRequest({ github: contributor, repo: {}, number: 5, now, reopened: false, dryRun: false, log() {} });
+ assert.ok(contributor.calls.some(call => call.name === 'closePullRequest'));
+ const owner = fakeGitHub({ pullRequest: apiPullRequest({ user: { login: 'anxuanng' } }), files: [{ filename: 'src/scene.js' }], comments });
+ const outcome = await checkOnePullRequest({ github: owner, repo: {}, number: 6, now, reopened: false, dryRun: false, log() {} });
+ assert.ok(!owner.calls.some(call => ['closePullRequest', 'createComment', 'updateComment'].includes(call.name)));
+ assert.ok(outcome.result.contributorFixes.length > 0);
+});
+
+test('a dry run changes nothing and a hold label that was added before is not added again', async () => {
+ const dry = fakeGitHub({ pullRequest: apiPullRequest(), files: [{ filename: 'src/lighting.js' }] });
+ await checkOnePullRequest({ github: dry, repo: {}, number: 5, now: 0, reopened: false, dryRun: true, log() {} });
+ assert.deepEqual(dry.calls.map(call => call.name), ['get']);
+ const removedByOwner = fakeGitHub({
+ pullRequest: apiPullRequest(),
+ files: [{ filename: 'src/lighting.js' }],
+ events: [{ event: 'labeled', label: { name: 'hold:look-approval' } }],
+ });
+ await checkOnePullRequest({ github: removedByOwner, repo: {}, number: 5, now: 0, reopened: false, dryRun: false, log() {} });
+ const added = removedByOwner.calls.filter(call => call.name === 'addLabels').flatMap(call => call.params.labels);
+ assert.ok(!added.includes('hold:look-approval'));
+});
+
+test('the CI gate fails a shipped change without a note and a protected file edit', () => {
+ assert.deepEqual(failingGatesFor(['src/a.js']).map(gate => gate.name), ['change note']);
+ assert.deepEqual(failingGatesFor(['src/a.js', 'changes/1.md']), []);
+ assert.deepEqual(failingGatesFor(['CHANGELOG.md']).map(gate => gate.name), ['protected files']);
+ assert.deepEqual(failingGatesFor(['docs/a.md']), []);
+});