lightsystemdarkgreen
@ 261119.3 · fetching
current
// Emit per-line diff metadata as an OSC sequence, so that a host application
// (e.g. lazygit) can map a rendered diff row back to its patch-space identity
// (file, type, new-file line, old-file line) without re-parsing the rendered
// output. delta restructures the diff (drops the +/- markers, conveys the side
// by color, adds gutters), so that identity cannot be recovered from the
// painted text alone -- the pager, which still has it at render time, states it.
//
// This is gated on the OSC1717 environment variable: the host advertises the
// protocol versions it understands and delta emits the highest mutually-
// understood one. When the variable is unset (i.e. delta is not running under
// such a host) nothing is emitted, so a raw terminal / less / tmux see a normal
// diff.
//
// The OSC number 1717 was chosen after auditing the OSC allocations of the major
// terminal emulators (xterm, VTE, kitty, foot, WezTerm, iTerm2, Windows Terminal,
// Ghostty, VS Code, ConEmu, urxvt); none of them interpret it, so a terminal that
// is not a participating host skips it harmlessly.

use std::io::{self, Write};
use std::sync::OnceLock;

use crate::delta::{DiffType, State};

/// Highest protocol version this build of delta knows how to emit.
const SUPPORTED_VERSION: u32 = 1;

const OSC: &str = "\x1b]1717";
const ST: &str = "\x1b\\";

/// The highest version in the host's advertised list (e.g. "V1" or "V1,V2")
/// that this build also understands, or `None` if the lists are disjoint.
fn pick_version(advertised: &str) -> Option<u32> {
    advertised
        .split(',')
        .filter_map(|v| v.trim().strip_prefix('V')?.parse::<u32>().ok())
        .filter(|v| *v <= SUPPORTED_VERSION)
        .max()
}

/// The protocol version to emit, negotiated against the host's advertised list
/// in `OSC1717` (e.g. "V1" or "V1,V2"), or `None` when no host is asking (the
/// variable is unset) so delta stays silent.
pub fn negotiated_version() -> Option<u32> {
    static VERSION: OnceLock<Option<u32>> = OnceLock::new();
    *VERSION.get_or_init(|| pick_version(&std::env::var("OSC1717").ok()?))
}

/// The handshake record: a version-only OSC 1717 (no further fields) that a
/// conforming pager emits once, as its first output, to announce it speaks the
/// protocol (see the spec, §4.4). It lets a host probe delta on an empty diff --
/// which emits no per-line records -- and tell "speaks the protocol" apart from
/// "unsupported pager". Empty when no host negotiated a version.
pub fn handshake() -> String {
    negotiated_version().map_or(String::new(), handshake_for_version)
}

fn handshake_for_version(version: u32) -> String {
    format!("{OSC};{version}{ST}")
}

/// Tracks the current old-/new-file line numbers within a hunk and formats the
/// per-line OSC sequence. One instance is held by the `Painter` (when emission
/// is negotiated) and re-seeded at every hunk header.
pub struct DiffLineMetadata {
    version: u32,
    old_line: usize,
    new_line: usize,
    file: String,
    /// The record (`type_char`, `new_line`, `old_line`) most recently emitted
    /// for a primary content line, so a wrapped continuation row can re-emit it
    /// without advancing the counters. Set by every primary line; read by the
    /// wrapped row(s) that immediately follow it.
    last_record: Option<(char, usize, Option<usize>)>,
}

impl DiffLineMetadata {
    /// Returns an emitter iff the host negotiated a protocol version.
    pub fn from_env() -> Option<Self> {
        negotiated_version().map(|version| Self {
            version,
            old_line: 0,
            new_line: 0,
            file: String::new(),
            last_record: None,
        })
    }

