rustik-diff 0.3.0

Pure diff viewer and Git diff pager for Rustik.
Documentation
//! Background syntax highlighting and context expansion for diff viewers.
//!
//! [`spawn_highlighter`] runs the blocking repo and syntax-highlighting work on
//! a dedicated thread so an interactive viewer stays responsive. A viewer feeds
//! it the [`HighlightRequest`]s collected by
//! [`DiffViewer::visible_highlight_requests`](crate::DiffViewer::visible_highlight_requests)
//! and the [`ContextRequest`]s prepared by
//! [`DiffViewer::context_request`](crate::DiffViewer::context_request), then
//! applies each [`HighlightOutput`] it produces.

use std::collections::{BTreeMap, BTreeSet};
use std::path::PathBuf;
use std::sync::mpsc::{self, SyncSender, TrySendError};
use std::thread;

use rustik_repo::{DiffRepository, git};

use crate::builtins::Builtins;
use crate::{
    BuiltinHighlighter, ContextRequest, ContextUpdate, Decode, DiffDocument, DiffHighlighter,
    DiffSide, FileId, HighlightRequest, HighlightResult, HighlightSource, Oid,
};

/// Source context lines fetched around highlighted rows.
const HIGHLIGHT_CONTEXT_LINES: usize = 256;
/// Bound on queued highlight and context commands.
const COMMAND_QUEUE: usize = 4;

/// A running background highlighter.
///
/// Submits highlight and context work to the worker thread spawned by
/// [`spawn_highlighter`]. Dropping the handle disconnects the command channel,
/// which stops the worker once it drains.
pub struct Highlighter {
    /// Command channel to the worker thread.
    commands: SyncSender<Command>,
}

impl Highlighter {
    /// Queues a batch of rows for highlighting.
    ///
    /// Returns the requests back when the worker queue is full or gone, so the
    /// caller can cancel them with
    /// [`DiffViewer::cancel_highlights`](crate::DiffViewer::cancel_highlights).
    /// Returns `None` once the batch is queued.
    pub fn highlight(&self, requests: Vec<HighlightRequest>) -> Option<Vec<HighlightRequest>> {
        // `try_send` errors return the command we sent, so the error always
        // holds `Command::Highlight`.
        match self.commands.try_send(Command::Highlight(requests)) {
            Ok(()) => None,
            Err(
                TrySendError::Full(Command::Highlight(requests))
                | TrySendError::Disconnected(Command::Highlight(requests)),
            ) => Some(requests),
            Err(_) => None,
        }
    }

    /// Queues a context refetch, returning whether it was accepted.
    pub fn context(&self, request: ContextRequest) -> bool {
        self.commands.try_send(Command::Context(request)).is_ok()
    }
}

/// Result produced by the background highlighter.
pub enum HighlightOutput {
    /// Highlighted source rows ready for
    /// [`DiffViewer::apply_highlights`](crate::DiffViewer::apply_highlights).
    Highlights(Vec<HighlightResult>),
    /// A decoded context update, or `None` when the refetch produced nothing,
    /// ready for
    /// [`DiffViewer::apply_context_update`](crate::DiffViewer::apply_context_update).
    Context(Option<ContextUpdate>),
}

/// Command sent to the worker thread.
enum Command {
    /// Highlight a batch of source rows.
    Highlight(Vec<HighlightRequest>),
    /// Refetch and decode a context update.
    Context(ContextRequest),
}

/// Spawns a background highlighter for `document`.
///
/// `output` is invoked on the worker thread for each produced
/// [`HighlightOutput`]; forward it to the UI thread (for example over a
/// channel) and apply it to the viewer.
pub fn spawn_highlighter(
    document: &DiffDocument,
    repo: Option<git::Repository>,
    output: impl Fn(HighlightOutput) + Send + 'static,
) -> Highlighter {
    let (commands, requests) = mpsc::sync_channel::<Command>(COMMAND_QUEUE);
    let seed = Seed::new(document);

    thread::spawn(move || {
        // Theme parsing and grammar compilation are blocking, so the worker is
        // built here rather than on the caller's thread.
        let mut worker = HighlightWorker::new(seed, repo);
        while let Ok(command) = requests.recv() {
            match command {
                Command::Highlight(requests) => {
                    if requests.is_empty() {
                        continue;
                    }
                    output(HighlightOutput::Highlights(worker.highlight(requests)));
                }
                Command::Context(request) => {
                    output(HighlightOutput::Context(worker.context(request)));
                }
            }
        }
    });
    Highlighter { commands }
}

