fallow_engine/

changed_files.rs

//! Changed-file helpers owned by the engine boundary.

use std::path::{Path, PathBuf};
use std::process::{Command, Output, Stdio};
use std::sync::OnceLock;

use fallow_types::{
    output_dead_code::{
        CircularDependencyFinding, DuplicateExportFinding, DuplicatePropShapeFinding,
        PropDrillingChainFinding, ReExportCycleFinding, UnlistedDependencyFinding,
    },
    results::{AnalysisResults, SecurityFinding},
};
use rustc_hash::FxHashSet;

use crate::duplicates::{self, DuplicationReport};

pub use crate::git_env::{AMBIENT_GIT_ENV_VARS, clear_ambient_git_env};

/// Function pointer signature used to intercept short-running git
/// subprocesses spawned by changed-file helpers.
pub type ChangedFilesSpawnHook = fn(&mut std::process::Command) -> std::io::Result<Output>;

static SPAWN_HOOK: OnceLock<ChangedFilesSpawnHook> = OnceLock::new();

/// Classification of a changed-file git failure.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ChangedFilesError {
    /// Git ref failed validation before invoking `git`.
    InvalidRef(String),
    /// `git` binary not found or not executable.
    GitMissing(String),
    /// Command ran but the directory is not a git repository.
    NotARepository,
    /// Command ran but the ref is invalid or another git error occurred.
    GitFailed(String),
}

impl ChangedFilesError {
    /// Human-readable clause suitable for embedding in an error message.
    #[must_use]
    pub fn describe(&self) -> String {
        match self {
            Self::InvalidRef(err) => format!("invalid git ref: {err}"),
            Self::GitMissing(err) => format!("failed to run git: {err}"),
            Self::NotARepository => "not a git repository".to_owned(),
            Self::GitFailed(stderr) => augment_git_failed(stderr),
        }
    }

    /// Stable kebab-case token naming this failure, for machine consumers.
    ///
    /// One token per variant, so a consumer can branch on the cause without
    /// matching prose. Published on the wire as
    /// `request_outcomes["changed-since"].reason`.
    #[must_use]
    pub const fn reason(&self) -> &'static str {
        match self {
            Self::InvalidRef(_) => "invalid-ref",
            Self::GitMissing(_) => "git-missing",
            Self::NotARepository => "not-a-repository",
            Self::GitFailed(_) => "git-failed",
        }
    }

    /// The full sentence for a run whose `--changed-since` request could not be
    /// applied: what was asked, what happened instead, and the next step.
    ///
    /// The one prose source for this fact. The CLI writes it to stderr and
    /// publishes the same string on the envelope, so a log a human read and a
    /// report a script read cannot say different things.
    ///
    /// Git's own stderr is folded onto one line: the sentence travels into a
    /// jq-rendered CI annotation and into a rendered pull-request comment, and
    /// a multi-line value there splits one fact across two log records.
    #[must_use]
    pub fn changed_since_message(&self, git_ref: &str) -> String {
        let cause = self
            .describe()
            .split_whitespace()
            .collect::<Vec<_>>()
            .join(" ");
        format!(
            "--changed-since '{git_ref}' was ignored because {cause}, so this report covers \
             the whole project instead of the changed files. {}",
            self.changed_since_remedy()
        )
    }

    /// The next step for [`Self::changed_since_message`], one per cause.
    const fn changed_since_remedy(&self) -> &'static str {
        match self {
            Self::InvalidRef(_) => {
                "Pass a ref git can resolve, such as a branch name or a commit sha."
            }
            Self::GitMissing(_) => {
                "Install git and make it available on PATH, or drop --changed-since."
            }
            Self::NotARepository => {
                "Run fallow from inside the repository, or drop --changed-since."
            }
            Self::GitFailed(_) => {
                "Verify the ref exists in this repository, and check out with full history."
            }
        }
    }
}

fn augment_git_failed(stderr: &str) -> String {
    let lower = stderr.to_ascii_lowercase();
    if lower.contains("not a valid object name")
        || lower.contains("unknown revision")
        || lower.contains("ambiguous argument")
    {
        format!(
            "{stderr} (shallow clone? try `git fetch --unshallow`, or set `fetch-depth: 0` on actions/checkout / `GIT_DEPTH: 0` in GitLab CI)"
        )
    } else {
        stderr.to_owned()
    }
}

/// Install a spawn-hook for changed-file git subprocesses.
pub fn set_spawn_hook(hook: ChangedFilesSpawnHook) {
    let _ = SPAWN_HOOK.set(hook);
}

/// Validate a user-supplied git ref before passing it to git.
pub(crate) fn validate_git_ref(s: &str) -> Result<&str, String> {
    if s.is_empty() {
        return Err("git ref cannot be empty".to_string());
    }
    if s.starts_with('-') {
        return Err("git ref cannot start with '-'".to_string());
    }
    let mut in_braces = false;
    for c in s.chars() {
        match c {
            '{' => in_braces = true,
            '}' => in_braces = false,
            ':' | ' ' if in_braces => {}
            c if c.is_ascii_alphanumeric()
                || matches!(c, '.' | '_' | '-' | '/' | '~' | '^' | '@' | '{' | '}') => {}
            _ => return Err(format!("git ref contains disallowed character: '{c}'")),
        }
    }
    if in_braces {
        return Err("git ref has unclosed '{'".to_string());
    }
    Ok(s)
}

