From 2b71eb9dc2dae9280d14769e33bb253fad775a63 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9=20S=C3=A1=20de=20Mello?= <codasm@pm.me>
Date: Mon, 18 Nov 2024 01:34:36 +0000
Subject: [PATCH 1/8] rework Diagnostic trait

---
 src/assign.rs  |  38 ++---
 src/pointer.rs | 188 ++--------------------
 src/report.rs  | 413 ++++++++++++++-----------------------------------
 3 files changed, 150 insertions(+), 489 deletions(-)

diff --git a/src/assign.rs b/src/assign.rs
index dc477f9..2b30439 100644
--- a/src/assign.rs
+++ b/src/assign.rs
@@ -38,9 +38,10 @@
 
 use crate::{
     index::{OutOfBoundsError, ParseIndexError},
-    report::{impl_diagnostic_url, Diagnostic, Label, Report, Subject},
-    Pointer, PointerBuf,
+    report::{impl_diagnostic_url, Enrich, Label},
+    Pointer,
 };
+use alloc::borrow::Cow;
 use core::{
     fmt::{self, Debug},
     iter::once,
@@ -227,40 +228,33 @@ impl fmt::Display for Error {
     }
 }
 
-impl_diagnostic_url!(enum assign::Error);
-
-impl Diagnostic for Error {
-    type Subject = PointerBuf;
-
-    fn into_report(self, source: Self::Subject) -> Report<Self> {
-        Report::new(self, source)
-    }
+impl<'s> Enrich<'s> for Error {
+    type Subject = Cow<'s, Pointer>;
 
     fn url() -> &'static str {
-        Self::url()
+        impl_diagnostic_url!(enum assign::Error)
     }
 
-    fn labels(&self, origin: &Subject) -> Option<Box<dyn Iterator<Item = Label>>> {
-        let ptr = origin.as_pointer_buf()?;
+    fn labels(&self, origin: &Self::Subject) -> Option<Box<dyn Iterator<Item = Label>>> {
         let position = self.position();
-        let token = ptr.get(position)?;
-        let offset = if self.offset() + 1 < ptr.as_str().len() {
+        let token = origin.get(position)?;
+        let offset = if self.offset() + 1 < origin.as_str().len() {
             self.offset() + 1
         } else {
             self.offset()
         };
         let len = token.encoded().len();
         Some(match self {
-            Error::FailedToParseIndex { .. } => Box::new(once(Label {
-                len,
+            Error::FailedToParseIndex { .. } => Box::new(once(Label::new(
+                format!("\"{}\" is an invalid array index", token.decoded()),
                 offset,
-                text: format!("\"{}\" is an invalid array index", token.decoded()),
-            })),
-            Error::OutOfBounds { source, .. } => Box::new(once(Label {
+                len,
+            ))),
+            Error::OutOfBounds { source, .. } => Box::new(once(Label::new(
+                format!("{} is out of bounds (len: {})", source.index, source.length),
                 offset,
                 len,
-                text: format!("{} is out of bounds (len: {})", source.index, source.length),
-            })),
+            ))),
         })
     }
 }
diff --git a/src/pointer.rs b/src/pointer.rs
index 22f0cc0..44f4de5 100644
--- a/src/pointer.rs
+++ b/src/pointer.rs
@@ -1,10 +1,10 @@
 use crate::{
-    report::{impl_diagnostic_url, Diagnostic, Label, Report, Subject},
+    report::{impl_diagnostic_url, Enrich, Enriched, Label},
     token::InvalidEncodingError,
     Components, Token, Tokens,
 };
 use alloc::{
-    borrow::ToOwned,
+    borrow::{Cow, ToOwned},
     boxed::Box,
     fmt,
     string::{String, ToString},
@@ -215,6 +215,7 @@ impl Pointer {
             )
             .into()
     }
+
     /// Splits the `Pointer` at the given index if the character at the index is
     /// a separator backslash (`'/'`), returning `Some((head, tail))`. Otherwise,
     /// returns `None`.
@@ -910,10 +911,12 @@ impl PointerBuf {
     ///
     /// ## Errors
     /// Returns a [`RichParseError`] if the string is not a valid JSON Pointer.
-    pub fn parse(s: impl Into<String>) -> Result<Self, RichParseError> {
+    pub fn parse<'s>(s: impl Into<Cow<'s, str>>) -> Result<Self, Enriched<'s, ParseError>> {
         let s = s.into();
-        validate(&s).map_err(|err| err.with_subject(s.clone()))?;
-        Ok(Self(s))
+        match validate(&s) {
+            Ok(_) => Ok(Self(s.into_owned())),
+            Err(err) => Err(err.enrich(s)),
+        }
     }
 
     /// Creates a new `PointerBuf` from a slice of non-encoded strings.
@@ -1023,25 +1026,6 @@ impl PointerBuf {
     pub fn clear(&mut self) {
         self.0.clear();
     }
-
-    pub fn offset_for_position(&self, position: usize) -> Option<usize> {
-        if position == 0 {
-            return Some(0);
-        }
-        let bytes = self.0.as_bytes();
-        let mut i = 0;
-        let mut current = 0;
-        while i < bytes.len() && current <= position {
-            if bytes[i] == b'/' {
-                current += 1;
-                if current == position {
-                    return Some(i + 1);
-                }
-            }
-            i += 1;
-        }
-        None
-    }
 }
 
 impl FromStr for PointerBuf {
@@ -1207,121 +1191,6 @@ const fn validate(value: &str) -> Result<&str, ParseError> {
     Ok(value)
 }
 
-/*
-░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
-╔══════════════════════════════════════════════════════════════════════════════╗
-║                                                                              ║
-║                              TopicalParseError                               ║
-║                             ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯                              ║
-╚══════════════════════════════════════════════════════════════════════════════╝
-░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
-*/
-#[derive(Debug, PartialEq)]
-pub struct RichParseError {
-    subject: String,
-    source: ParseError,
-}
-
-impl RichParseError {
-    pub fn new(subject: String, source: ParseError) -> Self {
-        Self { subject, source }
-    }
-
-    pub fn subject(&self) -> &str {
-        &self.subject
-    }
-
-    pub fn source(&self) -> &ParseError {
-        &self.source
-    }
-
-    // TODO: should this be pub?
-    pub(crate) fn take(self) -> (ParseError, String) {
-        (self.source, self.subject)
-    }
-}
-
-#[cfg(feature = "std")]
-impl std::error::Error for RichParseError {
-    fn source(&self) -> Option<&(dyn core::error::Error + 'static)> {
-        Some(&self.source)
-    }
-}
-
-#[cfg(feature = "miette")]
-impl miette::Diagnostic for RichParseError {
-    fn url<'a>(&'a self) -> Option<Box<dyn core::fmt::Display + 'a>> {
-        Some(Box::new(Self::url()))
-    }
-
-    fn source_code(&self) -> Option<&dyn miette::SourceCode> {
-        Some(&self.subject)
-    }
-
-    fn labels(&self) -> Option<Box<dyn Iterator<Item = miette::LabeledSpan> + '_>> {
-        Some(Box::new(
-            self.source.create_labels(&self.subject).map(Into::into),
-        ))
-    }
-}
-
-impl core::fmt::Display for RichParseError {
-    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
-        core::fmt::Display::fmt(&self.source, f)
-    }
-}
-
-impl From<RichParseError> for ParseError {
-    fn from(value: RichParseError) -> Self {
-        value.source
-    }
-}
-
-impl From<Report<ParseError>> for RichParseError {
-    fn from(value: Report<ParseError>) -> Self {
-        let (err, subj) = value.take();
-        Self::new(subj.to_string(), err)
-    }
-}
-
-impl From<Report<RichParseError>> for RichParseError {
-    fn from(value: Report<RichParseError>) -> Self {
-        let (err, _) = value.take();
-        err
-    }
-}
-impl From<RichParseError> for Report<RichParseError> {
-    fn from(err: RichParseError) -> Self {
-        let subj = err.subject().to_string();
-        Report::new(err, subj)
-    }
-}
-
-impl From<RichParseError> for Report<ParseError> {
-    fn from(err: RichParseError) -> Self {
-        let (err, subj) = err.take();
-        Report::new(err, subj)
-    }
-}
-
-impl_diagnostic_url!(struct RichParseError);
-
-impl Diagnostic for RichParseError {
-    type Subject = ();
-
-    fn into_report(self, (): Self::Subject) -> Report<Self> {
-        let subject = Subject::String(self.subject.clone());
-        Report::new(self, subject)
-    }
-
-    fn url() -> &'static str {
-        Self::url()
-    }
-    fn labels(&self, subject: &Subject) -> Option<Box<dyn Iterator<Item = Label>>> {
-        self.source.labels(subject)
-    }
-}
-
 /*
 ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
 ╔══════════════════════════════════════════════════════════════════════════════╗
@@ -1348,6 +1217,7 @@ pub enum ParseError {
         source: InvalidEncodingError,
     },
 }
+
 impl ParseError {
     pub fn offset(&self) -> usize {
         match self {
@@ -1356,13 +1226,6 @@ impl ParseError {
         }
     }
 
-    pub fn with_subject(self, value: String) -> RichParseError {
-        RichParseError {
-            source: self,
-            subject: value,
-        }
-    }
-
     pub fn invalid_encoding_len(&self, subject: &str) -> usize {
         match self {
             Self::NoLeadingBackslash => 0,
@@ -1377,27 +1240,15 @@ impl ParseError {
     }
 }
 
-impl_diagnostic_url!(struct ParseError);
-
-impl Diagnostic for ParseError {
-    type Subject = String;
-
-    fn into_report(self, subject: Self::Subject) -> Report<Self> {
-        Report::new(self, subject)
-    }
+impl<'s> Enrich<'s> for ParseError {
+    type Subject = Cow<'s, str>;
 
     fn url() -> &'static str {
-        Self::url()
+        impl_diagnostic_url!(struct ParseError)
     }
 
-    fn labels(&self, subject: &Subject) -> Option<Box<dyn Iterator<Item = Label>>> {
+    fn labels(&self, subject: &Self::Subject) -> Option<Box<dyn Iterator<Item = Label>>> {
         // TODO: considering searching the pointer for all invalid encodings
-        Some(self.create_labels(subject.as_string()?))
-    }
-}
-
-impl ParseError {
-    fn create_labels(&self, subject: &str) -> Box<dyn Iterator<Item = Label>> {
         let offset = self.complete_offset();
         let len = self.invalid_encoding_len(subject);
         let text = match self {
@@ -1405,9 +1256,10 @@ impl ParseError {
             ParseError::InvalidEncoding { .. } => "'~' must be followed by '0' or '1'",
         }
         .to_string();
-        Box::new(once(Label { text, offset, len }))
+        Some(Box::new(once(Label::new(text, offset, len))))
     }
 }
+
 impl fmt::Display for ParseError {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         match self {
@@ -1541,8 +1393,6 @@ impl std::error::Error for ReplaceError {}
 mod tests {
     use std::error::Error;
 
-    use crate::report::Diagnose;
-
     use super::*;
     use quickcheck::TestResult;
     use quickcheck_macros::quickcheck;
@@ -1929,14 +1779,6 @@ mod tests {
         );
     }
 
-    #[test]
-    fn into_report() {
-        let report = Pointer::parse("invalid~encoding")
-            .diagnose_with(|| "invalid~encoding")
-            .unwrap_err();
-        assert_eq!(report.subject(), "invalid~encoding");
-    }
-
     #[test]
     fn get() {
         let ptr = Pointer::from_static("/0/1/2/3/4/5/6/7/8/9");
diff --git a/src/report.rs b/src/report.rs
index 2dca0f4..4aa42d7 100644
--- a/src/report.rs
+++ b/src/report.rs
@@ -1,106 +1,122 @@
 //! Error reporting data structures and miette integration.
 
-use crate::{Pointer, PointerBuf, Token};
+use core::fmt;
 
 /// Implemented by errors which can be converted into a [`Report`].
-pub trait Diagnostic: Sized {
+pub trait Enrich<'s>: Sized + private::Sealed {
     /// The value which caused the error.
     type Subject;
 
-    /// Convert the error into a [`Report`].
-    fn into_report(self, subject: Self::Subject) -> Report<Self>;
+    /// Enrich the error with its subject.
+    fn enrich(self, subject: Self::Subject) -> Enriched<'s, Self> {
+        Enriched::new(self, subject)
+    }
 
     /// The docs.rs URL for this error
     fn url() -> &'static str;
 
     /// Returns the label for the given [`Subject`] if applicable.
-    fn labels(&self, subject: &Subject) -> Option<Box<dyn Iterator<Item = Label>>>;
+    fn labels(&self, subject: &Self::Subject) -> Option<Box<dyn Iterator<Item = Label>>>;
 }
 
 /// A label for a span within a json pointer or malformed string.
 #[derive(Debug, PartialEq, Eq, Clone)]
 pub struct Label {
-    /// The text for the label.
-    pub text: String,
-    /// The offset of the label.
-    pub offset: usize,
-    /// The length of the label.
-    pub len: usize,
+    text: String,
+    offset: usize,
+    len: usize,
 }
 
 impl Label {
-    #[cfg(feature = "miette")]
-    pub fn into_miette_labeled_span(self) -> miette::LabeledSpan {
-        miette::LabeledSpan::new(Some(self.text), self.offset, self.len)
+    /// Creates a new instance of a [`Label`] from its parts
+    pub fn new(text: String, offset: usize, len: usize) -> Self {
+        Self { text, offset, len }
     }
 }
 
 #[cfg(feature = "miette")]
 impl From<Label> for miette::LabeledSpan {
-    fn from(label: Label) -> Self {
-        label.into_miette_labeled_span()
+    fn from(value: Label) -> Self {
+        miette::LabeledSpan::new(Some(value.text), value.offset, value.len)
     }
 }
 
 /// An error wrapper which includes the [`String`] which failed to parse or the
 /// [`PointerBuf`] being used.
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct Report<E> {
-    /// The error which occurred.
-    source: E,
-    /// The value which caused the error.
-    subject: Subject,
+#[derive(Clone, PartialEq, Eq)]
+pub struct Enriched<'s, S: Enrich<'s>> {
+    source: S,
+    subject: S::Subject,
 }
 
-impl<E: Diagnostic> Report<E> {
+impl<'s, S: Enrich<'s>> Enriched<'s, S> {
     /// Create a new `Report` with the given subject and error.
-    pub fn new(error: E, subject: impl Into<Subject>) -> Self {
+    fn new(source: S, subject: impl Into<S::Subject>) -> Self {
         Self {
-            source: error,
+            source,
             subject: subject.into(),
         }
     }
 
+    /// Returns labels associated with spans where the error occurs.
     pub fn labels(&self) -> Option<Box<dyn Iterator<Item = Label>>> {
         self.source.labels(&self.subject)
     }
 
-    pub fn subject(&self) -> &Subject {
+    /// The value which caused the error.
+    pub fn subject(&self) -> &S::Subject {
         &self.subject
     }
 
-    pub fn source(&self) -> &E {
+    /// The error which occurred.
+    pub fn source(&self) -> &S {
         &self.source
     }
 
-    // TODO: should this be pub?
-    pub(crate) fn take(self) -> (E, Subject) {
-        (self.source, self.subject)
+    /// The docs.rs URL for the error of this [`Report`].
+    pub fn url() -> &'static str {
+        S::url()
     }
 }
 
-impl<E: Diagnostic> Report<E> {
-    /// The docs.rs URL for the error of this [`Report`].
-    fn url() -> &'static str {
-        E::url()
+impl<'s, S> fmt::Display for Enriched<'s, S>
+where
+    S: Enrich<'s> + fmt::Display,
+{
+    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
+        fmt::Display::fmt(&self.source, f)
     }
 }
 
-impl<E> core::fmt::Display for Report<E>
+impl<'s, S> fmt::Debug for Enriched<'s, S>
 where
-    E: core::fmt::Display,
+    S: Enrich<'s> + fmt::Debug,
+    S::Subject: fmt::Debug,
 {
-    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
-        core::fmt::Display::fmt(&self.source, f)
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.debug_struct("Enriched")
+            .field("source", &self.source)
+            .field("subject", &self.subject)
+            .finish()
     }
 }
 
-impl<E> std::error::Error for Report<E> where E: std::error::Error {}
+#[cfg(feature = "std")]
+impl<'s, S> std::error::Error for Enriched<'s, S>
+where
+    S: Enrich<'s> + fmt::Debug + std::error::Error + 'static,
+    S::Subject: fmt::Debug,
+{
+    fn source(&self) -> Option<&(dyn core::error::Error + 'static)> {
+        Some(&self.source)
+    }
+}
 
 #[cfg(feature = "miette")]
-impl<E> miette::Diagnostic for Report<E>
+impl<'s, S> miette::Diagnostic for Enriched<'s, S>
 where
-    E: Diagnostic + std::error::Error,
+    S: Enrich<'s> + fmt::Debug + std::error::Error + 'static,
+    S::Subject: fmt::Debug + miette::SourceCode,
 {
     fn url<'a>(&'a self) -> Option<Box<dyn core::fmt::Display + 'a>> {
         Some(Box::new(Self::url()))
@@ -115,270 +131,79 @@ where
     }
 }
 
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub enum Subject {
-    String(String),
-    PointerBuf(PointerBuf),
-}
-impl core::fmt::Display for Subject {
-    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
-        match self {
-            Self::String(s) => core::fmt::Display::fmt(s, f),
-            Self::PointerBuf(p) => core::fmt::Display::fmt(p, f),
-        }
-    }
-}
-
-impl Subject {
-    pub fn as_str(&self) -> &str {
-        match self {
-            Self::String(s) => s.as_str(),
-            Self::PointerBuf(p) => p.as_str(),
-        }
-    }
-    /// Returns a reference to the string if this `Subject` is a `String`.
-    /// Returns `None` if  is a `PointerBuf`.
-    pub fn as_string(&self) -> Option<&String> {
-        match self {
-            Self::String(s) => Some(s),
-            Self::PointerBuf(_) => None,
-        }
-    }
-
-    /// Returns a reference to the [`PointerBuf`] if this `Subject` is a `PointerBuf`.
-    pub fn as_pointer_buf(&self) -> Option<&PointerBuf> {
-        match self {
-            Self::PointerBuf(p) => Some(p),
-            Self::String(_) => None,
-        }
-    }
-
-    /// If this `Source` is a `PointerBuf`, returns the offset of the given
-    /// token position (index).
-    pub fn offset_for_position(&self, position: usize) -> Option<usize> {
-        let ptr = self.as_pointer_buf()?;
-        ptr.get(0..position).map(|s| s.as_str().len())
-    }
-
-    /// If this `Source` is a `PointerBuf`, returns the token at
-    /// the given position (index), if it exists.
-    pub fn token(&self, position: usize) -> Option<Token> {
-        self.as_pointer_buf().and_then(|ptr| ptr.get(position))
-    }
-
-    /// Returns `true` if the subject is [`String`].
-    ///
-    /// [`String`]: Subject::String
-    #[must_use]
-    pub fn is_string(&self) -> bool {
-        matches!(self, Self::String(..))
-    }
-
-    /// Returns `true` if the subject is [`PointerBuf`].
-    ///
-    /// [`PointerBuf`]: Subject::PointerBuf
-    #[must_use]
-    pub fn is_pointer_buf(&self) -> bool {
-        matches!(self, Self::PointerBuf(..))
-    }
-
-    /// ## Errors
-    /// Returns `Self` if the [`Subject`] is not a `String`.
-    pub fn try_into_string(self) -> Result<String, Self> {
-        if let Self::String(v) = self {
-            Ok(v)
-        } else {
-            Err(self)
-        }
-    }
-    /// ## Errors
-    /// Returns `Self` if the [`Subject`] is not a `PointerBuf`.
-    pub fn try_into_pointer_buf(self) -> Result<PointerBuf, Self> {
-        if let Self::PointerBuf(v) = self {
-            Ok(v)
-        } else {
-            Err(self)
-        }
-    }
-}
-
-#[cfg(feature = "miette")]
-impl miette::SourceCode for Subject {
-    fn read_span<'a>(
-        &'a self,
-        span: &miette::SourceSpan,
-        context_lines_before: usize,
-        context_lines_after: usize,
-    ) -> Result<Box<dyn miette::SpanContents<'a> + 'a>, miette::MietteError> {
-        self.as_str()
-            .read_span(span, context_lines_before, context_lines_after)
-    }
-}
-
-impl PartialEq<str> for Subject {
-    fn eq(&self, other: &str) -> bool {
-        match self {
-            Self::String(this) => this == other,
-            Self::PointerBuf(this) => this.as_str() == other,
-        }
-    }
-}
-impl PartialEq<Subject> for str {
-    fn eq(&self, other: &Subject) -> bool {
-        other == self
-    }
-}
-impl PartialEq<Pointer> for Subject {
-    fn eq(&self, other: &Pointer) -> bool {
-        self == other.as_str()
-    }
-}
-impl PartialEq<Subject> for String {
-    fn eq(&self, other: &Subject) -> bool {
-        self == other.as_str()
-    }
-}
-impl PartialEq<String> for Subject {
-    fn eq(&self, other: &String) -> bool {
-        self == other.as_str()
-    }
-}
-impl PartialEq<Subject> for Pointer {
-    fn eq(&self, other: &Subject) -> bool {
-        self.as_str() == other
-    }
-}
-impl From<&str> for Subject {
-    fn from(value: &str) -> Self {
-        Self::String(value.to_string())
-    }
-}
-impl From<&Pointer> for Subject {
-    fn from(value: &Pointer) -> Self {
-        Self::PointerBuf(value.to_buf())
-    }
-}
-impl From<PointerBuf> for Subject {
-    fn from(value: PointerBuf) -> Self {
-        Self::PointerBuf(value)
-    }
-}
-impl From<String> for Subject {
-    fn from(value: String) -> Self {
-        Self::String(value)
-    }
-}
-
-pub trait Diagnose<T> {
-    type Error: Diagnostic;
-
-    #[allow(clippy::missing_errors_doc)]
-    fn diagnose(
-        self,
-        subject: impl Into<<Self::Error as Diagnostic>::Subject>,
-    ) -> Result<T, Report<Self::Error>>;
-
-    #[allow(clippy::missing_errors_doc)]
-    fn diagnose_with<F, S>(self, f: F) -> Result<T, Report<Self::Error>>
-    where
-        F: FnOnce() -> S,
-        S: Into<<Self::Error as Diagnostic>::Subject>;
-}
-
-impl<T, E> Diagnose<T> for Result<T, E>
-where
-    E: Diagnostic,
-{
-    type Error = E;
-
-    fn diagnose(
-        self,
-        subject: impl Into<<Self::Error as Diagnostic>::Subject>,
-    ) -> Result<T, Report<Self::Error>> {
-        self.map_err(|error| error.into_report(subject.into()))
-    }
-
-    fn diagnose_with<F, S>(self, f: F) -> Result<T, Report<Self::Error>>
-    where
-        F: FnOnce() -> S,
-        S: Into<<Self::Error as Diagnostic>::Subject>,
-    {
-        self.diagnose(f())
-    }
-}
-
 macro_rules! impl_diagnostic_url {
     (enum $type:ident) => {
-        crate::report::impl_diagnostic_url!("enum", "", $type);
+        $crate::report::impl_diagnostic_url!("enum", "", $type)
     };
     (struct $type:ident) => {
-        crate::report::impl_diagnostic_url!("struct", "", $type);
+        $crate::report::impl_diagnostic_url!("struct", "", $type)
     };
     (enum $mod:ident::$type:ident) => {
-        crate::report::impl_diagnostic_url!("enum", concat!("/", stringify!($mod)), $type);
+        $crate::report::impl_diagnostic_url!("enum", concat!("/", stringify!($mod)), $type)
     };
     (struct $mod:ident::$type:ident) => {
-        crate::report::impl_diagnostic_url!("struct", concat!("/", stringify!($mod)), $type);
+        $crate::report::impl_diagnostic_url!("struct", concat!("/", stringify!($mod)), $type)
     };
     ($kind:literal, $mod:expr, $type:ident) => {
-        impl $type {
-            #[doc = "The docs.rs URL for this error"]
-            pub const fn url() -> &'static str {
-                concat!(
-                    "https://docs.rs/jsonptr/",
-                    env!("CARGO_PKG_VERSION"),
-                    "/jsonptr",
-                    $mod,
-                    "/",
-                    $kind,
-                    ".",
-                    stringify!($type),
-                    ".html",
-                )
-            }
-        }
+        concat!(
+            "https://docs.rs/jsonptr/",
+            env!("CARGO_PKG_VERSION"),
+            "/jsonptr",
+            $mod,
+            "/",
+            $kind,
+            ".",
+            stringify!($type),
+            ".html",
+        )
     };
 }
 pub(crate) use impl_diagnostic_url;
 
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[test]
-    #[cfg(all(
-        feature = "assign",
-        feature = "miette",
-        feature = "serde",
-        feature = "json"
-    ))]
-    fn assign_error() {
-        use crate::assign::Error;
-
-        let mut v = serde_json::json!({"foo": {"bar": ["0"]}});
-
-        let ptr = PointerBuf::parse("/foo/bar/invalid/cannot/reach").unwrap();
-        let report = ptr.assign(&mut v, "qux").diagnose(ptr).unwrap_err();
-        println!("{:?}", miette::Report::from(report));
-
-        let ptr = PointerBuf::parse("/foo/bar/3/cannot/reach").unwrap();
-        let report = ptr.assign(&mut v, "qux").diagnose(ptr).unwrap_err();
-        println!("{:?}", miette::Report::from(report));
-    }
-
-    #[test]
-    fn parse_error() {
-        let invalid = "/foo/bar/invalid~3~encoding/cannot/reach";
-        let report = Pointer::parse(invalid).diagnose(invalid).unwrap_err();
-
-        println!("{:?}", miette::Report::from(report));
-
-        // TODO: impl `miette::Diagnostic` for `RichParseError`
-        let report = PointerBuf::parse("/foo/bar/invalid~3~encoding/cannot/reach")
-            .diagnose(())
-            .unwrap_err();
-
-        let report = miette::Report::from(report);
-        println!("{report:?}");
-    }
-}
+mod private {
+    pub trait Sealed {}
+    impl Sealed for crate::pointer::ParseError {}
+    impl Sealed for crate::assign::Error {}
+}
+
+// #[cfg(test)]
+// mod tests {
+//     use super::*;
+
+//     #[test]
+//     #[cfg(all(
+//         feature = "assign",
+//         feature = "miette",
+//         feature = "serde",
+//         feature = "json"
+//     ))]
+//     fn assign_error() {
+//         use crate::assign::Error;
+
+//         let mut v = serde_json::json!({"foo": {"bar": ["0"]}});
+
+//         let ptr = PointerBuf::parse("/foo/bar/invalid/cannot/reach").unwrap();
+//         let report = ptr.assign(&mut v, "qux").diagnose(ptr).unwrap_err();
+//         println!("{:?}", miette::Report::from(report));
+
+//         let ptr = PointerBuf::parse("/foo/bar/3/cannot/reach").unwrap();
+//         let report = ptr.assign(&mut v, "qux").diagnose(ptr).unwrap_err();
+//         println!("{:?}", miette::Report::from(report));
+//     }
+
+//     #[test]
+//     fn parse_error() {
+//         let invalid = "/foo/bar/invalid~3~encoding/cannot/reach";
+//         let report = Pointer::parse(invalid).diagnose(invalid).unwrap_err();
+
+//         println!("{:?}", miette::Report::from(report));
+
+//         // TODO: impl `miette::Diagnostic` for `RichParseError`
+//         let report = PointerBuf::parse("/foo/bar/invalid~3~encoding/cannot/reach")
+//             .diagnose(())
+//             .unwrap_err();
+
+//         let report = miette::Report::from(report);
+//         println!("{report:?}");
+//     }
+// }

From 8b63c7a53e5dcde3c538d27d2bdb87b64d4e8647 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9=20S=C3=A1=20de=20Mello?= <codasm@pm.me>
Date: Mon, 18 Nov 2024 02:00:56 +0000
Subject: [PATCH 2/8] add diagnose back + tests

---
 src/pointer.rs |  37 ++++++++++++++++
 src/report.rs  | 118 +++++++++++++++++++++++++++++++------------------
 2 files changed, 113 insertions(+), 42 deletions(-)

diff --git a/src/pointer.rs b/src/pointer.rs
index 44f4de5..6a7a817 100644
--- a/src/pointer.rs
+++ b/src/pointer.rs
@@ -644,6 +644,37 @@ impl<'de: 'p, 'p> serde::Deserialize<'de> for &'p Pointer {
     }
 }
 
+macro_rules! impl_source_code {
+    ($($ty:ty),+) => {
+        $(
+            #[cfg(feature = "miette")]
+            impl miette::SourceCode for $ty {
+                fn read_span<'a>(
+                    &'a self,
+                    span: &miette::SourceSpan,
+                    context_lines_before: usize,
+                    context_lines_after: usize,
+                ) -> Result<Box<dyn miette::SpanContents<'a> + 'a>, miette::MietteError> {
+                    miette::SourceCode::read_span(
+                        self.0.as_bytes(),
+                        span,
+                        context_lines_before,
+                        context_lines_after,
+                    )
+                }
+            }
+        )*
+    };
+}
+
+impl_source_code!(Pointer, &Pointer);
+
+impl<'p> From<&'p Pointer> for Cow<'p, Pointer> {
+    fn from(value: &'p Pointer) -> Self {
+        Cow::Borrowed(value)
+    }
+}
+
 impl ToOwned for Pointer {
     type Owned = PointerBuf;
 
@@ -1079,6 +1110,12 @@ impl serde::Serialize for PointerBuf {
     }
 }
 
+impl From<PointerBuf> for Cow<'static, Pointer> {
+    fn from(value: PointerBuf) -> Self {
+        Cow::Owned(value)
+    }
+}
+
 impl From<Token<'_>> for PointerBuf {
     fn from(t: Token) -> Self {
         PointerBuf::from_tokens([t])
diff --git a/src/report.rs b/src/report.rs
index 4aa42d7..f738d83 100644
--- a/src/report.rs
+++ b/src/report.rs
@@ -8,7 +8,7 @@ pub trait Enrich<'s>: Sized + private::Sealed {
     type Subject;
 
     /// Enrich the error with its subject.
-    fn enrich(self, subject: Self::Subject) -> Enriched<'s, Self> {
+    fn enrich(self, subject: impl Into<Self::Subject>) -> Enriched<'s, Self> {
         Enriched::new(self, subject)
     }
 
@@ -166,44 +166,78 @@ mod private {
     impl Sealed for crate::assign::Error {}
 }
 
-// #[cfg(test)]
-// mod tests {
-//     use super::*;
-
-//     #[test]
-//     #[cfg(all(
-//         feature = "assign",
-//         feature = "miette",
-//         feature = "serde",
-//         feature = "json"
-//     ))]
-//     fn assign_error() {
-//         use crate::assign::Error;
-
-//         let mut v = serde_json::json!({"foo": {"bar": ["0"]}});
-
-//         let ptr = PointerBuf::parse("/foo/bar/invalid/cannot/reach").unwrap();
-//         let report = ptr.assign(&mut v, "qux").diagnose(ptr).unwrap_err();
-//         println!("{:?}", miette::Report::from(report));
-
-//         let ptr = PointerBuf::parse("/foo/bar/3/cannot/reach").unwrap();
-//         let report = ptr.assign(&mut v, "qux").diagnose(ptr).unwrap_err();
-//         println!("{:?}", miette::Report::from(report));
-//     }
-
-//     #[test]
-//     fn parse_error() {
-//         let invalid = "/foo/bar/invalid~3~encoding/cannot/reach";
-//         let report = Pointer::parse(invalid).diagnose(invalid).unwrap_err();
-
-//         println!("{:?}", miette::Report::from(report));
-
-//         // TODO: impl `miette::Diagnostic` for `RichParseError`
-//         let report = PointerBuf::parse("/foo/bar/invalid~3~encoding/cannot/reach")
-//             .diagnose(())
-//             .unwrap_err();
-
-//         let report = miette::Report::from(report);
-//         println!("{report:?}");
-//     }
-// }
+pub trait Diagnose<'s, T> {
+    type Error: Enrich<'s>;
+
+    #[allow(clippy::missing_errors_doc)]
+    fn diagnose(
+        self,
+        subject: impl Into<<Self::Error as Enrich<'s>>::Subject>,
+    ) -> Result<T, Enriched<'s, Self::Error>>;
+
+    #[allow(clippy::missing_errors_doc)]
+    fn diagnose_with<F, S>(self, f: F) -> Result<T, Enriched<'s, Self::Error>>
+    where
+        F: FnOnce() -> S,
+        S: Into<<Self::Error as Enrich<'s>>::Subject>;
+}
+
+impl<'s, T, E> Diagnose<'s, T> for Result<T, E>
+where
+    E: Enrich<'s>,
+{
+    type Error = E;
+
+    fn diagnose(
+        self,
+        subject: impl Into<<Self::Error as Enrich<'s>>::Subject>,
+    ) -> Result<T, Enriched<'s, Self::Error>> {
+        self.map_err(|error| error.enrich(subject.into()))
+    }
+
+    fn diagnose_with<F, S>(self, f: F) -> Result<T, Enriched<'s, Self::Error>>
+    where
+        F: FnOnce() -> S,
+        S: Into<<Self::Error as Enrich<'s>>::Subject>,
+    {
+        self.diagnose(f())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::{Pointer, PointerBuf};
+
+    #[test]
+    #[cfg(all(
+        feature = "assign",
+        feature = "miette",
+        feature = "serde",
+        feature = "json"
+    ))]
+    fn assign_error() {
+        let mut v = serde_json::json!({"foo": {"bar": ["0"]}});
+
+        let ptr = PointerBuf::parse("/foo/bar/invalid/cannot/reach").unwrap();
+        let report = ptr.assign(&mut v, "qux").diagnose(ptr).unwrap_err();
+        println!("{:?}", miette::Report::from(report));
+
+        let ptr = PointerBuf::parse("/foo/bar/3/cannot/reach").unwrap();
+        let report = ptr.assign(&mut v, "qux").diagnose(ptr).unwrap_err();
+        println!("{:?}", miette::Report::from(report));
+    }
+
+    #[test]
+    fn parse_error() {
+        let invalid = "/foo/bar/invalid~3~encoding/cannot/reach";
+        let report = Pointer::parse(invalid).diagnose(invalid).unwrap_err();
+
+        println!("{:?}", miette::Report::from(report));
+
+        let report = PointerBuf::parse("/foo/bar/invalid~3~encoding/cannot/reach").unwrap_err();
+
+        let report = miette::Report::from(report);
+        println!("{report:?}");
+    }
+}

From a9cfea1c36bc8214a525cfeeb0793a75f68820fb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9=20S=C3=A1=20de=20Mello?= <codasm@pm.me>
Date: Mon, 18 Nov 2024 02:05:55 +0000
Subject: [PATCH 3/8] deref + fix tests

---
 src/pointer.rs |  2 +-
 src/report.rs  | 13 ++++++++++++-
 src/token.rs   |  2 +-
 3 files changed, 14 insertions(+), 3 deletions(-)

diff --git a/src/pointer.rs b/src/pointer.rs
index 6a7a817..cad602a 100644
--- a/src/pointer.rs
+++ b/src/pointer.rs
@@ -2116,7 +2116,7 @@ mod tests {
         assert!(invalid.is_err());
         assert_eq!(
             invalid.unwrap_err().to_string(),
-            "failed to parse json pointer\n\ncaused by:\njson pointer is malformed as it does not start with a backslash ('/') at line 1 column 9"
+            "failed to parse json pointer\n\ncaused by:\njson pointer is malformed as it does not start with a backslash ('/') and is not empty at line 1 column 9"
         );
     }
 
diff --git a/src/report.rs b/src/report.rs
index f738d83..1f628c8 100644
--- a/src/report.rs
+++ b/src/report.rs
@@ -69,7 +69,7 @@ impl<'s, S: Enrich<'s>> Enriched<'s, S> {
     }
 
     /// The error which occurred.
-    pub fn source(&self) -> &S {
+    pub fn original(&self) -> &S {
         &self.source
     }
 
@@ -79,6 +79,17 @@ impl<'s, S: Enrich<'s>> Enriched<'s, S> {
     }
 }
 
+impl<'s, S> core::ops::Deref for Enriched<'s, S>
+where
+    S: Enrich<'s>,
+{
+    type Target = S;
+
+    fn deref(&self) -> &Self::Target {
+        &self.source
+    }
+}
+
 impl<'s, S> fmt::Display for Enriched<'s, S>
 where
     S: Enrich<'s> + fmt::Display,
diff --git a/src/token.rs b/src/token.rs
index 9f10c58..1187b39 100644
--- a/src/token.rs
+++ b/src/token.rs
@@ -432,7 +432,7 @@ mod tests {
     fn invalid_encoding_error_display() {
         assert_eq!(
             Token::from_encoded("~").unwrap_err().to_string(),
-            "json pointer is malformed due to invalid encoding ('~' not followed by '0' or '1')"
+            "json pointer is malformed due to invalid encoding"
         );
     }
 

From cf3bcfa288dca82dbdc7d830474a7b9442d592e7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9=20S=C3=A1=20de=20Mello?= <codasm@pm.me>
Date: Mon, 18 Nov 2024 02:15:16 +0000
Subject: [PATCH 4/8] revert name + some simplifications

---
 src/assign.rs                    |  4 +-
 src/{report.rs => diagnostic.rs} | 75 +++++++++++++++-----------------
 src/lib.rs                       |  2 +-
 src/pointer.rs                   |  6 +--
 4 files changed, 41 insertions(+), 46 deletions(-)
 rename src/{report.rs => diagnostic.rs} (70%)

diff --git a/src/assign.rs b/src/assign.rs
index 2b30439..cc04375 100644
--- a/src/assign.rs
+++ b/src/assign.rs
@@ -37,8 +37,8 @@
 //!
 
 use crate::{
+    diagnostic::{impl_diagnostic_url, IntoDiagnostic, Label},
     index::{OutOfBoundsError, ParseIndexError},
-    report::{impl_diagnostic_url, Enrich, Label},
     Pointer,
 };
 use alloc::borrow::Cow;
@@ -228,7 +228,7 @@ impl fmt::Display for Error {
     }
 }
 
-impl<'s> Enrich<'s> for Error {
+impl<'s> IntoDiagnostic<'s> for Error {
     type Subject = Cow<'s, Pointer>;
 
     fn url() -> &'static str {
diff --git a/src/report.rs b/src/diagnostic.rs
similarity index 70%
rename from src/report.rs
rename to src/diagnostic.rs
index 1f628c8..1982039 100644
--- a/src/report.rs
+++ b/src/diagnostic.rs
@@ -2,14 +2,14 @@
 
 use core::fmt;
 
-/// Implemented by errors which can be converted into a [`Report`].
-pub trait Enrich<'s>: Sized + private::Sealed {
+/// Implemented by errors which can be converted into a [`Diagnostic`].
+pub trait IntoDiagnostic<'s>: Sized + private::Sealed {
     /// The value which caused the error.
     type Subject;
 
     /// Enrich the error with its subject.
-    fn enrich(self, subject: impl Into<Self::Subject>) -> Enriched<'s, Self> {
-        Enriched::new(self, subject)
+    fn enrich(self, subject: impl Into<Self::Subject>) -> Diagnostic<'s, Self> {
+        Diagnostic::new(self, subject)
     }
 
     /// The docs.rs URL for this error
@@ -44,12 +44,12 @@ impl From<Label> for miette::LabeledSpan {
 /// An error wrapper which includes the [`String`] which failed to parse or the
 /// [`PointerBuf`] being used.
 #[derive(Clone, PartialEq, Eq)]
-pub struct Enriched<'s, S: Enrich<'s>> {
+pub struct Diagnostic<'s, S: IntoDiagnostic<'s>> {
     source: S,
     subject: S::Subject,
 }
 
-impl<'s, S: Enrich<'s>> Enriched<'s, S> {
+impl<'s, S: IntoDiagnostic<'s>> Diagnostic<'s, S> {
     /// Create a new `Report` with the given subject and error.
     fn new(source: S, subject: impl Into<S::Subject>) -> Self {
         Self {
@@ -58,11 +58,6 @@ impl<'s, S: Enrich<'s>> Enriched<'s, S> {
         }
     }
 
-    /// Returns labels associated with spans where the error occurs.
-    pub fn labels(&self) -> Option<Box<dyn Iterator<Item = Label>>> {
-        self.source.labels(&self.subject)
-    }
-
     /// The value which caused the error.
     pub fn subject(&self) -> &S::Subject {
         &self.subject
@@ -73,15 +68,15 @@ impl<'s, S: Enrich<'s>> Enriched<'s, S> {
         &self.source
     }
 
-    /// The docs.rs URL for the error of this [`Report`].
-    pub fn url() -> &'static str {
-        S::url()
+    /// The original parts of the [`Diagnostic`].
+    pub fn decompose(self) -> (S, S::Subject) {
+        (self.source, self.subject)
     }
 }
 
-impl<'s, S> core::ops::Deref for Enriched<'s, S>
+impl<'s, S> core::ops::Deref for Diagnostic<'s, S>
 where
-    S: Enrich<'s>,
+    S: IntoDiagnostic<'s>,
 {
     type Target = S;
 
@@ -90,18 +85,18 @@ where
     }
 }
 
-impl<'s, S> fmt::Display for Enriched<'s, S>
+impl<'s, S> fmt::Display for Diagnostic<'s, S>
 where
-    S: Enrich<'s> + fmt::Display,
+    S: IntoDiagnostic<'s> + fmt::Display,
 {
     fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
         fmt::Display::fmt(&self.source, f)
     }
 }
 
-impl<'s, S> fmt::Debug for Enriched<'s, S>
+impl<'s, S> fmt::Debug for Diagnostic<'s, S>
 where
-    S: Enrich<'s> + fmt::Debug,
+    S: IntoDiagnostic<'s> + fmt::Debug,
     S::Subject: fmt::Debug,
 {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
@@ -113,9 +108,9 @@ where
 }
 
 #[cfg(feature = "std")]
-impl<'s, S> std::error::Error for Enriched<'s, S>
+impl<'s, S> std::error::Error for Diagnostic<'s, S>
 where
-    S: Enrich<'s> + fmt::Debug + std::error::Error + 'static,
+    S: IntoDiagnostic<'s> + fmt::Debug + std::error::Error + 'static,
     S::Subject: fmt::Debug,
 {
     fn source(&self) -> Option<&(dyn core::error::Error + 'static)> {
@@ -124,13 +119,13 @@ where
 }
 
 #[cfg(feature = "miette")]
-impl<'s, S> miette::Diagnostic for Enriched<'s, S>
+impl<'s, S> miette::Diagnostic for Diagnostic<'s, S>
 where
-    S: Enrich<'s> + fmt::Debug + std::error::Error + 'static,
+    S: IntoDiagnostic<'s> + fmt::Debug + std::error::Error + 'static,
     S::Subject: fmt::Debug + miette::SourceCode,
 {
     fn url<'a>(&'a self) -> Option<Box<dyn core::fmt::Display + 'a>> {
-        Some(Box::new(Self::url()))
+        Some(Box::new(S::url()))
     }
 
     fn source_code(&self) -> Option<&dyn miette::SourceCode> {
@@ -138,22 +133,22 @@ where
     }
 
     fn labels(&self) -> Option<Box<dyn Iterator<Item = miette::LabeledSpan> + '_>> {
-        Some(Box::new(self.labels()?.map(Into::into)))
+        Some(Box::new(S::labels(self, &self.subject)?.map(Into::into)))
     }
 }
 
 macro_rules! impl_diagnostic_url {
     (enum $type:ident) => {
-        $crate::report::impl_diagnostic_url!("enum", "", $type)
+        $crate::diagnostic::impl_diagnostic_url!("enum", "", $type)
     };
     (struct $type:ident) => {
-        $crate::report::impl_diagnostic_url!("struct", "", $type)
+        $crate::diagnostic::impl_diagnostic_url!("struct", "", $type)
     };
     (enum $mod:ident::$type:ident) => {
-        $crate::report::impl_diagnostic_url!("enum", concat!("/", stringify!($mod)), $type)
+        $crate::diagnostic::impl_diagnostic_url!("enum", concat!("/", stringify!($mod)), $type)
     };
     (struct $mod:ident::$type:ident) => {
-        $crate::report::impl_diagnostic_url!("struct", concat!("/", stringify!($mod)), $type)
+        $crate::diagnostic::impl_diagnostic_url!("struct", concat!("/", stringify!($mod)), $type)
     };
     ($kind:literal, $mod:expr, $type:ident) => {
         concat!(
@@ -178,38 +173,38 @@ mod private {
 }
 
 pub trait Diagnose<'s, T> {
-    type Error: Enrich<'s>;
+    type Error: IntoDiagnostic<'s>;
 
     #[allow(clippy::missing_errors_doc)]
     fn diagnose(
         self,
-        subject: impl Into<<Self::Error as Enrich<'s>>::Subject>,
-    ) -> Result<T, Enriched<'s, Self::Error>>;
+        subject: impl Into<<Self::Error as IntoDiagnostic<'s>>::Subject>,
+    ) -> Result<T, Diagnostic<'s, Self::Error>>;
 
     #[allow(clippy::missing_errors_doc)]
-    fn diagnose_with<F, S>(self, f: F) -> Result<T, Enriched<'s, Self::Error>>
+    fn diagnose_with<F, S>(self, f: F) -> Result<T, Diagnostic<'s, Self::Error>>
     where
         F: FnOnce() -> S,
-        S: Into<<Self::Error as Enrich<'s>>::Subject>;
+        S: Into<<Self::Error as IntoDiagnostic<'s>>::Subject>;
 }
 
 impl<'s, T, E> Diagnose<'s, T> for Result<T, E>
 where
-    E: Enrich<'s>,
+    E: IntoDiagnostic<'s>,
 {
     type Error = E;
 
     fn diagnose(
         self,
-        subject: impl Into<<Self::Error as Enrich<'s>>::Subject>,
-    ) -> Result<T, Enriched<'s, Self::Error>> {
+        subject: impl Into<<Self::Error as IntoDiagnostic<'s>>::Subject>,
+    ) -> Result<T, Diagnostic<'s, Self::Error>> {
         self.map_err(|error| error.enrich(subject.into()))
     }
 
-    fn diagnose_with<F, S>(self, f: F) -> Result<T, Enriched<'s, Self::Error>>
+    fn diagnose_with<F, S>(self, f: F) -> Result<T, Diagnostic<'s, Self::Error>>
     where
         F: FnOnce() -> S,
-        S: Into<<Self::Error as Enrich<'s>>::Subject>,
+        S: Into<<Self::Error as IntoDiagnostic<'s>>::Subject>,
     {
         self.diagnose(f())
     }
diff --git a/src/lib.rs b/src/lib.rs
index ca05f39..01df35d 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -64,7 +64,7 @@ pub mod resolve;
 #[cfg(feature = "resolve")]
 pub use resolve::{Resolve, ResolveMut};
 
-pub mod report;
+pub mod diagnostic;
 
 mod pointer;
 pub use pointer::{ParseError, Pointer, PointerBuf};
diff --git a/src/pointer.rs b/src/pointer.rs
index cad602a..c5810e7 100644
--- a/src/pointer.rs
+++ b/src/pointer.rs
@@ -1,5 +1,5 @@
 use crate::{
-    report::{impl_diagnostic_url, Enrich, Enriched, Label},
+    diagnostic::{impl_diagnostic_url, Diagnostic, IntoDiagnostic, Label},
     token::InvalidEncodingError,
     Components, Token, Tokens,
 };
@@ -942,7 +942,7 @@ impl PointerBuf {
     ///
     /// ## Errors
     /// Returns a [`RichParseError`] if the string is not a valid JSON Pointer.
-    pub fn parse<'s>(s: impl Into<Cow<'s, str>>) -> Result<Self, Enriched<'s, ParseError>> {
+    pub fn parse<'s>(s: impl Into<Cow<'s, str>>) -> Result<Self, Diagnostic<'s, ParseError>> {
         let s = s.into();
         match validate(&s) {
             Ok(_) => Ok(Self(s.into_owned())),
@@ -1277,7 +1277,7 @@ impl ParseError {
     }
 }
 
-impl<'s> Enrich<'s> for ParseError {
+impl<'s> IntoDiagnostic<'s> for ParseError {
     type Subject = Cow<'s, str>;
 
     fn url() -> &'static str {

From 3c9ff88f4ba19761a9d98ce3165ea021430a00fc Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9=20S=C3=A1=20de=20Mello?= <codasm@pm.me>
Date: Mon, 18 Nov 2024 14:44:22 +0000
Subject: [PATCH 5/8] rename diagnostic --> report, add into_owned

---
 src/assign.rs     |   4 +-
 src/diagnostic.rs | 129 ++++++++++++++++++++++++++++++++++------------
 src/pointer.rs    |  10 ++--
 3 files changed, 104 insertions(+), 39 deletions(-)

diff --git a/src/assign.rs b/src/assign.rs
index cc04375..187f209 100644
--- a/src/assign.rs
+++ b/src/assign.rs
@@ -37,7 +37,7 @@
 //!
 
 use crate::{
-    diagnostic::{impl_diagnostic_url, IntoDiagnostic, Label},
+    diagnostic::{impl_diagnostic_url, Diagnostic, Label},
     index::{OutOfBoundsError, ParseIndexError},
     Pointer,
 };
@@ -228,7 +228,7 @@ impl fmt::Display for Error {
     }
 }
 
-impl<'s> IntoDiagnostic<'s> for Error {
+impl<'s> Diagnostic<'s> for Error {
     type Subject = Cow<'s, Pointer>;
 
     fn url() -> &'static str {
diff --git a/src/diagnostic.rs b/src/diagnostic.rs
index 1982039..f49a6f8 100644
--- a/src/diagnostic.rs
+++ b/src/diagnostic.rs
@@ -2,14 +2,14 @@
 
 use core::fmt;
 
-/// Implemented by errors which can be converted into a [`Diagnostic`].
-pub trait IntoDiagnostic<'s>: Sized + private::Sealed {
+/// Implemented by errors which can be converted into a [`Report`].
+pub trait Diagnostic<'s>: Sized + private::Sealed {
     /// The value which caused the error.
-    type Subject;
+    type Subject: private::IntoOwned;
 
-    /// Enrich the error with its subject.
-    fn enrich(self, subject: impl Into<Self::Subject>) -> Diagnostic<'s, Self> {
-        Diagnostic::new(self, subject)
+    /// Combine the error with its subject to generate a [`Report`].
+    fn into_report(self, subject: impl Into<Self::Subject>) -> Report<'s, Self> {
+        Report::new(self, subject)
     }
 
     /// The docs.rs URL for this error
@@ -41,15 +41,14 @@ impl From<Label> for miette::LabeledSpan {
     }
 }
 
-/// An error wrapper which includes the [`String`] which failed to parse or the
-/// [`PointerBuf`] being used.
+/// An error wrapper which includes the subject of the failure.
 #[derive(Clone, PartialEq, Eq)]
-pub struct Diagnostic<'s, S: IntoDiagnostic<'s>> {
+pub struct Report<'s, S: Diagnostic<'s>> {
     source: S,
     subject: S::Subject,
 }
 
-impl<'s, S: IntoDiagnostic<'s>> Diagnostic<'s, S> {
+impl<'s, S: Diagnostic<'s>> Report<'s, S> {
     /// Create a new `Report` with the given subject and error.
     fn new(source: S, subject: impl Into<S::Subject>) -> Self {
         Self {
@@ -68,15 +67,36 @@ impl<'s, S: IntoDiagnostic<'s>> Diagnostic<'s, S> {
         &self.source
     }
 
-    /// The original parts of the [`Diagnostic`].
+    /// The original parts of the [`Report`].
     pub fn decompose(self) -> (S, S::Subject) {
         (self.source, self.subject)
     }
 }
 
-impl<'s, S> core::ops::Deref for Diagnostic<'s, S>
+impl<'s, S> Report<'s, S>
 where
-    S: IntoDiagnostic<'s>,
+    S: Diagnostic<'s>,
+{
+    /// Converts the Report into an owned instance (generally by cloning the subject).
+    pub fn into_owned<O>(self) -> Report<'static, O>
+    where
+        S: Into<O>,
+        O: Diagnostic<'static, Subject = <S::Subject as private::IntoOwned>::Owned>,
+    {
+        use private::IntoOwned;
+
+        Report {
+            // TODO: is there a way to avoid the `Into` here? We really want `S == O`,
+            // but I'm strugggling to express that without a bound predicate cycle
+            source: self.source.into(),
+            subject: self.subject.into_owned(),
+        }
+    }
+}
+
+impl<'s, S> core::ops::Deref for Report<'s, S>
+where
+    S: Diagnostic<'s>,
 {
     type Target = S;
 
@@ -85,18 +105,18 @@ where
     }
 }
 
-impl<'s, S> fmt::Display for Diagnostic<'s, S>
+impl<'s, S> fmt::Display for Report<'s, S>
 where
-    S: IntoDiagnostic<'s> + fmt::Display,
+    S: Diagnostic<'s> + fmt::Display,
 {
     fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
         fmt::Display::fmt(&self.source, f)
     }
 }
 
-impl<'s, S> fmt::Debug for Diagnostic<'s, S>
+impl<'s, S> fmt::Debug for Report<'s, S>
 where
-    S: IntoDiagnostic<'s> + fmt::Debug,
+    S: Diagnostic<'s> + fmt::Debug,
     S::Subject: fmt::Debug,
 {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
@@ -108,9 +128,9 @@ where
 }
 
 #[cfg(feature = "std")]
-impl<'s, S> std::error::Error for Diagnostic<'s, S>
+impl<'s, S> std::error::Error for Report<'s, S>
 where
-    S: IntoDiagnostic<'s> + fmt::Debug + std::error::Error + 'static,
+    S: Diagnostic<'s> + fmt::Debug + std::error::Error + 'static,
     S::Subject: fmt::Debug,
 {
     fn source(&self) -> Option<&(dyn core::error::Error + 'static)> {
@@ -119,9 +139,9 @@ where
 }
 
 #[cfg(feature = "miette")]
-impl<'s, S> miette::Diagnostic for Diagnostic<'s, S>
+impl<'s, S> miette::Diagnostic for Report<'s, S>
 where
-    S: IntoDiagnostic<'s> + fmt::Debug + std::error::Error + 'static,
+    S: Diagnostic<'s> + fmt::Debug + std::error::Error + 'static,
     S::Subject: fmt::Debug + miette::SourceCode,
 {
     fn url<'a>(&'a self) -> Option<Box<dyn core::fmt::Display + 'a>> {
@@ -167,44 +187,69 @@ macro_rules! impl_diagnostic_url {
 pub(crate) use impl_diagnostic_url;
 
 mod private {
+    use crate::Pointer;
+    use alloc::borrow::Cow;
+
     pub trait Sealed {}
     impl Sealed for crate::pointer::ParseError {}
     impl Sealed for crate::assign::Error {}
+
+    pub trait IntoOwned {
+        type Owned: 'static;
+
+        fn into_owned(self) -> Self::Owned;
+    }
+
+    impl<'s> IntoOwned for Cow<'s, str> {
+        type Owned = Cow<'static, str>;
+
+        fn into_owned(self) -> Cow<'static, str> {
+            Cow::Owned(self.into_owned())
+        }
+    }
+
+    impl<'s> IntoOwned for Cow<'s, Pointer> {
+        type Owned = Cow<'static, Pointer>;
+
+        fn into_owned(self) -> Cow<'static, Pointer> {
+            Cow::Owned(self.into_owned())
+        }
+    }
 }
 
 pub trait Diagnose<'s, T> {
-    type Error: IntoDiagnostic<'s>;
+    type Error: Diagnostic<'s>;
 
     #[allow(clippy::missing_errors_doc)]
     fn diagnose(
         self,
-        subject: impl Into<<Self::Error as IntoDiagnostic<'s>>::Subject>,
-    ) -> Result<T, Diagnostic<'s, Self::Error>>;
+        subject: impl Into<<Self::Error as Diagnostic<'s>>::Subject>,
+    ) -> Result<T, Report<'s, Self::Error>>;
 
     #[allow(clippy::missing_errors_doc)]
-    fn diagnose_with<F, S>(self, f: F) -> Result<T, Diagnostic<'s, Self::Error>>
+    fn diagnose_with<F, S>(self, f: F) -> Result<T, Report<'s, Self::Error>>
     where
         F: FnOnce() -> S,
-        S: Into<<Self::Error as IntoDiagnostic<'s>>::Subject>;
+        S: Into<<Self::Error as Diagnostic<'s>>::Subject>;
 }
 
 impl<'s, T, E> Diagnose<'s, T> for Result<T, E>
 where
-    E: IntoDiagnostic<'s>,
+    E: Diagnostic<'s>,
 {
     type Error = E;
 
     fn diagnose(
         self,
-        subject: impl Into<<Self::Error as IntoDiagnostic<'s>>::Subject>,
-    ) -> Result<T, Diagnostic<'s, Self::Error>> {
-        self.map_err(|error| error.enrich(subject.into()))
+        subject: impl Into<<Self::Error as Diagnostic<'s>>::Subject>,
+    ) -> Result<T, Report<'s, Self::Error>> {
+        self.map_err(|error| error.into_report(subject.into()))
     }
 
-    fn diagnose_with<F, S>(self, f: F) -> Result<T, Diagnostic<'s, Self::Error>>
+    fn diagnose_with<F, S>(self, f: F) -> Result<T, Report<'s, Self::Error>>
     where
         F: FnOnce() -> S,
-        S: Into<<Self::Error as IntoDiagnostic<'s>>::Subject>,
+        S: Into<<Self::Error as Diagnostic<'s>>::Subject>,
     {
         self.diagnose(f())
     }
@@ -213,7 +258,7 @@ where
 #[cfg(test)]
 mod tests {
     use super::*;
-    use crate::{Pointer, PointerBuf};
+    use crate::{ParseError, Pointer, PointerBuf};
 
     #[test]
     #[cfg(all(
@@ -246,4 +291,22 @@ mod tests {
         let report = miette::Report::from(report);
         println!("{report:?}");
     }
+
+    #[test]
+    fn into_owned() {
+        // NOTE: the type has to be fully specified here because of the `S: Into<O>` bound
+        // in `Report::into_owned`. Ideally we'd express `S == O` so that the output can
+        // be automatically inferred.
+        let owned_report: Report<'static, ParseError> = {
+            // creating owned string to ensure its lifetime is local
+            // (could also coerce a static reference, but this is less brittle)
+            let invalid = "/foo/bar/invalid~3~encoding/cannot/reach".to_string();
+            let report = Pointer::parse(&invalid)
+                .diagnose(invalid.as_str())
+                .unwrap_err();
+            report.into_owned()
+        };
+
+        println!("{owned_report}");
+    }
 }
diff --git a/src/pointer.rs b/src/pointer.rs
index c5810e7..90a882e 100644
--- a/src/pointer.rs
+++ b/src/pointer.rs
@@ -1,5 +1,5 @@
 use crate::{
-    diagnostic::{impl_diagnostic_url, Diagnostic, IntoDiagnostic, Label},
+    diagnostic::{impl_diagnostic_url, Diagnostic, Label, Report},
     token::InvalidEncodingError,
     Components, Token, Tokens,
 };
@@ -942,11 +942,11 @@ impl PointerBuf {
     ///
     /// ## Errors
     /// Returns a [`RichParseError`] if the string is not a valid JSON Pointer.
-    pub fn parse<'s>(s: impl Into<Cow<'s, str>>) -> Result<Self, Diagnostic<'s, ParseError>> {
+    pub fn parse<'s>(s: impl Into<Cow<'s, str>>) -> Result<Self, RichParseError<'s>> {
         let s = s.into();
         match validate(&s) {
             Ok(_) => Ok(Self(s.into_owned())),
-            Err(err) => Err(err.enrich(s)),
+            Err(err) => Err(err.into_report(s)),
         }
     }
 
@@ -1277,7 +1277,7 @@ impl ParseError {
     }
 }
 
-impl<'s> IntoDiagnostic<'s> for ParseError {
+impl<'s> Diagnostic<'s> for ParseError {
     type Subject = Cow<'s, str>;
 
     fn url() -> &'static str {
@@ -1387,6 +1387,8 @@ impl std::error::Error for ParseError {
     }
 }
 
+pub type RichParseError<'s> = Report<'s, ParseError>;
+
 /*
 ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
 ╔══════════════════════════════════════════════════════════════════════════════╗

From a728f72f62d35ec03c623fcb5244dff30b0fed84 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9=20S=C3=A1=20de=20Mello?= <codasm@pm.me>
Date: Mon, 18 Nov 2024 15:37:18 +0000
Subject: [PATCH 6/8] better generics

---
 src/diagnostic.rs | 110 +++++++++++++++++-----------------------------
 src/pointer.rs    |   2 +-
 2 files changed, 42 insertions(+), 70 deletions(-)

diff --git a/src/diagnostic.rs b/src/diagnostic.rs
index f49a6f8..445a8f4 100644
--- a/src/diagnostic.rs
+++ b/src/diagnostic.rs
@@ -8,7 +8,7 @@ pub trait Diagnostic<'s>: Sized + private::Sealed {
     type Subject: private::IntoOwned;
 
     /// Combine the error with its subject to generate a [`Report`].
-    fn into_report(self, subject: impl Into<Self::Subject>) -> Report<'s, Self> {
+    fn into_report(self, subject: impl Into<Self::Subject>) -> Report<Self, Self::Subject> {
         Report::new(self, subject)
     }
 
@@ -42,15 +42,15 @@ impl From<Label> for miette::LabeledSpan {
 }
 
 /// An error wrapper which includes the subject of the failure.
-#[derive(Clone, PartialEq, Eq)]
-pub struct Report<'s, S: Diagnostic<'s>> {
-    source: S,
-    subject: S::Subject,
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Report<SRC, SUB> {
+    source: SRC,
+    subject: SUB,
 }
 
-impl<'s, S: Diagnostic<'s>> Report<'s, S> {
+impl<SRC, SUB> Report<SRC, SUB> {
     /// Create a new `Report` with the given subject and error.
-    fn new(source: S, subject: impl Into<S::Subject>) -> Self {
+    fn new(source: SRC, subject: impl Into<SUB>) -> Self {
         Self {
             source,
             subject: subject.into(),
@@ -58,80 +58,58 @@ impl<'s, S: Diagnostic<'s>> Report<'s, S> {
     }
 
     /// The value which caused the error.
-    pub fn subject(&self) -> &S::Subject {
+    pub fn subject(&self) -> &SUB {
         &self.subject
     }
 
     /// The error which occurred.
-    pub fn original(&self) -> &S {
+    pub fn original(&self) -> &SRC {
         &self.source
     }
 
     /// The original parts of the [`Report`].
-    pub fn decompose(self) -> (S, S::Subject) {
+    pub fn decompose(self) -> (SRC, SUB) {
         (self.source, self.subject)
     }
 }
 
-impl<'s, S> Report<'s, S>
+impl<'s, S> Report<S, <S as Diagnostic<'s>>::Subject>
 where
     S: Diagnostic<'s>,
 {
     /// Converts the Report into an owned instance (generally by cloning the subject).
-    pub fn into_owned<O>(self) -> Report<'static, O>
-    where
-        S: Into<O>,
-        O: Diagnostic<'static, Subject = <S::Subject as private::IntoOwned>::Owned>,
-    {
+    pub fn into_owned(self) -> Report<S, <S::Subject as private::IntoOwned>::Owned> {
         use private::IntoOwned;
 
         Report {
-            // TODO: is there a way to avoid the `Into` here? We really want `S == O`,
-            // but I'm strugggling to express that without a bound predicate cycle
-            source: self.source.into(),
+            source: self.source,
             subject: self.subject.into_owned(),
         }
     }
 }
 
-impl<'s, S> core::ops::Deref for Report<'s, S>
-where
-    S: Diagnostic<'s>,
-{
-    type Target = S;
+impl<SRC, SUB> core::ops::Deref for Report<SRC, SUB> {
+    type Target = SRC;
 
     fn deref(&self) -> &Self::Target {
         &self.source
     }
 }
 
-impl<'s, S> fmt::Display for Report<'s, S>
+impl<SRC, SUB> fmt::Display for Report<SRC, SUB>
 where
-    S: Diagnostic<'s> + fmt::Display,
+    SRC: fmt::Display,
 {
     fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
         fmt::Display::fmt(&self.source, f)
     }
 }
 
-impl<'s, S> fmt::Debug for Report<'s, S>
-where
-    S: Diagnostic<'s> + fmt::Debug,
-    S::Subject: fmt::Debug,
-{
-    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        f.debug_struct("Enriched")
-            .field("source", &self.source)
-            .field("subject", &self.subject)
-            .finish()
-    }
-}
-
 #[cfg(feature = "std")]
-impl<'s, S> std::error::Error for Report<'s, S>
+impl<SRC, SUB> std::error::Error for Report<SRC, SUB>
 where
-    S: Diagnostic<'s> + fmt::Debug + std::error::Error + 'static,
-    S::Subject: fmt::Debug,
+    SRC: fmt::Debug + std::error::Error + 'static,
+    SUB: fmt::Debug,
 {
     fn source(&self) -> Option<&(dyn core::error::Error + 'static)> {
         Some(&self.source)
@@ -139,13 +117,13 @@ where
 }
 
 #[cfg(feature = "miette")]
-impl<'s, S> miette::Diagnostic for Report<'s, S>
+impl<'s, SRC> miette::Diagnostic for Report<SRC, SRC::Subject>
 where
-    S: Diagnostic<'s> + fmt::Debug + std::error::Error + 'static,
-    S::Subject: fmt::Debug + miette::SourceCode,
+    SRC: Diagnostic<'s> + fmt::Debug + std::error::Error + 'static,
+    SRC::Subject: fmt::Debug + miette::SourceCode,
 {
     fn url<'a>(&'a self) -> Option<Box<dyn core::fmt::Display + 'a>> {
-        Some(Box::new(S::url()))
+        Some(Box::new(SRC::url()))
     }
 
     fn source_code(&self) -> Option<&dyn miette::SourceCode> {
@@ -153,7 +131,7 @@ where
     }
 
     fn labels(&self) -> Option<Box<dyn Iterator<Item = miette::LabeledSpan> + '_>> {
-        Some(Box::new(S::labels(self, &self.subject)?.map(Into::into)))
+        Some(Box::new(SRC::labels(self, &self.subject)?.map(Into::into)))
     }
 }
 
@@ -187,7 +165,6 @@ macro_rules! impl_diagnostic_url {
 pub(crate) use impl_diagnostic_url;
 
 mod private {
-    use crate::Pointer;
     use alloc::borrow::Cow;
 
     pub trait Sealed {}
@@ -195,23 +172,15 @@ mod private {
     impl Sealed for crate::assign::Error {}
 
     pub trait IntoOwned {
-        type Owned: 'static;
+        type Owned;
 
         fn into_owned(self) -> Self::Owned;
     }
 
-    impl<'s> IntoOwned for Cow<'s, str> {
-        type Owned = Cow<'static, str>;
-
-        fn into_owned(self) -> Cow<'static, str> {
-            Cow::Owned(self.into_owned())
-        }
-    }
-
-    impl<'s> IntoOwned for Cow<'s, Pointer> {
-        type Owned = Cow<'static, Pointer>;
+    impl<'s, T: 'static + ToOwned + ?Sized> IntoOwned for Cow<'s, T> {
+        type Owned = Cow<'static, T>;
 
-        fn into_owned(self) -> Cow<'static, Pointer> {
+        fn into_owned(self) -> Cow<'static, T> {
             Cow::Owned(self.into_owned())
         }
     }
@@ -224,10 +193,13 @@ pub trait Diagnose<'s, T> {
     fn diagnose(
         self,
         subject: impl Into<<Self::Error as Diagnostic<'s>>::Subject>,
-    ) -> Result<T, Report<'s, Self::Error>>;
+    ) -> Result<T, Report<Self::Error, <Self::Error as Diagnostic<'s>>::Subject>>;
 
     #[allow(clippy::missing_errors_doc)]
-    fn diagnose_with<F, S>(self, f: F) -> Result<T, Report<'s, Self::Error>>
+    fn diagnose_with<F, S>(
+        self,
+        f: F,
+    ) -> Result<T, Report<Self::Error, <Self::Error as Diagnostic<'s>>::Subject>>
     where
         F: FnOnce() -> S,
         S: Into<<Self::Error as Diagnostic<'s>>::Subject>;
@@ -242,11 +214,14 @@ where
     fn diagnose(
         self,
         subject: impl Into<<Self::Error as Diagnostic<'s>>::Subject>,
-    ) -> Result<T, Report<'s, Self::Error>> {
+    ) -> Result<T, Report<Self::Error, <Self::Error as Diagnostic<'s>>::Subject>> {
         self.map_err(|error| error.into_report(subject.into()))
     }
 
-    fn diagnose_with<F, S>(self, f: F) -> Result<T, Report<'s, Self::Error>>
+    fn diagnose_with<F, S>(
+        self,
+        f: F,
+    ) -> Result<T, Report<Self::Error, <Self::Error as Diagnostic<'s>>::Subject>>
     where
         F: FnOnce() -> S,
         S: Into<<Self::Error as Diagnostic<'s>>::Subject>,
@@ -258,7 +233,7 @@ where
 #[cfg(test)]
 mod tests {
     use super::*;
-    use crate::{ParseError, Pointer, PointerBuf};
+    use crate::{Pointer, PointerBuf};
 
     #[test]
     #[cfg(all(
@@ -294,10 +269,7 @@ mod tests {
 
     #[test]
     fn into_owned() {
-        // NOTE: the type has to be fully specified here because of the `S: Into<O>` bound
-        // in `Report::into_owned`. Ideally we'd express `S == O` so that the output can
-        // be automatically inferred.
-        let owned_report: Report<'static, ParseError> = {
+        let owned_report = {
             // creating owned string to ensure its lifetime is local
             // (could also coerce a static reference, but this is less brittle)
             let invalid = "/foo/bar/invalid~3~encoding/cannot/reach".to_string();
diff --git a/src/pointer.rs b/src/pointer.rs
index 90a882e..8861913 100644
--- a/src/pointer.rs
+++ b/src/pointer.rs
@@ -1387,7 +1387,7 @@ impl std::error::Error for ParseError {
     }
 }
 
-pub type RichParseError<'s> = Report<'s, ParseError>;
+pub type RichParseError<'s> = Report<ParseError, <ParseError as Diagnostic<'s>>::Subject>;
 
 /*
 ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░

From 1404c619ff89d8592144c35b6f01f4583b31ae6b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9=20S=C3=A1=20de=20Mello?= <codasm@pm.me>
Date: Mon, 18 Nov 2024 15:46:39 +0000
Subject: [PATCH 7/8] remove Report::new

---
 src/diagnostic.rs | 13 ++++---------
 1 file changed, 4 insertions(+), 9 deletions(-)

diff --git a/src/diagnostic.rs b/src/diagnostic.rs
index 445a8f4..354232d 100644
--- a/src/diagnostic.rs
+++ b/src/diagnostic.rs
@@ -9,7 +9,10 @@ pub trait Diagnostic<'s>: Sized + private::Sealed {
 
     /// Combine the error with its subject to generate a [`Report`].
     fn into_report(self, subject: impl Into<Self::Subject>) -> Report<Self, Self::Subject> {
-        Report::new(self, subject)
+        Report {
+            source: self,
+            subject: subject.into(),
+        }
     }
 
     /// The docs.rs URL for this error
@@ -49,14 +52,6 @@ pub struct Report<SRC, SUB> {
 }
 
 impl<SRC, SUB> Report<SRC, SUB> {
-    /// Create a new `Report` with the given subject and error.
-    fn new(source: SRC, subject: impl Into<SUB>) -> Self {
-        Self {
-            source,
-            subject: subject.into(),
-        }
-    }
-
     /// The value which caused the error.
     pub fn subject(&self) -> &SUB {
         &self.subject

From 83cf219b1f3f46d9ecec809f83b002940e3e98f2 Mon Sep 17 00:00:00 2001
From: Chance <chanceusc@gmail.com>
Date: Thu, 30 Jan 2025 11:46:08 -0500
Subject: [PATCH 8/8] refactor a bit (#100)

* renames SRC generic of Report to D and bound it to Diagnostic

* drops SUB in generic, uses D::Subject instead

* removes lifetime from Report

* removes seal for Diagnostic
---
 CHANGELOG.md      |  16 ++-
 Cargo.lock        | 104 ++++--------------
 Cargo.toml        |   2 +-
 src/assign.rs     | 148 ++++++++-----------------
 src/diagnostic.rs | 205 ++++++++++++++++-------------------
 src/index.rs      |  59 ++--------
 src/lib.rs        |   8 +-
 src/pointer.rs    | 269 ++++++++++++++++++++++------------------------
 src/resolve.rs    | 110 +++++++------------
 src/token.rs      |  89 ++++++++++++---
 10 files changed, 432 insertions(+), 578 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index a4a919d..90482aa 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -15,7 +15,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 -   Adds `Pointer::starts_with` and `Pointer::ends_with` for prefix and suffix matching.
 -   Adds new `ParseIndexError` variant to express the presence non-digit characters in the token.
 -   Adds `Token::is_next` for checking if a token represents the `-` character.
--   Adds `ParseBufError`, returned as the `Err` variant of `PointerBuf::parse`, which includes the input `String` (from `Into::into`).
+-   Adds `InvalidEncoding` to represent the two possible encoding errors when decoding a token.
+-   Adds `diagnostic` mod, including:
+-   Adds `diagnotic::Diagnostic` trait to facilitate error reporting and
+    `miette` integration. All errors intended for usage with `assign::Assign` or
+    `resolve::Resolve` must implement this trait.
+-   Adds `"miette"` featureflag to enable `miette` integration for error reporting.
 
 ### Changed
 
@@ -24,11 +29,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 -   `Pointer::get` now accepts ranges and can produce `Pointer` segments as output (similar to
     `slice::get`).
 -   `PointerBuf::parse` now returns `BufParseError` instead of `ParseError`.
+-   Adds field `position` to variants of `resolve::Error` and `assign::Error` to indicate the
+    token index of where the error occurred.
+-   Renames `ParseError::NoLeadingBackslash` to `ParseError::NoLeadingSlash`.
 
 ### Fixed
 
 -   Make validation of array indices conform to RFC 6901 in the presence of non-digit characters.
 
+### Deprecated
+
+-   `assign::AssignError` renamed to `assign::Error`
+-   `resolve::ResolveError` renamed to `resolve::Error`
+-   `InvalidEncodingError` renamed to `EncodingError`
+
 ## [0.6.2] 2024-09-30
 
 ### Added
diff --git a/Cargo.lock b/Cargo.lock
index 614e52f..f22b580 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -38,7 +38,7 @@ dependencies = [
  "miniz_oxide",
  "object",
  "rustc-demangle",
- "windows-targets 0.52.6",
+ "windows-targets",
 ]
 
 [[package]]
@@ -172,9 +172,9 @@ checksum = "78ca9ab1a0babb1e7d5695e3530886289c18cf2f87ec19a575a0abdce112e3a3"
 
 [[package]]
 name = "miette"
-version = "7.2.0"
+version = "7.4.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4edc8853320c2a0dab800fbda86253c8938f6ea88510dc92c5f1ed20e794afc1"
+checksum = "317f146e2eb7021892722af37cf1b971f0a70c8406f487e24952667616192c64"
 dependencies = [
  "backtrace",
  "backtrace-ext",
@@ -192,9 +192,9 @@ dependencies = [
 
 [[package]]
 name = "miette-derive"
-version = "7.2.0"
+version = "7.4.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "dcf09caffaac8068c346b6df2a7fc27a177fd20b39421a39ce0a211bde679a6c"
+checksum = "23c9b935fbe1d6cbd1dac857b54a688145e2d93f48db36010514d0f612d0ad67"
 dependencies = [
  "proc-macro2",
  "quote",
@@ -378,12 +378,6 @@ dependencies = [
  "serde",
 ]
 
-[[package]]
-name = "smawk"
-version = "0.3.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b7c388c1b5e93756d0c740965c41e8822f866621d41acbdf6336a6a168f8840c"
-
 [[package]]
 name = "supports-color"
 version = "3.0.1"
@@ -429,12 +423,12 @@ dependencies = [
 
 [[package]]
 name = "terminal_size"
-version = "0.3.0"
+version = "0.4.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "21bebf2b7c9e0a515f6e0f8c51dc0f8e4696391e6f1ff30379559f8365fb0df7"
+checksum = "5352447f921fda68cf61b4101566c0bdb5104eff6804d0678e5227580ab6a4e9"
 dependencies = [
  "rustix",
- "windows-sys 0.48.0",
+ "windows-sys 0.59.0",
 ]
 
 [[package]]
@@ -443,7 +437,6 @@ version = "0.16.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "23d434d3f8967a09480fb04132ebe0a3e088c173e6d0ee7897abbdf4eab0f8b9"
 dependencies = [
- "smawk",
  "unicode-linebreak",
  "unicode-width",
 ]
@@ -526,37 +519,22 @@ version = "0.11.0+wasi-snapshot-preview1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9c8d87e72b64a3b4db28d11ce29237c246188f4f51057d65a7eab63b7987e423"
 
-[[package]]
-name = "windows-sys"
-version = "0.48.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "677d2418bec65e3338edb076e806bc1ec15693c5d0104683f2efe857f61056a9"
-dependencies = [
- "windows-targets 0.48.5",
-]
-
 [[package]]
 name = "windows-sys"
 version = "0.52.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "282be5f36a8ce781fad8c8ae18fa3f9beff57ec1b52cb3de0789201425d9a33d"
 dependencies = [
- "windows-targets 0.52.6",
+ "windows-targets",
 ]
 
 [[package]]
-name = "windows-targets"
-version = "0.48.5"
+name = "windows-sys"
+version = "0.59.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9a2fa6e2155d7247be68c096456083145c183cbbbc2764150dda45a87197940c"
+checksum = "1e38bc4d79ed67fd075bcc251a1c39b32a1776bbe92e5bef1f0bf1f8c531853b"
 dependencies = [
- "windows_aarch64_gnullvm 0.48.5",
- "windows_aarch64_msvc 0.48.5",
- "windows_i686_gnu 0.48.5",
- "windows_i686_msvc 0.48.5",
- "windows_x86_64_gnu 0.48.5",
- "windows_x86_64_gnullvm 0.48.5",
- "windows_x86_64_msvc 0.48.5",
+ "windows-targets",
 ]
 
 [[package]]
@@ -565,46 +543,28 @@ version = "0.52.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9b724f72796e036ab90c1021d4780d4d3d648aca59e491e6b98e725b84e99973"
 dependencies = [
- "windows_aarch64_gnullvm 0.52.6",
- "windows_aarch64_msvc 0.52.6",
- "windows_i686_gnu 0.52.6",
+ "windows_aarch64_gnullvm",
+ "windows_aarch64_msvc",
+ "windows_i686_gnu",
  "windows_i686_gnullvm",
- "windows_i686_msvc 0.52.6",
- "windows_x86_64_gnu 0.52.6",
- "windows_x86_64_gnullvm 0.52.6",
- "windows_x86_64_msvc 0.52.6",
+ "windows_i686_msvc",
+ "windows_x86_64_gnu",
+ "windows_x86_64_gnullvm",
+ "windows_x86_64_msvc",
 ]
 
-[[package]]
-name = "windows_aarch64_gnullvm"
-version = "0.48.5"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2b38e32f0abccf9987a4e3079dfb67dcd799fb61361e53e2882c3cbaf0d905d8"
-
 [[package]]
 name = "windows_aarch64_gnullvm"
 version = "0.52.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "32a4622180e7a0ec044bb555404c800bc9fd9ec262ec147edd5989ccd0c02cd3"
 
-[[package]]
-name = "windows_aarch64_msvc"
-version = "0.48.5"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "dc35310971f3b2dbbf3f0690a219f40e2d9afcf64f9ab7cc1be722937c26b4bc"
-
 [[package]]
 name = "windows_aarch64_msvc"
 version = "0.52.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "09ec2a7bb152e2252b53fa7803150007879548bc709c039df7627cabbd05d469"
 
-[[package]]
-name = "windows_i686_gnu"
-version = "0.48.5"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a75915e7def60c94dcef72200b9a8e58e5091744960da64ec734a6c6e9b3743e"
-
 [[package]]
 name = "windows_i686_gnu"
 version = "0.52.6"
@@ -617,48 +577,24 @@ version = "0.52.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0eee52d38c090b3caa76c563b86c3a4bd71ef1a819287c19d586d7334ae8ed66"
 
-[[package]]
-name = "windows_i686_msvc"
-version = "0.48.5"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8f55c233f70c4b27f66c523580f78f1004e8b5a8b659e05a4eb49d4166cca406"
-
 [[package]]
 name = "windows_i686_msvc"
 version = "0.52.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "240948bc05c5e7c6dabba28bf89d89ffce3e303022809e73deaefe4f6ec56c66"
 
-[[package]]
-name = "windows_x86_64_gnu"
-version = "0.48.5"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "53d40abd2583d23e4718fddf1ebec84dbff8381c07cae67ff7768bbf19c6718e"
-
 [[package]]
 name = "windows_x86_64_gnu"
 version = "0.52.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "147a5c80aabfbf0c7d901cb5895d1de30ef2907eb21fbbab29ca94c5b08b1a78"
 
-[[package]]
-name = "windows_x86_64_gnullvm"
-version = "0.48.5"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0b7b52767868a23d5bab768e390dc5f5c55825b6d30b86c844ff2dc7414044cc"
-
 [[package]]
 name = "windows_x86_64_gnullvm"
 version = "0.52.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "24d5b23dc417412679681396f2b49f3de8c1473deb516bd34410872eff51ed0d"
 
-[[package]]
-name = "windows_x86_64_msvc"
-version = "0.48.5"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ed94fce61571a4006852b7389a063ab983c02eb1bb37b47f8272ce92d06d9538"
-
 [[package]]
 name = "windows_x86_64_msvc"
 version = "0.52.6"
diff --git a/Cargo.toml b/Cargo.toml
index f658d1d..b137ae6 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -16,7 +16,7 @@ rust-version = "1.79.0"
 version = "0.6.3"
 
 [dependencies]
-miette     = { version = "7.2.0", optional = true, features = ["fancy"] }
+miette     = { version = "7.4.0", optional = true, features = ["fancy"] }
 serde      = { version = "1.0.203", optional = true, features = ["alloc"] }
 serde_json = { version = "1.0.119", optional = true, features = ["alloc"] }
 toml       = { version = "0.8", optional = true }
diff --git a/src/assign.rs b/src/assign.rs
index 187f209..f8f4803 100644
--- a/src/assign.rs
+++ b/src/assign.rs
@@ -37,26 +37,16 @@
 //!
 
 use crate::{
-    diagnostic::{impl_diagnostic_url, Diagnostic, Label},
+    diagnostic::{diagnostic_url, Diagnostic, Label},
     index::{OutOfBoundsError, ParseIndexError},
-    Pointer,
+    Pointer, PointerBuf,
 };
-use alloc::borrow::Cow;
+use alloc::boxed::Box;
 use core::{
     fmt::{self, Debug},
     iter::once,
 };
 
-/*
-░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
-╔══════════════════════════════════════════════════════════════════════════════╗
-║                                                                              ║
-║                                    Assign                                    ║
-║                                   ¯¯¯¯¯¯¯¯                                   ║
-╚══════════════════════════════════════════════════════════════════════════════╝
-░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
-*/
-
 /// Implemented by types which can internally assign a
 /// ([`Value`](`Assign::Value`)) at a path represented by a JSON [`Pointer`].
 ///
