feat!: Add BlameRanges to enable multi-range blame support

This update replaces single-range handling with the `BlameRanges` type, allowing multiple 1-based inclusive line ranges to be specified for blame operations.

It hides some of the implementation details of the range logic, prepares for compatibility with `git` behavior, and adds tests to validate multi-range scenarios.

Author: holodorum

gix-blame/src/file/function.rs

@@ -94,11 +94,15 @@ pub fn file(
         return Ok(Outcome::default());
     }
 
-    let range_in_blamed_file = one_based_inclusive_to_zero_based_exclusive_range(options.range, num_lines_in_blamed)?;
-    let mut hunks_to_blame = vec![UnblamedHunk {
-        range_in_blamed_file: range_in_blamed_file.clone(),
-        suspects: [(suspect, range_in_blamed_file)].into(),
-    }];
+    let ranges = options.range.to_zero_based_exclusive(num_lines_in_blamed)?;
+    let mut hunks_to_blame = Vec::with_capacity(ranges.len());
+
+    for range in ranges {
+        hunks_to_blame.push(UnblamedHunk {
+            range_in_blamed_file: range.clone(),
+            suspects: [(suspect, range)].into(),
+        });
+    }
 
     let (mut buf, mut buf2) = (Vec::new(), Vec::new());
     let commit = find_commit(cache.as_ref(), &odb, &suspect, &mut buf)?;
@@ -342,25 +346,6 @@ pub fn file(
     })
 }
 
-/// This function assumes that `range` has 1-based inclusive line numbers and converts it to the
-/// format internally used: 0-based line numbers stored in ranges that are exclusive at the
-/// end.
-fn one_based_inclusive_to_zero_based_exclusive_range(
-    range: Option<Range<u32>>,
-    max_lines: u32,
-) -> Result<Range<u32>, Error> {
-    let Some(range) = range else { return Ok(0..max_lines) };
-    if range.start == 0 {
-        return Err(Error::InvalidLineRange);
-    }
-    let start = range.start - 1;
-    let end = range.end;
-    if start >= max_lines || end > max_lines || start == end {
-        return Err(Error::InvalidLineRange);
-    }
-    Ok(start..end)
-}
-
 /// Pass ownership of each unblamed hunk of `from` to `to`.
 ///
 /// This happens when `from` didn't actually change anything in the blamed file.

gix-blame/src/lib.rs

@@ -17,7 +17,7 @@
 mod error;
 pub use error::Error;
 mod types;
-pub use types::{BlameEntry, Options, Outcome, Statistics};
+pub use types::{BlameEntry, BlameRanges, Options, Outcome, Statistics};
 
 mod file;
 pub use file::function::file;

gix-blame/src/types.rs

@@ -8,16 +8,142 @@ use gix_object::bstr::BString;
 use smallvec::SmallVec;
 
 use crate::file::function::tokens_for_diffing;