/// Resolve the canonical git toplevel for `cwd`.
pub fn resolve_git_toplevel(cwd: &Path) -> Result<PathBuf, ChangedFilesError> {
    let output = spawn_output(&mut git_command(cwd, &["rev-parse", "--show-toplevel"]))
        .map_err(|e| ChangedFilesError::GitMissing(e.to_string()))?;

    if !output.status.success() {
        let stderr = String::from_utf8_lossy(&output.stderr);
        return Err(if stderr.contains("not a git repository") {
            ChangedFilesError::NotARepository
        } else {
            ChangedFilesError::GitFailed(stderr.trim().to_owned())
        });
    }

    let raw = String::from_utf8_lossy(&output.stdout);
    let trimmed = raw.trim();
    if trimmed.is_empty() {
        return Err(ChangedFilesError::GitFailed(
            "git rev-parse --show-toplevel returned empty output".to_owned(),
        ));
    }

    let path = PathBuf::from(trimmed);
    Ok(dunce::canonicalize(&path).unwrap_or(path))
}

/// Resolve the canonical git common directory for `cwd`.
pub fn resolve_git_common_dir(cwd: &Path) -> Result<PathBuf, ChangedFilesError> {
    let output = spawn_output(&mut git_command(
        cwd,
        &["rev-parse", "--path-format=absolute", "--git-common-dir"],
    ))
    .map_err(|e| ChangedFilesError::GitMissing(e.to_string()))?;

    if !output.status.success() {
        let stderr = String::from_utf8_lossy(&output.stderr);
        return Err(if stderr.contains("not a git repository") {
            ChangedFilesError::NotARepository
        } else {
            ChangedFilesError::GitFailed(stderr.trim().to_owned())
        });
    }

    let raw = String::from_utf8_lossy(&output.stdout);
    let trimmed = raw.trim();
    if trimmed.is_empty() {
        return Err(ChangedFilesError::GitFailed(
            "git rev-parse --git-common-dir returned empty output".to_owned(),
        ));
    }

    let path = PathBuf::from(trimmed);
    Ok(dunce::canonicalize(&path).unwrap_or(path))
}

/// Get files changed since a git ref.
fn try_get_changed_files(
    root: &Path,
    git_ref: &str,
) -> Result<FxHashSet<PathBuf>, ChangedFilesError> {
    validate_git_ref(git_ref).map_err(ChangedFilesError::InvalidRef)?;
    let toplevel = resolve_git_toplevel(root)?;
    try_get_changed_files_with_toplevel(root, &toplevel, git_ref)
}

/// Resolve changed files for a git ref relative to a project root.
///
/// # Errors
///
/// Returns an error when git cannot resolve the ref or repository state.
pub fn changed_files(root: &Path, git_ref: &str) -> Result<FxHashSet<PathBuf>, ChangedFilesError> {
    try_get_changed_files(root, git_ref)
}

/// Get changed files and the git toplevel used to resolve them.
pub fn try_get_changed_files_with_toplevel(
    cwd: &Path,
    toplevel: &Path,
    git_ref: &str,
) -> Result<FxHashSet<PathBuf>, ChangedFilesError> {
    validate_git_ref(git_ref).map_err(ChangedFilesError::InvalidRef)?;

    let mut files = collect_git_paths(
        cwd,
        toplevel,
        &[
            "diff",
            "--name-only",
            "-z",
            "--end-of-options",
            &format!("{git_ref}...HEAD"),
        ],
    )?;
    files.extend(collect_git_paths(
        cwd,
        toplevel,
        &["diff", "--name-only", "-z", "HEAD"],
    )?);
    files.extend(collect_git_paths(
        cwd,
        toplevel,
        &[
            "ls-files",
            "--full-name",
            "--others",
            "--exclude-standard",
            "-z",
        ],
    )?);
    Ok(files)
}

/// A file rename detected between a git ref's merge base and the working
/// tree, with absolute paths joined onto the git toplevel.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct RenamedFile {
    /// Absolute pre-rename path (exists in the base tree).
    pub from: PathBuf,
    /// Absolute post-rename path (exists in the current tree).
    pub to: PathBuf,
}

/// Detect renamed files between a git ref's merge base and the current tree.
///
/// Covers the committed range (`<ref>...HEAD`) plus renames staged against
/// `HEAD`, mirroring the tracked scope of [`try_get_changed_files_with_toplevel`].
/// A rename committed as `a -> b` and then staged as `b -> c` is composed into
/// one `a -> c` entry. Copies are intentionally not reported: a copy leaves
/// the original in place, so findings on the copy are genuinely new.
///
/// # Errors
///
/// Returns an error when git cannot resolve the ref or repository state.
pub fn try_get_renamed_files(
    root: &Path,
    git_ref: &str,
) -> Result<Vec<RenamedFile>, ChangedFilesError> {
    validate_git_ref(git_ref).map_err(ChangedFilesError::InvalidRef)?;
    let toplevel = resolve_git_toplevel(root)?;
    let mut renames = collect_git_rename_pairs(
        root,
        &toplevel,
        &[
            "diff",
            "--name-status",
            "-z",
            "--find-renames",
            "--end-of-options",
            &format!("{git_ref}...HEAD"),
        ],
    )?;
    let staged = collect_git_rename_pairs(
        root,
        &toplevel,
        &["diff", "--name-status", "-z", "--find-renames", "HEAD"],
    )?;
    for pair in staged {
        if let Some(chained) = renames.iter_mut().find(|rename| rename.to == pair.from) {
            chained.to = pair.to;
        } else {
            renames.push(pair);
        }
    }
    Ok(renames)
}

/// Run a `--name-status -z` diff and collect its `R` (rename) pairs.
///
/// The `-z` stream alternates status and path fields separated by NUL; rename
/// and copy statuses (`R<score>` / `C<score>`) carry two path fields (old then
/// new), every other status carries one.
fn collect_git_rename_pairs(
    cwd: &Path,
    toplevel: &Path,
    args: &[&str],
) -> Result<Vec<RenamedFile>, ChangedFilesError> {
    let output = spawn_output(&mut git_command(cwd, args))
        .map_err(|e| ChangedFilesError::GitMissing(e.to_string()))?;

    if !output.status.success() {
        return Err(changed_files_error_from_output(&output));
    }

    let mut fields = output
        .stdout
        .split(|byte| *byte == 0)
        .filter(|field| !field.is_empty());
    let mut renames = Vec::new();
    while let Some(status) = fields.next() {
        let Some(first_path) = fields.next() else {
            break;
        };
        match status.first() {
            Some(b'R') => {
                let Some(second_path) = fields.next() else {
                    break;
                };
                renames.push(RenamedFile {
                    from: toplevel.join(git_path_from_bytes(first_path)),
                    to: toplevel.join(git_path_from_bytes(second_path)),
                });
            }
            // Copies also carry two path fields but are conservatively treated
            // as new files, so only the extra field is consumed.
            Some(b'C') => {
                let _ = fields.next();
            }
            _ => {}
        }
    }
    Ok(renames)
}

