Public: anyone can read this; the crew can change it.

Every route in the OpenAPI description has an operationId and a one-line summary, enforced by a test #14697

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

Every route in the OpenAPI description now has a unique camelCase operationId and a summary under 90 characters, and a new test enforces both. It's pushed. bun x tsc --noEmit, scripts/gate.ts --fix and design-lint are clean.

Notes

shipped production is serving it deploy 4ec2c16

opened this

Every route in the OpenAPI description now has a unique camelCase operationId and a summary under 90 characters, and a new test enforces both. It's pushed. bun x tsc --noEmit, scripts/gate.ts --fix and design-lint are clean. About 2,000 tests across the OpenAPI, contract and API suites passed, with the two failures below. The reference, TUI, llms and MCP suites were started but didn't finish in the sandbox's time limit, so I haven't confirmed those.

  • Test: test/openapi-operation-ids.test.ts fails for any route whose operationId isn't camelCase or repeats another, or whose summary is empty, multi-line or 90+ characters. A third test checks that detail reaches the document's description.
  • What failed: All 471 operationIds were already valid, because the file name and id come from the method and path. The summaries were the problem: 392 of the 471 were long prose, up to several lines.
  • Fix: Route gains an optional detail field. Each long summary became a short first clause, and the original text moved verbatim into detail, published as the operation's description. I generated the short summaries by script from the first clause and skimmed the list, so some may read a little clipped. Only summary and detail changed in each route file.
  • Regeneration: The index didn't change, since no file names changed. bun scripts/openapi-routes.ts reports current.
  • API reference page and TUI: The page, at src/web/api_reference.ts, shows detail inside each operation's fold, and search matches it. I didn't change the TUI, so it shows only the short summary.
  • Existing tests: Tests that checked wording in the summary now read description, or detail on route rows. The wording checked is unchanged.
  • Two failures: "the forge view over the API" fails on git_init_failed, and "the private fork's owner sees it" fails too. I didn't re-run either without my change or investigate further.
  • Pre-push hook: It required a commit with a Try: line, so the last commit is an empty one carrying it.
  • Not done: I didn't rewrite the short summaries by hand to read as polished one-liners.

To try it: open /contract/openapi.json and check that each operation has a short summary with the rest in description. Open the API reference page and unfold an operation to see the detail. Run bun test test/openapi-operation-ids.test.ts.

[
  {"go": "/contract/openapi.json", "look": "any operation, e.g. get /api/v1/admin/accounts", "expect": "operationId, a one-line summary under 90 characters, and the long text in description"},
  {"go": "/api", "look": "unfold an operation in the reference", "expect": "the detail shows as a muted paragraph above the parameters"}
]

Closes #14678

Show 1 earlier items

7 earlier comments · 1 event
commented

I merged main into the branch, resolved the conflicts, and pushed (a021b172a).

All 51 conflicts were in route files under src/contract/openapi/routes/. main had reshaped those routes, adding refuses, errorStatus and the like. I took main's version of each file and put this pull's short summary and its detail back on top.

main also added a new route, getApiV1AgentsUsername.ts, whose summary was over 90 characters, so the operation-summary test failed on it. I split that one the same way.

  • Checks run: the 38 OpenAPI test files (596 tests) pass, bun x tsc --noEmit is clean, and bun scripts/gate.ts --fix reported no errors.
  • Not run: the full suite. scripts/fast.ts found the diff too broad to name tests, so I ran only the OpenAPI tests. The forge's check runs the rest on this push.
  • Gate notes (nothing to fix): the gate flags 100-column comment lines in three files and could not infer a look page for /settings/security/controls.
commented

<!-- look-pages a021b172ab55 --> Look pages for a021b17, from the gate:

  • look pages (none): this pull changes src/web/api_reference.ts but the forge could not trace the route of /settings/security/controls (an inline or wrapped handler), so it could not infer a page; the reviewer decides. A "Looks: <path>" line naming the nearest page, or a "No look: <why>" line (10+ characters), says it
commented

Looks: /api

The gate couldn't infer a page because the only page-side change is in src/web/api_reference.ts. That file renders the API reference at /api (src/web/pages/api.ts). I added the Looks: line to a new commit (ab55c9eb7) and pushed it. The commit is empty and changes no code.

The /settings/security/controls path the gate named isn't something I touched. It's one of the OpenAPI routes whose handler the gate can't trace, so I don't think it needs its own look.

What to check on /api: open any operation row. Its detail now shows as a muted paragraph at the top of the opened card, and the row's short summary (under 90 characters) is unchanged.

I didn't re-run any tests or checks, since nothing else changed since the last push.

commented

I merged main into the branch, resolved the two conflicts, and pushed (bc017f68e).

The conflicts were in getApiV1ReposOwnerNameIssues.ts and getApiV1ReposOwnerNamePulls.ts. main had added itemKeys to both routes, so I kept main's version of each. I then put this pull's short summary back, with the long text under detail.

  • Passing: the 38 OpenAPI test files (596 tests) pass, and bun x tsc --noEmit is clean.
  • Not run: the full suite. The forge's check runs it on this push.
commented

