Skip to main content

ferromark_transforms/
lib.rs

1//! Optional ordered passes over Ferromark's arena-backed Markdown AST.
2//!
3//! This crate depends on [`ferromark`] and is not a dependency of the core
4//! parser or renderer. Construct a [`TransformPipeline`] only when AST passes
5//! are needed; an empty pipeline performs no traversal or URL scan.
6//!
7//! # Custom pass
8//!
9//! A pass borrows the parsed document and arena for one call. The same pass
10//! object can be reused for later documents, but it must not retain references
11//! into an arena that the caller may reset. See the packaged
12//! [`custom pass example`](https://github.com/sebastian-software/ferromark/tree/main/transforms/examples/custom_pass.rs).
13//! Pass objects are `Send`, so callers can move a configured pipeline to the
14//! thread that owns a document; documents and contexts stay thread-local.
15
16#![deny(missing_docs)]
17#![deny(
18    clippy::unwrap_used,
19    clippy::expect_used,
20    clippy::panic,
21    clippy::todo,
22    clippy::unimplemented
23)]
24
25mod emoji;
26mod emoji_data;
27mod github;
28mod prose;
29mod toc;
30mod typography;
31
32pub use emoji::EmojiShortcodesPass;
33pub use github::{GitHubReferencesPass, InvalidGitHubRepository};
34pub use toc::{TableOfContentsError, build_table_of_contents};
35pub use typography::{
36    TypographyLanguage, TypographyOptions, TypographyPass, UnsupportedTypographyLanguage,
37};
38
39use std::borrow::Cow;
40use std::error::Error;
41use std::fmt;
42use std::ops::Range;
43
44use ferromark::ast::{Document, Link, Node, Span, Text};
45use ferromark::{Allocator, AutolinkMatcher, HtmlRendererOptions};
46
47/// The boxed, thread-safe error type returned by custom transform passes.
48pub type BoxError = Box<dyn Error + Send + Sync + 'static>;
49
50/// A stateful pass over one parsed document.
51///
52/// Passes run in insertion order. A pass may mutate the document before it
53/// returns an error; the pipeline does not roll back changes. Callers should
54/// discard or reparse that document after a failure. Implementations must keep
55/// all document-specific references local to [`Self::apply`], since callers
56/// may reset the arena as soon as they have finished rendering the document.
57/// Pass values must be `Send` so a configured pipeline can move to the worker
58/// that owns a document.
59pub trait TransformPass: Send {
60    /// Stable name included in pipeline errors.
61    fn name(&self) -> &'static str;
62
63    /// Applies this pass to one document.
64    fn apply<'arena>(
65        &mut self,
66        document: &mut Document<'arena>,
67        context: &TransformContext<'arena>,
68    ) -> Result<(), BoxError>;
69}
70
71/// Ordered collection of reusable AST transform passes.
72#[derive(Default)]
73pub struct TransformPipeline {
74    passes: Vec<Box<dyn TransformPass>>,
75}
76
77impl TransformPipeline {
78    /// Creates an empty pipeline.
79    #[must_use]
80    pub fn new() -> Self {
81        Self::default()
82    }
83
84    /// Appends a pass. Passes are called in the order they are added.
85    pub fn add<P: TransformPass + 'static>(&mut self, pass: P) {
86        self.passes.push(Box::new(pass));
87    }
88
89    /// Returns the number of passes in this pipeline.
90    #[must_use]
91    pub fn len(&self) -> usize {
92        self.passes.len()
93    }
94
95    /// Returns whether this pipeline contains no passes.
96    #[must_use]
97    pub fn is_empty(&self) -> bool {
98        self.passes.is_empty()
99    }
100
101    /// Runs each pass in insertion order and stops at the first error.
102    ///
103    /// The pipeline stores no reference to `document`, `context`, or the arena,
104    /// and can be reused for another document after this call. If a pass fails,
105    /// earlier changes (including changes made by the failing pass) remain in
106    /// the document; discard or reparse it before rendering.
107    pub fn run<'arena>(
108        &mut self,
109        document: &mut Document<'arena>,
110        context: &TransformContext<'arena>,
111    ) -> Result<(), TransformError> {
112        for (pass_index, pass) in self.passes.iter_mut().enumerate() {
113            let pass_name = pass.name();
114            if let Err(source) = pass.apply(document, context) {
115                return Err(TransformError {
116                    pass_index,
117                    pass_name,
118                    source,
119                });
120            }
121        }
122
123        Ok(())
124    }
125}
126
127/// Context available to a pass while one document is being transformed.
128///
129/// The context only scans for URLs when a pass explicitly calls
130/// [`TextRun::protected_url_ranges`]. It builds one reusable matcher from the
131/// supplied renderer options, so disabled autolinks and custom prefixes match
132/// the renderer exactly.
133pub struct TransformContext<'arena> {
134    allocator: &'arena Allocator,
135    source: &'arena str,
136    autolink_matcher: Option<AutolinkMatcher>,
137}
138
139impl<'arena> TransformContext<'arena> {
140    /// Creates a context for the exact source and allocator used to parse a document.
141    ///
142    /// The caller must pass the same allocator and source that produced the
143    /// document; the public AST does not retain either identity for validation.
144    /// Renderer options are copied into one reusable URL matcher for the
145    /// optional URL-protection helper. Construct the renderer from those same
146    /// options (or an unchanged clone) so URL protection and output stay aligned.
147    /// This matcher is not used unless a pass explicitly scans a text run.
148    #[must_use]
149    pub fn new(
150        allocator: &'arena Allocator,
151        source: &'arena str,
152        renderer_options: &HtmlRendererOptions,
153    ) -> Self {
154        Self {
155            allocator,
156            source,
157            autolink_matcher: renderer_options.autolink_matcher(),
158        }
159    }
160
161    /// Returns the source text parsed into the document.
162    #[must_use]
163    pub const fn source(&self) -> &'arena str {
164        self.source
165    }
166
167    /// Allocates a string that can be stored in this document's AST.
168    #[must_use]
169    pub fn alloc_str(&self, value: &str) -> &'arena str {
170        let allocator: &'arena Allocator = self.allocator;
171        allocator.alloc_str(value)
172    }
173
174    /// Creates text for a replacement while preserving its original source span.
175    #[must_use]
176    pub fn replacement_text(&self, value: &str, span: Span) -> Text<'arena> {
177        Text {
178            value: self.alloc_str(value),
179            span,
180        }
181    }
182
183    /// Creates text that was inserted without replacing source content.
184    ///
185    /// Generated text uses [`Span::empty`]. This intentionally does not
186    /// distinguish generated content from a genuine empty source span.
187    #[must_use]
188    pub fn generated_text(&self, value: &str) -> Text<'arena> {
189        self.replacement_text(value, Span::empty())
190    }
191
192    /// Replaces a text node's value and leaves its source span unchanged.
193    pub fn replace_text_value(&self, text: &mut Text<'arena>, value: &str) {
194        text.value = self.alloc_str(value);
195    }
196
197    /// Replaces a byte range within adjacent text nodes and returns its source span.
198    ///
199    /// `node_range` selects one contiguous run from the `nodes` slice. The byte
200    /// range addresses the run's coalesced text and must use UTF-8 boundaries.
201    /// Unchanged prefix and suffix text retain the source ranges of their
202    /// contributing nodes; replacement text receives the bounding span of the
203    /// source nodes it overlaps. A zero-width insertion receives an empty span.
204    /// If one parsed text node decodes to fewer bytes than its source spelling
205    /// (for example a character reference), every piece split from that node
206    /// keeps the full node span; this API does not provide character-level maps.
207    pub fn replace_text_range(
208        &self,
209        nodes: &mut ferromark::allocator::Vec<'arena, Node<'arena>>,
210        node_range: Range<usize>,
211        byte_range: Range<usize>,
212        replacement: &str,
213    ) -> Result<Span, TextReplacementError> {
214        Self::replace_text_range_with_node(nodes, node_range, byte_range, |span| {
215            (!replacement.is_empty()).then(|| Node::Text(self.replacement_text(replacement, span)))
216        })
217    }
218
219    pub(crate) fn replace_text_range_with_node(
220        nodes: &mut ferromark::allocator::Vec<'arena, Node<'arena>>,
221        node_range: Range<usize>,
222        byte_range: Range<usize>,
223        replacement: impl FnOnce(Span) -> Option<Node<'arena>>,
224    ) -> Result<Span, TextReplacementError> {
225        validate_node_range(nodes, &node_range)?;
226        validate_text_byte_range(nodes, &node_range, &byte_range)?;
227
228        let replacement_span = span_for_byte_range(nodes, &node_range, &byte_range);
229        let replacement = replacement(replacement_span);
230        if byte_range.is_empty() {
231            if let Some(node) = replacement {
232                insert_node_at_text_offset(nodes, &node_range, byte_range.start, node);
233            }
234            return Ok(Span::empty());
235        }
236
237        let (first, last, first_offset, last_offset) =
238            overlapping_text_nodes(nodes, &node_range, &byte_range)?;
239        let (first_value, first_span) = match &nodes[first] {
240            Node::Text(text) => (text.value, text.span),
241            _ => return Err(TextReplacementError::NonTextNode { index: first }),
242        };
243        let (last_value, last_span) = match &nodes[last] {
244            Node::Text(text) => (text.value, text.span),
245            _ => return Err(TextReplacementError::NonTextNode { index: last }),
246        };
247
248        // Rebuild only the nodes whose text overlaps the edit. Prefix and
249        // suffix slices borrow the original arena strings, and empty nodes in
250        // the consumed interval retain their value and span unchanged.
251        let mut replacements = std::vec::Vec::with_capacity(last - first + 3);
252        let prefix = &first_value[..first_offset];
253        if !prefix.is_empty() {
254            replacements.push(Node::Text(Text {
255                value: prefix,
256                span: first_span,
257            }));
258        }
259        if let Some(replacement) = replacement {
260            replacements.push(replacement);
261        }
262        if first < last {
263            for node in &nodes[first + 1..last] {
264                if let Node::Text(text) = node
265                    && text.value.is_empty()
266                {
267                    replacements.push(Node::Text(Text {
268                        value: text.value,
269                        span: text.span,
270                    }));
271                }
272            }
273        }
274        let suffix = &last_value[last_offset..];
275        if !suffix.is_empty() {
276            replacements.push(Node::Text(Text {
277                value: suffix,
278                span: last_span,
279            }));
280        }
281
282        drop(nodes.splice(first..last + 1, replacements));
283
284        Ok(replacement_span)
285    }
286
287    pub(crate) fn text_link_node(&self, label: &str, url: &str, span: Span) -> Node<'arena> {
288        let mut children = self.allocator.new_vec();
289        children.push(Node::Text(self.replacement_text(label, span)));
290        Node::Link(self.allocator.boxed(Link {
291            url: self.alloc_str(url),
292            title: None,
293            attributes: None,
294            children,
295            span,
296        }))
297    }
298}
299
300/// A maximal sequence of adjacent `Text` nodes in one sibling list.
301///
302/// Runs do not cross formatting nodes. A pass that wants context across
303/// emphasis or links must traverse those children in order and maintain its
304/// own context; it should still use these runs for matching within each child
305/// list. Non-text nodes are left to the caller's protected-content policy.
306pub struct TextRun<'nodes, 'arena> {
307    nodes: &'nodes [Node<'arena>],
308    node_range: Range<usize>,
309}
310
311impl<'nodes, 'arena> TextRun<'nodes, 'arena> {
312    /// The selected nodes' range within the sibling slice passed to [`text_runs`].
313    #[must_use]
314    pub fn node_range(&self) -> Range<usize> {
315        self.node_range.clone()
316    }
317
318    /// Returns each text value with the source span of its original node.
319    pub fn segments(&self) -> impl Iterator<Item = TextSegment<'arena>> + '_ {
320        self.nodes.iter().filter_map(|node| {
321            if let Node::Text(text) = node {
322                Some(TextSegment {
323                    value: text.value,
324                    span: text.span,
325                })
326            } else {
327                None
328            }
329        })
330    }
331
332    /// Finds protected URL ranges using the renderer options in `context`.
333    ///
334    /// Each original text segment is scanned independently, then its ranges
335    /// are offset into the coalesced run. This mirrors HTML rendering, where
336    /// autolinks do not cross AST text-node boundaries. If URL autolinking is
337    /// disabled or no prefixes are configured, this returns no ranges.
338    #[must_use]
339    pub fn protected_url_ranges(&self, context: &TransformContext<'_>) -> Vec<Range<usize>> {
340        let mut ranges = Vec::new();
341        let Some(matcher) = &context.autolink_matcher else {
342            return ranges;
343        };
344
345        let mut offset = 0;
346        for segment in self.segments() {
347            ranges.extend(
348                matcher
349                    .find_ranges(segment.value)
350                    .into_iter()
351                    .map(|range| range.start + offset..range.end + offset),
352            );
353            offset += segment.value.len();
354        }
355        ranges
356    }
357
358    /// Returns the coalesced text, borrowing for a one-node run.
359    #[must_use]
360    pub fn value(&self) -> Cow<'arena, str> {
361        if let [Node::Text(text)] = self.nodes {
362            return Cow::Borrowed(text.value);
363        }
364
365        let capacity = self.segments().map(|segment| segment.value.len()).sum();
366        let mut value = String::with_capacity(capacity);
367        for segment in self.segments() {
368            value.push_str(segment.value);
369        }
370        Cow::Owned(value)
371    }
372
373    /// Returns the bounding non-empty source span of all text in the run.
374    #[must_use]
375    pub fn source_span(&self) -> Span {
376        span_for_byte_range(self.nodes, &(0..self.nodes.len()), &self.value_range())
377    }
378
379    /// Returns the bounding source span of text touched by a byte range.
380    ///
381    /// Insertions (empty ranges) map to [`Span::empty`].
382    pub fn span_for_bytes(&self, range: Range<usize>) -> Result<Span, TextReplacementError> {
383        let value = self.value();
384        validate_byte_range(&value, &range)?;
385        Ok(span_for_byte_range(
386            self.nodes,
387            &(0..self.nodes.len()),
388            &range,
389        ))
390    }
391
392    fn value_range(&self) -> Range<usize> {
393        0..self.segments().map(|segment| segment.value.len()).sum()
394    }
395}
396
397/// One decoded text segment and the source range of its AST node.
398#[derive(Debug, Clone, Copy, PartialEq, Eq)]
399pub struct TextSegment<'arena> {
400    /// Decoded text value stored by Ferromark.
401    pub value: &'arena str,
402    /// Original source range for the complete AST text node.
403    pub span: Span,
404}
405
406/// Iterator over maximal adjacent text runs in a node slice.
407pub struct TextRuns<'nodes, 'arena> {
408    nodes: &'nodes [Node<'arena>],
409    cursor: usize,
410}
411
412impl<'nodes, 'arena> Iterator for TextRuns<'nodes, 'arena> {
413    type Item = TextRun<'nodes, 'arena>;
414
415    fn next(&mut self) -> Option<Self::Item> {
416        while self.cursor < self.nodes.len() && !matches!(self.nodes[self.cursor], Node::Text(_)) {
417            self.cursor += 1;
418        }
419        if self.cursor == self.nodes.len() {
420            return None;
421        }
422
423        let start = self.cursor;
424        while self.cursor < self.nodes.len() && matches!(self.nodes[self.cursor], Node::Text(_)) {
425            self.cursor += 1;
426        }
427
428        Some(TextRun {
429            nodes: &self.nodes[start..self.cursor],
430            node_range: start..self.cursor,
431        })
432    }
433}
434
435/// Iterates over maximal adjacent `Text` runs in one sibling list.
436#[must_use]
437pub fn text_runs<'nodes, 'arena>(nodes: &'nodes [Node<'arena>]) -> TextRuns<'nodes, 'arena> {
438    TextRuns { nodes, cursor: 0 }
439}
440
441/// Error returned when a pass replaces an invalid node or text range.
442#[derive(Debug, Clone, PartialEq, Eq)]
443#[non_exhaustive]
444pub enum TextReplacementError {
445    /// The requested range does not select a non-empty slice of nodes.
446    InvalidNodeRange {
447        /// Requested start index.
448        start: usize,
449        /// Requested exclusive end index.
450        end: usize,
451        /// Number of nodes in the sibling slice.
452        node_count: usize,
453    },
454    /// The selected slice includes a node that is not text.
455    NonTextNode {
456        /// Index of the node relative to the sibling slice.
457        index: usize,
458    },
459    /// The byte range starts after its end.
460    ReversedByteRange {
461        /// Requested start byte.
462        start: usize,
463        /// Requested exclusive end byte.
464        end: usize,
465    },
466    /// The byte range extends beyond the coalesced text.
467    ByteRangeOutOfBounds {
468        /// Requested exclusive end byte.
469        end: usize,
470        /// Coalesced text length in bytes.
471        text_len: usize,
472    },
473    /// A byte offset splits a UTF-8 code point.
474    NotCharBoundary {
475        /// Invalid byte offset.
476        offset: usize,
477    },
478}
479
480impl fmt::Display for TextReplacementError {
481    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
482        match self {
483            Self::InvalidNodeRange {
484                start,
485                end,
486                node_count,
487            } => write!(
488                formatter,
489                "text node range {start}..{end} is invalid for {node_count} nodes"
490            ),
491            Self::NonTextNode { index } => {
492                write!(formatter, "node {index} in the selected range is not text")
493            }
494            Self::ReversedByteRange { start, end } => {
495                write!(formatter, "text byte range {start}..{end} is reversed")
496            }
497            Self::ByteRangeOutOfBounds { end, text_len } => write!(
498                formatter,
499                "text byte range ends at {end}, past the {text_len}-byte value"
500            ),
501            Self::NotCharBoundary { offset } => {
502                write!(
503                    formatter,
504                    "text byte offset {offset} is not a UTF-8 boundary"
505                )
506            }
507        }
508    }
509}
510
511impl Error for TextReplacementError {}
512
513fn validate_node_range(
514    nodes: &[Node<'_>],
515    range: &Range<usize>,
516) -> Result<(), TextReplacementError> {
517    if range.start >= range.end || range.end > nodes.len() {
518        return Err(TextReplacementError::InvalidNodeRange {
519            start: range.start,
520            end: range.end,
521            node_count: nodes.len(),
522        });
523    }
524    for (index, node) in nodes.iter().enumerate().take(range.end).skip(range.start) {
525        if !matches!(node, Node::Text(_)) {
526            return Err(TextReplacementError::NonTextNode { index });
527        }
528    }
529    Ok(())
530}
531
532fn validate_text_byte_range(
533    nodes: &[Node<'_>],
534    node_range: &Range<usize>,
535    byte_range: &Range<usize>,
536) -> Result<(), TextReplacementError> {
537    if byte_range.start > byte_range.end {
538        return Err(TextReplacementError::ReversedByteRange {
539            start: byte_range.start,
540            end: byte_range.end,
541        });
542    }
543
544    let text_len = text_len_in_range(nodes, node_range);
545    if byte_range.end > text_len {
546        return Err(TextReplacementError::ByteRangeOutOfBounds {
547            end: byte_range.end,
548            text_len,
549        });
550    }
551
552    for offset in [byte_range.start, byte_range.end] {
553        if !is_text_char_boundary(nodes, node_range, offset) {
554            return Err(TextReplacementError::NotCharBoundary { offset });
555        }
556    }
557    Ok(())
558}
559
560fn text_len_in_range(nodes: &[Node<'_>], node_range: &Range<usize>) -> usize {
561    nodes[node_range.clone()]
562        .iter()
563        .map(|node| match node {
564            Node::Text(text) => text.value.len(),
565            _ => 0,
566        })
567        .sum()
568}
569
570fn is_text_char_boundary(nodes: &[Node<'_>], node_range: &Range<usize>, offset: usize) -> bool {
571    let mut cursor = 0;
572    for node in &nodes[node_range.clone()] {
573        let Node::Text(text) = node else {
574            return false;
575        };
576        let end = cursor + text.value.len();
577        if offset <= end {
578            return text.value.is_char_boundary(offset - cursor);
579        }
580        cursor = end;
581    }
582    offset == cursor
583}
584
585fn overlapping_text_nodes(
586    nodes: &[Node<'_>],
587    node_range: &Range<usize>,
588    byte_range: &Range<usize>,
589) -> Result<(usize, usize, usize, usize), TextReplacementError> {
590    let mut cursor = 0;
591    let mut first = None;
592    let mut last = None;
593    let mut first_offset = 0;
594    let mut last_offset = 0;
595
596    for index in node_range.clone() {
597        let Node::Text(text) = &nodes[index] else {
598            continue;
599        };
600        let end = cursor + text.value.len();
601        if cursor < byte_range.end && end > byte_range.start {
602            if first.is_none() {
603                first = Some(index);
604                first_offset = byte_range.start - cursor;
605            }
606            last = Some(index);
607            last_offset = byte_range.end.min(end) - cursor;
608        }
609        cursor = end;
610    }
611
612    let Some(first) = first else {
613        return Err(TextReplacementError::ByteRangeOutOfBounds {
614            end: byte_range.end,
615            text_len: text_len_in_range(nodes, node_range),
616        });
617    };
618    let Some(last) = last else {
619        return Err(TextReplacementError::ByteRangeOutOfBounds {
620            end: byte_range.end,
621            text_len: text_len_in_range(nodes, node_range),
622        });
623    };
624    Ok((first, last, first_offset, last_offset))
625}
626
627fn insert_node_at_text_offset<'arena>(
628    nodes: &mut ferromark::allocator::Vec<'arena, Node<'arena>>,
629    node_range: &Range<usize>,
630    offset: usize,
631    inserted: Node<'arena>,
632) {
633    let text_len = text_len_in_range(nodes, node_range);
634    if offset == 0 {
635        drop(nodes.splice(
636            node_range.start..node_range.start,
637            std::iter::once(inserted),
638        ));
639        return;
640    }
641    if offset == text_len {
642        drop(nodes.splice(node_range.end..node_range.end, std::iter::once(inserted)));
643        return;
644    }
645
646    let mut cursor = 0;
647    for index in node_range.clone() {
648        let Node::Text(text) = &nodes[index] else {
649            continue;
650        };
651        let end = cursor + text.value.len();
652        if cursor < offset && offset < end {
653            let (prefix, suffix, span) = (
654                &text.value[..offset - cursor],
655                &text.value[offset - cursor..],
656                text.span,
657            );
658            let parts = [
659                Some(Node::Text(Text {
660                    value: prefix,
661                    span,
662                })),
663                Some(inserted),
664                Some(Node::Text(Text {
665                    value: suffix,
666                    span,
667                })),
668            ];
669            drop(nodes.splice(index..index + 1, parts.into_iter().flatten()));
670            return;
671        }
672        cursor = end;
673        if cursor == offset {
674            drop(nodes.splice(index + 1..index + 1, std::iter::once(inserted)));
675            return;
676        }
677    }
678
679    // Byte-range validation guarantees a boundary in the selected text run.
680    // The run-end case is handled above, so this fallback inserts at its end.
681    drop(nodes.splice(node_range.end..node_range.end, std::iter::once(inserted)));
682}
683
684fn validate_byte_range(value: &str, range: &Range<usize>) -> Result<(), TextReplacementError> {
685    if range.start > range.end {
686        return Err(TextReplacementError::ReversedByteRange {
687            start: range.start,
688            end: range.end,
689        });
690    }
691    if range.end > value.len() {
692        return Err(TextReplacementError::ByteRangeOutOfBounds {
693            end: range.end,
694            text_len: value.len(),
695        });
696    }
697    for offset in [range.start, range.end] {
698        if !value.is_char_boundary(offset) {
699            return Err(TextReplacementError::NotCharBoundary { offset });
700        }
701    }
702    Ok(())
703}
704
705fn span_for_byte_range(
706    nodes: &[Node<'_>],
707    node_range: &Range<usize>,
708    byte_range: &Range<usize>,
709) -> Span {
710    if byte_range.is_empty() {
711        return Span::empty();
712    }
713
714    let mut byte_cursor = 0;
715    let mut span = None;
716    for node in nodes.iter().take(node_range.end).skip(node_range.start) {
717        if let Node::Text(text) = node {
718            let segment_end = byte_cursor + text.value.len();
719            if byte_cursor < byte_range.end
720                && segment_end > byte_range.start
721                && !text.span.is_empty()
722            {
723                span = Some(span.map_or(text.span, |current: Span| current.merge(text.span)));
724            }
725            byte_cursor = segment_end;
726        }
727    }
728    span.unwrap_or_else(Span::empty)
729}
730
731/// Error from a pass, including its ordered identity in the pipeline.
732#[derive(Debug)]
733pub struct TransformError {
734    pass_index: usize,
735    pass_name: &'static str,
736    source: BoxError,
737}
738
739impl TransformError {
740    /// Returns this pass's zero-based position in the pipeline.
741    #[must_use]
742    pub const fn pass_index(&self) -> usize {
743        self.pass_index
744    }
745
746    /// Returns the stable name of the failing pass.
747    #[must_use]
748    pub const fn pass_name(&self) -> &'static str {
749        self.pass_name
750    }
751}
752
753impl fmt::Display for TransformError {
754    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
755        write!(
756            formatter,
757            "transform pass {} ({:?}) failed: {}",
758            self.pass_index, self.pass_name, self.source
759        )
760    }
761}
762
763impl Error for TransformError {
764    fn source(&self) -> Option<&(dyn Error + 'static)> {
765        Some(&*self.source)
766    }
767}