forge_agent/env/git_diff/

hunks.rs

//! Per-file hunk scanner for the `/diff` overlay.
//!
//! Extends [`super`]'s numstat-based snapshot with full unified-diff
//! content needed to render the GitHub-style diff viewer. Runs up to
//! three subprocess calls per scan:
//!
//! 1. `git diff <target> --name-status` - file list with M/A/D/R
//!    classification.
//! 2. `git diff <target> --no-ext-diff` - full unified-diff body.
//!    The flag defeats user-configured difftastic / delta so the
//!    parser sees standard unified-diff format.
//! 3. `git ls-files --others --exclude-standard` - untracked files
//!    (only when `target == "HEAD"`, capped at `MAX_UNTRACKED_FILES`
//!    entries, each read up to `MAX_UNTRACKED_FILE_SIZE` bytes).
//!
//! Single-shot - never polled. The `/diff` overlay calls [`scan`] on
//! open and renders the resulting `Vec<FileHunks>` for the duration
//! of the view; refreshing mid-review would invalidate pending
//! comments anchored to specific lines.
//!
//! Always returns a [`ScanOutcome`] - `files` may be empty on a
//! genuinely clean tree OR when one of the subprocess calls hit
//! Failed / Oversize. The `scanner_ok` flag distinguishes the two
//! so a downstream renderer can show "scan failed" rather than
//! miscategorising the empty result as "no changes."

use std::path::Path;
use std::time::Duration;

use serde::{Deserialize, Serialize};

use super::{COMMAND_TIMEOUT, GitOutput, run_git_within};

/// Skip the untracked-file scan entirely when the working tree
/// has more than this many untracked entries. A fresh-repo state
/// with hundreds of untracked files would otherwise dump everything
/// into the overlay. The Inspector GIT section is unaffected; only
/// the `/diff` overlay's untracked surface is suppressed (no `U`
/// rows render in the rail when the cap is exceeded).
///
/// Public so a view can surface the cap in the
/// "+N untracked suppressed (cap M)" notice - the number lives
/// here as the source of truth.
pub const MAX_UNTRACKED_FILES: usize = 4;

/// Per-file size ceiling for untracked content surfaced in the diff
/// body. Above this we keep the rail entry but skip reading bytes.
pub(crate) const MAX_UNTRACKED_FILE_SIZE: u64 = 1024;

/// One file's worth of hunks, ordered as `git diff` emitted them.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct FileHunks {
    pub path: String,
    pub status: FileStatus,
    pub hunks: Vec<Hunk>,
    /// The full-context fetch tripped the oversize cap, so `hunks` is a
    /// bounded fallback (or empty) rather than the pinned snapshot the
    /// overlay expands from. The overlay renders it normally but disables
    /// context expansion for this file.
    pub oversize: bool,
}

/// File-level change classification from `git diff --name-status`,
/// plus a synthetic [`Untracked`](FileStatus::Untracked) variant for
/// files surfaced from `git ls-files --others`.
///
/// Covers every status code git emits: M/A/D/R/C/T/U. Unknown
/// codes (`X` - internal error indicator, `B` - broken pairing)
/// fire a WARN log and skip the entry rather than collapsing to
/// `Modified`; legitimate user-visible types stay distinct.
///
/// The definition moved to primitives because it crosses to views
/// now; this re-export keeps every existing reader.
pub use forge_primitives::git::FileStatus;

/// A single `@@`-delimited hunk inside one file's diff. `lines`
/// preserves the original unified-diff ordering with each line
/// tagged as context, added, or removed - the renderer iterates
/// them directly to draw the `+ / - / ` markers and per-side line
/// numbers without re-classifying anything.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct Hunk {
    pub old_start: u32,
    pub old_count: u32,
    pub new_start: u32,
    pub new_count: u32,
    pub lines: Vec<DiffLine>,
}

impl Hunk {
    /// Count of lines added in this hunk (`+` markers).
    pub fn added_count(&self) -> u32 {
        u32::try_from(self.lines.iter().filter(|l| l.kind == DiffLineKind::Added).count())
            .unwrap_or(u32::MAX)
    }

    /// Count of lines removed in this hunk (`-` markers).
    pub fn removed_count(&self) -> u32 {
        u32::try_from(self.lines.iter().filter(|l| l.kind == DiffLineKind::Removed).count())
            .unwrap_or(u32::MAX)
    }
}

impl FileHunks {
    /// Total additions across all hunks in this file.
    pub fn added_count(&self) -> u32 {
        self.hunks.iter().map(Hunk::added_count).fold(0u32, u32::saturating_add)
    }

    /// Total removals across all hunks in this file.
    pub fn removed_count(&self) -> u32 {
        self.hunks.iter().map(Hunk::removed_count).fold(0u32, u32::saturating_add)
    }
}

/// Per-line classification inside a hunk.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum DiffLineKind {
    /// Line appears in both old and new - printed without a marker
    /// (or with a leading space, depending on the renderer).
    Context,
    /// Line is in the new file only - rendered with `+` marker.
    Added,
    /// Line is in the old file only - rendered with `-` marker.
    Removed,
}

/// One rendered diff line. Carries its kind, raw text (no leading
/// marker), and per-side line numbers so the renderer can show a
/// gutter without recomputing positions.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct DiffLine {
    pub kind: DiffLineKind,
    pub text: String,
    /// Line number in the old file. `None` for `Added` lines.
    pub old_line: Option<u32>,
    /// Line number in the new file. `None` for `Removed` lines.
    pub new_line: Option<u32>,
}

/// Outcome of a single scan invocation. `files` carries whatever
/// was parsed; `scanner_ok` is `false` when at least one of the
/// underlying subprocess calls hit `Failed` or `Oversize` - the
/// file list may be partial or empty, and a downstream renderer
/// should distinguish that case from a genuine clean tree so the
/// user knows whether to retry vs. accept "no changes."
///
/// `untracked_suppressed` carries the count of untracked files
/// that DIDN'T make it into `files` because the working tree had
/// more than `MAX_UNTRACKED_FILES` untracked entries. The renderer
/// surfaces this so the user knows the rail is incomplete; without
/// it, a fresh-repo state with 5+ untracked files looks identical
/// to a tree with zero.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ScanOutcome {
    pub files: Vec<FileHunks>,
    pub scanner_ok: bool,
    pub untracked_suppressed: usize,
}

/// One commit in the review stepper's ordered list. `sha` is the full
/// hash (used to scope the per-commit diff), `short_sha` the abbreviated
/// form for display, `subject` the commit's first line. `body` is the
/// message beyond the subject, filled lazily by [`scan_commit_body`] when
/// the stepper first lands on the commit (empty until then, and for a
/// subject-only commit).
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct CommitMeta {
    pub sha: String,
    pub short_sha: String,
    pub subject: String,
    pub body: String,
}

/// Git's canonical empty-tree object (SHA-1). Diffing a parentless
/// root commit against it yields the commit's full contents as
/// additions - `<sha>^` doesn't resolve for a root, so this stands in
/// for the non-existent parent.
const EMPTY_TREE_SHA: &str = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";

/// Field separator for the `git log` format below - the ASCII unit
/// separator, which never appears in a commit subject.
const LOG_FIELD_SEP: char = '\u{1f}';

/// List the commits in `<target>..HEAD`, oldest first, for the diff
/// overlay's commit stepper. Empty when the range has no commits
/// (dirty-tree-only review, `/diff HEAD`, or `target` unresolvable).
pub async fn scan_commits(cwd: &Path, target: &str) -> Vec<CommitMeta> {
    scan_commits_within(cwd, target, COMMAND_TIMEOUT).await
}

