feat(git): add git review-url to resolve an issue's Linear review URL

[oliviasculley]

What

linear-cli git review-url <issue> prints the Linear review page URL(s) for the pull requests attached to an issue:

$ linear-cli git review-url ABC-262
https://linear.app/acme/review/readings-read-side-aggregation-stage-1b-abc-262-3f92e33afbc6

$ linear-cli git review-url ABC-262 -o json --compact
[{"number":303,"reviewUrl":"https://linear.app/acme/review/readings-…-3f92e33afbc6","status":"merged","title":"Readings read-side aggregation","url":"https://github.com/acme/app/pull/303"}]

How, and why this way

There is no public GitHub-URL → review-URL lookup, and the slug is not on the issue: issue.attachments (and attachmentsForURL) carry the pull request as a sourceType: "github" attachment with rich GitHub metadata and no review URL. So this resolves in two steps:

1. PullRequestNotification — the one public place a pull request is paired with its review page. Its url is the review URL (review/<title-slug>-<id>), so it's returned verbatim; a #comment-<id> anchor from a comment notification is trimmed. The command matches the issue's github pull request attachments against the feed. The feed has no server-side filter for pull requests, so it's walked newest-first for at most 5 pages — the one part of this I'd happily replace if there's a filter I missed.
2. Agent sessions — fallback. AgentSession.pullRequests exposes PullRequest.slugId directly, from which the URL is assembled with organization.urlKey.

Results are merged per pull request, so a PR reachable both ways is listed once.

What stays unresolvable is a pull request with no notification and no agent session — in practice one opened minutes ago with no CI result, comment, or review yet. The command reports that (naming the GitHub URL as the alternative) rather than emitting a URL that would 404. Happy to switch that to exit 0 with empty output if you'd prefer it for scripting.

For completeness on what was ruled out: Query.diff(id:) reaches a PullRequest but is [Internal] and takes a Diff id nothing public hands out — it rejects a slug, a PR URL, an attachment id, a GitHub node id, and a pullRequestId from a notification.

Testing

• 7 unit tests on pure helpers: attachment filtering (GitHub pull requests only, deduped, non-PR URLs and other sources ignored), notification matching (only the requested PR, URL used verbatim, comment anchor trimmed), merge precedence, and the agent-session path (URL from slug, dedupe across sessions, and never a bogus URL when a slug is missing or blank).
• Full suite green: 557 tests. cargo fmt clean on the touched files; cargo clippy --all-targets adds no new warnings.
• Verified against a live workspace on all three paths: an ordinary branch-detected PR resolves through notifications, an agent-session PR resolves through the fallback, and a PR opened an hour earlier with no activity reports the limitation.

git::handle gains the &OutputOptions argument the other command modules already take, so -o json / --format work here too.

[oliviasculley]

Pushed a correction. My first pass claimed the review URL only exists for agent-session PRs — that was wrong. Linear creates a review page for any PR it detects from a branch, and PullRequestNotification.url is that page, so the command now resolves through the notification feed (returning the canonical URL, title slug and all) and keeps the agent-session path only as a fallback. Description updated to match.

[oliviasculley]

I'm not too familiar with rust but hopefully this is good, and the command design makes sense, I'm happy to change anything about this!

[Finesssee]

Thanks for the PR, I will review this ASAP.

[Finesssee]

Thermo-nuclear code quality review

Verdict: request changes

1. [Blocker] Decompose git.rs before merging

src/commands/git.rs:184-410, 847-992

This PR pushes git.rs from 653 to 1,042 physical lines. The new code also has little to do with local Git/VCS operations: it owns GraphQL queries, notification pagination, API decoding, source precedence, deduplication, rendering, and tests.

Move this feature into a focused module such as src/commands/git/review_url.rs; leave only the command variant and dispatch in git.rs. Extraction should be combined with the simplifications below rather than merely moving all 389 lines unchanged.

2. [High] Partial resolution incorrectly exits successfully

src/commands/git.rs:381-399

The command only errors when entries.is_empty(). Given two attached PRs where one resolves through notifications and the other has neither a recent notification nor an agent-session slug, it prints the first URL and exits 0 without mentioning the unresolved PR. That contradicts the documented promise that an unresolvable PR is reported and makes scripting unreliable.

