feat(error): offset-based span tracking

New methods `error()` and `error_at()` attach the current offset
so callers get location info in error messages.

Author: weihanglo

src/patch/error.rs

@@ -1,26 +1,51 @@
 //! Error types for patch parsing.
 
 use std::fmt;
+use std::ops::Range;
 
 /// An error returned when parsing a `Patch` using [`Patch::from_str`] fails.
 ///
 /// [`Patch::from_str`]: struct.Patch.html#method.from_str
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ParsePatchError {
     pub(crate) kind: ParsePatchErrorKind,
+    span: Option<Range<usize>>,
+}
+
+impl ParsePatchError {
+    /// Creates a new error with the given kind and span.
+    pub(crate) fn new(kind: ParsePatchErrorKind, span: Range<usize>) -> Self {
+        Self {
+            kind,
+            span: Some(span),
+        }
+    }
+
+    /// Returns the byte range in the input where the error occurred.
+    pub fn span(&self) -> Option<Range<usize>> {
+        self.span.clone()
+    }
 }
 
 impl fmt::Display for ParsePatchError {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        write!(f, "error parsing patch: {}", self.kind)
+        if let Some(span) = &self.span {
+            write!(
+                f,
+                "error parsing patch at byte {}: {}",
+                span.start, self.kind
+            )
+        } else {
+            write!(f, "error parsing patch: {}", self.kind)
+        }
     }
 }
 
 impl std::error::Error for ParsePatchError {}
 
 impl From<ParsePatchErrorKind> for ParsePatchError {
     fn from(kind: ParsePatchErrorKind) -> Self {
-        Self { kind }
+        Self { kind, span: None }
     }
 }
 

src/patch/parse.rs

@@ -29,15 +29,28 @@ impl<'a, T: Text + ?Sized> Parser<'a, T> {
         self.lines.peek()
     }
 
+    fn offset(&self) -> usize {
+        self.offset
+    }
+
     fn next(&mut self) -> Result<&'a T> {
         let line = self
             .lines
             .next()
-            .ok_or(ParsePatchErrorKind::UnexpectedEof)?;
+            .ok_or_else(|| self.error(ParsePatchErrorKind::UnexpectedEof))?;
         self.offset += line.len();
         Ok(line)
     }
 
+    /// Creates an error with the current offset as span.
+    fn error(&self, kind: ParsePatchErrorKind) -> ParsePatchError {
+        ParsePatchError::new(kind, self.offset..self.offset)
+    }
+
+    /// Creates an error with a specific offset as span.
+    fn error_at(&self, kind: ParsePatchErrorKind, offset: usize) -> ParsePatchError {
+        ParsePatchError::new(kind, offset..offset)
+    }
 }
 
 pub fn parse(input: &str) -> Result<Patch<'_, str>> {
@@ -80,12 +93,12 @@ fn patch_header<'a, T: Text + ToOwned + ?Sized>(
     while let Some(line) = parser.peek() {
         if line.starts_with("--- ") {
             if filename1.is_some() {
-                return Err(ParsePatchErrorKind::MultipleOriginalHeaders.into());
+                return Err(parser.error(ParsePatchErrorKind::MultipleOriginalHeaders));
             }
             filename1 = Some(parse_filename("--- ", parser.next()?)?);
         } else if line.starts_with("+++ ") {
             if filename2.is_some() {
-                return Err(ParsePatchErrorKind::MultipleModifiedHeaders.into());
+                return Err(parser.error(ParsePatchErrorKind::MultipleModifiedHeaders));
             }
             filename2 = Some(parse_filename("+++ ", parser.next()?)?);
         } else {
@@ -149,20 +162,23 @@ fn hunks<'a, T: Text + ?Sized>(parser: &mut Parser<'a, T>) -> Result<Vec<Hunk<'a
 
     // check and verify that the Hunks are in sorted order and don't overlap
     if !verify_hunks_in_order(&hunks) {
-        return Err(ParsePatchErrorKind::HunksOutOfOrder.into());
+        return Err(parser.error(ParsePatchErrorKind::HunksOutOfOrder));
     }
 
     Ok(hunks)
 }
 
 fn hunk<'a, T: Text + ?Sized>(parser: &mut Parser<'a, T>) -> Result<Hunk<'a, T>> {
-    let (range1, range2, function_context) = hunk_header(parser.next()?)?;
+    let hunk_start = parser.offset();
+    let header_line = parser.next()?;
+    let (range1, range2, function_context) =
+        hunk_header(header_line).map_err(|e| parser.error_at(e.kind, hunk_start))?;
     let lines = hunk_lines(parser)?;
 
     // check counts of lines to see if they match the ranges in the hunk header
     let (len1, len2) = super::hunk_lines_count(&lines);
     if len1 != range1.len || len2 != range2.len {
-        return Err(ParsePatchErrorKind::HunkMismatch.into());
+        return Err(parser.error_at(ParsePatchErrorKind::HunkMismatch, hunk_start));
     }
 
     Ok(Hunk::new(range1, range2, function_context, lines))
