yaml-edit 0.3.2

//! Block-style parsing: block mappings (`k: v` on separate lines),
//! block sequences (`- item`), explicit-key mappings (`? key\n: val`),
//! and complex-key mappings (flow collections used as keys).
//!
//! Split out of `parser/mod.rs` unchanged.

use super::scalars::is_plain_scalar_kind;
use super::Parser;
use crate::error_recovery::ParseContext;
use crate::lex::SyntaxKind;
use crate::ParseErrorKind;

impl Parser {
    /// Consume comment lines sitting between entries of a block collection.
    ///
    /// Returns true when the comments ran into a dedent, meaning the
    /// collection has ended and the caller should stop.
    ///
    /// At root level (`base_indent == 0`) every comment belongs to this
    /// collection, indented or not, because there is no enclosing scope.
    fn absorb_entry_comments(&mut self, base_indent: usize) -> bool {
        while self.current() == Some(SyntaxKind::COMMENT) {
            // A comment on its own line says nothing about the block by its
            // own column: what ends the block is the next line with content,
            // so `a:\n  - x\n# c\n  - y\n` keeps both entries. Stop only
            // when that line really is dedented. A comment with no content
            // after it, and a trailing comment on an entry's own line, keep
            // the old reading, which leaves them inside this block.
            let dedented = match self.indent_after_comment_lines() {
                Some(indent) => indent < base_indent,
                None => self.is_at_dedented_position(base_indent),
            };
            if base_indent > 0 && dedented {
                return true;
            }
            self.bump();
            if self.current() == Some(SyntaxKind::NEWLINE) {
                self.bump();
            }
            if self.skip_whitespace_only_with_dedent_check(base_indent) {
                return true;
            }
        }
        false
    }

    pub(super) fn parse_mapping_with_base_indent(&mut self, base_indent: usize) {
        // Entries inside a mapping are bounded by their key's column, which
        // is not always the column the caller measured from: a document
        // indented as a whole keeps its leading INDENT outside DOCUMENT, so
        // the caller still says 0 and every line looks nested. Take the
        // first key's own column when it is further right, or
        // `"  k:\n  j: 1\n"` reads as `{k: {j: 1}}` where saphyr and PyYAML
        // both give two sibling entries.
        let base_indent = base_indent.max(self.current_line_indent);
        let outer_equal_indent = self.equal_indent_continues_scalar;
        self.equal_indent_continues_scalar = false;
        self.builder.start_node(SyntaxKind::MAPPING.into());
        self.error_context.push_context(ParseContext::Mapping);

        while self.current().is_some() {
            let tokens_before_iter = self.tokens.len();
            // Skip whitespace, break on dedent
            if self.skip_whitespace_only_with_dedent_check(base_indent) {
                break;
            }

            // A `:` at or left of the `?` we sit inside opens that entry's
            // value, not another entry of ours: `? a: 1\n: b: 2\n` keys the
            // outer mapping with `{a: 1}` and values it `{b: 2}`, as the
            // YAML test suite's V9D5 expects.
            if self.current() == Some(SyntaxKind::COLON)
                && self
                    .explicit_key_column
                    .is_some_and(|column| self.current_line_indent <= column)
            {
                break;
            }

            // Emit comments as children of MAPPING
            if self.absorb_entry_comments(base_indent) {
                break;
            }

            // Check dedent via tracked line indentation (covers the case where
            // MAPPING_ENTRY consumed its trailing NEWLINE before we could detect
            // the dedent in skip_whitespace_only_with_dedent_check).
            if base_indent > 0 && self.is_at_dedented_position(base_indent) {
                break;
            }

            // No mapping key found - exit
            if !self.is_mapping_key() && !self.is_complex_mapping_key() {
                break;
            }

            // Check for complex keys (sequences or mappings as keys)
            if self.current() == Some(SyntaxKind::LEFT_BRACKET)
                || self.current() == Some(SyntaxKind::LEFT_BRACE)
            {
                // Start a MAPPING_ENTRY to wrap this key-value pair
                self.builder.start_node(SyntaxKind::MAPPING_ENTRY.into());

                self.builder.start_node(SyntaxKind::KEY.into());
                if self.current() == Some(SyntaxKind::LEFT_BRACKET) {
                    self.parse_flow_sequence();
                } else if self.current() == Some(SyntaxKind::LEFT_BRACE) {
                    self.parse_flow_mapping();
                }
                self.builder.finish_node();

                self.skip_ws_and_newlines();

                if self.current() == Some(SyntaxKind::COLON) {
                    self.bump();
                    self.skip_whitespace();

                    self.builder.start_node(SyntaxKind::VALUE.into());
                    if self.current().is_some() && self.current() != Some(SyntaxKind::NEWLINE) {
                        self.parse_value();
                    } else if self.current() == Some(SyntaxKind::NEWLINE) {
                        self.bump();
                        if self.current() == Some(SyntaxKind::INDENT) {
                            self.bump();
                            self.parse_value();
                        }
                    }
                    self.builder.finish_node();
                } else {
                    let error_msg = self.create_detailed_error(
                        "Missing colon in mapping",
                        "':' after key",
                        self.current_text(),
                    );
                    self.add_error_and_recover(error_msg, SyntaxKind::COLON, ParseErrorKind::Other);
                }

                // Finish the MAPPING_ENTRY node
                self.builder.finish_node();
            }
            // Check for explicit key indicator
            else if self.current() == Some(SyntaxKind::QUESTION) {
                // Start a MAPPING_ENTRY to wrap this key-value pair
                self.builder.start_node(SyntaxKind::MAPPING_ENTRY.into());

                // Parse explicit key
                let question_column = self.error_context.current_location().1.saturating_sub(1);
                self.bump(); // consume '?'
                self.skip_whitespace();

                self.builder.start_node(SyntaxKind::KEY.into());
                self.parse_explicit_key_node(question_column, question_column);
                self.builder.finish_node();

                self.skip_ws_and_newlines();

                // Parse value if there's a colon
                if self.current() == Some(SyntaxKind::COLON) {
                    self.bump(); // consume ':'
                    self.skip_whitespace();

                    self.parse_value_after_colon(false);
                } else {
                    // No value, just a key - create explicit null value
                    self.emit_implicit_null_value();
                }

                // Finish the MAPPING_ENTRY node
                self.builder.finish_node();
            } else {
                self.parse_mapping_key_value_pair(base_indent);
            }

            // Progress guard: if no token was consumed this iteration we
            // would loop forever (e.g. when is_mapping_key() is fooled by a
            // delimiter such as `}` followed by `:`, and synthetic-token
            // recovery never advances).
            if self.tokens.len() == tokens_before_iter {
                let unexpected = self.current_text().unwrap_or("").to_string();
                self.add_error(
                    format!("Unexpected token in mapping: {unexpected:?}"),
                    ParseErrorKind::Other,
                );
                self.bump();
            }
        }

        self.equal_indent_continues_scalar = outer_equal_indent;
        self.builder.finish_node();
        self.error_context.pop_context();
    }