    /// A version-1 emitter regardless of environment. Tests cannot go through
    /// `from_env`: the negotiated version is cached in a process-wide OnceLock,
    /// so an env var set by one test would leak into all others.
    #[cfg(test)]
    pub fn v1_for_tests() -> Self {
        Self {
            version: 1,
            old_line: 0,
            new_line: 0,
            file: String::new(),
            last_record: None,
        }
    }

    /// Seed the line-number counters and file path at a hunk header. Mirrors
    /// `LineNumbersData::initialize_hunk`: the first entry is the old-file start,
    /// the last is the new-file start.
    pub fn initialize_hunk(&mut self, line_numbers: &[(usize, usize)], file: String) {
        self.old_line = line_numbers[0].0;
        self.new_line = line_numbers[line_numbers.len() - 1].0;
        self.file = file;
    }

    /// Advance the counters for `state` and return the OSC sequence to prepend
    /// to that content line, or an empty string for states that carry no
    /// metadata (headers and -- in this prototype -- combined/merge diffs). The
    /// counter arithmetic mirrors `line_numbers::linenumbers_and_styles`.
    ///
    /// A wrapped continuation row (`Hunk*Wrapped`, produced when side-by-side
    /// wraps a long line into several output rows) re-emits the record of the
    /// primary line it continues, *without* advancing the counters. delta emits
    /// each wrapped row as a distinct output line, so a host sees them as
    /// distinct lines and needs the identity on each -- otherwise acting on a
    /// continuation row, or treating the wrapped line as one block when
    /// navigating, breaks.
    pub fn osc_for_line(&mut self, state: &State) -> String {
        use State::*;
        let record = match state {
            HunkZero(DiffType::Unified, _) => {
                let record = ('c', self.new_line, None);
                self.old_line += 1;
                self.new_line += 1;
                record
            }
            HunkPlus(DiffType::Unified, _) => {
                let record = ('a', self.new_line, None);
                self.new_line += 1;
                record
            }
            HunkMinus(DiffType::Unified, _) => {
                // A deletion sits at the new-file position the new-file counter
                // currently holds (it has not advanced past the preceding
                // context/added lines); it carries both numbers.
                let record = ('d', self.new_line, Some(self.old_line));
                self.old_line += 1;
                record
            }
            HunkZeroWrapped | HunkMinusWrapped | HunkPlusWrapped => match self.last_record {
                Some(record) => record,
                None => return String::new(),
            },
            _ => return String::new(),
        };
        self.last_record = Some(record);
        let (type_char, new_line, old_line) = record;
        let old_field = old_line.map_or(String::new(), |n| n.to_string());
        format!(
            "{OSC};{version};{type_char};{new_line};{old_field};{file}{ST}",
            version = self.version,
            file = self.file,
        )
    }

    /// The `h` (hunk-header) record for the current hunk. `initialize_hunk` has
    /// just seeded `new_line` with the hunk's new-file start -- which is the
    /// hunk's first line (spec §5.2) -- so it is in hand exactly when the hunk
    /// header is rendered. `old-line` is empty on a header.
    pub fn osc_for_hunk_header(&self) -> String {
        self.header_osc('h', Some(self.new_line), &self.file)
    }

    /// The `f` (file-header) record. It carries no line numbers (spec §5.5):
    /// delta renders the file header (the boxed file name) as soon as it parses
    /// the `+++` line, *before* it has seen the first `@@`, so the file's first
    /// hunk line is not known here. The path is supplied by the caller because
    /// the emitter only learns it at the first hunk header.
    pub fn osc_for_file_header(&self, file: &str) -> String {
        self.header_osc('f', None, file)
    }

    fn header_osc(&self, type_char: char, new_line: Option<usize>, file: &str) -> String {
        let new_field = new_line.map_or(String::new(), |n| n.to_string());
        format!(
            "{OSC};{version};{type_char};{new_field};;{file}{ST}",
            version = self.version,
        )
    }