+use crate::Error;
+
+/// A type to represent one or more line ranges to blame in a file.
+///
+/// This type handles the conversion between git's 1-based inclusive ranges and the internal
+/// 0-based exclusive ranges used by the blame algorithm.
+///
+/// # Examples
+///
+/// ```rust
+/// use gix_blame::BlameRanges;
+///
+/// // Blame lines 20 through 40 (inclusive)
+/// let range = BlameRanges::from_range(20..41);
+///
+/// // Blame multiple ranges
+/// let mut ranges = BlameRanges::new();
+/// ranges.add_range(1..5);   // Lines 1-4
+/// ranges.add_range(10..15); // Lines 10-14
+/// ```
+///
+/// # Line Number Representation
+///
+/// This type uses 1-based inclusive ranges to mirror `git`'s behaviour:
+/// - A range of `20..41` represents 21 lines, spanning from line 20 up to and including line 40
+/// - This will be converted to `19..40` internally as the algorithm uses 0-based ranges that are exclusive at the end
+///
+/// # Empty Ranges
+///
+/// An empty `BlameRanges` (created via `BlameRanges::new()` or `BlameRanges::default()`) means
+/// to blame the entire file, similar to running `git blame` without line number arguments.
+#[derive(Debug, Clone, Default)]
+pub struct BlameRanges {
+    /// The ranges to blame, stored as 1-based inclusive ranges
+    /// An empty Vec means blame the entire file
+    ranges: Vec<Range<u32>>,
+}
+
+impl BlameRanges {
+    /// Create a new empty BlameRanges instance.
+    ///
+    /// An empty instance means to blame the entire file.
+    pub fn new() -> Self {
+        Self { ranges: Vec::new() }
+    }
+
+    /// Add a single range to blame.
+    ///
+    /// The range should be 1-based inclusive.
+    /// If the new range overlaps with or is adjacent to an existing range,
+    /// they will be merged into a single range.
+    pub fn add_range(&mut self, new_range: Range<u32>) {
+        self.merge_range(new_range);
+    }
+
+    /// Create from a single range.
+    ///
+    /// The range should be 1-based inclusive, similar to git's line number format.
+    pub fn from_range(range: Range<u32>) -> Self {
+        Self { ranges: vec![range] }
+    }
+
+    /// Create from multiple ranges.
+    ///
+    /// All ranges should be 1-based inclusive.
+    /// Overlapping or adjacent ranges will be merged.
+    pub fn from_ranges(ranges: Vec<Range<u32>>) -> Self {
+        let mut result = Self::new();
+        for range in ranges {
+            result.merge_range(range);
+        }
+        result
+    }
+
+    /// Attempts to merge the new range with any existing ranges.
+    /// If no merge is possible, adds it as a new range.
+    fn merge_range(&mut self, new_range: Range<u32>) {
+        // First check if this range can be merged with any existing range
+        for range in &mut self.ranges {
+            // Check if ranges overlap or are adjacent
+            if new_range.start <= range.end && range.start <= new_range.end {
+                // Merge the ranges by taking the minimum start and maximum end
+                range.start = range.start.min(new_range.start);
+                range.end = range.end.max(new_range.end);
+                return;
+            }
+        }
+        // If no overlap found, add as new range
+        self.ranges.push(new_range);
+    }
+
+    /// Convert the 1-based inclusive ranges to 0-based exclusive ranges.
+    ///
+    /// This is used internally by the blame algorithm to convert from git's line number format
+    /// to the internal format used for processing.
+    ///
+    /// # Errors
+    ///
+    /// Returns `Error::InvalidLineRange` if:
+    /// - Any range starts at 0 (must be 1-based)
+    /// - Any range extends beyond the file's length
+    /// - Any range has the same start and end
+    pub fn to_zero_based_exclusive(&self, max_lines: u32) -> Result<Vec<Range<u32>>, Error> {
+        if self.ranges.is_empty() {
+            let range = 0..max_lines;
+            return Ok(vec![range]);
+        }
+
+        let mut result = Vec::with_capacity(self.ranges.len());
+        for range in &self.ranges {
+            if range.start == 0 {
+                return Err(Error::InvalidLineRange);
+            }
+            let start = range.start - 1;
+            let end = range.end;
+            if start >= max_lines || end > max_lines || start == end {
+                return Err(Error::InvalidLineRange);
+            }
+            result.push(start..end);
+        }
+        Ok(result)
+    }
+
+    /// Returns true if no specific ranges are set (meaning blame entire file)
+    pub fn is_empty(&self) -> bool {
+        self.ranges.is_empty()
+    }
+}
 
 /// Options to be passed to [`file()`](crate::file()).
 #[derive(Default, Debug, Clone)]
 pub struct Options {
     /// The algorithm to use for diffing.
     pub diff_algorithm: gix_diff::blob::Algorithm,
-    /// A 1-based inclusive range, in order to mirror `git`’s behaviour. `Some(20..40)` represents
-    /// 21 lines, spanning from line 20 up to and including line 40. This will be converted to
-    /// `19..40` internally as the algorithm uses 0-based ranges that are exclusive at the end.
-    pub range: Option<std::ops::Range<u32>>,
+    /// The ranges to blame in the file.
+    pub range: BlameRanges,
     /// Don't consider commits before the given date.
     pub since: Option<gix_date::Time>,
 }

gix-blame/tests/blame.rs

@@ -1,5 +1,6 @@
 use std::path::PathBuf;
 
+use gix_blame::BlameRanges;
 use gix_hash::ObjectId;
 use gix_object::bstr;
 
@@ -193,7 +194,7 @@ macro_rules! mktest {
                 format!("{}.txt", $case).as_str().into(),
                 gix_blame::Options {
                     diff_algorithm: gix_diff::blob::Algorithm::Histogram,
-                    range: None,
+                    range: BlameRanges::default(),
                     since: None,
                 },
             )?
