The OpenAPI document describes a pull's checks: GET and POST …/pulls/{number}/checks #5391

The OpenAPI document now describes GET and POST /api/v1/repos/{owner}/{name}/pulls/{number}/checks. bun test test/openapi passes (46 tests), but I couldn't run bun x tsc --noEmit. It stops with "Cannot find type definition file for 'bun'", and it does the same with my change stashed. The forge's check will run the type check.

• Rows: both sit in ROUTES in src/contract/openapi.ts right after the …/merge row, read from the handlers in src/http/api.ts.

- GET needs no token. It answers { head, state, required, run, runs }, with state set to none when there is no run. - POST needs a token with rw scope and a writer. It answers 202 with { run }. The refusals listed are forbidden (403) and, as 409s, not_open, no_checks and no_check_declared.

• Coverage list: both routes are removed from NOT_YET_DESCRIBED in test/openapi-coverage.test.ts.
• New test: test/openapi-oa-pull-checks.test.ts reads the served document and checks the GET summary, the POST's 202 response and the no_check_declared refusal. It would fail without the rows.

I didn't describe response body schemas beyond the summary text, since the rows in ROUTES don't carry them.

Closes #5380

The OpenAPI document now describes GET and POST /api/v1/repos/{owner}/{name}/pulls/{number}/checks. bun test test/openapi passes (46 tests), but I couldn't run bun x tsc --noEmit. It stops with "Cannot find type definition file for 'bun'", and it does the same with my change stashed. The forge's check will run the type check.

• Rows: both sit in ROUTES in src/contract/openapi.ts right after the …/merge row, read from the handlers in src/http/api.ts.

- GET needs no token. It answers { head, state, required, run, runs }, with state set to none when there is no run. - POST needs a token with rw scope and a writer. It answers 202 with { run }. The refusals listed are forbidden (403) and, as 409s, not_open, no_checks and no_check_declared.

• Coverage list: both routes are removed from NOT_YET_DESCRIBED in test/openapi-coverage.test.ts.
• New test: test/openapi-oa-pull-checks.test.ts reads the served document and checks the GET summary, the POST's 202 response and the no_check_declared refusal. It would fail without the rows.

I didn't describe response body schemas beyond the summary text, since the rows in ROUTES don't carry them.

The full gate on land was red; the pull is open again. Red tests:

• the gate audit before any shard > a new file is in the gate with no list naming it, and explicit files are not audited
• the gate audit before any shard > a new file is in the gate with no list naming it, and explicit files are not audited [73.76ms] [shard 103]

The two checks rows now carry response body schemas, and the test pins their auth. I couldn't reproduce the red gate-audit failure, so I made no change for it.

• Response schemas: ROUTES rows take an optional reply field, which openapi() turns into a JSON schema on the success response.

- GET describes head, state, required, run and runs. - POST describes run on the 202. - The run and runs entries are typed only as object and array. I didn't describe the run's own fields.

• Auth pinned: test/openapi-oa-pull-checks.test.ts now asserts the GET row has no security and the POST row requires the token. It also asserts both schemas' field names.
• Gate failure: the failing test is "a new file is in the gate with no list naming it…" in test/shards.test.ts. It passes when I run it here, and I changed no gate list. The failure looks load-dependent, since it was at 73 ms on shard 103. I'm not certain of that, so the forge's rerun on this push should confirm it.
• Local run: test/openapi* and test/shards.test.ts pass except one test in shards.test.ts, which fails here with "Cannot find module 'typescript/package.json'". That is an install gap in this sandbox, not my change. bun x tsc --noEmit still can't run here for the same reason.

Pushed. The check failed because this pull took the gate to 999 test files. The test needs a --shard 1000/1000 spec, and --shard N/M only accepted three-digit numbers. I haven't run the full check here.

parseShardSpec in scripts/shards.ts now accepts up to four digits, so the failing gate-audit test passes again. I added a 1000/1000 case to the parseShardSpec test in test/shards.test.ts. The bad specs 0/3, 1/0, 4/3 and 1/3/5 are still refused. I changed the limit rather than the failing test, because the matrix total grows with the file count and would have hit the same wall again.

I reproduced the failure locally after rebasing onto main, and it was absent on main itself. With the fix, test/shards.test.ts and test/openapi* pass here, except the typescript 7.x checker test. That test fails here only because the sandbox has no typescript package.

The other red test in the log, the merge queue > a gate that never answers is abandoned at the deadline…, is a 1.6 s timing test in code this pull doesn't touch. I didn't change it, so a rerun of the check will show whether it was a flake.

I first rebased onto main and tried to force-push. That was denied, so I dropped the rebase and put the fix on top of the pushed branch.