drep/diff/

mod.rs

//! Which files changed, in git terms.
//!
//! Every command in `drep` that looks at "what changed" comes through here.
//! `drep check --staged` for a pre-commit hook, `--diff <ref>` for a pre-push
//! gate, and the cache key that deduplicates repeated LLM calls all need a
//! stable answer to the same question. They shell out to git directly —
//! `tokio::process::Command` rather than libgit2, because the only operations
//! drep needs are the ones git's own CLI was built for, and a git CLI that
//! misbehaves would surface as a real OS-level error rather than a translated
//! library one.
//!
//! Two invariants matter more than the implementations:
//!
//! - "No files changed" must be **distinct** from "I could not ask git".
//!   Conflating them is how a commit gate rubber-stamps the day the user's
//!   git install breaks.
//! - `current_commit_sha` is the one place this is reversed: it only feeds
//!   a cache key, and a cache-key component must never take the analysis down.

use std::ffi::{OsStr, OsString};
use std::path::{Path, PathBuf};
use std::time::Duration;

use futures::StreamExt;

use crate::files;

mod git;
pub mod hunks;
mod prefix;
mod quoting;
mod uncommitted;

use git::{GitEnv, committing_index, spawn_git, spawn_git_bytes};
pub(crate) use git::{git_query, run_git, same_directory};
use hunks::{Hunk, parse_unified_diff};
use prefix::{from_prefix, hunks_from, paths_from, working_prefix};
pub use uncommitted::{Uncommitted, diverging_from, uncommitted_paths};

/// The well-known SHA for the empty git tree.
///
/// On a fresh `git init` (no commits yet) there is no `HEAD` to diff against,
/// so drep diffs against this instead. Otherwise every first commit on a new
/// repository would fail with "fatal: ambiguous argument 'HEAD'".
const EMPTY_TREE: &str = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";

/// How long `current_commit_sha` is willing to wait for `git` to answer.
///
/// Used to be wall-clock unbounded, which was fine until a hung `git` stalled
/// the gate and blocked every commit. Five seconds is more than enough for a
/// local `git rev-parse`; if it does not answer by then the answer is
/// "unknown" and the cache key falls through.
const SHA_TIMEOUT: Duration = Duration::from_secs(5);

/// What went wrong shelling out to git.
///
/// Distinct from `std::io::Error` because the most common cause — git exits
/// non-zero for "not a repository" — is not the same as "could not spawn
/// git", and the two should not be displayed the same way.
#[derive(Debug)]
pub enum GitError {
    /// `git` could not be spawned at all: missing binary, permission denied,
    /// or the OS rejected the argv. This is fundamentally different from
    /// git exiting non-zero.
    Spawn(String),
    /// `git` ran and refused. `code` is the exit status when git set one;
    /// `stderr` is the last argument worth showing to a user.
    NonZero { code: Option<i32>, stderr: String },
}

impl std::fmt::Display for GitError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            GitError::Spawn(msg) => write!(f, "git could not be spawned: {msg}"),
            GitError::NonZero { code, stderr } => {
                let code = code.map_or("<signal>".to_owned(), |c| c.to_string());
                write!(f, "git exited {code}: {stderr}")
            }
        }
    }
}

impl std::error::Error for GitError {}

/// Whether `root` has any commit yet.
///
/// Single-purpose helper: kept here because it is git semantics, not file
/// discovery, and the diff commands need to know this both for the empty-tree
/// fallback and for the `changed_since` no-HEAD case.
async fn has_head(root: &Path) -> bool {
    run_git(root, &["rev-parse", "--verify", "HEAD"])
        .await
        .is_ok()
}

/// Resolve a path printed by `git rev-parse` against the queried repository.
///
/// Git prints an absolute path for some worktree layouts and a repository-
/// relative path for others. Callers must not independently guess which form
/// they received.
pub(crate) async fn git_path(root: &Path, args: &[&str]) -> Result<PathBuf, GitError> {
    let raw = run_git(root, args).await?;
    let path = PathBuf::from(raw);
    Ok(if path.is_absolute() {
        path
    } else {
        root.join(path)
    })
}

