formatter.oc

//* The ocen code formatter (v2)
//*
//* Architecture:
//*   - Doc IR layer: Wadler-Lindig style intermediate representation
//*     (Text, Line, SoftLine, Indent, Group, IfBreak, Concat).
//*     Width-aware renderer (doc_render) decides group breaking.
//*     build_collection_doc() demonstrates end-to-end Doc IR pipeline.
//*
//*   - Plan/Emit separation: formatting decisions are computed in a
//*     planning phase (plan_collection, plan_params) producing typed
//*     plan structs, then emitted separately (emit_collection, emit_params).
//*     No decisions are made during the emission phase.
//*
//*   - Pure decision functions: should_break_collection(), etc.
//*     decouple policy from traversal. Source-shape-driven currently,
//*     but designed to accept width budgets for future line-length rules.
//*
//*   - FormatOptions: centralized config (indent_size, line_width, etc.)
//*
//*   - CommentIndex: O(1) comment lookups by line number.
//*
//*   - Range reconstruction: helper methods (emit_source_lines,
//*     emit_formatted_lines, emit_mapping_substitution, filter_leaf_mappings,
//*     reconstruct_range) with validate_mappings() debug assertions.
//*
//*   - Consolidated patterns: emit_item_preamble() unifies the
//*     blank-line/comment preamble logic across format_block/format_struct.

import std::buffer::{ Buffer }
import std::vector::{ Vector }
import std::span::{ Span, Location }
import std::sv::{ SV }
import std::mem
import std::fs
import std::{ shift_args }
import std::sort::{ sort_by }
import std::libc::{ memset }
import @ast::nodes::{ * }
import @ast::program::{ Namespace, Program, CompilerOption }
import @ast::operators::{ Operator }
import @ast::scopes::{ Symbol, SymbolType }
import @tokens::{ Token, TokenType, Comment }
import @types::{ Type, BaseType, FunctionType, ArrayType }
import @parser::{ Parser }
import @lexer::{ Lexer }
import @errors::{ Error }
import @attributes::{ AttributeType }

//! Doc IR: Intermediate representation for formatting decisions.
//!
//! Instead of emitting text directly while walking the AST, we can
//! build a tree of Doc nodes that describe the *intent* of the
//! formatting. A renderer then decides how to lay out the output,
//! choosing whether to break groups based on line width constraints.
//!
//! This is the same fundamental approach used by Prettier, Wadler-
//! Lindig, and other modern formatters.
enum DocKind {
    Text      //! Literal text (no newlines)
    Line      //! Hard line break — always newline + indent
    SoftLine  //! Newline if group breaks, else space
    SoftEmpty //! Newline if group breaks, else nothing
    Concat    //! Sequence of child docs
    DocIndent //! Increase indent for child
    Group     //! Try to fit on one line; break if too wide
    IfBreak   //! Choose between break/flat alternatives
}

union DocUnion {
    text: str
    children: &Vector<&Doc>
    child: &Doc
    if_break: DocIfBreak
}

struct DocIfBreak {
    break_doc: &Doc
    flat_doc: &Doc
}

struct Doc {
    kind: DocKind
    u: DocUnion
}

// Allocate a Doc on the heap with the given kind
def Doc::make(kind: DocKind): &Doc {
    let d = mem::alloc<Doc>()
    d.kind = kind
    return d
}

def Doc::new_text(s: str): &Doc {
    let d = Doc::make(DocKind::Text)
    d.u.text = s
    return d
}

def Doc::new_line(): &Doc => Doc::make(DocKind::Line)

def Doc::new_softline(): &Doc => Doc::make(DocKind::SoftLine)

def Doc::new_softline_empty(): &Doc => Doc::make(DocKind::SoftEmpty)

def Doc::new_concat(parts: &Vector<&Doc>): &Doc {
    let d = Doc::make(DocKind::Concat)
    d.u.children = parts
    return d
}

def Doc::new_indent(inner: &Doc): &Doc {
    let d = Doc::make(DocKind::DocIndent)
    d.u.child = inner
    return d
}

def Doc::new_group(inner: &Doc): &Doc {
    let d = Doc::make(DocKind::Group)
    d.u.child = inner
    return d
}

def Doc::new_if_break(break_doc: &Doc, flat_doc: &Doc): &Doc {
    let d = Doc::make(DocKind::IfBreak)
    d.u.if_break.break_doc = break_doc
    d.u.if_break.flat_doc = flat_doc
    return d
}

// Join docs with a separator
def doc_join(items: &Vector<&Doc>, sep: &Doc): &Doc {
    let parts = Vector<&Doc>::new()
    for let i = 0u32; i < items.size; i++ {
        if i > 0 then parts.push(sep)
        parts.push(items.at(i))
    }
    return Doc::new_concat(parts)
}

// Build a list of docs into a single concat
def doc_list(): &Vector<&Doc> => Vector<&Doc>::new()

// Render mode for the doc printer
enum RenderMode {
    Flat  // Try to fit everything on one line
    Break // Break at soft line breaks
}

// A command on the render stack
struct RenderCommand {
    indent: u32
    mode: RenderMode
    doc: &Doc
}

// Measure flat width of a Doc (returns -1 if it contains a hard Line)
def doc_flat_width(doc: &Doc): i32 {
    match doc.kind {
        Text => return doc.u.text.len() as i32
        Line => return -1
        SoftLine => return 1  // space in flat mode
        SoftEmpty => return 0 // nothing in flat mode
        Concat => {
            let total = 0i32
            for let i = 0u32; i < doc.u.children.size; i++ {
                let w = doc_flat_width(doc.u.children.at(i))
                if w < 0 then return -1
                total += w
            }
            return total
        }
        DocIndent => return doc_flat_width(doc.u.child)
        Group => return doc_flat_width(doc.u.child)
        IfBreak => return doc_flat_width(doc.u.if_break.flat_doc)
    }
    return 0
}

// Render a Doc tree to a Buffer.
//
// The algorithm uses a stack-based approach (Wadler-Lindig):
// - Push commands onto the stack in reverse order
// - For each Group, check if the flat version fits in remaining width
// - If it fits, render in Flat mode; otherwise, in Break mode
def doc_render(doc: &Doc, indent_size: u32, line_width: u32): str {
    let out = Buffer::make()
    let stack = Vector<RenderCommand>::new()
    stack.push(RenderCommand(indent: 0, mode: RenderMode::Break, doc))

    let col = 0u32

    while stack.size > 0 {
        let cmd = stack.pop()
        match cmd.doc.kind {
            Text => {
                out += cmd.doc.u.text
                col += cmd.doc.u.text.len()
            }
            Line => {
                out += '\n'
                for let i = 0u32; i < cmd.indent * indent_size; i++ {
                    out += ' '
                }
                col = cmd.indent * indent_size
            }
            SoftLine => {
                if cmd.mode == RenderMode::Break {
                    out += '\n'
                    for let i = 0u32; i < cmd.indent * indent_size; i++ {
                        out += ' '
                    }
                    col = cmd.indent * indent_size
                } else {
                    out += ' '
                    col += 1
                }
            }
            SoftEmpty => {
                if cmd.mode == RenderMode::Break {
                    out += '\n'
                    for let i = 0u32; i < cmd.indent * indent_size; i++ {
                        out += ' '
                    }
                    col = cmd.indent * indent_size
                }
                // flat mode: emit nothing
            }
            Concat => {
                let parts = cmd.doc.u.children
                // Push in reverse order so first part is processed first
                for let i = parts.size; i > 0; i-- {
                    stack.push(RenderCommand(indent: cmd.indent, mode: cmd.mode, doc: parts.at(i - 1)))
                }
            }
            DocIndent => {
                stack.push(RenderCommand(indent: cmd.indent + 1, mode: cmd.mode, doc: cmd.doc.u.child))
            }
            Group => {
                // Check if flat version fits remaining line width
                let flat_w = doc_flat_width(cmd.doc.u.child)
                let fits = flat_w >= 0 and (col + flat_w as u32) <= line_width
                let group_mode = if fits then RenderMode::Flat else RenderMode::Break
                stack.push(RenderCommand(indent: cmd.indent, mode: group_mode, doc: cmd.doc.u.child))
            }
            IfBreak => {
                let chosen = if cmd.mode == RenderMode::Break {
                    yield cmd.doc.u.if_break.break_doc
                } else {
                    yield cmd.doc.u.if_break.flat_doc
                }

                stack.push(RenderCommand(indent: cmd.indent, mode: cmd.mode, doc: chosen))
            }
        }
    }

    return out.str()
}

//! Centralized formatting options.
//! All formatting decisions should be routed through this struct
//! to make it easy to add new options in the future.
struct FormatOptions {
    indent_size: u32
    line_width: u32 // Target line width for group breaking (0 = disabled)
}

def FormatOptions::default(): FormatOptions {
    return FormatOptions(
        indent_size: 4,
        line_width: 0 // 0 = use source-shape heuristics only (no width-aware breaking)
    )
}

//* Check if line-width-aware formatting is enabled
def FormatOptions::width_enabled(&this): bool => .line_width > 0

//! Decision functions: pure policy for formatting choices.
//!
//! These decouple "should we break?" from the AST traversal logic.
//! Currently source-shape-driven (matching existing behavior), but
//! the interface is designed to accept width budgets for future
//! line-length-aware formatting.
// Decide whether a collection (call args, array literal, etc.)
// should be formatted in multiline mode.
//
// Parameters:
//   start_line/end_line: source span of the collection
//   has_comments: whether there are inline comments in the range
//   options: formatting options (for future width-aware decisions)
//
// Current policy: break if multi-line in source AND has inline comments.
// This preserves existing behavior. Future: also break when content
// exceeds options.line_width.
def should_break_collection(start_line: u32, end_line: u32, has_comments: bool, options: &FormatOptions): bool {
    return start_line != end_line and has_comments
}

// Decide whether a vector/map literal should break.
// Current policy: break if multi-line in source (always, regardless of comments).
def should_break_list_literal(start_line: u32, end_line: u32, options: &FormatOptions): bool {
    return start_line != end_line
}

// Decide whether function parameters should be multiline.
// Current policy: break if params span multiple lines AND have inline comments.
def should_break_params(first_param_line: u32, last_param_line: u32, has_comments: bool, options: &FormatOptions): bool {
    return last_param_line > first_param_line and has_comments
}

// Decide whether a binary op RHS should be on the next line.
// Current policy: break if RHS starts on a different line than the operator.
def should_break_binary_rhs(op_line: u32, rhs_start_line: u32, in_format_str: bool, options: &FormatOptions): bool {
    return rhs_start_line > op_line and not in_format_str
}

//! Formatting plans: separate decision-making from emission.
//!
//! A plan captures all formatting choices for a construct (multiline,
//! trailing commas, etc.) as a pure data structure. The emission
//! phase then reads the plan without making any further decisions.
//!
//! This separation allows:
//! - Testing decisions independently from text generation
//! - Future Doc IR generation from the same plan
//! - Width-aware re-planning without changing emission logic
struct CollectionPlan {
    multiline: bool // Whether to break items across multiple lines
    size: u32       // Number of items in the collection
    open: str       // Opening delimiter
    close: str      // Closing delimiter
}

// Plan for formatting function parameters
struct ParamPlan {
    multiline: bool   // Whether to break params across multiple lines
    param_count: u32  // Number of parameters
    is_variadic: bool // Whether function has variadic "..."
}

//! A tagged union to represent a top-level declaration in source order
enum DeclType {
    Function
    Structure
    Enum
    Constant
    Variable
    Import
    Namespace
    TypeDef
    CompilerOpt
}

struct TypeDefInfo {
    name: str
    type: &Type
    span: Span
}

struct Decl {
    type: DeclType
    line: u32
    col: u32
    u: DeclUnion
}

union DeclUnion {
    func: &Function
    struc: &Structure
    enom: &Enum
    var_node: &AST
    import_node: &AST
    ns: &Namespace
    type_def: TypeDefInfo
    compiler_opt: CompilerOption
}

struct DeclMapping {
    source_start: u32
    source_end: u32
    output_start: u32
    output_end: u32
}

//* Get the end line of a declaration from its span
def decl_end_line(decl: &Decl): u32 => match decl.type {
    Function => decl.u.func.span.end.line
    Structure => decl.u.struc.span.end.line
    Enum => decl.u.enom.span.end.line
    Constant | Variable => decl.u.var_node.span.end.line
    Import => decl.u.import_node.span.end.line
    Namespace => decl.u.ns.span.end.line
    TypeDef => decl.u.type_def.span.end.line
    CompilerOpt => decl.u.compiler_opt.span.end.line
}

//! Per-line comment index for O(1) lookups.
//! Maps line numbers to indices in the comment array,
//! avoiding expensive linear scans for comment queries.
struct CommentIndex {
    // For each line, the indices of comments on that line.
    // line_to_comments[line] gives a vector of comment indices.
    line_to_comments: &Vector<&Vector<u32>>
    // Total number of lines
    num_lines: u32
}

def CommentIndex::build(all_comments: &Vector<Comment>, num_lines: u32): CommentIndex {
    let line_to_comments = Vector<&Vector<u32>>::new()
    // Pre-allocate for all lines (1-indexed, so num_lines+1)
    for let i = 0u32; i <= num_lines; i++ {
        line_to_comments.push(Vector<u32>::new())
    }
    for let i = 0u32; i < all_comments.size; i++ {
        let line = all_comments.at(i).span.start.line
        if line <= num_lines {
            line_to_comments.at(line).push(i)
        }
    }
    return CommentIndex(line_to_comments, num_lines)
}

//* Get all comment indices on a given line
def CommentIndex::comments_on_line(&this, line: u32): &Vector<u32> {
    if line > .num_lines then return Vector<u32>::new()
    return .line_to_comments.at(line)
}

struct Formatter {
    output: Buffer
    indent: u32
    options: FormatOptions
    source: str
    line_offsets: &Vector<u32>
    filename: str
    comments: &Vector<Comment>
    comment_index: u32
    program: &Program
    ns: &Namespace

    // Range formatting fields
    range_start: u32 // Start line of range (0 = no range, format all)
    range_end: u32   // End line of range (0 = no range)
    output_line: u32 // Tracks current output line (1-based)
    decl_mappings: &Vector<DeclMapping>
    stmt_mappings: &Vector<DeclMapping> // Statement-level source↔output mappings
    track_stmts: bool                   // Whether to record stmt_mappings in format_block

    in_format_str: bool = false // Suppress multi-line formatting inside format strings
    in_binary_continuation: bool = false // Track if we're in a binary op continuation indent
    ic_lines: &Vector<u32>      // Output line numbers of emitted inline comments
    last_comment_request_line: u32
    debug_cursor: bool
    cursor_regressions: u32
    comment_emitted: &Vector<bool>   // Track which comments have been emitted
    comment_line_index: CommentIndex // Per-line comment index for O(1) lookups
    output_col: u32 // Current column in the output (0-based)
}

