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

A missing docs page reads as a page: /docs/<unknown> and /docs/features/<unknown> answer the HTML not-found page to a browser #14378

Merged opened this

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

Merged

/docs/ and /docs/features/ now answer the HTML not-found page to a browser, and JSON only when Accept ranks application/json first. I did not call keepplan or estimate and gave no time estimate. What changed The fix is in docPage in src/web/pages/docslink.ts, which both docsFile and docsFeature go through.

Notes

shipped production is serving it deploy 4ec2c16

opened this

/docs/<unknown> and /docs/features/<unknown> now answer the HTML not-found page to a browser, and JSON only when Accept ranks application/json first. I did not call keep_plan or estimate and gave no time estimate.

What changed

  • The fix is in docPage in src/web/pages/docs_link.ts, which both docsFile and docsFeature go through. A missing entry now returns notFoundPage(ctx) unless the caller prefers JSON, in which case it returns notFound() as before.
  • The new test file is test/docs-not-found.test.ts. For both routes it checks the HTML 404 with a browser Accept and the JSON 404 with Accept: application/json. A third test sweeps every GET route from buildRouter(), fills the params with junk, and asserts no browser-facing path answers a JSON 404.
  • The new tests ran green with the fix. Stashing the src change turned the three browser-facing ones red, and the two JSON-only ones passed either way, as expected.
  • bun x tsc --noEmit is clean, design-lint is clean, and test/docs-link.test.ts passes.
  • gate.ts --fix rewrapped comments in one file and that went into the commit. I did not run bun test across the whole suite; the forge does that on push.

What the sweep skips

  • It skips paths that missShape classes as machine or file (.png, .svg, .atom, .txt, /og/*, /api).
  • It also skips five data-feed routes that answer JSON or a stream by design: /forges/:name/bill, /forges/:name/ready, /:owner/:name/stream, /:owner/:name/paths/:ref, and /origins/:id/r/:owner/:name/paths/:ref. They are listed in the FEEDS set in the test.
  • A route that never ends a response is skipped after 5 seconds rather than counted as a failure.

How to try it Request /docs/start with Accept: text/html and you get the 404 page ("Nothing here"). The same request with Accept: application/json gets the JSON body.

Pushing The pre-push hook refused the push until a commit carried a "Try:" line, so I added an empty commit for it. You can squash it.

Closes #14366

3 earlier comments
commented

/docs/<unknown> and /docs/features/<unknown> now answer the HTML not-found page to a browser, and JSON only when Accept ranks application/json first. I did not call keep_plan or estimate and gave no time estimate.

What changed

  • The fix is in docPage in src/web/pages/docs_link.ts, which both docsFile and docsFeature go through. A missing entry now returns notFoundPage(ctx) unless the caller prefers JSON, in which case it returns notFound() as before.
  • The new test file is test/docs-not-found.test.ts. For both routes it checks the HTML 404 with a browser Accept and the JSON 404 with Accept: application/json. A third test sweeps every GET route from buildRouter(), fills the params with junk, and asserts no browser-facing path answers a JSON 404.
  • The new tests ran green with the fix. Stashing the src change turned the three browser-facing ones red, and the two JSON-only ones passed either way, as expected.
  • bun x tsc --noEmit is clean, design-lint is clean, and test/docs-link.test.ts passes.
  • gate.ts --fix rewrapped comments in one file and that went into the commit. I did not run bun test across the whole suite; the forge does that on push.

What the sweep skips

  • It skips paths that missShape classes as machine or file (.png, .svg, .atom, .txt, /og/*, /api).
  • It also skips five data-feed routes that answer JSON or a stream by design: /forges/:name/bill, /forges/:name/ready, /:owner/:name/stream, /:owner/:name/paths/:ref, and /origins/:id/r/:owner/:name/paths/:ref. They are listed in the FEEDS set in the test.
  • A route that never ends a response is skipped after 5 seconds rather than counted as a failure.

How to try it Request /docs/start with Accept: text/html and you get the 404 page ("Nothing here"). The same request with Accept: application/json gets the JSON body.

Pushing The pre-push hook refused the push until a commit carried a "Try:" line, so I added an empty commit for it. You can squash it.

commented

<!-- look-pages 381585aa1766 --> Look pages for 381585a, from the gate:

  • look pages (inferred): this pull changes src/web/pages/docs_link.ts; the forge pictures /docs (src/web/pages/docs_link.ts), the pages whose routes import it. A "Looks: <path>" or "No look: <why>" line in a commit message overrides
commented

A missing docs page (/docs/<unknown> and /docs/features/<unknown>) now answers a browser with the HTML not-found page instead of a 235-byte JSON 404. JSON still comes back only when Accept ranks application/json first. The gate's "both doors" rule failed the earlier push because it edits src/web/pages/docs_link.ts with no matching terminal change; the new No door: line in the latest commit answers that rule and the gate now passes locally, but I haven't seen the forge's re-run.

  • Fix: it is in docPage in src/web/pages/docs_link.ts, which both docsFile and docsFeature go through.
  • Tests: test/docs-not-found.test.ts covers both routes in both modes. It also sweeps every GET page route in buildRouter() and finds no other path answering a browser a JSON 404. The sweep skips file and machine paths and five data-feed routes that answer JSON or a stream by design (bill, ready, stream, and the two paths/:ref routes). Three of the five tests fail without the fix.
  • No door: the terminal has no docs not-found screen, so there was no terminal change to make. I added a No door: line to a commit message instead, which is the escape the gate offers for an edit that shows nothing new. If a reviewer wants the terminal to show something here, that is a separate change.
  • Checks: I did not run the full suite here. I ran bun x tsc --noEmit (clean), bun scripts/design-lint.ts (clean) and test/docs-link.test.ts (passes).
  • Hook: the pre-push hook wants a "Try:" line in a commit, so the branch carries one empty commit for it. You can squash it.

To try it, request /docs/start with Accept: text/html and you get the 404 page ("Nothing here"). The same request with Accept: application/json gets the JSON body.

commented

I added a No look: line to a new commit and pushed it. The gate inferred /docs as the look page because the pull edits docs_link.ts, but this change only touches a missing docs page's 404. The /docs index and the rendered docs look the same, so nothing needs a new picture. I didn't re-run the gate or any tests after this commit, since it changes only the commit message.

The change itself is the same as before. A missing docs page now gets the HTML not-found page in a browser and JSON only for Accept: application/json. The tests are in test/docs-not-found.test.ts.

If you'd rather have a picture of the not-found page, tell me which path to put in a Looks: line, for example /docs/start.

Approved

Works in the preview: /docs/start, /docs/nope and /docs/features/nope answer 404 text/html (the not-found page) to a browser; JSON stays for Accept: application/json. The fix is one line in docPage, which both routes share, and the 404 page is the existing chrome one, so no design-system departure. No terminal door is needed: the not-found page has no terminal counterpart. README untouched.

Two things I would do next:

  1. The FEEDS allowlist in the sweep is hand-kept; derive it from the router (or a marker on feed routes) so a new feed does not need a test edit, and a new JSON-404 page route is not silently excused.
  2. The not-found page has no Looks: picture; add one so the HTML 404 is seen, not only asserted.

Small note: the test path /docs/start reads like a real page; a name like /docs/nope-99 states the intent.

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs