Skip to main content

rustik_diff/
highlight.rs

1//! Highlight request and result protocol for diff rendering.
2
3use std::collections::{BTreeMap, hash_map::DefaultHasher};
4use std::hash::{Hash, Hasher};
5use std::path::PathBuf;
6use std::sync::Arc;
7
8use rustik_highlight as syntax;
9use rustik_tui as tui;
10use rustik_tui::{Color, Label, Line, Style};
11
12use crate::{DiffLine, FileDiff, FileId, Hunk, HunkId, RowId};
13
14/// Side of the diff used as syntax-highlighting source context.
15#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
16pub enum DiffSide {
17    /// Old side of a deleted or context line.
18    Old,
19    /// New side of an added or context line.
20    New,
21}
22
23/// Cache key for one highlighted diff row.
24#[derive(Clone, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
25pub struct HighlightKey {
26    /// File containing the row.
27    pub file: FileId,
28    /// Diff side to highlight.
29    pub side: DiffSide,
30    /// One-based source line number.
31    pub source_line: u32,
32    /// Hash of the row text.
33    pub text_hash: u64,
34    /// Syntax key or `auto`.
35    pub syntax: String,
36    /// Theme key.
37    pub theme: String,
38}
39
40/// Request sent from a visible diff viewport to a highlighter.
41#[derive(Clone, Debug, Eq, PartialEq)]
42pub struct HighlightRequest {
43    /// Stable cache key for this request.
44    pub key: HighlightKey,
45    /// Hunk containing the row.
46    pub hunk: HunkId,
47    /// Row to highlight.
48    pub row: RowId,
49    /// Source path used for syntax inference.
50    pub path: Option<PathBuf>,
51    /// Source-side text used for range highlighting.
52    pub source: HighlightSource,
53}
54
55/// Highlighted line returned by a worker.
56#[derive(Clone, Debug)]
57pub struct HighlightResult {
58    /// Cache key copied from the original request.
59    pub key: HighlightKey,
60    /// Hunk containing the highlighted row.
61    pub hunk: HunkId,
62    /// Highlighted row.
63    pub row: RowId,
64    /// Renderable highlighted line.
65    pub line: tui::Line,
66}
67
68/// File-side source text used to highlight a diff row with surrounding context.
69#[derive(Clone, Debug, Eq, PartialEq)]
70pub struct HighlightSource {
71    /// Source-side text assembled from the diff.
72    pub text: Arc<str>,
73    /// Source line represented by the head of [`HighlightSource::text`].
74    pub head: u32,
75}
76
77/// Pure built-in highlighter for visible diff rows.
78#[derive(Debug)]
79pub struct BuiltinHighlighter {
80    /// Grammar and theme registry.
81    registry: syntax::Registry,
82    /// Theme used when requests ask for automatic theme selection.
83    default_theme: String,
84    /// Per-source tokenizer caches reused across batches.
85    blob_caches: BTreeMap<BlobCacheKey, BlobCacheEntry>,
86}
87
88/// Identifier for cached blob-highlight state.
89#[derive(Clone, Debug, Eq, Ord, PartialEq, PartialOrd)]
90struct BlobCacheKey {
91    /// Grammar name used to tokenize the source.
92    grammar: String,
93    /// Address of the cached source allocation.
94    text_ptr: usize,
95    /// Length of the cached source allocation.
96    text_len: usize,
97}
98
99/// Cached tokenizer state for one source allocation.
100#[derive(Debug)]
101struct BlobCacheEntry {
102    /// Source owner that keeps the cached allocation pinned.
103    _source: Arc<str>,
104    /// Per-line parser state and scope cache.
105    cache: syntax::BlobCache,
106}
107
108/// Highlights diff rows requested by a [`crate::DiffViewer`].
109pub trait DiffHighlighter {
110    /// Highlights one batch of visible diff rows.
111    fn highlight_batch(&mut self, requests: Vec<HighlightRequest>) -> Vec<HighlightResult>;
112}
113
114/// Grouping key for requests that can share one range highlighter.
115#[derive(Clone, Debug, Eq, Ord, PartialEq, PartialOrd)]
116struct HighlightBatchKey {
117    /// File containing the requested rows.
118    file: FileId,
119    /// Source side containing the requested rows.
120    side: DiffSide,
121    /// Syntax key requested by the viewer.
122    syntax: String,
123    /// Theme key requested by the viewer.
124    theme: String,
125    /// Path used for syntax inference.
126    path: Option<PathBuf>,
127    /// Source allocation identity.
128    source: HighlightSourceId,
129}
130
131/// Allocation identity for source text shared by highlight requests.
132#[derive(Clone, Copy, Debug, Eq, Ord, PartialEq, PartialOrd)]
133struct HighlightSourceId {
134    /// Address of the source text allocation.
135    ptr: usize,
136    /// Length of the source text allocation.
137    len: usize,
138    /// Source line represented by the head of the source text.
139    head: u32,
140}
141
142impl HighlightKey {
143    /// Creates a key for a row of source text.
144    pub fn new(input: HighlightKeyInput<'_>) -> Self {
145        let mut hasher = DefaultHasher::new();
146        input.text.hash(&mut hasher);
147
148        Self {
149            file: input.file,
150            side: input.side,
151            source_line: input.source_line,
152            text_hash: hasher.finish(),
153            syntax: input.syntax.unwrap_or("auto").to_owned(),
154            theme: input.theme.to_owned(),
155        }
156    }
157}
158
159impl HighlightSource {
160    /// Creates source text beginning at a source line.
161    pub fn new(text: impl Into<Arc<str>>, head: u32) -> Self {
162        Self {
163            text: text.into(),
164            head,
165        }
166    }
167
168    /// Returns the zero-based source-text line index for a source line.
169    pub fn line_index(&self, source_line: u32) -> Option<usize> {
170        source_line.checked_sub(self.head).map(|line| line as usize)
171    }
172
173    /// Returns one source line without its trailing line terminator.
174    pub fn line(&self, source_line: u32) -> Option<&str> {
175        self.line_index(source_line)
176            .and_then(|index| self.text.lines().nth(index))
177    }
178
179    /// Returns a compact identity for grouping requests that share this source.
180    fn id(&self) -> HighlightSourceId {
181        HighlightSourceId {
182            ptr: self.text.as_ptr() as usize,
183            len: self.text.len(),
184            head: self.head,
185        }
186    }
187}
188
189impl Hunk {
190    /// Builds contiguous source text for one hunk side.
191    pub fn highlight_source(&self, side: DiffSide) -> HighlightSource {
192        let text = side_lines(self, side).collect::<Vec<_>>().join("\n");
193        HighlightSource::new(text, hunk_head(self, side))
194    }
195}
196
197impl FileDiff {
198    /// Returns the source path for a file side, falling back to the other side.
199    pub fn source_path(&self, side: DiffSide) -> Option<PathBuf> {
200        let (primary, fallback) = match side {
201            DiffSide::Old => (&self.header.old_path, &self.header.new_path),
202            DiffSide::New => (&self.header.new_path, &self.header.old_path),
203        };
204        primary.clone().or_else(|| fallback.clone())
205    }
206
207    /// Builds contiguous source text for one file side.
208    ///
209    /// Returns `None` when the file's hunks are not contiguous on `side`.
210    pub fn highlight_source(&self, side: DiffSide) -> Option<HighlightSource> {
211        let mut lines: Vec<&str> = Vec::new();
212        let mut head = None;
213        let mut next_line = None;
214
215        for hunk in &self.hunks {
216            let hunk_head = hunk_head(hunk, side);
217            if next_line.is_some_and(|line| line != hunk_head) {
218                return None;
219            }
220            head.get_or_insert(hunk_head);
221            lines.extend(side_lines(hunk, side));
222            let len = hunk
223                .lines
224                .iter()
225                .map(|line| source_len(line, side))
226                .sum::<u32>();
227            next_line = Some(hunk_head + len);
228        }
229        head.map(|head| HighlightSource::new(lines.join("\n"), head))
230    }
231}
232
233/// Yields the source-side text of every line present on `side`.
234///
235/// Lines are joined with `\n` by callers; blank lines are kept so a
236/// [`HighlightSource`] line index stays aligned with its source line number.
237fn side_lines(hunk: &Hunk, side: DiffSide) -> impl Iterator<Item = &str> {
238    hunk.lines
239        .iter()
240        .filter(move |line| source_len(line, side) != 0)
241        .map(|line| line.text.as_str())
242}
243
244/// Returns the first source line for one hunk side.
245fn hunk_head(hunk: &Hunk, side: DiffSide) -> u32 {
246    match side {
247        DiffSide::Old => hunk.header.old_line_no,
248        DiffSide::New => hunk.header.new_line_no,
249    }
250}
251
252/// Returns how many source lines a diff line contributes on `side`.
253fn source_len(line: &DiffLine, side: DiffSide) -> u32 {
254    match side {
255        DiffSide::Old => line.kind.old_len(),
256        DiffSide::New => line.kind.new_len(),
257    }
258}
259
260impl BuiltinHighlighter {
261    /// Creates a highlighter from caller-loaded grammars and themes.
262    pub fn new(registry: syntax::Registry, default_theme: impl Into<String>) -> Self {
263        Self {
264            registry,
265            default_theme: default_theme.into(),
266            blob_caches: BTreeMap::new(),
267        }
268    }
269
270    /// Adds `grammar` to this highlighter if a grammar with the same name is absent.
271    pub fn ensure_grammar(&mut self, grammar: syntax::Grammar) {
272        if self.registry.grammar_by_name(&grammar.name).is_err() {
273            self.registry.add_grammar(grammar);
274        }
275    }
276
277    /// Highlights one request.
278    pub fn highlight(&mut self, request: HighlightRequest) -> HighlightResult {
279        self.highlight_group(vec![request]).remove(0)
280    }
281
282    /// Highlights multiple requests.
283    pub fn highlight_requests<I>(&mut self, requests: I) -> Vec<HighlightResult>
284    where
285        I: IntoIterator<Item = HighlightRequest>,
286    {
287        let mut batches: BTreeMap<HighlightBatchKey, Vec<HighlightRequest>> = BTreeMap::new();
288        for request in requests {
289            batches
290                .entry(HighlightBatchKey::from(&request))
291                .or_default()
292                .push(request);
293        }
294
295        batches
296            .into_values()
297            .flat_map(|requests| self.highlight_group(requests))
298            .collect()
299    }
300
301    /// Highlights grouped requests with one range highlighter.
302    fn highlight_group(&mut self, requests: Vec<HighlightRequest>) -> Vec<HighlightResult> {
303        let Some(first) = requests.first() else {
304            return Vec::new();
305        };
306        let Ok(grammar) = self.registry.query(syntax::GrammarQuery {
307            syntax: (first.key.syntax != "auto").then_some(first.key.syntax.as_str()),
308            path: first.path.as_deref(),
309            head: first.source.text.lines().next(),
310        }) else {
311            return requests.into_iter().map(HighlightResult::plain).collect();
312        };
313        let theme_name = if first.key.theme == "auto" {
314            self.default_theme.as_str()
315        } else {
316            &first.key.theme
317        };
318        let Ok(theme) = self.registry.theme_by_name(theme_name) else {
319            return requests.into_iter().map(HighlightResult::plain).collect();
320        };
321        let range = requests.iter().filter_map(|request| {
322            request
323                .source
324                .line_index(request.key.source_line)
325                .map(|line| line..line.saturating_add(1))
326        });
327        let mut start = usize::MAX;
328        let mut end = 0;
329        for range in range {
330            start = start.min(range.start);
331            end = end.max(range.end);
332        }
333        if start >= end {
334            return requests.into_iter().map(HighlightResult::plain).collect();
335        }
336        let source = first.source.text.clone();
337        let cache_key = BlobCacheKey {
338            grammar: grammar.name.clone(),
339            text_ptr: source.as_ptr() as usize,
340            text_len: source.len(),
341        };
342        let cache = self
343            .blob_caches
344            .remove(&cache_key)
345            .map(|entry| entry.cache)
346            .unwrap_or_default();
347
348        let mut lines = BTreeMap::new();
349        let cache = {
350            let mut blob = syntax::BlobHighlighter::with_cache(grammar, source.as_ref(), cache);
351            blob.highlight_styled_range(theme, start..end, |line| {
352                lines.insert(line.line_index, line_from_spans(line.text, line.styles));
353            });
354            blob.into_cache()
355        };
356        self.blob_caches.insert(
357            cache_key,
358            BlobCacheEntry {
359                _source: source,
360                cache,
361            },
362        );
363
364        requests
365            .into_iter()
366            .map(|request| {
367                let line = request
368                    .source
369                    .line_index(request.key.source_line)
370                    .and_then(|index| lines.remove(&index))
371                    .unwrap_or_else(|| request.plain_line());
372                HighlightResult::new(request, line)
373            })
374            .collect()
375    }
376}
377
378impl DiffHighlighter for BuiltinHighlighter {
379    fn highlight_batch(&mut self, requests: Vec<HighlightRequest>) -> Vec<HighlightResult> {
380        self.highlight_requests(requests)
381    }
382}
383
384impl HighlightRequest {
385    /// Returns the unhighlighted source row for this request.
386    fn plain_line(&self) -> Line {
387        self.source
388            .line(self.key.source_line)
389            .map(Line::new)
390            .unwrap_or_default()
391    }
392}
393
394impl HighlightResult {
395    /// Pairs a highlighted line with the metadata copied from its request.
396    pub fn new(request: HighlightRequest, line: Line) -> Self {
397        Self {
398            key: request.key,
399            hunk: request.hunk,
400            row: request.row,
401            line,
402        }
403    }
404
405    /// Returns a plain result for an unhighlightable request.
406    fn plain(request: HighlightRequest) -> Self {
407        let line = request.plain_line();
408        Self::new(request, line)
409    }
410}
411
412impl From<&HighlightRequest> for HighlightBatchKey {
413    fn from(request: &HighlightRequest) -> Self {
414        Self {
415            file: request.key.file,
416            side: request.key.side,
417            syntax: request.key.syntax.clone(),
418            theme: request.key.theme.clone(),
419            path: request.path.clone(),
420            source: request.source.id(),
421        }
422    }
423}
424
425/// Converts style spans into a TUI line.
426fn line_from_spans(text: &str, spans: &[syntax::StyleSpan]) -> Line {
427    if text.is_empty() || spans.is_empty() {
428        return Line::new(text);
429    }
430    let mut line = Line::blank();
431    let mut cursor = 0;
432
433    for span in spans {
434        if cursor < span.start {
435            line.push(Label::new(&text[cursor..span.start]));
436        }
437        if span.start < span.end {
438            line.push(Label::new(&text[span.start..span.end]).style(span.style.tui_style()));
439        }
440        cursor = span.end;
441    }
442    if cursor < text.len() {
443        line.push(Label::new(&text[cursor..]));
444    }
445    line
446}
447
448/// Input fields used to create a [`HighlightKey`].
449#[derive(Clone, Copy, Debug)]
450pub struct HighlightKeyInput<'a> {
451    /// File containing the row.
452    pub file: FileId,
453    /// Diff side to highlight.
454    pub side: DiffSide,
455    /// One-based source line number.
456    pub source_line: u32,
457    /// Source text.
458    pub text: &'a str,
459    /// Optional syntax override.
460    pub syntax: Option<&'a str>,
461    /// Theme name.
462    pub theme: &'a str,
463}
464
465/// Converts syntax styles into TUI styles.
466trait SyntaxStyleExt {
467    /// Converts this syntax style into a TUI style.
468    fn tui_style(self) -> Style;
469}
470
471impl SyntaxStyleExt for syntax::Style {
472    fn tui_style(self) -> Style {
473        let mut out = Style::default();
474        if let Some(color) = self.foreground {
475            out = out.fg(Color::RGB(color.r, color.g, color.b));
476        }
477        if self.font_style.contains(syntax::FontStyle::BOLD) {
478            out = out.bold();
479        }
480        if self.font_style.contains(syntax::FontStyle::ITALIC) {
481            out = out.italic();
482        }
483        if self.font_style.contains(syntax::FontStyle::UNDERLINE) {
484            out = out.underline();
485        }
486        if self.font_style.contains(syntax::FontStyle::STRIKETHROUGH) {
487            out = out.strikethrough();
488        }
489        out
490    }
491}
492
493#[cfg(test)]
494mod tests {
495    use super::*;
496    use crate::Decode;
497    use std::str::FromStr;
498
499    #[test]
500    fn source_lines_before_head_are_absent() {
501        let source = HighlightSource::new("two\nthree\n", 2);
502
503        assert_eq!(source.line_index(1), None);
504        assert_eq!(source.line(1), None);
505        assert_eq!(source.line_index(2), Some(0));
506        assert_eq!(source.line(2), Some("two"));
507    }
508
509    #[test]
510    fn file_highlight_source_spans_the_new_side() {
511        let document = crate::DiffDocument::decode_str(
512            "\
513diff --git a/a.css b/a.css
514index 1111111..2222222 100644
515--- a/a.css
516+++ b/a.css
517@@ -1,3 +1,3 @@
518 .x {
519-background: url(old.svg);
520+background: url(new.svg);
521 }
522",
523        )
524        .unwrap();
525        let source = document.files[0].highlight_source(DiffSide::New).unwrap();
526
527        assert_eq!(source.head, 1);
528        assert_eq!(source.line(1), Some(".x {"));
529        assert_eq!(source.line(2), Some("background: url(new.svg);"));
530        assert_eq!(source.line(3), Some("}"));
531    }
532
533    #[test]
534    fn highlight_source_keeps_a_leading_blank_line() {
535        // A hunk whose first source line is blank must not collapse it away,
536        // or every later line index shifts up by one against its line number.
537        // The blank context line is a single space; spell the fixture with
538        // `concat!` so that space cannot be mistaken for trailing whitespace.
539        let document = crate::DiffDocument::decode_str(concat!(
540            "diff --git a/a.rs b/a.rs\n",
541            "index 1111111..2222222 100644\n",
542            "--- a/a.rs\n",
543            "+++ b/a.rs\n",
544            "@@ -2,3 +2,3 @@\n",
545            " \n",
546            "-old\n",
547            "+new\n",
548            " tail\n",
549        ))
550        .unwrap();
551        let hunk = &document.files[0].hunks[0];
552
553        let source = hunk.highlight_source(DiffSide::New);
554        assert_eq!(source.head, 2);
555        assert_eq!(source.line(2), Some(""));
556        assert_eq!(source.line(3), Some("new"));
557        assert_eq!(source.line(4), Some("tail"));
558
559        let file = document.files[0].highlight_source(DiffSide::New).unwrap();
560        assert_eq!(file.line(2), Some(""));
561        assert_eq!(file.line(3), Some("new"));
562    }
563
564    #[test]
565    fn css_custom_properties_use_variable_theme_style() {
566        let grammar = syntax::Grammar::from_str(syntax::syntaxes::CSS).unwrap();
567        let theme =
568            syntax::Theme::parse(include_str!("themes/rustik-catppuccin-mocha.json")).unwrap();
569        let line = "  --color-background-light: #dad8d8;";
570        let mut state = syntax::LineState::default();
571        let mut tokenizer = syntax::LineTokenizer::new(&grammar);
572        let _ = tokenizer.tokenize_line(&mut state, ":root {");
573        let spans = tokenizer.tokenize_line(&mut state, line);
574        let styles = theme.style_spans(&grammar, line, &spans);
575        let custom_property = line.find("--color-background-light").unwrap();
576        let style = styles
577            .iter()
578            .find(|style| style.start <= custom_property && style.end > custom_property)
579            .unwrap();
580
581        assert!(scopes_for_byte(&grammar, &spans, custom_property).contains(&"variable.css"));
582        assert_eq!(
583            style.style.foreground,
584            Some(syntax::Rgb {
585                r: 137,
586                g: 180,
587                b: 250
588            })
589        );
590    }
591
592    #[test]
593    fn css_var_references_use_variable_theme_style() {
594        let grammar = syntax::Grammar::from_str(syntax::syntaxes::CSS).unwrap();
595        let theme =
596            syntax::Theme::parse(include_str!("themes/rustik-catppuccin-mocha.json")).unwrap();
597        let line = "  color: var(--color-dimmer);";
598        let mut state = syntax::LineState::default();
599        let mut tokenizer = syntax::LineTokenizer::new(&grammar);
600        let _ = tokenizer.tokenize_line(&mut state, ".note-meta {");
601        let spans = tokenizer.tokenize_line(&mut state, line);
602        let styles = theme.style_spans(&grammar, line, &spans);
603        let variable = line.find("--color-dimmer").unwrap();
604        let style = styles
605            .iter()
606            .find(|style| style.start <= variable && style.end > variable)
607            .unwrap();
608
609        assert!(scopes_for_byte(&grammar, &spans, variable).contains(&"variable.argument.css"));
610        assert_eq!(
611            style.style.foreground,
612            Some(syntax::Rgb {
613                r: 235,
614                g: 160,
615                b: 172
616            })
617        );
618    }
619
620    fn scopes_for_byte<'a>(
621        grammar: &'a syntax::Grammar,
622        spans: &'a [syntax::ScopeSpan],
623        byte: usize,
624    ) -> Vec<&'a str> {
625        spans
626            .iter()
627            .filter(|span| span.start <= byte && span.end > byte)
628            .filter_map(|span| grammar.scopes.get(span.scope.index()))
629            .map(String::as_str)
630            .collect()
631    }
632}