noyalib 0.0.56

// SPDX-License-Identifier: MIT OR Apache-2.0
// Copyright (c) 2026 Noyalib. All rights reserved.

//! Comment capture on the parse path.
//!
//! YAML comments are outside the data model — the standard parser
//! drops them silently. This module exposes a *capture* API so tools
//! that need to preserve human-authored context (migration scripts,
//! config linters, documentation generators) can read comments out
//! of a source document alongside the parsed `Value`.
//!
//! # Scope
//!
//! This is the MVP: capture-only. The functions here return a
//! read-only `Vec<Comment>` with source spans and a crude classifier
//! ([`CommentKind::Line`] vs [`CommentKind::Inline`]) you can cross-
//! reference against [`Spanned<T>`](crate::Spanned) to associate
//! comments with specific fields.
//!
//! # Not (yet) in scope
//!
//! Emit-time round-tripping — i.e. parsing a YAML document with
//! comments into `Value`, then re-serialising it with the comments
//! back in the right places — is a separate, larger undertaking and
//! is tracked as a follow-up. The building blocks are here: the
//! scanner now preserves comment spans, so a future commit can layer
//! an AST side-table on top without re-plumbing the parser.
//!
//! # Examples
//!
//! ```
//! use noyalib::{load_comments, CommentKind};
//!
//! let yaml = "# top-of-file header\nname: noyalib  # inline\nversion: 0.0.1\n";
//! let comments = load_comments(yaml).unwrap();
//!
//! assert_eq!(comments.len(), 2);
//! assert_eq!(comments[0].kind, CommentKind::Line);
//! assert!(comments[0].text.contains("top-of-file"));
//! assert_eq!(comments[1].kind, CommentKind::Inline);
//! assert!(comments[1].text.contains("inline"));
//! ```

use crate::error::{Error, Result};
use crate::parser::Parser;
use crate::prelude::*;

/// Classification of a scanned comment.
///
/// # Examples
///
/// ```
/// use noyalib::CommentKind;
/// let k = CommentKind::Inline;
/// assert_eq!(k, CommentKind::Inline);
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum CommentKind {
    /// A standalone comment occupying its own line (possibly indented).
    ///
    /// # Examples
    ///
    /// ```
    /// use noyalib::CommentKind;
    /// let _ = CommentKind::Line;
    /// ```
    Line,

    /// A comment trailing content on the same line, e.g.
    /// `key: value  # note`.
    ///
    /// # Examples
    ///
    /// ```
    /// use noyalib::CommentKind;
    /// let _ = CommentKind::Inline;
    /// ```
    Inline,
}

/// A scanned YAML comment with its source span and classification.
///
/// `start` and `end` are byte offsets into the original input. The
/// range points at the `#` through the character before the line
/// break (or end of input).
///
/// # Examples
///
/// ```
/// use noyalib::load_comments;
/// let comments = load_comments("# hi\n").unwrap();
/// assert_eq!(comments[0].text, " hi");
/// assert_eq!(comments[0].start, 0);
/// ```
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Comment {
    /// Text of the comment excluding the leading `#`.
    ///
    /// Leading whitespace between the `#` and the comment body is
    /// preserved so callers can reconstruct exact formatting.
    ///
    /// # Examples
    ///
    /// ```
    /// use noyalib::load_comments;
    /// let c = &load_comments("# hello\n").unwrap()[0];
    /// assert_eq!(c.text, " hello");
    /// ```
    pub text: String,

    /// Byte offset of the leading `#` in the source.
    ///
    /// # Examples
    ///
    /// ```
    /// use noyalib::load_comments;
    /// let c = &load_comments("k: 1  # x\n").unwrap()[0];
    /// assert_eq!(c.start, 6);
    /// ```
    pub start: usize,

    /// Byte offset one past the last byte of the comment text.
    ///
    /// # Examples
    ///
    /// ```
    /// use noyalib::load_comments;
    /// let c = &load_comments("# x\n").unwrap()[0];
    /// assert_eq!(c.end, 3);
    /// ```
    pub end: usize,

    /// Classification: line-level or inline-trailing.
    ///
    /// # Examples
    ///
    /// ```
    /// use noyalib::{load_comments, CommentKind};
    /// let cs = load_comments("# hi\nk: 1  # inl\n").unwrap();
    /// assert_eq!(cs[0].kind, CommentKind::Line);
    /// assert_eq!(cs[1].kind, CommentKind::Inline);
    /// ```
    pub kind: CommentKind,
}