/// The working tree's top-level directory.
///
/// Here rather than beside its caller for the reason this module's header
/// states: `run_git` is the only place drep spawns git, and its
/// `GIT_DIR`/`GIT_WORK_TREE` scrubbing is what stops a hook's inherited
/// environment answering about a different repository. Site policy is evaluated
/// against this answer, and a marker checked against the wrong tree is a policy
/// bypass rather than a cosmetic mistake.
///
/// Through `git_path` because `--show-toplevel` prints an absolute path for some
/// worktree layouts and a relative one for others - the guess that helper exists
/// to remove.
pub(crate) async fn repository_root(root: &Path) -> Result<PathBuf, GitError> {
    git_path(root, &["rev-parse", "--show-toplevel"]).await
}

/// Parse the newline-delimited output of `git diff --name-only` into paths,
/// then keep only those the caller analyzes.
///
/// Empty lines are tolerated because git occasionally emits a trailing one
/// depending on version and locale settings; the filter is the load-bearing
/// half — it is what makes a diff query return files drep can do something
/// with, and keeps lock/build output from inflating the work set.
///
/// Each line is decoded before the filter sees it: git quotes a name holding
/// a byte such as `é` or `"`, and the quoted form matched no file class, so a
/// staged `café.md` was silently absent from `lint-docs --staged`.
///
/// `wanted` is a parameter rather than a hardcoded `files::is_scan_target`
/// because the file classes are disjoint and one command owns each: `check`
/// asks for registered-language sources, `lint-docs` asks for markdown. With
/// the predicate baked in, `lint-docs --staged` could not be expressed at all
/// and the hook ran over the whole repository instead.
fn filter_paths(output: &str, wanted: fn(&Path) -> bool) -> Vec<PathBuf> {
    output
        .lines()
        .filter(|line| !line.trim().is_empty())
        .map(quoting::decode)
        .filter(|path| wanted(path))
        .collect()
}

/// Every `git diff` drep runs starts with these, ahead of its selection.
///
/// drep parses the output, and git formats it from the user's configuration
/// and the repository's attributes. Each option pins one thing a setting or
/// attribute would otherwise change, and each such change made the parser find
/// no hunk, or a hunk other than the committed text, which the gate then
/// reports as reviewed:
///
/// - `core.quotePath=true` quotes every byte above 0x7f, so a name that is not
///   UTF-8 arrives as escapes `quoting::decode` reverses exactly, rather than
///   as raw bytes the lossy conversion of stdout replaces.
/// - `diff.suppressBlankEmpty=false` keeps the leading space on a blank context
///   line. Printed empty, the line was skipped and every line after it in the
///   hunk carried the wrong number.
/// - `--text` because `binary` or `-diff` in a committed `.gitattributes`, or
///   a single NUL byte in the content, turns a source file's hunks into one
///   `Binary files ... differ` line. Binary files outside the caller's file
///   class are rendered as text too, then dropped unread.
/// - `--no-textconv` and `--no-ext-diff` ignore a textconv driver,
///   `diff.external` and `GIT_EXTERNAL_DIFF`, whose program (difftastic, say)
///   prints something other than the committed text as a unified diff.
/// - `--no-color` overrides `color.ui=always`, which wraps each header in
///   escape codes even when stdout is a pipe.
/// - `--src-prefix`/`--dst-prefix` restore the `a/` and `b/` that
///   `diff.noprefix` removes and `diff.mnemonicPrefix` (`c/` and `i/` for
///   `--cached`) and `diff.srcPrefix`/`diff.dstPrefix` replace.
/// - `--no-relative` overrides `diff.relative`, which names each file from the
///   working directory and leaves out every file outside it, so a commit run
///   from a subdirectory passed its other files unreviewed. Every path is named
///   from the top level, as `:<path>` resolves it when a staged file's content
///   is read, and `prefix` converts it to the working directory's view before a
///   query returns it.
///
/// `--diff-filter=ACMRT` is selection rather than format, and is here so the
/// staged and branch queries state it once; `staged_files` says why deletions
/// are left out. `T` is kept because a type change is how a symlink becomes a
/// regular file, and leaving it out passed that file's whole content
/// unreviewed.
const DIFF: &[&str] = &[
    "-c",
    "core.quotePath=true",
    "-c",
    "diff.suppressBlankEmpty=false",
    "diff",
    "--text",
    "--no-textconv",
    "--no-ext-diff",
    "--no-color",
    "--src-prefix=a/",
    "--dst-prefix=b/",
    "--no-relative",
    "--diff-filter=ACMRT",
];