@@ -217,25 +233,25 @@ fn hunk_lines<'a, T: Text + ?Sized>(parser: &mut Parser<'a, T>) -> Result<Vec<Li
         let line = if line.starts_with("@") {
             break;
         } else if no_newline_context {
-            return Err(ParsePatchErrorKind::ExpectedEndOfHunk.into());
+            return Err(parser.error(ParsePatchErrorKind::ExpectedEndOfHunk));
         } else if let Some(line) = line.strip_prefix(" ") {
             Line::Context(line)
         } else if line.starts_with("\n") {
             Line::Context(*line)
         } else if let Some(line) = line.strip_prefix("-") {
             if no_newline_delete {
-                return Err(ParsePatchErrorKind::TooManyDeletedLines.into());
+                return Err(parser.error(ParsePatchErrorKind::TooManyDeletedLines));
             }
             Line::Delete(line)
         } else if let Some(line) = line.strip_prefix("+") {
             if no_newline_insert {
-                return Err(ParsePatchErrorKind::TooManyInsertedLines.into());
+                return Err(parser.error(ParsePatchErrorKind::TooManyInsertedLines));
             }
             Line::Insert(line)
         } else if line.starts_with(NO_NEWLINE_AT_EOF) {
             let last_line = lines
                 .pop()
-                .ok_or(ParsePatchErrorKind::UnexpectedNoNewlineMarker)?;
+                .ok_or_else(|| parser.error(ParsePatchErrorKind::UnexpectedNoNewlineMarker))?;
             match last_line {
                 Line::Context(line) => {
                     no_newline_context = true;
@@ -251,7 +267,7 @@ fn hunk_lines<'a, T: Text + ?Sized>(parser: &mut Parser<'a, T>) -> Result<Vec<Li
                 }
             }
         } else {
-            return Err(ParsePatchErrorKind::UnexpectedHunkLine.into());
+            return Err(parser.error(ParsePatchErrorKind::UnexpectedHunkLine));
         };
 
         lines.push(line);

src/patch/tests.rs

@@ -21,8 +21,8 @@ fn test_escaped_filenames() {
 +Oathbringer
 ";
     assert_eq!(
-        parse(s).unwrap_err(),
-        ParsePatchErrorKind::InvalidCharInUnquotedFilename.into(),
+        parse(s).unwrap_err().kind,
+        ParsePatchErrorKind::InvalidCharInUnquotedFilename,
     );
     parse_bytes(s.as_ref()).unwrap_err();
 
@@ -34,8 +34,8 @@ fn test_escaped_filenames() {
 +Oathbringer
 ";
     assert_eq!(
-        parse(s).unwrap_err(),
-        ParsePatchErrorKind::InvalidUnescapedChar.into(),
+        parse(s).unwrap_err().kind,
+        ParsePatchErrorKind::InvalidUnescapedChar,
     );
     parse_bytes(s.as_ref()).unwrap_err();
 
@@ -193,8 +193,8 @@ fn escaped_filename_octal() {
 +content
 "#;
     assert_eq!(
-        parse(s).unwrap_err(),
-        ParsePatchErrorKind::InvalidEscapedChar.into(),
+        parse(s).unwrap_err().kind,
+        ParsePatchErrorKind::InvalidEscapedChar,
     );
 
     // Non-octal digit in second position → error
@@ -205,8 +205,8 @@ fn escaped_filename_octal() {
 +content
 "#;
     assert_eq!(
-        parse(s).unwrap_err(),
-        ParsePatchErrorKind::InvalidEscapedChar.into(),
+        parse(s).unwrap_err().kind,
+        ParsePatchErrorKind::InvalidEscapedChar,
     );
 }
 
@@ -267,8 +267,8 @@ fn test_missing_filename_header() {
 +Oathbringer
 ";
     assert_eq!(
-        parse(s).unwrap_err(),
-        ParsePatchErrorKind::MultipleOriginalHeaders.into(),
+        parse(s).unwrap_err().kind,
+        ParsePatchErrorKind::MultipleOriginalHeaders,
     );
 }
 
@@ -396,7 +396,7 @@ mod error_display {
         let err = Patch::from_str(content).unwrap_err();
         assert_data_eq!(
             err.to_string(),
-            str!["error parsing patch: unable to parse hunk header"]
+            str!["error parsing patch at byte 28: unable to parse hunk header"]
         );
     }
 
@@ -412,7 +412,7 @@ mod error_display {
         let err = Patch::from_str(content).unwrap_err();
         assert_data_eq!(
             err.to_string(),
-            str!["error parsing patch: hunk header does not match hunk"]
+            str!["error parsing patch at byte 28: hunk header does not match hunk"]
         );
     }