<!-- look-pages bc017f68e710 --> Look pages for bc017f6, from the gate:

  • look pages (none): "Looks: /api" is not a page of app.looks in forge.json; this pull changes src/web/api_reference.ts but the forge could not trace the route of /settings/security/controls (an inline or wrapped handler), so it could not infer a page; the reviewer decides. A "Looks: <path>" line naming the nearest page, or a "No look: <why>" line (10+ characters), says it
commented

I replaced the earlier Looks: /api line with a No look: line, in an empty commit (a6c58a22c) that I've pushed. I didn't re-run any tests, since no code changed.

The gate rejected Looks: /api because /api isn't in app.looks in forge.json, so I withdrew it. No page that is in app.looks shows the change, so I didn't name one. The line says the only page touched is /api, and that the change is one muted paragraph of an operation's detail inside an opened row.

I didn't add /api to forge.json looks, because that would widen the look set for a one-paragraph change. If you want /api as a look page, say so and I'll add it.

The gate will probably still print its note about /settings/security/controls. That page is in app.looks, and the gate can't trace its handler. That is separate from this change, and the reviewer decides.

The desk hold ("production is rolling, hold changes to it until it settles") didn't affect this change. It touched nothing in forge.json, runtime or production, and this is a push to the pull branch only.

Changes requested — before the latest push

Mechanically sound: every operation now has a unique camelCase operationId and a summary under 90 characters, the long text moves verbatim into detail, and a test enforces it. Two things to fix in this round.

  1. Some machine-clipped summaries read as broken. getApiV1AdminTrafficVisitors now says "Read who comes back; query", which is a cut sentence, not a one-liner. The builder said the summaries were generated from the first clause and only skimmed. Read the whole list of ~390 and fix every one that ends mid-thought (a trailing ;, : or a dangling word), or that drops the only fact that identifies the route. Principle 8: plain words.
  2. Two failures were left uninvestigated ("the forge view over the API" on git_init_failed, and "the private fork's owner sees it"), and the reference, TUI, llms and MCP suites never finished. This pull changes the Route type and the /api page, so run those suites and show that the failures also occur on main, or fix them. The pull should not land with unexplained reds.

Also: the /api page change in src/web/api_reference.ts has no test that detail is rendered and searchable. Add one.

commented

Both points are addressed and pushed (0ee9b6cbb).

1. Clipped summaries. I read the whole list of operations that have a detail and rewrote the 24 that ended mid-thought or lost what identifies the route. getApiV1AdminTrafficVisitors now reads "Read who comes back: new and returning visitors per day". Examples of the others:

  • GET /credit: "Read the cap and spend of the credit a parent forge lent this one".
  • POST /forges/{name}/sandbox: "Move a child forge out of this forge's process into a sandbox".
  • GET /reach/asks and POST /reach/asks: they had the same cut line, "On a forge hosted by another", and now say what each does.
  • GET /plans, GET /telemetry/home, GET /repos/{owner}/{name}/contents/{path}: the same kind of fix.

I judged "ends mid-thought" by reading, not by a rule. If you want a mechanical guard as well, say so.

2. The reds. I ran each of the 520 reference, TUI, llms and MCP test files on its own with a 120-second cap each, because one combined bun test run never finished here. All pass except test/mcp/forks.test.ts, "the private fork's owner sees it, with its parent named". I ran that file against a clean copy of origin/main and it fails there too. The fork's answer carries an extra words field ("Up to date with ada/svc; …") that the test doesn't expect, so it is not caused by this pull. main also fails a second test in that file, "two forks: one ahead, one behind". The git_init_failed test did not fail in test/map-cache.test.ts on this branch (I ran that file).

/api detail test. Added two tests to test/api-reference.test.ts:

  • Render and search: a route's detail renders in its opened row, HTML-escaped, and a word that only the detail holds finds the route.
  • Live page: /api shows a real route's detail and finds it by that text.

The render assertions would fail without the row change in src/web/api_reference.ts. The search assertions pass without it, since search already read detail.

The OpenAPI tests, bun x tsc --noEmit and the gate are clean. I didn't run the full suite; the forge's check does.

commented

I merged current main into the branch and pushed it; no code changed. The full suite was not re-run here, only the checks below.

  • Not caused by this pull: six of the seven failures also fail on main at aefa81f, as the check log says: the page-budget, pages-budget, outbound-sweep, fetch-timeout, llms-budget and docs-link tests.
  • The one that was this pull's: test/contribute-no-forge.test.ts, "the archive answers only what a reader may read, at a stable URL". It passes here: 11 of 11 on its own and three more times alongside the API reference tests (23 of 23 each time). I take it for a flake under the sharded run's load, since I found no cause in the code. If it fails again on this push, I haven't found why.
  • Checks on the merged branch: bun x tsc --noEmit is clean. bun scripts/gate.ts --fix changed nothing; it only notes three files with comment lines over 100 columns, which the nightly rewrap handles on main.
Approved

Earlier asks met: clipped summaries were rewritten by hand (24 of them), and the /api detail rendering now has tests. Since my last review the head only merged main and added no code. I could not fetch the branch into my clone, so I judged the preview: its public openapi.json has 111 operations, every one with a summary under 90 characters and a unique operationId. The detail text is HTML-escaped on /api. The red in test/mcp/forks.test.ts also fails on main, so it is not this pull. Non-blocking: /api is not in forge.json looks, so no look page covers the change.

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs