opy_rs/

settings.rs

//! Scoped `settings { ... }` extraction and JSONC parsing (#86).
//!
//! The settings block is recognized and consumed *before* lexing, so the
//! lexer never gains global `{`/`}` tokens (meipocalypse's dict literal keeps
//! failing as a `lex-error`). [`find_blocks`] locates a logical-line `settings`
//! statement in each source file with a keyword scan, [`sanitize_for_lex`]
//! blanks the block region out of the text handed to the lexer (newlines
//! preserved, so positions after the block are unchanged), and [`parse_block`]
//! turns the JSONC text into a typed [`cst::Settings`] tree with source spans.
//!
//! The parse is value-driven: any JSONC object/leaf shape becomes a
//! structurally generic [`cst::SettingsNode`]. Which keys exist and which
//! leaf kinds/spellings are valid is Workshop-owned settings-schema content;
//! that validation is `lowering-dependent` (issue #8) and lives at the
//! Workshop integration boundary, never in a local allowlist here.

use std::collections::HashMap;

use crate::cst;
use crate::diag::{OpyError, OpyResult, Position, Span};
use crate::hir;
use crate::lexer::{decode_string_escape, is_ident_continue, is_ident_start};

/// A project `settings { ... }` block.
#[derive(Debug, Clone)]
pub struct SettingsBlock {
    /// The raw JSONC text between the braces (braces excluded).
    pub text: String,
    /// The whole block: the `settings` keyword through the closing brace.
    pub span: Span,
    /// The `settings` keyword token (diagnostic anchor).
    pub keyword_span: Span,
    /// The char offset of the `settings` keyword (for sanitization).
    pub start: usize,
    /// The char offset just past the closing brace (for sanitization).
    pub end: usize,
    /// The position of the first char of `text` (just past the opening brace).
    pub text_start: Position,
    /// The source file containing the extracted settings content.
    pub content_file: u32,
    /// The span covering the extracted settings content.
    pub content_span: Span,
    /// The external source path for `settings "settings.opy.json"`.
    pub external_path: Option<String>,
}

/// Locate every `settings { ... }` block in a source text.
///
/// Rules: 0 blocks -> `Ok(vec![])`; `settings` is a statement when it opens a
/// logical line — the reference checks `tokens[0]` of every parsed line with
/// no indentation or ordering requirement — or the inline tail of a `:`-header
/// line, which the reference parses as a nested line. A newline inside
/// brackets continues the logical line, so `settings` there is an ordinary
/// token. After `settings` a `{` or quoted external path is required;
/// a second/later block is `settings-placement` at its keyword span; brace
/// matching respects `"`/`'` strings, `\` escapes, and nesting; an
/// unterminated block is `settings-invalid`.
pub fn find_blocks(text: &str, file_id: u32) -> OpyResult<Vec<SettingsBlock>> {
    let mut scanner = Cursor::new(text, file_id, Position::new(1, 1));
    let mut blocks = Vec::new();
    let mut in_block_comment = false;
    let mut string_quote = None;
    let mut escaped = false;
    // `line_start`: the next token would open a logical line. `tail_start`:
    // the next token would open the inline tail of a `:`-header line.
    // `depth`: open `(`, `[`, `{` count, which keeps a newline from ending
    // the logical line.
    let mut line_start = true;
    let mut tail_start = false;
    let mut depth = 0usize;
    while let Some(ch) = scanner.peek() {
        if scanner.advance_quoted(&mut string_quote, &mut escaped, ch) {
            continue;
        }
        if in_block_comment {
            if ch == '*' && scanner.peek_at(1) == Some('/') {
                in_block_comment = false;
                scanner.advance_by(2);
            } else {
                scanner.advance_by(1);
            }
            continue;
        }
        if matches!(ch, '"' | '\'') {
            string_quote = Some(ch);
            line_start = false;
            tail_start = false;
            scanner.advance_by(1);
            continue;
        }
        if ch == ' ' || ch == '\t' || ch == '\r' {
            scanner.advance_by(1);
            continue;
        }
        if ch == '\n' {
            if depth == 0 {
                line_start = true;
                tail_start = false;
            }
            scanner.advance_by(1);
            continue;
        }
        if ch == '#' {
            scanner.skip_to_eol();
            continue;
        }
        if ch == '/' && scanner.peek_at(1) == Some('*') {
            scanner.advance_by(2);
            in_block_comment = true;
            continue;
        }
        match ch {
            '(' | '[' | '{' => depth += 1,
            ')' | ']' | '}' => depth = depth.saturating_sub(1),
            ':' if depth == 0 => {
                tail_start = true;
                line_start = false;
                scanner.advance_by(1);
                continue;
            }
            _ => {}
        }
        if is_ident_start(ch) {
            let statement_start = line_start || tail_start;
            line_start = false;
            tail_start = false;
            let keyword_start = scanner.here();
            let keyword_offset = scanner.char_pos;
            let word = scanner.read_word();
            if word == "settings" && statement_start {
                let keyword_span = Span::new(file_id, keyword_start, scanner.here());
                if !blocks.is_empty() {
                    return Err(OpyError::at(
                        "settings-placement",
                        "only one settings block is supported in a file".to_string(),
                        keyword_span,
                    ));
                }
                let block = match_block(&mut scanner, keyword_start, keyword_offset, keyword_span)?;
                blocks.push(block);
            }
            continue;
        }
        line_start = false;
        tail_start = false;
        scanner.advance_by(1);
    }
    Ok(blocks)
}