/// Run `git diff` with its output format pinned by [`DIFF`], selecting with
/// `selection`.
async fn git_diff(root: &Path, selection: &[&str], env: GitEnv<'_>) -> Result<String, GitError> {
    spawn_git(root, &[DIFF, selection].concat(), env).await
}

/// Files staged for commit, relative to `root`, that drep analyzes.
///
/// `--diff-filter=ACMRT` excludes deletions on purpose: a deleted file
/// cannot be analyzed, and passing it on would look like an unreadable file
/// rather than an absent one. The empty-tree fallback covers the
/// initial-commit case (no `HEAD` yet).
pub async fn staged_files(
    root: &Path,
    wanted: fn(&Path) -> bool,
) -> Result<Vec<PathBuf>, GitError> {
    let (names, prefix) = staged_diff(root, NAMES).await?;
    Ok(paths_from(filter_paths(&names, wanted), &prefix))
}

/// How many staged files have their content read at once: one `git cat-file`
/// each, bounded like drep's other child-process fan-outs.
const CONTENT_READ_CONCURRENCY: usize = 4;

/// Each staged file `wanted` accepts, with the content the commit records for it.
///
/// The content comes from the same index as the list, never from the working
/// tree, which differs from it after a partial `git add` and under an index the
/// committer chose. A file whose content cannot be read carries its error, as
/// reading it from disk would.
pub async fn staged_contents(
    root: &Path,
    wanted: fn(&Path) -> bool,
) -> Result<Vec<(PathBuf, std::io::Result<String>)>, GitError> {
    let view = StagedView::of(root).await?;
    let paths = filter_paths(&view.diff(root, NAMES).await?, wanted);
    let view = &view;
    Ok(futures::stream::iter(paths)
        .map(|path| async move {
            let content = view.content(root, &path).await;
            (from_prefix(&path, &view.prefix), content)
        })
        .buffered(CONTENT_READ_CONCURRENCY)
        .collect()
        .await)
}

/// `git diff --cached` in whichever output mode the caller wants, and the
/// working directory's prefix its paths are to be read from.
///
/// The selection rules — the empty-tree fallback here, `--diff-filter=ACMRT`
/// in [`DIFF`] — live once rather than in each of `staged_files` and
/// `staged_hunks`. They were stated twice, and a change applied to one and not
/// the other would make the file list and the hunk set disagree about what is
/// in scope: drep would analyze a file the gate never listed, which is exactly
/// the class of failure this module exists to prevent.
async fn staged_diff(root: &Path, mode: &str) -> Result<(String, PathBuf), GitError> {
    let view = StagedView::of(root).await?;
    Ok((view.diff(root, mode).await?, view.prefix))
}

/// What the staged queries read: whether HEAD exists, the index the commit is being made from, and where `root` sits in the working tree.
///
/// Built once per query so the file list and the content read for it come from the same index.
struct StagedView {
    head: bool,
    index: Option<PathBuf>,
    prefix: PathBuf,
}

impl StagedView {
    async fn of(root: &Path) -> Result<Self, GitError> {
        let (head, index, prefix) =
            tokio::join!(has_head(root), committing_index(root), working_prefix(root));
        Ok(Self {
            head,
            index: index?,
            prefix: prefix?,
        })
    }

    fn env(&self) -> GitEnv<'_> {
        self.index
            .as_deref()
            .map_or(GitEnv::Scrubbed, GitEnv::Index)
    }

    async fn diff(&self, root: &Path, mode: &str) -> Result<String, GitError> {
        let selection: &[&str] = if self.head {
            &["--cached", mode]
        } else {
            &["--cached", mode, EMPTY_TREE]
        };
        git_diff(root, selection, self.env()).await
    }

    /// The content the commit records for `path`: its blob in the index, as UTF-8 text.
    ///
    /// The `:<path>` spec is built from the path's bytes, so a name that is not
    /// UTF-8, which `quoting::decode` keeps exactly, reaches git unchanged.
    async fn content(&self, root: &Path, path: &Path) -> std::io::Result<String> {
        let mut spec = OsString::from(":");
        spec.push(path);
        let args = [OsStr::new("cat-file"), OsStr::new("blob"), &spec];
        let blob = spawn_git_bytes(root, &args, self.env())
            .await
            .map_err(std::io::Error::other)?;
        String::from_utf8(blob).map_err(|_| {
            std::io::Error::new(
                std::io::ErrorKind::InvalidData,
                "stream did not contain valid UTF-8",
            )
        })
    }
}