//* Snapshot of comment-related state, used by measurement functions.
//* Measurement must not permanently advance the comment cursor or mark
//* comments as emitted, since the measured text is discarded.
struct CommentState {
    comment_index: u32
    last_comment_request_line: u32
    cursor_regressions: u32
    emitted_snapshot: &Vector<bool>
}

//* Save the current comment-tracking state so it can be restored after
//* a dry-run measurement pass.
//*
//* When in_format_str=true (measurement mode), emit_inline_comment and
//* emit_comments_before are no-ops, so comment_emitted is never modified.
//* In that case we skip the expensive deep-copy and store null for
//* emitted_snapshot as a sentinel. restore_comment_state checks for null
//* and skips the restore loop accordingly.
def Formatter::save_comment_state(&this): CommentState {
    if .in_format_str {
        // Fast path: comment state cannot be modified during measurement.
        return CommentState(
            comment_index: .comment_index,
            last_comment_request_line: .last_comment_request_line,
            cursor_regressions: .cursor_regressions,
            emitted_snapshot: null,
        )
    }
    // Slow path: deep-copy for non-measurement callers (e.g. capture_collection_item).
    let snapshot = Vector<bool>::new()
    for let i = 0u32; i < .comment_emitted.size; i++ {
        snapshot.push(.comment_emitted.at(i))
    }
    return CommentState(
        comment_index: .comment_index,
        last_comment_request_line: .last_comment_request_line,
        cursor_regressions: .cursor_regressions,
        emitted_snapshot: snapshot,
    )
}

//* Restore comment-tracking state saved by save_comment_state.
def Formatter::restore_comment_state(&this, state: &CommentState) {
    .comment_index = state.comment_index
    .last_comment_request_line = state.last_comment_request_line
    .cursor_regressions = state.cursor_regressions
    if state.emitted_snapshot? {
        for let i = 0u32; i < state.emitted_snapshot.size; i++ {
            .comment_emitted.data[i] = state.emitted_snapshot.at(i)
        }
    }
}

def build_line_offsets(source: str): &Vector<u32> {
    let offsets = Vector<u32>::new()
    offsets.push(0)
    for let i = 0u32; source[i] != '\0'; i++ {
        if source[i] == '\n' {
            offsets.push(i + 1)
        }
    }
    return offsets
}

def Formatter::make(program: &Program, ns: &Namespace, source: str, filename: str): Formatter {
    let debug_cursor_env = std::libc::getenv("OCEN_FORMAT_DEBUG_CURSOR")
    let debug_cursor = debug_cursor_env? and debug_cursor_env.len() > 0
    // Filter comments to only include those from the current file
    let filtered = Vector<Comment>::new()
    for comment in program.comments.iter() {
        if comment.span.start.filename.eq(filename) {
            filtered.push(comment)
        }
    }
    let emitted = Vector<bool>::new()
    for let i = 0u32; i < filtered.size; i++ {
        emitted.push(false)
    }
    let line_offsets = build_line_offsets(source)
    let num_lines = line_offsets.size as u32
    let comment_line_index = CommentIndex::build(filtered, num_lines)
    return Formatter(output: Buffer::make(), indent: 0, options: FormatOptions::default(), source, line_offsets, filename, comments: filtered, comment_index: 0, program, ns, range_start: 0, range_end: 0, output_line: 1, decl_mappings: Vector<DeclMapping>::new(), stmt_mappings: Vector<DeclMapping>::new(), track_stmts: false, ic_lines: Vector<u32>::new(), last_comment_request_line: 0, debug_cursor: debug_cursor, cursor_regressions: 0, comment_emitted: emitted, comment_line_index: comment_line_index, output_col: 0)
}

def Formatter::note_cursor_regression(&this, kind: str, requested: u32) {
    .cursor_regressions++
    if .debug_cursor {
        eprintln("[formatter] comment cursor regression (%s): requested=%u, last=%u, file=%s", kind, requested, .last_comment_request_line, .filename)
    }
}

//* Write raw string to output
def Formatter::write(&this, s: str) {
    .output += s
    // Optimised column/line tracking: find the last newline (if any) in a
    // single pass instead of doing a branch + output_col++ on every char.
    // Common case (no newlines): just add string length to output_col.
    let len = s.len() as u32
    let last_nl = -1i32
    for let i = 0u32; i < len; i++ {
        if s[i] == '\n' {
            .output_line++
            last_nl = i as i32
        }
    }
    if last_nl < 0 {
        .output_col += len
    } else {
        .output_col = len - (last_nl as u32) - 1
    }
}

//* Write a newline
def Formatter::newline(&this) {
    .output += '\n'
    .output_line++
    .output_col = 0
}

def Formatter::push_indent(&this) {
    .indent++
}

def Formatter::pop_indent(&this) {
    assert .indent > 0, "Formatter indent underflow"
    .indent--
}

//* Write indentation at current level
def Formatter::write_indent(&this) {
    let spaces = .indent * .options.indent_size
    if spaces > 0 {
        // Use memset for fast space-filling instead of per-char appends.
        .output.resize_if_necessary(.output.size + spaces)
        memset(.output.data + .output.size, ' ' as u8, spaces)
        .output.size += spaces
    }
    .output_col = spaces
}

//* Begin a continuation break. Used when a single statement or expression
//* won't fit on the current line and needs to break to the next line with
//* one extra level of indentation. Must be paired with end_continuation().
def Formatter::begin_continuation(&this) {
    .newline()
    .push_indent()
    .write_indent()
}

//* End a continuation break started by begin_continuation().
def Formatter::end_continuation(&this) {
    .pop_indent()
}

//* Begin a continuation break for binary operators. Similar to
//* begin_continuation() but tracks the in_binary_continuation flag to
//* prevent double-indenting chained binary operators (e.g. a + b + c
//* should only get one continuation indent, not one per operator).
//* Returns the previous in_binary_continuation value which must be
//* passed to end_binary_continuation().
def Formatter::begin_binary_continuation(&this): bool {
    .newline()
    let saved = .in_binary_continuation
    if not .in_binary_continuation {
        .push_indent()
        .in_binary_continuation = true
    }
    .write_indent()
    return saved
}

//* End a binary continuation break. Pass the value returned by
//* begin_binary_continuation(). Only pops indent if we actually pushed
//* it, and restores the in_binary_continuation flag.
def Formatter::end_binary_continuation(&this, saved: bool) {
    if not saved {
        .pop_indent()
    }
    .in_binary_continuation = saved
}

//* Measure how wide an expression would be if formatted on a single line.
//* Returns the width in characters (not including any leading indentation).
//* This uses buffer capture - it temporarily swaps the output buffer.
def Formatter::measure_expr(&this, node: &AST): u32 {
    let saved_output = .output
    let saved_line = .output_line
    let saved_col = .output_col
    let saved_in_fmt = .in_format_str
    // Set in_format_str=true BEFORE save_comment_state so it can skip the
    // expensive deep-copy (emit_* functions are no-ops when in_format_str).
    .in_format_str = true
    let saved_comments = .save_comment_state()
    let saved_ic_size = .ic_lines.size
    .output = Buffer::make()
    .output_line = 1
    .output_col = 0
    .format_expr(node)
    let width = .output_col
    // For multi-line expressions (e.g. if-then-else with block body),
    // output_col reflects only the last line (e.g. "}").  Use the first
    // line's width instead, since that's the line that determines whether
    // the expression fits inline.
    if .output_line > 1 {
        let buf = .output.str()
        for let c = 0u32; buf[c] != '\0'; c++ {
            if buf[c] == '\n' {
                width = c
                break
            }
        }
    }
    .output = saved_output
    .output_line = saved_line
    .output_col = saved_col
    .in_format_str = saved_in_fmt
    .restore_comment_state(&saved_comments)
    // Discard any ic_lines entries added during measurement
    .ic_lines.size = saved_ic_size
    return width
}

//* Measure how wide a statement would be if formatted on a single line.
def Formatter::measure_statement(&this, node: &AST): u32 {
    let saved_output = .output
    let saved_line = .output_line
    let saved_col = .output_col
    let saved_in_fmt = .in_format_str
    // Set in_format_str=true BEFORE save so the save skips the expensive deep-copy.
    .in_format_str = true
    let saved_comments = .save_comment_state()
    let saved_ic_size = .ic_lines.size
    .output = Buffer::make()
    .output_line = 1
    .output_col = 0
    .format_statement(node)
    let width = .output_col
    // For multi-line statements, use the first line's width.
    if .output_line > 1 {
        let buf = .output.str()
        for let c = 0u32; buf[c] != '\0'; c++ {
            if buf[c] == '\n' {
                width = c
                break
            }
        }
    }
    .output = saved_output
    .output_line = saved_line
    .output_col = saved_col
    .in_format_str = saved_in_fmt
    .restore_comment_state(&saved_comments)
    // Discard any ic_lines entries added during measurement
    .ic_lines.size = saved_ic_size
    return width
}

//* Measure the width of import parts as if formatted on a single line.

def Formatter::measure_import_parts(&this, parts: &Vector<&ImportPart>): u32 {
    let w = 0u32
    for let i = 0u32; i < parts.size; i++ {
        if i > 0 then w += 2 // "::"
        let part = parts.at(i)
        match part.type {
            Single => {
                w += part.u.single.name.len() as u32
                if part.u.single.alias? {
                    w += 4 + part.u.single.alias.len() as u32 // " as X"
                }
            }
            Multiple => {
                w += 4 // "{ " + " }"
                for let j = 0u32; j < part.u.multiple.paths.size; j++ {
                    if j > 0 then w += 2 // ", "
                    w += .measure_import_parts(part.u.multiple.paths.at(j))
                }
            }
            Wildcard => w += 1
        }
    }
    return w
}

//* Measure the width of a match condition as if formatted on a single line.
def Formatter::measure_match_cond(&this, cond: &MatchCond): u32 {
    let w = .measure_expr(cond.expr)
    if cond.args? and cond.args.size > 0 {
        w += 2 // "()"
        for let i = 0u32; i < cond.args.size; i++ {
            if i > 0 then w += 2 // ", "
            w += cond.args.at(i).var.sym.name.len() as u32
        }
    }
    return w
}

//* Check if the current output column plus additional text would exceed line width.
//* Returns false if line_width is 0 (disabled).
def Formatter::would_exceed_width(&this, additional: u32): bool {
    if not .options.width_enabled() then return false
    return (.output_col + additional) > .options.line_width
}

//* Get the remaining width on the current line.
//* Returns a large number if line_width is 0 (disabled).
def Formatter::remaining_width(&this): u32 {
    if not .options.width_enabled() then return 10000u32
    if .output_col >= .options.line_width then return 0u32
    return .options.line_width - .output_col
}

//* Measure the full width of a collection as if formatted on one line.
//* For Calls: callee(arg1, arg2, arg3)
//* For Arrays: [elem1, elem2, elem3]
//* etc.
def Formatter::measure_collection(&this, node: &AST, open: str, close: str): u32 {
    let size = .collection_size(node)
    let width = open.len() + close.len()
    // Set in_format_str=true once before the loop so that:
    //  (a) save_comment_state uses the fast shallow path (no deep-copy), and
    //  (b) emit_* are no-ops, meaning comment state never changes between items.
    // We therefore need only ONE save/restore wrapping the whole loop.
    let saved_in_fmt = .in_format_str
    .in_format_str = true
    let saved_comments = .save_comment_state()
    let saved_ic_size = .ic_lines.size
    for let i = 0u32; i < size; i++ {
        if i > 0 then width += 2 // ", "
        let saved_output = .output
        let saved_line = .output_line
        let saved_col = .output_col
        .output = Buffer::make()
        .output_line = 1
        .output_col = 0
        .format_collection_item(node, i)
        width += .output_col
        .output = saved_output
        .output_line = saved_line
        .output_col = saved_col
    }
    .in_format_str = saved_in_fmt
    .restore_comment_state(&saved_comments)
    .ic_lines.size = saved_ic_size
    return width
}

//* Measure the full width of function params as if on one line.
//* e.g.: (a: u32, b: str, c: bool)
def Formatter::measure_params(&this, func: &Function): u32 {
    let width = 2u32 // "(" + ")"
    // Set in_format_str=true once before the loop (same rationale as measure_collection).
    let saved_in_fmt = .in_format_str
    .in_format_str = true
    let saved_comments = .save_comment_state()
    let saved_ic_size = .ic_lines.size
    for let i = 0u32; i < func.params.size; i++ {
        if i > 0 then width += 2 // ", "
        let saved_output = .output
        let saved_line = .output_line
        let saved_col = .output_col
        .output = Buffer::make()
        .output_line = 1
        .output_col = 0
        .format_param(func.params.at(i), is_first: i == 0)
        width += .output_col
        .output = saved_output
        .output_line = saved_line
        .output_col = saved_col
    }
    if func.is_variadic {
        if func.params.size > 0 then width += 2 // ", "
        width += 3 // "..."
    }
    .in_format_str = saved_in_fmt
    .restore_comment_state(&saved_comments)
    .ic_lines.size = saved_ic_size
    return width
}

//* Get source text for a span
def Formatter::source_text(&this, span: Span): str {
    let text = .program.get_source_text(span)
    if not text? then return ""
    return text
}

//* Check if a function has an explicitly written return type.
//* The parser synthesizes return types for functions without explicit ones,
//* using the function name span. We detect this by checking if the return
//* type span location matches the function name span location.
def Formatter::has_explicit_return_type(&this, func: &Function): bool {
    if not func.parsed_return_type? then return false
    if func.parsed_return_type.base == BaseType::Void then return false
    // When no explicit return type is given, the parser synthesizes one using
    // the function name span. Check if the spans share the same position.
    let rt_start = func.parsed_return_type.span.start
    let name_start = func.sym.span.start
    if rt_start.line == name_start.line and rt_start.col == name_start.col then return false
    return true
}

def Formatter::is_implicit_void_function_type(&this, type: &Type): bool {
    if not type? or not type.u.func.return_type? then return false
    let return_type = type.u.func.return_type
    if return_type.base != BaseType::Unresolved then return false
    if not return_type.u.unresolved? or return_type.u.unresolved.type != Identifier then return false
    if not return_type.u.unresolved.u.ident.name.eq("void") then return false
    return return_type.span.start.line == type.span.start.line and return_type.span.start.col == type.span.start.col
}