/// Match the braces of one `settings { ... }` block, returning the extracted
/// block. `scanner` is positioned just past the `settings` keyword.
fn match_block(
    scanner: &mut Cursor<'_>,
    keyword_start: Position,
    keyword_offset: usize,
    keyword_span: Span,
) -> OpyResult<SettingsBlock> {
    scanner.skip_horizontal_whitespace();
    if scanner.peek() != Some('{') {
        let Some(quote) = scanner.peek().filter(|ch| matches!(ch, '"' | '\'')) else {
            return Err(OpyError::at(
                "settings-invalid",
                "settings block must be a `settings { ... }` block or `settings \"file\"`",
                keyword_span,
            ));
        };
        scanner.advance_by(1);
        let mut path = String::new();
        let mut escaped = false;
        loop {
            let Some(ch) = scanner.peek() else {
                return Err(OpyError::at(
                    "settings-invalid",
                    "unterminated external settings path",
                    keyword_span,
                ));
            };
            scanner.advance_by(1);
            if escaped {
                path.push(decode_string_escape(ch));
                escaped = false;
            } else if ch == '\\' {
                escaped = true;
            } else if ch == quote {
                break;
            } else if ch == '\n' {
                return Err(OpyError::at(
                    "settings-invalid",
                    "external settings path must be one quoted string",
                    keyword_span,
                ));
            } else {
                path.push(ch);
            }
        }
        scanner.skip_horizontal_whitespace();
        if scanner.peek() == Some('#') {
            scanner.skip_to_eol();
        }
        if !matches!(scanner.peek(), None | Some('\n')) {
            return Err(OpyError::at(
                "settings-invalid",
                "external settings declaration has unexpected trailing content",
                keyword_span,
            ));
        }
        return Ok(SettingsBlock {
            text: String::new(),
            span: Span::new(keyword_span.file, keyword_start, scanner.here()),
            keyword_span,
            start: keyword_offset,
            end: scanner.char_pos,
            text_start: keyword_start,
            content_file: keyword_span.file,
            content_span: keyword_span,
            external_path: Some(path),
        });
    }
    let mut depth = 0usize;
    let mut string_quote: Option<char> = None;
    let mut escaped = false;
    let mut text_start_offset = None;
    let mut text_start = None;
    loop {
        let Some(ch) = scanner.peek() else {
            return Err(OpyError::at(
                "settings-invalid",
                "unterminated settings block (missing closing brace)".to_string(),
                keyword_span,
            ));
        };
        if scanner.advance_quoted(&mut string_quote, &mut escaped, ch) {
            continue;
        }
        match ch {
            '"' | '\'' => string_quote = Some(ch),
            '{' => {
                if depth == 0 {
                    text_start_offset = Some(scanner.pos + ch.len_utf8());
                    text_start = Some(scanner.here_after(1));
                }
                depth += 1;
            }
            '}' => {
                depth -= 1;
                if depth == 0 {
                    let text = scanner
                        .text
                        .get(text_start_offset.expect("text start offset set on '{'")..scanner.pos)
                        .unwrap_or_default()
                        .to_string();
                    return Ok(SettingsBlock {
                        text,
                        span: Span::new(keyword_span.file, keyword_start, scanner.here_after(1)),
                        keyword_span,
                        start: keyword_offset,
                        end: scanner.char_pos + 1,
                        text_start: text_start.expect("text start set on '{'"),
                        content_file: keyword_span.file,
                        content_span: Span::new(
                            keyword_span.file,
                            text_start.expect("text start set on '{'"),
                            scanner.here(),
                        ),
                        external_path: None,
                    });
                }
            }
            _ => {}
        }
        scanner.advance_by(1);
    }
}

/// Replace every char of the block region with a space, preserving newlines,
/// so tokens after the block keep their exact original line/col.
pub fn sanitize_for_lex(text: &str, block: &SettingsBlock) -> String {
    let mut out = String::with_capacity(text.len());
    for (index, ch) in text.chars().enumerate() {
        if index >= block.start && index < block.end {
            out.push(if ch == '\n' { '\n' } else { ' ' });
        } else {
            out.push(ch);
        }
    }
    out
}

/// Parse a settings block's JSONC text into a typed CST settings tree.
///
/// Grammar: quoted keys, `"`/`'` strings with `\` escapes, int/float numbers
/// (f64), `true`/`false`, arrays of strings, nested objects, trailing commas
/// in objects and arrays. Rejections (`settings-invalid`): duplicate keys,
/// non-object root, missing `gamemodes` group, malformed values.
pub fn parse_block(block: &SettingsBlock) -> OpyResult<cst::Settings> {
    let mut parser = Cursor::new(&block.text, block.content_file, block.text_start);
    parser.skip_whitespace();
    let children = if block.external_path.is_some() {
        let (children, _) = parser.parse_object()?;
        children
    } else {
        // The block's own braces delimit the root object; the text between
        // them parses as its members.
        parser.parse_members(true)?
    };
    parser.skip_whitespace();
    if parser.pos < parser.text.len() {
        return Err(parser.error(
            "settings-invalid",
            "unexpected content after the settings object".to_string(),
        ));
    }
    if !children
        .iter()
        .any(|node| matches!(node, cst::SettingsNode::Group { name, .. } if name == "gamemodes"))
    {
        return Err(OpyError::at(
            "settings-invalid",
            "settings block must contain a gamemodes group".to_string(),
            block.content_span,
        ));
    }
    Ok(cst::Settings {
        span: block.content_span,
        children,
    })
}

/// Resolve parsed settings values through the ordinary OPY HIR expression path.
///
/// Token-level `#!define` expansion is performed by [`crate::preprocess`]
/// before this function runs. Source macros and constants are resolved from
/// the same HIR program used by ordinary OPY lowering.
pub(crate) fn resolve_hir_settings(
    program: &mut hir::Program,
    cst_program: &cst::Program,
) -> OpyResult<()> {
    let constants = program
        .declarations
        .iter()
        .filter_map(|declaration| match declaration {
            hir::Declaration::Constant { name, value, .. } => Some((name.clone(), value.as_ref())),
            _ => None,
        })
        .collect::<HashMap<_, _>>();
    let mut expander = crate::compiler::MacroExpander::from_declarations(&program.declarations);
    let Some(settings) = program.settings.take() else {
        return Ok(());
    };
    let mut lowerer = crate::lower::SettingsLowerer::new(cst_program)?;
    let children = settings
        .children
        .into_iter()
        .map(|node| resolve_hir_node(node, &constants, &mut expander, &mut lowerer))
        .collect::<OpyResult<Vec<_>>>()?;
    program.settings = Some(hir::Settings {
        span: settings.span,
        children,
    });
    Ok(())
}

fn resolve_hir_node(
    node: hir::SettingsNode,
    constants: &HashMap<String, &hir::Expr>,
    expander: &mut crate::compiler::MacroExpander<'_>,
    lowerer: &mut crate::lower::SettingsLowerer,
) -> OpyResult<hir::SettingsNode> {
    match node {
        hir::SettingsNode::Group {
            name,
            children,
            span,
        } => Ok(hir::SettingsNode::Group {
            name,
            children: children
                .into_iter()
                .map(|child| resolve_hir_node(child, constants, expander, lowerer))
                .collect::<OpyResult<Vec<_>>>()?,
            span,
        }),
        hir::SettingsNode::Raw { name, value, span } => {
            let Some(span) = span else {
                return Err(OpyError::new(
                    "settings-expression",
                    "settings value has no source span",
                ));
            };
            let diag_span = hir_span_to_diag_span(span);
            let value = eval_settings_text(&value, span, constants, expander, lowerer, true)?;
            node_from_value(name, value, diag_span)
        }
        // The pinned OverPy evaluates each settings list element through its
        // expression path and errors on what it cannot resolve (#512).
        // Evaluation is recorded on the element rather than emitted eagerly:
        // elements under catalogued enum keys and hero lists are member
        // names, not expressions, and only the downstream pass knows which.
        hir::SettingsNode::List {
            name,
            elements,
            span,
        } => Ok(hir::SettingsNode::List {
            name,
            elements: elements
                .into_iter()
                .map(|mut element| {
                    if element.evaluated.is_none()
                        && let Some(span) = element.span
                    {
                        element.evaluated = eval_settings_text(
                            &element.value,
                            span,
                            constants,
                            expander,
                            lowerer,
                            true,
                        )
                        .ok()
                        .and_then(|value| display_value(&value).ok());
                    }
                    element
                })
                .collect(),
            span,
        }),
        // A literal string still passes the pinned `__customString__`
        // check upstream — `{n}`/`{}` formatters without arguments are an
        // error even outside `.format(...)` calls (#512).
        hir::SettingsNode::String { name, value, span } => {
            if crate::compile_time::has_unbound_formatters(&value) {
                let Some(span) = span else {
                    return Err(OpyError::new(
                        "settings-expression",
                        "settings value has no source span",
                    ));
                };
                return Err(settings_expression_error(
                    hir_span_to_diag_span(span),
                    format!("settings string '{value}' has format arguments"),
                ));
            }
            Ok(hir::SettingsNode::String { name, value, span })
        }
        node => Ok(node),
    }
}