@@ -134,30 +124,10 @@ pub trait Assign {
         V: Into<Self::Value>;
 }
 
-/*
-░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
-╔══════════════════════════════════════════════════════════════════════════════╗
-║                                                                              ║
-║                                 AssignError                                  ║
-║                                ¯¯¯¯¯¯¯¯¯¯¯¯¯                                 ║
-╚══════════════════════════════════════════════════════════════════════════════╝
-░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
-*/
-
 /// Alias for [`Error`] - indicates a value assignment failed.
 #[deprecated(since = "0.7.0", note = "renamed to `Error`")]
 pub type AssignError = Error;
 
-/*
-░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
-╔══════════════════════════════════════════════════════════════════════════════╗
-║                                                                              ║
-║                                    Error                                     ║
-║                                   ¯¯¯¯¯¯¯                                    ║
-╚══════════════════════════════════════════════════════════════════════════════╝
-░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
-*/
-
 /// Possible error returned from [`Assign`] implementations for
 /// [`serde_json::Value`] and
 /// [`toml::Value`](https://docs.rs/toml/0.8.14/toml/index.html).
@@ -189,7 +159,7 @@ pub enum Error {
 }
 
 impl Error {
-    /// Returns the position (index) of the [`Token`](crate::Token) which was out of bounds
+    /// The position (token index) of the [`Token`](crate::Token) which was out of bounds
     pub fn position(&self) -> usize {
         match self {
             Self::OutOfBounds { position, .. } | Self::FailedToParseIndex { position, .. } => {
@@ -197,42 +167,52 @@ impl Error {
             }
         }
     }
-
+    /// Offset (in bytes) of the partial pointer starting with the invalid token.
     pub fn offset(&self) -> usize {
         match self {
             Self::OutOfBounds { offset, .. } | Self::FailedToParseIndex { offset, .. } => *offset,
         }
     }
+
+    /// Returns `true` if the error is [`OutOfBounds`].
+    ///
+    /// [`OutOfBounds`]: Error::OutOfBounds
+    #[must_use]
+    pub fn is_out_of_bounds(&self) -> bool {
+        matches!(self, Self::OutOfBounds { .. })
+    }
+
+    /// Returns `true` if the error is [`FailedToParseIndex`].
+    ///
+    /// [`FailedToParseIndex`]: Error::FailedToParseIndex
+    #[must_use]
+    pub fn is_failed_to_parse_index(&self) -> bool {
+        matches!(self, Self::FailedToParseIndex { .. })
+    }
 }
 
 impl fmt::Display for Error {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         match self {
-            Self::FailedToParseIndex { .. } => {
-                write!(
-                    f,
-                    "value failed to be assigned by json pointer; \
-                    array index for token at offset {} is not a valid integer or '-'",
-                    self.offset()
-                )
-            }
-            Self::OutOfBounds { .. } => {
+            Self::FailedToParseIndex { offset, .. } => {
                 write!(
                     f,
-                    "value failed to be assigned by json pointer; \
-                    array index for token at offset {} is out of bounds",
-                    self.offset()
+                    "assign failed: json pointer token at offset {offset} failed to parse as an array index"
                 )
             }
+            Self::OutOfBounds { offset, .. } => write!(
+                f,
+                "assign failed: json pointer token at offset {offset} is out of bounds",
+            ),
         }
     }
 }
 
-impl<'s> Diagnostic<'s> for Error {
-    type Subject = Cow<'s, Pointer>;
+impl Diagnostic for Error {
+    type Subject = PointerBuf;
 
     fn url() -> &'static str {
-        impl_diagnostic_url!(enum assign::Error)
+        diagnostic_url!(enum assign::Error)
     }
 
     fn labels(&self, origin: &Self::Subject) -> Option<Box<dyn Iterator<Item = Label>>> {
@@ -244,18 +224,20 @@ impl<'s> Diagnostic<'s> for Error {
             self.offset()
         };
         let len = token.encoded().len();
-        Some(match self {
-            Error::FailedToParseIndex { .. } => Box::new(once(Label::new(
-                format!("\"{}\" is an invalid array index", token.decoded()),
-                offset,
-                len,
-            ))),
-            Error::OutOfBounds { source, .. } => Box::new(once(Label::new(
-                format!("{} is out of bounds (len: {})", source.index, source.length),
-                offset,
-                len,
-            ))),
-        })
+        let text = match self {
+            Error::FailedToParseIndex { .. } => "expected array index or '-'".to_string(),
+            Error::OutOfBounds { source, .. } => {
+                format!("{} is out of bounds (len: {})", source.index, source.length)
+            }
+        };
+        Some(Box::new(once(Label::new(text, offset, len))))
+    }
+}
+
+#[cfg(feature = "miette")]
+impl miette::Diagnostic for Error {
+    fn url<'a>(&'a self) -> Option<Box<dyn fmt::Display + 'a>> {
+        Some(Box::new(<Self as Diagnostic>::url()))
     }
 }
 