//* Emit comments that appear before `line`.
//* When preserve_blanks is true, preserve source blank lines between emitted comments.
//* Returns end line of the last emitted non-inline comment, or prev_end_line when none.
def Formatter::emit_comments_before(&this, line: u32, preserve_blanks: bool = false, prev_end_line: u32 = 0): u32 {
    // During dry-run measurement (in_format_str), don't modify comment state.
    if .in_format_str then return prev_end_line
    if line < .last_comment_request_line {
        .note_cursor_regression("before", line)
    }
    if line > .last_comment_request_line {
        .last_comment_request_line = line
    }
    let comment_end = prev_end_line
    while .comment_index < .comments.size {
        let comment = .comments.at(.comment_index)
        if comment.span.start.line >= line then break
        if comment.is_inline {
            .comment_index++
            continue
        }
        if preserve_blanks and comment_end > prev_end_line and comment.span.start.line > comment_end + 1 {
            .newline()
        }
        .write_indent()
        .write(comment.text)
        .newline()
        .comment_emitted.data[.comment_index] = true
        comment_end = comment.span.end.line
        .comment_index++
    }
    return comment_end
}

//* Emit any inline comment on the given line
def Formatter::emit_inline_comment(&this, line: u32) {
    // During dry-run measurement (in_format_str), don't modify comment state.
    if .in_format_str then return
    if line < .last_comment_request_line {
        .note_cursor_regression("inline", line)
        // Backward scan: search for un-emitted inline comments on this line
        .emit_inline_comment_backward(line)
        return
    }
    if line > .last_comment_request_line {
        .last_comment_request_line = line
    }
    let emitted = false
    while .comment_index < .comments.size {
        let comment = .comments.at(.comment_index)

        // If the cursor lags behind on inline comments from earlier lines,
        // skip them so they do not block inline comments on the current line.
        if comment.span.start.line < line {
            if comment.is_inline {
                .comment_index++
                continue
            }
            break
        }

        if comment.span.start.line > line then break
        if not comment.is_inline {
            break
        }

        if not emitted {
            .ic_lines.push(.output_line)
            emitted = true
        }
        .write(" ")
        .write(comment.text)
        .comment_emitted.data[.comment_index] = true
        .comment_index++
    }
}

//* Backward scan for inline comments when cursor regression detected.
//* Uses the comment line index for efficient O(k) lookup instead of linear scan.
def Formatter::emit_inline_comment_backward(&this, line: u32) {
    let emitted = false
    // Use indexed lookup: get all comment indices on this line
    let indices = .comment_line_index.comments_on_line(line)
    for let i = 0u32; i < indices.size; i++ {
        let ci = indices.at(i)
        let comment = .comments.at(ci)
        if comment.is_inline and not .comment_emitted.at(ci) {
            if not emitted {
                .ic_lines.push(.output_line)
                emitted = true
            }
            .write(" ")
            .write(comment.text)
            .comment_emitted.data[ci] = true
        }
    }
}

//* Emit any remaining comments, optionally limited to before `max_line`
//* When max_line is 0, emit all remaining comments (for top-level namespace)
def Formatter::emit_remaining_comments(&this, max_line: u32 = 0, prev_end_line: u32 = 0) {
    let prev_end = prev_end_line
    while .comment_index < .comments.size {
        let comment = .comments.at(.comment_index)
        // Use >= so inline comments on the closing brace line itself remain
        // available for the caller's emit_inline_comment call.
        if max_line > 0 and comment.span.start.line >= max_line then break
        if comment.is_inline {
            .comment_index++
            continue
        }
        if prev_end > 0 and comment.span.start.line > prev_end + 1 {
            .newline()
        }
        .write_indent()
        .write(comment.text)
        .newline()
        .comment_emitted.data[.comment_index] = true
        prev_end = comment.span.end.line
        .comment_index++
    }
}

//* Check if any inline comments exist in the given line range
def Formatter::has_inline_comments_in_range(&this, start_line: u32, end_line: u32): bool {
    if .in_format_str then return false
    for let ci = .comment_index; ci < .comments.size; ci++ {
        let comment = .comments.at(ci)
        if comment.span.start.line > end_line then break
        if comment.span.start.line >= start_line and comment.is_inline then return true
    }
    return false
}

//* Check if there is an un-emitted inline comment on the given line.
//* Uses CommentIndex for efficient O(k) lookup where k = comments on this line.
def Formatter::has_unemitted_inline_comment(&this, line: u32): bool {
    if .in_format_str then return false
    let indices = .comment_line_index.comments_on_line(line)
    for let i = 0u32; i < indices.size; i++ {
        let ci = indices.at(i)
        let comment = .comments.at(ci)
        if comment.is_inline and not .comment_emitted.at(ci) {
            return true
        }
    }
    return false
}

//* Check if there are any un-emitted inline comments in a line range.
//* Uses CommentIndex for efficient lookup.
def Formatter::has_unemitted_inline_comment_in_range(&this, start_line: u32, end_line: u32): bool {
    if .in_format_str then return false
    for let line = start_line; line <= end_line; line++ {
        let indices = .comment_line_index.comments_on_line(line)
        for let i = 0u32; i < indices.size; i++ {
            let ci = indices.at(i)
            let comment = .comments.at(ci)
            if comment.is_inline and not .comment_emitted.at(ci) {
                return true
            }
        }
    }
    return false
}

//* Emit all un-emitted inline comments in a line range.
//* Uses CommentIndex for efficient lookup.
def Formatter::emit_all_unemitted_inline_comments_in_range(&this, start_line: u32, end_line: u32) {
    for let line = start_line; line <= end_line; line++ {
        let indices = .comment_line_index.comments_on_line(line)
        for let i = 0u32; i < indices.size; i++ {
            let ci = indices.at(i)
            let comment = .comments.at(ci)
            if comment.is_inline and not .comment_emitted.at(ci) {
                .write(" ")
                .write(comment.text)
                .comment_emitted.data[ci] = true
            }
        }
    }
}

//* Check if there is any blank (whitespace-only) line in the source between
//* after_line and before_line (exclusive). Lines are 1-based.
def Formatter::has_blank_source_line_between(&this, after_line: u32, before_line: u32): bool {
    if before_line <= after_line + 1 then return false
    if .line_offsets.size == 0 then return false
    let total_lines = .line_offsets.size
    let start_line = after_line + 1
    if start_line > total_lines then return false
    let end_line = before_line - 1
    if end_line > total_lines {
        end_line = total_lines
    }
    if start_line > end_line then return false
    for let line = start_line; line <= end_line; line++ {
        let start_idx = .line_offsets.at(line - 1)
        let end_idx = .source.len()
        if line < .line_offsets.size {
            end_idx = .line_offsets.at(line) - 1
        }

        let is_blank = true
        for let i = start_idx; i < end_idx; i++ {
            if not .source[i].is_space() {
                is_blank = false
                break
            }
        }
        if is_blank then return true
    }
    return false
}

def Formatter::format_extern_attr(&this, sym: &Symbol) {
    if not sym.is_extern then return
    .write_indent()
    .write("[extern")
    if sym.extern_name? and not sym.extern_name.eq(sym.name) {
        .write(" \"")
        .write(sym.extern_name)
        .write("\"")
    }
    .write("]")
    .newline()
}

def Formatter::format_template_params(&this, sym: &Symbol) {
    if not sym.template? then return
    .write("<")
    let tmpl = sym.template
    for let i = 0u32; i < tmpl.params.size; i++ {
        if i > 0 then .write(", ")
        .write(tmpl.params.at(i).name)
    }
    .write(">")
}

def Formatter::write_attr_line(&this, attr: str) {
    .write_indent()
    .write("[")
    .write(attr)
    .write("]")
    .newline()
}

def Formatter::first_item_or_comment_line(&this, prev_end_line: u32, item_start_line: u32): u32 {
    let next_line = item_start_line
    if .comment_index < .comments.size {
        let comment = .comments.at(.comment_index)
        if comment.span.start.line < next_line and comment.span.start.line > prev_end_line {
            next_line = comment.span.start.line
        }
    }
    return next_line
}

//* Emit blank line separators and leading comments before a block/struct item.
//*
//* This consolidates the duplicated pattern that appears in format_block,
//* format_struct, and similar constructs: check for blank line gap,
//* emit comments with blank preservation, and emit post-comment blank.
//*
//* Returns the updated prev_end_line for tracking gaps.
def Formatter::emit_item_preamble(&this, item_start_line: u32, item_index: u32, prev_end_line: u32): u32 {
    let next_line = .first_item_or_comment_line(prev_end_line, item_start_line)
    if next_line > prev_end_line + 1 {
        // For subsequent items, always emit blank when there's a line gap.
        // For the first item, only emit blank if the source has a blank line
        // (e.g. blank line after opening brace).
        if item_index > 0 or .has_blank_source_line_between(prev_end_line, next_line) {
            .newline()
        }
    }
    let comment_end = .emit_comments_before(item_start_line, preserve_blanks: true, prev_end_line: prev_end_line)
    if comment_end > prev_end_line and item_start_line > comment_end + 1 {
        .newline()
    }
    return comment_end
}

def Formatter::format_top_level_var_decl(&this, node: &AST, keyword: str) {
    let var = node.u.var_decl
    if var.is_atomic {
        .write_attr_line("atomic")
    }
    .write_indent()
    if var.sym.is_extern {
        .write("[extern")
        if var.sym.extern_name? and not var.sym.extern_name.eq(var.sym.name) {
            .write(" \"")
            .write(var.sym.extern_name)
            .write("\"")
        }
        .write("] ")
    }
    .write_var_decl(var, keyword)
    .emit_inline_comment(node.span.start.line)
    .newline()
}

def Formatter::write_var_decl(&this, var: &Variable, keyword: str) {
    .write(keyword)
    .write(" ")
    .write(var.sym.name)
    if var.parsed_type? {
        .write(": ")
        .write(.format_type(var.parsed_type))
    }
    if var.default_value? {
        // Width-aware: check if RHS would fit on same line.
        // Only break at '=' when the RHS is NOT a breakable collection
        // (calls, arrays, etc. handle their own breaking).
        if .options.width_enabled() and not .in_format_str {
            let rhs_width = .measure_expr(var.default_value)
            if .would_exceed_width(3 + rhs_width) { // 3 for " = "
                let rhs = var.default_value
                // Check if the RHS can handle its own breaking
                // (collections with items, binary ops, etc.)
                let is_breakable = false
                if rhs.type == BinaryOp {
                    is_breakable = true
                } else if rhs.type == Call and rhs.u.call.args.size > 0 {
                    is_breakable = true
                } else if rhs.type == ArrayLiteral and rhs.u.array_literal.elements.size > 0 {
                    is_breakable = true
                } else if rhs.type == VectorLiteral and rhs.u.vec_literal.elements.size > 0 {
                    is_breakable = true
                } else if rhs.type == MapLiteral and rhs.u.map_literal.elements.size > 0 {
                    is_breakable = true
                }
                if not is_breakable {
                    .write(" =")
                    .begin_continuation()
                    .format_expr(var.default_value)
                    .end_continuation()
                    .emit_inline_comment(var.default_value.span.start.line)
                    return
                }
            }
        }
        .write(" = ")
        .format_expr(var.default_value)
    }
}

def Formatter::format_inline_if_body(&this, body: &AST) {
    .write(" {")
    .newline()
    .push_indent()
    .write_indent()
    .format_statement(body)
    .emit_inline_comment(body.span.start.line)
    .newline()
    .pop_indent()
    .write_indent()
    .write("}")
}

def Formatter::format_arrow_body(&this, body: &AST, add_match_trailing_comma: bool = false) {
    if body.type == Block {
        .format_block(body)
        return
    }

    .format_statement(body)
    if add_match_trailing_comma and .match_body_needs_trailing_comma(body) {
        .write(",")
    }
}

def Formatter::format_function_type(&this, type: &Type): str {
    let out = Buffer::make()
    if type.base == BaseType::Closure {
        out += "@"
    }
    out += "fn("
    let func_type = type.u.func
    for let i = 0u32; i < func_type.params.size; i++ {
        if i > 0 then out += ", "
        out += .format_type(func_type.params.at(i).parsed_type)
    }
    if func_type.is_variadic {
        if func_type.params.size > 0 then out += ", "
        out += "..."
    }
    out += ")"
    if func_type.return_type? and not .is_implicit_void_function_type(type) {
        out += ": "
        out += .format_type(func_type.return_type)
    }
    return out.str()
}

//* Format a type as a string.
def Formatter::format_type(&this, type: &Type): str {
    if not type? then return ""
    match type.base {
        BaseType::Pointer => {
            let out = Buffer::make()
            out += "&"
            out += .format_type(type.u.ptr)
            return out.str()
        }
        BaseType::FunctionPtr | BaseType::Closure => {
            return .format_function_type(type)
        }
        BaseType::Array => {
            let out = Buffer::make()
            out += "["
            out += .format_type(type.u.arr.elem_type)
            out += "; "
            out += .source_text(type.u.arr.size_expr.span)
            out += "]"
            return out.str()
        }
        BaseType::VectorShorthand => {
            let out = Buffer::make()
            out += "$["
            out += .format_type(type.u.ptr)
            out += "]"
            return out.str()
        }
        BaseType::MapShorthand => {
            let out = Buffer::make()
            out += "${"
            out += .format_type(type.u.map_types.key)
            out += ": "
            out += .format_type(type.u.map_types.value)
            out += "}"
            return out.str()
        }
        else => return .source_text(type.span)
    }
}

def Formatter::collection_size(&this, node: &AST): u32 => match node.type {
    Call => node.u.call.args.size
    ArrayLiteral => node.u.array_literal.elements.size
    VectorLiteral => node.u.vec_literal.elements.size
    MapLiteral => node.u.map_literal.elements.size
    else => 0
}

def Formatter::collection_item_start_line(&this, node: &AST, i: u32): u32 => match node.type {
    Call => node.u.call.args.at(i).expr.span.start.line
    ArrayLiteral => node.u.array_literal.elements.at(i).span.start.line
    VectorLiteral => node.u.vec_literal.elements.at(i).span.start.line
    MapLiteral => node.u.map_literal.elements[i].key.span.start.line
    else => node.span.start.line
}

def Formatter::collection_item_end_line(&this, node: &AST, i: u32): u32 => match node.type {
    Call => node.u.call.args.at(i).expr.span.end.line
    ArrayLiteral => node.u.array_literal.elements.at(i).span.end.line
    VectorLiteral => node.u.vec_literal.elements.at(i).span.end.line
    MapLiteral => node.u.map_literal.elements[i].value.span.end.line
    else => node.span.end.line
}

def Formatter::format_collection_item(&this, node: &AST, i: u32) {
    match node.type {
        Call => {
            let arg = node.u.call.args.at(i)
            if arg.label? {
                .write(arg.label)
                .write(": ")
            }
            .format_expr(arg.expr)
        }
        ArrayLiteral => .format_expr(node.u.array_literal.elements.at(i))
        VectorLiteral => .format_expr(node.u.vec_literal.elements.at(i))
        MapLiteral => {
            let pair = node.u.map_literal.elements[i]
            .format_expr(pair.key)
            .write(": ")
            .format_expr(pair.value)
        }
        else => {}
    }
}