/// `git diff <ref>...<HEAD|empty-tree>` in whichever output mode is wanted.
///
/// The three-dot spec is built once for the same reason as `staged_diff`: the
/// merge-base semantics are a decision, and `changed_since`/`hunks_since` must
/// not be able to drift apart on it.
///
/// A `git_ref` that begins with `-` is rejected before any git invocation.
/// Without this guard, `drep check --diff --output=/tmp/x` would reach git
/// as a flag — `--output=/tmp/x` is parsed by `git diff` as an option, not
/// a ref. Passing `--` does not help: after `--`, git treats arguments as
/// *paths*, and `--diff -- this/file` is "diff versus the path `this/file`"
/// rather than "diff versus the ref `--`".
async fn since_diff(
    root: &Path,
    git_ref: &str,
    tip: Option<&str>,
    mode: &str,
) -> Result<String, GitError> {
    for candidate in [Some(git_ref), tip].into_iter().flatten() {
        refuse_flag_like(candidate)?;
    }
    // An explicit tip names the commit the caller means, which is not always
    // the checked-out one. The pre-push hook is the case that forced this:
    // git can push a ref that is not HEAD (`git push origin feature:feature`
    // from another branch, or `git push --all`), and diffing against HEAD
    // there reviews the wrong branch entirely and green-lights the pushed one
    // unseen - the exact "unanalyzed reported as clean" failure the gate
    // exists to prevent.
    // No `EMPTY_TREE` fallback here, unlike `staged_diff`. A three-dot spec is
    // a *symmetric difference between two commits*, and the empty tree is a
    // tree - git rejects `<ref>...4b825dc` with "Invalid symmetric difference
    // expression" whatever `<ref>` is. So the fallback could never produce a
    // diff; it only turned "this repo has no commits" into a confusing message
    // about symmetric differences. A repo with an unborn HEAD also has no ref
    // to diff *from*, so there is nothing to salvage - say so plainly.
    let ref_b = match tip {
        Some(tip) => tip,
        None if has_head(root).await => "HEAD",
        None => {
            return Err(GitError::NonZero {
                code: None,
                stderr: "this repository has no commits yet, so there is nothing to \
                         diff against; use --staged before the first commit"
                    .to_owned(),
            });
        }
    };
    let spec = format!("{git_ref}...{ref_b}");
    git_diff(root, &[mode, &spec], GitEnv::Scrubbed).await
}

/// Refuse a ref that git would parse as an option.
///
/// Every query that hands a caller's ref to git applies it before spawning,
/// for the reason [`since_diff`] gives: `--output=<file>` in a ref position is
/// an option to `git diff`, and `--` cannot help because what follows it is a
/// path.
pub(crate) fn refuse_flag_like(candidate: &str) -> Result<(), GitError> {
    if candidate.starts_with('-') {
        return Err(GitError::NonZero {
            code: None,
            stderr: format!("ref `{candidate}` looks like a flag; refusing to pass it to git"),
        });
    }
    Ok(())
}

/// Output mode: just the paths.
const NAMES: &str = "--name-only";

/// Files changed on this branch relative to `git_ref`, relative to `root`.
///
/// Three-dot diff (`<ref>...HEAD`) is the merge-base diff — *what my branch
/// changed*. Two-dot would also report everything that landed on the other
/// branch since the fork, which would gate a push on files the author never
/// touched.
///
/// `git_ref` is the same string the user typed: a branch name, a SHA, or a
/// remote-tracking ref like `origin/main`. A ref that does not exist makes
/// git exit non-zero, and that surfaces here as `Err(GitError::NonZero)`
/// rather than an empty Vec — see the module docs.
pub async fn changed_since(root: &Path, git_ref: &str) -> Result<Vec<PathBuf>, GitError> {
    let (names, prefix) =
        tokio::join!(since_diff(root, git_ref, None, NAMES), working_prefix(root));
    Ok(paths_from(
        filter_paths(&names?, files::is_scan_target),
        &prefix?,
    ))
}

/// How many lines of unchanged context to request around each change.
///
/// Generous on purpose. The model has no parser and no whole-file view, so
/// this is the only thing giving it the surrounding function body to judge a
/// change against. git merges hunks whose context windows overlap, so a large
/// value cannot produce duplicate coverage of the same lines.
pub const CONTEXT_LINES: u32 = 20;