/// Scan a YAML document and return the list of comments it contains.
///
/// The source is driven through the event parser so the returned
/// positions stay consistent with the spans on [`Spanned<T>`](crate::Spanned).
/// Comments are returned in source order.
///
/// The input is held to the default [`ParserConfig`](crate::ParserConfig)
/// limits a value parse would apply: at most `max_document_length`
/// bytes, and a pending key may hold back no more tokens than
/// `max_events` allows.
///
/// # Errors
///
/// Returns an error if the input is longer than the default
/// `max_document_length`, if a pending key holds back more tokens than
/// the default `max_events` allows, or if the input is not a lexically
/// valid YAML document — e.g. an unclosed flow collection. Comments inside an
/// otherwise-well-formed document are captured even if deeper parse
/// stages (e.g. merge resolution) would later fail.
///
/// # Examples
///
/// ```
/// use noyalib::{load_comments, CommentKind};
/// let yaml = "name: noyalib  # the library\n# trailing\n";
/// let comments = load_comments(yaml).unwrap();
/// assert_eq!(comments.len(), 2);
/// assert_eq!(comments[0].kind, CommentKind::Inline);
/// assert_eq!(comments[1].kind, CommentKind::Line);
/// ```
pub fn load_comments(input: &str) -> Result<Vec<Comment>> {
    let limits = crate::ParserConfig::default();
    if input.len() > limits.max_document_length {
        return Err(Error::Parse(format!(
            "document exceeds maximum length of {} bytes",
            limits.max_document_length
        )));
    }
    let mut parser = Parser::with_max_events(input, limits.max_events);
    parser.enable_comment_capture();
    // Drain events — we don't care about the tree, just need the
    // scanner to walk the whole document so every comment gets
    // captured.
    loop {
        match parser.next_event() {
            Ok(ev) => {
                if matches!(ev, crate::parser::Event::StreamEnd) {
                    break;
                }
            }
            Err(e) => return Err(e.into_error(input, limits.max_events)),
        }
    }
    Ok(parser.take_comments())
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn an_oversized_input_is_refused_like_a_value_parse() {
        let limit = crate::ParserConfig::default().max_document_length;
        let input = format!("# c\n{}", "a".repeat(limit));
        let err = load_comments(&input).unwrap_err().to_string();
        assert!(err.contains("maximum length"), "{err}");
    }

    #[test]
    fn empty_document_has_no_comments() {
        assert_eq!(load_comments("").unwrap(), vec![]);
        assert_eq!(load_comments("k: 1\n").unwrap(), vec![]);
    }

    #[test]
    fn single_line_comment() {
        let cs = load_comments("# hello\n").unwrap();
        assert_eq!(cs.len(), 1);
        assert_eq!(cs[0].text, " hello");
        assert_eq!(cs[0].kind, CommentKind::Line);
        assert_eq!(cs[0].start, 0);
        assert_eq!(cs[0].end, 7);
    }

    #[test]
    fn inline_comment_classification() {
        let cs = load_comments("k: 1  # trailing\n").unwrap();
        assert_eq!(cs.len(), 1);
        assert_eq!(cs[0].kind, CommentKind::Inline);
        assert!(cs[0].text.contains("trailing"));
    }

    #[test]
    fn mixed_leading_and_inline() {
        let yaml = "# top\nk: 1  # tail\n# bottom\n";
        let cs = load_comments(yaml).unwrap();
        assert_eq!(cs.len(), 3);
        assert_eq!(cs[0].kind, CommentKind::Line);
        assert_eq!(cs[1].kind, CommentKind::Inline);
        assert_eq!(cs[2].kind, CommentKind::Line);
    }

    #[test]
    fn indented_line_comment_is_still_line() {
        // A comment indented by spaces on an otherwise-empty line
        // should classify as Line (no preceding content on this line).
        let cs = load_comments("k:\n  # indented\n  v: 1\n").unwrap();
        assert!(!cs.is_empty(), "expected a non-empty value");
        assert_eq!(cs[0].kind, CommentKind::Line);
    }

    #[test]
    fn source_order_preserved() {
        let yaml = "# a\n# b\n# c\n";
        let cs = load_comments(yaml).unwrap();
        assert_eq!(cs.len(), 3);
        assert!(cs[0].start < cs[1].start);
        assert!(cs[1].start < cs[2].start);
    }
}