//* Format a collection item to a string without emitting to the main output.
//* This temporarily swaps the output buffer to capture the formatted text,
//* then restores the original buffer. Used by build_collection_doc to
//* construct Doc IR nodes from formatted item text.
def Formatter::capture_collection_item(&this, node: &AST, i: u32): str {
    let saved_output = .output
    let saved_line = .output_line
    let saved_comments = .save_comment_state()
    let saved_ic_size = .ic_lines.size
    .output = Buffer::make()
    .output_line = 1
    .format_collection_item(node, i)
    let result = .output.str()
    .output = saved_output
    .output_line = saved_line
    .restore_comment_state(&saved_comments)
    .ic_lines.size = saved_ic_size
    return result
}

//* Build a Doc IR tree for a collection.
//*
//* Produces a Group containing:
//*   open + Indent(SoftLine + item1 + "," + SoftLine + item2 + ...) + SoftLine + close
//*
//* When rendered with doc_render():
//* - If everything fits on one line: open + item1 + ", " + item2 + close
//* - If it breaks: open + \n + indent(item1, \n item2, ...) + \n + close
//*
//* NOTE: This does not handle inline comments. When line_width formatting
//* is enabled, comment handling will need integration with the Doc IR.
//* For now, this is available as infrastructure for future use.
def Formatter::build_collection_doc(&this, node: &AST, open: str, close: str): &Doc {
    let size = .collection_size(node)
    if size == 0 {
        return Doc::new_text(`{open}{close}`)
    }

    let parts = doc_list()

    // Build the content: items separated by commas
    let inner_parts = doc_list()
    for let i = 0u32; i < size; i++ {
        if i > 0 {
            inner_parts.push(Doc::new_text(","))
            inner_parts.push(Doc::new_softline())
        }
        inner_parts.push(Doc::new_text(.capture_collection_item(node, i)))
    }

    parts.push(Doc::new_text(open))
    parts.push(Doc::new_indent(Doc::new_concat({
        let p = doc_list()
        p.push(Doc::new_softline_empty())
        p.push(Doc::new_concat(inner_parts))
        yield p
    })))
    parts.push(Doc::new_softline_empty())
    parts.push(Doc::new_text(close))

    return Doc::new_group(Doc::new_concat(parts))
}

//* Compute a collection plan: what delimiter, how many items, multiline or not.
//* This is the "planning" phase — no text is emitted.
def Formatter::plan_collection(&this, node: &AST, open: str, close: str): CollectionPlan {
    let size = .collection_size(node)
    let has_comments = .has_inline_comments_in_range(node.span.start.line, node.span.end.line)

    // Use the appropriate decision function based on node type
    let multiline = match node.type {
        VectorLiteral | MapLiteral => {
            yield should_break_list_literal(node.span.start.line, node.span.end.line, &.options)
        }
        else => {
            yield should_break_collection(node.span.start.line, node.span.end.line, has_comments, &.options)
        }
    }

    // Force multiline when source has blank lines between arguments —
    // collapsing to single-line would lose those blank line separators.
    if not multiline and size > 1 and node.span.start.line != node.span.end.line {
        for let i = 1u32; i < size; i++ {
            let prev_end = .collection_item_end_line(node, i - 1)
            let next_start = .collection_item_start_line(node, i)
            if .has_blank_source_line_between(prev_end, next_start) {
                multiline = true
                break
            }
        }
    }
    // Also force multiline if there's a blank line between last item and close paren
    if not multiline and size > 0 and node.span.start.line != node.span.end.line {
        let last_end = .collection_item_end_line(node, size - 1)
        if .has_blank_source_line_between(last_end, node.span.end.line) {
            multiline = true
        }
    }

    // Width-aware: if not already multiline and line_width is set,
    // check if the collection would exceed line width on one line
    if not multiline and .options.width_enabled() and size > 0 and not .in_format_str {
        let col_width = .measure_collection(node, open, close)
        if .would_exceed_width(col_width) {
            multiline = true
        }
    }

    return CollectionPlan(multiline, size, open, close)
}

//* Emit a collection according to a pre-computed plan.
//* This is the "emission" phase — no decisions are made here.
def Formatter::emit_collection(&this, node: &AST, plan: &CollectionPlan) {
    // Save and reset binary continuation flag so items get their own indent context
    let saved_continuation = .in_binary_continuation
    .in_binary_continuation = false
    if plan.multiline and plan.size > 0 {
        .write(plan.open)
        .newline()
        .push_indent()
        let prev_item_end = node.span.start.line
        for let i = 0u32; i < plan.size; i++ {
            let item_start = .collection_item_start_line(node, i)
            // Preserve blank lines between arguments
            if i > 0 and .has_blank_source_line_between(prev_item_end, item_start) {
                .newline()
            }
            .emit_comments_before(item_start)
            .write_indent()
            .format_collection_item(node, i)
            if i + 1 < plan.size then .write(",")
            .emit_inline_comment(.collection_item_end_line(node, i))
            .newline()
            prev_item_end = .collection_item_end_line(node, i)
        }
        // Preserve blank line between last item and closing paren
        if prev_item_end > 0 and .has_blank_source_line_between(prev_item_end, node.span.end.line) {
            .newline()
        }
        .pop_indent()
        .write_indent()
        .write(plan.close)
        .in_binary_continuation = saved_continuation
        return
    }

    .write(plan.open)
    for let i = 0u32; i < plan.size; i++ {
        if i > 0 then .write(", ")
        .format_collection_item(node, i)
    }
    .write(plan.close)
    .in_binary_continuation = saved_continuation
}

//* Convenience: plan + emit a collection in one call (for callers that
//* don't need to inspect or modify the plan).
def Formatter::format_collection_items(&this, node: &AST, open: str, close: str, multiline: bool) {
    // Legacy interface: build a plan from the provided multiline flag
    let plan = CollectionPlan(multiline, size: .collection_size(node), open, close)
    .emit_collection(node, &plan)
}

//* Compute a parameter formatting plan.
//* This is the "planning" phase — no text is emitted.
def Formatter::plan_params(&this, func: &Function): ParamPlan {
    let multiline = false
    if func.params.size > 0 {
        let first_line = func.params.at(0).sym.span.start.line
        let last_param = func.params.at(func.params.size - 1)
        let last_line = last_param.sym.span.start.line
        if func.is_variadic and func.variadic_span.start.line > last_line {
            last_line = func.variadic_span.start.line
        }
        let has_comments = .has_inline_comments_in_range(first_line, last_line)
        multiline = should_break_params(first_line, last_line, has_comments, &.options)

        // Width-aware: if not already multiline and line_width is set,
        // check if the params would exceed line width on one line
        if not multiline and .options.width_enabled() {
            let param_width = .measure_params(func)
            if .would_exceed_width(param_width) {
                multiline = true
            }
        }
    }
    return ParamPlan(multiline, param_count: func.params.size, is_variadic: func.is_variadic)
}

//* Emit function parameters according to a pre-computed plan.
//* This is the "emission" phase — no decisions are made here.
def Formatter::emit_params(&this, func: &Function, plan: &ParamPlan) {
    .write("(")
    if plan.multiline {
        .newline()
        .push_indent()
        for let i = 0u32; i < plan.param_count; i++ {
            .write_indent()
            .format_param(func.params.at(i), is_first: i == 0)
            .write(",")
            .emit_inline_comment(func.params.at(i).sym.span.start.line)
            .newline()
        }
        if plan.is_variadic {
            .write_indent()
            .write("...")
            .emit_inline_comment(func.variadic_span.start.line)
            .newline()
        }
        .pop_indent()
        .write_indent()
    } else {
        for let i = 0u32; i < plan.param_count; i++ {
            if i > 0 then .write(", ")
            .format_param(func.params.at(i), is_first: i == 0)
        }
        if plan.is_variadic {
            if plan.param_count > 0 then .write(", ")
            .write("...")
        }
    }

    .write(")")
}

//* Get the printed width of a binary operator (including surrounding spaces).
//* e.g., " + " => 3, " and " => 5
def binary_op_width(op: Operator): u32 => match op {
    Assignment | PlusEquals | MinusEquals | MultiplyEquals | DivideEquals => 3
    LeftShiftEquals | RightShiftEquals => 4
    Equals | NotEquals | LessThan | LessThanEquals | GreaterThan | GreaterThanEquals => 3
    Plus | Minus | Multiply | Divide | Modulus => 3
    And | In => 5
    Or => 4
    BitwiseAnd | BitwiseOr | BitwiseXor => 3
    LeftShift | RightShift => 4
    else => 3
}

//* Format an expression to string
def Formatter::format_expr(&this, node: &AST) {
    if not node? then return
    // Preserve parentheses from the source
    if node.paren {
        .write("(")
        // Temporarily clear paren flag to avoid double-wrapping, and strip the
        // outer parens from the span. The span was set to include the enclosing
        // `(` and `)` characters when the node was parsed; if we don't strip
        // them, `source_text(node.span)` for leaf nodes (e.g. IntLiteral)
        // would re-emit the `(...)` and the explicit write above would produce
        // double parens on every format pass.
        node.paren = false
        let saved_continuation = .in_binary_continuation
        .in_binary_continuation = false
        let old_span = node.span
        let inner_start = old_span.start
        let inner_end = old_span.end
        inner_start.index += 1u32
        inner_start.col += 1u32
        inner_end.index -= 1u32
        inner_end.col -= 1u32
        node.span = Span(inner_start, inner_end)
        .format_expr(node)
        node.span = old_span
        .in_binary_continuation = saved_continuation
        node.paren = true
        .write(")")
        return
    }

    match node.type {
        BoolLiteral => {
            if node.u.bool_literal {
                .write("true")
            } else {
                .write("false")
            }
        }
        IntLiteral | FloatLiteral => {
            let span = node.span
            if node.u.num_literal.suffix? {
                span = span.join(node.u.num_literal.suffix.span)
            }
            .write(.source_text(span))
        }
        StringLiteral => {
            .write(.source_text(node.span))
        }
        CharLiteral => {
            .write(.source_text(node.span))
        }
        FormatStringLiteral => {
            let fmt = node.u.fmt_str
            // Determine the original delimiter style from the source
            let src = .source_text(node.span)
            let is_backtick = src[0] == '`'
            if is_backtick {
                .write("`")
            } else {
                .write("f\"")
            }

            let saved_in_fmt = .in_format_str
            .in_format_str = true
            for let i = 0u32; i < fmt.parts.size; i++ {
                .write(fmt.parts.at(i))
                if i < fmt.exprs.size {
                    .write("{")
                    .format_expr(fmt.exprs.at(i))
                    let spec = fmt.specs.at(i)
                    if spec? {
                        .write(":")
                        .write(spec)
                    }
                    .write("}")
                }
            }
            .in_format_str = saved_in_fmt
            if is_backtick {
                .write("`")
            } else {
                .write("\"")
            }
        }
        Null => .write("null")
        Identifier => {
            .write(node.u.ident.name)
        }
        NSLookup => {
            .format_expr(node.u.lookup.lhs)
            .write("::")
            .write(node.u.lookup.rhs_name)
        }
        Member => {
            if node.u.member.dot_shorthand {
                .write(".")
                .write(node.u.member.rhs_name)
            } else {
                .format_expr(node.u.member.lhs)
                .write(".")
                .write(node.u.member.rhs_name)
            }
        }
        TryMember => {
            .format_expr(node.u.member.lhs)
            .write("?.")
            .write(node.u.member.rhs_name)
        }
        BinaryOp => {
            let op = node.u.binary.op
            match op {
                Index => {
                    .format_expr(node.u.binary.lhs)
                    .write("[")
                    .format_expr(node.u.binary.rhs)
                    .write("]")
                    return
                }
                IndexAssign => {
                    // binary.lhs is the original Index expression (e.g., buf[len])
                    // binary.rhs is the value being assigned (e.g., '\0')
                    .format_expr(node.u.binary.lhs)
                    .write(" = ")
                    .format_expr(node.u.binary.rhs)
                    return
                }
                else => {}
            }
            .format_expr(node.u.binary.lhs)

            // Check if this binary op should break to next line
            let op_line = node.u.binary.op_span.start.line
            let rhs_start_line = node.u.binary.rhs.span.start.line
            let is_multiline = should_break_binary_rhs(op_line, rhs_start_line, .in_format_str, &.options)

            // Width-aware: if not already multiline, check if the RHS
            // would push past the line width. We check after the operator
            // width is accounted for.
            if not is_multiline and .options.width_enabled() and not .in_format_str {
                let rhs_width = .measure_expr(node.u.binary.rhs)
                let op_w = binary_op_width(op)
                if .would_exceed_width(op_w + rhs_width) {
                    // Check if the RHS can handle its own breaking
                    // (collections with items break naturally without
                    // needing to break at the operator)
                    let rhs = node.u.binary.rhs
                    let rhs_breakable = false
                    if rhs.type == Call and rhs.u.call.args.size > 0 {
                        rhs_breakable = true
                    } else if rhs.type == ArrayLiteral and rhs.u.array_literal.elements.size > 0 {
                        rhs_breakable = true
                    } else if rhs.type == VectorLiteral and rhs.u.vec_literal.elements.size > 0 {
                        rhs_breakable = true
                    } else if rhs.type == MapLiteral and rhs.u.map_literal.elements.size > 0 {
                        rhs_breakable = true
                    }
                    if not rhs_breakable {
                        is_multiline = true
                    }
                }
            }

            // Write the operator. When breaking to next line, omit the trailing
            // space to avoid trailing whitespace on the line.
            if is_multiline {
                match op {
                    Assignment => .write(" =")
                    PlusEquals => .write(" +=")
                    MinusEquals => .write(" -=")
                    MultiplyEquals => .write(" *=")
                    DivideEquals => .write(" /=")
                    LeftShiftEquals => .write(" <<=")
                    RightShiftEquals => .write(" >>=")
                    Equals => .write(" ==")
                    NotEquals => .write(" !=")
                    LessThan => .write(" <")
                    LessThanEquals => .write(" <=")
                    GreaterThan => .write(" >")
                    GreaterThanEquals => .write(" >=")
                    Plus => .write(" +")
                    Minus => .write(" -")
                    Multiply => .write(" *")
                    Divide => .write(" /")
                    Modulus => .write(" %")
                    And => .write(" and")
                    Or => .write(" or")
                    In => .write(" in")
                    BitwiseAnd => .write(" &")
                    BitwiseOr => .write(" |")
                    BitwiseXor => .write(" ^")
                    LeftShift => .write(" <<")
                    RightShift => .write(" >>")
                    else => {
                        .write(" ")
                        .write(.source_text(node.u.binary.op_span))
                    }
                }
                .emit_inline_comment(op_line)
                let saved_continuation = .begin_binary_continuation()
                .format_expr(node.u.binary.rhs)
                .end_binary_continuation(saved_continuation)
            } else {
                match op {
                    Assignment => .write(" = ")
                    PlusEquals => .write(" += ")
                    MinusEquals => .write(" -= ")
                    MultiplyEquals => .write(" *= ")
                    DivideEquals => .write(" /= ")
                    LeftShiftEquals => .write(" <<= ")
                    RightShiftEquals => .write(" >>= ")
                    Equals => .write(" == ")
                    NotEquals => .write(" != ")
                    LessThan => .write(" < ")
                    LessThanEquals => .write(" <= ")
                    GreaterThan => .write(" > ")
                    GreaterThanEquals => .write(" >= ")
                    Plus => .write(" + ")
                    Minus => .write(" - ")
                    Multiply => .write(" * ")
                    Divide => .write(" / ")
                    Modulus => .write(" % ")
                    And => .write(" and ")
                    Or => .write(" or ")
                    In => .write(" in ")
                    BitwiseAnd => .write(" & ")
                    BitwiseOr => .write(" | ")
                    BitwiseXor => .write(" ^ ")
                    LeftShift => .write(" << ")
                    RightShift => .write(" >> ")
                    else => {
                        .write(" ")
                        .write(.source_text(node.u.binary.op_span))
                        .write(" ")
                    }
                }
                .format_expr(node.u.binary.rhs)
            }
        }
        UnaryOp => {
            let op = node.u.unary.op
            match op {
                Negate => {
                    .write("-")
                    .format_expr(node.u.unary.expr)
                }
                Address => {
                    .write("&")
                    .format_expr(node.u.unary.expr)
                }
                Dereference => {
                    .write("*")
                    .format_expr(node.u.unary.expr)
                }
                Not => {
                    .write("not ")
                    .format_expr(node.u.unary.expr)
                }
                BitwiseNot => {
                    .write("~")
                    .format_expr(node.u.unary.expr)
                }
                IsNotNull => {
                    .format_expr(node.u.unary.expr)
                    .write("?")
                }
                PreIncrement => {
                    .write("++")
                    .format_expr(node.u.unary.expr)
                }
                PreDecrement => {
                    .write("--")
                    .format_expr(node.u.unary.expr)
                }
                PostIncrement => {
                    .format_expr(node.u.unary.expr)
                    .write("++")
                }
                PostDecrement => {
                    .format_expr(node.u.unary.expr)
                    .write("--")
                }
                ErrorProp => {
                    .format_expr(node.u.unary.expr)
                    .write("!")
                }
                ErrorUnwrap => {
                    .format_expr(node.u.unary.expr)
                    .write("!!")
                }
                else => {
                    .write(.source_text(node.u.unary.op_span))
                    .format_expr(node.u.unary.expr)
                }
            }
        }
        Call => {
            .format_expr(node.u.call.callee)
            let plan = .plan_collection(node, "(", ")")
            .emit_collection(node, &plan)
        }
        Cast => {
            .format_expr(node.u.cast.lhs)
            .write(" as ")
            .write(.format_type(node.u.cast.parsed_to))
        }
        SizeOf => {
            .write("sizeof(")
            .write(.format_type(node.u.size_of_type))
            .write(")")
        }
        Specialization => {
            .format_expr(node.u.spec.base)
            .write("<")
            for let i = 0u32; i < node.u.spec.parsed_template_args.size; i++ {
                if i > 0 then .write(", ")
                .write(.format_type(node.u.spec.parsed_template_args.at(i)))
            }
            .write(">")
        }
        ArrayLiteral => {
            let plan = .plan_collection(node, "[", "]")
            .emit_collection(node, &plan)
        }
        VectorLiteral => {
            let plan = .plan_collection(node, "$[", "]")
            .emit_collection(node, &plan)
        }
        MapLiteral => {
            let plan = .plan_collection(node, "${", "}")
            .emit_collection(node, &plan)
        }
        If => .format_if(node, is_expr: true)
        Match => .format_match(node)
        Block => .format_block(node)
        CreateNew => {
            .write("@new ")
            .format_expr(node.u.child)
        }
        CreateClosure => .format_closure(node.u.closure)
        Is => {
            .format_expr(node.u.is_expr.lhs)
            .write(" is ")
            for let i = 0u32; i < node.u.is_expr.conds.size; i++ {
                if i > 0 then .write(" | ")
                .format_match_cond(node.u.is_expr.conds.at(i))
            }
        }
        OverloadedOperator => {
            .write(.source_text(node.span))
        }
        Error => {
            .write(.source_text(node.span))
        }
        else => {
            // Fallback: use source text
            .write(.source_text(node.span))
        }
    }
}

