Emit f and h records on the per-hunk header banners

difftastic renders no `@@`/`diff --git` rows; its only structural row
is one banner per hunk (`path --- N/total --- Format`) announcing both
the file and the hunk. Annotate it with the header records so a host
can anchor file and hunk navigation on the banners themselves and can
see files with no content lines: every banner carries its hunk's `h`
record with the hunk's first new-file line, and the first hunk's
banner -- the only row announcing the file -- additionally carries the
file's `f` record before the `h`, per the spec's combined-header rule
(§5.5). `f` never carries a line number; the spec fixes each header
type's payload rather than leaving it to the renderer (a streaming
renderer like delta cannot know the first-hunk line at its file
header).

Unlike delta, difftastic builds the whole diff before rendering, so
the hunk's first new-file line is in hand when the banner is printed:
the first aligned row with a new-file line provides it, falling back
to the position the next new line would occupy for a hunk with none
(a pure deletion), mirroring the deletion convention. In inline mode
the banner print moves below the context calculation for the same
reason. A whole-file add/delete renders through the single-column
path as one hunk, so its banner carries `f` plus an `h` at line 1
(addition) or 0 (deletion, matching its `d` records). A rename's
two-row banner repeats the records on each row (spec §6.4).

With OSC1717 unset, output remains byte-for-byte identical to stock
difftastic.

Author: stefanhaller

src/display/diff_line_metadata.rs

@@ -174,6 +174,40 @@ impl DiffLineMetadata {
         }
     }
 
+    /// Prefix every row of a header banner with its OSC record(s). difftastic
+    /// renders no `@@`/`diff --git` rows; instead it prints one banner per hunk
+    /// (`path --- N/total --- Format`) that announces both the file and the
+    /// hunk. Every banner is a hunk header, so it carries that hunk's `h`
+    /// record (`new_line` is the hunk's first new-file line); the first hunk's
+    /// banner is also the only row announcing the file, so it additionally
+    /// carries the file's `f` record -- before the `h`, per the combined-header
+    /// rule (spec §5.5). An `f` never carries line numbers.
+    ///
+    /// The banner is one row, or two when the first hunk also shows a rename's
+    /// old path -- and spec §6.4 wants every row of a header block tagged, so
+    /// each row gets the same record(s).
+    pub(crate) fn header_banner(
+        &self,
+        is_first_hunk: bool,
+        new_line: usize,
+        banner: &str,
+    ) -> String {
+        let mut prefix = String::new();
+        if is_first_hunk {
+            prefix.push_str(&format!(
+                "{OSC};{version};f;;;{file}{ST}",
+                version = self.version,
+                file = self.file,
+            ));
+        }
+        prefix.push_str(&self.osc('h', new_line, None));
+        format!(
+            "{}{}",
+            prefix,
+            banner.replace('\n', &format!("\n{}", prefix))
+        )
+    }
+
     fn osc(&self, type_char: char, new_line: usize, old_line: Option<usize>) -> String {
         let old_field = old_line.map_or(String::new(), |n| n.to_string());
         format!(
@@ -280,6 +314,34 @@ mod tests {
         );
     }
 
+    #[test]
+    fn test_header_banner_file_and_hunk() {
+        // Every banner is a hunk header (`h`, carrying the hunk's first line);
+        // the first hunk's banner also announces the file, so it additionally
+        // carries the `f` record -- first, and without line numbers (spec §5.5).
+        let md = metadata();
+        assert_eq!(
+            md.header_banner(true, 1, "b.txt --- Rust"),
+            "\x1b]1717;1;f;;;a/b.txt\x1b\\\x1b]1717;1;h;1;;a/b.txt\x1b\\b.txt --- Rust"
+        );
+        assert_eq!(
+            md.header_banner(false, 16, "b.txt --- 2/2 --- Rust"),
+            "\x1b]1717;1;h;16;;a/b.txt\x1b\\b.txt --- 2/2 --- Rust"
+        );
+    }
+
+    #[test]
+    fn test_header_banner_tags_every_row() {
+        // A rename's first-hunk banner spans two rows (path, then old path);
+        // each row carries the same records (spec §6.4).
+        let md = metadata();
+        assert_eq!(
+            md.header_banner(true, 1, "new.txt --- Rust\nrenamed from old.txt"),
+            "\x1b]1717;1;f;;;a/b.txt\x1b\\\x1b]1717;1;h;1;;a/b.txt\x1b\\new.txt --- Rust\n\
+             \x1b]1717;1;f;;;a/b.txt\x1b\\\x1b]1717;1;h;1;;a/b.txt\x1b\\renamed from old.txt"
+        );
+    }
+
     #[test]
     fn test_row_is_novel_compares_contents_not_tokens() {
         let lhs_lines = ["foo(1)", "", "same"];

src/display/inline.rs

@@ -76,18 +76,6 @@ pub(crate) fn print(
     let rhs_line_nums_width = format_line_num(rhs_src.max_line()).len();
 
     for (i, hunk) in hunks.iter().enumerate() {
-        println!(
-            "{}",
-            style::header(
-                display_path,
-                extra_info.as_ref(),
-                i + 1,
-                hunks.len(),
-                file_format,
-                display_options
-            )
-        );
-
         let hunk_lines = hunk.lines.clone();
 
         let before_lines = calculate_before_context(
@@ -106,6 +94,30 @@ pub(crate) fn print(
             display_options.num_context_lines as usize,
         );
 
+        let banner = style::header(
+            display_path,
+            extra_info.as_ref(),
+            i + 1,
+            hunks.len(),
+            file_format,
+            display_options,
+        );
+        match &metadata {
+            // The banner announces both the file and this hunk: every banner
+            // carries the hunk's `h` (with the hunk's first new-file line), and
+            // the first hunk's banner additionally carries the file's `f`.
+            Some(metadata) => {
+                let new_line = before_lines
+                    .iter()
+                    .chain(hunk_lines.iter())
+                    .chain(after_lines.iter())
+                    .find_map(|(_, rhs)| rhs.map(|n| n.as_usize() + 1))
+                    .unwrap_or(1);
+                println!("{}", metadata.header_banner(i == 0, new_line, &banner));
+            }
+            None => println!("{}", banner),
+        }
+
         // Inline mode groups all old-side content (before-context, then
         // deletions) before all new-side content (additions, then
         // after-context). The metadata rides each line: the old-side passes

src/display/side_by_side.rs

@@ -81,15 +81,18 @@ fn display_single_column(
 
     let mut formatted_lines = Vec::with_capacity(src_lines.len());
 
-    let mut header_line = String::new();
-    header_line.push_str(&style::header(
-        display_path,
-        old_path,
-        1,
-        1,
-        file_format,
-        display_options,
-    ));
+    let banner = style::header(display_path, old_path, 1, 1, file_format, display_options);
+    let mut header_line = match metadata {
+        // A whole-file add/delete is a single hunk, so its banner carries the
+        // file's `f` and the hunk's `h`. A deleted file has no new-file
+        // content, so its hunk sits at new-line 0 (as for its deletion
+        // records); an added file's first new line is 1.
+        Some(metadata) => {
+            let new_line = if side == Side::Right { 1 } else { 0 };
+            metadata.header_banner(true, new_line, &banner)
+        }
+        None => banner,
+    };
     header_line.push('\n');
     formatted_lines.push(header_line);
 
@@ -426,6 +429,21 @@ fn visible_content_max_display_width(
     (lhs_content_max_width, rhs_content_max_width)
 }
 
+/// The new-file line a hunk's header banner points at: the first new-file
+/// (RHS) line shown in the hunk (spec §5.2). A hunk with no new-file lines at
+/// all (a pure deletion with no surrounding new context) falls back to the
+/// position the next new line would occupy, mirroring the deletion convention
+/// in `left_cell`.
+fn hunk_first_new_line(
+    aligned_lines: &[(Option<LineNumber>, Option<LineNumber>)],
+    prev_rhs: Option<LineNumber>,
+) -> usize {
+    aligned_lines
+        .iter()
+        .find_map(|(_, rhs)| rhs.map(|n| n.as_usize() + 1))
+        .unwrap_or_else(|| prev_rhs.map_or(1, |n| n.as_usize() + 2))
+}
+
 pub(crate) fn print(
     hunks: &[Hunk],
     display_options: &DisplayOptions,
@@ -608,18 +626,6 @@ pub(crate) fn print(
     );
 
     for (i, hunk) in hunks.iter().enumerate() {
-        println!(
-            "{}",
-            style::header(
-                display_path,
-                old_path,
-                i + 1,
-                hunks.len(),
-                file_format,
-                display_options
-            )
-        );
-
         let (start_i, end_i) = matched_lines_indexes_for_hunk(
             matched_lines_to_print,
             hunk,
@@ -633,6 +639,25 @@ pub(crate) fn print(
         // diffs.
         matched_lines_to_print = &matched_lines_to_print[start_i..];
 
+        let banner = style::header(
+            display_path,
+            old_path,
+            i + 1,
+            hunks.len(),
+            file_format,
+            display_options,
+        );
+        match &metadata {
+            // The banner announces both the file and this hunk: every banner
+            // carries the hunk's `h` (with the hunk's first new-file line), and
+            // the first hunk's banner additionally carries the file's `f`.
+            Some(metadata) => {
+                let new_line = hunk_first_new_line(aligned_lines, prev_rhs_line_num);
+                println!("{}", metadata.header_banner(i == 0, new_line, &banner));
+            }
+            None => println!("{}", banner),
+        }
+
         let no_lhs_changes = hunk.novel_lhs.is_empty();
         let no_rhs_changes = hunk.novel_rhs.is_empty();
         let same_lines = aligned_lines.iter().all(|(l, r)| l == r);