fix(web): speed up PR previews with fewer GitHub requests

[dominic-r]

PR hover cards appear 41% sooner, fresh PR opens are 36% faster, and hovering three PRs uses 56% fewer GraphQL requests and points than main. Opening after hover stays around 0.3s on both.

An intentional hover fetches full detail after the existing 350 ms delay and reuses it on click. One GraphQL query combines core detail, permissions, merge settings, checks and branch comparison. Both workflow approval safety checks remain; large check lists retain pagination. Crossing links triggers no requests.

Compared actual main 9ea9c3d5d with this PR f4d4be88d using separate checkouts, production web bundles, fresh browser/server caches and the same real GitHub PRs (#11825, #11806, #11990). Five matched hover sessions and three fresh-click sessions, alternating order; September 18.

Browser timing, median	Main	This PR
Cold hover card	4,865 ms	2,854 ms
Immediate repeat hover	829 ms	74 ms
Fresh click without hovering	4,560 ms	2,932 ms
Open after hovering three PRs	317 ms	305 ms

Post-hover opening ranges overlap: main 260–355 ms, PR 298–352 ms. Treat this as comparable cached opening latency. Click timing ends when full-detail tabs appear; activity may finish later.

Workload	Main: GraphQL requests / points	This PR: GraphQL requests / points
Cold hover	5 / 5	2 / 2
Hover three different PRs	9 / 9	4 / 4
Hover three PRs, then open the first	11 / 25	6 / 20
Fresh click without hovering	7 / 21	4 / 18
Cross ten links / repeat cached hover	0 / 0	0 / 0

Open-session totals include activity and stack reads. Setup traffic is excluded equally. Counts include requests inside gh; GraphQL costs use rateLimit.cost, replaying CLI-generated queries after timing. The earlier 10-point three-hover baseline was corrected to 9: a REST quota probe had been counted as a GraphQL point.

Measurements, ranges and samples · Reproduction scripts, fixture and captured queries

477 focused tests pass; server/web typechecks, targeted lint and production web build pass. Reserve protection and manual-action access are covered. A real browser hover with a simulated GitHub CLI rate-limit failure verified the original-URL fallback (screenshot). No live account was exhausted.

Web and desktop share the hover component; native Electron was not timed separately. Mobile shares the server improvement and has no hover interaction.

Main	This PR

Main video · PR video. Normal-speed illustrative samples; tables use all selected runs.

Implemented with GPT-6 in Codex.

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This PR introduces a new authenticated pull-request preview RPC and changes provider, caching, client-state, and hover-link behavior across the production path. It also touches authorization code and has unresolved risks involving Forgejo host resolution and preview-cache freshness, so the change is not limited to a low-risk performance tweak.

Not approved because:

• 2 blocking correctness issues found at or above your repo's Minimum Blocking Severity

^{Adjust the Minimum Blocking Severity for this repo — including turning it Off — in Settings. You can add or adjust custom eligibility rules. Learn more.}

[dominic-r]

Both correctness findings in the Macroscope summary above are fixed in 868c761, with replies on each review thread. The preview now respects the detail cache TTL without awaiting pending detail, and Forgejo links preserve their HTTP authority. The expiry regression failed before the fix; all 309 focused tests and CI on the latest commit pass. Both threads are resolved. The summary currently reflects the previous commit, 3ef5185.

[dominic-r]

@coderabbitai review

[dominic-r]

@macroscope-app review the latest commit, 868c761. Both findings from the previous review have been fixed and verified; the review threads contain the details.

[macroscopeapp]

Sorry, I'm unable to act on this request because you do not have permissions within this repository.

[macroscopeapp]

Sorry, I'm unable to act on this request because you do not have permissions within this repository.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: 3379b2d9-6748-42a5-8a32-cbf4d0ecca86

📥 Commits

Reviewing files that changed from the base of the PR and between 15b5030 and dd50c1b.

📒 Files selected for processing (16)

• apps/server/src/auth/RpcAuthorization.ts
• apps/server/src/pullRequest/GitHubPullRequestCli.test.ts
• apps/server/src/pullRequest/GitHubPullRequestCli.ts
• apps/server/src/pullRequest/GitHubPullRequestProvider.test.ts
• apps/server/src/pullRequest/GitHubPullRequestProvider.ts
• apps/server/src/pullRequest/PullRequestProvider.ts
• apps/server/src/pullRequest/PullRequestService.test.ts
• apps/server/src/pullRequest/PullRequestService.ts
• apps/server/src/pullRequest/gitHubPullRequestJson.ts
• apps/server/src/ws.ts
• apps/web/src/components/ChatMarkdown.tsx
• packages/client-runtime/src/state/pullRequestRouting.ts
• packages/client-runtime/src/state/pullRequests.test.ts
• packages/client-runtime/src/state/pullRequests.ts
• packages/contracts/src/pullRequest.ts
• packages/contracts/src/rpc.ts

Included review availability: Your plan provides up to 10 included reviews per hour; 9 remain after this review.

---

📝 Walkthrough

Walkthrough

This change adds a lightweight pull request preview contract and RPC. The server provides GitHub preview data with caching and fallback behavior. The client routes and refreshes preview queries, then uses them before loading full details.

Changes

Pull request preview flow

Layer / File(s)	Summary
Preview contract and provider API packages/contracts/src/pullRequest.ts, packages/contracts/src/rpc.ts, apps/server/src/pullRequest/PullRequestProvider.ts	Defines PullRequestPreview, the pullRequests.preview RPC, and the optional provider preview method.
Server preview path apps/server/src/pullRequest/gitHubPullRequestJson.ts, apps/server/src/pullRequest/GitHubPullRequestCli.ts, apps/server/src/pullRequest/GitHubPullRequestProvider.ts, apps/server/src/pullRequest/PullRequestService.ts, apps/server/src/ws.ts, apps/server/src/auth/RpcAuthorization.ts, apps/server/src/pullRequest/*test.ts	Adds GitHub GraphQL decoding, provider delegation, service caching and fallback behavior, WebSocket wiring, authorization, and validation.
Concurrent workflow reads apps/server/src/pullRequest/GitHubPullRequestCli.ts, apps/server/src/pullRequest/GitHubPullRequestCli.test.ts, apps/server/src/pullRequest/GitHubPullRequestProvider.ts, apps/server/src/pullRequest/GitHubPullRequestProvider.test.ts	Runs workflow listing, pull-request head probing, and change-request comparison concurrently, with synchronization tests and updated call-count assertions.
Client preview cache and hover flow packages/client-runtime/src/state/pullRequestRouting.ts, packages/client-runtime/src/state/pullRequests.ts, packages/client-runtime/src/state/pullRequests.test.ts, apps/web/src/components/pullRequest/PullRequestLinkPreview.tsx, apps/web/src/components/ChatMarkdown.tsx	Adds routed preview queries, mutation-triggered refreshes, cache tests, and preview-first link hover, focus, and click behavior.

Priority: ➖ Normal

Estimated code review effort: 4 (Complex) | ~45 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant PullRequestLinkPreview
  participant PullRequestService
  participant GitHubPullRequestProvider
  participant GitHubPullRequestCli
  participant GitHub
  User->>PullRequestLinkPreview: hover or focus link
  PullRequestLinkPreview->>PullRequestService: request preview
  PullRequestService->>GitHubPullRequestProvider: getChangeRequestPreview
  GitHubPullRequestProvider->>GitHubPullRequestCli: getPullRequestPreview
  GitHubPullRequestCli->>GitHub: GraphQL preview query
  GitHub-->>GitHubPullRequestCli: preview fields
  GitHubPullRequestCli-->>PullRequestService: decoded preview
  PullRequestService-->>PullRequestLinkPreview: preview data
  PullRequestLinkPreview->>PullRequestService: warm full detail

Loading

Suggested reviewers: juliusmarminge

Merge Risk: ⚪ Minimal · up to dd50c

The preview flow, cache behavior, authorization, routing, and concurrent reads have no confirmed remaining merge-blocking risk.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 16.67% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 6 functions across 17 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly summarizes the main change: improving web pull request preview speed while reducing GitHub requests.
Description check	✅ Passed	The description provides detailed change scope, performance rationale, UI evidence, validation results, and test coverage. It does not use the template headings or checklist, but it is complete enough…

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

---

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

[coderabbitai]

❌ Action failed

Review failed.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[dominic-r]

@coderabbitai The review summary covers 3ef5185; the latest commit is 868c761, which fixes preview cache expiry and Forgejo ports and adds regression coverage. The 80% docstring warning conflicts with this repository’s AGENTS.md guidance to document non-obvious reasons rather than narrate clear code. I have retained the comments explaining preview scope and warming, and the executable regression tests, without adding boilerplate to meet a percentage. Please assess the new commit when the incremental review runs.

[dominic-r]

@coderabbitai full review

[coderabbitai]

✅ Action performed

Full review finished.

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf '%s\n' '--- commit ---'
git show --no-ext-diff --format=fuller --stat 868c7610e --

printf '%s\n' '--- relevant file outlines ---'
ast-grep outline apps/server/src/pullRequest/PullRequestService.ts --items all --match 'preview|detail|cache|invalidate|refresh' || true
ast-grep outline apps/web/src/components/ChatMarkdown.tsx --items all --match 'PullRequest|pullRequest|Preview' || true
ast-grep outline apps/server/src/pullRequest/PullRequestService.test.ts --items all --match 'preview|detail|expire|TTL|Forgejo' || true

printf '%s\n' '--- patch ---'
git show --no-ext-diff --format= --find-renames 868c7610e -- \
  apps/server/src/pullRequest/PullRequestService.ts \
  apps/server/src/pullRequest/PullRequestService.test.ts \
  apps/web/src/components/ChatMarkdown.tsx

printf '%s\n' '--- guidance ---'
fd -HI '^AGENTS\.md$' . -x sh -c 'echo "--- $1"; cat "$1"' sh {} \;

Length of output: 144146

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf '%s\n' '--- cache and preview references ---'
rg -n -C 5 '\b(detailCache|previewCache|lastGoodDetail|refCacheKey|Cache\.getSuccess|const preview)\b' \
  apps/server/src/pullRequest/PullRequestService.ts

printf '%s\n' '--- cache helper definitions and call sites ---'
rg -n -C 4 '\bgetSuccess\b|\bexport.*Cache\b|\bnamespace Cache\b|\bclass Cache\b' \
  apps/server packages --glob '*.{ts,tsx}' | head -300

printf '%s\n' '--- Forgejo test context ---'
sed -n '1815,1955p' apps/server/src/pullRequest/PullRequestService.test.ts

printf '%s\n' '--- link candidate authority and preview consumers ---'
rg -n -C 5 '\b(authority|pullRequestCandidate|preview)\b' \
  apps/web/src/components/ChatMarkdown.tsx \
  apps/web/src/components/pullRequest/PullRequestLinkPreview.tsx \
  packages/client-runtime/src/state/pullRequests.ts

printf '%s\n' '--- relevant cache implementation candidates ---'
fd -HI '.*[Cc]ache.*\.(ts|tsx)$' apps packages | head -100

Length of output: 48760

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf '%s\n' '--- service cache configuration ---'
sed -n '2420,2485p' apps/server/src/pullRequest/PullRequestService.ts
sed -n '2665,2778p' apps/server/src/pullRequest/PullRequestService.ts

printf '%s\n' '--- cache API implementation ---'
rg -n -C 8 'getSuccess\s*[=:]' .repos/effect-smol packages apps \
  --glob '*.{ts,tsx}' | head -240

printf '%s\n' '--- PullRequestService test helper ---'
rg -n -C 8 '\bfunction fakeProvider\b|\bconst fakeProvider\b|\bfakeProvider\s*=' \
  apps/server/src/pullRequest/PullRequestService.test.ts

printf '%s\n' '--- TTL declaration ---'
rg -n -C 3 '\bDETAIL_CACHE_TTL\b' apps/server/src/pullRequest/PullRequestService.ts

printf '%s\n' '--- parsed authority type and function ---'
rg -n -C 5 '\bparseChangeRequestUrl\b|\bauthority\b' \
  packages apps --glob '*.{ts,tsx}' | head -220

Length of output: 37085

---

@dominic-r I assessed commit 868c7610e.

The preview path now uses Cache.getSuccess(detailCache, key). This API returns no value for expired or pending entries. It does not start or await a detail read. The preview path then reads previewCache. The 16-second TestClock regression test verifies expiry beyond the 15-second detail TTL.

The Forgejo path now passes pullRequestCandidate.authority when present. The URL parser derives this value from url.host, which retains the port. The regression coverage reaches the provider with code.example:3000.

The docstring-percentage finding does not match the root AGENTS.md documentation guidance. The existing rationale comments and executable regression tests are appropriate. I found no remaining issue in these fixes.

---

✏️ Learnings added

Learnt from: dominic-r
URL: https://github.com/pingdotgg/t3code/pull/11825

Timestamp: 2026-09-15T00:13:06.450Z
Learning: In this repository, root `AGENTS.md` directs contributors to document non-obvious rationale and constraints. Do not add boilerplate docstrings that narrate clear implementation details solely to meet a documentation percentage.

Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.

You are interacting with an AI system.

[juliusmarminge]

Has the GitHub rate-limit impact of this been evaluated and tested?

Every pointer-enter and focus on a PR link now issues a GraphQL query (plus the warm-up detail read once the card opens), where before nothing left the client until the card actually opened. The client caches for 60s and the server for 15s, so a single hover is cheaper than the old detail fan-out, but the prefetch fires for every link a pointer crosses, so a scroll through a thread full of PR links can now cost a burst of requests that never happened before.

I already hit GitHub rate limits fairly often in day-to-day use, and we have a broader problem to fix there first. I don't want to add more pressure on top of that before that's sorted. Could you share what you measured: how many GraphQL points a hover-heavy session costs before vs. after, and whether you tested it against a session that's already close to the limit (does the budget helper's reserve kick in and degrade gracefully, or do hovers start failing)?

[dominic-r]

@juliusmarminge Updated to reuse the optimized detail fetch on click. Against main, median hover is 4.87s → 2.85s (41% faster) and fresh opens are 4.56s → 2.93s (36% faster). Opening after hover stays around 0.3s on both (317ms → 305ms across five runs).

Three hovers use 9 GraphQL requests / 9 points → 4 / 4; hovering then opening uses 11 / 25 → 6 / 20. Crossing links still triggers zero requests. Reserve/fallback checks pass; measurements and reproduction scripts are in the description.