//* Format a match condition (pattern)
def Formatter::format_match_cond(&this, cond: &MatchCond) {
    .format_expr(cond.expr)
    if cond.args? and cond.args.size > 0 {
        .write("(")
        for let i = 0u32; i < cond.args.size; i++ {
            if i > 0 then .write(", ")
            let arg = cond.args.at(i)
            .write(arg.var.sym.name)
        }
        .write(")")
    }
}

//* Format an if/else chain
def Formatter::format_if(&this, node: &AST, is_expr: bool = false) {
    let if_stmt = node.u.if_stmt

    // Multi-if: `if { cond => body, cond2 => body2, else => body3 }`
    if if_stmt.is_multi_if {
        .format_multi_if(node)
        return
    }

    for let i = 0u32; i < if_stmt.branches.size; i++ {
        let branch = if_stmt.branches[i]
        if i == 0 {
            .write("if ")
        } else {
            .write(" else if ")
        }

        .format_expr(branch.cond)
        if branch.body.type == Block {
            .write(" ")
            .format_block(branch.body)
        } else if .has_inline_comments_in_range(branch.body.span.start.line, branch.body.span.start.line) {
            // Non-block body has inline comment; use block to preserve it
            .format_inline_if_body(branch.body)
        } else if .options.width_enabled() and not if_stmt.els? and if_stmt.branches.size == 1 and .would_exceed_width(6 + .measure_statement(branch.body)) {
            // " then " is 6 chars; only convert to block form when there's
            // no else clause, to avoid idempotency issues with cascading reflows
            .format_inline_if_body(branch.body)
        } else if if_stmt.els? and .options.width_enabled() and .would_exceed_width(6 + .measure_statement(branch.body)) {
            // Else present and body won't fit. If `then` was in the source,
            // break before 'then' keeping expression form. Otherwise write a
            // space (can't add 'then' that wasn't there; block form + else
            // has idempotency issues so avoid that too).
            if branch.has_then {
                .begin_continuation()
                .write("then ")
                .format_statement(branch.body)
                .end_continuation()
            } else {
                .write(" ")
                .format_statement(branch.body)
            }
        } else if branch.has_then {
            .write(" then ")
            .format_statement(branch.body)
        } else {
            // No 'then' in source: preserve as-is without injecting the keyword
            .write(" ")
            .format_statement(branch.body)
        }
    }

    if if_stmt.els? {
        if if_stmt.els.type == If {
            .write(" else ")
            .format_if(if_stmt.els, is_expr)
        } else if if_stmt.els.type == Block {
            .write(" else ")
            .format_block(if_stmt.els)
        } else if .has_inline_comments_in_range(if_stmt.els.span.start.line, if_stmt.els.span.start.line) {
            // Non-block else body has inline comment; use block to preserve it
            .write(" else")
            .format_inline_if_body(if_stmt.els)
        } else if .options.width_enabled() and .would_exceed_width(6 + .measure_statement(if_stmt.els)) {
            // Else won't fit on this line. Check if we can use block form:
            // Block form `else { ... }` is only safe in statement context
            // (when all branches used block form). In expression context
            // (inline `then` form), blocks don't yield values, so we must
            // break the line instead.
            let last_branch = if_stmt.branches.at(if_stmt.branches.size - 1)
            if last_branch.body.type == Block {
                // Statement context (block-if): safe to use block form
                .write(" else")
                .format_inline_if_body(if_stmt.els)
            } else {
                // Expression/inline context: break before 'else' keyword
                .begin_continuation()
                .write("else ")
                .format_statement(if_stmt.els)
                .end_continuation()
            }
        } else {
            .write(" else ")
            .format_statement(if_stmt.els)
        }
    }
}

//* Format a multi-if: `if { cond => body, cond2 => body2, else => body3 }`
def Formatter::format_multi_if(&this, node: &AST) {
    let if_stmt = node.u.if_stmt
    .write("if {")
    .newline()
    .push_indent()
    let prev_end_line = node.span.start.line
    for let i = 0u32; i < if_stmt.branches.size; i++ {
        let branch = if_stmt.branches[i]
        .emit_item_preamble(branch.cond.span.start.line, i, prev_end_line)
        .write_indent()
        .format_expr(branch.cond)
        .write(" => ")
        .format_arrow_body(branch.body)
        .emit_inline_comment(branch.body.span.start.line)
        .newline()
        prev_end_line = branch.body.span.end.line
        // Cap to avoid span overlap with next branch
        if i + 1 < if_stmt.branches.size {
            let next_start = if_stmt.branches[i + 1].cond.span.start.line
            if prev_end_line >= next_start then prev_end_line = next_start - 1
        } else if if_stmt.els? {
            let next_start = if_stmt.els_span.start.line
            if prev_end_line >= next_start then prev_end_line = next_start - 1
        }
    }
    if if_stmt.els? {
        .emit_item_preamble(if_stmt.els_span.start.line, if_stmt.branches.size, prev_end_line)
        .write_indent()
        .write("else => ")
        .format_arrow_body(if_stmt.els)
        .emit_inline_comment(if_stmt.els.span.start.line)
        .newline()
    }
    .pop_indent()
    .write_indent()
    .write("}")
}

//* Format a block `{ ... }`
def Formatter::format_block(&this, node: &AST) {
    .write("{")
    let stmts = node.u.block.statements
    if stmts.size == 0 {
        if .has_inline_comments_in_range(node.span.start.line, node.span.start.line) {
            // Empty block with inline comment: put `}` on next line
            .emit_inline_comment(node.span.start.line)
            .newline()
            .write_indent()
        } else if node.span.end.line > node.span.start.line and .has_blank_source_line_between(node.span.start.line, node.span.end.line) {
            // Empty block with blank line(s): preserve the spacing
            .newline()
            .newline()
            .write_indent()
        }
        .write("}")
        return
    }
    .emit_inline_comment(node.span.start.line)
    .newline()
    .push_indent()

    let prev_end_line = node.span.start.line
    for let i = 0u32; i < stmts.size; i++ {
        let stmt = stmts.at(i)
        .emit_item_preamble(stmt.span.start.line, i, prev_end_line)
        let stmt_output_start = .output_line
        .write_indent()
        .format_statement(stmt)
        .emit_inline_comment(stmt.span.start.line)
        .newline()
        if .track_stmts {
            let source_end = stmt.span.end.line
            let output_lines = (.output_line - 1) - stmt_output_start + 1
            // Cap source_end based on output line count to avoid
            // swallowing comments/blanks after the statement.
            let output_cap = stmt.span.start.line + output_lines - 1
            if source_end > output_cap {
                source_end = output_cap
            }
            // Cap at next statement's start line to prevent overlapping
            // source ranges (some AST spans include the next line).
            if i + 1 < stmts.size {
                let next_start = stmts[i + 1].span.start.line
                if source_end >= next_start {
                    source_end = next_start - 1
                }
            }
            // For the last statement, cap source_end before the block's
            // closing brace so it's not swallowed into this mapping.
            if i == stmts.size - 1 and source_end >= node.span.end.line {
                source_end = node.span.end.line - 1
            }
            .stmt_mappings.push(DeclMapping(source_start: stmt.span.start.line, source_end: source_end, output_start: stmt_output_start, output_end: .output_line - 1))
        }
        prev_end_line = stmt.span.end.line
        // When the AST span over-extends (e.g. bare `return`/`break` spans
        // include the next token), use output-based end to avoid hiding blank
        // lines between statements.
        //
        // When the AST span under-extends (e.g. if-else expression spans
        // don't cover the else body), output_based_end may be larger than
        // span.end.  In that case we extend prev_end_line, but ONLY if
        // the source lines between span.end and output_based_end contain
        // no blank lines — blank lines indicate the span end is valid and
        // the output merely expanded via reformatting.
        let output_based_end = stmt.span.start.line + (.output_line - 1 - stmt_output_start)
        if i + 1 < stmts.size and prev_end_line >= stmts[i + 1].span.start.line {
            // Span over-extends past next statement; use output-based end.
            // But if output_based_end itself covers blank source lines (due to
            // formatting expansion, e.g. single-line `if X return Y` becoming
            // multi-line `if X { return Y }`), don't extend past those blanks.
            // NOTE: must check this BEFORE the under-extend branch, since when
            // span.end == next_stmt.start, checking has_blank from span.end would
            // look inside the next statement's body (wrong region).
            if not .has_blank_source_line_between(stmt.span.start.line, output_based_end + 1) {
                prev_end_line = output_based_end
            } else {
                prev_end_line = stmt.span.start.line
            }
        } else if i == stmts.size - 1 and prev_end_line >= node.span.end.line {
            // Last statement span extends past closing brace; use output-based end.
            // Apply same blank-line guard as above.
            // NOTE: must check this BEFORE the under-extend branch, since when
            // prev_end_line >= close_line, checking has_blank from prev_end_line
            // would look at lines OUTSIDE the block (past the closing brace).
            if not .has_blank_source_line_between(stmt.span.start.line, output_based_end + 1) {
                prev_end_line = output_based_end
            } else {
                prev_end_line = stmt.span.start.line
            }
        } else if output_based_end > prev_end_line and not .has_blank_source_line_between(prev_end_line, output_based_end + 1) {
            // Span under-extends (source lines above are non-blank content); extend
            prev_end_line = output_based_end
        }
    }
    let close_line = node.span.end.line
    // Emit trailing comments with blank line preservation
    while .comment_index < .comments.size {
        let comment = .comments.at(.comment_index)
        if comment.span.start.line >= close_line then break
        if comment.is_inline {
            .comment_index++
            continue
        }
        if comment.span.start.line > prev_end_line + 1 {
            .newline()
        }
        .write_indent()
        .write(comment.text)
        .newline()
        .comment_emitted.data[.comment_index] = true
        prev_end_line = comment.span.end.line
        .comment_index++
    }
    // Preserve blank line before closing brace
    if close_line > prev_end_line + 1 and .has_blank_source_line_between(prev_end_line, close_line) {
        .newline()
    }
    .pop_indent()
    .write_indent()
    .write("}")
    .emit_inline_comment(close_line)
}