/// [`scan_commits`] with its command budget spelled; see the module's
/// [`scan_within`].
pub async fn scan_commits_within(cwd: &Path, target: &str, budget: Duration) -> Vec<CommitMeta> {
    let range = format!("{target}..HEAD");
    let raw =
        match run_git_within(cwd, &["log", "--reverse", "--format=%H%x1f%h%x1f%s", &range], budget)
            .await
        {
            GitOutput::Ok(s) => s,
            GitOutput::Empty | GitOutput::Failed | GitOutput::Oversize => return Vec::new(),
        };
    raw.lines()
        .filter_map(|line| {
            let mut parts = line.split(LOG_FIELD_SEP);
            let sha = parts.next()?.to_owned();
            let short_sha = parts.next()?.to_owned();
            // Subject may be empty (a commit with a blank message); the
            // sha/short_sha are the identifying fields, so only bail
            // when those are missing.
            let subject = parts.next().unwrap_or_default().to_owned();
            if sha.is_empty() {
                return None;
            }
            // Body stays empty here; a multi-line body would break this
            // line-per-commit parse. It is fetched lazily per commit.
            Some(CommitMeta { sha, short_sha, subject, body: String::new() })
        })
        .collect()
}

/// Scan a single commit's own diff (`<sha>^..<sha>`, or against the
/// empty tree for a parentless root commit) into per-file hunks. Never
/// surfaces untracked files - a commit's diff is closed over its own
/// changes.
pub async fn scan_commit(cwd: &Path, sha: &str) -> ScanOutcome {
    scan_commit_within(cwd, sha, COMMAND_TIMEOUT).await
}

/// [`scan_commit`] with its command budget spelled; see the module's
/// [`scan_within`].
pub async fn scan_commit_within(cwd: &Path, sha: &str, budget: Duration) -> ScanOutcome {
    let Some(ref_spec) = commit_ref_spec(cwd, sha, budget).await else {
        // Nothing a revision could be built from: the scan reports its own
        // failure rather than a diff of some other tree.
        return ScanOutcome { files: Vec::new(), scanner_ok: false, untracked_suppressed: 0 };
    };
    scan_with_ref_spec(cwd, &ref_spec, budget).await
}

/// Resolve the two-endpoint `git diff` range for one commit, or `None` when
/// `sha` names no commit git can read.
///
/// **The sha is resolved first, because it is a revision off a wire**: the
/// range this builds is handed to `git diff` as one argv, and an
/// option-shaped sha would be read as an option of the diff's own - the same
/// gate [`super::file::resolve_commit`] applies to the file read, and the
/// same reason. Resolved, it is a commit id, which cannot be a flag.
///
/// Uses `git rev-list --parents -n 1 <id>` (always exits 0, so no spurious
/// non-zero-exit WARN) to detect a parent: `<id> <parent…>` means a normal
/// commit (`<id>^..<id>`, first-parent for a merge), a lone `<id>` means a
/// root commit (diff against the empty tree).
pub(crate) async fn commit_ref_spec(cwd: &Path, sha: &str, budget: Duration) -> Option<String> {
    let commit = super::file::resolve_commit(cwd, sha, budget).await?;
    match run_git_within(cwd, &["rev-list", "--parents", "-n", "1", &commit], budget).await {
        GitOutput::Ok(s) if s.split_whitespace().count() > 1 => {
            Some(format!("{commit}^..{commit}"))
        }
        GitOutput::Ok(_) => Some(format!("{EMPTY_TREE_SHA}..{commit}")),
        // Best-effort on any anomaly: the normal-commit spec, whose
        // scan just reports scanner failure rather than panicking.
        GitOutput::Empty | GitOutput::Failed | GitOutput::Oversize => {
            Some(format!("{commit}^..{commit}"))
        }
    }
}

/// Fetch a commit's message body - everything after the subject line,
/// with the trailing newline trimmed. Empty for a subject-only commit.
/// Kept out of [`scan_commits`] because a multi-line body would break
/// its line-per-commit `git log` parse; the stepper fetches it lazily
/// per commit alongside the hunks.
pub async fn scan_commit_body(cwd: &Path, sha: &str) -> String {
    scan_commit_body_within(cwd, sha, COMMAND_TIMEOUT).await
}

/// [`scan_commit_body`] with its command budget spelled; see the module's
/// [`scan_within`].
///
/// The sha is resolved first, the same gate the commit scan's own ref spec
/// takes: it is a revision off a wire, and `git show` would read an
/// option-shaped one as its own option. A sha that names no commit reads as
/// no body.
pub async fn scan_commit_body_within(cwd: &Path, sha: &str, budget: Duration) -> String {
    let Some(commit) = super::file::resolve_commit(cwd, sha, budget).await else {
        return String::new();
    };
    match run_git_within(cwd, &["show", "-s", "--format=%b", &commit], budget).await {
        GitOutput::Ok(s) => s.trim_end().to_owned(),
        GitOutput::Empty | GitOutput::Failed | GitOutput::Oversize => String::new(),
    }
}

/// Max in-flight `git diff -- <path>` subprocesses during a scan.
/// macOS's default soft open-file limit is ~256 and every git child
/// holds stdin/stdout/stderr pipes plus a handful of git internals
/// (~6-10 FDs); firing all N at once on a 100+ file refactor
/// branch trips `EMFILE`. 16 keeps total well under the FD ceiling
/// while still giving a 16× speedup over a sequential loop.
pub(super) const MAX_INFLIGHT_FETCHES: usize = 16;

/// Unified-diff context radius the per-file fetch pins at open: large
/// enough to cover realistic inter-hunk gaps (so expanding reveals hidden
/// lines from the cached snapshot without a live re-fetch), but bounded
/// so a big file with a small change doesn't emit its whole content and
/// trip the oversize cap. A gap wider than this reveals up to the cap.
const PINNED_CONTEXT_LINES: u32 = 2_000;

/// Fallback context radius for a file whose pinned full-context fetch was
/// still oversize - a bounded diff that renders normally (expansion is
/// disabled for it). git's own default is 3.
const FALLBACK_CONTEXT_LINES: u32 = 3;

/// Top-level scanner entry. `target` is a plain ref / SHA / `"HEAD"`
/// (not a `..`/`...` range - the helper `diff_ref_spec` picks the
/// shape for us). `"HEAD"` runs a two-dot working-tree diff
/// (uncommitted only); any other ref runs `git diff <target>...HEAD`,
/// the three-dot form that surfaces what THIS branch contributed
/// vs the merge-base with `target`. Three-dot matches the Inspector
/// GIT panel's branch-ahead scanner (which composes
/// `format!("{default}...HEAD")` via the same helper), so the panel
/// and overlay agree on what's diffable even after a squash-merge
/// where two-dot `git diff main HEAD` would be empty.
///
/// Returns a [`ScanOutcome`] - `files` carries one [`FileHunks`]
/// per changed file in the order `git diff --name-status` reports
/// them (untracked files when `target == "HEAD"` come at the end
/// as [`FileStatus::Untracked`]), `scanner_ok` is `false` when any
/// subprocess hit `Failed`/`Oversize` so the caller can surface
/// "scan failed, check logs" rather than miscategorising the empty
/// result as "no changes."
pub async fn scan(cwd: &Path, target: &str) -> ScanOutcome {
    scan_within(cwd, target, COMMAND_TIMEOUT).await
}