/// Return the raw git diff from a ref's merge base through the working tree.
///
/// The result includes committed, staged, unstaged, and untracked changes so it
/// covers the same scope as `try_get_changed_files`.
pub fn try_get_changed_diff(root: &Path, git_ref: &str) -> Result<String, ChangedFilesError> {
    validate_git_ref(git_ref).map_err(ChangedFilesError::InvalidRef)?;
    let toplevel = resolve_git_toplevel(root)?;
    let merge_base_output = spawn_output(&mut git_command(root, &["merge-base", git_ref, "HEAD"]))
        .map_err(|e| ChangedFilesError::GitMissing(e.to_string()))?;
    if !merge_base_output.status.success() {
        return Err(changed_files_error_from_output(&merge_base_output));
    }
    let merge_base = String::from_utf8_lossy(&merge_base_output.stdout)
        .trim()
        .to_owned();
    if merge_base.is_empty() {
        return Err(ChangedFilesError::GitFailed(
            "git merge-base returned empty output".to_owned(),
        ));
    }

    let output = spawn_output(&mut git_command(
        root,
        &[
            "diff",
            "--relative",
            "--unified=0",
            "--end-of-options",
            &merge_base,
        ],
    ))
    .map_err(|e| ChangedFilesError::GitMissing(e.to_string()))?;

    if !output.status.success() {
        return Err(changed_files_error_from_output(&output));
    }

    let mut diff = String::from_utf8_lossy(&output.stdout).into_owned();
    append_untracked_diffs(root, &toplevel, &mut diff)?;
    Ok(diff)
}

fn append_untracked_diffs(
    root: &Path,
    toplevel: &Path,
    diff: &mut String,
) -> Result<(), ChangedFilesError> {
    let canonical_root = dunce::canonicalize(root).unwrap_or_else(|_| root.to_path_buf());
    let mut untracked: Vec<PathBuf> = collect_git_paths(
        root,
        toplevel,
        &[
            "ls-files",
            "--full-name",
            "--others",
            "--exclude-standard",
            "-z",
        ],
    )?
    .into_iter()
    .filter_map(|path| {
        path.strip_prefix(&canonical_root)
            .ok()
            .map(Path::to_path_buf)
    })
    .collect();
    untracked.sort_unstable();

    #[cfg(windows)]
    let empty_file = "NUL";
    #[cfg(not(windows))]
    let empty_file = "/dev/null";

    for path in untracked {
        let mut command = git_command(root, &["diff", "--no-index", "--unified=0", "--"]);
        command.arg(empty_file).arg(untracked_path_arg(&path));
        let output =
            spawn_output(&mut command).map_err(|e| ChangedFilesError::GitMissing(e.to_string()))?;
        if !output.status.success() && output.status.code() != Some(1) {
            return Err(changed_files_error_from_output(&output));
        }
        if !diff.is_empty() && !diff.ends_with('\n') {
            diff.push('\n');
        }
        diff.push_str(&String::from_utf8_lossy(&output.stdout));
    }
    Ok(())
}

/// Forward-slashed relative path for the `git diff --no-index` argument.
/// Passing the native form on Windows makes git echo backslashes into the
/// `+++ b/` header, so every consumer keyed on forward-slashed diff paths
/// (added-line lookups included) silently misses the file.
fn untracked_path_arg(path: &Path) -> String {
    path.to_string_lossy().replace('\\', "/")
}

fn changed_files_error_from_output(output: &Output) -> ChangedFilesError {
    let stderr = String::from_utf8_lossy(&output.stderr);
    if stderr.contains("not a git repository") {
        ChangedFilesError::NotARepository
    } else {
        ChangedFilesError::GitFailed(stderr.trim().to_owned())
    }
}

/// Get changed files if git can resolve them, otherwise return `None`.
#[must_use]
#[expect(
    clippy::print_stderr,
    reason = "intentional user-facing warning for the CLI's --changed-since fallback path; typed callers use try_get_changed_files instead"
)]
pub fn get_changed_files(root: &Path, git_ref: &str) -> Option<FxHashSet<PathBuf>> {
    match try_get_changed_files(root, git_ref) {
        Ok(files) => Some(files),
        Err(err) => {
            eprintln!("Warning: {}", err.changed_since_message(git_ref));
            None
        }
    }
}

fn spawn_output(command: &mut Command) -> std::io::Result<Output> {
    if let Some(hook) = SPAWN_HOOK.get() {
        hook(command)
    } else {
        command.output()
    }
}

fn collect_git_paths(
    cwd: &Path,
    toplevel: &Path,
    args: &[&str],
) -> Result<FxHashSet<PathBuf>, ChangedFilesError> {
    let output = spawn_output(&mut git_command(cwd, args))
        .map_err(|e| ChangedFilesError::GitMissing(e.to_string()))?;

    if !output.status.success() {
        let stderr = String::from_utf8_lossy(&output.stderr);
        return Err(if stderr.contains("not a git repository") {
            ChangedFilesError::NotARepository
        } else {
            ChangedFilesError::GitFailed(stderr.trim().to_owned())
        });
    }

    let files = output
        .stdout
        .split(|byte| *byte == 0)
        .filter(|path| !path.is_empty())
        .map(git_path_from_bytes)
        .map(|path| toplevel.join(path))
        .collect();

    Ok(files)
}