/// Header-only document data the worker needs.
///
/// Extracted on the caller's thread so the document itself — which holds every
/// line of the patch — does not have to be cloned into the worker. Its size is
/// proportional to the number of changed files, not diff lines.
struct Seed {
    /// Changed file paths used to select built-in grammars.
    paths: Vec<PathBuf>,
    /// Source object ids keyed by diff file and side.
    head_oids: BTreeMap<(FileId, DiffSide), Oid>,
}

impl Seed {
    /// Extracts the worker's seed from `document`.
    fn new(document: &DiffDocument) -> Self {
        let mut head_oids = BTreeMap::new();
        for file in &document.files {
            if let Some(oid) = file.header.old_oid {
                head_oids.insert((file.id, DiffSide::Old), oid);
            }
            if let Some(oid) = file.header.new_oid {
                head_oids.insert((file.id, DiffSide::New), oid);
            }
        }
        Self {
            paths: Builtins::document_paths(document),
            head_oids,
        }
    }
}

/// Background worker for blocking repo and syntax-highlighting work.
struct HighlightWorker {
    /// Built-in syntax highlighter.
    highlighter: BuiltinHighlighter,
    /// Git-backed repo used for direct Git invocations.
    repo: Option<git::Repository>,
    /// Highlight source context cache keyed by diff file and side.
    context_sources: BTreeMap<(FileId, DiffSide), Vec<HighlightSource>>,
    /// Source object ids keyed by diff file and side.
    head_oids: BTreeMap<(FileId, DiffSide), Oid>,
    /// File-side heads already checked for first-line grammar metadata.
    loaded_heads: BTreeSet<(FileId, DiffSide)>,
}

impl HighlightWorker {
    /// Creates a background worker.
    fn new(seed: Seed, repo: Option<git::Repository>) -> Self {
        Self {
            highlighter: Builtins::highlighter_for_paths(&seed.paths)
                .unwrap_or_else(|_| BuiltinHighlighter::new(Default::default(), "")),
            repo,
            context_sources: BTreeMap::new(),
            head_oids: seed.head_oids,
            loaded_heads: BTreeSet::new(),
        }
    }

    /// Highlights one batch of source rows.
    fn highlight(&mut self, mut requests: Vec<HighlightRequest>) -> Vec<HighlightResult> {
        self.load_context_sources(&requests);
        for request in &mut requests {
            if let Some(source) = self.context_source_for(request) {
                request.source = source.clone();
            }
            self.load_head_grammar(request);
        }
        self.highlighter.highlight_batch(requests)
    }

    /// Loads first-line-selected grammars for a request's file side.
    fn load_head_grammar(&mut self, request: &HighlightRequest) {
        let key = (request.key.file, request.key.side);
        if !self.loaded_heads.insert(key) {
            return;
        }
        if request.source.head == 1
            && let Some(head) = request.source.text.lines().next()
        {
            let _ = Builtins::load_head_grammars(&mut self.highlighter, head);
            return;
        }
        let Some(repo) = self.repo.as_ref() else {
            return;
        };
        let Some(path) = request.path.as_deref() else {
            return;
        };
        if self.highlighter.has_path_grammar(path) {
            return;
        }
        let Some(oid) = self.head_oids.get(&key) else {
            return;
        };
        let head = repo.head_line(*oid);
        if let Ok(Some(head)) = head {
            let _ = Builtins::load_head_grammars(&mut self.highlighter, &head);
        }
    }

