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 expression = lowerer
                .lower(
                    &value,
                    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 =
                crate::compile_time::evaluate(&expression, constants, &HashMap::new(), &mut stack)
                    .ok_or_else(|| {
                        settings_expression_error(
                            diag_span,
                            "expression is not a compile-time value".to_string(),
                        )
                    })?;
            node_from_value(name, value, diag_span)
        }
        node => Ok(node),
    }
}

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 {
        crate::compile_time::Value::Number(value) if value.is_finite() => {
            hir::SettingsNode::Number {
                name,
                value,
                span: Some(span.into()),
            }
        }
        crate::compile_time::Value::Number(_) => {
            return Err(settings_expression_error(
                span,
                "compile-time number is not finite".to_string(),
            ));
        }
        crate::compile_time::Value::String(value) => 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| {
                    Ok(hir::SettingsListElement {
                        value: display_value(&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()),
        },
    };
    Ok(node)
}

fn display_value(value: &crate::compile_time::Value) -> Result<String, String> {
    match value {
        crate::compile_time::Value::Number(value) if value.is_finite() => {
            Ok(crate::compiler::number_format::javascript_text(*value))
        }
        crate::compile_time::Value::String(value) => Ok(value.clone()),
        crate::compile_time::Value::Bool(value) => Ok(value.to_string()),
        _ => Err("settings list can only contain primitive values".to_string()),
    }
}

/// The number literal a settings value token spells as JavaScript's
/// `Number` reads it: decimal and exponent forms plus `0x`/`0o`/`0b`
/// radixes, with an optional leading sign. `None` for non-number tokens.
fn js_number_literal(text: &str) -> Option<f64> {
    // `f64::parse` also admits spellings like `inf` and `NaN` that the pinned
    // tokenizer reads as names, not literals; only a digit, dot, or sign can
    // start a JavaScript number here.
    if !text
        .trim_start_matches(['-', '+'])
        .chars()
        .next()
        .is_some_and(|c| c.is_ascii_digit() || c == '.')
    {
        return None;
    }
    // The reference's number reader requires a fraction digit before an
    // exponent marker (`1.e5`); Rust accepts it, so gate the spelling out —
    // an unrecognized literal keeps its authored text.
    if !text.contains(".e") && !text.contains(".E") {
        if let Ok(value) = text.parse::<f64>() {
            return Some(value);
        }
    }
    let (negative, rest) = if let Some(rest) = text.strip_prefix('-') {
        (true, rest)
    } else {
        (false, text.strip_prefix('+').unwrap_or(text))
    };
    let digits = rest
        .strip_prefix("0x")
        .or_else(|| rest.strip_prefix("0X"))
        .map(|digits| (digits, 16))
        .or_else(|| {
            rest.strip_prefix("0o")
                .or_else(|| rest.strip_prefix("0O"))
                .map(|digits| (digits, 8))
        })
        .or_else(|| {
            rest.strip_prefix("0b")
                .or_else(|| rest.strip_prefix("0B"))
                .map(|digits| (digits, 2))
        });
    let (digits, radix) = digits?;
    if digits.is_empty() {
        return None;
    }
    let value = digits.chars().try_fold(0f64, |value, c| {
        c.to_digit(radix)
            .map(|digit| value * radix as f64 + digit as f64)
    })?;
    Some(if negative { -value } else { value })
}
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.
    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() || c == '-' => {
                Some(ScalarValue::Number(self.parse_number()?))
            }
            _ => None,
        };
        let node = if let Some(scalar) = scalar {
            self.skip_inline_whitespace();
            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 {
                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 {
            match ch {
                Some('[') => {
                    let elements = self.parse_list()?;
                    cst::SettingsNode::List {
                        name: String::new(),
                        elements,
                        span: Span::new(self.file, start, self.here()),
                    }
                }
                Some('{') => {
                    let (children, _) = self.parse_object()?;
                    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).
    /// An exponent marker needs a fraction digit before it (`1.e5` is the
    /// reference's "Expected a number after '.'" error).
    /// A signed exponent (`1e-7`, `1e+21`) is not read — the reference
    /// tokenizer splits the sign out as an operator and errors, so leaving
    /// the `e` behind reproduces its rejection through the object parser.
    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());
            }
            if digits == 0 || self.peek().is_some_and(|c| c.is_ascii_alphanumeric()) {
                return Err(self.error_at(
                    "settings-invalid",
                    format!("invalid number '{text}' in settings block"),
                    Span::new(self.file, start, self.here()),
                ));
            }
            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;
            }
        }
        if self.peek() == Some('.') {
            text.push(self.advance().unwrap());
            let mut fraction = 0usize;
            while let Some(c) = self.peek() {
                if c.is_ascii_digit() {
                    text.push(self.advance().unwrap());
                    fraction += 1;
                } else {
                    break;
                }
            }
            // The reference requires a fraction digit before an exponent
            // marker: `1.e5` is its "Expected a number after '.'" error.
            if fraction == 0 && matches!(self.peek(), Some('e' | 'E')) {
                return Err(self.error_at(
                    "settings-invalid",
                    format!("invalid number '{text}' in settings block"),
                    Span::new(self.file, start, self.here()),
                ));
            }
        }
        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 = match self.peek() {
                Some('"') | Some('\'') => self.parse_string_expression().ok_or_else(|| {
                    self.error(
                        "settings-invalid",
                        "unterminated string in settings list".to_string(),
                    )
                })?,
                Some(']') | Some(',') | None => {
                    return Err(self.error(
                        "settings-invalid",
                        "settings list elements must not be empty".to_string(),
                    ));
                }
                _ => {
                    let value = self.parse_expression_value();
                    // A bare list element that is a number literal writes its
                    // `String(value)` form (`[1e21]` emits `1e+21`; #496).
                    js_number_literal(&value)
                        .map(crate::compiler::number_format::javascript_text)
                        .unwrap_or(value)
                }
            };
            let span = Span::new(self.file, start, self.here());
            elements.push(cst::SettingsListElement { value, 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)
    }

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

    fn is_expression_continuation(&self) -> bool {
        if matches!(
            self.peek(),
            Some('+' | '-' | '*' | '/' | '%' | '<' | '>' | '=')
        ) {
            return true;
        }
        ["and", "or", "if"].iter().any(|word| {
            self.text[self.pos..]
                .strip_prefix(word)
                .is_some_and(|rest| {
                    rest.chars().next().is_none_or(|character| {
                        !character.is_ascii_alphanumeric() && character != '_'
                    })
                })
        })
    }
}

/// 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_rejects_signed_exponents_like_the_pinned_reference() {
        // The pinned settings tokenizer splits an exponent sign out as an
        // operator and errors (`1e-7`, `1e+21`, `-2.5e-3`; #496), and it
        // requires a fraction digit before an exponent marker (`1.e5`).
        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 error = parse_block(&found).unwrap_err();
            assert_eq!(error.code, "settings-invalid", "{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);
    }
}