/// Decode one NUL-separated `git` output path into a `PathBuf`.
///
/// Unix keeps the raw bytes, so a non-UTF-8 tree path survives intact.
/// Shared with `crate::churn`, which decodes the same `git` byte output under
/// the same semantics.
#[cfg(unix)]
pub(crate) fn git_path_from_bytes(path: &[u8]) -> PathBuf {
    use std::ffi::OsString;
    use std::os::unix::ffi::OsStringExt;

    PathBuf::from(OsString::from_vec(path.to_vec()))
}

/// Windows counterpart: there is no byte-oriented `OsString`, so decode
/// lossily and rewrite to backslash separators.
#[cfg(windows)]
pub(crate) fn git_path_from_bytes(path: &[u8]) -> PathBuf {
    PathBuf::from(String::from_utf8_lossy(path).replace('/', "\\"))
}

#[expect(
    clippy::disallowed_methods,
    reason = "canonical engine-owned git spawn wrapper for changed-file orchestration"
)]
fn git_command(cwd: &Path, args: &[&str]) -> Command {
    let mut command = Command::new("git");
    clear_ambient_git_env(&mut command);
    // Changed-file probes are non-interactive and must not inherit protocol stdin.
    command.stdin(Stdio::null()).args(args).current_dir(cwd);
    command
}

/// Scope dead-code results to findings affected by changed files.
///
/// Dependency-level issues stay unfiltered because whether a dependency is
/// unused is a graph-global fact, not a changed-file-local fact.
#[expect(
    clippy::implicit_hasher,
    reason = "fallow standardizes on FxHashSet across the workspace"
)]
pub fn filter_results_by_changed_files(
    results: &mut AnalysisResults,
    changed_files: &FxHashSet<PathBuf>,
) {
    let cf = normalize_changed_files_set(changed_files);
    classify_changed_file_filter_fields(results);
    retain_basic_issue_findings_by_changed_path(results, &cf);
    retain_graph_findings_by_changed_files(results, &cf);
    retain_boundary_policy_and_suppression_findings(results, &cf);
    retain_security_and_workspace_findings(results, &cf);
    retain_framework_findings_by_changed_files(results, &cf);
}

fn classify_changed_file_filter_fields(results: &AnalysisResults) {
    let AnalysisResults {
        unused_files: _unused_files,
        unused_exports: _unused_exports,
        unused_types: _unused_types,
        private_type_leaks: _private_type_leaks,
        unused_dependencies: _unused_dependencies,
        unused_dev_dependencies: _unused_dev_dependencies,
        unused_optional_dependencies: _unused_optional_dependencies,
        unused_enum_members: _unused_enum_members,
        unused_class_members: _unused_class_members,
        unused_store_members: _unused_store_members,
        unresolved_imports: _unresolved_imports,
        unlisted_dependencies: _unlisted_dependencies,
        duplicate_exports: _duplicate_exports,
        type_only_dependencies: _type_only_dependencies,
        test_only_dependencies: _test_only_dependencies,
        dev_dependencies_in_production: _dev_dependencies_in_production,
        circular_dependencies: _circular_dependencies,
        re_export_cycles: _re_export_cycles,
        boundary_violations: _boundary_violations,
        boundary_coverage_violations: _boundary_coverage_violations,
        boundary_call_violations: _boundary_call_violations,
        policy_violations: _policy_violations,
        stale_suppressions: _stale_suppressions,
        unused_catalog_entries: _unused_catalog_entries,
        empty_catalog_groups: _empty_catalog_groups,
        unresolved_catalog_references: _unresolved_catalog_references,
        unused_dependency_overrides: _unused_dependency_overrides,
        misconfigured_dependency_overrides: _misconfigured_dependency_overrides,
        invalid_client_exports: _invalid_client_exports,
        mixed_client_server_barrels: _mixed_client_server_barrels,
        misplaced_directives: _misplaced_directives,
        unprovided_injects: _unprovided_injects,
        unrendered_components: _unrendered_components,
        route_collisions: _route_collisions,
        dynamic_segment_name_conflicts: _dynamic_segment_name_conflicts,
        unused_component_props: _unused_component_props,
        unused_component_emits: _unused_component_emits,
        unused_component_inputs: _unused_component_inputs,
        unused_component_outputs: _unused_component_outputs,
        unused_svelte_events: _unused_svelte_events,
        unused_server_actions: _unused_server_actions,
        unused_load_data_keys: _unused_load_data_keys,
        unused_load_data_keys_global_abstain: _unused_load_data_keys_global_abstain,
        prop_drilling_chains: _prop_drilling_chains,
        thin_wrappers: _thin_wrappers,
        duplicate_prop_shapes: _duplicate_prop_shapes,
        suppression_count: _suppression_count,
        unused_component_props_exempted: _unused_component_props_exempted,
        active_suppressions: _active_suppressions,
        feature_flags: _feature_flags,
        security_findings: _security_findings,
        security_unresolved_edge_files: _security_unresolved_edge_files,
        security_unresolved_callee_sites: _security_unresolved_callee_sites,
        security_unresolved_callee_diagnostics: _security_unresolved_callee_diagnostics,
        export_usages: _export_usages,
        entry_point_summary: _entry_point_summary,
        render_fan_in: _render_fan_in,
        react_component_intel: _react_component_intel,
        semantic_framework_contracts: _semantic_framework_contracts,
    } = results;
}