@@ -264,7 +265,7 @@ fn diff_disparity() {
             format!("{case}.txt").as_str().into(),
             gix_blame::Options {
                 diff_algorithm: gix_diff::blob::Algorithm::Histogram,
-                range: None,
+                range: BlameRanges::default(),
                 since: None,
             },
         )
@@ -296,7 +297,7 @@ fn line_range() {
         "simple.txt".into(),
         gix_blame::Options {
             diff_algorithm: gix_diff::blob::Algorithm::Histogram,
-            range: Some(1..2),
+            range: BlameRanges::from_range(1..2),
             since: None,
         },
     )
@@ -327,7 +328,7 @@ fn since() {
         "simple.txt".into(),
         gix_blame::Options {
             diff_algorithm: gix_diff::blob::Algorithm::Histogram,
-            range: None,
+            range: BlameRanges::default(),
             since: Some(gix_date::parse("2025-01-31", None).unwrap()),
         },
     )
@@ -342,6 +343,75 @@ fn since() {
     assert_eq!(lines_blamed, baseline);
 }
 
+#[test]
+fn multiple_ranges_using_add_range() {
+    let Fixture {
+        odb,
+        mut resource_cache,
+        suspect,
+    } = Fixture::new().unwrap();
+
+    let mut ranges = BlameRanges::new();
+    ranges.add_range(1..2); // Lines 1-2
+    ranges.add_range(1..1); // Duplicate range, should be ignored
+    ranges.add_range(4..4); // Line 4
+
+    let lines_blamed = gix_blame::file(
+        &odb,
+        suspect,
+        None,
+        &mut resource_cache,
+        "simple.txt".into(),
+        gix_blame::Options {
+            diff_algorithm: gix_diff::blob::Algorithm::Histogram,
+            range: ranges,
+            since: None,
+        },
+    )
+    .unwrap()
+    .entries;
+
+    assert_eq!(lines_blamed.len(), 3); // Should have 3 lines total (2 from first range + 1 from second range)
+
+    let git_dir = fixture_path().join(".git");
+    let baseline = Baseline::collect(git_dir.join("simple-lines-multiple-1-2-and-4.baseline")).unwrap();
+
+    assert_eq!(lines_blamed, baseline);
+}
+
+#[test]
+fn multiple_ranges_usingfrom_ranges() {
+    let Fixture {
+        odb,
+        mut resource_cache,
+        suspect,
+    } = Fixture::new().unwrap();
+
+    let ranges = BlameRanges::from_ranges(vec![1..2, 1..1, 4..4]);
+
+    let lines_blamed = gix_blame::file(
+        &odb,
+        suspect,
+        None,
+        &mut resource_cache,
+        "simple.txt".into(),
+        gix_blame::Options {
+            diff_algorithm: gix_diff::blob::Algorithm::Histogram,
+            range: ranges,
+            since: None,
+        },
+    )
+    .unwrap()
+    .entries;
+
+    assert_eq!(lines_blamed.len(), 3); // Should have 3 lines total (2 from first range + 1 from second range)
+
+    let git_dir = fixture_path().join(".git");
+    let baseline = Baseline::collect(git_dir.join("simple-lines-multiple-1-2-and-4.baseline")).unwrap();
+
+    assert_eq!(lines_blamed, baseline);
+}
+
 fn fixture_path() -> PathBuf {
     gix_testtools::scripted_fixture_read_only("make_blame_repo.sh").unwrap()
 }

gix-blame/tests/fixtures/make_blame_repo.sh

@@ -227,6 +227,7 @@ git merge branch-that-has-earlier-commit || true
 
 git blame --porcelain simple.txt > .git/simple.baseline
 git blame --porcelain -L 1,2 simple.txt > .git/simple-lines-1-2.baseline
+git blame --porcelain -L 1,2 -L 4 simple.txt > .git/simple-lines-multiple-1-2-and-4.baseline
 git blame --porcelain --since 2025-01-31 simple.txt > .git/simple-since.baseline
 git blame --porcelain multiline-hunks.txt > .git/multiline-hunks.baseline
 git blame --porcelain deleted-lines.txt > .git/deleted-lines.baseline