Model the result explicitly as resolved and unresolved PRs. Verify every attached PR URL was resolved before printing, or intentionally expose unresolved entries in the output contract. Add a mixed-result test covering one resolved and one unresolved attachment.

3. [High] Replace the raw-JSON merge pipeline with a typed resolution model

src/commands/git.rs:214-288

The 227-line production feature contains 35 string-indexed JSON accesses. Both sources construct anonymous Value objects, and merge_review_entries then reads those objects back through string keys. Missing fields silently become null or empty strings, while source precedence and identity are implicit conventions.

Define typed deserialization models plus a serializable ReviewEntry, then merge into one map keyed by GitHub PR URL. Insert the agent-session fallback first and let notification results replace it, or use an explicit precedence method. This removes much of merge_review_entries, the repeated json! construction, and fragile indexing while making required fields and unresolved states explicit.

4. [Medium] Do not add another private cursor-pagination implementation

src/commands/git.rs:299-337

This duplicates the canonical machinery in src/pagination.rs. It also handles malformed pagination less safely: if hasNextPage is true but endCursor is absent, it sends after: null and can reread the first page until the five-page cap.

Use paginate_nodes with a 500-item limit and 100-item page size. If stopping as soon as every PR is found materially matters, add a reusable short-circuiting paginator rather than maintaining another cursor state machine inside a feature command.

Validation

• PR merge code compiled successfully in CI.
• 359 unit tests and 203 integration tests passed, with zero failures.
• git diff --check passes.
• The PR check is red because cargo fmt --check found an unrelated trailing blank line in unchanged src/commands/initiatives.rs; Clippy therefore did not run.
• No test currently covers partial resolution across multiple attached PRs.

[oliviasculley]

Thanks — all four addressed in add6954.

1. Decompose git.rs — the feature now lives in src/commands/git/review_url.rs; git.rs keeps the command variant and dispatch and is back to 672 lines (653 before this PR). The extraction carries the simplifications below rather than moving 389 lines unchanged.

2. Partial resolution — resolution is modelled explicitly as resolved plus unresolved pull requests, and unresolved ones are now part of the output contract rather than dropped:

• -o json returns {"resolved": [...], "unresolved": [...]}
• plain text prints the review URLs on stdout and names each unresolved pull request on stderr
• the command still fails only when it resolved nothing at all

I went with exposing unresolved entries rather than failing the whole command, since an issue with an old resolved PR and a brand-new unresolvable one still has a useful answer — but it can no longer be mistaken for the whole set. test_merge_reports_an_attached_pull_request_neither_source_resolved covers one resolved + one unresolved, and test_resolution_serializes_both_halves pins the JSON shape. README and after_help updated to match.

3. Typed resolution model — typed Deserialize models for both sources plus a serializable ReviewEntry; the two merge into one map keyed by GitHub PR URL, agent-session fallback inserted first so a notification result replaces it. Production json! construction and string-indexed access are gone (35 → 3, all three being the GraphQL envelope unwrap), merge_review_entries with it. Required fields are Options instead of silent nulls, and a pull request Linear returns without a URL now yields no entry rather than one with a null identity.

Ordering is explicit too: entries come back in attachment order, then any pull request an agent session linked without an attachment — test_merge_reports_in_attachment_order_then_unattached_pull_requests pins that against both arrival order and lexicographic-by-URL.

4. Pagination — the private cursor loop is gone. Rather than 5 fixed pages via paginate_nodes, I added paginate_until next to it in pagination.rs — the reusable short-circuiting paginator you suggested as the alternative. Plain paginate_nodes with a 500 limit would turn the common resolved-on-the-first-page case from 1 request into 5 on an interactive command, which seemed worth avoiding. It follows the canonical cursor rules, including stopping when a connection claims hasNextPage without an endCursor — the malformed case the private loop answered by rereading the first page until its cap.

The feed walk is now a small NotificationScan that owns the accumulator, which also fixed a latent bug: the feed is newest-first, so an older notification for the same pull request on a later page must not displace the one already held (test_scan_keeps_the_newest_notification_per_pull_request).

Also — dropped the trailing blank line in initiatives.rs so cargo fmt --check passes and Clippy can run. It came in on master, not this branch, but it was blocking this PR's check.

Validation: 362 unit + 203 integration tests pass, cargo fmt --check clean, cargo clippy -- -D warnings clean, git diff --check clean.

Hopefully this looks good!