fn retain_basic_issue_findings_by_changed_path(
    results: &mut AnalysisResults,
    changed_files: &FxHashSet<PathBuf>,
) {
    retain_by_changed_path(&mut results.unused_files, changed_files, |f| &f.file.path);
    retain_by_changed_path(&mut results.unused_exports, changed_files, |e| {
        &e.export.path
    });
    retain_by_changed_path(&mut results.unused_types, changed_files, |e| &e.export.path);
    retain_by_changed_path(&mut results.private_type_leaks, changed_files, |e| {
        &e.leak.path
    });
    retain_by_changed_path(&mut results.unused_enum_members, changed_files, |m| {
        &m.member.path
    });
    retain_by_changed_path(&mut results.unused_class_members, changed_files, |m| {
        &m.member.path
    });
    retain_by_changed_path(&mut results.unused_store_members, changed_files, |m| {
        &m.member.path
    });
    retain_by_changed_path(&mut results.unresolved_imports, changed_files, |i| {
        &i.import.path
    });
}

fn retain_graph_findings_by_changed_files(
    results: &mut AnalysisResults,
    changed_files: &FxHashSet<PathBuf>,
) {
    retain_unlisted_dependencies_by_import_site(&mut results.unlisted_dependencies, changed_files);
    retain_duplicate_exports_by_changed_locations(&mut results.duplicate_exports, changed_files);
    retain_circular_dependencies_by_changed_file(&mut results.circular_dependencies, changed_files);
    retain_re_export_cycles_by_changed_file(&mut results.re_export_cycles, changed_files);
}

fn retain_boundary_policy_and_suppression_findings(
    results: &mut AnalysisResults,
    changed_files: &FxHashSet<PathBuf>,
) {
    retain_by_changed_path(&mut results.boundary_violations, changed_files, |v| {
        &v.violation.from_path
    });
    retain_by_changed_path(
        &mut results.boundary_coverage_violations,
        changed_files,
        |v| &v.violation.path,
    );
    retain_by_changed_path(&mut results.boundary_call_violations, changed_files, |v| {
        &v.violation.path
    });
    retain_by_changed_path(&mut results.policy_violations, changed_files, |v| {
        &v.violation.path
    });
    retain_by_changed_path(&mut results.stale_suppressions, changed_files, |s| &s.path);
}

fn retain_security_and_workspace_findings(
    results: &mut AnalysisResults,
    changed_files: &FxHashSet<PathBuf>,
) {
    retain_security_findings_by_changed_path(&mut results.security_findings, changed_files);
    retain_by_changed_path(
        &mut results.security_unresolved_callee_diagnostics,
        changed_files,
        |d| &d.path,
    );
    retain_by_changed_path(
        &mut results.unresolved_catalog_references,
        changed_files,
        |r| &r.reference.path,
    );
    results
        .empty_catalog_groups
        .retain(|g| normalized_set_contains_path(changed_files, &g.group.path));
    retain_by_changed_path(
        &mut results.unused_dependency_overrides,
        changed_files,
        |o| &o.entry.path,
    );
    retain_by_changed_path(
        &mut results.misconfigured_dependency_overrides,
        changed_files,
        |o| &o.entry.path,
    );
}

fn retain_framework_findings_by_changed_files(
    results: &mut AnalysisResults,
    changed_files: &FxHashSet<PathBuf>,
) {
    retain_client_boundary_findings_by_changed_files(results, changed_files);
    retain_component_contract_findings_by_changed_files(results, changed_files);
    retain_react_health_findings_by_changed_files(results, changed_files);
    retain_nextjs_findings_by_changed_files(results, changed_files);
}

fn retain_client_boundary_findings_by_changed_files(
    results: &mut AnalysisResults,
    changed_files: &FxHashSet<PathBuf>,
) {
    let AnalysisResults {
        invalid_client_exports,
        mixed_client_server_barrels,
        misplaced_directives,
        ..
    } = results;

    retain_by_changed_path(invalid_client_exports, changed_files, |e| &e.export.path);
    retain_by_changed_path(mixed_client_server_barrels, changed_files, |b| {
        &b.barrel.path
    });
    retain_by_changed_path(misplaced_directives, changed_files, |d| {
        &d.directive_site.path
    });
}

fn retain_component_contract_findings_by_changed_files(
    results: &mut AnalysisResults,
    changed_files: &FxHashSet<PathBuf>,
) {
    let AnalysisResults {
        unprovided_injects,
        unrendered_components,
        unused_component_props,
        unused_component_emits,
        unused_component_inputs,
        unused_component_outputs,
        unused_svelte_events,
        unused_server_actions,
        unused_load_data_keys,
        ..
    } = results;

    retain_by_changed_path(unprovided_injects, changed_files, |i| &i.inject.path);
    retain_by_changed_path(unrendered_components, changed_files, |c| &c.component.path);
    retain_by_changed_path(unused_component_props, changed_files, |p| &p.prop.path);
    retain_by_changed_path(unused_component_emits, changed_files, |e| &e.emit.path);
    retain_by_changed_path(unused_component_inputs, changed_files, |i| &i.input.path);
    retain_by_changed_path(unused_component_outputs, changed_files, |o| &o.output.path);
    retain_by_changed_path(unused_svelte_events, changed_files, |e| &e.event.path);
    retain_by_changed_path(unused_server_actions, changed_files, |a| &a.action.path);
    retain_by_changed_path(unused_load_data_keys, changed_files, |k| &k.key.path);
}

fn retain_react_health_findings_by_changed_files(
    results: &mut AnalysisResults,
    changed_files: &FxHashSet<PathBuf>,
) {
    let AnalysisResults {
        prop_drilling_chains,
        thin_wrappers,
        duplicate_prop_shapes,
        ..
    } = results;

    retain_prop_drilling_chains_by_anchor(prop_drilling_chains, changed_files);
    retain_by_changed_path(thin_wrappers, changed_files, |w| &w.wrapper.file);
    retain_duplicate_prop_shapes_by_anchor(duplicate_prop_shapes, changed_files);
}

fn retain_nextjs_findings_by_changed_files(
    results: &mut AnalysisResults,
    changed_files: &FxHashSet<PathBuf>,
) {
    let AnalysisResults {
        route_collisions,
        dynamic_segment_name_conflicts,
        ..
    } = results;

    retain_by_changed_path(route_collisions, changed_files, |c| &c.collision.path);
    retain_by_changed_path(dynamic_segment_name_conflicts, changed_files, |c| {
        &c.conflict.path
    });
}