    /// The `C` (commit) record marking the first row of a commit in `git log`
    /// output. A commit is no line of any file, so it carries no line numbers
    /// and states its id where a diff row states its file.
    pub fn osc_for_commit(&self, commit: &str) -> String {
        format!("{OSC};{version};C;;;{commit}{ST}", version = self.version)
    }
}

/// The commit a commit-header line names: the first token after whatever
/// `--commit-regex` matched, which is where git prints it. `None` when there is
/// no such token or it is no hash, so a custom regex matching something else
/// yields no record rather than a wrong one.
pub fn commit_id(line: &str, marker_end: usize) -> Option<&str> {
    let commit = line.get(marker_end..)?.split_whitespace().next()?;
    let is_hash = commit.len() >= 4 && commit.chars().all(|c| c.is_ascii_hexdigit());
    is_hash.then_some(commit)
}

/// A `Write` adapter that injects `prefix` at the start of the stream and after
/// every newline. delta draws a file/hunk header as a *multi-row* decoration --
/// an underline under the file name, a box around the hunk header -- written
/// straight to the output by the `draw` functions. To tag the whole block we
/// wrap that writer so every row the decoration emits is preceded by the
/// header's record, the same "every output row carries the record" rule that
/// wrapped content rows follow (spec §6.3/§6.4).
struct OscLinePrefixer<'a> {
    inner: &'a mut dyn Write,
    prefix: &'a str,
    at_line_start: bool,
}

impl Write for OscLinePrefixer<'_> {
    fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
        for chunk in buf.split_inclusive(|&b| b == b'\n') {
            if self.at_line_start {
                self.inner.write_all(self.prefix.as_bytes())?;
            }
            self.inner.write_all(chunk)?;
            self.at_line_start = chunk.ends_with(b"\n");
        }
        Ok(buf.len())
    }

    fn flush(&mut self) -> io::Result<()> {
        self.inner.flush()
    }
}