/// Compile an authored settings expression to a constant value: parse it as
/// OPY, expand macros, then fold. `strict` selects the pinned settings
/// evaluator — scalars and list elements both evaluate through it upstream
/// (#512).
fn eval_settings_text(
    text: &str,
    span: hir::Span,
    constants: &HashMap<String, &hir::Expr>,
    expander: &mut crate::compiler::MacroExpander<'_>,
    lowerer: &mut crate::lower::SettingsLowerer,
    strict: bool,
) -> OpyResult<crate::compile_time::Value> {
    let diag_span = hir_span_to_diag_span(span);
    let expression = lowerer
        .lower(
            text,
            span.file,
            Position::new(span.start.line, span.start.col),
        )
        .map_err(|error| settings_expression_error(diag_span, error.message))?;
    let expression = expander
        .expand_expr(&expression, &HashMap::new(), None)
        .map_err(|error| {
            let error_span = error
                .diagnostic
                .span
                .map(hir_span_to_diag_span)
                .unwrap_or(diag_span);
            OpyError::at(error.diagnostic.code, error.diagnostic.message, error_span)
        })?;
    let mut stack = Vec::new();
    let value = if strict {
        crate::compile_time::evaluate_settings(&expression, constants, &HashMap::new(), &mut stack)
    } else {
        crate::compile_time::evaluate(&expression, constants, &HashMap::new(), &mut stack)
    };
    value.ok_or_else(|| {
        settings_expression_error(
            diag_span,
            "expression is not a compile-time value".to_string(),
        )
    })
}

fn hir_span_to_diag_span(span: hir::Span) -> Span {
    Span::new(
        span.file,
        Position::new(span.start.line, span.start.col),
        Position::new(span.end.line, span.end.col),
    )
}

fn settings_expression_error(span: Span, message: String) -> OpyError {
    OpyError::at(
        "settings-expression",
        format!("settings value is not a compile-time value: {message}"),
        span,
    )
}

fn node_from_value(
    name: String,
    value: crate::compile_time::Value,
    span: Span,
) -> OpyResult<hir::SettingsNode> {
    let node = match value {
        // `String(numValue)` writes `NaN`/`Infinity` literally upstream —
        // `x: 5%0` is `x: NaN` and `x: Infinity` is `x: Infinity` (#512).
        crate::compile_time::Value::Number(value) => hir::SettingsNode::Number {
            name,
            value,
            span: Some(span.into()),
        },
        crate::compile_time::Value::String(value) => {
            if crate::compile_time::has_unbound_formatters(&value) {
                return Err(settings_expression_error(
                    span,
                    format!("settings string '{value}' has format arguments"),
                ));
            }
            hir::SettingsNode::String {
                name,
                value,
                span: Some(span.into()),
            }
        }
        crate::compile_time::Value::Bool(value) => hir::SettingsNode::Bool {
            name,
            value,
            span: Some(span.into()),
        },
        crate::compile_time::Value::Array(values) => hir::SettingsNode::List {
            name,
            elements: values
                .into_iter()
                .map(|value| {
                    let value = display_value(&value)?;
                    Ok(hir::SettingsListElement {
                        evaluated: Some(value.clone()),
                        value,
                        span: Some(span.into()),
                    })
                })
                .collect::<Result<Vec<_>, String>>()
                .map_err(|message| settings_expression_error(span, message))?,
            span: Some(span.into()),
        },
        crate::compile_time::Value::Object(entries) => hir::SettingsNode::Group {
            name,
            children: entries
                .into_iter()
                .map(|(key, value)| {
                    let crate::compile_time::Value::String(name) = key else {
                        return Err(settings_expression_error(
                            span,
                            "compile-time object keys must be strings".to_string(),
                        ));
                    };
                    node_from_value(name, value, span)
                })
                .collect::<OpyResult<Vec<_>>>()?,
            span: Some(span.into()),
        },
        // A `vect` AST has no settings object form upstream — the
        // reference reports it unhandled (#512).
        crate::compile_time::Value::Vector(_) | crate::compile_time::Value::Null => {
            return Err(settings_expression_error(
                span,
                "compile-time value is not a settings value".to_string(),
            ));
        }
    };
    Ok(node)
}

fn display_value(value: &crate::compile_time::Value) -> Result<String, String> {
    match value {
        // `String(value)` writes `NaN`/`Infinity` literally, as the pinned
        // evaluator does for `%` results and unparsed number tokens (#512).
        crate::compile_time::Value::Number(value) => {
            Ok(crate::compiler::number_format::javascript_text(*value))
        }
        crate::compile_time::Value::String(value) => {
            if crate::compile_time::has_unbound_formatters(value) {
                return Err(format!("settings string '{value}' has format arguments"));
            }
            Ok(value.clone())
        }
        crate::compile_time::Value::Bool(value) => Ok(value.to_string()),
        // JavaScript `String(value)` on containers, as the pinned evaluator
        // writes them: arrays join their element text with commas, objects
        // string-ify to the literal `[object Object]` (#512).
        crate::compile_time::Value::Array(values) => values
            .iter()
            .map(display_value)
            .collect::<Result<Vec<_>, _>>()
            .map(|text| text.join(",")),
        crate::compile_time::Value::Object(_) => Ok("[object Object]".to_string()),
        crate::compile_time::Value::Vector(_) | crate::compile_time::Value::Null => {
            Err("compile-time value is not a settings value".to_string())
        }
    }
}