fn retain_unlisted_dependencies_by_import_site(
    dependencies: &mut Vec<UnlistedDependencyFinding>,
    changed_files: &FxHashSet<PathBuf>,
) {
    dependencies.retain(|dependency| {
        dependency
            .dep
            .imported_from
            .iter()
            .any(|site| contains_normalized(changed_files, &site.path))
    });
}

fn retain_duplicate_exports_by_changed_locations(
    duplicate_exports: &mut Vec<DuplicateExportFinding>,
    changed_files: &FxHashSet<PathBuf>,
) {
    for duplicate in &mut *duplicate_exports {
        duplicate
            .export
            .locations
            .retain(|location| contains_normalized(changed_files, &location.path));
    }
    duplicate_exports.retain(|duplicate| duplicate.export.locations.len() >= 2);
}

fn retain_circular_dependencies_by_changed_file(
    cycles: &mut Vec<CircularDependencyFinding>,
    changed_files: &FxHashSet<PathBuf>,
) {
    cycles.retain(|cycle| {
        cycle
            .cycle
            .files
            .iter()
            .any(|file| contains_normalized(changed_files, file))
    });
}

fn retain_re_export_cycles_by_changed_file(
    cycles: &mut Vec<ReExportCycleFinding>,
    changed_files: &FxHashSet<PathBuf>,
) {
    cycles.retain(|cycle| {
        cycle
            .cycle
            .files
            .iter()
            .any(|file| contains_normalized(changed_files, file))
    });
}

fn retain_security_findings_by_changed_path(
    findings: &mut Vec<SecurityFinding>,
    changed_files: &FxHashSet<PathBuf>,
) {
    findings.retain(|finding| security_finding_touches_changed_path(finding, changed_files));
}

fn retain_prop_drilling_chains_by_anchor(
    chains: &mut Vec<PropDrillingChainFinding>,
    changed_files: &FxHashSet<PathBuf>,
) {
    chains.retain(|chain| {
        chain
            .chain
            .hops
            .first()
            .is_some_and(|hop| contains_normalized(changed_files, &hop.file))
    });
}

fn retain_duplicate_prop_shapes_by_anchor(
    shapes: &mut Vec<DuplicatePropShapeFinding>,
    changed_files: &FxHashSet<PathBuf>,
) {
    retain_by_changed_path(shapes, changed_files, |shape| &shape.shape.file);
}

fn retain_by_changed_path<T>(
    items: &mut Vec<T>,
    changed_files: &FxHashSet<PathBuf>,
    path: impl Fn(&T) -> &Path,
) {
    items.retain(|item| contains_normalized(changed_files, path(item)));
}

fn security_finding_touches_changed_path(
    finding: &SecurityFinding,
    changed_files: &FxHashSet<PathBuf>,
) -> bool {
    contains_normalized(changed_files, &finding.path)
        || finding
            .trace
            .iter()
            .any(|hop| contains_normalized(changed_files, &hop.path))
        || finding.reachability.as_ref().is_some_and(|reachability| {
            reachability
                .untrusted_source_trace
                .iter()
                .any(|hop| contains_normalized(changed_files, &hop.path))
        })
}

fn normalize_changed_files_set(changed_files: &FxHashSet<PathBuf>) -> FxHashSet<PathBuf> {
    changed_files
        .iter()
        .map(|p| dunce::simplified(p).to_path_buf())
        .collect()
}

fn contains_normalized(normalized: &FxHashSet<PathBuf>, path: &Path) -> bool {
    normalized.contains(dunce::simplified(path))
}

fn normalized_set_contains_path(normalized: &FxHashSet<PathBuf>, path: &Path) -> bool {
    contains_normalized(normalized, path)
        || (path.is_relative() && normalized.iter().any(|changed| changed.ends_with(path)))
}

/// Scope duplication groups to clone groups touching at least one changed file.
#[expect(
    clippy::implicit_hasher,
    reason = "fallow standardizes on FxHashSet across the workspace"
)]
pub fn filter_duplication_by_changed_files(
    report: &mut DuplicationReport,
    changed_files: &FxHashSet<PathBuf>,
    root: &Path,
) {
    let cf = normalize_changed_files_set(changed_files);
    report.clone_groups.retain(|group| {
        group
            .instances
            .iter()
            .any(|instance| contains_normalized(&cf, &instance.file))
    });
    duplicates::refresh_clone_families(report, root);
    report.stats = duplicates::recompute_stats(report);
}

#[cfg(test)]
mod tests {
    use super::*;
    use fallow_types::{
        duplicates::{CloneGroup, CloneInstance, DuplicationStats},
        output_dead_code::{
            EmptyCatalogGroupFinding, UnusedDependencyFinding, UnusedExportFinding,
            UnusedFileFinding,
        },
        results::{
            DependencyLocation, EmptyCatalogGroup, UnusedDependency, UnusedExport, UnusedFile,
        },
    };

    #[test]
    fn validate_git_ref_rejects_option_like_ref() {
        assert!(validate_git_ref("--upload-pack=evil").is_err());
        assert!(validate_git_ref("-flag").is_err());
    }

    #[test]
    fn validate_git_ref_allows_reflog_relative_date() {
        assert!(validate_git_ref("HEAD@{1 week ago}").is_ok());
    }

    /// One reason token per cause, because each carries a different remedy and
    /// a consumer branches on the token rather than on the prose.
    #[test]
    fn every_changed_files_cause_reports_its_own_reason() {
        let reasons = [
            ChangedFilesError::InvalidRef("unclosed brace".to_owned()).reason(),
            ChangedFilesError::GitMissing("no such file".to_owned()).reason(),
            ChangedFilesError::NotARepository.reason(),
            ChangedFilesError::GitFailed("unknown revision".to_owned()).reason(),
        ];
        assert_eq!(
            reasons,
            [
                "invalid-ref",
                "git-missing",
                "not-a-repository",
                "git-failed"
            ]
        );
        let unique: std::collections::BTreeSet<&str> = reasons.iter().copied().collect();
        assert_eq!(
            unique.len(),
            reasons.len(),
            "two causes must not share a token"
        );
    }