//* Format a single statement
def Formatter::format_statement(&this, node: &AST) {
    match node.type {
        VarDeclaration => .format_var_decl(node)
        Return => {
            .write("return")
            if node.u.ret.expr? {
                .write(" ")
                .format_expr(node.u.ret.expr)
            }
        }
        Yield => {
            .write("yield")
            if node.u.ret.expr? {
                .write(" ")
                .format_expr(node.u.ret.expr)
            }
        }
        If => .format_if(node)
        While => {
            .write("while ")
            .format_expr(node.u.loop.cond)
            // If the condition has any unemitted inline comments (e.g., multi-line
            // boolean expressions), emit them and put { on its own line
            let cond_start = node.u.loop.cond.span.start.line
            let cond_end = node.u.loop.cond.span.end.line
            if .has_unemitted_inline_comment_in_range(cond_start, cond_end) {
                .emit_all_unemitted_inline_comments_in_range(cond_start, cond_end)
                .newline()
                .write_indent()
            } else {
                .write(" ")
            }

            .format_block(node.u.loop.body)
        }
        For => .format_for(node)
        Match => .format_match(node)
        Block => .format_block(node)
        Break => .write("break")
        Continue => .write("continue")
        Defer => {
            .write("defer ")
            .format_statement(node.u.child)
        }
        Assert => {
            .write("assert ")
            .format_expr(node.u.assertion.expr)
            if node.u.assertion.msg? {
                // Width-aware: break after comma if assertion + message won't fit
                if .options.width_enabled() and .would_exceed_width(2 + .measure_expr(node.u.assertion.msg)) {
                    .write(",")
                    .begin_continuation()
                    .format_expr(node.u.assertion.msg)
                    .end_continuation()
                    .emit_inline_comment(node.u.assertion.msg.span.start.line)
                } else {
                    .write(", ")
                    .format_expr(node.u.assertion.msg)
                }
            }
        }
        Import => .format_import(node)
        else => .format_expr(node)
    }
}

def Formatter::match_body_needs_trailing_comma(&this, body: &AST): bool {
    return body.type == If or body.type == Match
}

//* Detect and format for-each loops vs C-style for loops
def Formatter::format_for(&this, node: &AST) {
    let loop_node = node.u.loop

    // Detect for-each: init is VarDeclaration with generated _i name
    if loop_node.init? and loop_node.init.type == VarDeclaration {
        let init_var = loop_node.init.u.var_decl
        let var_name = init_var.sym.name
        if var_name.starts_with("_i") {
            // for-each pattern: body is Block with [loop_var_decl, inner_body]
            let body = loop_node.body
            if body.type == Block and body.u.block.statements.size >= 2 {
                let inner_var = body.u.block.statements.at(0)
                if inner_var.type == VarDeclaration {
                    let iter_name = inner_var.u.var_decl.sym.name
                    .write("for ")
                    .write(iter_name)
                    .write(" in ")
                    .format_expr(init_var.default_value)
                    .write(" ")
                    let real_body = body.u.block.statements.at(1)
                    .format_block(real_body)
                    return
                }
            }
        }
    }

    // C-style for loop
    .write("for ")
    if loop_node.init? {
        .format_statement(loop_node.init)
    }
    .write("; ")
    if loop_node.cond? {
        .format_expr(loop_node.cond)
    }
    .write("; ")
    if loop_node.step? {
        .format_expr(loop_node.step)
    }
    .write(" ")
    .format_block(loop_node.body)
}

//* Format a match statement/expression
def Formatter::format_match(&this, node: &AST) {
    let match_node = node.u.match_stmt
    .write("match ")
    .format_expr(match_node.expr)
    .write(" {")
    .newline()
    .push_indent()
    let prev_end_line = node.span.start.line
    for let i = 0u32; i < match_node.cases.size; i++ {
        let case_node = match_node.cases[i]
        let case_cond_start = case_node.conds.at(0).expr.span.start.line
        .emit_item_preamble(case_cond_start, i, prev_end_line)
        let case_output_start = .output_line
        .write_indent()

        // Width-aware: check if all conditions fit on one line
        let break_conds = false
        if .options.width_enabled() and case_node.conds.size > 1 {
            let conds_width = 0u32
            for let j = 0u32; j < case_node.conds.size; j++ {
                if j > 0 then conds_width += 3 // " | "
                conds_width += .measure_match_cond(case_node.conds.at(j))
            }
            // Also add " => " + body
            if .would_exceed_width(conds_width + 4) {
                break_conds = true
            }
        }

        if break_conds {
            for let j = 0u32; j < case_node.conds.size; j++ {
                if j > 0 {
                    .newline()
                    .write_indent()
                    .write("| ")
                }
                .format_match_cond(case_node.conds.at(j))
            }
        } else {
            for let j = 0u32; j < case_node.conds.size; j++ {
                if j > 0 then .write(" | ")
                .format_match_cond(case_node.conds.at(j))
            }
        }

        // Width-aware: check if " => body" fits on the same line
        if case_node.body.type != Block and .options.width_enabled() {
            let body_width = .measure_statement(case_node.body)
            if .would_exceed_width(4 + body_width) {
                .write(" =>")
                .begin_continuation()
                .format_statement(case_node.body)
                if .match_body_needs_trailing_comma(case_node.body) {
                    .write(",")
                }
                .end_continuation()
                .emit_inline_comment(case_node.body.span.start.line)
                .newline()
                prev_end_line = case_node.body.span.end.line
                let output_based_end = case_cond_start + (.output_line - 1 - case_output_start)
                // Cap to avoid span overlap with next case.
                // Use case_cond_start when there are blank lines (mirrors format_block
                // logic: span over-extends but blank lines present → use stmt start).
                if i + 1 < match_node.cases.size {
                    let next_start = match_node.cases[i + 1].conds.at(0).expr.span.start.line
                    if prev_end_line >= next_start {
                        if not .has_blank_source_line_between(case_cond_start, output_based_end + 1) {
                            prev_end_line = output_based_end
                        } else {
                            prev_end_line = case_cond_start
                        }
                    }
                } else if match_node.defolt? {
                    let next_start = match_node.defolt_span.start.line
                    if prev_end_line >= next_start {
                        if not .has_blank_source_line_between(case_cond_start, output_based_end + 1) {
                            prev_end_line = output_based_end
                        } else {
                            prev_end_line = case_cond_start
                        }
                    }
                }
                continue
            }
        }

        .write(" => ")
        .format_arrow_body(case_node.body, add_match_trailing_comma: true)
        .emit_inline_comment(case_node.body.span.start.line)
        .newline()
        prev_end_line = case_node.body.span.end.line
        let output_based_end = case_cond_start + (.output_line - 1 - case_output_start)
        // Cap to avoid span overlap with next case.
        // Use case_cond_start when there are blank lines (mirrors format_block
        // logic: span over-extends but blank lines present → use stmt start).
        if i + 1 < match_node.cases.size {
            let next_start = match_node.cases[i + 1].conds.at(0).expr.span.start.line
            if prev_end_line >= next_start {
                if not .has_blank_source_line_between(case_cond_start, output_based_end + 1) {
                    prev_end_line = output_based_end
                } else {
                    prev_end_line = case_cond_start
                }
            }
        } else if match_node.defolt? {
            let next_start = match_node.defolt_span.start.line
            if prev_end_line >= next_start {
                if not .has_blank_source_line_between(case_cond_start, output_based_end + 1) {
                    prev_end_line = output_based_end
                } else {
                    prev_end_line = case_cond_start
                }
            }
        }
    }
    if match_node.defolt? {
        .emit_item_preamble(match_node.defolt_span.start.line, match_node.cases.size, prev_end_line)
        .write_indent()
        .write("else => ")
        .format_arrow_body(match_node.defolt)
        .emit_inline_comment(match_node.defolt.span.start.line)
        .newline()
    }
    .pop_indent()
    .write_indent()
    .write("}")
}

//* Format a variable declaration
def Formatter::format_var_decl(&this, node: &AST) {
    let var = node.u.var_decl
    .write_var_decl(var, "let")
}

//* Format an import statement
def Formatter::format_import(&this, node: &AST) {
    let imp = node.u.import_path
    if imp.export {
        .write("[export] ")
    }
    .write("import ")
    match imp.type {
        ProjectNamespace => .write("@")
        ParentNamespace => {
            for let i = 0u32; i < imp.parent_count; i++ {
                .write(".")
            }
        }
        CurrentScope => .write("::")
        else => {}
    }
    .format_import_parts(imp.parts)
}

//* Format import path parts
def Formatter::format_import_parts(&this, parts: &Vector<&ImportPart>) {
    for let i = 0u32; i < parts.size; i++ {
        if i > 0 then .write("::")
        let part = parts.at(i)
        match part.type {
            Single => {
                .write(part.u.single.name)
                if part.u.single.alias? {
                    .write(" as ")
                    .write(part.u.single.alias)
                }
            }
            Multiple => {
                // Width-aware: measure full import list to decide single/multi-line
                let break_imports = false
                if .options.width_enabled() {
                    let total_w = 4u32 // "{ " + " }"
                    for let j = 0u32; j < part.u.multiple.paths.size; j++ {
                        if j > 0 then total_w += 2 // ", "
                        total_w += .measure_import_parts(part.u.multiple.paths.at(j))
                    }
                    if .would_exceed_width(total_w) {
                        break_imports = true
                    }
                }
                if break_imports {
                    .write("{")
                    .newline()
                    .push_indent()
                    for let j = 0u32; j < part.u.multiple.paths.size; j++ {
                        .write_indent()
                        .format_import_parts(part.u.multiple.paths.at(j))
                        .write(",")
                        .newline()
                    }
                    .pop_indent()
                    .write_indent()
                    .write("}")
                } else {
                    .write("{ ")
                    for let j = 0u32; j < part.u.multiple.paths.size; j++ {
                        if j > 0 then .write(", ")
                        .format_import_parts(part.u.multiple.paths.at(j))
                    }
                    .write(" }")
                }
            }
            Wildcard => .write("*")
        }
    }
}

//* Format a closure expression
def Formatter::format_closure(&this, func: &Function) {
    .write("|")
    for let i = 0u32; i < func.params.size; i++ {
        if i > 0 then .write(", ")
        let param = func.params.at(i)
        .write(param.sym.name)
        if param.parsed_type? {
            .write(": ")
            .write(.format_type(param.parsed_type))
        }
    }
    .write("|")
    if func.parsed_return_type? {
        .write(": ")
        .write(.format_type(func.parsed_return_type))
    }
    if func.is_arrow {
        .write(" => ")
        .format_expr(func.body)
    } else {
        .write(" ")
        .format_block(func.body)
    }
}

//* Format a function parameter
def Formatter::format_param(&this, param: &Variable, is_first: bool) {
    if is_first and param.sym.name.eq("this") {
        if param.parsed_type? and param.parsed_type.base == BaseType::Pointer {
            .write("&this")
        } else {
            .write("this")
        }

        return
    }
    .write(param.sym.name)
    if param.parsed_type? {
        .write(": ")
        .write(.format_type(param.parsed_type))
    }
    if param.default_value? {
        .write(" = ")
        .format_expr(param.default_value)
    }
}

//* Format function attributes
def Formatter::format_function_attrs(&this, func: &Function) {
    .format_extern_attr(func.sym)
    if func.exits {
        .write_attr_line("exits")
    }
    if func.is_variadic_format {
        .write_attr_line("variadic_format")
    }
    if func.operator_overloads? {
        for op in func.operator_overloads.iter() {
            .write_indent()
            .write("[operator \"")
            .write(op.str())
            .write("\"]")
            .newline()
        }
    }
    if func.is_test_function {
        .write_attr_line("test")
    }
    if func.flatten_attr {
        .write_attr_line("flatten")
    }
    if func.is_alive {
        .write_attr_line("alive")
    }
}

//* Format a function definition
def Formatter::format_function(&this, func: &Function) {
    .format_function_attrs(func)
    let header_output_start = .output_line
    .write_indent()
    .write("def ")

    // Method name: Type::name
    if func.parent_type? {
        .format_expr(func.parent_type.u.unresolved)
        .write("::")
    }
    .write(func.sym.name)

    // Template parameters
    .format_template_params(func.sym)

    // Parameters: plan then emit (no decisions in emission phase)
    let param_plan = .plan_params(func)
    .emit_params(func, &param_plan)

    // Return type - only emit if explicitly written by user
    if .has_explicit_return_type(func) {
        .write(": ")
        .write(.format_type(func.parsed_return_type))
    }

    // Body
    if func.sym.is_extern {
        .newline()
        return
    }

    if func.is_arrow {
        // Width-aware: check if arrow body would fit on same line
        let break_arrow = false
        if .options.width_enabled() {
            let body_width = .measure_expr(func.body)
            if .would_exceed_width(4 + body_width) { // 4 for " => "
                break_arrow = true
            }
        }
        if break_arrow {
            .write(" =>")
            .begin_continuation()
            .format_expr(func.body)
            .end_continuation()
            .emit_inline_comment(func.body.span.start.line)
            .newline()
        } else {
            .write(" => ")
            .format_expr(func.body)
            .emit_inline_comment(func.body.span.start.line)
            .newline()
        }
    } else {
        .write(" ")
        // Record function header (def ... {) as a pseudo-statement so
        // range formatting can include the signature when it overlaps.
        if .range_start > 0 {
            .stmt_mappings.push(DeclMapping(source_start: func.span.start.line, source_end: func.body.span.start.line, output_start: header_output_start, output_end: .output_line))
        }
        let was_tracking = .track_stmts
        if .range_start > 0 then .track_stmts = true
        .format_block(func.body)
        .track_stmts = was_tracking
        .newline()
    }
}