/// The number a settings list element spells when the pinned tokenizer
/// reads it as one number token. The reference's word characters are
/// `[A-Za-z0-9_@$]` (no `.` — `1.5` is `1 . 5` merged by the parser, not a
/// token), so a digit-led word like `1_000`, `12abc`, `0o18`, or `5e` is
/// one number token that `Number` converts to `NaN`. `0x` is the one
/// lenient prefix: the reference rewrites it through `parseInt(name, 16)`
/// which reads a hex *prefix*, so `0x1FZ` is 31 while `0x`/`0xZZ` are
/// `NaN`. `0X`/`0o`/`0b` go through `Number` — all digits must be valid
/// (`0o17` is 15, `0o18` and `0X1FZ` are `NaN`; #512).
/// `None` when the element is not such a token (a dot, a sign, or a signed
/// exponent like `1e-7` are separate tokens upstream and take the
/// expression path).
fn js_number_value(text: &str) -> Option<f64> {
    if !text.starts_with(|c: char| c.is_ascii_digit())
        || !text
            .chars()
            .all(|c| c.is_ascii_alphanumeric() || matches!(c, '_' | '@' | '$'))
    {
        return None;
    }
    // `parseInt(name, 16)`: reads the hex prefix; `NaN` without digits.
    if let Some(digits) = text.strip_prefix("0x") {
        let mut value = 0f64;
        let mut seen = false;
        for c in digits.chars() {
            let Some(digit) = c.to_digit(16) else { break };
            value = value * 16.0 + digit as f64;
            seen = true;
        }
        return Some(if seen { value } else { f64::NAN });
    }
    let strict_radix = text
        .strip_prefix("0X")
        .map(|digits| (digits, 16))
        .or_else(|| {
            text.strip_prefix("0o")
                .or_else(|| text.strip_prefix("0O"))
                .map(|digits| (digits, 8))
        })
        .or_else(|| {
            text.strip_prefix("0b")
                .or_else(|| text.strip_prefix("0B"))
                .map(|digits| (digits, 2))
        });
    if let Some((digits, radix)) = strict_radix {
        return Some(
            (!digits.is_empty())
                .then(|| {
                    digits.chars().try_fold(0f64, |value, c| {
                        c.to_digit(radix)
                            .map(|digit| value * radix as f64 + digit as f64)
                    })
                })
                .flatten()
                .unwrap_or(f64::NAN),
        );
    }
    // Whole-token `Number(text)`: unparseable tails yield `NaN`.
    Some(text.parse::<f64>().unwrap_or(f64::NAN))
}

struct Cursor<'a> {
    text: &'a str,
    pos: usize,
    char_pos: usize,
    line: u32,
    col: u32,
    file: u32,
}

impl Cursor<'_> {
    fn new(text: &str, file: u32, origin: Position) -> Cursor<'_> {
        Cursor {
            text,
            pos: 0,
            char_pos: 0,
            line: origin.line,
            col: origin.col,
            file,
        }
    }

    fn peek(&self) -> Option<char> {
        self.peek_at(0)
    }

    fn peek_at(&self, ahead: usize) -> Option<char> {
        self.text[self.pos..].chars().nth(ahead)
    }

    fn here(&self) -> Position {
        Position::new(self.line, self.col)
    }

    fn here_after(&self, n: usize) -> Position {
        let mut line = self.line;
        let mut col = self.col;
        for ch in self.text[self.pos..].chars().take(n) {
            if ch == '\n' {
                line += 1;
                col = 1;
            } else {
                col += 1;
            }
        }
        Position::new(line, col)
    }

    fn advance(&mut self) -> Option<char> {
        let ch = self.peek()?;
        if ch == '\n' {
            self.line += 1;
            self.col = 1;
        } else {
            self.col += 1;
        }
        self.pos += ch.len_utf8();
        self.char_pos += 1;
        Some(ch)
    }

    fn advance_by(&mut self, n: usize) {
        for _ in 0..n {
            if self.advance().is_none() {
                return;
            }
        }
    }

    fn advance_quoted(&mut self, quote: &mut Option<char>, escaped: &mut bool, ch: char) -> bool {
        let Some(quote_char) = *quote else {
            return false;
        };
        if *escaped {
            *escaped = false;
        } else if ch == '\\' {
            *escaped = true;
        } else if ch == quote_char {
            *quote = None;
        }
        self.advance_by(1);
        true
    }

    fn skip_to_eol(&mut self) {
        while self.peek().is_some_and(|ch| ch != '\n') {
            self.advance_by(1);
        }
    }

    fn skip_horizontal_whitespace(&mut self) {
        while matches!(self.peek(), Some(' ' | '\t' | '\r')) {
            self.advance_by(1);
        }
    }

    fn read_word(&mut self) -> String {
        let mut word = String::new();
        while let Some(ch) = self.peek() {
            if !is_ident_continue(ch) {
                break;
            }
            word.push(ch);
            self.advance_by(1);
        }
        word
    }
}

/// Primitive JSONC values before classification as typed settings nodes.
enum ScalarValue {
    String(String),
    Bool(bool),
    Number(f64),
}