/// [`scan`] with its command budget spelled: the shell gives each child
/// this reader spawns the 10 s `COMMAND_TIMEOUT`, and a test gives them one
/// of its own. **The budget is a bound on the machine, not on the read**: it
/// is spent starting each child, so a loaded machine can hold a child's
/// first output past the shell's 10 s and blank a file's hunk section.
pub async fn scan_within(cwd: &Path, target: &str, budget: Duration) -> ScanOutcome {
    let ref_spec = diff_ref_spec(target);
    let mut outcome = scan_with_ref_spec(cwd, &ref_spec, budget).await;

    // Untracked only when the caller is asking for working-tree
    // semantics. `/diff main` from a feature branch already includes
    // committed-since-main + uncommitted via the ref-vs-worktree
    // compare; untracked files don't belong to that comparison.
    if target == "HEAD" {
        let (untracked, untracked_ok, suppressed) = scan_untracked(cwd, budget).await;
        outcome.files.extend(untracked);
        outcome.scanner_ok = outcome.scanner_ok && untracked_ok;
        outcome.untracked_suppressed = suppressed;
    }

    outcome
}

/// Scan a pre-resolved diff range into per-file hunks. `ref_spec` is
/// already the exact shape git receives - `HEAD`, `main...HEAD`,
/// `<sha>^..<sha>`, an empty-tree range, etc. Never surfaces untracked
/// files, so `untracked_suppressed` is always 0.
async fn scan_with_ref_spec(cwd: &Path, ref_spec: &str, budget: Duration) -> ScanOutcome {
    let mut scanner_ok = true;
    let name_status = match run_git_within(cwd, &["diff", ref_spec, "--name-status"], budget).await
    {
        GitOutput::Ok(s) => s,
        GitOutput::Empty => String::new(),
        GitOutput::Failed | GitOutput::Oversize => {
            scanner_ok = false;
            String::new()
        }
    };
    let mut files = parse_name_status(&name_status);

    if !files.is_empty() {
        // Per-file concurrent fetch with bounded concurrency. Each
        // `git diff <ref_spec> --no-ext-diff -- <path>` subprocess
        // holds stdio pipes for its lifetime; firing all N
        // simultaneously via `futures::future::join_all` blows the
        // process's open-file limit on real refactor branches
        // (~130 files × ~3-10 FDs each easily exceeds the macOS
        // ~256 soft cap). `buffer_unordered(MAX_INFLIGHT_FETCHES)`
        // caps in-flight subprocesses to a safe number while still
        // giving ~MAX_INFLIGHT_FETCHES× speedup over a sequential
        // loop. Order doesn't matter because we zip back into
        // `files` by index, captured as the future's first item.
        use futures::StreamExt;
        // Clone the path list off `files` so the immutable borrow
        // drops before the stream runs - we mutate `files[idx]`
        // inside the consume loop.
        let paths: Vec<String> = files.iter().map(|f| f.path.clone()).collect();
        let ref_spec_for_fetch = ref_spec.to_owned();
        let mut stream = futures::stream::iter(paths.into_iter().enumerate().map(|(idx, path)| {
            let ref_spec = ref_spec_for_fetch.clone();
            async move { (idx, fetch_file_hunks(cwd, &ref_spec, &path, budget).await) }
        }))
        .buffer_unordered(MAX_INFLIGHT_FETCHES);
        while let Some((idx, result)) = stream.next().await {
            match result {
                FileScanOutcome::Ok { hunks, oversize } => {
                    files[idx].hunks = hunks;
                    files[idx].oversize = oversize;
                }
                // An oversize file is reported as Ok (with the flag set),
                // so only a genuine subprocess crash flips scanner_ok - one
                // huge file no longer blanks the whole scope.
                FileScanOutcome::SubprocessFailed => {
                    scanner_ok = false;
                }
            }
        }
    }

    ScanOutcome { files, scanner_ok, untracked_suppressed: 0 }
}

/// Per-file fetch result. `SubprocessFailed` propagates back to `scan`
/// so a single-file crash flips `scanner_ok` without poisoning the rest.
/// `oversize` marks a file whose full-context fetch tripped the size cap
/// and fell back to a bounded diff (or empty) - it renders but doesn't
/// expand, and crucially does NOT flip the scope-wide `scanner_ok`.
enum FileScanOutcome {
    Ok { hunks: Vec<Hunk>, oversize: bool },
    SubprocessFailed,
}

/// Translate a caller-supplied diff `target` into the git ref-spec
/// the underlying subprocess receives.
///
/// - `HEAD` -> `HEAD` (two-dot semantics: working tree vs HEAD,
///   which is what the user means by "uncommitted edits").
/// - Anything else (branch name, SHA) -> `<target>...HEAD`
///   (three-dot semantics: diff from the merge-base of `target` and
///   `HEAD` to `HEAD`, i.e. "what did THIS branch contribute").
///
/// Why the asymmetry: after a squash-merge of the branch into the
/// target, two-dot `git diff main HEAD` is empty (content already in
/// main with a different SHA) while three-dot `git diff main...HEAD`
/// still surfaces the branch's contributions vs the merge-base. The
/// Inspector GIT panel uses three-dot via
/// `forge_agent::env::git_diff::scan`'s `format!("{default}...HEAD")`
/// at the branch-ahead layer; this helper keeps the overlay scanner
/// in sync so the panel + overlay never disagree on what's diffable.
fn diff_ref_spec(target: &str) -> String {
    if target == "HEAD" { "HEAD".to_owned() } else { format!("{target}...HEAD") }
}

/// One file-diff subprocess result before it's folded into a
/// [`FileScanOutcome`]: parsed hunks, the size cap, or a crash.
enum DiffFetch {
    Ok(Vec<Hunk>),
    Oversize,
    Failed,
}

/// Fetch + parse one file's diff at a given context radius. Binary /
/// submodule entries and empty diffs return `Ok(vec![])`. Splits the
/// oversize cap from a genuine subprocess crash so the caller can retry
/// oversize at a smaller context instead of failing the whole scan.
async fn run_file_diff(
    cwd: &Path,
    ref_spec: &str,
    path: &str,
    context: u32,
    budget: Duration,
) -> DiffFetch {
    let flag = format!("-U{context}");
    let section =
        match run_git_within(cwd, &["diff", ref_spec, "--no-ext-diff", &flag, "--", path], budget)
            .await
        {
            GitOutput::Ok(s) => s,
            GitOutput::Empty => return DiffFetch::Ok(Vec::new()),
            GitOutput::Oversize => return DiffFetch::Oversize,
            GitOutput::Failed => return DiffFetch::Failed,
        };
    let hunks = parse_hunks(&section);
    if hunks.is_empty() && contains_hunk_marker(&section) {
        // Parser produced zero hunks despite seeing at least one
        // `@@` marker. WARN so an operator hunting "I edited this
        // file but it shows as no-diff" has a breadcrumb. The
        // per-hunk malformed-header WARN inside parse_hunks already
        // fires too; this rollup catches the section-level case.
        tracing::warn!(
            target: crate::logging::targets::ENV_GIT,
            event_name = "git_hunks_parse_empty",
            message = "diff section had @@ markers but produced zero hunks",
            outcome = "failure",
            path = %path,
            section_bytes = section.len(),
        );
    }
    DiffFetch::Ok(hunks)
}