/// Run `draw`, prefixing every output row it writes with `osc` (a header
/// record). With `osc` empty the closure writes to `writer` untouched, so the
/// output stays byte-for-byte identical to stock delta.
pub fn write_with_header_osc(
    writer: &mut dyn Write,
    osc: &str,
    draw: impl FnOnce(&mut dyn Write) -> io::Result<()>,
) -> io::Result<()> {
    if osc.is_empty() {
        draw(writer)
    } else {
        let mut prefixer = OscLinePrefixer {
            inner: writer,
            prefix: osc,
            at_line_start: true,
        };
        draw(&mut prefixer)
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::delta::{DiffType, State};

    fn emitter() -> DiffLineMetadata {
        let mut md = DiffLineMetadata::v1_for_tests();
        // @@ -1,3 +1,4 @@ : old start 1, new start 1.
        md.initialize_hunk(&[(1, 3), (1, 4)], "f.txt".to_owned());
        md
    }

    #[test]
    fn test_handshake_is_version_only() {
        // The handshake carries only the version (no further fields), so a host tells
        // it apart from a per-line record by field count.
        assert_eq!(handshake_for_version(1), "\x1b]1717;1\x1b\\");
    }

    #[test]
    fn test_hunk_header_record_carries_the_hunks_first_line() {
        // `h` carries the hunk's first new-file line (just seeded by
        // initialize_hunk) and no old-line. Emitting it does not advance the
        // counters: the hunk's first content line reports the same line.
        let mut md = emitter();
        assert_eq!(md.osc_for_hunk_header(), "\x1b]1717;1;h;1;;f.txt\x1b\\");
        assert_eq!(
            md.osc_for_line(&State::HunkZero(DiffType::Unified, None)),
            "\x1b]1717;1;c;1;;f.txt\x1b\\"
        );
    }

    #[test]
    fn test_file_header_record_has_no_line_numbers() {
        // `f` never carries line numbers (spec §5.5): delta draws the file
        // header before it has seen the first `@@`. The path comes from the
        // caller, because the emitter's own state is only seeded at the first
        // hunk header.
        let md = emitter();
        assert_eq!(
            md.osc_for_file_header("src/foo.rs"),
            "\x1b]1717;1;f;;;src/foo.rs\x1b\\"
        );
    }

    #[test]
    fn test_header_record_prefixes_every_row_of_a_multi_row_block() {
        // A file/hunk header is a multi-row decoration (an underlined name, a
        // box); every row of the block carries the record (spec §6.4). With no
        // record the drawn bytes pass through untouched.
        let draw = |w: &mut dyn io::Write| -> io::Result<()> {
            write!(w, "──┐\n1:│\n──┘\n")
        };

        let mut tagged = Vec::new();
        write_with_header_osc(&mut tagged, "[osc]", draw).unwrap();
        assert_eq!(
            String::from_utf8(tagged).unwrap(),
            "[osc]──┐\n[osc]1:│\n[osc]──┘\n"
        );

        let mut untouched = Vec::new();
        write_with_header_osc(&mut untouched, "", draw).unwrap();
        assert_eq!(String::from_utf8(untouched).unwrap(), "──┐\n1:│\n──┘\n");
    }

    #[test]
    fn test_commit_record_carries_the_commit_id() {
        // `C` marks the first row of a commit in `git log` output. It is no line
        // of any file, so it carries no line numbers; the commit id goes where a
        // diff row carries its file.
        let md = emitter();
        assert_eq!(
            md.osc_for_commit("dbb7c03c3f306c0b12ce003358e1fd17c3fd2701"),
            "\x1b]1717;1;C;;;dbb7c03c3f306c0b12ce003358e1fd17c3fd2701\x1b\\"
        );
    }

    #[test]
    fn test_commit_id_is_the_token_after_what_marks_the_line() {
        // Whatever `--commit-regex` matched identifies the line; the commit is
        // the first token after it, so decorations stay out of it.
        assert_eq!(
            commit_id("commit dbb7c03 (HEAD -> main, origin/main)", 7),
            Some("dbb7c03")
        );
        assert_eq!(commit_id("commit ", 7), None);
        assert_eq!(commit_id("commit not-a-hash", 7), None);
    }

    #[test]
    fn test_wrapped_rows_reemit_the_primary_record_without_advancing() {
        let mut md = emitter();
        let zero = md.osc_for_line(&State::HunkZero(DiffType::Unified, None));
        let plus = md.osc_for_line(&State::HunkPlus(DiffType::Unified, None));
        let plus_w1 = md.osc_for_line(&State::HunkPlusWrapped);
        let plus_w2 = md.osc_for_line(&State::HunkPlusWrapped);
        let zero_after = md.osc_for_line(&State::HunkZero(DiffType::Unified, None));

        assert_eq!(zero, "\x1b]1717;1;c;1;;f.txt\x1b\\");
        assert_eq!(plus, "\x1b]1717;1;a;2;;f.txt\x1b\\");
        // Continuation rows re-emit the addition's record verbatim.
        assert_eq!(plus_w1, plus);
        assert_eq!(plus_w2, plus);
        // The wrapped rows must not advance the counters: the next content line
        // is new-line 3, not 5.
        assert_eq!(zero_after, "\x1b]1717;1;c;3;;f.txt\x1b\\");
    }

    #[test]
    fn test_wrapped_deletion_reemits_both_line_numbers() {
        let mut md = emitter();
        let minus = md.osc_for_line(&State::HunkMinus(DiffType::Unified, None));
        let minus_w = md.osc_for_line(&State::HunkMinusWrapped);
        assert_eq!(minus, "\x1b]1717;1;d;1;1;f.txt\x1b\\");
        assert_eq!(minus_w, minus);
    }

    #[test]
    fn test_wrapped_row_with_no_preceding_primary_emits_nothing() {
        let mut md = emitter();
        assert_eq!(md.osc_for_line(&State::HunkZeroWrapped), "");
    }

    #[test]
    fn test_pick_version() {
        assert_eq!(pick_version("V1"), Some(1));
        assert_eq!(pick_version("V1,V2"), Some(1)); // we cap at SUPPORTED_VERSION
        assert_eq!(pick_version("V2,V3"), None); // disjoint with what we emit
        assert_eq!(pick_version(""), None);
        assert_eq!(pick_version("garbage"), None);
    }

    #[test]
    fn test_unified_context_addition_deletion_sequence() {
        // A modification hunk in normal (unified) mode: one context line, two
        // deletions, two additions, then a trailing context line. Two consecutive
        // deletions share a new-line and are told apart only by old-line; a
        // deletion sits at the new-file position the counter currently holds,
        // while context and additions advance it.
        let mut md = emitter();
        assert_eq!(
            md.osc_for_line(&State::HunkZero(DiffType::Unified, None)),
            "\x1b]1717;1;c;1;;f.txt\x1b\\"
        );
        assert_eq!(
            md.osc_for_line(&State::HunkMinus(DiffType::Unified, None)),
            "\x1b]1717;1;d;2;2;f.txt\x1b\\"
        );
        assert_eq!(
            md.osc_for_line(&State::HunkMinus(DiffType::Unified, None)),
            "\x1b]1717;1;d;2;3;f.txt\x1b\\"
        );
        assert_eq!(
            md.osc_for_line(&State::HunkPlus(DiffType::Unified, None)),
            "\x1b]1717;1;a;2;;f.txt\x1b\\"
        );
        assert_eq!(
            md.osc_for_line(&State::HunkPlus(DiffType::Unified, None)),
            "\x1b]1717;1;a;3;;f.txt\x1b\\"
        );
        assert_eq!(
            md.osc_for_line(&State::HunkZero(DiffType::Unified, None)),
            "\x1b]1717;1;c;4;;f.txt\x1b\\"
        );
    }

    #[test]
    fn test_initialize_hunk_reseeds_the_counters() {
        // A second hunk re-seeds the old/new starts, so the counters jump to the
        // new hunk rather than continuing from the previous one.
        let mut md = emitter();
        md.initialize_hunk(&[(20, 3), (25, 4)], "f.txt".to_owned());
        assert_eq!(
            md.osc_for_line(&State::HunkZero(DiffType::Unified, None)),
            "\x1b]1717;1;c;25;;f.txt\x1b\\"
        );
        assert_eq!(
            md.osc_for_line(&State::HunkMinus(DiffType::Unified, None)),
            "\x1b]1717;1;d;26;21;f.txt\x1b\\"
        );
    }

    #[test]
    fn test_whole_file_deletion_sits_at_new_line_zero() {
        // A deleted file's hunk header is `@@ -1,N +0,0 @@`, so the new-file
        // start is 0 and every deletion reports new-line 0.
        let mut md = emitter();
        md.initialize_hunk(&[(1, 3), (0, 0)], "gone.txt".to_owned());
        assert_eq!(
            md.osc_for_line(&State::HunkMinus(DiffType::Unified, None)),
            "\x1b]1717;1;d;0;1;gone.txt\x1b\\"
        );
        assert_eq!(
            md.osc_for_line(&State::HunkMinus(DiffType::Unified, None)),
            "\x1b]1717;1;d;0;2;gone.txt\x1b\\"
        );
    }

    #[test]
    fn test_path_may_contain_semicolons() {
        // The path is the last field, so it may itself contain ';': a host splits
        // into at most five fields and takes the remainder as the path.
        let mut md = emitter();
        md.initialize_hunk(&[(1, 1), (1, 1)], "weird;name.txt".to_owned());
        assert_eq!(
            md.osc_for_line(&State::HunkPlus(DiffType::Unified, None)),
            "\x1b]1717;1;a;1;;weird;name.txt\x1b\\"
        );
    }
}