Introduce a first-class PR review session model #81

New issue

Closed

opened 2026-04-07 17:04:10 +00:00 by barrettruth · 1 comment

barrettruth commented

2026-04-07 17:04:10 +00:00

Summary

forge.nvim needs a real review session model for PR review instead of treating review as a thin PR side action that mostly proxies to checkout + diff tooling.

This issue is the architectural foundation for the review workflow.

Goals

represent PR review as a first-class session, not just a diff action
define canonical review subject/session state
keep the implementation picker-agnostic so fzf-lua, telescope, and snacks can all drive the same review flow
avoid baking checkout/worktree behavior into the definition of review

Proposed direction

Introduce an internal review model that can answer:

what subject is being reviewed?
what are the resolved base/head refs?
what mode is active?
what files belong to the review session?
what materialization strategy is in use, if any?

Example shape:

{
  subject = {
    kind = 'pr',
    id = '123',
    label = 'PR #123',
    base_ref = 'origin/main',
    head_ref = 'pr/123',
  },
  mode = 'patch',
  files = { ... },
  current_file = nil,
  materialization = 'current',
}

Scope

review subject/session types and state
PR subject resolution
base/head resolution for PR review
review state that can support later navigation and view changes

Out of scope

branch/commit review entrypoints
changed-files UI
patch/file-context switching
file/hunk navigation details

Part of #63.

## Summary forge.nvim needs a real review session model for PR review instead of treating review as a thin PR side action that mostly proxies to checkout + diff tooling. This issue is the architectural foundation for the review workflow. ## Goals - represent PR review as a first-class session, not just a `diff` action - define canonical review subject/session state - keep the implementation picker-agnostic so fzf-lua, telescope, and snacks can all drive the same review flow - avoid baking checkout/worktree behavior into the definition of review ## Proposed direction Introduce an internal review model that can answer: - what subject is being reviewed? - what are the resolved base/head refs? - what mode is active? - what files belong to the review session? - what materialization strategy is in use, if any? Example shape: ```lua { subject = { kind = 'pr', id = '123', label = 'PR #123', base_ref = 'origin/main', head_ref = 'pr/123', }, mode = 'patch', files = { ... }, current_file = nil, materialization = 'current', } ``` ## Scope - review subject/session types and state - PR subject resolution - base/head resolution for PR review - review state that can support later navigation and view changes ## Out of scope - branch/commit review entrypoints - changed-files UI - patch/file-context switching - file/hunk navigation details Part of #63.

barrettruth commented

2026-04-10 22:00:31 +00:00

Implemented on main in #89 as part of the review workflow foundation.