[FumingPower3925]

Replaces line-number celeris citations with symbol citations, in three pages. Draft. Stacked: PR 2 (#105) is based on this branch and PR 3 on PR 2. Base is goceleris/docs origin/main 7ecb763 (after #102).

#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 the DOCSSITE PR does (item 8 and item 10 of the unticked list). The checklist issue stays open and its boxes are not ticked here.

What changed

• Item 8 (symbol citations, site-wide). configuration.md (60 locators), middleware-traffic.md (56), websocket.md (49) now cite celeris/<path>.go (Symbol) in place of path.go:N[-M]. 165 of 515 locators on the site so far.
• Item 10 (prefix convention). The celeris/ prefix is the repository name and is kept. Bare citations in middleware-traffic.md (9) get the prefix and the full repository path (for example celeris/middleware/overload/config.go, celeris/observe/collector.go). Subdirectory-relative paths are expanded the same way.
• Test (scripts/docs-symbol-citations.test.ts, run by bun test, which ci.yml already runs). It counts .go:N locators per page against an allowlist with exact counts, and it fails for a locator on any page that is not allowlisted, a count that drifts, or a continuation fragment on an unlisted page (shapes listed under Review round 1). This PR removes the three pages from the allowlist.

How the symbols were chosen

• Each locator's docs line was blamed to the docs commit that wrote it. That commit's date gives the celeris revision (git rev-list -1 --before). The declaration that covers the cited range in that revision was found with a go/ast tool, so fields (Config.MaxFormSize), methods (Conn.WriteMessage) and const-block entries (CompressionLevelDefault) are separate symbols. Doc comments are part of a declaration's span.
• Where the prose already named the symbol (for example "(WithDefaults)" after a locator), only the path is replaced, so there is no doubled name.
• Every new citation was then checked on celeris origin/main at 13fa176: the path exists and the symbol is declared in that file (verify.py: 515 of 515 ok). The check is done per file on main, so a symbol that moved to another file of the same name would still pass. That is the weakest point and is listed under open points.
• Citations that point at a file header or package comment (doc.go 30-32 and 41-44 in websocket.md, and idempotency.go 1-19 in middleware-traffic.md) have no declaration to name, so they cite the file only.

Checks run in the first version (head 95bfa70, tree as 19a013a; current head and logs under Review round 1)

• Failing first: bun test scripts/docs-symbol-citations.test.ts with an empty allowlist fails on 20 pages (log work/test-failing-first.log in the lane).
• Baseline: the allowlist of the 20 pages with exact counts passes (commit 97ceded).
• After this PR: the test passes with 17 pages allowlisted.
• Negative control A: git checkout of configuration.md (uncleaned) makes the page-offender test and the continuation test fail. Control B: one celeris/middleware/websocket/conn.go:100 line appended to websocket.md makes the offender test fail. Both restored; see work/controls-pr1.log.
• CI steps from ci.yml, run locally on 19a013a with bun from the lane (logs ci-*-pr1-final.log): bun run validate, bun run build, bun run check and bun test all exit 0 bun test ran 25 tests across 2 files. An earlier run on a610315 (logs ci-validate.log and siblings) also passed. verify_all.py on 19a013a: 177 citations on this tree, 0 bad (verify-all-pr1-final.log).
• Review follow-up, commit 19a013a: two bare citations in middleware-traffic.md pointed at the root config.go (Adaptive, Std) when the sentence was about bodylimit (Config.ContentLengthRequired) and idempotency (Config.Methods). Both corrected.
• Stale restatements: grep of src/content/docs for lines? [0-9]+, line-number, line number and L[0-9]+ finds none.

Review round 1 (head cb88174)

Refs #891 item 8. Findings of the first review, each with its evidence:

• Orphan fragments (major). The first version claimed zero locators remained, but the second and later locators of a multi-locator sentence had been kept as bare backticked fragments. In this PR's pages: configuration.md 243-245 (wrapped over two lines) and websocket.md :411 and :985. Now symbols: Config.WithDefaults with defaultEngine; Conn.ReadMessage with Conn.ReadMessageReuse; Conn.SetReadDeadline with Conn.SetWriteDeadline. The reviewer's grep, saved: work/r1/reviewer-grep-5a27611.log (7 lines on the old PR 3 head, 8 fragments counting the wrapped one). The same grep on the new head is empty, and .go:<digits> has 0 hits (work/r1/reviewer-grep-new-head.log).
• Ratchet widened, failing first. The detector (continuationLines in scripts/docs-symbol-citations.test.ts) flags, on every page outside the allowlist: a backticked N-M range or :N/:N-M fragment after a .go path on the same line; a comma list (x.go:1-2, 3-4); a wrapped line that starts with N-M and a closing backtick (243-245)); and a wrapped line that starts with a backticked :NorN-Mright after a line that holds a.gopath. It does not flag a listen address such as:8080or:0unless that opens a line right after a.goline (reword such a line). A plain backticked number such as0is not flagged. Failing-first run: commit be14253 adds the detector and the new tests; before the page fixes it fails with configuration.md:116, websocket.md:131 and websocket.md:303 (work/r1/failing-first-pr1.log). Unit controls in the test file: eight leftover shapes must be flagged and:8080, :0, a bare backticked 0and ordinary prose must not. Page controls (work/r1/controls-pr1.log): re-inserting:411in websocket.md fails the test, a wrapped:243` in configuration.md fails the test, restored and passing.
• Four mislabeled citations (major), corrected. The old locator was right when written; the symbol I had put in its place was not what it pointed at. configuration.md:442 cited Server.PauseAccept for the 863-868 range, which is Server.Collector (the sentence is about Collector() returning nil); it now cites Config.DisableMetrics, New and Server.Collector. middleware-traffic.md:507 cited Config.StopContext for config.go:177, which is defaultThresholds (stage table and thresholds): now Stage and defaultThresholds. websocket.md:475 cited Hub.Len for hub.go:56, the doc comment of Hub (encode once per broadcast): now Hub and Hub.Broadcast. websocket.md:637 cited Conn.CloseHandler (the getter) for conn.go:1029, the CloseError comment: now Conn.SetCloseHandler and CloseError. The earlier statement in this body that 863-868 is Server.PauseAccept was wrong (I had looked it up on celeris main by hand, not at the revision of the docs line) and is corrected in the sections below.
• Systematic control for that class (new). (1) work/r1/introducing.py takes the docs commit that introduced each of the 515 locator texts (git log --reverse -S<text> on the page at 7ecb763) and re-resolves at that celeris revision. All 515 have an introducing commit; for 505 it is the same celeris revision as the blame resolution, for 10 it differs, and the top candidate differs for 1 (work/r1/introducing.log). The three wrong labels above are not in that diff: their blame and introducing revision agree, and the error was in the symbol I chose by hand where the automatic resolution had found nothing (hub.go, conn.go) or the wrong file (bare config.go). So this check alone does not discriminate. (2) work/r1/strict.py therefore compares the symbols that map.json cites against the declaration covering the range at the introducing revision. Of 515 rows, 498 cite symbols (17 are path-only), and 60 are flagged (work/r1/strict.log, work/r1/show.log). The control holds: Config.StopContext, Hub.Len and Conn.CloseHandler are among the flagged. Adjudication of the 60: 5 wrong, now corrected (the three above, plus middleware-traffic.md:577 Thresholds for the DepthThresholds comment, and middleware-traffic.md:496 Controller for the overload.go package comment, now path-only); 6 correct as is (the const blocks of Stage x2, Protocol, EngineType, ClientPolicy, and Config.Limit for a sentence about the Limit field whose locator pointed at the Config type comment); 49 name a symbol declared inside the cited range, of which three were widened because the range held more than one: middleware-traffic.md:721 now ErrBodyTooLarge and ErrLengthRequired, engines.md capability sources (PR 3), performance.md:84 Context.JSON (PR 2). (3) The nine continuation ranges that map.json does not carry were re-resolved at their introducing revisions (work/r1/contranges.log, contranges2.log): 294-303 is Config.WithDefaults, 317-326 is resolveTimeout, 279-284 and 276-278 are Config.WithDefaults, 175-177 is Config.Validate, 863-868 is Server.Collector, 243-245 is Config.WithDefaults, 178-181 is Config.DisableMetrics, 152-154 is New. configuration.md:58 now names Config.WithDefaults and resolveTimeout.
• Enclosing-type citations (minor). configuration.md:505 now cites Config.OnConnect and Config.OnDisconnect. The three Sources: lines (189, 342, 370) now name the fields of the old range (Config.ReadTimeout ... Config.ShutdownTimeout; the three HTTP/2 fields; Config.DisableKeepAlive, Config.BufferSize, Config.SocketRecvBuf, Config.SocketSendBuf, Config.MaxConns). Other Config or <X>Config citations that stay at type level (about 25 on the site) each head a field table for that type, and the type is the declaration that locates the table.
• .coderabbit.yaml (nit). The review-bot instruction told reviewers to check cited line numbers; it now asks for file and symbol and says not to ask for line numbers.

Checks on head cb88174 (work/r1/): bun run validate, bun run build, bun run check and bun test exit 0 (ci-*-pr1-cb88174.log; 27 tests across 2 files); verify_all.py 195 symbol citations, 0 bad (verify-all-pr1-cb88174.log). The checks above establish that a symbol exists in the cited file on celeris origin/main 13fa176 and that it covers the range at the introducing revision. They do not establish that a reader would pick the same symbol for the claim.

Neighbours changed in the same pages

• middleware-traffic.md: two citations of the same New in one sentence ("singleflight.go:102-149, singleflight.go:143") are one citation now.
• configuration.md: the two continuation ranges in the same sentences (294-303, 317-326, 276-278, 863-868) are written as symbols or dropped, since they were line numbers too. The 863-868 range (server.go) is Server.Collector at the revision of its docs line (this body first said Server.PauseAccept; see Review round 1).

Review round 2 (head 20380a0)

Refs #891 item 8. Merge of origin/main (0c840e2, #107) into this branch, then:

• Major. middleware-traffic.md:215 cited luaUndo for 'the script'; luaUndo is the refund script, the atomic token-bucket script is luaTokenBucket (//go:embed redisstore.lua). Now luaTokenBucket (with New).
• Minor. websocket.md:314: the bullet is about SetCompressionLevel (range -2..9) but only Conn.EnableWriteCompression was cited; both are named now.
• Sentence-level pass (all three PRs; verdicts in the lane at lanes-20261019/DOCSCITES-FIX/verdicts.tsv, one line per row). All 515 citations were read against the sentence they support, not only against the old range. Rows whose old range covered more than one declaration (struct fields, const-block entries and methods counted separately): 107, plus 15 whose range held no declaration (package or file comments, cited path-only); the remaining 393 cover a single declaration. The first-pass resolver had a systematic weakness: when the range began inside a declaration that was not the one the sentence is about, it took the first overlapping declaration (or the last, for a range end), which is how the five major errors below arose. Result: 12 rows corrected (5 major, 7 minor), 503 kept. Rows 96, 118, 296, 318 and 320 (bare config.go:N that the first pass resolved against the root config.go) were checked by hand against the middleware's own config.go; they are right in the pages. Every symbol on every page was checked to exist in its file on celeris main 13fa176.

Checks on head 20380a0 (bun install --frozen-lockfile, bun run validate, bun run build, bun run check, bun test): all exit 0, 27 tests (logs ci-*-pr1.log in the lane).

Open points (not blocking)

• Introducing-commit check: done in Review round 1 for all 515 locators (revision differs for 10, top candidate for 1). The reading of every range-overlap row against its sentence is done in Review round 2 below (it found the five errors named there).
• The symbol choice for a locator is the covering declaration at the revision the line was blamed to. A reviewer who knows a specific citation meant another declaration can change that one symbol; the test does not check meaning, only existence.
• The continuation ranges in configuration.md were first looked up by hand against celeris origin/main; that is where the Server.PauseAccept error came from. They are now re-resolved at their introducing revisions (Review round 1).
• Per-page counts in the task text (configuration 62, deployment 35) are from before docs: shutdown, deployment, getting-started, error-handling and data-stores match v1.6.0 #102. The counts here are 60 and 34 at 7ecb763.
• Not run: nothing Linux, amd64 or cluster related applies to a docs-only change.

Refs #891 item 8
Refs #891 item 10

[coderabbitai]

Note

Currently processing new changes in this PR. This may take a few minutes, please wait...

⚙️ Run configuration

• Configuration used: Repository: goceleris/docs/.coderabbit.yaml
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: f37cc286-cc6b-4938-a37e-b65ee14321e9

📥 Commits

Reviewing files that changed from the base of the PR and between 0c840e2 and 20380a0.

📒 Files selected for processing: 5

• .coderabbit.yaml
• scripts/docs-symbol-citations.test.ts
• src/content/docs/configuration.md
• src/content/docs/middleware-traffic.md
• src/content/docs/websocket.md

Warning

This pull request changes a CodeRabbit configuration file. Because it comes from a fork or its author is not a repository collaborator, reviews use only the configuration from the target branch. The proposed configuration will take effect after it is merged.

✨ Finishing Touches

📝 Generate docstrings

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• 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	20380a0	Commit Preview URL Branch Preview URL	Oct 19 2026, 10:57 AM

[FumingPower3925]

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