    /// The published sentence and the stderr line are the same string, so the
    /// remedy cannot drift between a log a human read and a report a script
    /// read. It names the ref, says the report widened, and ends with a next
    /// step.
    #[test]
    fn the_changed_since_message_names_the_ref_the_widening_and_the_next_step() {
        let message = ChangedFilesError::NotARepository.changed_since_message("origin/main");
        assert!(
            message.contains("--changed-since 'origin/main'"),
            "{message}"
        );
        assert!(message.contains("covers the whole project"), "{message}");
        assert!(message.ends_with("or drop --changed-since."), "{message}");
    }

    /// Git writes multi-line stderr, and the sentence travels into a CI
    /// annotation and a rendered comment where a newline splits one fact
    /// across two records.
    #[test]
    fn the_changed_since_message_folds_git_stderr_onto_one_line() {
        let message = ChangedFilesError::GitFailed(
            "fatal: ambiguous argument 'x'\nUse '--' to separate paths".to_owned(),
        )
        .changed_since_message("x");
        assert!(!message.contains('\n'), "{message}");
        assert!(
            message.contains("ambiguous argument 'x' Use '--'"),
            "{message}"
        );
    }

    #[test]
    fn git_command_clears_parent_git_environment() {
        let command = git_command(Path::new("."), &["status"]);
        let envs: Vec<_> = command.get_envs().collect();

        for var in AMBIENT_GIT_ENV_VARS {
            assert!(
                envs.iter()
                    .any(|(key, value)| key.to_str() == Some(*var) && value.is_none()),
                "{var} should be cleared from the command env",
            );
        }
    }

    #[test]
    fn try_get_changed_files_not_a_repository() {
        let temp = tempfile::tempdir().expect("tempdir");
        let result = try_get_changed_files(temp.path(), "main");
        assert!(matches!(result, Err(ChangedFilesError::NotARepository)));
    }

    #[cfg(unix)]
    #[test]
    fn changed_files_preserve_special_filenames() {
        let repo = tempfile::tempdir().expect("tempdir");
        for args in [
            &["init", "--quiet"][..],
            &["config", "user.email", "test@example.com"][..],
            &["config", "user.name", "Test User"][..],
            &["config", "commit.gpgsign", "false"][..],
        ] {
            run_git(repo.path(), args);
        }
        std::fs::write(repo.path().join("initial.ts"), "initial\n").expect("initial fixture");
        run_git(repo.path(), &["add", "."]);
        run_git(repo.path(), &["commit", "--quiet", "-m", "initial"]);
        run_git(repo.path(), &["tag", "base"]);

        let canonical_root = repo.path().canonicalize().expect("canonical repo");
        let special_files = [
            "src/line\nbreak.ts",
            "src/space name.ts",
            "src/quote\"name.ts",
            "src/back\\slash.ts",
            "src/unicode-λ.ts",
        ]
        .map(|path| canonical_root.join(path));
        std::fs::create_dir_all(canonical_root.join("src")).expect("source dir");
        for special in &special_files {
            std::fs::write(special, "changed\n").expect("special fixture");
        }

        let changed = try_get_changed_files(repo.path(), "base").expect("changed files");
        for special in special_files {
            assert!(
                changed.contains(&special),
                "missing {special:?}: {changed:?}"
            );
        }
    }

    #[cfg(windows)]
    #[test]
    fn git_path_bytes_use_windows_separators() {
        assert_eq!(
            git_path_from_bytes(b"src/nested/file.ts"),
            PathBuf::from(r"src\nested\file.ts")
        );
    }

    #[test]
    fn changed_diff_covers_staged_unstaged_and_untracked_files() {
        let repo = tempfile::tempdir().expect("tempdir");
        for args in [
            &["init", "--quiet"][..],
            &["config", "user.email", "test@example.com"][..],
            &["config", "user.name", "Test User"][..],
            &["config", "commit.gpgsign", "false"][..],
        ] {
            run_git(repo.path(), args);
        }
        std::fs::write(repo.path().join("staged.ts"), "old\n").expect("staged fixture");
        std::fs::write(repo.path().join("unstaged.ts"), "old\n").expect("unstaged fixture");
        run_git(repo.path(), &["add", "."]);
        run_git(repo.path(), &["commit", "--quiet", "-m", "initial"]);
        run_git(repo.path(), &["tag", "base"]);

        std::fs::write(repo.path().join("committed.ts"), "committed\n").expect("committed fixture");
        run_git(repo.path(), &["add", "committed.ts"]);
        run_git(
            repo.path(),
            &["commit", "--quiet", "-m", "committed change"],
        );

        std::fs::write(repo.path().join("staged.ts"), "staged\n").expect("staged edit");
        run_git(repo.path(), &["add", "staged.ts"]);
        std::fs::write(repo.path().join("unstaged.ts"), "unstaged\n").expect("unstaged edit");
        std::fs::write(repo.path().join("untracked.ts"), "untracked\n").expect("untracked edit");

        let diff = try_get_changed_diff(repo.path(), "base").expect("complete changeset diff");
        let index = fallow_output::DiffIndex::from_unified_diff(&diff);

        assert!(diff.contains("b/committed.ts"), "{diff}");
        assert!(diff.contains("b/staged.ts"), "{diff}");
        assert!(diff.contains("b/unstaged.ts"), "{diff}");
        assert!(diff.contains("b/untracked.ts"), "{diff}");
        assert_eq!(index.hunk_count(), 4);
        assert_eq!(index.net_lines(), 2);
    }