impl Cursor<'_> {
    fn skip_whitespace(&mut self) {
        loop {
            while let Some(ch) = self.peek() {
                if ch.is_whitespace() {
                    self.advance();
                } else {
                    break;
                }
            }
            if self.peek() == Some('#') {
                while self.peek().is_some_and(|ch| ch != '\n') {
                    self.advance();
                }
                continue;
            }
            if self.text[self.pos..].starts_with("//") {
                self.advance();
                self.advance();
                while self.peek().is_some_and(|ch| ch != '\n') {
                    self.advance();
                }
                continue;
            }
            if self.text[self.pos..].starts_with("/*") {
                self.advance();
                self.advance();
                while self.peek().is_some() && !self.text[self.pos..].starts_with("*/") {
                    self.advance();
                }
                if self.text[self.pos..].starts_with("*/") {
                    self.advance();
                    self.advance();
                }
                continue;
            }
            break;
        }
    }

    fn error(&self, code: &str, message: String) -> OpyError {
        OpyError::at(
            code,
            message,
            Span::new(self.file, self.here(), self.here()),
        )
    }

    fn error_at(&self, code: &str, message: String, span: Span) -> OpyError {
        OpyError::at(code, message, span)
    }

    fn parse_object(&mut self) -> OpyResult<(Vec<cst::SettingsNode>, Span)> {
        let open = self.here();
        if self.advance() != Some('{') {
            return Err(self.error(
                "settings-invalid",
                "settings block must be a JSONC object".to_string(),
            ));
        }
        let members = self.parse_members(false)?;
        let span = Span::new(self.file, open, self.here());
        Ok((members, span))
    }

    /// Parse `key: value, ...` members. `root` is true when the enclosing
    /// object's braces are the settings block's own braces (the text runs to
    /// the end of the block, and a trailing comma before it is allowed).
    fn parse_members(&mut self, root: bool) -> OpyResult<Vec<cst::SettingsNode>> {
        let mut nodes = Vec::new();
        let mut names = Vec::new();
        self.skip_whitespace();
        if (!root && self.peek() == Some('}')) || (root && self.pos >= self.text.len()) {
            if !root {
                self.advance();
            }
            return Ok(nodes);
        }
        loop {
            self.skip_whitespace();
            let key_start = self.here();
            let key = match self.parse_string_value() {
                Some(value) => value,
                None => {
                    return Err(self.error(
                        "settings-invalid",
                        "settings keys must be quoted strings".to_string(),
                    ));
                }
            };
            let key_span = Span::new(self.file, key_start, self.here());
            if names.contains(&key) {
                return Err(self.error_at(
                    "settings-invalid",
                    format!("duplicate settings key '{key}'"),
                    key_span,
                ));
            }
            names.push(key.clone());
            self.skip_whitespace();
            if self.advance() != Some(':') {
                return Err(self.error_at(
                    "settings-invalid",
                    format!("expected ':' after settings key '{key}'"),
                    key_span,
                ));
            }
            self.skip_whitespace();
            let (node, value_end) = self.parse_value()?;
            let node = build_node(key, node, value_end, key_start, self.file);
            nodes.push(node);
            self.skip_whitespace();
            match self.peek() {
                Some(',') => {
                    self.advance();
                    self.skip_whitespace();
                    if (!root && self.peek() == Some('}')) || (root && self.pos >= self.text.len())
                    {
                        if !root {
                            self.advance();
                        }
                        return Ok(nodes);
                    }
                }
                Some('}') if !root => {
                    self.advance();
                    return Ok(nodes);
                }
                None if root => return Ok(nodes),
                _ => {
                    return Err(self.error(
                        "settings-invalid",
                        "expected ',' or '}' in settings object".to_string(),
                    ));
                }
            }
        }
    }

    /// Parse one value; returns the built node (name placeholder) and the
    /// position after it. A scalar literal, list, or group that is followed
    /// by anything but a member terminator is re-read as one expression —
    /// the pinned evaluator compiles each value as a single expression, so
    /// `"a".charAt(0)`, `[1,2].last()`, `1 in [3]`, and word tails like
    /// `1_000` all evaluate there rather than splitting (#512).
    fn parse_value(&mut self) -> OpyResult<(cst::SettingsNode, Position)> {
        let start = self.here();
        let ch = self.peek();
        let saved = (self.pos, self.char_pos, self.line, self.col);
        let scalar = match ch {
            Some('"') | Some('\'') => {
                let value = self.parse_string_expression().ok_or_else(|| {
                    self.error(
                        "settings-invalid",
                        "unterminated string in settings value".to_string(),
                    )
                })?;
                Some(ScalarValue::String(value))
            }
            Some('t') => {
                self.expect_word("true")?;
                Some(ScalarValue::Bool(true))
            }
            Some('f') => {
                self.expect_word("false")?;
                Some(ScalarValue::Bool(false))
            }
            Some(c) if c.is_ascii_digit() => Some(ScalarValue::Number(self.parse_number()?)),
            // `-` starts a number only before a digit; `-(1+2)` and
            // `-Infinity` are expressions upstream.
            Some('-') if self.peek_at(1).is_some_and(|c| c.is_ascii_digit()) => {
                Some(ScalarValue::Number(self.parse_number()?))
            }
            _ => None,
        };
        let node = if let Some(scalar) = scalar {
            if !self.is_expression_continuation() {
                let span = Span::new(self.file, start, self.here());
                match scalar {
                    ScalarValue::String(value) => cst::SettingsNode::String {
                        name: String::new(),
                        value,
                        span,
                    },
                    ScalarValue::Bool(value) => cst::SettingsNode::Bool {
                        name: String::new(),
                        value,
                        span,
                    },
                    ScalarValue::Number(value) => cst::SettingsNode::Number {
                        name: String::new(),
                        value,
                        span,
                    },
                }
            } else {
                self.pos = saved.0;
                self.char_pos = saved.1;
                self.line = saved.2;
                self.col = saved.3;
                cst::SettingsNode::Raw {
                    name: String::new(),
                    value: self.parse_expression_value(),
                    span: Span::new(self.file, start, self.here()),
                }
            }
        } else {
            match ch {
                Some('[') => {
                    let elements = self.parse_list()?;
                    if self.is_expression_continuation() {
                        self.pos = saved.0;
                        self.char_pos = saved.1;
                        self.line = saved.2;
                        self.col = saved.3;
                        cst::SettingsNode::Raw {
                            name: String::new(),
                            value: self.parse_expression_value(),
                            span: Span::new(self.file, start, self.here()),
                        }
                    } else {
                        cst::SettingsNode::List {
                            name: String::new(),
                            elements,
                            span: Span::new(self.file, start, self.here()),
                        }
                    }
                }
                Some('{') => {
                    let (children, _) = self.parse_object()?;
                    if self.is_expression_continuation() {
                        self.pos = saved.0;
                        self.char_pos = saved.1;
                        self.line = saved.2;
                        self.col = saved.3;
                        cst::SettingsNode::Raw {
                            name: String::new(),
                            value: self.parse_expression_value(),
                            span: Span::new(self.file, start, self.here()),
                        }
                    } else {
                        cst::SettingsNode::Group {
                            name: String::new(),
                            children,
                            span: Span::new(self.file, start, self.here()),
                        }
                    }
                }
                _ => {
                    let value = self.parse_expression_value();
                    if value.trim().is_empty() {
                        return Err(self.error(
                            "settings-invalid",
                            "expected a value in settings block".to_string(),
                        ));
                    }
                    cst::SettingsNode::Raw {
                        name: String::new(),
                        value,
                        span: Span::new(self.file, start, self.here()),
                    }
                }
            }
        };
        let end = self.here();
        Ok((node, end))
    }

    /// Preserve an unquoted setting expression as an opaque value. Commas and
    /// closing braces delimit it only outside nested expression delimiters and
    /// string literals.
    fn parse_expression_value(&mut self) -> String {
        let mut value = String::new();
        let mut depth = 0usize;
        let mut quote = None;
        while let Some(ch) = self.peek() {
            if let Some(expected) = quote {
                value.push(self.advance().expect("peeked character exists"));
                if ch == expected {
                    quote = None;
                }
                continue;
            }
            match ch {
                '"' | '\'' => {
                    quote = Some(ch);
                    value.push(self.advance().expect("peeked character exists"));
                }
                '(' | '[' | '{' => {
                    depth += 1;
                    value.push(self.advance().expect("peeked character exists"));
                }
                ']' | ',' | '}' if depth == 0 => break,
                ')' | ']' | '}' => {
                    depth = depth.saturating_sub(1);
                    value.push(self.advance().expect("peeked character exists"));
                }
                _ => value.push(self.advance().expect("peeked character exists")),
            }
        }
        value.trim().to_string()
    }

    fn expect_word(&mut self, word: &str) -> OpyResult<()> {
        let start = self.here();
        for expected in word.chars() {
            if self.advance() != Some(expected) {
                return Err(self.error_at(
                    "settings-invalid",
                    format!("expected '{word}' in settings block"),
                    Span::new(self.file, start, self.here()),
                ));
            }
        }
        Ok(())
    }

    /// Read one settings number literal the way the pinned OverPy tokenizer
    /// admits it: decimal with an optional unsigned exponent (`1e21`,
    /// `0.5e3`), and `0x`/`0o`/`0b` integer radixes (`0x1F` is 31; #496).
    /// The read stops where the reference's word token would split off an
    /// operator: a `.` needs digits on both sides (`1.5` joins, `2.`/`1.e5`
    /// split at the dot), and an exponent marker needs a fraction digit
    /// before it plus an unsigned digit run after it (`1e-7` keeps its `e`
    /// for the expression path). A radix prefix without digits reads as
    /// `NaN` (`0x`, like `parseInt("0x", 16)`), and any leftover word tail
    /// (`0x1FZ`, `1_000`) makes the whole value an expression through the
    /// continuation check in `parse_value` (#512).
    fn parse_number(&mut self) -> OpyResult<f64> {
        let start = self.here();
        let mut text = String::new();
        if self.peek() == Some('-') {
            text.push(self.advance().unwrap());
        }
        if self.peek() == Some('0')
            && matches!(self.peek_at(1), Some('x' | 'X' | 'o' | 'O' | 'b' | 'B'))
        {
            text.push(self.advance().unwrap());
            let letter = self.advance().expect("radix letter is peeked");
            text.push(letter);
            let radix = match letter {
                'x' | 'X' => 16,
                'o' | 'O' => 8,
                _ => 2,
            };
            let mut value = 0f64;
            let mut digits = 0usize;
            while let Some(c) = self.peek() {
                let Some(digit) = c.to_digit(radix) else {
                    break;
                };
                value = value * radix as f64 + digit as f64;
                digits += 1;
                text.push(self.advance().unwrap());
            }
            // `Number("0x")`/`parseInt("0x", 16)` is `NaN`; a word tail is
            // left for `is_expression_continuation` to send to the
            // expression path (`0x1FZ` is 31 there, `0xZZ` is `NaN`; #512).
            let value = if digits == 0 { f64::NAN } else { value };
            return Ok(if text.starts_with('-') { -value } else { value });
        }
        while let Some(c) = self.peek() {
            if c.is_ascii_digit() {
                text.push(self.advance().unwrap());
            } else {
                break;
            }
        }
        // `.` joins the literal only between digits — `1.5` is one number
        // upstream while `2.` and `-.5` split the dot into member access.
        if self.peek() == Some('.')
            && text.chars().any(|c| c.is_ascii_digit())
            && self.peek_at(1).is_some_and(|c| c.is_ascii_digit())
        {
            text.push(self.advance().unwrap());
            while let Some(c) = self.peek() {
                if c.is_ascii_digit() {
                    text.push(self.advance().unwrap());
                } else {
                    break;
                }
            }
        }
        if matches!(self.peek(), Some('e' | 'E'))
            && self.peek_at(1).is_some_and(|c| c.is_ascii_digit())
        {
            text.push(self.advance().unwrap());
            while let Some(c) = self.peek() {
                if c.is_ascii_digit() {
                    text.push(self.advance().unwrap());
                } else {
                    break;
                }
            }
        }
        text.parse::<f64>().map_err(|_| {
            self.error_at(
                "settings-invalid",
                format!("invalid number '{text}' in settings block"),
                Span::new(self.file, start, self.here()),
            )
        })
    }

    fn parse_list(&mut self) -> OpyResult<Vec<cst::SettingsListElement>> {
        self.advance(); // '['
        let mut elements = Vec::new();
        self.skip_whitespace();
        if self.peek() == Some(']') {
            self.advance();
            return Ok(elements);
        }
        loop {
            self.skip_whitespace();
            let start = self.here();
            let (value, expr) = match self.peek() {
                Some(']') | Some(',') | None => {
                    return Err(self.error(
                        "settings-invalid",
                        "settings list elements must not be empty".to_string(),
                    ));
                }
                _ => {
                    let text = self.parse_expression_value();
                    match js_number_value(&text) {
                        // A bare list element that is a number token writes
                        // its `String(value)` form (`[1e21]` emits `1e+21`,
                        // `[1_000]` emits `NaN`; #496, #512).
                        Some(number) => (
                            crate::compiler::number_format::javascript_text(number),
                            false,
                        ),
                        // Every other element — quoted strings included —
                        // is an expression the pinned settings evaluator
                        // resolves or rejects (`"a"=="a"` emits `true`;
                        // #512).
                        None => (text, true),
                    }
                }
            };
            let span = Span::new(self.file, start, self.here());
            elements.push(cst::SettingsListElement { value, expr, span });
            self.skip_whitespace();
            match self.peek() {
                Some(',') => {
                    self.advance();
                    self.skip_whitespace();
                    if self.peek() == Some(']') {
                        self.advance();
                        return Ok(elements);
                    }
                }
                Some(']') => {
                    self.advance();
                    return Ok(elements);
                }
                _ => {
                    return Err(self.error(
                        "settings-invalid",
                        "expected ',' or ']' in settings list".to_string(),
                    ));
                }
            }
        }
    }

    /// Parse a quoted string value; `None` when no string is here or the
    /// string is unterminated before end-of-line.
    fn parse_string_value(&mut self) -> Option<String> {
        let quote = self.peek()?;
        if quote != '"' && quote != '\'' {
            return None;
        }
        self.advance();
        let mut value = String::new();
        loop {
            let ch = self.advance()?;
            if ch == '\n' {
                return None;
            }
            if ch == quote {
                return Some(value);
            }
            if ch == '\\' {
                let escaped = self.advance()?;
                value.push(decode_string_escape(escaped));
            } else {
                value.push(ch);
            }
        }
    }

    /// Parse adjacent quoted strings as one compile-time string value. This
    /// is the settings equivalent of OPY's implicit string concatenation and
    /// is used after macro expansion has turned identifiers into literals.
    fn parse_string_expression(&mut self) -> Option<String> {
        let mut value = self.parse_string_value()?;
        loop {
            let saved = (self.pos, self.char_pos, self.line, self.col);
            self.skip_whitespace();
            if self.peek() != Some('"') && self.peek() != Some('\'') {
                self.pos = saved.0;
                self.char_pos = saved.1;
                self.line = saved.2;
                self.col = saved.3;
                break;
            }
            let next = self.parse_string_value()?;
            value.push_str(&next);
        }
        Some(value)
    }

    /// Whether anything but a member terminator (`,`, `}`, or the end of
    /// the block) follows the value just parsed. The pinned evaluator
    /// compiles each settings value as one expression, so a suffix like
    /// `.charAt(0)`, `[0]`, `in [3]`, `and 2`, or a word tail (`1_000`,
    /// `0x1FZ`) means the value is an expression, not the parsed literal
    /// (#512). Lookahead only; does not move the cursor.
    fn is_expression_continuation(&self) -> bool {
        self.text[self.pos..]
            .trim_start()
            .chars()
            .next()
            .is_some_and(|c| c != ',' && c != '}')
    }
}