//* Format a struct or union definition
def Formatter::format_struct(&this, struc: &Structure) {
    .format_extern_attr(struc.sym)

    .write_indent()
    if struc.is_union {
        .write("union ")
    } else {
        .write("struct ")
    }

    .write(struc.sym.name)

    // Template parameters
    .format_template_params(struc.sym)

    // Parent (inheritance)
    if struc.parsed_parent? {
        .write(" : ")
        .write(.format_type(struc.parsed_parent))
    }

    if struc.sym.is_extern and struc.fields.size == 0 {
        if struc.span.end.line > struc.span.start.line and .has_blank_source_line_between(struc.span.start.line, struc.span.end.line) {
            .write(" {")
            .newline()
            .newline()
            .write_indent()
            .write("}")
        } else {
            .write(" {}")
        }
        .newline()
        return
    }

    // Non-extern empty struct: also keep on one line
    if struc.fields.size == 0 {
        if struc.span.end.line > struc.span.start.line and .has_blank_source_line_between(struc.span.start.line, struc.span.end.line) {
            .write(" {")
            .newline()
            .newline()
            .write_indent()
            .write("}")
        } else {
            .write(" {}")
        }
        .newline()
        return
    }

    .write(" {")
    .emit_inline_comment(struc.span.start.line)
    .newline()
    .push_indent()

    // Format fields, detecting multi-field declarations
    let i = 0u32
    let prev_field_end = struc.span.start.line
    while i < struc.fields.size {
        let field = struc.fields.at(i)

        .emit_item_preamble(field.sym.span.start.line, i, prev_field_end)

        // Emit field-level attributes ([atomic], [extern])
        if field.sym.is_extern {
            .format_extern_attr(field.sym)
        }
        if field.is_atomic {
            .write_attr_line("atomic")
        }

        .write_indent()

        // Check for multi-field: consecutive fields sharing the same type span
        let multi_end = i + 1
        while multi_end < struc.fields.size {
            let next_field = struc.fields.at(multi_end)
            if next_field.parsed_type? and field.parsed_type? {
                let a = next_field.parsed_type.span
                let b = field.parsed_type.span
                if a.start.line == b.start.line and a.start.col == b.start.col {
                    multi_end++
                } else {
                    break
                }
            } else {
                break
            }
        }

        if multi_end > i + 1 {
            // Multi-field: a, b, c: Type
            for let j = i; j < multi_end; j++ {
                if j > i then .write(", ")
                .write(struc.fields.at(j).sym.name)
            }
            .write(": ")
            .write(.format_type(field.parsed_type))
            .emit_inline_comment(field.sym.span.start.line)
            .newline()
            prev_field_end = struc.fields.at(multi_end - 1).sym.span.end.line
            i = multi_end
        } else {
            .write(field.sym.name)
            if field.parsed_type? {
                .write(": ")
                .write(.format_type(field.parsed_type))
            }
            if field.default_value? {
                .write(" = ")
                .format_expr(field.default_value)
            }
            .emit_inline_comment(field.sym.span.start.line)
            .newline()
            prev_field_end = field.sym.span.end.line
            i++
        }
    }

    .pop_indent()
    .write_indent()
    .write("}")
    .emit_inline_comment(struc.span.end.line)
    .newline()
}

//* Format an enum definition
def Formatter::format_enum(&this, enom: &Enum) {
    .format_extern_attr(enom.sym)
    if enom.is_flag_enum {
        .write_attr_line("flags")
    }

    .write_indent()
    .write("enum ")
    .write(enom.sym.name)

    // Template parameters
    .format_template_params(enom.sym)

    .write(" {")
    .emit_inline_comment(enom.span.start.line)
    .newline()
    .push_indent()

    let prev_end_line = enom.span.start.line

    // Shared fields
    for let i = 0u32; i < enom.shared_fields.size; i++ {
        let field = enom.shared_fields.at(i)
        .emit_item_preamble(field.sym.span.start.line, i, prev_end_line)
        .write_indent()
        .write(field.sym.name)
        .write(": ")
        .write(.format_type(field.parsed_type))
        if field.default_value? {
            .write(" = ")
            .format_expr(field.default_value)
        }
        .emit_inline_comment(field.sym.span.start.line)
        .newline()
        prev_end_line = field.sym.span.end.line
    }

    // Variants
    let variant_offset = enom.shared_fields.size
    for let i = 0u32; i < enom.variants.size; i++ {
        let variant = enom.variants.at(i)
        .emit_item_preamble(variant.span.start.line, i + variant_offset, prev_end_line)
        .write_indent()
        .write(variant.sym.name)
        if variant.specific_fields.size > 0 {
            .write("(")
            for let j = 0u32; j < variant.specific_fields.size; j++ {
                if j > 0 then .write(", ")
                let field = variant.specific_fields.at(j)
                .write(field.sym.name)
                if field.parsed_type? {
                    .write(": ")
                    .write(.format_type(field.parsed_type))
                }
                if field.default_value? {
                    .write(" = ")
                    .format_expr(field.default_value)
                }
            }
            .write(")")
        }
        if variant.sym.is_extern and variant.sym.extern_name? and not variant.sym.extern_name.eq(variant.sym.name) {
            .write(` = extern("`)
            .write(variant.sym.extern_name)
            .write(`")`)
        }
        .emit_inline_comment(variant.span.start.line)
        .newline()
        prev_end_line = variant.span.end.line
    }

    .pop_indent()
    .write_indent()
    .write("}")
    .emit_inline_comment(enom.span.end.line)
    .newline()
}

//* Format a constant declaration
def Formatter::format_const_decl(&this, node: &AST) {
    .format_top_level_var_decl(node, "const")
}

//* Format a global variable declaration
def Formatter::format_global_var(&this, node: &AST) {
    .format_top_level_var_decl(node, "let")
}

//* Format a typedef
def Formatter::format_typedef(&this, name: str, type: &Type) {
    .write_indent()
    .write("typedef ")
    .write(name)
    .write(" = ")
    .write(.format_type(type))
    .emit_inline_comment(type.span.start.line)
    .newline()
}

//* Collect all top-level declarations and sort by source position
def Formatter::collect_decls(&this, ns: &Namespace): &Vector<Decl> {
    let decls = Vector<Decl>::new()

    for func in ns.functions.iter() {
        let d: Decl
        d.type = DeclType::Function
        d.line = func.span.start.line
        d.col = func.span.start.col
        d.u.func = func
        decls.push(d)
    }

    for struc in ns.structs.iter() {
        let d: Decl
        d.type = DeclType::Structure
        d.line = struc.span.start.line
        d.col = struc.span.start.col
        d.u.struc = struc
        decls.push(d)
    }

    for enom in ns.enums.iter() {
        let d: Decl
        d.type = DeclType::Enum
        d.line = enom.span.start.line
        d.col = enom.span.start.col
        d.u.enom = enom
        decls.push(d)
    }

    for node in ns.constants.iter() {
        let d: Decl
        d.type = DeclType::Constant
        d.line = node.span.start.line
        d.col = node.span.start.col
        d.u.var_node = node
        decls.push(d)
    }

    for node in ns.variables.iter() {
        let d: Decl
        d.type = DeclType::Variable
        d.line = node.span.start.line
        d.col = node.span.start.col
        d.u.var_node = node
        decls.push(d)
    }

    for node in ns.imports.iter() {
        let d: Decl
        d.type = DeclType::Import
        d.line = node.span.start.line
        d.col = node.span.start.col
        d.u.import_node = node
        decls.push(d)
    }

    for entry in ns.namespaces.iter() {
        let child_ns = entry.value
        if child_ns.is_a_file then continue
        let d: Decl
        d.type = DeclType::Namespace
        d.line = child_ns.span.start.line
        d.col = child_ns.span.start.col
        d.u.ns = child_ns
        decls.push(d)
    }

    for entry in ns.typedefs.iter() {
        let name = entry.key
        let type = entry.value
        let d: Decl
        d.type = DeclType::TypeDef
        d.line = type.span.start.line
        d.col = type.span.start.col
        d.u.type_def = TypeDefInfo(name, type, span: type.span)
        decls.push(d)
    }

    for let i = 0u32; i < ns.compiler_options.size; i++ {
        let opt = ns.compiler_options.at(i)
        let d: Decl
        d.type = DeclType::CompilerOpt
        d.line = opt.span.start.line
        d.col = opt.span.start.col
        d.u.compiler_opt = opt
        decls.push(d)
    }

    // Sort by source position
    sort_by<Decl>(decls.data, decls.size, |a: Decl, b: Decl|: i8 {
        if a.line < b.line then return -1i8
        if a.line > b.line then return 1i8
        if a.col < b.col then return -1i8
        if a.col > b.col then return 1i8
        return 0i8
    })

    return decls
}

//* Format an entire file namespace
def Formatter::format_ns(&this, ns: &Namespace, track_mappings: bool = false) {
    let decls = .collect_decls(ns)

    let first = true
    let prev_type: DeclType = DeclType::Import
    let prev_is_arrow = false
    let prev_source_end = 0u32

    for let i = 0u32; i < decls.size; i++ {
        let d = decls.at(i)

        let map_output_start = .output_line

        // Add blank line between declaration groups BEFORE emitting comments,
        // so doc comments stay attached to their declaration.
        if not first {
            let need_blank = true
            let is_var_or_const = (d.type == DeclType::Variable or d.type == DeclType::Constant)
            let prev_var_or_const = (prev_type == DeclType::Variable or prev_type == DeclType::Constant)
            let cur_is_arrow = (d.type == DeclType::Function and d.u.func.is_arrow)
            if d.type == DeclType::Import and prev_type == DeclType::Import {
                need_blank = .has_blank_source_line_between(prev_source_end, d.line)
            } else if d.type == DeclType::CompilerOpt and prev_type == DeclType::CompilerOpt {
                need_blank = .has_blank_source_line_between(prev_source_end, d.line)
            } else if is_var_or_const and prev_var_or_const {
                need_blank = .has_blank_source_line_between(prev_source_end, d.line)
                // Consecutive arrow functions: preserve source spacing
                // Check for actual blank lines in source (not just attribute/comment lines)
            } else if cur_is_arrow and prev_is_arrow {
                need_blank = .has_blank_source_line_between(prev_source_end, d.line)
            }
            if need_blank {
                .newline()
            }
        }

        let old_ci = .comment_index
        .emit_comments_before(d.line, preserve_blanks: true, prev_end_line: prev_source_end)
        let emitted_comments = .comment_index > old_ci

        if emitted_comments {
            // Blank line after comments, only if the source has one between
            // the last comment and the declaration.
            let last_comment_end = .comments.at(.comment_index - 1).span.end.line
            if .has_blank_source_line_between(last_comment_end, d.line) {
                .newline()
            }
        }

        match d.type {
            Function => .format_function(d.u.func)
            Structure => .format_struct(d.u.struc)
            Enum => .format_enum(d.u.enom)
            Constant => .format_const_decl(d.u.var_node)
            Variable => .format_global_var(d.u.var_node)
            Import => {
                .write_indent()
                .format_import(d.u.import_node)
                .emit_inline_comment(d.u.import_node.span.start.line)
                .newline()
            }
            Namespace => .format_ns_block(d.u.ns)
            TypeDef => .format_typedef(d.u.type_def.name, d.u.type_def.type)
            CompilerOpt => {
                let opt = d.u.compiler_opt
                .write_indent()
                .write("@compiler ")
                .write(opt.type_name)
                .write(" \"")
                .write(opt.arg)
                .write("\"")
                .emit_inline_comment(opt.span.start.line)
                .newline()
            }
        }

        if track_mappings {
            let source_end = decl_end_line(&d)
            .decl_mappings.push(DeclMapping(source_start: prev_source_end + 1, source_end, output_start: map_output_start, output_end: .output_line - 1))
            prev_source_end = source_end
        } else {
            prev_source_end = decl_end_line(&d)
        }
        // Cap prev_source_end so it doesn't reach the next decl's start line.
        // Some AST spans (e.g. variables, imports) extend to the next token,
        // which would incorrectly hide blank lines between declarations.
        if i + 1 < decls.size {
            let next_start = decls.at(i + 1).line
            if prev_source_end >= next_start {
                prev_source_end = next_start - 1
            }
        }

        prev_type = d.type
        prev_is_arrow = (d.type == DeclType::Function and d.u.func.is_arrow)
        first = false
    }

    // Handle trailing content (comments after last declaration)
    let map_output_start = .output_line
    .emit_remaining_comments(ns.span.end.line, prev_end_line: prev_source_end)
    if track_mappings and .output_line > map_output_start {
        // Count total source lines
        let total_lines = .line_offsets.size
        if total_lines > prev_source_end {
            .decl_mappings.push(DeclMapping(source_start: prev_source_end + 1, source_end: total_lines, output_start: map_output_start, output_end: .output_line - 1))
        }
    }
}

//* Format a namespace block `namespace Name { ... }`
def Formatter::format_ns_block(&this, ns: &Namespace) {
    .write_indent()
    .write("namespace ")
    .write(ns.sym.name)
    .write(" {")
    .emit_inline_comment(ns.span.start.line)
    .newline()
    .push_indent()
    .format_ns(ns)
    .pop_indent()
    .write_indent()
    .write("}")
    .emit_inline_comment(ns.span.end.line)
    .newline()
}

//* Split a string into lines (returns a vector of SVs)
def split_lines(text: str): &Vector<SV> {
    let lines = Vector<SV>::new()
    let sv = SV::from_str(text)
    while not sv.is_empty() {
        lines.push(sv.chop_line())
    }
    return lines
}

//* Find the column of the inline comment (last " //" pattern) in a line
def find_inline_comment_col(line: SV): u32 {
    if line.len < 3 then return 0
    for let i = line.len as i32 - 2; i >= 1; i-- {
        if line.data[i] == '/' and line.data[i + 1] == '/' and line.data[i - 1] == ' ' {
            return i as u32
        }
    }
    return 0
}

//* Post-process output to align inline comments on consecutive output lines
def Formatter::align_inline_comments(&this) {
    if .ic_lines.size < 2 then return
    let text = .output.str()
    let lines = split_lines(text)

    // Build a set of line numbers with inline comments for fast lookup
    // (ic_lines is already sorted since we emit in order)

    // Process groups of consecutive inline comment lines
    let i = 0u32
    let any_changes = false
    // Store (line_index, padding) pairs
    let pad_lines = Vector<u32>::new()
    let pad_amounts = Vector<u32>::new()

    while i < .ic_lines.size {
        let group_start = i
        i++
        while i < .ic_lines.size and .ic_lines.at(i) == .ic_lines.at(i - 1) + 1 {
            i++
        }
        if i - group_start < 2 then continue
        // Find max comment column in this group
        let max_col = 0u32
        for let j = group_start; j < i; j++ {
            let line_idx = .ic_lines.at(j) - 1 // 0-indexed
            if line_idx < lines.size as u32 {
                let col = find_inline_comment_col(lines.at(line_idx))
                if col > max_col then max_col = col
            }
        }

        // Record padding for each line in the group
        for let j = group_start; j < i; j++ {
            let line_idx = .ic_lines.at(j) - 1
            if line_idx < lines.size as u32 {
                let col = find_inline_comment_col(lines.at(line_idx))
                if col < max_col {
                    pad_lines.push(line_idx)
                    pad_amounts.push(max_col - col)
                    any_changes = true
                }
            }
        }
    }

    if not any_changes then return
    // Rebuild output with padding inserted
    let new_output = Buffer::make()
    let pad_idx = 0u32
    for let k = 0u32; k < lines.size as u32; k++ {
        let line = lines.at(k)
        if pad_idx < pad_lines.size and pad_lines.at(pad_idx) == k {
            let col = find_inline_comment_col(line)
            let pad = pad_amounts.at(pad_idx)
            // Write everything before the comment
            for let c = 0u32; c < col; c++ {
                new_output += line.data[c]
            }
            // Write padding spaces
            for let p = 0u32; p < pad; p++ {
                new_output += ' '
            }
            // Write the comment and rest of line
            for let c = col; c < line.len; c++ {
                new_output += line.data[c]
            }
            pad_idx++
        } else {
            new_output.write_sv(line)
        }

        new_output += '\n'
    }
    .output = new_output
}

