source

Documentation

Overview

Package source resolves command-line arguments into a ReviewSource: something that yields a parsed set of file diffs, a human title, and a stable key for draft persistence. It unifies the patch-file / stdin path with the local-git path; pull-request references are resolved by the CLI layer into a PRSource before Resolve is consulted.

Index

• func InferPRRef(ctx context.Context, dir string, ref forge.PullRequestRef) (forge.PullRequestRef, error)
• type ContextContenter
• type ExchangeSource
  • func (s *ExchangeSource) Exchange() *review.Exchange
  • func (s *ExchangeSource) Files(context.Context) ([]diff.FileDiff, error)
  • func (s *ExchangeSource) HeadOID(context.Context) string
  • func (s *ExchangeSource) Key() string
  • func (s *ExchangeSource) Path() string
  • func (s *ExchangeSource) RawPatch(context.Context) ([]byte, error)
  • func (s *ExchangeSource) Title() string
• type Options
• type PRSource
  • func NewPRSource(ctx context.Context, f forge.Forge, ref forge.PullRequestRef) (*PRSource, error)
  • func (s *PRSource) Attachment(ctx context.Context, url string) ([]byte, error)
  • func (s *PRSource) ContextContent(ctx context.Context, path string, side diff.Side) ([]byte, error)
  • func (s *PRSource) ContextKey(_ context.Context, path string, side diff.Side) string
  • func (s *PRSource) Files(ctx context.Context) ([]diff.FileDiff, error)
  • func (s *PRSource) Forge() forge.Forge
  • func (s *PRSource) GeneralComments(ctx context.Context) ([]forge.Comment, error)
  • func (s *PRSource) HeadOID(context.Context) string
  • func (s *PRSource) Key() string
  • func (s *PRSource) PullRequest() *forge.PullRequest
  • func (s *PRSource) RawPatch(ctx context.Context) ([]byte, error)
  • func (s *PRSource) Ref() forge.PullRequestRef
  • func (s *PRSource) Threads(ctx context.Context) ([]forge.Thread, error)
  • func (s *PRSource) Title() string
• type RawPatcher
• type ReviewSource
  • func Resolve(ctx context.Context, opts Options) (ReviewSource, error)

Functions

func InferPRRef

func InferPRRef(ctx context.Context, dir string, ref forge.PullRequestRef) (forge.PullRequestRef, error)

InferPRRef fills in a missing owner/repo (and host) from the origin remote of the repository at dir, so a bare PR number resolves inside a checkout. It is a no-op when owner and repo are already set (e.g. from a full URL).

Types

type ContextContenter

type ContextContenter interface {
	ContextKey(ctx context.Context, path string, side diff.Side) string
	ContextContent(ctx context.Context, path string, side diff.Side) ([]byte, error)
}

ContextContenter is implemented by sources that can produce the full content of a file on either side of the diff — new side for the TUI's full-file context view, old side additionally for whole-file syntax highlighting of deletions. ContextKey is the content's cache identity (cheap to compute; "" means uncacheable — typically mutable local state like the working tree), and ContextContent performs the actual, possibly expensive, fetch. Callers pass the path as spelled on that side (renames).

type ExchangeSource

type ExchangeSource struct {
	// contains filtered or unexported fields
}

ExchangeSource is a ReviewSource backed by a review-exchange file: the diff under review is the patch embedded in the document, and the document's comments seed the draft. It keeps the file path so the session can write the updated conversation back to the same place — the file, not the draft store, is the medium the two sides of the conversation share.

func (*ExchangeSource) Exchange

func (s *ExchangeSource) Exchange() *review.Exchange

Exchange exposes the parsed document so the CLI can seed the draft from it.

func (*ExchangeSource) Files

func (s *ExchangeSource) Files(context.Context) ([]diff.FileDiff, error)

Files parses the embedded patch — the only diff the conversation's line numbers are meaningful against.

func (*ExchangeSource) HeadOID

func (s *ExchangeSource) HeadOID(context.Context) string

HeadOID is empty: the embedded patch carries no commit identity, and relocation across patch versions happens on import instead.

func (*ExchangeSource) Key

func (s *ExchangeSource) Key() string

Key seeds the draft store's filename; path-based so round trips resume.

func (*ExchangeSource) Path

func (s *ExchangeSource) Path() string

Path is where the conversation lives on disk — the writeback target.

func (*ExchangeSource) RawPatch

func (s *ExchangeSource) RawPatch(context.Context) ([]byte, error)

RawPatch returns the embedded patch for re-embedding on writeback.