/// Attach the key name and a key..value span to a parsed value node.
fn build_node(
    key: String,
    node: cst::SettingsNode,
    value_end: Position,
    key_start: Position,
    file: u32,
) -> cst::SettingsNode {
    let span = Span::new(file, key_start, value_end);
    match node {
        cst::SettingsNode::Group { children, .. } => cst::SettingsNode::Group {
            name: key,
            children,
            span,
        },
        cst::SettingsNode::Number { value, .. } => cst::SettingsNode::Number {
            name: key,
            value,
            span,
        },
        cst::SettingsNode::Bool { value, .. } => cst::SettingsNode::Bool {
            name: key,
            value,
            span,
        },
        cst::SettingsNode::String { value, .. } => cst::SettingsNode::String {
            name: key,
            value,
            span,
        },
        cst::SettingsNode::Raw { value, .. } => cst::SettingsNode::Raw {
            name: key,
            value,
            span,
        },
        cst::SettingsNode::List { elements, .. } => cst::SettingsNode::List {
            name: key,
            elements,
            span,
        },
    }
}

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

    fn block(text: &str) -> SettingsBlock {
        let mut blocks = find_blocks(text, 0).unwrap();
        assert_eq!(blocks.len(), 1, "one block expected in: {text}");
        blocks.pop().unwrap()
    }

    #[test]
    fn finds_block_after_comments_and_blanks() {
        let text = "/* header */\n# comment\n\nsettings {\n    \"gamemodes\": {}\n}\nrule \"r\":\n";
        let found = block(text);
        assert!(found.text.contains("gamemodes"));
        assert_eq!(found.keyword_span.start.line, 4);
        assert_eq!(found.span.end.line, 6);
    }

    #[test]
    fn no_blocks_for_plain_program() {
        assert!(
            find_blocks("rule \"r\":\n    pass\n", 0)
                .unwrap()
                .is_empty()
        );
    }

    #[test]
    fn ignores_settings_words_in_strings_and_indented_code() {
        let text = "rule \"settings\":\n    x = \"settings\"\n";
        assert!(find_blocks(text, 0).unwrap().is_empty());
    }

    #[test]
    fn settings_after_constructs_is_extracted() {
        // The pinned reference accepts `settings` as the first token of any
        // logical line, with no ordering or indentation requirement (#513).
        let text = "playervar score\n\nrule \"r\":\n    pass\n\nsettings {\n}\n";
        let found = block(text);
        assert_eq!(found.keyword_span.start.line, 6);

        // An indented `settings` inside a block body is still the statement.
        let found = block("rule \"r\":\n    pass\n    settings {\n    }\n");
        assert_eq!(found.keyword_span.start.line, 3);
    }

    #[test]
    fn settings_inside_brackets_is_an_ordinary_token() {
        // Inside a bracketed expression a `settings` line start does not open
        // a block; the text reaches the lexer and the parser rejects it.
        let text = "globalvar g = [\n    1,\nsettings]\n";
        assert!(find_blocks(text, 0).unwrap().is_empty());

        // A `settings` mid-line after a non-colon token is not a statement.
        assert!(
            find_blocks("globalvar g = settings {}\n", 0)
                .unwrap()
                .is_empty()
        );
    }

    #[test]
    fn settings_in_an_inline_tail_is_extracted() {
        // The reference parses the `:` tail of a header line as a nested
        // logical line, so its first token is a statement position (#513).
        let found = block("rule \"r\":\n    pass\n\nrule \"t\": settings {\n}\n");
        assert_eq!(found.keyword_span.start.line, 4);
    }

    #[test]
    fn settings_inside_an_enum_body_is_extracted() {
        // Recorded divergence: the reference absorbs a `settings` line inside
        // an enum body as a member named `settings`; we extract it as the
        // settings block (see docs/architecture/language-core.md).
        let found = block("enum E:\n    A\n    settings {\n    }\n");
        assert_eq!(found.keyword_span.start.line, 3);
    }

    #[test]
    fn second_block_is_placement_error() {
        let error =
            find_blocks("settings {\n    \"gamemodes\": {}\n}\nsettings {\n}\n", 0).unwrap_err();
        assert_eq!(error.code, "settings-placement");
        assert_eq!(error.span.unwrap().start.line, 4);
    }

    #[test]
    fn settings_file_form_is_extracted() {
        let found = block("settings \"file.opy.json\"\n");
        assert_eq!(found.external_path.as_deref(), Some("file.opy.json"));
    }

    #[test]
    fn unterminated_block_is_invalid() {
        let error = find_blocks("settings {\n    \"gamemodes\": {\n", 0).unwrap_err();
        assert_eq!(error.code, "settings-invalid");
    }

    #[test]
    fn braces_inside_strings_do_not_unbalance() {
        let found =
            block("settings {\n    \"description\": \"a { b }\",\n    \"gamemodes\": {}\n}\n");
        assert!(found.text.contains("a { b }"));
    }

    #[test]
    fn sanitize_preserves_post_block_positions() {
        let text = "settings {\n    \"gamemodes\": {}\n}\nrule \"r\":\n    pass\n";
        let found = block(text);
        let sanitized = sanitize_for_lex(text, &found);
        let lines: Vec<&str> = sanitized.lines().collect();
        assert_eq!(lines.len(), 5);
        assert_eq!(lines[3], "rule \"r\":");
        assert_eq!(lines[4], "    pass");
        // The rule keyword is at the same char offset as in the original.
        assert_eq!(sanitized.find("rule"), text.find("rule"));
    }

    #[test]
    fn unicode_preserves_offsets_and_sanitization() {
        let text = "# 前置🙂\nsettings {\n    \"main\": { \"description\": \"内🙂\" },\n    \"gamemodes\": {}\n}\nrule \"后🙂\":\n    pass\n";
        let found = block(text);
        let keyword_byte_offset = text.find("settings").unwrap();
        let closing_byte_offset = text.find("}\nrule").unwrap();
        assert_eq!(found.start, text[..keyword_byte_offset].chars().count());
        assert_eq!(
            found.end,
            text[..closing_byte_offset + '}'.len_utf8()].chars().count()
        );
        assert_eq!(found.keyword_span.start, Position::new(2, 1));
        assert_eq!(found.text_start, Position::new(2, 11));
        assert!(found.text.contains("内🙂"));

        let sanitized = sanitize_for_lex(text, &found);
        assert_eq!(sanitized.chars().count(), text.chars().count());
        let rule_char_offset = |source: &str| {
            let byte_offset = source.find("rule").unwrap();
            source[..byte_offset].chars().count()
        };
        assert_eq!(rule_char_offset(&sanitized), rule_char_offset(text));
        assert!(sanitized.contains("rule \"后🙂\":"));
    }

    #[test]
    fn non_object_after_settings_is_invalid() {
        // `settings [..]` is rejected at extraction (a `{` is required).
        let error = find_blocks("settings [1, 2]\n", 0).unwrap_err();
        assert_eq!(error.code, "settings-invalid");
    }

    #[test]
    fn parse_block_rejects_missing_gamemodes() {
        let found = block("settings {\n    \"main\": { \"description\": \"x\" }\n}\n");
        let error = parse_block(&found).unwrap_err();
        assert_eq!(error.code, "settings-invalid");
        assert!(error.message.contains("gamemodes"));
    }

    #[test]
    fn parse_block_rejects_duplicate_keys() {
        let found = block("settings {\n    \"gamemodes\": {},\n    \"gamemodes\": {}\n}\n");
        let error = parse_block(&found).unwrap_err();
        assert_eq!(error.code, "settings-invalid");
        assert!(error.message.contains("duplicate"));
    }

    #[test]
    fn parse_block_accepts_trailing_commas() {
        let found = block(
            "settings {\n    \"gamemodes\": {\n        \"general\": {\n            \"heroLimit\": \"off\",\n        },\n    },\n}\n",
        );
        let parsed = parse_block(&found).unwrap();
        assert_eq!(parsed.children.len(), 1);
    }

    #[test]
    fn parse_block_handles_escapes_and_quotes() {
        let found = block(
            "settings {\n    \"main\": { \"description\": \"line\\n\\t\\\"quoted\\\"\" },\n    \"gamemodes\": {}\n}\n",
        );
        let parsed = parse_block(&found).unwrap();
        let cst::SettingsNode::Group { children, .. } = &parsed.children[0] else {
            panic!("main group");
        };
        let cst::SettingsNode::String { value, .. } = &children[0] else {
            panic!("description");
        };
        assert_eq!(value, "line\n\t\"quoted\"");
    }

    #[test]
    fn parse_block_accepts_comments_and_expression_values() {
        let found = block(
            "settings {\n    # keep the source expression intact\n    \"lobby\": {\n        \"modeName\": GAMEMODE_NAME\" \"GAMEMODE_VERSION,\n    },\n    \"gamemodes\": {}\n}\n",
        );
        let parsed = parse_block(&found).unwrap();
        let cst::SettingsNode::Group { children, .. } = &parsed.children[0] else {
            panic!("lobby group");
        };
        let cst::SettingsNode::Raw { value, .. } = &children[0] else {
            panic!("expression-valued setting");
        };
        assert_eq!(value, "GAMEMODE_NAME\" \"GAMEMODE_VERSION");
    }

    #[test]
    fn parse_block_reads_javascript_number_literals() {
        // The pinned OverPy tokenizer reads exponent and `0x`/`0o`/`0b`
        // integer forms in settings (#496).
        let found = block(
            "settings {\n    \"lobby\": { \"a\": 0x1F, \"b\": 0b101, \"c\": 0o17, \"d\": 1.5e21, \"e\": 12e2, \"f\": -0.5, \"g\": 2.5e1 },\n    \"gamemodes\": {}\n}\n",
        );
        let parsed = parse_block(&found).unwrap();
        let cst::SettingsNode::Group { children, .. } = &parsed.children[0] else {
            panic!("lobby group");
        };
        let values: Vec<f64> = children
            .iter()
            .map(|node| match node {
                cst::SettingsNode::Number { value, .. } => *value,
                other => panic!("{other:?}"),
            })
            .collect();
        assert_eq!(values, [31.0, 5.0, 15.0, 1.5e21, 1200.0, -0.5, 25.0]);
    }

    #[test]
    fn parse_block_routes_signed_exponents_to_the_expression_path() {
        // The pinned settings tokenizer splits an exponent sign or a
        // fraction-less dot out as an operator, so `1e-7`, `1e+21`,
        // `-2.5e-3`, and `1.e5` are expressions — the parser keeps them
        // raw and the settings evaluator rejects them downstream (#512).
        for value in ["1e-7", "1e+21", "-2.5e-3", "0.5e+3", "1.e5", "0.e5"] {
            let found = block(&format!(
                "settings {{\n    \"lobby\": {{ \"k\": {value} }},\n    \"gamemodes\": {{}}\n}}\n"
            ));
            let parsed = parse_block(&found).unwrap();
            let cst::SettingsNode::Group { children, .. } = &parsed.children[0] else {
                panic!("lobby group");
            };
            let cst::SettingsNode::Raw { value: raw, .. } = &children[0] else {
                panic!("{value} must parse as a raw expression: {children:?}");
            };
            assert_eq!(raw, value);
        }
    }

    #[test]
    fn parse_block_types_values() {
        let found = block(
            "settings {\n    \"lobby\": { \"ffaSlots\": 6 },\n    \"gamemodes\": { \"general\": { \"enableRandomHeroes\": true, \"respawnTime%\": 30, \"heroLimit\": \"off\" } },\n    \"heroes\": { \"allTeams\": { \"enabledHeroes\": [\"mei\"] } }\n}\n",
        );
        let parsed = parse_block(&found).unwrap();
        let lobby = match &parsed.children[0] {
            cst::SettingsNode::Group { name, children, .. } => {
                assert_eq!(name, "lobby");
                children
            }
            other => panic!("{other:?}"),
        };
        assert!(matches!(
            lobby[0],
            cst::SettingsNode::Number { value: 6.0, .. }
        ));
    }

    #[test]
    fn spans_are_computed_from_block_base() {
        let text = "settings {\n    \"lobby\": {\n        \"ffaSlots\": 6\n    },\n    \"gamemodes\": {}\n}\n";
        let found = block(text);
        let parsed = parse_block(&found).unwrap();
        let cst::SettingsNode::Group { children, .. } = &parsed.children[0] else {
            panic!("lobby");
        };
        let cst::SettingsNode::Number { span, .. } = &children[0] else {
            panic!("ffaSlots");
        };
        assert_eq!(span.start.line, 3);
        assert_eq!(span.start.col, 9);
    }

    #[test]
    fn keyword_span_carries_the_file_id() {
        let found = block("settings {\n    \"gamemodes\": {}\n}\n");
        assert_eq!(found.keyword_span.file, 0);
        assert_eq!(found.keyword_span.start.col, 1);
        assert_eq!(found.keyword_span.end.col, 9);
    }
}