/// Fetch one file's hunks for the overlay, pinning at
/// [`PINNED_CONTEXT_LINES`] so the returned hunks carry enough context
/// for in-memory expansion. The `--` separator keeps a `--foo` path from
/// being read as a flag.
///
/// A file whose pinned fetch trips the oversize cap falls back to a
/// bounded [`FALLBACK_CONTEXT_LINES`] diff and is flagged `oversize` (it
/// renders but can't expand); if even that is oversize (a huge fully-
/// rewritten file) it keeps empty hunks and the flag. Either way it stays
/// `Ok`, so one big file never flips the scope-wide `scanner_ok`.
///
/// `ref_spec` is the already-resolved diff range from [`diff_ref_spec`]
/// (e.g. `HEAD`, or `main...HEAD`); callers pre-resolve it so the per-file
/// and top-level scans agree.
async fn fetch_file_hunks(
    cwd: &Path,
    ref_spec: &str,
    path: &str,
    budget: Duration,
) -> FileScanOutcome {
    match run_file_diff(cwd, ref_spec, path, PINNED_CONTEXT_LINES, budget).await {
        DiffFetch::Ok(hunks) => FileScanOutcome::Ok { hunks, oversize: false },
        DiffFetch::Failed => FileScanOutcome::SubprocessFailed,
        DiffFetch::Oversize => {
            match run_file_diff(cwd, ref_spec, path, FALLBACK_CONTEXT_LINES, budget).await {
                DiffFetch::Ok(hunks) => FileScanOutcome::Ok { hunks, oversize: true },
                DiffFetch::Oversize => FileScanOutcome::Ok { hunks: Vec::new(), oversize: true },
                DiffFetch::Failed => FileScanOutcome::SubprocessFailed,
            }
        }
    }
}

/// One `git diff --name-status` line: the classification, the new path,
/// and the old path a rename or copy names (absent for every other
/// status). The old path survives here rather than in [`FileHunks`] so
/// the content read can carry both sides of a rename while the overlay
/// keeps the one it draws.
#[derive(Debug, Clone, PartialEq, Eq)]
pub(super) struct NameStatusEntry {
    pub status: FileStatus,
    pub path: String,
    pub old_path: Option<String>,
}

/// The status a `--name-status` code's leading letter means, or `None` for
/// a code git grew that forge does not know.
pub(super) fn status_of(leading: char) -> Option<FileStatus> {
    Some(match leading {
        'M' => FileStatus::Modified,
        'A' => FileStatus::Added,
        'D' => FileStatus::Deleted,
        'R' => FileStatus::Renamed,
        'C' => FileStatus::Copied,
        'T' => FileStatus::Typechange,
        'U' => FileStatus::Unmerged,
        _ => return None,
    })
}

/// Parse `git diff --name-status` output into entries.
///
/// Status codes covered: M (modified), A (added), D (deleted),
/// R (renamed), C (copied), T (typechange - symlink/submodule),
/// U (unmerged - mid-merge-conflict). Unknown codes (X, B, or
/// anything else git might emit in future) fire a WARN log and
/// drop the entry so an operator can spot the gap.
pub(super) fn parse_name_status_entries(raw: &str) -> Vec<NameStatusEntry> {
    raw.lines()
        .filter_map(|line| {
            let mut parts = line.split('\t');
            let status_code = parts.next()?;
            // For R/C the line is "R100\told\tnew" - the new path is
            // the last tab-separated field. For plain M/A/D it's
            // "M\tpath" - also last. `next_back` is the
            // DoubleEndedIterator-aware way to grab the tail without
            // walking the whole split.
            let path = parts.next_back()?;
            let leading = status_code.chars().next()?;
            let Some(status) = status_of(leading) else {
                tracing::warn!(
                    target: crate::logging::targets::ENV_GIT,
                    event_name = "git_name_status_unknown_code",
                    message = "git diff --name-status emitted an unhandled status code; entry dropped",
                    outcome = "skipped",
                    status_code = ?leading,
                    path = %path,
                );
                return None;
            };
            // Whatever sits between the code and the new path is the
            // old path, which only a rename or copy names.
            let old_path = if matches!(leading, 'R' | 'C') {
                let rest: Vec<&str> = parts.collect();
                (!rest.is_empty()).then(|| rest.join("\t"))
            } else {
                None
            };
            Some(NameStatusEntry { status, path: path.to_owned(), old_path })
        })
        .collect()
}

/// Parse `git diff --name-status` output into a list of `FileHunks`
/// stubs. Hunks are filled in by the per-file fetch pass.
fn parse_name_status(raw: &str) -> Vec<FileHunks> {
    parse_name_status_entries(raw)
        .into_iter()
        .map(|entry| FileHunks {
            path: entry.path,
            status: entry.status,
            hunks: Vec::new(),
            oversize: false,
        })
        .collect()
}

/// True when `section` contains at least one `@@` line - used by
/// the per-file fetch path to distinguish "no body to parse"
/// (binary / submodule, no log) from "parser couldn't extract
/// hunks despite headers being present" (WARN-worthy).
fn contains_hunk_marker(section: &str) -> bool {
    section.lines().any(|line| line.starts_with("@@"))
}

/// Parse one file's diff section into individual hunks. Hunks are
/// `@@`-delimited; each line in a hunk body starts with one of
/// `-` (removed), `+` (added), ` ` (context), or `\` (newline
/// annotation, dropped).
pub(super) fn parse_hunks(section: &str) -> Vec<Hunk> {
    let lines: Vec<&str> = section.lines().collect();
    let mut hunk_starts: Vec<usize> = Vec::new();
    for (i, line) in lines.iter().enumerate() {
        if line.starts_with("@@") {
            hunk_starts.push(i);
        }
    }
    let mut hunks = Vec::with_capacity(hunk_starts.len());
    for (idx, &start) in hunk_starts.iter().enumerate() {
        let end = hunk_starts.get(idx + 1).copied().unwrap_or(lines.len());
        let header_line = lines[start];
        let Some((old_start, old_count, new_start, new_count)) = parse_hunk_header(header_line)
        else {
            // Malformed @@ header - never expected on healthy git
            // output, but if it does fire (corrupt diff, custom
            // pretty-format leaking through) the operator needs to
            // see which line broke the parse.
            let truncated = header_line.chars().take(120).collect::<String>();
            tracing::warn!(
                target: crate::logging::targets::ENV_GIT,
                event_name = "git_hunk_header_malformed",
                message = "hunk header didn't parse; hunk dropped",
                outcome = "skipped",
                header = %truncated,
            );
            continue;
        };
        let mut diff_lines = Vec::new();
        let mut old_cursor = old_start;
        let mut new_cursor = new_start;
        for line in &lines[start + 1..end] {
            if let Some(rest) = line.strip_prefix('-') {
                diff_lines.push(DiffLine {
                    kind: DiffLineKind::Removed,
                    text: rest.to_owned(),
                    old_line: Some(old_cursor),
                    new_line: None,
                });
                old_cursor = old_cursor.saturating_add(1);
            } else if let Some(rest) = line.strip_prefix('+') {
                diff_lines.push(DiffLine {
                    kind: DiffLineKind::Added,
                    text: rest.to_owned(),
                    old_line: None,
                    new_line: Some(new_cursor),
                });
                new_cursor = new_cursor.saturating_add(1);
            } else if let Some(rest) = line.strip_prefix(' ') {
                diff_lines.push(DiffLine {
                    kind: DiffLineKind::Context,
                    text: rest.to_owned(),
                    old_line: Some(old_cursor),
                    new_line: Some(new_cursor),
                });
                old_cursor = old_cursor.saturating_add(1);
                new_cursor = new_cursor.saturating_add(1);
            } else if line.starts_with('\\') {
                // `\ No newline at end of file` - legitimate diff
                // marker, intentionally dropped.
            } else if !line.is_empty() {
                // Hunk-body line with an unexpected leading byte.
                // Healthy unified-diff output never produces this;
                // if it fires we want a breadcrumb (custom pretty-
                // format leakage, corruption, encoding mishap).
                let truncated: String = line.chars().take(120).collect();
                tracing::warn!(
                    target: crate::logging::targets::ENV_GIT,
                    event_name = "git_hunk_body_stray_line",
                    message = "hunk body line doesn't start with -/+/ /\\; line dropped",
                    outcome = "skipped",
                    line = %truncated,
                );
            }
            // Truly empty lines fall through silently - they
            // bracket the final hunk in some `git diff` outputs.
        }
        hunks.push(Hunk { old_start, old_count, new_start, new_count, lines: diff_lines });
    }
    hunks
}

