forge_primitives/

git_diff.rs

//! Git diff snapshot types.
//!
//! Type-only - the scanner that produces these lives in
//! `forge_agent::env::git_diff::scan`. The four shapes cross every
//! forge-* crate boundary (agent produces, workspace mediates, a view
//! renders), so they live in primitives per the crate placement guide.
//! Sibling git types (`GitBranch`, `GitPrInfo`, `GitIssueRef`) live in
//! [`crate::git`].

use crate::git::{GitBranch, GitIssueRef, GitPrInfo};
use serde::{Deserialize, Serialize};

/// Per-layer scan state. Replaces the earlier parallel-bool encoding
/// (`Option<T>` paired with a `*_scan_ok: bool`) so the three legal
/// states are unrepresentable as illegal combinations.
///
/// - `Clean` - the layer ran cleanly with nothing to report (clean
///   worktree, branch at merge-base, on the default branch, detached
///   HEAD with no base, or not in a repo at all).
/// - `Populated(T)` - the layer ran and produced data the renderer
///   should show.
/// - `ScanFailed` - the underlying subprocess crashed, timed out, or
///   exceeded the stdout cap. The renderer surfaces a "(scan failed)"
///   stub so the user sees the failure rather than a silent
///   clean-tree render.
///
/// Serialised as the socket's record shape for the bounded content read,
/// whose layers answer in the same three states the scanner's do.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum LayerState<T> {
    Clean,
    Populated(T),
    ScanFailed,
}

impl<T> LayerState<T> {
    /// True when the layer has data the renderer should show.
    pub fn is_populated(&self) -> bool {
        matches!(self, LayerState::Populated(_))
    }
}

/// Whether a scan may reach the network for its PR block.
///
/// The lookup is one `gh api` call: a full TLS + API round trip measured at
/// 0.9 s on this machine, and it sat on the record a client waits for. A read
/// somebody is waiting on serves the PR it already holds and leaves the
/// refresh to the seat's own loop, which nobody waits on.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum PrRefresh {
    /// A cache past its window is looked up again.
    Fetch,
    /// A cache past its window is served as it stands for the branch and sha
    /// it belongs to - anything else answers nothing - and is never looked up.
    ServeCached,
}

/// Three-state classification of the scan's repo gate. Replaces the
/// earlier `in_repo` + `scanner_ok` bool pair so the illegal
/// "in a repo but the scanner failed" combination is unrepresentable.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum RepoGate {
    /// `git rev-parse` confirmed the cwd is inside a work tree.
    InRepo,
    /// The cwd is not inside a work tree, and the scanner's
    /// repo-existence probe found no `.git` to contradict that.
    NotARepo,
    /// The rev-parse gate yielded no branch and the repo-existence probe
    /// did not rule a repo out: a timeout or oversize read, a checkout
    /// git refuses, or a git that would not run. The renderer surfaces a
    /// "scanner unhealthy" banner distinct from a legitimate non-repo
    /// cwd.
    ScannerFailed,
}

/// Snapshot of one project's git state, suitable for rendering in
/// the Inspector pane's GIT section. Branch info is folded in here
/// so a single polled scan covers everything the renderer needs.
///
/// `worktree` and `branch_ahead` are independent: a worker on a
/// topic branch with uncommitted edits surfaces both layers, while
/// the lead on `main` with a clean tree surfaces neither.
///
/// `repo_gate` makes the repo-vs-scanner-failure states exclusive at
/// the type level. The remaining cross-field invariant the scanner
/// upholds: `branch_ahead` is only `Populated` when `default_branch`
/// resolved (the renderer's tuple-match relies on it), and the layer
/// states / `pr` / `closes` / `default_branch` stay empty unless
/// `repo_gate` is [`RepoGate::InRepo`].
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct GitDiffSnapshot {
    /// Current branch (Named / Detached / NoRepo / Unknown).
    pub branch: GitBranch,
    /// HEAD's newest pushed ancestor at scan time: the first sha of
    /// HEAD's first-parent history the remote already tracks. `None`
    /// when nothing is pushed, the walk failed, or the PR lookup was
    /// skipped (default branch / detached). The PR cache key rides on
    /// this rather than the branch name, so a worktree whose local
    /// branch differs from the PR's head ref still resolves its PR.
    pub pushed_sha: Option<String>,
    /// Wall-clock stamp of the last PR-lookup attempt, `Some` even
    /// when the attempt found nothing or failed - the refetch timer
    /// must rate-limit failed lookups too or a persistent `gh`
    /// failure hammers every 10 s scan. `None` when the PR side never
    /// ran (non-repo, default branch, detached).
    pub pr_fetched_at: Option<std::time::SystemTime>,
    /// Resolved default branch (e.g. `main`, `master`), if known.
    /// `None` when `origin/HEAD` is missing AND neither `main` nor
    /// `master` exists as a local ref.
    pub default_branch: Option<String>,
    /// Repo gate: in-repo, not-a-repo, or scanner-failed. Replaces the
    /// old `in_repo` + `scanner_ok` bool pair so the illegal
    /// "in a repo but the scanner failed" combination can't be built.
    pub repo_gate: RepoGate,
    /// Layer 1: uncommitted edits vs HEAD.
    pub worktree: LayerState<GitDiffStats>,
    /// Layer 2: commits the current branch has ahead of
    /// `default_branch`. The commit count is exposed separately
    /// from the file stats because `--numstat` collapses every
    /// commit into a single stat block; the count tells the
    /// renderer "this many commits produced these stats".
    pub branch_ahead: LayerState<GitBranchAhead>,
    /// Open pull request containing the current branch's newest
    /// pushed ancestor, if one exists. Only populated for `Named`
    /// non-default branches; `None` otherwise. Cached across scans
    /// while the branch name and pushed sha both hold and the fetch
    /// is less than 5 minutes old (see the scanner's `prev`
    /// parameter).
    pub pr: Option<GitPrInfo>,
    /// Issues the open PR closes (from GitHub's
    /// `closingIssuesReferences`). Empty when there's no PR or the
    /// PR doesn't reference any issues. Cached alongside `pr`.
    pub closes: Vec<GitIssueRef>,
}

