rustik-diff 0.3.0

Pure diff viewer and Git diff pager for Rustik.
Documentation
//! Host-supplied decorations for diff files and hunks.
//!
//! The diff viewer is review-agnostic: it renders a parsed patch and knows
//! nothing about approval state, comments, or any other host concept. A host
//! application owns those concerns and feeds per-file and per-hunk decorations
//! into the viewer through the [`DiffDecorator`] trait, which the renderer
//! queries by [`FileId`] and [`HunkId`] while drawing each frame.

use std::{cmp::Ordering, fmt};

use rustik_tui as tui;
use tui::{Line, Paint, Style};

use crate::{FileId, FileStats, HunkId};

/// Source of per-file and per-hunk decorations overlaid on a rendered diff.
///
/// Methods are queried during rendering, so they must be cheap and free of side
/// effects. The default implementations return empty decorations, so a host
/// only overrides the parts it uses.
pub trait DiffDecorator: fmt::Debug + Send + Sync {
    /// Returns the decoration for the given file's header row.
    fn file(&self, file: FileId) -> FileDecoration {
        let _ = file;
        FileDecoration::default()
    }

    /// Returns the decoration for the given hunk.
    fn hunk(&self, file: FileId, hunk: HunkId) -> HunkDecoration {
        let _ = (file, hunk);
        HunkDecoration::default()
    }
}

/// Decoration overlaid on a file header row.
///
/// The header already renders an expand/collapse marker, the file path, an
/// optional file-kind badge, and a right-aligned diffstat. A decoration adds a
/// leading status glyph, extra right-aligned segments, and an optional
/// replacement for the diffstat.
#[derive(Clone, Debug, Default)]
pub struct FileDecoration {
    /// Status glyph inserted before the path, for example an approval marker.
    pub status: Option<Paint<char>>,
    /// Right-aligned segments shown before the diffstat, outermost first.
    pub annotations: Vec<Line>,
    /// Review progress shown in the file header.
    pub progress: Option<ReviewProgress>,
    /// Replacement for the computed addition and deletion counts, when set.
    pub stats: Option<FileStats>,
}

/// Review progress over a fixed number of changed lines.
#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
pub struct ReviewProgress {
    /// Number of accepted changed lines.
    pub accepted: usize,
    /// Total number of reviewable changed lines.
    pub total: usize,
}

impl ReviewProgress {
    /// Returns whether all reviewable changed lines have been accepted.
    pub fn is_complete(self) -> bool {
        self.total > 0 && self.accepted >= self.total
    }

    /// Returns the filled cell count for a progress bar of the given width.
    ///
    /// Rounds up so any nonzero progress is visible.
    pub fn filled(self, width: usize) -> usize {
        if self.total == 0 {
            0
        } else {
            self.accepted
                .saturating_mul(width)
                .div_ceil(self.total)
                .min(width)
        }
    }
}

impl Ord for ReviewProgress {
    fn cmp(&self, other: &Self) -> Ordering {
        match (self.total == 0, other.total == 0) {
            (true, true) => self.accepted.cmp(&other.accepted),
            (true, false) => Ordering::Greater,
            (false, true) => Ordering::Less,
            (false, false) => {
                let left = (self.accepted as u128) * (other.total as u128);
                let right = (other.accepted as u128) * (self.total as u128);

                left.cmp(&right)
                    .then_with(|| self.accepted.cmp(&other.accepted))
                    .then_with(|| self.total.cmp(&other.total))
            }
        }
    }
}

impl PartialOrd for ReviewProgress {
    fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
        Some(self.cmp(other))
    }
}

/// Decoration overlaid on a hunk.
///
/// Decorations never add rows: the gutter and corner are drawn into existing
/// body rows, and the style is composed onto those rows.
#[derive(Clone, Debug, Default)]
pub struct HunkDecoration {
    /// Optional marker drawn in the gutter beside every hunk body row.
    pub gutter: Option<Paint<char>>,
    /// Markers drawn in the hunk's top-right corner.
    pub corner: Line,
    /// Style composed onto the hunk's body rows, used to mute approved or
    /// otherwise inactive hunks.
    pub style: Option<Style>,
}