    fn parse_sequence(&mut self) {
        self.parse_sequence_with_base_indent(0);
    }

    pub(super) fn parse_sequence_with_base_indent(&mut self, base_indent: usize) {
        // A sequence entry's continuation only has to clear the sequence's
        // own column, which parse_value_with_base_indent already enforces.
        // Put the outer rule back on the way out, as the mapping does.
        let outer_equal_indent = self.equal_indent_continues_scalar;
        self.equal_indent_continues_scalar = true;
        self.builder.start_node(SyntaxKind::SEQUENCE.into());
        self.error_context.push_context(ParseContext::Sequence);

        while self.current().is_some() {
            // Skip whitespace, break on dedent
            if self.skip_whitespace_only_with_dedent_check(base_indent) {
                break;
            }

            // Emit comments as children of SEQUENCE
            if self.absorb_entry_comments(base_indent) {
                break;
            }

            // Check dedent via tracked line indentation (covers the case where
            // SEQUENCE_ENTRY consumed its trailing NEWLINE before we could detect
            // the dedent in skip_whitespace_only_with_dedent_check).
            if base_indent > 0 && self.is_at_dedented_position(base_indent) {
                break;
            }

            // No dash - exit
            if self.current() != Some(SyntaxKind::DASH) {
                break;
            }
            // Start SEQUENCE_ENTRY node to wrap the entire item
            self.builder.start_node(SyntaxKind::SEQUENCE_ENTRY.into());

            // The dash's true column, read before bump() consumes it, and
            // zero-based to match the indents it is compared against.
            // current_line_indent counts leading whitespace only, so it reads
            // 0 for the `-` of an explicit key (`? - a`), whose entries then
            // look indented past their own sequence.
            let dash_column = self.error_context.current_location().1.saturating_sub(1);
            self.bump(); // consume dash
            self.skip_whitespace();

            // Record the dash's line indentation for the item value parsing
            let item_indent = self.current_line_indent;

            // A `-` on a later line continues this entry's scalar when it is
            // indented past our own dash, and opens the next entry when it is
            // not. The dash column is the only thing that tells those apart.
            let outer_entry_column = self.sequence_entry_column;
            self.sequence_entry_column = Some(dash_column);

            // An entry's value is never the document's own node, so a block
            // scalar here still needs an indented body: `- |\n- x\n` is two
            // entries, not one scalar holding `- x`.
            self.node_is_document_root = false;

            // A comment is not a value. When nothing indented follows it the
            // entry is an implicit null, just as a bare `-` is: `- # c\n- a\n`
            // is two entries, as the YAML test suite's W42U expects, where
            // parsing the comment as a value left an empty SEQUENCE behind.
            // The entry's value may still be on the next line though
            // (`- # c\n  v\n`, as in RZP5), so keep the comment and let the
            // later-line handling below claim it.
            if self.current() == Some(SyntaxKind::COMMENT)
                && self.comment_ends_the_entry(dash_column)
            {
                self.bump();
                self.builder.start_node(SyntaxKind::SCALAR.into());
                self.builder.token(SyntaxKind::NULL.into(), "");
                self.builder.finish_node();
            } else if self.current() == Some(SyntaxKind::COMMENT) {
                // The comment belongs to this entry; its value follows.
                self.bump();
                if let Some(indent_level) = self.entry_value_indent(dash_column) {
                    self.bump(); // newline
                    while self.current() == Some(SyntaxKind::NEWLINE)
                        || (self.current() == Some(SyntaxKind::INDENT)
                            && self.indent_is_blank_line())
                    {
                        self.bump();
                    }
                    self.bump(); // indent
                    self.parse_value_with_base_indent(indent_level);
                }
            } else if self.current().is_some() && self.current() != Some(SyntaxKind::NEWLINE) {
                // Use item's line indent so nested mappings parse at the right
                // level. It is one short of the column an inline value starts
                // at, since it counts the dash but not the space after it; a
                // mapping opening here measures its own entries from its key's
                // column instead, which parse_mapping_key_value_pair reads.
                self.parse_value_with_base_indent(item_indent);
            } else if self.current() == Some(SyntaxKind::NEWLINE) {
                // Nested content is a NEWLINE then INDENT. A bare `-` item is
                // an implicit null; leave the NEWLINE for the terminator bump
                // so set/remove see DASH, SCALAR, NEWLINE in that order.
                //
                // A blank line between the dash and its value carries no
                // indentation of its own, so look past a run of them:
                // `- \n\n m\n` is the entry `m`, just as `- \n m\n` is.
                // The value has to clear our own dash's column, or the line
                // opens the next entry rather than belonging to this one.
                if let Some(indent_level) = self.entry_value_indent(dash_column) {
                    self.bump(); // consume newline
                                 // Step over the blank lines the helper looked past.
                    while self.current() == Some(SyntaxKind::NEWLINE)
                        || (self.current() == Some(SyntaxKind::INDENT)
                            && self.indent_is_blank_line())
                    {
                        self.bump();
                    }
                    self.bump(); // consume indent

                    // The value parses at its own column, but a plain scalar
                    // there is still a node of this sequence, so a
                    // continuation only has to clear the *dash's* column:
                    // `-\n   b\n  - z\n` is the single item `b - z`, as
                    // both saphyr and PyYAML read it. Only for a scalar: a
                    // nested collection's entries set their own column.
                    let outer_floor = self.scalar_continuation_floor;
                    if self.current() != Some(SyntaxKind::DASH) {
                        self.scalar_continuation_floor = Some(dash_column);
                    }
                    self.parse_value_with_base_indent(indent_level);
                    self.scalar_continuation_floor = outer_floor;
                } else {
                    self.emit_implicit_null();
                }
            } else {
                self.emit_implicit_null();
            }

            self.sequence_entry_column = outer_entry_column;

            // Block-style SEQUENCE_ENTRY owns its NEWLINE terminator (DESIGN.md)
            if self.current() == Some(SyntaxKind::NEWLINE) {
                self.bump();
            }

            // Finish SEQUENCE_ENTRY node
            self.builder.finish_node();
        }

        self.equal_indent_continues_scalar = outer_equal_indent;
        self.builder.finish_node();
        self.error_context.pop_context();
    }

    pub(super) fn parse_explicit_key_mapping(&mut self, base_indent: usize) {
        // Parse mapping with explicit key indicator '?'
        self.builder.start_node(SyntaxKind::MAPPING.into());

        // `?` and `:` lines delimit this mapping's own entries, so a scalar
        // inside one must not keep folding at an enclosing key's column: an
        // inherited floor would let `? a\n: 1\n? c\n` read `? c` as part of
        // the value `1`.
        let outer_floor = self.scalar_continuation_floor;
        self.scalar_continuation_floor = None;

        while self.current() == Some(SyntaxKind::QUESTION) {
            // Start a MAPPING_ENTRY to wrap this key-value pair
            self.builder.start_node(SyntaxKind::MAPPING_ENTRY.into());

            // Parse explicit key
            let question_column = self.error_context.current_location().1.saturating_sub(1);
            self.bump(); // consume '?'
            self.skip_whitespace();

            // Parse key - can be any value including sequences and mappings
            self.builder.start_node(SyntaxKind::KEY.into());

            // A `:` line at or left of the `?` is this entry's value, so an
            // annotation inside the key must not adopt it.
            let outer_explicit_key = self.explicit_key_column;
            self.explicit_key_column = Some(question_column);
            // A `?` opening a line at this mapping's own column is its next
            // entry, not part of the key's scalar: `- ? k\n  ? c\n` is two
            // entries, as saphyr and PyYAML both read it.
            let outer_value_column = self.mapping_value_column;
            self.mapping_value_column = Some(question_column);

            // Parse the first part of the key
            self.parse_explicit_key_node(question_column, base_indent);

            // Check if this is a multiline key (newline followed by indent)
            // Only for scalar keys, not sequences or mappings
            if self.current() == Some(SyntaxKind::NEWLINE) {
                // Peek ahead to see if there's an indent after the newline
                // Since tokens are reversed, peek at the second-to-last token
                if self.tokens.len() >= 2 {
                    let (next_kind, _) = &self.tokens[self.tokens.len() - 2];
                    if *next_kind == SyntaxKind::INDENT {
                        // Check what comes after the indent (at position len() - 3)
                        if self.tokens.len() >= 3 {
                            let (token_after_indent, _) = &self.tokens[self.tokens.len() - 3];
                            // The key's own content has to clear the `?`;
                            // a line at the indicator's column opens the
                            // next entry instead (`- ?\n  j: 1\n` is two
                            // entries, as saphyr reads it).
                            let clears_indicator =
                                self.tokens[self.tokens.len() - 2].1.len() > question_column;
                            // If it's a DASH, this is a sequence continuation which was already
                            // handled by parse_value() above - don't try to parse it as multiline scalar
                            if *token_after_indent != SyntaxKind::DASH && clears_indicator {
                                // This is a multiline scalar key continuation
                                self.bump(); // consume newline
                                let key_indent =
                                    self.tokens.last().map_or(0, |(_, text)| text.len());
                                self.bump(); // consume indent

                                // Unless the key is a block mapping starting
                                // on this line: `?\n s: 1\n e: 2\n: v\n` is
                                // keyed by `{s: 1, e: 2}`, as saphyr reads it
                                // and as the inline `? s: 1\n  e: 2\n` spelling
                                // already parsed. Reading it as scalar parts
                                // stopped at the first colon and dropped every
                                // entry after it, and the value with them.
                                // A line starting at the colon is this
                                // entry's own value (`? a\n: 1\n`), not part
                                // of the key, even though is_mapping_key
                                // counts it as the null-key entry it would be
                                // anywhere else.
                                if self.current() != Some(SyntaxKind::COLON)
                                    && self.is_mapping_key()
                                {
                                    self.parse_mapping_with_base_indent(key_indent);
                                }

                                // Parse scalar tokens at this indentation level as part of the key
                                while self.current().is_some()
                                    && self.current() != Some(SyntaxKind::NEWLINE)
                                    && self.current() != Some(SyntaxKind::COLON)
                                {
                                    let before = self.tokens.len();
                                    self.parse_scalar();
                                    if self.current() == Some(SyntaxKind::WHITESPACE) {
                                        self.bump(); // consume whitespace between key parts
                                    }
                                    // Progress guard: parse_scalar() can return without
                                    // consuming tokens for kinds it doesn't handle (e.g.
                                    // COMMENT). Break to avoid an infinite loop.
                                    if self.tokens.len() == before {
                                        break;
                                    }
                                }
                            }
                        }
                    }
                }
            }

            self.builder.finish_node();
            self.explicit_key_column = outer_explicit_key;
            self.mapping_value_column = outer_value_column;

            self.skip_ws_and_newlines();

            // Parse value if there's a colon
            if self.current() == Some(SyntaxKind::COLON) {
                let colon_column = self.error_context.current_location().1.saturating_sub(1);
                self.bump(); // consume ':'
                self.skip_whitespace();

                // `:\n- c\n` -- an indentless sequence value, whose entries
                // sit at the `:`'s own column rather than past it. The shared
                // value-after-colon shape measures from the indent it finds,
                // so this one case is handled before delegating to it.
                if self.indentless_sequence_follows(colon_column) {
                    self.builder.start_node(SyntaxKind::VALUE.into());
                    self.bump(); // consume the newline
                    self.parse_sequence_with_base_indent(base_indent);
                    self.builder.finish_node();
                } else {
                    self.parse_value_after_colon(true);
                }
            } else {
                // No value, just a key - create explicit null value
                self.emit_implicit_null_value();
            }

            // Finish the MAPPING_ENTRY node
            self.builder.finish_node();

            self.skip_ws_and_newlines();

            // A following line at a shallower column closes this mapping --
            // it belongs to an enclosing one, not here.
            if self.is_at_dedented_position(base_indent) {
                break;
            }

            // Check if there are more entries
            if self.current() != Some(SyntaxKind::QUESTION) && !self.is_mapping_key() {
                break;
            }
        }

        // Continue parsing regular mapping entries if any
        while self.current().is_some()
            && !self.is_at_dedented_position(base_indent)
            && self.is_mapping_key()
        {
            let tokens_before_iter = self.tokens.len();
            // is_mapping_key() returns true for QUESTION, but
            // parse_mapping_key_value_pair does not consume a `?` key - that
            // would loop forever. Re-enter explicit-key handling for `?`.
            //
            // It takes the whole run of them, so the plain entries after that
            // run are still ours to parse: `?\nk:\n?\na:\n` has four. Leave
            // the loop to the progress guard below rather than breaking here.
            if self.current() == Some(SyntaxKind::QUESTION) {
                self.parse_explicit_key_entries();
            } else {
                self.parse_mapping_key_value_pair(base_indent);
            }
            self.skip_ws_and_newlines();
            // Progress guard against any future case where the body consumes
            // nothing (e.g. recovery via synthetic-token insertion).
            if self.tokens.len() == tokens_before_iter {
                let unexpected = self.current_text().unwrap_or("").to_string();
                self.add_error(
                    format!("Unexpected token in explicit-key mapping: {unexpected:?}"),
                    ParseErrorKind::Other,
                );
                self.bump();
            }
        }

        self.scalar_continuation_floor = outer_floor;
        self.builder.finish_node();
    }

    pub(super) fn parse_complex_key_mapping(&mut self) {
        // Parse mapping where the key is a complex structure (sequence or mapping)
        self.builder.start_node(SyntaxKind::MAPPING.into());

        // Start a MAPPING_ENTRY to wrap this key-value pair
        self.builder.start_node(SyntaxKind::MAPPING_ENTRY.into());

        // Parse the complex key
        self.builder.start_node(SyntaxKind::KEY.into());
        // An anchor before the key annotates that key, so it belongs inside
        // the KEY node: `&key [ a ]: value` anchors the flow sequence, not
        // the mapping. Left outside, it looked like a second anchor on the
        // mapping itself (test suite 6BFJ).
        while matches!(self.current(), Some(SyntaxKind::ANCHOR | SyntaxKind::TAG)) {
            self.bump();
            self.skip_whitespace();
        }
        if self.current() == Some(SyntaxKind::LEFT_BRACKET) {
            self.parse_flow_sequence();
        } else if self.current() == Some(SyntaxKind::LEFT_BRACE) {
            self.parse_flow_mapping();
        }
        self.builder.finish_node();

        self.skip_ws_and_newlines(); // Allow newlines between key and colon

        // Expect colon
        if self.current() == Some(SyntaxKind::COLON) {
            self.bump();
            self.skip_whitespace();

            // Parse value
            self.parse_value_after_colon(false);
        } else {
            let error_msg = self.create_detailed_error(
                "Missing colon in complex mapping",
                "':' after complex key",
                self.current_text(),
            );
            self.add_error_and_recover(error_msg, SyntaxKind::COLON, ParseErrorKind::Other);
        }

        // Finish the first MAPPING_ENTRY node
        self.builder.finish_node();

        self.skip_ws_and_newlines();

        // Continue parsing more entries if they exist
        while self.current().is_some() {
            let tokens_before_iter = self.tokens.len();
            if self.current() == Some(SyntaxKind::QUESTION) {
                // Switch to explicit key parsing
                self.parse_explicit_key_entries();
                break;
            } else if self.is_complex_mapping_key()
                || (self.is_mapping_key() && self.current() != Some(SyntaxKind::QUESTION))
            {
                // Start a MAPPING_ENTRY for this additional entry
                self.builder.start_node(SyntaxKind::MAPPING_ENTRY.into());

                // Parse another entry
                self.builder.start_node(SyntaxKind::KEY.into());

                if self.current() == Some(SyntaxKind::LEFT_BRACKET) {
                    self.parse_flow_sequence();
                } else if self.current() == Some(SyntaxKind::LEFT_BRACE) {
                    self.parse_flow_mapping();
                } else if matches!(
                    self.current(),
                    Some(
                        SyntaxKind::STRING
                            | SyntaxKind::INT
                            | SyntaxKind::FLOAT
                            | SyntaxKind::BOOL
                            | SyntaxKind::NULL
                            | SyntaxKind::MERGE_KEY
                    )
                ) {
                    self.bump();
                }
                self.builder.finish_node();

                self.skip_whitespace();

                if self.current() == Some(SyntaxKind::COLON) {
                    self.bump();
                    self.skip_whitespace();

                    self.builder.start_node(SyntaxKind::VALUE.into());
                    if self.current().is_some() && self.current() != Some(SyntaxKind::NEWLINE) {
                        self.parse_value();
                    } else if self.current() == Some(SyntaxKind::NEWLINE) {
                        self.bump();
                        if self.current() == Some(SyntaxKind::INDENT) {
                            self.bump();
                            self.parse_value();
                        }
                    }
                    self.builder.finish_node();
                }

                // Finish the MAPPING_ENTRY node
                self.builder.finish_node();

                self.skip_ws_and_newlines();
            } else {
                break;
            }

            // Progress guard: if is_mapping_key() returned true but nothing
            // consumed the current token (e.g. `]:` at top level), break to
            // avoid an infinite loop.
            if self.tokens.len() == tokens_before_iter {
                let unexpected = self.current_text().unwrap_or("").to_string();
                self.add_error(
                    format!("Unexpected token in complex mapping: {unexpected:?}"),
                    ParseErrorKind::Other,
                );
                self.bump();
            }
        }

        self.builder.finish_node();
    }

    fn parse_explicit_key_entries(&mut self) {
        // Helper to continue parsing explicit key entries within a mapping
        while self.current() == Some(SyntaxKind::QUESTION) {
            // Start a MAPPING_ENTRY to wrap this key-value pair
            self.builder.start_node(SyntaxKind::MAPPING_ENTRY.into());

            let question_column = self.error_context.current_location().1.saturating_sub(1);
            self.bump(); // consume '?'
            self.skip_whitespace();

            self.builder.start_node(SyntaxKind::KEY.into());
            self.parse_explicit_key_node(question_column, question_column);
            self.builder.finish_node();

            self.skip_ws_and_newlines();

            if self.current() == Some(SyntaxKind::COLON) {
                self.bump();
                self.skip_whitespace();

                self.parse_value_after_colon(false);
            } else {
                // No value, just a key - create explicit null value
                self.emit_implicit_null_value();
            }

            // Finish the MAPPING_ENTRY node
            self.builder.finish_node();

            self.skip_ws_and_newlines();
        }
    }

    /// As [`is_complex_mapping_key`](Self::is_complex_mapping_key), reading
    /// past a run of leading anchors and tags.
    ///
    /// `&key [ a ]: value` anchors the flow sequence that is the key, so the
    /// shape has to be recognised with the annotation still in front of it.
    pub(super) fn is_complex_mapping_key_after_annotations(&self) -> bool {
        let mut rest = self
            .upcoming_tokens()
            .skip_while(|k| {
                matches!(
                    k,
                    SyntaxKind::ANCHOR
                        | SyntaxKind::TAG
                        | SyntaxKind::WHITESPACE
                        | SyntaxKind::INDENT
                )
            })
            .peekable();
        let start_kind = match rest.peek() {
            Some(SyntaxKind::LEFT_BRACKET) => SyntaxKind::LEFT_BRACKET,
            Some(SyntaxKind::LEFT_BRACE) => SyntaxKind::LEFT_BRACE,
            _ => return false,
        };
        let close_kind = match start_kind {
            SyntaxKind::LEFT_BRACKET => SyntaxKind::RIGHT_BRACKET,
            _ => SyntaxKind::RIGHT_BRACE,
        };
        let mut depth = 0usize;
        let mut found_close = false;
        for kind in rest.skip(1) {
            if !found_close {
                if kind == start_kind {
                    depth += 1;
                } else if kind == close_kind {
                    if depth == 0 {
                        found_close = true;
                    } else {
                        depth -= 1;
                    }
                }
            } else {
                match kind {
                    SyntaxKind::COLON => return true,
                    SyntaxKind::WHITESPACE => continue,
                    _ => return false,
                }
            }
        }
        false
    }

    pub(super) fn is_complex_mapping_key(&self) -> bool {
        // Check if a flow sequence or mapping is used as a key
        if !matches!(
            self.current(),
            Some(SyntaxKind::LEFT_BRACKET | SyntaxKind::LEFT_BRACE)
        ) {
            return false;
        }

        // Look ahead to find matching closing bracket/brace and then check for colon
        let mut depth = 0;
        let start_kind = self.current();
        let close_kind = match start_kind {
            Some(SyntaxKind::LEFT_BRACKET) => SyntaxKind::RIGHT_BRACKET,
            Some(SyntaxKind::LEFT_BRACE) => SyntaxKind::RIGHT_BRACE,
            _ => return false,
        };

        let mut found_close = false;
        for kind in self.upcoming_tokens() {
            if !found_close {
                if Some(kind) == start_kind {
                    depth += 1;
                } else if kind == close_kind {
                    if depth == 0 {
                        // Found matching close
                        found_close = true;
                    } else {
                        depth -= 1;
                    }
                }
            } else {
                // We've found the closing bracket/brace, now look for colon
                match kind {
                    SyntaxKind::WHITESPACE | SyntaxKind::INDENT => continue,
                    SyntaxKind::COLON => return true,
                    _ => return false,
                }
            }
        }
        false
    }

    fn parse_mapping_value(&mut self, base_indent: usize) {
        // A mapping value is never the document's own node, whatever the
        // caller was parsing: `a: |\nb: 1\n` has an empty block scalar and
        // keeps `b` as a sibling, where `|\nb: 1\n` at the root would take
        // the line as body.
        self.node_is_document_root = false;

        // When parsing the value part of a mapping, be more conservative about
        // interpreting content as nested mappings. Only parse as mapping if
        // it's clearly a structured value, otherwise parse as scalar.
        match self.current() {
            Some(SyntaxKind::DASH) if !self.in_flow_context => self.parse_sequence(),
            Some(SyntaxKind::REFERENCE) => self.parse_alias(),
            Some(SyntaxKind::TAG) => self.parse_tagged_value_as_mapping_value(base_indent),
            Some(SyntaxKind::QUESTION) => {
                // Explicit key indicator - parse complex mapping
                self.parse_explicit_key_mapping(base_indent);
            }
            Some(SyntaxKind::PIPE) => self.parse_literal_block_scalar(),
            Some(SyntaxKind::GREATER) => self.parse_folded_block_scalar(),
            Some(SyntaxKind::LEFT_BRACKET) => {
                // Check if this is a complex key in a mapping
                if !self.in_flow_context && self.is_complex_mapping_key() {
                    self.parse_complex_key_mapping();
                } else {
                    self.parse_flow_sequence();
                }
            }
            Some(SyntaxKind::LEFT_BRACE) => {
                // Check if this is a complex key in a mapping
                if !self.in_flow_context && self.is_complex_mapping_key() {
                    self.parse_complex_key_mapping();
                } else {
                    self.parse_flow_mapping();
                }
            }
            _ => {
                // For all other cases in mapping values, parse as scalar
                // This handles URLs and other complex scalar values containing colons
                self.parse_scalar();
            }
        }
    }

