rustik_diff/decorate.rs
1//! Host-supplied decorations for diff files and hunks.
2//!
3//! The diff viewer is review-agnostic: it renders a parsed patch and knows
4//! nothing about approval state, comments, or any other host concept. A host
5//! application owns those concerns and feeds per-file and per-hunk decorations
6//! into the viewer through the [`DiffDecorator`] trait, which the renderer
7//! queries by [`FileId`] and [`HunkId`] while drawing each frame.
8
9use std::{cmp::Ordering, fmt};
10
11use rustik_tui as tui;
12use tui::{Line, Paint, Style};
13
14use crate::{FileId, FileStats, HunkId};
15
16/// Source of per-file and per-hunk decorations overlaid on a rendered diff.
17///
18/// Methods are queried during rendering, so they must be cheap and free of side
19/// effects. The default implementations return empty decorations, so a host
20/// only overrides the parts it uses.
21pub trait DiffDecorator: fmt::Debug + Send + Sync {
22 /// Returns the decoration for the given file's header row.
23 fn file(&self, file: FileId) -> FileDecoration {
24 let _ = file;
25 FileDecoration::default()
26 }
27
28 /// Returns the decoration for the given hunk.
29 fn hunk(&self, file: FileId, hunk: HunkId) -> HunkDecoration {
30 let _ = (file, hunk);
31 HunkDecoration::default()
32 }
33}
34
35/// Decoration overlaid on a file header row.
36///
37/// The header already renders an expand/collapse marker, the file path, an
38/// optional file-kind badge, and a right-aligned diffstat. A decoration adds a
39/// leading status glyph, extra right-aligned segments, and an optional
40/// replacement for the diffstat.
41#[derive(Clone, Debug, Default)]
42pub struct FileDecoration {
43 /// Status glyph inserted before the path, for example an approval marker.
44 pub status: Option<Paint<char>>,
45 /// Right-aligned segments shown before the diffstat, outermost first.
46 pub annotations: Vec<Line>,
47 /// Review progress shown in the file header.
48 pub progress: Option<ReviewProgress>,
49 /// Replacement for the computed addition and deletion counts, when set.
50 pub stats: Option<FileStats>,
51}
52
53/// Review progress over a fixed number of changed lines.
54#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
55pub struct ReviewProgress {
56 /// Number of accepted changed lines.
57 pub accepted: usize,
58 /// Total number of reviewable changed lines.
59 pub total: usize,
60}
61
62impl ReviewProgress {
63 /// Returns whether all reviewable changed lines have been accepted.
64 pub fn is_complete(self) -> bool {
65 self.total > 0 && self.accepted >= self.total
66 }
67
68 /// Returns the filled cell count for a progress bar of the given width.
69 ///
70 /// Rounds up so any nonzero progress is visible.
71 pub fn filled(self, width: usize) -> usize {
72 if self.total == 0 {
73 0
74 } else {
75 self.accepted
76 .saturating_mul(width)
77 .div_ceil(self.total)
78 .min(width)
79 }
80 }
81}
82
83impl Ord for ReviewProgress {
84 fn cmp(&self, other: &Self) -> Ordering {
85 match (self.total == 0, other.total == 0) {
86 (true, true) => self.accepted.cmp(&other.accepted),
87 (true, false) => Ordering::Greater,
88 (false, true) => Ordering::Less,
89 (false, false) => {
90 let left = (self.accepted as u128) * (other.total as u128);
91 let right = (other.accepted as u128) * (self.total as u128);
92
93 left.cmp(&right)
94 .then_with(|| self.accepted.cmp(&other.accepted))
95 .then_with(|| self.total.cmp(&other.total))
96 }
97 }
98 }
99}
100
101impl PartialOrd for ReviewProgress {
102 fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
103 Some(self.cmp(other))
104 }
105}
106
107/// Decoration overlaid on a hunk.
108///
109/// Decorations never add rows: the gutter and corner are drawn into existing
110/// body rows, and the style is composed onto those rows.
111#[derive(Clone, Debug, Default)]
112pub struct HunkDecoration {
113 /// Optional marker drawn in the gutter beside every hunk body row.
114 pub gutter: Option<Paint<char>>,
115 /// Markers drawn in the hunk's top-right corner.
116 pub corner: Line,
117 /// Style composed onto the hunk's body rows, used to mute approved or
118 /// otherwise inactive hunks.
119 pub style: Option<Style>,
120}