[FumingPower3925]

Third and last batch of the symbol-citation change: the remaining twelve pages. Draft. Stacked on the second batch (#105, which is stacked on #104). After this PR no path.go:N locator and no leftover :N or N-M fragment of one is left on the site (shapes the ratchet checks are listed in the body of #104), and the citation ratchet's allowlist is empty.

#N in this body means goceleris/celeris#N, except where it says goceleris/docs. The items are the checklist items of goceleris/celeris#891 numbered as in the DOCSSITE PR (items 8 and 10). The checklist issue stays open and its boxes are not ticked here.

What changed

• Item 8 (symbol citations). observability.md (31 locators), routing.md (28), sse.md (26), middleware-content.md (25), middleware.md (21), engines.md (20), testing.md (17), net-http-interop.md (16), streaming.md (15), middleware-auth.md (1), context-api-reference.md (1) and binding-and-validation.md (1). That is 202 locators. Across the three PRs, all 515 locators at goceleris/docs 7ecb763 (after docs: shutdown, deployment, getting-started, error-handling and data-stores match v1.6.0 #102) are symbol citations.
• Item 10 (prefix). The 25 bare citations in middleware-content.md (compress/config.go, etag/etag.go, cache/cache.go, protobuf/config.go, swagger/swagger.go, and so on) get celeris/ and the full repository path, such as celeris/middleware/swagger/config.go. The celeris/ prefix is the repository name and is kept everywhere.
• Test (scripts/docs-symbol-citations.test.ts). The allowlist is now empty, so the test asserts that no page has a .go:N locator, no page has a continuation fragment (shapes in the body of docs: cite celeris symbols, not line numbers (configuration, middleware-traffic, websocket) #104), and no page names a source file with a dir/x.go path or a (x.go) form without the celeris/ prefix.
• Neighbours. sse.md had the same symbol twice in one citation sentence (sse.go:487 and sse.go:700-705 are both inside New on celeris origin/main, which spans 349-720); written once.

Special cases

• binding-and-validation.md:213 (validation/doc.go:22-31) and net-http-interop.md:319 (middleware/adapters/doc.go:10-13) are package-comment ranges with no declaration to name; they cite the file only.
• Every other citation names a declaration, chosen by the method in PR 1 (blame to the revision the line was written against, then the declaration covering the cited range there).

Checks run in the first version (head 5a27611, tree as 2d8d463; current head under Review round 1)

• Ratchet: bun test scripts/docs-symbol-citations.test.ts passes with the empty allowlist. The failing-first run (empty allowlist, before any page was cleaned) is in the lane (work/test-failing-first.log: 20 pages, 515 locators, plus continuations); the negative controls for PR 1 are in work/controls-pr1.log; the PR 2 control (one proxy.go:97-117, 215-226 line appended to deployment.md) fails the offender and continuation tests and is restored.
• Every citation on the docs tree: work/verify_all.py parses each `celeris/<path>.go` (`Sym`, ...) group and checks that the path exists on celeris origin/main and each symbol is declared there (a method name matches Type.Name or Name). Output: work/verify-all-pr3.log, 522 citations, 0 bad.
• CI steps from ci.yml on 2d8d463, run from the lane: bun run validate, bun run build, bun run check, bun test all exit 0 (logs work/ci-*-pr3.log). bun test ran 25 tests across 2 files.
• No other line-anchor form is left: grep for .go line, .go L, #L<digits> and .go:<digits> over src/content/docs finds nothing.

Review round 1 (head 3534c2e)

Refs #891 item 8. Rebased onto the new head of #105 (8167681). The detector and the controls that come with the first-round fixes are described in the body of #104; this PR adds the prefix guard.

• Orphan fragments (major). The first version of this PR claimed that no locator remained, but it kept the second and later locators of multi-locator sentences as bare fragments. Replaced with symbols: observability.md :180 (Config.SensitiveFormFields, with Config.SensitiveHeaders), :55 (DefaultSensitiveFormFields, with DefaultSensitiveHeaders) and :283 (JSONConfig, with CLFConfig); sse.md :560-562 (the OnDisconnect call: New in sse.go with Config.OnDisconnect in config.go) and :160-190 (kvStore.Append, with KVReplayStoreConfig). The websocket.md and configuration.md fragments are in docs: cite celeris symbols, not line numbers (configuration, middleware-traffic, websocket) #104. Reproduction: the reviewer's grep on the old head 5a27611 gives 7 lines (work/r1/reviewer-grep-5a27611.log); on the new head it gives none, and .go:<digits> has 0 hits (work/r1/reviewer-grep-new-head.log). Source-side check, independent of the detector: the added lines of git diff 7ecb763 -- src/content/docs (work/r1/added-lines.txt, 504 lines) with a run of two or more digits (work/r1/added-digits.txt, 17 non-table lines, and the table lines) were read; each digit run is prose or a quoted value (4096, /users/42, 503 {...}), none is a leftover line reference.
• Prefix (item 10). The prefix guard is a new test (commit 649cbab, failing first: work/r1/failing-first-pr3.log lists core-concepts.md x9, middleware-content.md shorthand lines and the observability and sse fragments). It flags a path-qualified .go file that does not start with celeris/ (for example `swagger/config.go` or the shorthand `etag/config.go` after a full path) and a bare parenthesised file name (server.go). Fixed: middleware-content.md (compress, etag, cache, protobuf, swagger source lines: 12 paths) and core-concepts.md (nine (server.go)-style mentions, now (`celeris/server.go`) and so on). The guard does not see a bare backticked file name such as `config.go`, so "every mention carries the prefix" is not claimed; it is claimed for the two shapes it checks. All 136 distinct celeris/<path>.go paths on the site exist on celeris origin/main 13fa176 (work/r1/path-exists-pr3.log). Controls (work/r1/controls-pr3.log): re-inserting :560-562 into sse.md fails the continuation test, a bare (server.go) in core-concepts.md fails the prefix test, restored and passing.
• Strict symbol control and the adjudication of the 60 flagged rows are in the body of docs: cite celeris symbols, not line numbers (configuration, middleware-traffic, websocket) #104. In this PR's pages: engines.md capability sources now name AcceptController, SwitchFreezer and SendfileCapable, the three declarations of the cited range.
• Test counts across the stack: 27 tests in docs: cite celeris symbols, not line numbers (configuration, middleware-traffic, websocket) #104 and docs: cite celeris symbols, not line numbers (routing helpers, data stores, performance, deployment, graceful shutdown) #105, 29 in this PR. The allowlist is empty on this head.

Checks on head 3534c2e (work/r1/): bun run validate, bun run build, bun run check and bun test exit 0 (ci-*-pr3-3534c2e.log; 29 tests across 2 files); verify_all.py 548 symbol citations, 0 bad (verify-all-pr3-3534c2e.log).

Review round 2 (head 519febd)

Refs #891 item 8. Plain merge of #105's head 10ed9f5 into this branch (no force-push), then:

• Major. streaming.md:54 (the Context.StreamWriter() nil-check example) cited appendClone: now Context.StreamWriter. streaming.md:69 (The StreamWriter API table) cited Context.materializeRequestViews: now StreamWriter. middleware-content.md:492 (Respond writes the exact protobuf variant, honors q=0) cited Write: now Respond. testing.md:221 (WithCookie does not escape ; or CR/LF) cited WithContentType: now WithCookie.
• Minor. streaming.md:367 ('Context.StreamWriter() returns nil' while buffering) cited the type: now Context.StreamWriter. routing.md:379 (the UsesDriver paragraph) cited Route.Async: now Route.UsesDriver. middleware-content.md:521 (FromContext falls back to default options) cited New: now FromContext. engines.md:521 (the per-worker WorkerLoop surface) names WorkerLoop besides EventLoopProvider.
• Sentence-level pass: all 515 rows over the stack are described in the body of docs: cite celeris symbols, not line numbers (configuration, middleware-traffic, websocket) #104; the verdict file has one line per row.

Checks on head 519febd: validate, build, check, test all exit 0 (logs ci-*-pr3.log in the lane).

Open points (not blocking)

• The symbol choice is the covering declaration at the revision each line was blamed to. verify_all checks that the symbol exists in its file on celeris origin/main, not that it is the one the author meant. A reviewer who knows that a citation meant another declaration can change that one symbol; the test would still pass.
• Negative controls were run on PR 1, PR 2 (earlier head) and, in Review round 1, on PR 3 (work/r1/controls-pr3.log). Introducing-commit check: done in Review round 1 (body of docs: cite celeris symbols, not line numbers (configuration, middleware-traffic, websocket) #104); the range-overlap rows were read against their sentences in Review round 2.
• Not run: nothing Linux, amd64 or cluster related applies to a docs-only change.

Refs #891 item 8
Refs #891 item 10

[coderabbitai]

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 53 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

• Configuration used: Repository: goceleris/docs/.coderabbit.yaml
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: a91054a1-0d9c-42a2-a85d-25ca9c53d10c

📥 Commits

Reviewing files that changed from the base of the PR and between 41d244e and 6bc0cd2.

📒 Files selected for processing: 19

• scripts/docs-symbol-citations.test.ts
• src/content/docs/binding-and-validation.md
• src/content/docs/context-api-reference.md
• src/content/docs/core-concepts.md
• src/content/docs/data-stores.md
• src/content/docs/deployment.md
• src/content/docs/engines.md
• src/content/docs/graceful-shutdown.md
• src/content/docs/middleware-auth.md
• src/content/docs/middleware-content.md
• src/content/docs/middleware-routing-helpers.md
• src/content/docs/middleware.md
• src/content/docs/net-http-interop.md
• src/content/docs/observability.md
• src/content/docs/performance.md
• src/content/docs/routing.md
• src/content/docs/sse.md
• src/content/docs/streaming.md
• src/content/docs/testing.md

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	goceleris-docs	499c0de	Commit Preview URL Branch Preview URL	Oct 19 2026, 11:11 AM

[FumingPower3925]

Merging with every required check green (build, coverage, CodeQL, codecov/patch, Workers Builds). The CodeRabbit review is advisory and had not finished.