    /// Parse the node an explicit key indicator introduces.
    ///
    /// The key may sit on the indicator's own line, or start on the next
    /// line: indentless when its dashes line up with the `?` itself, and
    /// otherwise indented past it. With neither, the key is an implicit
    /// null.
    fn parse_explicit_key_node(&mut self, question_column: usize, base_indent: usize) {
        if self.current().is_some() && self.current() != Some(SyntaxKind::NEWLINE) {
            // A sequence opening on the indicator's own line is bounded by
            // it: measured from column 0 instead, the key's sequence in
            // `-\n  ? - c\n- z\n` swallowed the enclosing sequence's next
            // entry. Other node kinds set their own bounds as before.
            if self.current() == Some(SyntaxKind::DASH) {
                self.parse_sequence_with_base_indent(question_column);
            } else {
                self.parse_value();
            }
        } else if self.indentless_sequence_follows(question_column) {
            self.bump(); // consume the newline
            self.parse_sequence_with_base_indent(base_indent);
        } else if let Some(indent) = self.indented_sequence_indent(question_column) {
            self.bump(); // consume the newline
            self.bump(); // consume the indent
            self.parse_sequence_with_base_indent(indent);
        } else if let Some(indent) = self.aligned_sequence_indent(question_column) {
            // `- ?\n  - a\n`: the `?` sits at a column the sequence's own
            // indentation reproduces, so the dashes are written out as an
            // INDENT rather than starting the line. They still belong to
            // the key.
            self.bump(); // consume the newline
            self.bump(); // consume the indent
            self.parse_sequence_with_base_indent(indent);
        } else if let Some(indent) = self.indented_key_node_indent(question_column) {
            // The same for a mapping or scalar key node: `?\n  j: 1\n` is
            // keyed by `{j: 1}`. Emitting the implicit null first left the
            // real key beside it in the KEY node, where every accessor read
            // the null instead.
            self.bump(); // consume the newline
            self.bump(); // consume the indent
            self.parse_value_with_base_indent(indent);
        } else {
            self.emit_implicit_null();
        }
    }

    /// The indentation of a non-sequence key node starting on the line after
    /// an explicit key indicator at `question_column`, if one does.
    ///
    /// A line opening at the colon is the entry's own value rather than part
    /// of its key, so `? a\n: 1\n` is left alone.
    fn indented_key_node_indent(&self, question_column: usize) -> Option<usize> {
        if self.current() != Some(SyntaxKind::NEWLINE) {
            return None;
        }
        let mut rest = self.tokens.iter().rev().skip(1);
        let indent = loop {
            match rest.next()? {
                (SyntaxKind::NEWLINE, _) => continue,
                (SyntaxKind::INDENT, text) => break text.len(),
                _ => return None,
            }
        };
        if indent <= question_column {
            return None;
        }
        match rest.next()? {
            (SyntaxKind::COLON, _) | (SyntaxKind::DASH, _) => None,
            _ => Some(indent),
        }
    }

    /// As [`indented_sequence_indent`](Self::indented_sequence_indent), for a
    /// sequence whose dashes line up with the `?` itself.
    ///
    /// The indicator only looks indentless when it starts its line; nested in
    /// a sequence entry, the same alignment arrives as an INDENT token.
    fn aligned_sequence_indent(&self, question_column: usize) -> Option<usize> {
        if self.current() != Some(SyntaxKind::NEWLINE) || question_column == 0 {
            return None;
        }
        let mut rest = self.tokens.iter().rev().skip(1);
        let indent = loop {
            match rest.next()? {
                (SyntaxKind::NEWLINE, _) => continue,
                (SyntaxKind::INDENT, text) => break text.len(),
                _ => return None,
            }
        };
        if indent != question_column {
            return None;
        }
        match rest.next()? {
            (SyntaxKind::DASH, _) => Some(indent),
            _ => None,
        }
    }

    /// The indentation of a sequence starting on the line after an explicit
    /// key indicator at `question_column`, if one does.
    ///
    /// `?\n  - a\n` keys the entry on `[a]`: the key's node is allowed to
    /// start on the following line as long as it is indented past the `?`.
    fn indented_sequence_indent(&self, question_column: usize) -> Option<usize> {
        if self.current() != Some(SyntaxKind::NEWLINE) {
            return None;
        }
        let mut rest = self.tokens.iter().rev().skip(1);
        let indent = loop {
            match rest.next()? {
                (SyntaxKind::NEWLINE, _) => continue,
                (SyntaxKind::INDENT, text) => break text.len(),
                _ => return None,
            }
        };
        if indent <= question_column {
            return None;
        }
        match rest.next()? {
            (SyntaxKind::DASH, _) => Some(indent),
            _ => None,
        }
    }

    /// Whether the next line opens an indentless block sequence, whose
    /// entries sit at the current construct's own column.
    ///
    /// The caller is on the NEWLINE that ends the `?` or `:` line. A `-`
    /// straight after that line break carries no INDENT token, which is what
    /// makes the sequence indentless.
    fn indentless_sequence_follows(&self, indicator_column: usize) -> bool {
        // The dashes carry no INDENT, so they start their line: only an
        // indicator in column 0 shares that column. Further in, `- ?\n- a\n`
        // dedents out of the entry and the sequence is the enclosing one's.
        if self.current() != Some(SyntaxKind::NEWLINE) || indicator_column != 0 {
            return false;
        }
        // A blank line between the indicator and the sequence carries no
        // indentation of its own, so it neither ends the entry nor stops the
        // sequence being the indentless one: `?\n\n- a\n: v\n` is keyed by
        // the sequence `[a]`, exactly as `?\n- a\n: v\n` is.
        let mut rest = self.upcoming_tokens();
        loop {
            match rest.next() {
                Some(SyntaxKind::NEWLINE) => continue,
                Some(kind) => return kind == SyntaxKind::DASH,
                None => return false,
            }
        }
    }

