rlsp-yaml-parser 0.11.1

// SPDX-License-Identifier: MIT

use std::iter::Peekable;

use crate::error::Error;
use crate::event::Event;
use crate::pos::{LineIndex, Span};

use super::{LoadError, Result};

#[expect(
    clippy::inline_always,
    reason = "rustc declined #[inline] for this 3-line allocating helper; #[inline(always)] forces inlining at 4 call sites with minimal code-size impact"
)]
#[inline(always)]
pub(super) fn with_hash_prefix(text: &str) -> String {
    let mut s = String::with_capacity(text.len() + 1);
    s.push('#');
    s.push_str(text);
    s
}

type EventStream<'a> =
    Peekable<Box<dyn Iterator<Item = std::result::Result<(Event<'a>, Span), Error>> + 'a>>;

/// Pull the next event from the stream, converting parse errors to `LoadError`.
#[inline]
pub(super) fn next_from<'a>(stream: &mut EventStream<'a>) -> Result<Option<(Event<'a>, Span)>> {
    match stream.next() {
        None => Ok(None),
        Some(Ok(item)) => Ok(Some(item)),
        Some(Err(e)) => Err(LoadError::Parse {
            pos: e.pos,
            message: e.message,
            kind: e.kind,
        }),
    }
}

/// Consume leading block-level Comment events at document level, appending
/// them to `doc_comments`.  Stops at the first non-Comment event.
///
/// Block-level comments have `span.end` on a different line than `span.start`.
pub(super) fn consume_leading_doc_comments(
    stream: &mut EventStream<'_>,
    doc_comments: &mut Vec<String>,
    line_index: &LineIndex,
) -> Result<()> {
    while matches!(stream.peek(), Some(Ok((Event::Comment { .. }, _)))) {
        if let Some((Event::Comment { text }, span)) = next_from(stream)? {
            let start_line = line_index.line_column(span.start).0;
            let end_line = line_index.line_column(span.end).0;
            if end_line > start_line {
                doc_comments.push(with_hash_prefix(text));
            }
        }
    }
    Ok(())
}

/// Consume leading block-level Comment events before a collection item or
/// mapping key.  Returns the captured comment texts.
///
/// A "leading" comment is any `Comment` event that appears before the next
/// non-comment structural event.  By the time this function is called,
/// `peek_trailing_comment` has already consumed any trailing comment that was
/// on the same line as the preceding value — so every remaining `Comment` here
/// is on its own line and belongs to the upcoming key/item as a leading comment.
#[expect(
    clippy::inline_always,
    reason = "#[inline] was declined by rustc for this wrapper (confirmed via LLVM IR); #[inline(always)] forces inlining of the tiny peek+branch fast path at its 2 call sites"
)]
#[inline(always)]
pub(super) fn consume_leading_comments(stream: &mut EventStream<'_>) -> Result<Vec<String>> {
    if !matches!(stream.peek(), Some(Ok((Event::Comment { .. }, _)))) {
        return Ok(Vec::new());
    }
    consume_leading_comments_slow(stream)
}

fn consume_leading_comments_slow(stream: &mut EventStream<'_>) -> Result<Vec<String>> {
    let mut leading = Vec::new();
    while matches!(stream.peek(), Some(Ok((Event::Comment { .. }, _)))) {
        if let Some((Event::Comment { text }, _)) = next_from(stream)? {
            leading.push(with_hash_prefix(text));
        }
    }
    Ok(leading)
}