@@ -269,16 +251,6 @@ impl std::error::Error for Error {
     }
 }
 
-/*
-░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
-╔══════════════════════════════════════════════════════════════════════════════╗
-║                                                                              ║
-║                                  json impl                                   ║
-║                                 ¯¯¯¯¯¯¯¯¯¯¯                                  ║
-╚══════════════════════════════════════════════════════════════════════════════╝
-░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
-*/
-
 #[cfg(feature = "json")]
 mod json {
     use super::{Assign, Assigned, Error};
@@ -454,16 +426,6 @@ mod json {
     }
 }
 
-/*
-░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
-╔══════════════════════════════════════════════════════════════════════════════╗
-║                                                                              ║
-║                                  toml impl                                   ║
-║                                 ¯¯¯¯¯¯¯¯¯¯¯                                  ║
-╚══════════════════════════════════════════════════════════════════════════════╝
-░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
-*/
-
 #[cfg(feature = "toml")]
 mod toml {
     use super::{Assign, Assigned, Error};
@@ -638,16 +600,6 @@ enum Assigned<'v, V> {
     Continue { next_dest: &'v mut V, same_value: V },
 }
 
-/*
-░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
-╔══════════════════════════════════════════════════════════════════════════════╗
-║                                                                              ║
-║                                    Tests                                     ║
-║                                   ¯¯¯¯¯¯¯                                    ║
-╚══════════════════════════════════════════════════════════════════════════════╝
-░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
-*/
-
 #[cfg(test)]
 #[allow(clippy::too_many_lines)]
 mod tests {
@@ -694,12 +646,6 @@ mod tests {
         }
     }
 
-    /*
-    ╔═══════════════════════════════════════════════════╗
-    ║                        json                       ║
-    ╚═══════════════════════════════════════════════════╝
-    */
-
     #[test]
     #[cfg(feature = "json")]
     fn assign_json() {
@@ -890,12 +836,6 @@ mod tests {
         .for_each(|(i, t)| t.run(i));
     }
 
-    /*
-    ╔══════════════════════════════════════════════════╗
-    ║                       toml                       ║
-    ╚══════════════════════════════════════════════════╝
-    */
-
     #[test]
     #[cfg(feature = "toml")]
     fn assign_toml() {
diff --git a/src/diagnostic.rs b/src/diagnostic.rs
index 354232d..e450e77 100644
--- a/src/diagnostic.rs
+++ b/src/diagnostic.rs
@@ -1,18 +1,17 @@
 //! Error reporting data structures and miette integration.
+//!
 
-use core::fmt;
+use alloc::{boxed::Box, string::String};
+use core::{fmt, ops::Deref};
 
 /// Implemented by errors which can be converted into a [`Report`].
-pub trait Diagnostic<'s>: Sized + private::Sealed {
+pub trait Diagnostic: Sized {
     /// The value which caused the error.
-    type Subject: private::IntoOwned;
+    type Subject: Deref;
 
     /// Combine the error with its subject to generate a [`Report`].
-    fn into_report(self, subject: impl Into<Self::Subject>) -> Report<Self, Self::Subject> {
-        Report {
-            source: self,
-            subject: subject.into(),
-        }
+    fn into_report(self, subject: impl Into<Self::Subject>) -> Report<Self> {
+        Report::new(self, subject.into())
     }
 
     /// The docs.rs URL for this error
@@ -23,6 +22,7 @@ pub trait Diagnostic<'s>: Sized + private::Sealed {
 }
 
 /// A label for a span within a json pointer or malformed string.
+///
 #[derive(Debug, PartialEq, Eq, Clone)]
 pub struct Label {
     text: String,
@@ -45,80 +45,66 @@ impl From<Label> for miette::LabeledSpan {
 }
 
 /// An error wrapper which includes the subject of the failure.
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct Report<SRC, SUB> {
-    source: SRC,
-    subject: SUB,
+#[derive(Debug, Clone)]
+pub struct Report<D: Diagnostic> {
+    source: D,
+    subject: D::Subject,
 }
 
-impl<SRC, SUB> Report<SRC, SUB> {
+impl<D: Diagnostic> Report<D> {
+    fn new(source: D, subject: D::Subject) -> Self {
+        Self { source, subject }
+    }
+
     /// The value which caused the error.
-    pub fn subject(&self) -> &SUB {
+    pub fn subject(&self) -> &<D::Subject as Deref>::Target {
         &self.subject
     }
 
     /// The error which occurred.
-    pub fn original(&self) -> &SRC {
+    pub fn original(&self) -> &D {
         &self.source
     }
 
     /// The original parts of the [`Report`].
-    pub fn decompose(self) -> (SRC, SUB) {
+    pub fn decompose(self) -> (D, D::Subject) {
         (self.source, self.subject)
     }
 }
 
-impl<'s, S> Report<S, <S as Diagnostic<'s>>::Subject>
-where
-    S: Diagnostic<'s>,
-{
-    /// Converts the Report into an owned instance (generally by cloning the subject).
-    pub fn into_owned(self) -> Report<S, <S::Subject as private::IntoOwned>::Owned> {
-        use private::IntoOwned;
-
-        Report {
-            source: self.source,
-            subject: self.subject.into_owned(),
-        }
-    }
-}
-
-impl<SRC, SUB> core::ops::Deref for Report<SRC, SUB> {
-    type Target = SRC;
+impl<D: Diagnostic> core::ops::Deref for Report<D> {
+    type Target = D;
 
     fn deref(&self) -> &Self::Target {
         &self.source
     }
 }
 
-impl<SRC, SUB> fmt::Display for Report<SRC, SUB>
-where
-    SRC: fmt::Display,
-{
+impl<D: Diagnostic + fmt::Display> fmt::Display for Report<D> {
     fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
         fmt::Display::fmt(&self.source, f)
     }
 }
 
 #[cfg(feature = "std")]
-impl<SRC, SUB> std::error::Error for Report<SRC, SUB>
+impl<D> std::error::Error for Report<D>
 where
-    SRC: fmt::Debug + std::error::Error + 'static,
-    SUB: fmt::Debug,
+    D: Diagnostic + fmt::Debug + std::error::Error + 'static,
+    D::Subject: fmt::Debug,
 {
-    fn source(&self) -> Option<&(dyn core::error::Error + 'static)> {
-        Some(&self.source)
+    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
+        self.source.source()
     }
 }
 
 #[cfg(feature = "miette")]
-impl<'s, SRC> miette::Diagnostic for Report<SRC, SRC::Subject>
+impl<D> miette::Diagnostic for Report<D>
 where
-    SRC: Diagnostic<'s> + fmt::Debug + std::error::Error + 'static,
-    SRC::Subject: fmt::Debug + miette::SourceCode,
+    D: Diagnostic + fmt::Debug + std::error::Error + 'static,
+    D::Subject: fmt::Debug + miette::SourceCode,
 {
     fn url<'a>(&'a self) -> Option<Box<dyn core::fmt::Display + 'a>> {
-        Some(Box::new(SRC::url()))
+        Some(Box::new(D::url()))
     }
 
     fn source_code(&self) -> Option<&dyn miette::SourceCode> {
@@ -126,22 +112,22 @@ where
     }
 
     fn labels(&self) -> Option<Box<dyn Iterator<Item = miette::LabeledSpan> + '_>> {
-        Some(Box::new(SRC::labels(self, &self.subject)?.map(Into::into)))
+        Some(Box::new(D::labels(self, &self.subject)?.map(Into::into)))
     }
 }
 
-macro_rules! impl_diagnostic_url {
+macro_rules! diagnostic_url {
     (enum $type:ident) => {
-        $crate::diagnostic::impl_diagnostic_url!("enum", "", $type)
+        $crate::diagnostic::diagnostic_url!("enum", "", $type)
     };
     (struct $type:ident) => {
-        $crate::diagnostic::impl_diagnostic_url!("struct", "", $type)
+        $crate::diagnostic::diagnostic_url!("struct", "", $type)
     };
     (enum $mod:ident::$type:ident) => {
-        $crate::diagnostic::impl_diagnostic_url!("enum", concat!("/", stringify!($mod)), $type)
+        $crate::diagnostic::diagnostic_url!("enum", concat!("/", stringify!($mod)), $type)
     };
     (struct $mod:ident::$type:ident) => {
-        $crate::diagnostic::impl_diagnostic_url!("struct", concat!("/", stringify!($mod)), $type)
+        $crate::diagnostic::diagnostic_url!("struct", concat!("/", stringify!($mod)), $type)
     };
     ($kind:literal, $mod:expr, $type:ident) => {
         concat!(
@@ -157,69 +143,67 @@ macro_rules! impl_diagnostic_url {
         )
     };
 }
-pub(crate) use impl_diagnostic_url;
-
-mod private {
-    use alloc::borrow::Cow;
-
-    pub trait Sealed {}
-    impl Sealed for crate::pointer::ParseError {}
-    impl Sealed for crate::assign::Error {}
-
-    pub trait IntoOwned {
-        type Owned;
-
-        fn into_owned(self) -> Self::Owned;
-    }
-
-    impl<'s, T: 'static + ToOwned + ?Sized> IntoOwned for Cow<'s, T> {
-        type Owned = Cow<'static, T>;
-
-        fn into_owned(self) -> Cow<'static, T> {
-            Cow::Owned(self.into_owned())
-        }
-    }
-}
+pub(crate) use diagnostic_url;
 
+/// An extension trait for `Result<_, E>`, where `E` is an implementation of
+/// [`Diagnostic`], that converts `E` into [`Report<E>`](`Report`), yielding
+/// `Result<_, Report<E>>`.
 pub trait Diagnose<'s, T> {
-    type Error: Diagnostic<'s>;
-
+    /// The error type returned from `diagnose` and `diagnose_with`.
+    type Error: Diagnostic;
+
+    /// If the `Result` is an `Err`, converts the error into a [`Report`] with
+    /// the supplied `subject`.
+    ///
+    /// ## Example
+    /// ```
+    /// use core::any::{Any, TypeId};
+    /// use jsonptr::{Pointer, ParseError, Diagnose, Report};
+    /// let subj = "invalid/pointer";
+    /// let err = Pointer::parse(subj).diagnose(subj).unwrap_err();
+    /// assert_eq!(err.type_id(),TypeId::of::<Report<ParseError>>());
+    /// ```
     #[allow(clippy::missing_errors_doc)]
     fn diagnose(
         self,
-        subject: impl Into<<Self::Error as Diagnostic<'s>>::Subject>,
-    ) -> Result<T, Report<Self::Error, <Self::Error as Diagnostic<'s>>::Subject>>;
-
+        subject: impl Into<<Self::Error as Diagnostic>::Subject>,
+    ) -> Result<T, Report<Self::Error>>;
+
+    /// If the `Result` is an `Err`, converts the error into a [`Report`] with
+    /// the subject returned from `f`
+    ///
+    /// ## Example
+    /// ```
+    /// use core::any::{Any, TypeId};
+    /// use jsonptr::{Pointer, ParseError, Diagnose, Report};
+    /// let subj = "invalid/pointer";
+    /// let err = Pointer::parse(subj).diagnose_with(|| subj).unwrap_err();
+    ///
+    /// assert_eq!(err.type_id(),TypeId::of::<Report<ParseError>>());
     #[allow(clippy::missing_errors_doc)]
-    fn diagnose_with<F, S>(
-        self,
-        f: F,
-    ) -> Result<T, Report<Self::Error, <Self::Error as Diagnostic<'s>>::Subject>>
+    fn diagnose_with<F, S>(self, f: F) -> Result<T, Report<Self::Error>>
     where
         F: FnOnce() -> S,
-        S: Into<<Self::Error as Diagnostic<'s>>::Subject>;
+        S: Into<<Self::Error as Diagnostic>::Subject>;
 }
 
 impl<'s, T, E> Diagnose<'s, T> for Result<T, E>
 where
-    E: Diagnostic<'s>,
+    E: Diagnostic,
 {
     type Error = E;
 
     fn diagnose(
         self,
-        subject: impl Into<<Self::Error as Diagnostic<'s>>::Subject>,
-    ) -> Result<T, Report<Self::Error, <Self::Error as Diagnostic<'s>>::Subject>> {
+        subject: impl Into<<Self::Error as Diagnostic>::Subject>,
+    ) -> Result<T, Report<Self::Error>> {
         self.map_err(|error| error.into_report(subject.into()))
     }
 
-    fn diagnose_with<F, S>(
-        self,
-        f: F,
-    ) -> Result<T, Report<Self::Error, <Self::Error as Diagnostic<'s>>::Subject>>
+    fn diagnose_with<F, S>(self, f: F) -> Result<T, Report<Self::Error>>
     where
         F: FnOnce() -> S,
-        S: Into<<Self::Error as Diagnostic<'s>>::Subject>,
+        S: Into<<Self::Error as Diagnostic>::Subject>,
     {
         self.diagnose(f())
     }
@@ -229,7 +213,6 @@ where
 mod tests {
     use super::*;
     use crate::{Pointer, PointerBuf};
-
     #[test]
     #[cfg(all(
         feature = "assign",
@@ -239,7 +222,6 @@ mod tests {
     ))]
     fn assign_error() {
         let mut v = serde_json::json!({"foo": {"bar": ["0"]}});
-
         let ptr = PointerBuf::parse("/foo/bar/invalid/cannot/reach").unwrap();
         let report = ptr.assign(&mut v, "qux").diagnose(ptr).unwrap_err();
         println!("{:?}", miette::Report::from(report));
@@ -249,6 +231,24 @@ mod tests {
         println!("{:?}", miette::Report::from(report));
     }
 
+    #[test]
+    #[cfg(all(
+        feature = "resolve",
+        feature = "miette",
+        feature = "serde",
+        feature = "json"
+    ))]
+    fn resolve_error() {
+        let v = serde_json::json!({"foo": {"bar": ["0"]}});
+        let ptr = PointerBuf::parse("/foo/bar/invalid/cannot/reach").unwrap();
+        let report = ptr.resolve(&v).diagnose(ptr).unwrap_err();
+        println!("{:?}", miette::Report::from(report));
+
+        let ptr = PointerBuf::parse("/foo/bar/3/cannot/reach").unwrap();
+        let report = ptr.resolve(&v).diagnose(ptr).unwrap_err();
+        println!("{:?}", miette::Report::from(report));
+    }
+
     #[test]
     fn parse_error() {
         let invalid = "/foo/bar/invalid~3~encoding/cannot/reach";
@@ -261,19 +261,4 @@ mod tests {
         let report = miette::Report::from(report);
         println!("{report:?}");
     }
-
-    #[test]
-    fn into_owned() {
-        let owned_report = {
-            // creating owned string to ensure its lifetime is local
-            // (could also coerce a static reference, but this is less brittle)
-            let invalid = "/foo/bar/invalid~3~encoding/cannot/reach".to_string();
-            let report = Pointer::parse(&invalid)
-                .diagnose(invalid.as_str())
-                .unwrap_err();
-            report.into_owned()
-        };
-
-        println!("{owned_report}");
-    }
 }
diff --git a/src/index.rs b/src/index.rs
index 0acbb4b..bad40bc 100644
--- a/src/index.rs
+++ b/src/index.rs
@@ -237,7 +237,7 @@ derive_try_from!(String, &String);
 */
 
 /// Indicates that an `Index` is not within the given bounds.
-#[derive(Debug, PartialEq, Eq)]
+#[derive(Debug, Clone, PartialEq, Eq)]
 pub struct OutOfBoundsError {
     /// The provided array length.
     ///
@@ -256,7 +256,7 @@ impl fmt::Display for OutOfBoundsError {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         write!(
             f,
-            "index {} out of bounds (limit: {})",
+            "index {} out of bounds (len: {})",
             self.index, self.length
         )
     }
@@ -276,7 +276,7 @@ impl std::error::Error for OutOfBoundsError {}
 */
 
 /// Indicates that the `Token` could not be parsed as valid RFC 6901 array index.
-#[derive(Debug, PartialEq, Eq)]
+#[derive(Debug, Clone, PartialEq, Eq)]
 pub enum ParseIndexError {
     /// The Token does not represent a valid integer.
     InvalidInteger(ParseIntError),
@@ -295,14 +295,16 @@ impl From<ParseIntError> for ParseIndexError {
 impl fmt::Display for ParseIndexError {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         match self {
-            ParseIndexError::InvalidInteger(source) => {
-                write!(f, "failed to parse token as an integer: {source}")
+            ParseIndexError::InvalidInteger(_) => {
+                write!(f, "failed to parse token as an integer")
             }
             ParseIndexError::LeadingZeros => write!(
                 f,
                 "token contained leading zeros, which are disallowed by RFC 6901"
             ),
-            ParseIndexError::InvalidCharacter(err) => err.fmt(f),
+            ParseIndexError::InvalidCharacter(_) => {
+                write!(f, "failed to parse token as an index")
+            }
         }
     }
 }
@@ -319,7 +321,7 @@ impl std::error::Error for ParseIndexError {
 }
 
 /// Indicates that a non-digit character was found when parsing the RFC 6901 array index.
-#[derive(Debug, PartialEq, Eq)]
+#[derive(Debug, Clone, PartialEq, Eq)]
 pub struct InvalidCharacterError {
     pub(crate) source: String,
     pub(crate) offset: usize,
@@ -456,49 +458,6 @@ mod tests {
         assert!(Index::Next.for_len(1).is_err());
     }
 
-    #[test]
-    fn out_of_bounds_error_display() {
-        let err = OutOfBoundsError {
-            length: 5,
-            index: 10,
-        };
-        assert_eq!(err.to_string(), "index 10 out of bounds (limit: 5)");
-    }
-
-    #[test]
-    fn parse_index_error_display() {
-        let err = ParseIndexError::InvalidInteger("not a number".parse::<usize>().unwrap_err());
-        assert_eq!(
-            err.to_string(),
-            "failed to parse token as an integer: invalid digit found in string"
-        );
-        assert_eq!(
-            ParseIndexError::LeadingZeros.to_string(),
-            "token contained leading zeros, which are disallowed by RFC 6901"
-        );
-        assert_eq!(
-            ParseIndexError::InvalidCharacter(InvalidCharacterError {
-                source: "+10".into(),
-                offset: 0
-            })
-            .to_string(),
-            "token contains the non-digit character '+', \
-                which is disallowed by RFC 6901"
-        );
-    }
-
-    #[test]
-    #[cfg(feature = "std")]
-    fn parse_index_error_source() {
-        use std::error::Error;
-        let err = ParseIndexError::InvalidInteger("not a number".parse::<usize>().unwrap_err());
-        assert_eq!(
-            err.source().unwrap().to_string(),
-            "not a number".parse::<usize>().unwrap_err().to_string()
-        );
-        assert!(ParseIndexError::LeadingZeros.source().is_none());
-    }
-
     #[test]
     fn try_from_token() {
         let token = Token::new("3");
diff --git a/src/lib.rs b/src/lib.rs
index 01df35d..1339c83 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -65,12 +65,16 @@ pub mod resolve;
 pub use resolve::{Resolve, ResolveMut};
 
 pub mod diagnostic;
+pub use diagnostic::{Diagnose, Report};
 
 mod pointer;
-pub use pointer::{ParseError, Pointer, PointerBuf};
+pub use pointer::{ParseError, Pointer, PointerBuf, RichParseError};
 
 mod token;
-pub use token::{InvalidEncodingError, Token, Tokens};
+pub use token::{EncodingError, InvalidEncoding, Token, Tokens};
+
+#[allow(deprecated)]
+pub use token::InvalidEncodingError;
 
 pub mod index;
 
diff --git a/src/pointer.rs b/src/pointer.rs
index 8861913..0216c3e 100644
--- a/src/pointer.rs
+++ b/src/pointer.rs
@@ -1,7 +1,7 @@
 use crate::{
-    diagnostic::{impl_diagnostic_url, Diagnostic, Label, Report},
-    token::InvalidEncodingError,
-    Components, Token, Tokens,
+    diagnostic::{diagnostic_url, Diagnostic, Label, Report},
+    token::EncodingError,
+    Components, InvalidEncoding, Token, Tokens,
 };
 use alloc::{
     borrow::{Cow, ToOwned},
@@ -15,16 +15,6 @@ use slice::PointerIndex;
 
 mod slice;
 
-/*
-░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
-╔══════════════════════════════════════════════════════════════════════════════╗
-║                                                                              ║
-║                                   Pointer                                    ║
-║                                  ¯¯¯¯¯¯¯¯¯                                   ║
-╚══════════════════════════════════════════════════════════════════════════════╝
-░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
-*/
-
 /// A JSON Pointer is a string containing a sequence of zero or more reference
 /// [`Token`]s, each prefixed by a `'/'` character.
 ///
@@ -217,10 +207,11 @@ impl Pointer {
     }
 
     /// Splits the `Pointer` at the given index if the character at the index is
-    /// a separator backslash (`'/'`), returning `Some((head, tail))`. Otherwise,
+    /// a separator slash (`'/'`), returning `Some((head, tail))`. Otherwise,
     /// returns `None`.
     ///
-    /// For the following JSON Pointer, the following splits are possible (0, 4, 8):
+    /// For the following JSON Pointer, the following splits are possible (0, 4,
+    /// 8):
     /// ```text
     /// /foo/bar/baz
     /// ↑   ↑   ↑
@@ -667,7 +658,7 @@ macro_rules! impl_source_code {
     };
 }
 
-impl_source_code!(Pointer, &Pointer);
+impl_source_code!(Pointer, &Pointer, PointerBuf);
 
 impl<'p> From<&'p Pointer> for Cow<'p, Pointer> {
     fn from(value: &'p Pointer) -> Self {
@@ -898,16 +889,6 @@ impl<'a> IntoIterator for &'a Pointer {
     }
 }
 
-/*
-░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
-╔══════════════════════════════════════════════════════════════════════════════╗
-║                                                                              ║
-║                                  PointerBuf                                  ║
-║                                 ¯¯¯¯¯¯¯¯¯¯¯¯                                 ║
-╚══════════════════════════════════════════════════════════════════════════════╝
-░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
-*/
-
 /// An owned, mutable [`Pointer`] (akin to `String`).
 ///
 /// This type provides methods like [`PointerBuf::push_back`] and
@@ -942,10 +923,10 @@ impl PointerBuf {
     ///
     /// ## Errors
     /// Returns a [`RichParseError`] if the string is not a valid JSON Pointer.
-    pub fn parse<'s>(s: impl Into<Cow<'s, str>>) -> Result<Self, RichParseError<'s>> {
+    pub fn parse(s: impl Into<String>) -> Result<Self, RichParseError> {
         let s = s.into();
         match validate(&s) {
-            Ok(_) => Ok(Self(s.into_owned())),
+            Ok(_) => Ok(Self(s)),
             Err(err) => Err(err.into_report(s)),
         }
     }
@@ -1169,80 +1150,25 @@ impl core::fmt::Display for PointerBuf {
     }
 }
 
-const fn validate(value: &str) -> Result<&str, ParseError> {
-    if value.is_empty() {
-        return Ok(value);
-    }
-    let bytes = value.as_bytes();
-    if bytes[0] != b'/' {
-        return Err(ParseError::NoLeadingBackslash);
-    }
-    let mut ptr_offset = 0; // offset within the pointer of the most recent '/' separator
-    let mut tok_offset = 0; // offset within the current token
+/// Indicates that a [`Pointer`] was unable to be parsed due to not containing
+/// a leading slash (`'/'`).
+#[derive(Debug, PartialEq, Eq, Clone, Copy)]
+pub struct NoLeadingSlash;
 
-    let bytes = value.as_bytes();
-    let mut i = 0;
-    while i < bytes.len() {
-        match bytes[i] {
-            b'/' => {
-                // backslashes ('/') separate tokens
-                // we increment the ptr_offset to point to this character
-                ptr_offset = i;
-                // and reset the token offset
-                tok_offset = 0;
-            }
-            b'~' => {
-                // if the character is a '~', then the next character must be '0' or '1'
-                // otherwise the encoding is invalid and `InvalidEncodingError` is returned
-                if i + 1 >= bytes.len() || (bytes[i + 1] != b'0' && bytes[i + 1] != b'1') {
-                    // the pointer is not properly encoded
-                    //
-                    // we use the pointer offset, which points to the last
-                    // encountered separator, as the offset of the error.
-                    // The source `InvalidEncodingError` then uses the token
-                    // offset.
-                    //
-                    // "/foo/invalid~encoding"
-                    //      ^       ^
-                    //      |       |
-                    //  ptr_offset  |
-                    //          tok_offset
-                    //
-                    return Err(ParseError::InvalidEncoding {
-                        offset: ptr_offset,
-                        source: InvalidEncodingError { offset: tok_offset },
-                    });
-                }
-                // already checked the next character, so we skip it
-                i += 1;
-                // incrementing the pointer offset since the next byte has
-                // already been checked
-                tok_offset += 1;
-            }
-            _ => {}
-        }
-        i += 1;
-        // not a separator so we increment the token offset
-        tok_offset += 1;
+impl fmt::Display for NoLeadingSlash {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(
+            f,
+            "json pointer must start with a backslash ('/') and is not empty"
+        )
     }
-    Ok(value)
 }
 
-/*
-░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
-╔══════════════════════════════════════════════════════════════════════════════╗
-║                                                                              ║
-║                                  ParseError                                  ║
-║                                 ¯¯¯¯¯¯¯¯¯¯¯¯                                 ║
-╚══════════════════════════════════════════════════════════════════════════════╝
-░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
-*/
-
 /// Indicates that a `Pointer` was malformed and unable to be parsed.
 #[derive(Debug, PartialEq)]
 pub enum ParseError {
-    /// `Pointer` did not start with a backslash (`'/'`).
-    NoLeadingBackslash,
+    /// `Pointer` did not start with a slash (`'/'`).
+    NoLeadingSlash,
 
     /// `Pointer` contained invalid encoding (e.g. `~` not followed by `0` or
     /// `1`).
@@ -1251,21 +1177,23 @@ pub enum ParseError {
         /// the invalid encoding
         offset: usize,
         /// The source `InvalidEncodingError`
-        source: InvalidEncodingError,
+        source: EncodingError,
     },
 }
 
 impl ParseError {
+    /// Offset of the partial pointer starting with the token that contained the
+    /// invalid encoding
     pub fn offset(&self) -> usize {
         match self {
-            Self::NoLeadingBackslash => 0,
+            Self::NoLeadingSlash => 0,
             Self::InvalidEncoding { offset, .. } => *offset,
         }
     }
-
+    /// Length of the invalid encoding
     pub fn invalid_encoding_len(&self, subject: &str) -> usize {
         match self {
-            Self::NoLeadingBackslash => 0,
+            Self::NoLeadingSlash => 0,
             Self::InvalidEncoding { offset, .. } => {
                 if *offset < subject.len() - 1 {
                     2
@@ -1277,19 +1205,18 @@ impl ParseError {
     }
 }
 
-impl<'s> Diagnostic<'s> for ParseError {
-    type Subject = Cow<'s, str>;
+impl Diagnostic for ParseError {
+    type Subject = String;
 
     fn url() -> &'static str {
-        impl_diagnostic_url!(struct ParseError)
+        diagnostic_url!(struct ParseError)
     }
 
     fn labels(&self, subject: &Self::Subject) -> Option<Box<dyn Iterator<Item = Label>>> {
-        // TODO: considering searching the pointer for all invalid encodings
         let offset = self.complete_offset();
         let len = self.invalid_encoding_len(subject);
         let text = match self {
-            ParseError::NoLeadingBackslash => "must start with a backslash ('/')",
+            ParseError::NoLeadingSlash => "must start with a backslash ('/')",
             ParseError::InvalidEncoding { .. } => "'~' must be followed by '0' or '1'",
         }
         .to_string();
@@ -1297,16 +1224,24 @@ impl<'s> Diagnostic<'s> for ParseError {
     }
 }
 
+#[cfg(feature = "miette")]
+impl miette::Diagnostic for ParseError {}
+
 impl fmt::Display for ParseError {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         match self {
-            Self::NoLeadingBackslash { .. } => {
+            Self::NoLeadingSlash { .. } => {
+                write!(
+                    f,
+                    "json pointer failed to parse; does not start with a backslash ('/') and is not empty"
+                )
+            }
+            Self::InvalidEncoding { offset, .. } => {
                 write!(
                     f,
-                    "json pointer is malformed as it does not start with a backslash ('/') and is not empty"
+                    "json pointer failed to parse; the first token in the partial-pointer starting at offset {offset} is malformed"
                 )
             }
-            Self::InvalidEncoding { source, .. } => fmt::Display::fmt(source, f),
         }
     }
 }
@@ -1314,7 +1249,7 @@ impl fmt::Display for ParseError {
 impl ParseError {
     /// Returns `true` if this error is `NoLeadingBackslash`
     pub fn is_no_leading_backslash(&self) -> bool {
-        matches!(self, Self::NoLeadingBackslash { .. })
+        matches!(self, Self::NoLeadingSlash { .. })
     }
 
     /// Returns `true` if this error is `InvalidEncoding`    
@@ -1336,7 +1271,7 @@ impl ParseError {
     /// ```
     pub fn pointer_offset(&self) -> usize {
         match *self {
-            Self::NoLeadingBackslash { .. } => 0,
+            Self::NoLeadingSlash { .. } => 0,
             Self::InvalidEncoding { offset, .. } => offset,
         }
     }
@@ -1356,7 +1291,7 @@ impl ParseError {
     /// ```
     pub fn source_offset(&self) -> usize {
         match self {
-            Self::NoLeadingBackslash { .. } => 0,
+            Self::NoLeadingSlash { .. } => 0,
             Self::InvalidEncoding { source, .. } => source.offset,
         }
     }
@@ -1382,22 +1317,13 @@ impl std::error::Error for ParseError {
     fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
         match self {
             Self::InvalidEncoding { source, .. } => Some(source),
-            Self::NoLeadingBackslash => None,
+            Self::NoLeadingSlash => None,
         }
     }
 }
 
-pub type RichParseError<'s> = Report<ParseError, <ParseError as Diagnostic<'s>>::Subject>;
-
-/*
-░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
-╔══════════════════════════════════════════════════════════════════════════════╗
-║                                                                              ║
-║                              ReplaceTokenError                               ║
-║                             ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯                              ║
-╚══════════════════════════════════════════════════════════════════════════════╝
-░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
-*/
+/// A rich error type that includes the original string that failed to parse.
+pub type RichParseError = Report<ParseError>;
 
 /// Returned from [`PointerBuf::replace`] when the provided index is out of
 /// bounds.
@@ -1418,15 +1344,71 @@ impl fmt::Display for ReplaceError {
 #[cfg(feature = "std")]
 impl std::error::Error for ReplaceError {}
 
-/*
-░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
-╔══════════════════════════════════════════════════════════════════════════════╗
-║                                                                              ║
-║                                    Tests                                     ║
-║                                   ¯¯¯¯¯¯¯                                    ║
-╚══════════════════════════════════════════════════════════════════════════════╝
-░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
-*/
+const fn validate(value: &str) -> Result<&str, ParseError> {
+    if value.is_empty() {
+        return Ok(value);
+    }
+    if let Err(err) = validate_bytes(value.as_bytes(), 0) {
+        return Err(err);
+    }
+    Ok(value)
+}
+
+const fn validate_bytes(bytes: &[u8], offset: usize) -> Result<(), ParseError> {
+    if bytes[0] != b'/' && offset == 0 {
+        return Err(ParseError::NoLeadingSlash);
+    }
+
+    let mut ptr_offset = offset; // offset within the pointer of the most recent '/' separator
+    let mut tok_offset = 0; // offset within the current token
+
+    let mut i = offset;
+    while i < bytes.len() {
+        match bytes[i] {
+            b'/' => {
+                ptr_offset = i;
+                // and reset the token offset
+                tok_offset = 0;
+            }
+            b'~' => {
+                // if the character is a '~', then the next character must be '0' or '1'
+                // otherwise the encoding is invalid and `InvalidEncodingError` is returned
+                if i + 1 >= bytes.len() || (bytes[i + 1] != b'0' && bytes[i + 1] != b'1') {
+                    // the pointer is not properly encoded
+                    //
+                    // we use the pointer offset, which points to the last
+                    // encountered separator, as the offset of the error.
+                    // The source `InvalidEncodingError` then uses the token
+                    // offset.
+                    //
+                    // "/foo/invalid~encoding"
+                    //      ^       ^
+                    //      |       |
+                    //  ptr_offset  |
+                    //          tok_offset
+                    //
+                    return Err(ParseError::InvalidEncoding {
+                        offset: ptr_offset,
+                        source: EncodingError {
+                            offset: tok_offset,
+                            source: InvalidEncoding::Tilde,
+                        },
+                    });
+                }
+                // already checked the next character, so we skip it
+                i += 1;
+                // incrementing the pointer offset since the next byte has
+                // already been checked
+                tok_offset += 1;
+            }
+            _ => {}
+        }
+        i += 1;
+        // not a separator so we increment the token offset
+        tok_offset += 1;
+    }
+    Ok(())
+}
 
 #[cfg(test)]
 mod tests {
@@ -1540,26 +1522,35 @@ mod tests {
             ("/foo/bar/baz/~10", Ok("/foo/bar/baz/~10")),
             ("/foo/bar/baz/~11", Ok("/foo/bar/baz/~11")),
             ("/foo/bar/baz/~1/~0", Ok("/foo/bar/baz/~1/~0")),
-            ("missing-slash", Err(ParseError::NoLeadingBackslash)),
+            ("missing-slash", Err(ParseError::NoLeadingSlash)),
             (
                 "/~",
                 Err(ParseError::InvalidEncoding {
                     offset: 0,
-                    source: InvalidEncodingError { offset: 1 },
+                    source: EncodingError {
+                        offset: 1,
+                        source: InvalidEncoding::Tilde,
+                    },
                 }),
             ),
             (
                 "/~2",
                 Err(ParseError::InvalidEncoding {
                     offset: 0,
-                    source: InvalidEncodingError { offset: 1 },
+                    source: EncodingError {
+                        offset: 1,
+                        source: InvalidEncoding::Tilde,
+                    },
                 }),
             ),
             (
                 "/~a",
                 Err(ParseError::InvalidEncoding {
                     offset: 0,
-                    source: InvalidEncodingError { offset: 1 },
+                    source: EncodingError {
+                        offset: 1,
+                        source: InvalidEncoding::Tilde,
+                    },
                 }),
             ),
         ];
@@ -2116,10 +2107,6 @@ mod tests {
 
         let invalid = serde_json::from_str::<&Pointer>("\"foo/bar\"");
         assert!(invalid.is_err());
-        assert_eq!(
-            invalid.unwrap_err().to_string(),
-            "failed to parse json pointer\n\ncaused by:\njson pointer is malformed as it does not start with a backslash ('/') and is not empty at line 1 column 9"
-        );
     }
 
     #[test]
@@ -2352,7 +2339,7 @@ mod tests {
 
     #[test]
     fn quick_miette_spike() {
-        let err = PointerBuf::parse("hello-world").unwrap_err();
-        println!("{:?}", miette::Report::from(err));
+        // let err = PointerBuf::parse("hello-world").unwrap_err();
+        // println!("{:?}", miette::Report::from(err));
     }
 }
diff --git a/src/resolve.rs b/src/resolve.rs
index 38f2d79..b7ce22a 100644
--- a/src/resolve.rs
+++ b/src/resolve.rs
@@ -33,21 +33,14 @@
 //! | TOML  |    `toml::Value`    |   `"toml"`   |         |
 //!
 //!
+use core::iter::once;
+
 use crate::{
+    diagnostic::{diagnostic_url, Diagnostic, Label},
     index::{OutOfBoundsError, ParseIndexError},
-    Pointer, Token,
+    Pointer, PointerBuf, Token,
 };
 
-/*
-░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
-╔══════════════════════════════════════════════════════════════════════════════╗
-║                                                                              ║
-║                                   Resolve                                    ║
-║                                  ¯¯¯¯¯¯¯¯¯                                   ║
-╚══════════════════════════════════════════════════════════════════════════════╝
-░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
-*/
-
 /// A trait implemented by types which can resolve a reference to a value type
 /// from a path represented by a JSON [`Pointer`].
 pub trait Resolve {
@@ -65,16 +58,6 @@ pub trait Resolve {
     fn resolve(&self, ptr: &Pointer) -> Result<&Self::Value, Self::Error>;
 }
 
-/*
-░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
-╔══════════════════════════════════════════════════════════════════════════════╗
-║                                                                              ║
-║                                 ResolveMut                                   ║
-║                                ¯¯¯¯¯¯¯¯¯¯¯¯                                  ║
-╚══════════════════════════════════════════════════════════════════════════════╝
-░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
-*/
-
 /// A trait implemented by types which can resolve a mutable reference to a
 /// value type from a path represented by a JSON [`Pointer`].
 pub trait ResolveMut {
@@ -93,16 +76,6 @@ pub trait ResolveMut {
     fn resolve_mut(&mut self, ptr: &Pointer) -> Result<&mut Self::Value, Self::Error>;
 }
 
-/*
-░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
-╔══════════════════════════════════════════════════════════════════════════════╗
-║                                                                              ║
-║                                    Error                                     ║
-║                                   ¯¯¯¯¯¯¯                                    ║
-╚══════════════════════════════════════════════════════════════════════════════╝
-░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
-*/
-
 // TODO: should ResolveError be deprecated?
 /// Alias for [`Error`].
 pub type ResolveError = Error;
@@ -233,23 +206,52 @@ impl Error {
     }
 }
 
+impl Diagnostic for Error {
+    type Subject = PointerBuf;
+
+    fn url() -> &'static str {
+        diagnostic_url!(enum assign::Error)
+    }
+
+    fn labels(&self, origin: &Self::Subject) -> Option<Box<dyn Iterator<Item = Label>>> {
+        let position = self.position();
+        let token = origin.get(position)?;
+        let offset = if self.offset() + 1 < origin.as_str().len() {
+            self.offset() + 1
+        } else {
+            self.offset()
+        };
+        let len = token.encoded().len();
+        let text = match self {
+            Error::FailedToParseIndex { .. } => "not an array index".to_string(),
+            Error::OutOfBounds { source, .. } => source.to_string(),
+            Error::NotFound { .. } => "not found in value".to_string(),
+            Error::Unreachable { .. } => "unreachable".to_string(),
+        };
+        Some(Box::new(once(Label::new(text, offset, len))))
+    }
+}
+
 impl core::fmt::Display for Error {
     fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
         match self {
-            Self::FailedToParseIndex { .. } => {
-                write!(f, "value failed to resolve by json pointer because an array index is not a valid integer")
+            Self::FailedToParseIndex { offset, .. } => {
+                write!(f, "resolve failed: json pointer token at offset {offset} failed to parse as an index")
             }
-            Self::OutOfBounds { .. } => {
+            Self::OutOfBounds { offset, .. } => {
                 write!(
                     f,
-                    "value failed to resolve by json pointer because an array index is out of bounds"
+                    "resolve failed: json pointer token at offset {offset} is out of bounds"
                 )
             }
-            Self::NotFound { .. } => {
-                write!(f, "value failed to resolve by json pointer because a value within the path is not present")
+            Self::NotFound { offset, .. } => {
+                write!(
+                    f,
+                    "resolve failed: json pointer token at {offset} was not found in value"
+                )
             }
-            Self::Unreachable { .. } => {
-                write!(f, "value failed to resolve by json pointer because a scalar or null value was encountered before exhausting the path")
+            Self::Unreachable { offset, .. } => {
+                write!(f, "resolve failed: json pointer token at {offset} is unreachable (previous token resolved to a scalar or null value)")
             }
         }
     }
@@ -266,16 +268,6 @@ impl std::error::Error for Error {
     }
 }
 
-/*
-░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
-╔══════════════════════════════════════════════════════════════════════════════╗
-║                                                                              ║
-║                                  json impl                                   ║
-║                                 ¯¯¯¯¯¯¯¯¯¯¯                                  ║
-╚══════════════════════════════════════════════════════════════════════════════╝
-░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
-*/
-
 #[cfg(feature = "json")]
 mod json {
     use super::{parse_index, Error, Pointer, Resolve, ResolveMut};
@@ -373,16 +365,6 @@ fn parse_index(
         })
 }
 
-/*
-░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
-╔══════════════════════════════════════════════════════════════════════════════╗
-║                                                                              ║
-║                                  toml impl                                   ║
-║                                 ¯¯¯¯¯¯¯¯¯¯¯                                  ║
-╚══════════════════════════════════════════════════════════════════════════════╝
-░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
-*/
-
 #[cfg(feature = "toml")]
 mod toml {
     use super::{Error, Resolve, ResolveMut};
@@ -474,16 +456,6 @@ mod toml {
     }
 }
 
-/*
-░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
-╔══════════════════════════════════════════════════════════════════════════════╗
-║                                                                              ║
-║                                    Tests                                     ║
-║                                   ¯¯¯¯¯¯¯                                    ║
-╚══════════════════════════════════════════════════════════════════════════════╝
-░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
-*/
-
 #[cfg(test)]
 mod tests {
     use super::{Error, Resolve, ResolveMut};
diff --git a/src/token.rs b/src/token.rs
index 1187b39..fe574a2 100644
--- a/src/token.rs
+++ b/src/token.rs
@@ -70,11 +70,16 @@ impl<'a> Token<'a> {
     /// ## Errors
     /// Returns `InvalidEncodingError` if the input string is not a valid RFC
     /// 6901 (`~` must be followed by `0` or `1`)
-    pub fn from_encoded(s: &'a str) -> Result<Self, InvalidEncodingError> {
+    pub fn from_encoded(s: &'a str) -> Result<Self, EncodingError> {
         let mut escaped = false;
         for (offset, b) in s.bytes().enumerate() {
             match b {
-                b'/' => return Err(InvalidEncodingError { offset }),
+                b'/' => {
+                    return Err(EncodingError {
+                        offset,
+                        source: InvalidEncoding::Slash,
+                    })
+                }
                 ENC_PREFIX => {
                     escaped = true;
                 }
@@ -83,13 +88,19 @@ impl<'a> Token<'a> {
                 }
                 _ => {
                     if escaped {
-                        return Err(InvalidEncodingError { offset });
+                        return Err(EncodingError {
+                            offset,
+                            source: InvalidEncoding::Tilde,
+                        });
                     }
                 }
             }
         }
         if escaped {
-            return Err(InvalidEncodingError { offset: s.len() });
+            return Err(EncodingError {
+                offset: s.len(),
+                source: InvalidEncoding::Slash,
+            });
         }
         Ok(Self { inner: s.into() })
     }
@@ -345,23 +356,77 @@ impl<'t> Tokens<'t> {
 ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
 */
 
+#[deprecated(since = "0.7.0", note = "renamed to `EncodingError`")]
+/// Deprecated alias for [`EncodingError`].
+pub type InvalidEncodingError = EncodingError;
+
+/*
+░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
+╔══════════════════════════════════════════════════════════════════════════════╗
+║                                                                              ║
+║                                EncodingError                                 ║
+║                               ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯                                ║
+╚══════════════════════════════════════════════════════════════════════════════╝
+░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
+*/
+
 /// A token within a json pointer contained invalid encoding (`~` not followed
 /// by `0` or `1`).
 ///
 #[derive(Debug, PartialEq, Eq)]
-pub struct InvalidEncodingError {
+pub struct EncodingError {
     /// offset of the erroneous `~` from within the `Token`
     pub offset: usize,
+    /// the specific encoding error
+    pub source: InvalidEncoding,
+}
+
+#[cfg(feature = "std")]
+impl std::error::Error for EncodingError {
+    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
+        Some(&self.source)
+    }
 }
 
-impl fmt::Display for InvalidEncodingError {
+impl fmt::Display for EncodingError {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        write!(f, "json pointer is malformed due to invalid encoding")
+        write!(
+            f,
+            "token contains invalid encoding at offset {}",
+            self.offset
+        )
     }
 }
 
+/*
+░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
+╔══════════════════════════════════════════════════════════════════════════════╗
+║                                                                              ║
+║                               InvalidEncoding                                ║
+║                              ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯                               ║
+╚══════════════════════════════════════════════════════════════════════════════╝
+░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
+*/
+
+/// Represents the specific type of invalid encoding error.
+#[derive(Debug, PartialEq, Eq, Clone, Copy)]
+pub enum InvalidEncoding {
+    /// `~` not followed by `0` or `1`
+    Tilde,
+    /// non-encoded `/` found in token
+    Slash,
+}
+
+impl fmt::Display for InvalidEncoding {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            InvalidEncoding::Tilde => write!(f, "tilde (~) not followed by 0 or 1"),
+            InvalidEncoding::Slash => write!(f, "slash (/) found in token"),
+        }
+    }
+}
 #[cfg(feature = "std")]
-impl std::error::Error for InvalidEncodingError {}
+impl std::error::Error for InvalidEncoding {}
 
 /*
 ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
@@ -428,14 +493,6 @@ mod tests {
         token == decoded
     }
 
-    #[test]
-    fn invalid_encoding_error_display() {
-        assert_eq!(
-            Token::from_encoded("~").unwrap_err().to_string(),
-            "json pointer is malformed due to invalid encoding"
-        );
-    }
-
     #[test]
     fn tokens() {
         let pointer = Pointer::from_static("/a/b/c");