    fn run_git(root: &Path, args: &[&str]) {
        let output = spawn_output(&mut git_command(root, args)).expect("git command");
        assert!(
            output.status.success(),
            "git {args:?} failed: {}",
            String::from_utf8_lossy(&output.stderr)
        );
    }

    #[test]
    fn untracked_path_arg_uses_forward_slashes() {
        assert_eq!(
            super::untracked_path_arg(Path::new("src\\nested\\b.ts")),
            "src/nested/b.ts"
        );
        assert_eq!(super::untracked_path_arg(Path::new("src/b.ts")), "src/b.ts");
    }

    #[test]
    fn changed_files_error_describe_matches_core_contract() {
        assert_eq!(
            ChangedFilesError::InvalidRef("bad ref".to_string()).describe(),
            "invalid git ref: bad ref"
        );
        assert_eq!(
            ChangedFilesError::GitMissing("not found".to_string()).describe(),
            "failed to run git: not found"
        );
        assert_eq!(
            ChangedFilesError::NotARepository.describe(),
            "not a git repository"
        );
        assert!(
            ChangedFilesError::GitFailed("unknown revision main".to_string())
                .describe()
                .contains("fetch-depth: 0")
        );
    }

    #[test]
    fn filter_results_keeps_only_changed_file_findings() {
        let mut results = AnalysisResults::default();
        results
            .unused_files
            .push(UnusedFileFinding::with_actions(UnusedFile {
                path: PathBuf::from("/repo/a.ts"),
            }));
        results
            .unused_files
            .push(UnusedFileFinding::with_actions(UnusedFile {
                path: PathBuf::from("/repo/b.ts"),
            }));
        results
            .unused_exports
            .push(UnusedExportFinding::with_actions(UnusedExport {
                path: PathBuf::from("/repo/a.ts"),
                export_name: "foo".to_owned(),
                is_type_only: false,
                line: 1,
                col: 0,
                span_start: 0,
                is_re_export: false,
            }));

        let mut changed = FxHashSet::default();
        changed.insert(PathBuf::from("/repo/a.ts"));

        filter_results_by_changed_files(&mut results, &changed);

        assert_eq!(results.unused_files.len(), 1);
        assert_eq!(
            results.unused_files[0].file.path,
            PathBuf::from("/repo/a.ts")
        );
        assert_eq!(results.unused_exports.len(), 1);
    }

    #[test]
    fn filter_results_preserves_graph_global_dependency_findings() {
        let mut results = AnalysisResults::default();
        results
            .unused_dependencies
            .push(UnusedDependencyFinding::with_actions(UnusedDependency {
                package_name: "lodash".to_owned(),
                location: DependencyLocation::Dependencies,
                path: PathBuf::from("/repo/package.json"),
                line: 3,
                used_in_workspaces: Vec::new(),
            }));

        let changed = FxHashSet::default();
        filter_results_by_changed_files(&mut results, &changed);

        assert_eq!(results.unused_dependencies.len(), 1);
    }

    #[test]
    fn filter_results_keeps_relative_manifest_finding_when_manifest_changed() {
        let mut results = AnalysisResults::default();
        results
            .empty_catalog_groups
            .push(EmptyCatalogGroupFinding::with_actions(EmptyCatalogGroup {
                catalog_name: "legacy".to_owned(),
                path: PathBuf::from("pnpm-workspace.yaml"),
                line: 4,
            }));

        let mut changed = FxHashSet::default();
        changed.insert(PathBuf::from("/repo/pnpm-workspace.yaml"));

        filter_results_by_changed_files(&mut results, &changed);

        assert_eq!(results.empty_catalog_groups.len(), 1);
    }

    #[test]
    fn filter_duplication_keeps_groups_with_changed_instances_and_recomputes_stats() {
        let mut report = DuplicationReport {
            clone_groups: vec![
                CloneGroup {
                    instances: vec![
                        CloneInstance {
                            file: PathBuf::from("/repo/a.ts"),
                            start_line: 1,
                            end_line: 5,
                            start_col: 0,
                            end_col: 10,
                            fragment: "code".to_owned(),
                        },
                        CloneInstance {
                            file: PathBuf::from("/repo/b.ts"),
                            start_line: 1,
                            end_line: 5,
                            start_col: 0,
                            end_col: 10,
                            fragment: "code".to_owned(),
                        },
                    ],
                    token_count: 20,
                    line_count: 5,
                    similarity: None,
                },
                CloneGroup {
                    instances: vec![
                        CloneInstance {
                            file: PathBuf::from("/repo/c.ts"),
                            start_line: 1,
                            end_line: 5,
                            start_col: 0,
                            end_col: 10,
                            fragment: "other".to_owned(),
                        },
                        CloneInstance {
                            file: PathBuf::from("/repo/d.ts"),
                            start_line: 1,
                            end_line: 5,
                            start_col: 0,
                            end_col: 10,
                            fragment: "other".to_owned(),
                        },
                    ],
                    token_count: 20,
                    line_count: 5,
                    similarity: None,
                },
            ],
            clone_families: Vec::new(),
            mirrored_directories: Vec::new(),
            stats: DuplicationStats {
                total_files: 4,
                files_with_clones: 4,
                total_lines: 100,
                duplicated_lines: 20,
                total_tokens: 200,
                duplicated_tokens: 80,
                clone_groups: 2,
                clone_families: 0,
                clone_instances: 4,
                duplication_percentage: 20.0,
                clone_groups_below_min_occurrences: 0,
                clone_groups_ignored: 0,
                near_candidates_skipped: 0,
            },
        };

        let mut changed = FxHashSet::default();
        changed.insert(PathBuf::from("/repo/a.ts"));

        filter_duplication_by_changed_files(&mut report, &changed, Path::new("/repo"));

        assert_eq!(report.clone_groups.len(), 1);
        assert_eq!(report.stats.clone_groups, 1);
        assert_eq!(report.stats.clone_instances, 2);
    }
}