/// Per-file numstat plus aggregate totals for one diff layer.
/// Shared between [`GitDiffSnapshot::worktree`] (layer 1, HEAD vs
/// workdir) and [`GitBranchAhead::stats`] (layer 2, default vs
/// branch tip).
#[derive(Debug, Clone, PartialEq, Eq, Default, serde::Serialize, serde::Deserialize)]
pub struct GitDiffStats {
    pub files: Vec<GitDiffFile>,
    pub total_files: usize,
    pub total_added: u32,
    pub total_removed: u32,
}

/// How current the base a drawn branch diff was measured against is.
///
/// The base is a remote-tracking ref (`origin/main`), and how far the remote
/// has moved past it is only knowable over the network. The read that draws
/// the diff refreshes it first, so a diff is never shown from a stale base
/// without saying so.
#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum BaseState {
    /// A local base with nothing it could lag behind: no `origin` remote, and
    /// no upstream of its own. A local base beside an `origin`, or one whose
    /// branch tracks some remote (`main@{upstream}`), is `Unverified` instead
    /// - it can be arbitrarily behind one nobody fetched.
    Local,
    /// The base was fetched and matches the remote.
    Current,
    /// The base could not be fetched, and the remote has `behind` commits it
    /// lacks.
    Behind { behind: u32 },
    /// The base could not be fetched and could not be checked against the
    /// remote either.
    Unverified,
}

/// Layer 2 payload: how far the branch is ahead of the default
/// branch, alongside the corresponding numstat.
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct GitBranchAhead {
    /// Number of commits between the merge-base with `default_branch`
    /// and the branch tip. The renderer surfaces this so the user
    /// can see "N commits ahead" without inferring it from the file
    /// list.
    pub commit_count: u32,
    /// File-level numstat for the same commit range.
    pub stats: GitDiffStats,
    /// The chain itself, newest first, capped at the scan's own bound:
    /// the count above says how many there are, these say what they are.
    #[serde(default)]
    pub commits: Vec<crate::git::GitCommit>,
}

/// One file's diff stats. `added` / `removed` are git's `--numstat`
/// line counts; binary files (which numstat reports as `-`) are
/// dropped by the parser rather than appearing here.
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct GitDiffFile {
    pub path: String,
    pub added: u32,
    pub removed: u32,
    /// How git classified the change. `--numstat` carries no code, so
    /// the scan merges it in from `--name-status`; a file the merge did
    /// not reach keeps the default.
    #[serde(default)]
    pub status: crate::git::FileStatus,
}

/// The tree behind a git row's depth, bundled: what a hover over the
/// row draws beyond the branch and the count.
///
/// `None` layers read as nothing to state - a clean tree, an unscanned
/// one - the same way [`LayerState`] means it; the row above still
/// carries the gate that says which.
#[derive(Debug, Clone, Default, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct GitWorkView {
    /// The branch this tree is measured against, when it resolved; the
    /// row names it (`3 commits vs main`) and hides itself when this
    /// tree IS it.
    pub default_branch: Option<String>,
    /// The uncommitted files, with marks and counts.
    pub worktree: Option<GitDiffStats>,
    /// The branch's chain ahead of its default.
    pub ahead: Option<GitBranchAhead>,
    /// What the seat's last watch refresh found for the base the chain is
    /// measured against, `None` until one has run. **A base can move without
    /// the count or the chain moving**: the range is `base..HEAD`, so an
    /// upstream advance the branch does not contain leaves the branch's own
    /// commits exactly as they were, and this is the only field that says so.
    #[serde(default)]
    pub base: Option<BaseState>,
    /// Git's own words for a base refresh that could not run, beside the
    /// state it left. **The reason rides the row** so a page that hears a
    /// failed check learns why from the frame rather than only from its next
    /// read, and so a failure with new words is news even when the state is
    /// the one already drawn. Absent on records from an older server.
    #[serde(default)]
    pub base_error: Option<String>,
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn layer_state_is_populated_returns_true_only_for_populated() {
        let clean: LayerState<u32> = LayerState::Clean;
        let populated: LayerState<u32> = LayerState::Populated(42);
        let failed: LayerState<u32> = LayerState::ScanFailed;
        assert!(!clean.is_populated());
        assert!(populated.is_populated());
        assert!(!failed.is_populated());
    }

    /// **The four states' wire spellings, as the client parser reads them.**
    /// serde's external tagging nests a struct variant's fields under the
    /// variant name (`{"behind": {"behind": 3}}`), which a parser written
    /// against a flat object silently reads as unknown - the stale-base label
    /// then never draws. The client's `diffFrom` test feeds these same shapes.
    #[test]
    fn the_base_states_wire_spellings() {
        assert_eq!(
            serde_json::to_value(BaseState::Local).expect("encodes"),
            serde_json::json!("local")
        );
        assert_eq!(
            serde_json::to_value(BaseState::Current).expect("encodes"),
            serde_json::json!("current"),
        );
        assert_eq!(
            serde_json::to_value(BaseState::Unverified).expect("encodes"),
            serde_json::json!("unverified"),
        );
        assert_eq!(
            serde_json::to_value(BaseState::Behind { behind: 3 }).expect("encodes"),
            serde_json::json!({"behind": {"behind": 3}}),
            "a struct variant nests its fields under the variant name",
        );
    }
}