/// Parse `@@ -OLD_START[,OLD_COUNT] +NEW_START[,NEW_COUNT] @@`.
/// Missing counts default to 1 per the unified-diff spec. Returns
/// `None` on malformed headers (caller skips the hunk).
fn parse_hunk_header(line: &str) -> Option<(u32, u32, u32, u32)> {
    let rest = line.strip_prefix("@@")?;
    let payload = rest.split("@@").next()?.trim();
    let mut parts = payload.split_whitespace();
    let old_part = parts.next()?.strip_prefix('-')?;
    let new_part = parts.next()?.strip_prefix('+')?;
    let (old_start, old_count) = parse_pair(old_part)?;
    let (new_start, new_count) = parse_pair(new_part)?;
    Some((old_start, old_count, new_start, new_count))
}

fn parse_pair(s: &str) -> Option<(u32, u32)> {
    if let Some((a, b)) = s.split_once(',') {
        Some((a.parse().ok()?, b.parse().ok()?))
    } else {
        Some((s.parse().ok()?, 1))
    }
}

/// Read untracked files from `git ls-files --others
/// --exclude-standard` and synthesise a [`FileHunks`] for each one
/// (status [`Untracked`](FileStatus::Untracked), single all-added
/// hunk). Caps total count at `MAX_UNTRACKED_FILES` - when the
/// working tree has more untracked entries than that, returns an
/// empty `Vec` so a fresh-repo state doesn't dump hundreds of files
/// into the overlay.
///
/// Returns `(files, ok, suppressed)`:
/// - `ok = false` only when the underlying `ls-files` subprocess
///   hit `Failed` / `Oversize`. The cap-exceeded path keeps
///   `ok = true` because git ran fine.
/// - `suppressed` is the count of untracked files that didn't make
///   it into `files` due to `MAX_UNTRACKED_FILES`. Zero when the
///   tree was under the cap (or empty); positive when the cap
///   kicked in so the renderer can surface the truncation count.
async fn scan_untracked(cwd: &Path, budget: Duration) -> (Vec<FileHunks>, bool, usize) {
    let raw =
        match run_git_within(cwd, &["ls-files", "--others", "--exclude-standard"], budget).await {
            GitOutput::Ok(s) => s,
            GitOutput::Empty => String::new(),
            GitOutput::Failed | GitOutput::Oversize => return (Vec::new(), false, 0),
        };
    let untracked: Vec<&str> = raw.lines().filter(|l| !l.is_empty()).collect();
    if untracked.len() > MAX_UNTRACKED_FILES {
        let suppressed = untracked.len();
        return (Vec::new(), true, suppressed);
    }
    let mut out = Vec::with_capacity(untracked.len());
    for path in untracked {
        let file_path = cwd.join(path);
        let hunks = match tokio::fs::metadata(&file_path).await {
            Ok(meta) if meta.is_file() && meta.len() <= MAX_UNTRACKED_FILE_SIZE => {
                match tokio::fs::read_to_string(&file_path).await {
                    Ok(content) => {
                        let raw_lines: Vec<String> = content.lines().map(str::to_owned).collect();
                        let new_count = u32::try_from(raw_lines.len()).unwrap_or(u32::MAX);
                        let diff_lines: Vec<DiffLine> = raw_lines
                            .into_iter()
                            .enumerate()
                            .map(|(i, text)| DiffLine {
                                kind: DiffLineKind::Added,
                                text,
                                old_line: None,
                                new_line: u32::try_from(i + 1).ok(),
                            })
                            .collect();
                        vec![Hunk {
                            old_start: 0,
                            old_count: 0,
                            new_start: 1,
                            new_count,
                            lines: diff_lines,
                        }]
                    }
                    Err(err) => {
                        // File showed up in `ls-files --others` and
                        // its metadata read OK, but the content
                        // read failed (permissions flipped between
                        // calls, broken symlink target, decoding
                        // error). Keep the rail entry but log so
                        // an operator can correlate "U row with no
                        // content" to the IO error.
                        tracing::warn!(
                            target: crate::logging::targets::ENV_GIT,
                            event_name = "untracked_read_failed",
                            message = "untracked file content read failed; rail entry kept with empty hunks",
                            outcome = "failure",
                            path = %file_path.display(),
                            error = %err,
                        );
                        Vec::new()
                    }
                }
            }
            Ok(meta) if !meta.is_file() => {
                // ls-files --others normally returns regular files
                // only, but submodules / sockets / fifos can sneak
                // in on exotic setups. Log so an operator hunting
                // "why is this file showing as untracked-empty"
                // has a breadcrumb - the rail row stays but its
                // body is unviewable.
                tracing::warn!(
                    target: crate::logging::targets::ENV_GIT,
                    event_name = "untracked_non_regular",
                    message = "untracked entry is not a regular file; rail entry kept with empty hunks",
                    outcome = "skipped",
                    path = %file_path.display(),
                );
                Vec::new()
            }
            Ok(meta) => {
                // File exists but exceeds MAX_UNTRACKED_FILE_SIZE.
                // Documented cap behaviour; the WARN gives an
                // operator something to grep when a specific file
                // doesn't appear with its content.
                tracing::warn!(
                    target: crate::logging::targets::ENV_GIT,
                    event_name = "untracked_oversize",
                    message = "untracked file exceeded size cap; rail entry kept with empty hunks",
                    outcome = "skipped",
                    path = %file_path.display(),
                    bytes = meta.len(),
                    cap = MAX_UNTRACKED_FILE_SIZE,
                );
                Vec::new()
            }
            Err(err) => {
                tracing::warn!(
                    target: crate::logging::targets::ENV_GIT,
                    event_name = "untracked_metadata_failed",
                    message = "untracked file metadata read failed; rail entry kept with empty hunks",
                    outcome = "failure",
                    path = %file_path.display(),
                    error = %err,
                );
                Vec::new()
            }
        };
        out.push(FileHunks {
            path: path.to_owned(),
            status: FileStatus::Untracked,
            hunks,
            oversize: false,
        });
    }
    (out, true, 0)
}

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

    #[test]
    fn parse_name_status_modified() {
        let raw = "M\tpath/to/file.rs";
        let files = parse_name_status(raw);
        assert_eq!(files.len(), 1);
        assert_eq!(files[0].path, "path/to/file.rs");
        assert_eq!(files[0].status, FileStatus::Modified);
    }

    #[test]
    fn parse_name_status_all_codes() {
        let raw = "\
M\ta.rs
A\tb.rs
D\tc.rs
R100\told.rs\tnew.rs
C75\tsrc.rs\tdst.rs
T\tsymlink.rs
U\tconflicted.rs";
        let files = parse_name_status(raw);
        let statuses: Vec<_> = files.iter().map(|f| (f.path.clone(), f.status)).collect();
        assert_eq!(
            statuses,
            vec![
                ("a.rs".into(), FileStatus::Modified),
                ("b.rs".into(), FileStatus::Added),
                ("c.rs".into(), FileStatus::Deleted),
                ("new.rs".into(), FileStatus::Renamed),
                ("dst.rs".into(), FileStatus::Copied),
                ("symlink.rs".into(), FileStatus::Typechange),
                ("conflicted.rs".into(), FileStatus::Unmerged),
            ]
        );
    }

    #[test]
    fn parse_name_status_drops_unknown_codes() {
        // X (internal error) and B (broken pairing) shouldn't
        // appear in normal git output but are reserved codes; the
        // parser drops them rather than miscategorising. A WARN
        // log fires per drop but tests don't capture tracing.
        let raw = "M\tkeep.rs\nX\tweird.rs\nB\tbroken.rs\nA\talso_keep.rs";
        let files = parse_name_status(raw);
        let paths: Vec<&str> = files.iter().map(|f| f.path.as_str()).collect();
        assert_eq!(paths, vec!["keep.rs", "also_keep.rs"]);
    }

    #[test]
    fn parse_name_status_empty() {
        assert!(parse_name_status("").is_empty());
    }

    fn added(line: &DiffLine, expected: &str) -> bool {
        line.kind == DiffLineKind::Added && line.text == expected
    }

    fn removed(line: &DiffLine, expected: &str) -> bool {
        line.kind == DiffLineKind::Removed && line.text == expected
    }

    fn context(line: &DiffLine, expected: &str) -> bool {
        line.kind == DiffLineKind::Context && line.text == expected
    }

    // Raw strings throughout - unified-diff context lines are
    // single-space-prefixed, and Rust's `\<newline>` continuation
    // strips that space when it eats the next line's leading
    // whitespace. Raw strings preserve all whitespace verbatim.

    #[test]
    fn parse_hunks_single() {
        let section = "\
diff --git a/x.rs b/x.rs
index abc..def 100644
--- a/x.rs
+++ b/x.rs
@@ -1,3 +1,4 @@
 line1
 line2
+new line
 line3";
        let hunks = parse_hunks(section);
        assert_eq!(hunks.len(), 1);
        assert_eq!(hunks[0].old_start, 1);
        assert_eq!(hunks[0].old_count, 3);
        assert_eq!(hunks[0].new_start, 1);
        assert_eq!(hunks[0].new_count, 4);
        assert_eq!(hunks[0].added_count(), 1);
        assert_eq!(hunks[0].removed_count(), 0);
        assert!(hunks[0].lines.iter().any(|l| added(l, "new line")));
        // The added line carries its new-file line number; old_line
        // is None so a gutter renderer leaves that side blank.
        let inserted =
            hunks[0].lines.iter().find(|l| added(l, "new line")).expect("added line present");
        assert_eq!(inserted.new_line, Some(3));
        assert_eq!(inserted.old_line, None);
    }

    #[test]
    fn parse_hunks_multiple() {
        let section = "\
diff --git a/x.rs b/x.rs
--- a/x.rs
+++ b/x.rs
@@ -1,3 +1,4 @@
 line1
+added1
 line2
 line3
@@ -10,3 +11,4 @@
 line10
+added2
 line11
 line12";
        let hunks = parse_hunks(section);
        assert_eq!(hunks.len(), 2);
        assert_eq!(hunks[0].old_start, 1);
        assert_eq!(hunks[1].old_start, 10);
        assert!(hunks[0].lines.iter().any(|l| added(l, "added1")));
        assert!(hunks[1].lines.iter().any(|l| added(l, "added2")));
    }

    #[test]
    fn parse_hunks_deletion() {
        let section = "\
diff --git a/x.rs b/x.rs
--- a/x.rs
+++ b/x.rs
@@ -1,4 +1,3 @@
 line1
-deleted line
 line2
 line3";
        let hunks = parse_hunks(section);
        assert_eq!(hunks.len(), 1);
        assert_eq!(hunks[0].added_count(), 0);
        assert_eq!(hunks[0].removed_count(), 1);
        assert!(hunks[0].lines.iter().any(|l| removed(l, "deleted line")));
        let context_lines: Vec<&DiffLine> =
            hunks[0].lines.iter().filter(|l| l.kind == DiffLineKind::Context).collect();
        assert_eq!(context_lines.len(), 3);
        assert!(hunks[0].lines.iter().any(|l| context(l, "line1")));
    }

    #[test]
    fn parse_hunks_line_numbers_track_through_changes() {
        // Mixed hunk: 1 context, 1 remove, 1 add, 1 context.
        // Old:  L1 line_a, L2 line_b, L3 line_d
        // New:  L1 line_a, L2 line_c, L3 line_d
        let section = "\
diff --git a/x.rs b/x.rs
--- a/x.rs
+++ b/x.rs
@@ -1,3 +1,3 @@
 line_a
-line_b
+line_c
 line_d";
        let hunks = parse_hunks(section);
        assert_eq!(hunks.len(), 1);
        let lines = &hunks[0].lines;
        assert_eq!(lines[0].old_line, Some(1));
        assert_eq!(lines[0].new_line, Some(1));
        assert_eq!(lines[1].kind, DiffLineKind::Removed);
        assert_eq!(lines[1].old_line, Some(2));
        assert_eq!(lines[1].new_line, None);
        assert_eq!(lines[2].kind, DiffLineKind::Added);
        assert_eq!(lines[2].old_line, None);
        assert_eq!(lines[2].new_line, Some(2));
        assert_eq!(lines[3].kind, DiffLineKind::Context);
        assert_eq!(lines[3].old_line, Some(3));
        assert_eq!(lines[3].new_line, Some(3));
    }

    #[test]
    fn parse_hunk_header_with_counts() {
        let (o_s, o_c, n_s, n_c) = parse_hunk_header("@@ -65,4 +65,12 @@").unwrap();
        assert_eq!((o_s, o_c, n_s, n_c), (65, 4, 65, 12));
    }

    #[test]
    fn parse_hunk_header_omitted_counts() {
        // Per unified-diff spec, missing count means 1.
        let (o_s, o_c, n_s, n_c) = parse_hunk_header("@@ -42 +42 @@").unwrap();
        assert_eq!((o_s, o_c, n_s, n_c), (42, 1, 42, 1));
    }

    #[test]
    fn parse_hunk_header_with_trailing_context() {
        // Real git output appends the enclosing function name after
        // the second @@. Parser must ignore it.
        let (o_s, _, n_s, _) = parse_hunk_header("@@ -10,2 +10,3 @@ fn foo() {").unwrap();
        assert_eq!((o_s, n_s), (10, 10));
    }

    #[test]
    fn parse_hunk_header_malformed() {
        assert!(parse_hunk_header("not a hunk header").is_none());
        assert!(parse_hunk_header("@@ -x,y +1,2 @@").is_none());
    }

    #[test]
    fn contains_hunk_marker_true_when_at_marker_present() {
        let section = "diff --git a/x.rs b/x.rs\n--- a/x.rs\n+++ b/x.rs\n@@ -1 +1 @@\n-a\n+b\n";
        assert!(contains_hunk_marker(section));
    }

    #[test]
    fn contains_hunk_marker_false_when_no_at_marker() {
        let section =
            "diff --git a/logo.png b/logo.png\nBinary files a/logo.png and b/logo.png differ\n";
        assert!(!contains_hunk_marker(section));
    }

    #[test]
    fn parse_hunks_on_full_file_section_skips_diff_headers() {
        // Regression: per-file fetch yields the full output starting
        // with `diff --git` / `index` / `--- a/` / `+++ b/` headers.
        // `parse_hunks` must skip those and only consume from the
        // first `@@` marker onward.
        let raw = "diff --git a/x.rs b/x.rs\n\
--- a/x.rs\n\
+++ b/x.rs\n\
@@ -1,1 +1,2 @@\n\
 keep\n\
+new\n";
        let hunks = parse_hunks(raw);
        assert_eq!(hunks.len(), 1);
        assert!(hunks[0].lines.iter().any(|l| added(l, "new")));
        let file = FileHunks {
            path: "x.rs".to_owned(),
            status: FileStatus::Modified,
            hunks: hunks.clone(),
            oversize: false,
        };
        assert_eq!(file.added_count(), 1);
        assert_eq!(file.removed_count(), 0);
    }

    /// `diff_ref_spec` keeps `HEAD` as a two-dot working-tree diff
    /// (otherwise `HEAD...HEAD` would be empty since HEAD is its
    /// own merge-base with itself), and converts any other target
    /// to a three-dot range. Three-dot is the same form the
    /// Inspector GIT panel uses for branch-ahead at
    /// `forge_agent::env::git_diff::scan` (`format!("{default}...HEAD")`);
    /// keeping them in sync prevents the overlay-empty / panel-says-
    /// 142-lines asymmetry that surfaces after squash-merges.
    #[test]
    fn diff_ref_spec_passes_head_through_unchanged() {
        assert_eq!(diff_ref_spec("HEAD"), "HEAD");
    }

    #[test]
    fn diff_ref_spec_converts_branch_to_three_dot_range() {
        assert_eq!(diff_ref_spec("main"), "main...HEAD");
        assert_eq!(diff_ref_spec("master"), "master...HEAD");
        assert_eq!(diff_ref_spec("origin/main"), "origin/main...HEAD");
    }

    #[test]
    fn diff_ref_spec_treats_sha_like_a_branch() {
        // Commit SHAs benefit from three-dot the same way branches
        // do - diff vs merge-base, not vs the tip directly.
        assert_eq!(diff_ref_spec("abc1234"), "abc1234...HEAD");
    }

    // ---- commit-stepper scan (scan_commits / scan_commit) ----

    // `git init -b` needs git >= 2.28; init without -b then point HEAD
    // via symbolic-ref for portability (mirrors the parent module's
    // helper).
    fn git(dir: &tempfile::TempDir, args: &[&str]) {
        let out = std::process::Command::new("git")
            .arg("-C")
            .arg(dir.path())
            .args(args)
            .output()
            .expect("git");
        assert!(out.status.success(), "git {args:?}: {}", String::from_utf8_lossy(&out.stderr));
    }

    fn git_capture(dir: &tempfile::TempDir, args: &[&str]) -> String {
        let out = std::process::Command::new("git")
            .arg("-C")
            .arg(dir.path())
            .args(args)
            .output()
            .expect("git");
        assert!(out.status.success(), "git {args:?}: {}", String::from_utf8_lossy(&out.stderr));
        String::from_utf8_lossy(&out.stdout).trim().to_owned()
    }

    fn init_commit_repo(dir: &tempfile::TempDir) {
        git(dir, &["init", "-q"]);
        git(dir, &["symbolic-ref", "HEAD", "refs/heads/main"]);
        git(dir, &["config", "user.email", "t@e.com"]);
        git(dir, &["config", "user.name", "T"]);
        git(dir, &["config", "commit.gpgsign", "false"]);
    }

    fn write_file(dir: &tempfile::TempDir, name: &str, contents: &str) {
        std::fs::write(dir.path().join(name), contents).expect("write");
    }

    fn commit(dir: &tempfile::TempDir, msg: &str) {
        git(dir, &["add", "-A"]);
        git(dir, &["commit", "-q", "-m", msg]);
    }

    /// Build main+init then a `feat` branch with three commits, each
    /// adding a distinct file. Shared by the stepper scan tests.
    fn three_commit_branch(dir: &tempfile::TempDir) {
        init_commit_repo(dir);
        write_file(dir, "base.txt", "base\n");
        commit(dir, "init");
        git(dir, &["checkout", "-q", "-b", "feat"]);
        write_file(dir, "a.rs", "a\n");
        commit(dir, "first");
        write_file(dir, "b.rs", "b\n");
        commit(dir, "second");
        write_file(dir, "c.rs", "c\n");
        commit(dir, "third");
    }

    #[tokio::test(flavor = "current_thread")]
    async fn scan_commits_lists_branch_commits_oldest_first() {
        let dir = tempfile::tempdir().expect("tempdir");
        three_commit_branch(&dir);
        let commits = scan_commits_within(dir.path(), "main", TEST_GIT_BUDGET).await;
        let subjects: Vec<&str> = commits.iter().map(|c| c.subject.as_str()).collect();
        assert_eq!(subjects, vec!["first", "second", "third"], "oldest-first");
        assert!(commits.iter().all(|c| !c.sha.is_empty() && !c.short_sha.is_empty()));
        assert!(commits[0].sha.starts_with(&commits[0].short_sha), "short sha prefixes full");
    }

    #[tokio::test(flavor = "current_thread")]
    async fn scan_commits_empty_when_no_commits_ahead() {
        let dir = tempfile::tempdir().expect("tempdir");
        init_commit_repo(&dir);
        write_file(&dir, "base.txt", "base\n");
        commit(&dir, "init");
        // HEAD..HEAD is empty; a dirty-tree-only review has no stepper.
        assert!(scan_commits_within(dir.path(), "HEAD", TEST_GIT_BUDGET).await.is_empty());
    }

    /// **The readers take the budget they are given.** A ZERO budget refuses
    /// a read at its first `git` child, a helper deeper in refuses the same
    /// way, and the same repo reads under the budget these cases use - the
    /// seam `run_git_within` now offers every hunk and content read,
    /// production keeping `COMMAND_TIMEOUT`.
    #[tokio::test(flavor = "current_thread")]
    async fn the_readers_take_the_budget_they_are_given() {
        use forge_primitives::git::GitBranch;
        use forge_primitives::git_diff::{GitDiffSnapshot, GitDiffStats, LayerState, RepoGate};

        let dir = tempfile::tempdir().expect("tempdir");
        init_commit_repo(&dir);
        write_file(&dir, "base.txt", "base\n");
        commit(&dir, "init");
        write_file(&dir, "base.txt", "base\nand a change\n");

        // Every refusal below runs against a `git` that cannot answer inside
        // the zero budget: the machine's own can, and did, on CI (#2249).
        let bin = tempfile::tempdir().expect("tempdir");
        super::super::stall_git_at(dir.path(), bin.path());

        let refused = scan_within(dir.path(), "HEAD", Duration::ZERO).await;
        assert!(!refused.scanner_ok, "a zero budget reads as a failed scan: {refused:?}");
        assert!(refused.files.is_empty(), "with nothing read: {refused:?}");

        // A child the reader spawns LATER takes the same budget, so the
        // claim has a witness beyond the entry's first call: the per-file
        // fetch, which only runs once the name-status has listed a file.
        let deeper = fetch_file_hunks(dir.path(), "HEAD", "base.txt", Duration::ZERO).await;
        assert!(
            matches!(deeper, FileScanOutcome::SubprocessFailed),
            "a later child refuses a zero budget too",
        );

        // And the content reader carries the same seam.
        let snapshot = GitDiffSnapshot {
            branch: GitBranch::Named("feature".into()),
            default_branch: None,
            repo_gate: RepoGate::InRepo,
            pushed_sha: None,
            worktree: LayerState::Populated(GitDiffStats {
                files: Vec::new(),
                total_files: 0,
                total_added: 0,
                total_removed: 0,
            }),
            branch_ahead: LayerState::Clean,
            pr: None,
            closes: Vec::new(),
            pr_fetched_at: None,
        };
        let refused_content = super::super::content::scan_within(
            dir.path(),
            &snapshot,
            None,
            None,
            None,
            Duration::ZERO,
        )
        .await;
        assert!(
            matches!(refused_content.worktree, LayerState::ScanFailed),
            "the content reader refuses a zero budget too: {refused_content:?}",
        );

        // The budget these cases use reads the same repo.
        crate::env::git_command::clear_git_point(dir.path());
        let read = scan_within(dir.path(), "HEAD", TEST_GIT_BUDGET).await;
        assert!(read.scanner_ok, "and the tests' budget reads it: {read:?}");
        assert_eq!(read.files.len(), 1, "with the changed file: {read:?}");
    }

    #[tokio::test(flavor = "current_thread")]
    async fn scan_commit_scopes_to_that_commit_only() {
        let dir = tempfile::tempdir().expect("tempdir");
        three_commit_branch(&dir);
        let commits = scan_commits_within(dir.path(), "main", TEST_GIT_BUDGET).await;
        assert_eq!(commits.len(), 3);
        let middle = scan_commit_within(dir.path(), &commits[1].sha, TEST_GIT_BUDGET).await;
        let paths: Vec<&str> = middle.files.iter().map(|f| f.path.as_str()).collect();
        assert_eq!(paths, vec!["b.rs"], "middle commit touches only b.rs");
        assert!(middle.scanner_ok);
    }

    /// **A sha off a wire never reaches `git diff` as an option.** The range
    /// this scan builds is one argv, and `git diff --output=<file>^..…`
    /// writes files wherever the caller points it; the resolution is the
    /// gate, and this is the pin (the file read's own is beside it, in
    /// `file.rs`).
    #[tokio::test(flavor = "current_thread")]
    async fn an_option_shaped_sha_scans_nothing_and_writes_nothing() {
        let dir = tempfile::tempdir().expect("tempdir");
        init_commit_repo(&dir);
        write_file(&dir, "a.rs", "a\n");
        commit(&dir, "init");
        let target = dir.path().join("written-by-git");
        let shaped = format!("--output={}", target.display());

        let outcome = scan_commit_within(dir.path(), &shaped, TEST_GIT_BUDGET).await;
        assert!(!outcome.scanner_ok, "a sha that names no commit is the scan's own failure");
        assert!(outcome.files.is_empty(), "and it carries no files: {outcome:?}");
        assert!(!target.exists(), "git was never asked to write a file");

        let body = scan_commit_body_within(dir.path(), &shaped, TEST_GIT_BUDGET).await;
        assert!(body.is_empty(), "nor does the body read ask git for it");
        assert!(!target.exists(), "still no file");
    }

    #[tokio::test(flavor = "current_thread")]
    async fn scan_commit_root_commit_does_not_panic() {
        let dir = tempfile::tempdir().expect("tempdir");
        init_commit_repo(&dir);
        write_file(&dir, "README.md", "hello\n");
        commit(&dir, "init");
        let root = git_capture(&dir, &["rev-list", "--max-parents=0", "HEAD"]);
        let outcome = scan_commit_within(dir.path(), &root, TEST_GIT_BUDGET).await;
        // Parentless root: the empty-tree fallback surfaces its full
        // contents as an added file rather than erroring on `<sha>^`.
        let paths: Vec<&str> = outcome.files.iter().map(|f| f.path.as_str()).collect();
        assert_eq!(paths, vec!["README.md"]);
        assert!(outcome.scanner_ok);
    }

    #[tokio::test(flavor = "current_thread")]
    async fn scan_commit_body_returns_full_multiline_body() {
        let dir = tempfile::tempdir().expect("tempdir");
        init_commit_repo(&dir);
        write_file(&dir, "a.rs", "a\n");
        git(&dir, &["add", "-A"]);
        git(
            &dir,
            &[
                "commit",
                "-q",
                "-m",
                "the subject line",
                "-m",
                "body line one\nbody line two\n\nbody line three",
            ],
        );
        let sha = git_capture(&dir, &["rev-parse", "HEAD"]);
        let body = scan_commit_body_within(dir.path(), &sha, TEST_GIT_BUDGET).await;
        // `%b` starts after the subject, so the subject never appears.
        assert!(!body.contains("the subject line"), "body excludes the subject: {body:?}");
        assert!(body.contains("body line one"));
        assert!(body.contains("body line three"));
        // The internal blank line between paragraphs survives.
        assert!(body.lines().count() >= 4, "multi-line body preserved: {body:?}");
    }

    #[tokio::test(flavor = "current_thread")]
    async fn scan_commit_body_empty_for_subject_only() {
        let dir = tempfile::tempdir().expect("tempdir");
        init_commit_repo(&dir);
        write_file(&dir, "a.rs", "a\n");
        commit(&dir, "just a subject");
        let sha = git_capture(&dir, &["rev-parse", "HEAD"]);
        let body = scan_commit_body_within(dir.path(), &sha, TEST_GIT_BUDGET).await;
        assert!(body.is_empty(), "a subject-only commit has an empty body, got {body:?}");
    }

    // ---- full-context scan (pin-at-open snapshot source) ----

    #[tokio::test(flavor = "current_thread")]
    async fn scan_fetches_full_context_hunks() {
        let dir = tempfile::tempdir().expect("tempdir");
        init_commit_repo(&dir);
        // A 20-line file; edits near the top (line 3) and near the bottom
        // (line 17) leave a ~13-line unchanged gap between them. At full
        // context git folds them into one hunk carrying every line, so the
        // overlay can narrow + expand from that single cached snapshot.
        let base_lines: Vec<String> = (1..=20).map(|i| format!("line {i}")).collect();
        write_file(&dir, "f.rs", &format!("{}\n", base_lines.join("\n")));
        commit(&dir, "base");
        let mut edited = base_lines;
        "line 3 CHANGED".clone_into(&mut edited[2]);
        "line 17 CHANGED".clone_into(&mut edited[16]);
        write_file(&dir, "f.rs", &format!("{}\n", edited.join("\n")));

        let outcome = scan_within(dir.path(), "HEAD", TEST_GIT_BUDGET).await;
        assert!(outcome.scanner_ok);
        let file = outcome.files.iter().find(|f| f.path == "f.rs").expect("f.rs scanned");
        assert_eq!(file.hunks.len(), 1, "full context merges the two edits into one hunk");
        // The previously-hidden middle lines are all present in the snapshot.
        let texts: Vec<&str> = file.hunks[0].lines.iter().map(|l| l.text.as_str()).collect();
        assert!(texts.contains(&"line 10"), "a middle context line is in the snapshot");
        assert!(texts.contains(&"line 3 CHANGED"), "the first edit is present");
        assert!(texts.contains(&"line 17 CHANGED"), "the second edit is present");
    }

    #[tokio::test(flavor = "current_thread")]
    async fn oversize_file_does_not_blank_the_scope() {
        let dir = tempfile::tempdir().expect("tempdir");
        init_commit_repo(&dir);
        write_file(&dir, "small.rs", "fn a() {}\n");
        // A file whose diff blows the 8 MiB stdout cap: one ~5 MiB line
        // changed to another, so old+new exceeds the cap even at the
        // bounded fallback context.
        write_file(&dir, "big.txt", &"a".repeat(5 * 1024 * 1024));
        commit(&dir, "base");
        write_file(&dir, "small.rs", "fn a() { b(); }\n");
        write_file(&dir, "big.txt", &"b".repeat(5 * 1024 * 1024));

        let outcome = scan_within(dir.path(), "HEAD", TEST_GIT_BUDGET).await;
        assert!(outcome.scanner_ok, "one oversize file must not blank the whole scope");
        let small = outcome.files.iter().find(|f| f.path == "small.rs").expect("small scanned");
        assert!(!small.oversize, "the normal file is not flagged oversize");
        assert!(!small.hunks.is_empty(), "the normal file still renders its diff");
        let big = outcome.files.iter().find(|f| f.path == "big.txt").expect("big listed");
        assert!(big.oversize, "the oversize file is flagged (expansion disabled downstream)");
    }
}