/// If the next event is a trailing Comment on the same line as `preceding_end_line`,
/// consume it and return the text.  Otherwise return `None`.
///
/// libfyaml (`fy_attach_comments_if_any` in `fy-parse.c`) uses the same
/// criterion: a comment is "trailing" when its line equals the preceding
/// token's end line.  Line resolution is performed via `line_index`.
pub(super) fn peek_trailing_comment(
    stream: &mut EventStream<'_>,
    preceding_end_line: u32,
    line_index: &LineIndex,
) -> Result<Option<String>> {
    if let Some(Ok((Event::Comment { .. }, span))) = stream.peek() {
        let comment_line = line_index.line_column(span.start).0;
        if comment_line == preceding_end_line {
            if let Some((Event::Comment { text }, _)) = next_from(stream)? {
                return Ok(Some(with_hash_prefix(text)));
            }
        }
    }
    Ok(None)
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::error::Error;
    use crate::event::{Event, ScalarStyle};
    use crate::pos::{LineIndex, Pos, Span};

    fn make_stream<'a>(
        items: Vec<std::result::Result<(Event<'a>, Span), Error>>,
    ) -> EventStream<'a> {
        let boxed: Box<dyn Iterator<Item = _> + 'a> = Box::new(items.into_iter());
        boxed.peekable()
    }

    /// Build a zero-width span at byte offset 0. Suitable for events whose
    /// span position does not matter for the test being exercised.
    fn span(_start_line: usize, _end_line: usize) -> Span {
        Span { start: 0, end: 0 }
    }

    /// A `LineIndex` for a 5-line source, used in tests that check line-number comparisons.
    /// Source: "a\nb\nc\nd\ne\nf\ng\n" (8 lines, newlines at bytes 1,3,5,7,9,11,13).
    fn multi_line_index() -> LineIndex {
        LineIndex::new("a\nb\nc\nd\ne\nf\ng\n")
    }

    /// Span whose start and end are on the same line (both on line 6 = byte 10..11).
    fn inline_span() -> Span {
        // Line 6 starts at byte 10 ("f\n"). Start at 10, end at 11 (the \n) — same line 6.
        Span { start: 10, end: 11 }
    }

    /// Span whose start is on line 5 (byte 8) and end is on line 6 (byte 10).
    fn block_span() -> Span {
        Span { start: 8, end: 10 }
    }

    fn pos(line: usize) -> Pos {
        Pos {
            byte_offset: 0,
            line,
            column: 0,
        }
    }

    // -----------------------------------------------------------------------
    // next_from
    // -----------------------------------------------------------------------

    #[test]
    fn next_from_on_empty_stream_returns_ok_none() {
        let mut stream = make_stream(vec![]);
        assert_eq!(next_from(&mut stream), Ok(None));
    }

    #[test]
    fn next_from_forwards_ok_event() {
        let sp = span(1, 1);
        let mut stream = make_stream(vec![Ok((Event::StreamStart, sp))]);
        let result = next_from(&mut stream);
        assert_eq!(result, Ok(Some((Event::StreamStart, sp))));
    }

    #[test]
    fn next_from_propagates_parse_error_as_load_error() {
        let p = pos(3);
        let err = Error::syntax(p, "unexpected token".to_string());
        let mut stream = make_stream(vec![Err(err)]);
        let result = next_from(&mut stream);
        assert_eq!(
            result,
            Err(LoadError::Parse {
                pos: p,
                message: "unexpected token".to_string(),
                kind: crate::error::ErrorKind::Syntax,
            })
        );
    }

    // -----------------------------------------------------------------------
    // consume_leading_doc_comments
    // -----------------------------------------------------------------------

    #[test]
    fn consume_leading_doc_comments_empty_when_first_event_is_not_comment() {
        let sp = span(1, 1);
        let idx = multi_line_index();
        let mut stream = make_stream(vec![Ok((Event::StreamStart, sp))]);
        let mut doc_comments: Vec<String> = Vec::new();
        let result = consume_leading_doc_comments(&mut stream, &mut doc_comments, &idx);
        assert_eq!(result, Ok(()));
        assert!(doc_comments.is_empty());
        // stream not consumed — StreamStart still peeked
        assert!(stream.peek().is_some());
    }

    #[test]
    fn consume_leading_doc_comments_accumulates_block_comments() {
        // block-level: end byte on a later line than start byte
        let sp = block_span(); // start line 5, end line 6
        let trailing_sp = span(3, 3);
        let idx = multi_line_index();
        let mut stream = make_stream(vec![
            Ok((Event::Comment { text: " note" }, sp)),
            Ok((Event::Comment { text: " note" }, sp)),
            Ok((Event::StreamStart, trailing_sp)),
        ]);
        let mut doc_comments: Vec<String> = Vec::new();
        assert_eq!(
            consume_leading_doc_comments(&mut stream, &mut doc_comments, &idx),
            Ok(())
        );
        assert_eq!(doc_comments, vec!["# note", "# note"]);
        // non-comment event still peeked
        assert!(matches!(stream.peek(), Some(Ok((Event::StreamStart, _)))));
    }

    #[test]
    fn consume_leading_doc_comments_skips_single_line_comment() {
        // inline: start and end on the same line
        let inline_sp = inline_span();
        let trailing_sp = span(2, 2);
        let idx = multi_line_index();
        let mut stream = make_stream(vec![
            Ok((Event::Comment { text: " inline" }, inline_sp)),
            Ok((Event::StreamStart, trailing_sp)),
        ]);
        let mut doc_comments: Vec<String> = Vec::new();
        assert_eq!(
            consume_leading_doc_comments(&mut stream, &mut doc_comments, &idx),
            Ok(())
        );
        assert!(doc_comments.is_empty());
        // non-comment still peeked
        assert!(matches!(stream.peek(), Some(Ok((Event::StreamStart, _)))));
    }

    // -----------------------------------------------------------------------
    // consume_leading_comments — fast path (new split behavior)
    // -----------------------------------------------------------------------

    #[test]
    fn consume_leading_comments_returns_empty_vec_on_empty_stream() {
        let mut stream = make_stream(vec![]);
        let result = consume_leading_comments(&mut stream);
        assert_eq!(result, Ok(vec![]));
        assert!(stream.peek().is_none());
    }

    #[test]
    fn consume_leading_comments_returns_empty_vec_when_next_is_stream_start() {
        let sp = span(1, 1);
        let mut stream = make_stream(vec![Ok((Event::StreamStart, sp))]);
        let result = consume_leading_comments(&mut stream);
        assert_eq!(result, Ok(vec![]));
        // fast path must not consume the non-Comment event
        assert!(matches!(stream.peek(), Some(Ok((Event::StreamStart, _)))));
    }

    #[test]
    fn consume_leading_comments_returns_empty_vec_when_next_is_scalar() {
        let sp = span(1, 1);
        let mut stream = make_stream(vec![Ok((
            Event::Scalar {
                value: "x".into(),
                style: ScalarStyle::Plain,
                meta: None,
            },
            sp,
        ))]);
        let result = consume_leading_comments(&mut stream);
        assert_eq!(result, Ok(vec![]));
        assert!(stream.peek().is_some());
    }

    #[test]
    fn consume_leading_comments_returns_empty_vec_when_next_is_error_event() {
        let p = pos(1);
        let err = Error::syntax(p, "bad".to_string());
        let mut stream = make_stream(vec![Err(err)]);
        let result = consume_leading_comments(&mut stream);
        assert_eq!(result, Ok(vec![]));
        // error event must not be consumed by the fast-path wrapper
        assert!(stream.peek().is_some());
    }

    // -----------------------------------------------------------------------
    // consume_leading_comments — slow path delegation
    // -----------------------------------------------------------------------

    #[test]
    fn consume_leading_comments_returns_empty_vec_when_first_event_is_not_comment() {
        let sp = span(1, 1);
        let mut stream = make_stream(vec![Ok((Event::StreamStart, sp))]);
        let result = consume_leading_comments(&mut stream);
        assert_eq!(result, Ok(vec![]));
        // stream untouched
        assert!(stream.peek().is_some());
    }

    #[test]
    fn consume_leading_comments_single_comment_delegated_to_slow_path() {
        let sp = span(1, 1);
        let trailing_sp = span(2, 2);
        let mut stream = make_stream(vec![
            Ok((Event::Comment { text: " hi" }, sp)),
            Ok((Event::StreamStart, trailing_sp)),
        ]);
        let result = consume_leading_comments(&mut stream);
        assert_eq!(result, Ok(vec!["# hi".to_string()]));
        assert!(matches!(stream.peek(), Some(Ok((Event::StreamStart, _)))));
    }

    #[test]
    fn consume_leading_comments_accumulates_all_comment_events() {
        let sp = span(1, 1);
        let trailing_sp = span(2, 2);
        let mut stream = make_stream(vec![
            Ok((Event::Comment { text: " a" }, sp)),
            Ok((Event::Comment { text: " b" }, sp)),
            Ok((Event::StreamStart, trailing_sp)),
        ]);
        let result = consume_leading_comments(&mut stream);
        assert_eq!(result, Ok(vec!["# a".to_string(), "# b".to_string()]));
        // non-comment still peeked
        assert!(matches!(stream.peek(), Some(Ok((Event::StreamStart, _)))));
    }

    #[test]
    fn consume_leading_comments_multiple_consecutive_comments_all_consumed() {
        let sp = span(1, 1);
        let trailing_sp = span(4, 4);
        let mut stream = make_stream(vec![
            Ok((Event::Comment { text: " a" }, sp)),
            Ok((Event::Comment { text: " b" }, sp)),
            Ok((Event::Comment { text: " c" }, sp)),
            Ok((Event::StreamStart, trailing_sp)),
        ]);
        let result = consume_leading_comments(&mut stream);
        assert_eq!(
            result,
            Ok(vec![
                "# a".to_string(),
                "# b".to_string(),
                "# c".to_string()
            ])
        );
        assert!(matches!(stream.peek(), Some(Ok((Event::StreamStart, _)))));
    }

    #[test]
    fn consume_leading_comments_drains_all_consecutive_comments() {
        let sp = span(1, 1);
        let mut stream = make_stream(vec![
            Ok((Event::Comment { text: " x" }, sp)),
            Ok((Event::Comment { text: " y" }, sp)),
            Ok((Event::Comment { text: " z" }, sp)),
        ]);
        let result = consume_leading_comments(&mut stream);
        assert_eq!(
            result,
            Ok(vec![
                "# x".to_string(),
                "# y".to_string(),
                "# z".to_string()
            ])
        );
        // stream now empty
        assert!(stream.peek().is_none());
    }

    #[test]
    fn consume_leading_comments_stops_after_last_comment_leaves_non_comment_unconsumed() {
        let sp = span(1, 1);
        let mut stream = make_stream(vec![Ok((Event::Comment { text: " only" }, sp))]);
        let result = consume_leading_comments(&mut stream);
        assert_eq!(result, Ok(vec!["# only".to_string()]));
        assert!(stream.peek().is_none());
    }

    #[test]
    fn consume_leading_comments_stops_before_error_event_in_stream() {
        let sp = span(1, 1);
        let p = pos(2);
        let err = Error::syntax(p, "oops".to_string());
        let mut stream = make_stream(vec![Ok((Event::Comment { text: " ok" }, sp)), Err(err)]);
        let result = consume_leading_comments(&mut stream);
        assert_eq!(result, Ok(vec!["# ok".to_string()]));
        // Err left unconsumed for the caller
        assert!(stream.peek().is_some());
    }

    // -----------------------------------------------------------------------
    // peek_trailing_comment
    // -----------------------------------------------------------------------

    #[test]
    fn peek_trailing_comment_returns_none_when_next_is_not_comment() {
        let sp = span(1, 1);
        let idx = multi_line_index();
        let mut stream = make_stream(vec![Ok((Event::StreamStart, sp))]);
        let result = peek_trailing_comment(&mut stream, 1, &idx);
        assert_eq!(result, Ok(None));
        // stream untouched
        assert!(stream.peek().is_some());
    }

    #[test]
    fn peek_trailing_comment_returns_none_when_stream_empty() {
        let idx = multi_line_index();
        let mut stream = make_stream(vec![]);
        let result = peek_trailing_comment(&mut stream, 1, &idx);
        assert_eq!(result, Ok(None));
    }

    #[test]
    fn peek_trailing_comment_returns_some_when_comment_on_same_line() {
        // comment span.start is on line 6 (byte 10 in "a\nb\nc\nd\ne\nf\ng\n")
        // preceding_end_line = 6 → same line → consumed
        let sp = Span { start: 10, end: 12 };
        let idx = multi_line_index();
        let mut stream = make_stream(vec![Ok((Event::Comment { text: " text" }, sp))]);
        let preceding_line = idx.line_column(sp.start).0;
        let result = peek_trailing_comment(&mut stream, preceding_line, &idx);
        assert_eq!(result, Ok(Some("# text".to_string())));
        // stream advanced — comment consumed
        assert!(stream.peek().is_none());
    }

    #[test]
    fn peek_trailing_comment_returns_none_when_comment_on_later_line() {
        // comment span.start is on line 6 (byte 10), preceding_end_line = 5
        let sp = Span { start: 10, end: 12 };
        let idx = multi_line_index();
        let mut stream = make_stream(vec![Ok((Event::Comment { text: " later" }, sp))]);
        let result = peek_trailing_comment(&mut stream, 5, &idx);
        assert_eq!(result, Ok(None));
        // stream NOT consumed
        assert!(stream.peek().is_some());
    }

    // -----------------------------------------------------------------------
    // with_hash_prefix — behavior unchanged after #[inline(always)]
    // -----------------------------------------------------------------------

    #[test]
    fn with_hash_prefix_prepends_hash_to_empty_str() {
        assert_eq!(with_hash_prefix(""), "#");
    }

    #[test]
    fn with_hash_prefix_prepends_hash_to_nonempty_text() {
        assert_eq!(with_hash_prefix(" comment text"), "# comment text");
    }

    #[test]
    fn with_hash_prefix_preserves_inner_hashes() {
        assert_eq!(with_hash_prefix(" foo # bar"), "# foo # bar");
    }
}