    pub(super) fn is_mapping_key(&self) -> bool {
        // Check if this is an explicit key indicator
        if self.current() == Some(SyntaxKind::QUESTION) {
            return true;
        }

        // Check if this is a merge key
        if self.current() == Some(SyntaxKind::MERGE_KEY) {
            return true;
        }

        // If current token is a dash, this is not a mapping key
        if self.current() == Some(SyntaxKind::DASH) {
            return false;
        }

        // A line that starts at the colon is an entry with an empty key:
        // `: v` is a mapping from null to `v`, which is what the YAML test
        // suite expects (2JQS gives `=VAL :` for the key). The scan below
        // looks for a colon *after* a key, so a null key needs saying here
        // or the mapping loop stops before the entry.
        if self.current() == Some(SyntaxKind::COLON) {
            return true;
        }

        // Look ahead to see if there's a colon after the current token.
        // Plain scalars can contain spaces, so a key may span multiple scalar
        // tokens separated by whitespace before the terminating colon
        // (e.g. `abc cba: value`).
        //
        // Any number of leading TAG / ANCHOR tokens annotate the key
        // (`!!str &a1 "foo":`); skip past them and any WHITESPACE, then
        // apply the usual scan.
        let mut saw_scalar = false;
        for kind in self.upcoming_tokens() {
            if kind == SyntaxKind::COLON {
                return true;
            }
            if !saw_scalar && matches!(kind, SyntaxKind::TAG | SyntaxKind::ANCHOR) {
                continue;
            }
            if is_plain_scalar_kind(kind) {
                saw_scalar = true;
                continue;
            }
            if kind == SyntaxKind::WHITESPACE {
                continue;
            }
            return false;
        }
        false
    }
    fn parse_mapping_key_value_pair(&mut self, base_indent: usize) {
        // The key's own column, read before anything is consumed. It is
        // 1-based, so step back to a column.
        let key_column = self.error_context.current_location().1.saturating_sub(1);
        // Start MAPPING_ENTRY node to wrap the entire key-value pair
        self.builder.start_node(SyntaxKind::MAPPING_ENTRY.into());

        // Parse regular key
        self.builder.start_node(SyntaxKind::KEY.into());

        // Absorb any number of TAG / ANCHOR annotations preceding the
        // key scalar (`&anchor a:`, `!!str foo:`, `!!str &a1 "foo":`).
        while matches!(self.current(), Some(SyntaxKind::ANCHOR | SyntaxKind::TAG)) {
            self.bump(); // consume tag or anchor token
            self.skip_whitespace();
        }

        if self.current() == Some(SyntaxKind::MERGE_KEY) {
            self.builder.start_node(SyntaxKind::SCALAR.into());
            self.bump(); // consume the merge key token
            self.builder.finish_node(); // SCALAR
        } else if self.current() == Some(SyntaxKind::REFERENCE) {
            // Handle alias as key (*b:)
            self.parse_alias();
        } else if self.current().is_some_and(is_plain_scalar_kind) {
            self.builder.start_node(SyntaxKind::SCALAR.into());
            self.bump();
            // Plain scalars can contain spaces, so absorb any following
            // whitespace + scalar tokens until we reach the terminating colon
            // (e.g. `abc cba: value`).
            while self.current() == Some(SyntaxKind::WHITESPACE)
                && self
                    .upcoming_tokens()
                    .next()
                    .is_some_and(is_plain_scalar_kind)
            {
                self.bump(); // WHITESPACE inside the plain scalar
                self.bump(); // next scalar segment
            }
            self.builder.finish_node(); // SCALAR
        } else if self.current() == Some(SyntaxKind::COLON) {
            // No key before the colon: an explicit null, spelled the same
            // zero-width way as an implicit null value.
            self.builder.start_node(SyntaxKind::SCALAR.into());
            self.builder.token(SyntaxKind::NULL.into(), "");
            self.builder.finish_node(); // SCALAR
        }
        self.builder.finish_node(); // KEY

        self.skip_whitespace();

        // Expect colon
        if self.current() == Some(SyntaxKind::COLON) {
            self.bump();
            self.skip_whitespace();

            // Parse value - wrap in VALUE node
            self.builder.start_node(SyntaxKind::VALUE.into());
            // Anchors annotate the value; they do not make a following block value inline.
            while self.current() == Some(SyntaxKind::ANCHOR) {
                self.bump();
                self.skip_whitespace();
            }
            if self.current() == Some(SyntaxKind::COMMENT) {
                self.bump();
            }
            let mut has_value = false;
            if self.current().is_some()
                && self.current() != Some(SyntaxKind::NEWLINE)
                && self.current() != Some(SyntaxKind::COMMENT)
            {
                // Inline value on the same line as the colon. A `?` opening
                // a later line at this mapping's own column is its next
                // entry, not part of the value's scalar: `- a: 1\n  ? c\n`
                // is two entries, while `- x\n  ? c\n` (no mapping) is the
                // single scalar `x ? c`.
                let outer_column = self.mapping_value_column;
                self.mapping_value_column = Some(base_indent.max(key_column));
                self.parse_mapping_value(base_indent);
                self.mapping_value_column = outer_column;
                has_value = true;

                // Capture any trailing whitespace and comment on the same line (before NEWLINE)
                // This keeps inline comments like "value  # comment" together in the VALUE node
                if self.current() == Some(SyntaxKind::WHITESPACE) {
                    self.bump(); // emit whitespace inside VALUE
                }
                if self.current() == Some(SyntaxKind::COMMENT) {
                    self.bump(); // emit inline comment inside VALUE
                }
            } else if self.current() == Some(SyntaxKind::NEWLINE) {
                self.skip_ws_and_newlines();
                // A mapping's value is never the document's own node,
                // whatever the caller was parsing. Left set, a block scalar
                // here read its body as starting at column 0 and swallowed
                // the next entry: `k:\n  |\nz: 1\n` lost `z`.
                self.node_is_document_root = false;
                // A block value on a later line has to clear the *key's*
                // column, not the column the mapping was measured from. In a
                // sequence entry those differ: `- k:` puts `k` at column 2
                // while the mapping's base is 1, the dash's own column plus
                // the dash. Against the base, `- k:\n  j: 1\n` reads `j` as
                // the value of `k`; against the key it is the sibling entry
                // saphyr and PyYAML both give.
                if self.current_line_indent > base_indent.max(key_column) {
                    // Nested value is more indented than the enclosing mapping's
                    // base indent - belongs to this key.
                    //
                    // The value parses at its own column, but a plain scalar
                    // there is still a node of this mapping, so a
                    // continuation line only has to clear the *key's* column:
                    // `a:\n  x y\n z\n` is the single scalar `x y z`, as
                    // both saphyr and PyYAML read it.
                    //
                    // Only for a scalar value. A sequence's entries set their
                    // own column, so a line dedented past them ends the
                    // mapping rather than continuing an entry:
                    // `key:\n - a\ninvalid\n` is the error the YAML test
                    // suite's 6S55 and 9CWY expect, not the scalar `a invalid`.
                    let outer_floor = self.scalar_continuation_floor;
                    if self.current() != Some(SyntaxKind::DASH) {
                        self.scalar_continuation_floor = Some(base_indent);
                    }
                    // A lone anchor may annotate an indentless sequence, whose
                    // entries sit at the *key's* column rather than the
                    // anchor's (`seq:\n &a\n- x\n`). Hand it the key's base
                    // so it can adopt them; anything else measures from its
                    // own line as before.
                    let value_indent = if self.current() == Some(SyntaxKind::ANCHOR) {
                        base_indent
                    } else {
                        self.current_line_indent
                    };
                    self.parse_value_with_base_indent(value_indent);
                    self.scalar_continuation_floor = outer_floor;
                    has_value = true;
                } else if self.current() == Some(SyntaxKind::DASH)
                    && (self.current_line_indent == base_indent
                        || self.current_line_indent == key_column)
                    // A dash at the column of a sequence we sit in is that
                    // sequence's next entry, which it claims before we can:
                    // `- - k:\n  - b\n` is the two items `{k: null}` and
                    // `b`, not one item keyed by `[b]`.
                    && match self.sequence_entry_column {
                        Some(column) => self.current_line_indent > column,
                        None => true,
                    }
                {
                    // An indentless sequence: its entries sit at the key's
                    // own column rather than past it, so it is the key's
                    // value even though nothing is more indented. A mapping
                    // key at that column would be a sibling entry instead
                    // (`- k:\n  j: 1\n`), which is why only a dash counts.
                    self.parse_sequence_with_base_indent(self.current_line_indent);
                    has_value = true;
                }
                // Otherwise the "value" would be at the parent's indent or
                // less, so this key has an implicit null value and what
                // follows is a sibling entry.
            }

            // If no value present, create an implicit null scalar
            if !has_value {
                self.emit_implicit_null();
            }

            self.builder.finish_node(); // VALUE
        } else {
            let error_msg = self.create_detailed_error(
                "Missing colon in mapping",
                "':' after key",
                self.current_text(),
            );
            self.add_error_and_recover(error_msg, SyntaxKind::COLON, ParseErrorKind::Other);
        }

        // Consume any trailing inline whitespace before closing MAPPING_ENTRY
        // Note: Inline comments are consumed within the VALUE node itself.
        // Any COMMENT token here would be on a separate line and should not
        // be consumed as part of this entry (it may be dedented).
        while self.current() == Some(SyntaxKind::WHITESPACE) {
            self.bump();
        }

        // Block-style entries own their NEWLINE terminator (DESIGN.md)
        if self.current() == Some(SyntaxKind::NEWLINE) {
            self.bump();
        }

        // Finish MAPPING_ENTRY node
        self.builder.finish_node();
    }
}