/// Hunks for the files staged for commit.
///
/// Same selection as `staged_files` — `--diff-filter=ACMRT`, empty-tree
/// fallback when there is no HEAD — but the diff itself rather than the
/// names. `CONTEXT_LINES` of context is requested so the model reading each
/// hunk has the surrounding function body to compare against.
pub async fn staged_hunks(root: &Path, wanted: fn(&Path) -> bool) -> Result<Vec<Hunk>, GitError> {
    let (diff, prefix) = staged_diff(root, &unified()).await?;
    Ok(hunks_from(hunks_for(&diff, wanted), &prefix))
}

/// The `--unified=N` flag, built from [`CONTEXT_LINES`].
fn unified() -> String {
    format!("--unified={CONTEXT_LINES}")
}

/// Parse a diff and keep only the hunks for the files the caller analyzes.
///
/// The file-class policy is applied here rather than inside the parser: which
/// files a command reviews is a product decision, and `hunks.rs` answers only
/// "what does this diff say". Same layer, and now same signature, as
/// `filter_paths` over `--name-only` output: both queries take the class from
/// their caller, so a command cannot get one of them right and the other
/// wrong.
fn hunks_for(diff_text: &str, wanted: fn(&Path) -> bool) -> Vec<Hunk> {
    let mut hunks = parse_unified_diff(diff_text);
    hunks.retain(|hunk| wanted(&hunk.file_path));
    hunks
}

/// Hunks for what this branch changed relative to `git_ref`.
///
/// Three-dot (`<ref>...HEAD`), matching `changed_since`: the merge-base diff,
/// so work that landed on the base branch after the fork is not attributed to
/// this branch. `CONTEXT_LINES` of context is requested so the model has
/// enough surrounding code to judge each change.
pub async fn hunks_since(
    root: &Path,
    git_ref: &str,
    wanted: fn(&Path) -> bool,
) -> Result<Vec<Hunk>, GitError> {
    hunks_between(root, git_ref, None, wanted).await
}

/// Hunks between `git_ref` and an explicit `tip`, or `HEAD` when `tip` is
/// `None`.
///
/// The tip exists for the pre-push hook. git hands a hook the ref being
/// pushed, which need not be the checked-out branch, and reviewing `HEAD`
/// instead means the pushed code is never seen - so the hook passes the ref's
/// own oid here.
pub async fn hunks_between(
    root: &Path,
    git_ref: &str,
    tip: Option<&str>,
    wanted: fn(&Path) -> bool,
) -> Result<Vec<Hunk>, GitError> {
    let unified = unified();
    let (diff, prefix) = tokio::join!(
        since_diff(root, git_ref, tip, &unified),
        working_prefix(root)
    );
    Ok(hunks_from(hunks_for(&diff?, wanted), &prefix?))
}

/// The current commit's SHA, with `"unknown"` on any failure.
///
/// Deliberately lossy: this is the cache-key component for repeated LLM
/// calls, and a cache-key component must never take analysis down. A hung
/// git is a real failure mode in CI containers; the 5s timeout plus the
/// "unknown" fallback means the worst case is a cache miss, not a gate
/// stall.
pub async fn current_commit_sha(root: &Path) -> String {
    let result = tokio::time::timeout(SHA_TIMEOUT, run_git(root, &["rev-parse", "HEAD"])).await;
    match result {
        Ok(Ok(sha)) => normalize_sha(sha),
        // Timed out, git failed, or git is absent. All mean the same thing to a
        // cache key.
        _ => UNKNOWN_SHA.to_owned(),
    }
}

/// The placeholder used whenever the real SHA cannot be determined.
pub(crate) const UNKNOWN_SHA: &str = "unknown";

/// Empty output is as useless as an error.
///
/// Split out from `current_commit_sha` so it is reachable from a test: the
/// empty-success case cannot be provoked through real git, which fails rather
/// than succeeding with no output. Previously the guard sat inline and no test
/// could distinguish it from an unconditional pass-through.
pub(crate) fn normalize_sha(sha: String) -> String {
    if sha.is_empty() {
        UNKNOWN_SHA.to_owned()
    } else {
        sha
    }
}

#[cfg(test)]
mod tests;