    /// Loads bounded source context for uncached request paths.
    fn load_context_sources(&mut self, requests: &[HighlightRequest]) {
        let Some(repo) = self.repo.as_ref() else {
            return;
        };
        let mut targets = BTreeMap::new();
        for request in requests {
            let key = (request.key.file, request.key.side);
            // Skip sides the viewer already supplied whole-file context for;
            // refetching them would cost a `git diff` whose result is unused.
            if self.context_sources.contains_key(&key) || request.source.head == 1 {
                continue;
            }
            if let Some(path) = request.path.as_deref() {
                targets.insert((path.to_path_buf(), request.key.side), request.key.file);
            }
        }
        if targets.is_empty() {
            return;
        }

        let paths = targets
            .keys()
            .map(|(path, _)| path.as_path())
            .collect::<BTreeSet<_>>()
            .into_iter()
            .collect::<Vec<_>>();
        let Ok(patch) = repo.diff(HIGHLIGHT_CONTEXT_LINES, &paths) else {
            return;
        };
        let Ok(document) = DiffDocument::decode_bytes(&patch) else {
            return;
        };

        for file in &document.files {
            for side in [DiffSide::Old, DiffSide::New] {
                let Some(path) = file.source_path(side) else {
                    continue;
                };
                let Some(file_id) = targets.get(&(path, side)).copied() else {
                    continue;
                };
                let sources = file
                    .hunks
                    .iter()
                    .map(|hunk| hunk.highlight_source(side))
                    .collect::<Vec<_>>();
                self.context_sources.insert((file_id, side), sources);
            }
        }
    }

    /// Returns cached context that contains the requested source row.
    fn context_source_for(&self, request: &HighlightRequest) -> Option<&HighlightSource> {
        // A source starting at line 1 already carries every line the tokenizer
        // state depends on. The bounded refetch would only narrow it, dropping
        // context for rows further than HIGHLIGHT_CONTEXT_LINES into a file.
        if request.source.head == 1 {
            return None;
        }
        let key = (request.key.file, request.key.side);
        let expected = request.source.line(request.key.source_line)?;
        self.context_sources
            .get(&key)?
            .iter()
            .find(|source| source.line(request.key.source_line) == Some(expected))
    }

    /// Refetches and decodes one context update.
    fn context(&mut self, request: ContextRequest) -> Option<ContextUpdate> {
        let repo = self.repo.as_ref()?;
        let paths = request.paths().collect::<Vec<_>>();
        let patch = repo.diff(request.context_lines(), &paths).ok()?;

        drop(paths);
        request.decode(&patch).ok().flatten()
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::{HighlightKey, HighlightKeyInput, HunkId, RowId};

    /// Returns a request for row 5, carrying `source`.
    fn request(source: HighlightSource) -> HighlightRequest {
        HighlightRequest {
            key: HighlightKey::new(HighlightKeyInput {
                file: FileId::new(0),
                side: DiffSide::New,
                source_line: 5,
                text: "row",
                syntax: None,
                theme: "auto",
            }),
            hunk: HunkId::new(0),
            row: RowId::new(0),
            path: None,
            source,
        }
    }

    #[test]
    fn whole_file_sources_are_not_narrowed_to_bounded_context() {
        let mut worker = HighlightWorker::new(
            Seed {
                paths: Vec::new(),
                head_oids: BTreeMap::new(),
            },
            None,
        );
        worker.context_sources.insert(
            (FileId::new(0), DiffSide::New),
            vec![HighlightSource::new("row\n", 5)],
        );

        // A hunk-only source is still upgraded to the refetched context.
        let hunk_only = request(HighlightSource::new("row\n", 5));
        assert!(worker.context_source_for(&hunk_only).is_some());

        // A whole-file source is left alone: the refetch spans only
        // HIGHLIGHT_CONTEXT_LINES and would drop context before that.
        let whole_file = request(HighlightSource::new("a\nb\nc\nd\nrow\n", 1));
        assert!(worker.context_source_for(&whole_file).is_none());
    }
}