#[cfg(test)]
mod tests {
    use crate::yaml::YamlFile;
    use std::str::FromStr;

    /// Top-level keys of `src`, in document order.
    fn top_level_keys(src: &str) -> Vec<String> {
        YamlFile::from_str(src)
            .expect("should parse")
            .document()
            .expect("should have a document")
            .as_mapping()
            .expect("root should be a mapping")
            .keys()
            .map(|k| k.to_string())
            .collect()
    }

    // Regression: a nested explicit-key block (`? k` / `: v`) used to swallow
    // whatever followed it. parse_explicit_key_mapping was the only
    // block-mapping path taking no base_indent, so after its entries it kept
    // consuming whatever is_mapping_key() accepted -- neither knowing about
    // columns -- and a key at the outer level was absorbed into the nested
    // mapping. The text still round-tripped byte-for-byte, so only the
    // structure was wrong.

    #[test]
    fn test_key_after_nested_explicit_key_block() {
        assert_eq!(top_level_keys("m:\n  ? a\n  : 1\nuf: v\n"), ["m", "uf"]);
    }

    #[test]
    fn test_key_after_multi_entry_nested_explicit_key_block() {
        assert_eq!(
            top_level_keys("m:\n  ? a\n  : 1\n  ? b\n  : 2\nuf: v\n"),
            ["m", "uf"]
        );
    }

    #[test]
    fn test_nested_explicit_key_block_followed_by_another_nested_mapping() {
        assert_eq!(
            top_level_keys("m:\n  ? a\n  : 1\nn:\n  ? b\n  : 2\n"),
            ["m", "n"]
        );
    }

    /// An explicit key whose value is itself a block: the value must be
    /// bounded by the column that opened it, not parsed at indent 0.
    #[test]
    fn test_key_after_explicit_key_with_block_value() {
        assert_eq!(
            top_level_keys("m:\n  ? a\n  : \n    n: 1\nz: 9\n"),
            ["m", "z"]
        );
    }

    #[test]
    fn test_key_after_deeply_indented_explicit_key_block() {
        assert_eq!(
            top_level_keys("m:\n      ? a\n      : 1\nz: 9\n"),
            ["m", "z"]
        );
    }

    #[test]
    fn test_explicit_key_block_mixed_with_plain_entries_stops_at_dedent() {
        assert_eq!(
            top_level_keys("m:\n  ? a\n  : 1\n  plain: 2\nouter: 3\n"),
            ["m", "outer"]
        );
    }

    #[test]
    fn test_explicit_key_block_nested_two_levels_deep() {
        assert_eq!(
            top_level_keys("a:\n  b:\n    ? c\n    : 1\n  d: 2\ne: 3\n"),
            ["a", "e"]
        );
    }

    /// A `!!set`-tagged explicit-key block is the same shape and must also
    /// release the key that follows it.
    #[test]
    fn test_key_after_tagged_explicit_key_set() {
        assert_eq!(
            top_level_keys("keys: !!set\n  ? a\n  ? b\nz: 9\n"),
            ["keys", "z"]
        );
    }

    /// The nested mapping must hold only its own content -- a key count alone
    /// would miss a value that absorbed the dedented sibling.
    #[test]
    fn test_nested_explicit_key_value_excludes_dedented_sibling() {
        let parsed = YamlFile::from_str("m:\n  ? a\n  : 1\nuf: v\n").expect("should parse");
        let doc = parsed.document().expect("should have a document");
        let mapping = doc.as_mapping().expect("root should be a mapping");

        let m = mapping.get("m").expect("m should be present");
        assert_eq!(m.to_string().trim_end(), "? a\n  : 1");

        let uf = mapping.get("uf").expect("uf should be present");
        assert_eq!(uf.to_string().trim(), "v");
    }

    /// Top-level explicit keys were never affected; this guards against a
    /// dedent check that is too eager.
    #[test]
    fn test_top_level_explicit_keys_are_unaffected() {
        assert_eq!(top_level_keys("? a\n: 1\nplain: v\n"), ["a", "plain"]);
    }
}