func (*ExchangeSource) Title

func (s *ExchangeSource) Title() string

Title is the document's title, or the filename when it has none.

type Options

type Options struct {
	Args    []string  // positional arguments
	Base    string    // --base <ref>
	Staged  bool      // --staged
	Context int       // -U context lines
	Stdin   io.Reader // stdin, used when the argument is "-"
	Dir     string    // working directory (defaults to process CWD)
}

Options are the parsed CLI inputs used to resolve a source.

type PRSource

type PRSource struct {
	// contains filtered or unexported fields
}

PRSource is a ReviewSource backed by a forge pull request. It uses the host's canonical diff (the representation comments must align with) and exposes the forge, ref, and threads so the TUI can reply and submit reviews.

func NewPRSource

func NewPRSource(ctx context.Context, f forge.Forge, ref forge.PullRequestRef) (*PRSource, error)

NewPRSource fetches pull-request metadata and returns a ready source. The metadata call establishes the title and head commit up front.

func (*PRSource) Attachment

func (s *PRSource) Attachment(ctx context.Context, url string) ([]byte, error)

Attachment fetches a comment-attachment URL through the forge's authentication — comment images on private repos are unreachable without it.

func (*PRSource) ContextContent

func (s *PRSource) ContextContent(ctx context.Context, path string, side diff.Side) ([]byte, error)

ContextContent fetches the file at the side's commit through the forge.

func (*PRSource) ContextKey

func (s *PRSource) ContextKey(_ context.Context, path string, side diff.Side) string

ContextKey is commit + path: PR file content is immutable per commit, so a force-push or new commit changes the key rather than any cache state.

func (*PRSource) Files

func (s *PRSource) Files(ctx context.Context) ([]diff.FileDiff, error)

Files fetches and parses the canonical PR diff.

func (*PRSource) Forge

func (s *PRSource) Forge() forge.Forge

Forge returns the underlying forge (for replies and submission).

func (*PRSource) GeneralComments

func (s *PRSource) GeneralComments(ctx context.Context) ([]forge.Comment, error)

GeneralComments fetches the PR's conversation-level comments.

func (*PRSource) HeadOID

func (s *PRSource) HeadOID(context.Context) string

HeadOID returns the PR head commit captured at construction. It is recorded in the draft so that, on the next session, a changed head triggers comment relocation against the new diff.

func (*PRSource) Key

func (s *PRSource) Key() string

Key seeds the draft store's filename, so it must be stable across sessions and filesystem-safe: the host is made explicit (an empty host means github.com) and any "/" in the owner (GitLab nested groups) is flattened.

func (*PRSource) PullRequest

func (s *PRSource) PullRequest() *forge.PullRequest

PullRequest returns the metadata fetched at construction; the TUI uses it for the PR-info overlay (title, description, author) without another network round-trip.

func (*PRSource) RawPatch

func (s *PRSource) RawPatch(ctx context.Context) ([]byte, error)

RawPatch returns the host's canonical diff verbatim, enabling exchange export with the exact bytes review positions are anchored to.

func (*PRSource) Ref

func (s *PRSource) Ref() forge.PullRequestRef

Ref returns the pull-request reference; the TUI's PR context passes it back on every forge call (threads, replies, review submission).

func (*PRSource) Threads

func (s *PRSource) Threads(ctx context.Context) ([]forge.Thread, error)

Threads fetches existing review threads for the PR.

func (*PRSource) Title

func (s *PRSource) Title() string

Title is the string shown in the title bar: "owner/repo#N: <PR title>", so the reviewer can tell at a glance which PR the session is about.

type RawPatcher

type RawPatcher interface {
	RawPatch(ctx context.Context) ([]byte, error)
}

RawPatcher is implemented by sources that can hand out the raw unified patch they were built from. The review-exchange export needs the literal patch text (parsed FileDiffs cannot be serialised back verbatim), so exchange export is available exactly where this interface is.

type ReviewSource

type ReviewSource interface {
	// Files parses and returns the diff for this source.
	Files(ctx context.Context) ([]diff.FileDiff, error)
	// Title is a short human description shown in the status bar.
	Title() string
	// Key is a stable identifier used to namespace persisted drafts.
	Key() string
	// HeadOID returns the head commit the source was captured against, or "".
	HeadOID(ctx context.Context) string
}

ReviewSource is a resolved, ready-to-load set of changes under review.

func Resolve

func Resolve(ctx context.Context, opts Options) (ReviewSource, error)

Resolve inspects opts and returns the appropriate ReviewSource.