//! Range reconstruction helpers.
//!
//! These extract the monolithic range-patching logic from run()
//! into focused, testable helper methods. Each handles one concern:
//!   - emit_source_lines: copy source lines verbatim
//!   - emit_formatted_lines: copy formatted output lines
//!   - mapping_overlaps_range: overlap predicate
//!   - emit_mapping_substitution: decide per-mapping how to splice
//!   - filter_leaf_mappings: find innermost (leaf) stmt mappings
//!   - reconstruct_range: orchestrate the full range reconstruction
//* Emit source lines [start..end] (1-based inclusive) to result buffer
def emit_source_lines(result: &Buffer, source_lines: &Vector<SV>, start: u32, end: u32) {
    for let j = start; j <= end and j <= source_lines.size as u32; j++ {
        result.write_sv(source_lines.at(j - 1))
        (*result) += '\n'
    }
}

//* Emit formatted lines [start..end] (1-based inclusive) to result buffer
def emit_formatted_lines(result: &Buffer, formatted_lines: &Vector<SV>, start: u32, end: u32) {
    for let j = start; j <= end and j <= formatted_lines.size as u32; j++ {
        result.write_sv(formatted_lines.at(j - 1))
        (*result) += '\n'
    }
}

//* Check if a source range [source_start..source_end] overlaps [range_start..range_end]
def mapping_overlaps_range(source_start: u32, source_end: u32, range_start: u32, range_end: u32): bool {
    return source_start <= range_end and source_end >= range_start
}

//* Emit a single mapping's output, choosing between formatted and source
//* based on how it overlaps the requested range.
//*
//* Cases:
//*   1. Not overlapping range → emit source
//*   2. Fully within range → emit formatted
//*   3. Partially overlapping, same line count → per-line substitution
//*   4. Partially overlapping, different line count → format only if all
//*      source lines are within range, else keep source
def emit_mapping_substitution(result: &Buffer, mapping: &DeclMapping, source_lines: &Vector<SV>, formatted_lines: &Vector<SV>, range_start: u32, range_end: u32) {
    let overlaps = mapping_overlaps_range(mapping.source_start, mapping.source_end, range_start, range_end)
    let src_count = mapping.source_end - mapping.source_start + 1
    let fmt_count = mapping.output_end - mapping.output_start + 1

    if not overlaps {
        // Case 1: Not in range — use source
        emit_source_lines(result, source_lines, mapping.source_start, mapping.source_end)
    } else if mapping.source_start >= range_start and mapping.source_end <= range_end {
        // Case 2: Fully within range — use formatted
        emit_formatted_lines(result, formatted_lines, mapping.output_start, mapping.output_end)
    } else if src_count == fmt_count {
        // Case 3: Partially overlapping, same line count — per-line substitution
        for let li = 0u32; li < src_count; li++ {
            let abs_line = mapping.source_start + li
            if abs_line >= range_start and abs_line <= range_end {
                result.write_sv(formatted_lines.at(mapping.output_start - 1 + li))
            } else {
                result.write_sv(source_lines.at(mapping.source_start - 1 + li))
            }

            (*result) += '\n'
        }
    } else {
        // Case 4: Partially overlapping, different line count — only format
        // if ALL source lines are within range, else keep source
        let all_in = true
        for let j = mapping.source_start; j <= mapping.source_end; j++ {
            if j < range_start or j > range_end {
                all_in = false
                break
            }
        }
        if all_in {
            emit_formatted_lines(result, formatted_lines, mapping.output_start, mapping.output_end)
        } else {
            emit_source_lines(result, source_lines, mapping.source_start, mapping.source_end)
        }
    }
}

//* Filter a set of statement mapping indices to only "leaf" mappings —
//* those that don't strictly contain any other mapping.
//*
//* A mapping A contains mapping B if B's source range is strictly inside A's.
//* Leaf mappings are the innermost statements, which is what we want for
//* fine-grained range substitution.
def filter_leaf_mappings(all_stmts: &Vector<u32>, stmt_mappings: &Vector<DeclMapping>): &Vector<u32> {
    let leaves = Vector<u32>::new()
    for let a = 0u32; a < all_stmts.size; a++ {
        let sa = stmt_mappings.at(all_stmts.at(a))
        let is_leaf = true
        for let b = 0u32; b < all_stmts.size; b++ {
            if a == b then continue
            let sb = stmt_mappings.at(all_stmts.at(b))
            // B is strictly inside A if B's range is within A's but not identical
            if sb.source_start >= sa.source_start and sb.source_end <= sa.source_end and (sb.source_start > sa.source_start or sb.source_end < sa.source_end) {
                is_leaf = false
                break
            }
        }
        if is_leaf {
            leaves.push(all_stmts.at(a))
        }
    }
    return leaves
}

//* Validate mapping invariants in debug mode.
//*
//* Checks:
//*   1. Declaration mappings are monotonic (source_start non-decreasing)
//*   2. Declaration mappings don't overlap in source ranges
//*   3. All output ranges are valid (start <= end)
//*
//* These assertions catch bugs early when developing formatter changes.
//* Gated on debug_cursor to avoid overhead in production.
def Formatter::validate_mappings(&this) {
    if not .debug_cursor then return
    // Check decl_mappings ordering and non-overlap
    for let i = 0u32; i < .decl_mappings.size; i++ {
        let m = .decl_mappings.at(i)
        // Valid ranges
        if m.source_start > m.source_end {
            eprintln("[formatter] INVARIANT: decl_mapping[%u] has source_start=%u > source_end=%u in %s", i, m.source_start, m.source_end, .filename)
        }
        if m.output_start > m.output_end {
            eprintln("[formatter] INVARIANT: decl_mapping[%u] has output_start=%u > output_end=%u in %s", i, m.output_start, m.output_end, .filename)
        }
        // Monotonicity + non-overlap with previous
        if i > 0 {
            let prev = .decl_mappings.at(i - 1)
            if m.source_start < prev.source_start {
                eprintln("[formatter] INVARIANT: decl_mappings not monotonic: [%u].source_start=%u < [%u].source_start=%u in %s", i, m.source_start, i - 1, prev.source_start, .filename)
            }
            if m.source_start <= prev.source_end {
                eprintln("[formatter] INVARIANT: decl_mappings overlap: [%u].source_start=%u <= [%u].source_end=%u in %s", i, m.source_start, i - 1, prev.source_end, .filename)
            }
        }
    }

    // Check stmt_mappings valid ranges
    for let i = 0u32; i < .stmt_mappings.size; i++ {
        let m = .stmt_mappings.at(i)
        if m.source_start > m.source_end {
            eprintln("[formatter] INVARIANT: stmt_mapping[%u] has source_start=%u > source_end=%u in %s", i, m.source_start, m.source_end, .filename)
        }
        if m.output_start > m.output_end {
            eprintln("[formatter] INVARIANT: stmt_mapping[%u] has output_start=%u > output_end=%u in %s", i, m.output_start, m.output_end, .filename)
        }
    }
}

//* Reconstruct the output for range formatting mode.
//*
//* Strategy: iterate declaration mappings. For non-overlapping declarations,
//* emit source lines verbatim. For overlapping declarations, find leaf
//* statement mappings within them, and splice formatted output only for
//* statements that overlap the requested range.
def Formatter::reconstruct_range(&this, source_lines: &Vector<SV>, formatted_lines: &Vector<SV>): str {
    let result = Buffer::make()

    for let i = 0u32; i < .decl_mappings.size; i++ {
        let decl_map = .decl_mappings.at_ptr(i)

        // Non-overlapping declarations: emit source verbatim
        if not mapping_overlaps_range(decl_map.source_start, decl_map.source_end, .range_start, .range_end) {
            emit_source_lines(&result, source_lines, decl_map.source_start, decl_map.source_end)
            continue
        }

        // Collect all stmt_mappings within this declaration
        let all_stmts = Vector<u32>::new()
        for let k = 0u32; k < .stmt_mappings.size; k++ {
            let stmt_map = .stmt_mappings.at(k)
            if stmt_map.source_start >= decl_map.source_start and stmt_map.source_end <= decl_map.source_end {
                all_stmts.push(k)
            }
        }

        if all_stmts.size == 0 {
            // No statements tracked (import, struct, enum, arrow function, etc.)
            // Treat the whole declaration as a single mapping
            emit_mapping_substitution(&result, decl_map, source_lines, formatted_lines, .range_start, .range_end)
            continue
        }

        // Filter to leaf mappings and iterate in source order
        let leaves = filter_leaf_mappings(all_stmts, .stmt_mappings)
        let prev_source = decl_map.source_start

        for let a = 0u32; a < leaves.size; a++ {
            let stmt_map = .stmt_mappings.at_ptr(leaves.at(a))

            // Handle multiple stmts on same source line (e.g. semicolon-separated).
            // Skip source emission for duplicates; only emit formatted if in range.
            if stmt_map.source_start < prev_source {
                if mapping_overlaps_range(stmt_map.source_start, stmt_map.source_end, .range_start, .range_end) {
                    emit_formatted_lines(&result, formatted_lines, stmt_map.output_start, stmt_map.output_end)
                }
                if stmt_map.source_end >= prev_source {
                    prev_source = stmt_map.source_end + 1
                }
                continue
            }

            // Emit gap: source lines between previous mapping and this one
            emit_source_lines(&result, source_lines, prev_source, stmt_map.source_start - 1)

            // Emit this mapping using the substitution logic
            emit_mapping_substitution(&result, stmt_map, source_lines, formatted_lines, .range_start, .range_end)

            prev_source = stmt_map.source_end + 1
        }

        // Emit remaining source lines after last leaf
        emit_source_lines(&result, source_lines, prev_source, decl_map.source_end)
    }

    // Emit any trailing source lines not covered by any declaration mapping
    let last_covered = 0u32
    if .decl_mappings.size > 0 {
        last_covered = .decl_mappings.at(.decl_mappings.size - 1).source_end
    }
    if last_covered < source_lines.size as u32 {
        emit_source_lines(&result, source_lines, last_covered + 1, source_lines.size as u32)
    }

    return result.str()
}

//* Run the formatter and return the formatted string
def Formatter::run(&this): str {
    let track = .range_start > 0
    .format_ns(.ns, track_mappings: track)
    // Consume any remaining comments after the last namespace declaration
    .emit_remaining_comments()
    if .debug_cursor and .cursor_regressions > 0 {
        eprintln("[formatter] detected %u comment cursor regressions while formatting %s", .cursor_regressions, .filename)
    }
    assert .comment_index == .comments.size, "Formatter ended with un-emitted comments"

    // Verify all comments were actually emitted (not just cursor-advanced past)
    for let i = 0u32; i < .comment_emitted.size; i++ {
        if not .comment_emitted.at(i) {
            let c = .comments.at(i)
            eprintln("[formatter] WARNING: comment not emitted: line %u: %s", c.span.start.line, c.text)
        }
    }

    .align_inline_comments()

    if not track {
        return .output.str()
    }

    // Range mode: validate mapping invariants, then reconstruct output
    .validate_mappings()
    let source_lines = split_lines(.source)
    let formatted_lines = split_lines(.output.str())
    return .reconstruct_range(source_lines, formatted_lines)
}

def format_usage(code: i32) {
    println("Usage:")
    println("   ocen format [options] <file>")
    println("")
    println("Options:")
    println("    --indent N       Set indent size in spaces (default: 4)")
    println("    --line-width N   Set target line width (default: 0 = disabled)")
    println("    --range S:E      Only format declarations overlapping lines S through E")
    println("    -h, --help       Display this information")
    std::exit(code)
}

//* Entry point for `ocen format` subcommand
def format_main(argc: i32, argv: &str): i32 {
    shift_args(&argc, &argv) // skip "format"

    let indent_size: u32 = 4
    let line_width: u32 = 0
    let filename: str = null
    let range_start: u32 = 0
    let range_end: u32 = 0

    while argc > 0 {
        let arg = shift_args(&argc, &argv)
        match arg {
            "--help" | "-h" => format_usage(0)
            "--indent" => {
                if argc == 0 {
                    println("--indent requires a value")
                    format_usage(1)
                }
                let val = shift_args(&argc, &argv)
                indent_size = val.to_u32()
                if indent_size == 0 or indent_size > 16 {
                    println("Invalid indent size: %s (expected 1..16)", val)
                    format_usage(1)
                }
            }
            "--line-width" => {
                if argc == 0 {
                    println("--line-width requires a value")
                    format_usage(1)
                }
                let val = shift_args(&argc, &argv)
                line_width = val.to_u32()
            }
            "--range" => {
                if argc == 0 {
                    println("--range requires a value (start:end)")
                    format_usage(1)
                }
                let val = shift_args(&argc, &argv)
                let sv = SV::from_str(val)
                let start_sv = sv.chop_by_delim(':')
                range_start = start_sv.chop_u32()
                range_end = sv.chop_u32()
                if range_start == 0 or range_end == 0 or range_start > range_end {
                    println("Invalid range: %s (expected start:end where start <= end, 1-based)", val)
                    format_usage(1)
                }
            }
            else => {
                if arg[0] == '-' {
                    println("Unknown option: %s", arg)
                    format_usage(1)
                } else if not filename? {
                    filename = arg
                } else {
                    println("Too many arguments: '%s'", arg)
                    format_usage(1)
                }
            }
        }
    }

    if not filename? {
        println("No file specified")
        format_usage(1)
    }

    if not fs::file_exists(filename) {
        println("File not found: %s", filename)
        return 1
    }

    let contents = fs::read_file(filename).str()

    // Set up a program for parsing
    let program = Program::new()
    program.include_stdlib = false
    program.format_mode = true
    program.error_level = 2

    // Set up error handling
    let err_ctx = program.add_error_context()
    if err_ctx.set_jump_point() > 0 {
        // A parse or lex failure triggered longjmp. Instead of exiting with
        // error code, output the original contents and treat it as a no-op.
        print("%s", contents)
        return 0
    }

    program.setup_library_paths()

    // Parse the file -- errors will be recorded, but we want to continue so
    // we can fall back gracefully.
    Parser::parse_toplevel(program, filename, file_contents: contents, include_workspace_main: false)

    if not program.errors.is_empty() {
        // Parsing produced errors (e.g. lex/parse failure). Don't attempt to
        // format; return original source unchanged.
        print("%s", contents)
        return 0
    }

    let ns = program.global

    // Create formatter and run
    let fmt = Formatter::make(program, ns, contents, filename)
    fmt.options.indent_size = indent_size
    fmt.options.line_width = line_width
    fmt.range_start = range_start
    fmt.range_end = range_end
    let result = fmt.run()

    // Output to stdout
    print("%s", result)

    return 0
}