tokens: Vec<Token>,

pos: usize,

#[allow(dead_code)] source: String,

file: String,

pub errors: ErrorReporter,

pub fn new(tokens: Vec<Token>, source: String, file: String) -> Self {

Self { tokens, pos: 0, source, file, errors: ErrorReporter::new() }

}

// ── Token navigation ──────────────────────────────────────────────────────

fn current(&self) -> &Token {

self.tokens.get(self.pos).unwrap_or_else(|| self.tokens.last().unwrap())

}

fn peek_at(&self, offset: usize) -> &Token {

self.tokens.get(self.pos + offset).unwrap_or_else(|| self.tokens.last().unwrap())

}

fn advance(&mut self) -> &Token {

let t = &self.tokens[self.pos];

if self.pos < self.tokens.len() - 1 { self.pos += 1; }

t

}

fn skip_newlines(&mut self) {

while matches!(self.current().kind, TokenKind::Newline) { self.advance(); }

}

fn at(&self, kind: &TokenKind) -> bool {

std::mem::discriminant(&self.current().kind) == std::mem::discriminant(kind)

}

fn expect(&mut self, kind: &TokenKind) -> Result<Token, ParseError> {

if std::mem::discriminant(&self.current().kind) == std::mem::discriminant(kind) {

Ok(self.advance().clone())

} else {

Err(ParseError::new(

ParseErrorKind::ExpectedToken(format!("{:?}", kind)),

self.current().span.clone(),

format!("expected `{}`, found `{}`", token_kind_name(kind), self.current().text),

vec![format!("add `{}` here", token_kind_name(kind))],

))

}

}

fn expect_ident(&mut self) -> Result<(String, Span), ParseError> {

if let TokenKind::Ident(name) = &self.current().kind {

let name = name.clone();

let span = self.current().span.clone();

self.advance();

Ok((name, span))

} else {

Err(ParseError::new(

ParseErrorKind::ExpectedIdent,

self.current().span.clone(),

format!("expected identifier, found `{}`", self.current().text),

vec!["provide a valid identifier here".to_string()],

))

}

}

/// Like `expect_ident`, but also accepts a fixed set of "soft" keywords

/// that are reserved words in statement/type position but are extremely

/// common as method or path-segment names in real-world APIs — most

/// importantly `new` (`Type::new()`) and `write` (`module::write()`).

/// Without this, `col::HashMap::new()` or `fs::write(...)` fail to

/// parse with a confusing "expected identifier, found `new`" error,

/// even though `new`/`write` are perfectly unambiguous in path-segment

/// position (they can never start a path segment themselves, so there's

/// no grammar conflict in allowing them here).

fn expect_path_segment(&mut self) -> Result<(String, Span), ParseError> {

let span = self.current().span.clone();

let text = match &self.current().kind {

TokenKind::Ident(name) => Some(name.clone()),

TokenKind::New => Some("new".to_string()),

TokenKind::Write => Some("write".to_string()),

TokenKind::Type => Some("type".to_string()),

TokenKind::End => Some("end".to_string()),

TokenKind::As => Some("as".to_string()),

TokenKind::Is => Some("is".to_string()),

TokenKind::From => Some("from".to_string()),

TokenKind::Use => Some("use".to_string()),

TokenKind::Match => Some("match".to_string()),

TokenKind::In => Some("in".to_string()),

TokenKind::For => Some("for".to_string()),

TokenKind::Mod => Some("mod".to_string()),

TokenKind::Async => Some("async".to_string()),

TokenKind::Await => Some("await".to_string()),

TokenKind::Self_ => Some("self".to_string()),

_ => None,

};

match text {

Some(name) => { self.advance(); Ok((name, span)) }

None => Err(ParseError::new(

ParseErrorKind::ExpectedIdent,

span,

format!("expected identifier, found `{}`", self.current().text),

vec!["provide a valid identifier here".to_string()],

)),

}

}

fn error(&self, msg: impl Into<String>, hints: Vec<String>) -> ParseError {

let msg_str: String = msg.into();

ParseError::new(

ParseErrorKind::Custom(msg_str.clone()),

self.current().span.clone(),

msg_str,

hints,

)

}

fn recover(&mut self) {

// Always consume at least one token before checking the stop

// condition. Without this, an error that leaves the cursor sitting

// exactly on a stop-token (e.g. `Fn`) makes recover() a no-op —

// the caller's retry loop then sees the identical token again,

// fails the identical way, calls recover() again, and never makes

// progress. This was the root cause of a real hang (see the

// TokenKind::Fn case in parse_type_base for the original trigger);

// advancing unconditionally here makes recovery robust against

// this whole class of stuck-cursor bugs, not just the one trigger

// that's now also fixed at the source.

if !matches!(self.current().kind, TokenKind::EOF) {

self.advance();

}

while !matches!(self.current().kind,

TokenKind::EOF | TokenKind::Newline | TokenKind::Fn | TokenKind::Struct |

TokenKind::Enum | TokenKind::Impl | TokenKind::Pub | TokenKind::Use |

TokenKind::End)

{

self.advance();

}

}

// ── Module ─────────────────────────────────────────────────────────────────

pub fn parse_module(&mut self) -> Module {

let mut directives = Vec::new();

let mut items = Vec::new();

let mut imports = Vec::new();

let mut edition: Option<String> = None;

self.skip_newlines();

while !matches!(self.current().kind, TokenKind::EOF) {

self.skip_newlines();

if matches!(self.current().kind, TokenKind::EOF) { break; }

// `using "2026"` edition declaration

if matches!(self.current().kind, TokenKind::Using) {

self.advance();

if let TokenKind::StringLit(ed) = &self.current().kind.clone() {

edition = Some(ed.clone());

self.advance();

}

self.skip_newlines();

continue;

}

// Directives ~ / ~~

if let TokenKind::Directive(s) = &self.current().kind.clone() {

let span = self.current().span.clone(); let s = s.clone(); self.advance();

directives.push(Directive { kind: DirectiveKind::Dynamic, value: s, span });

continue;

}

if let TokenKind::FastDirective(s) = &self.current().kind.clone() {

let span = self.current().span.clone(); let s = s.clone(); self.advance();

directives.push(Directive { kind: DirectiveKind::Fast, value: s, span });

continue;

}

// `use` imports

if matches!(self.current().kind, TokenKind::Use) {

match self.parse_import() {

Ok((kind, alias, span)) => imports.push((kind, alias, span)),

Err(e) => { self.errors.report(e); self.recover(); }

}

continue;

}

// Top-level items

match self.parse_item() {

Ok(item) => items.push(item),

Err(e) => { self.errors.report(e); self.recover(); }

}

}

Module { file: self.file.clone(), edition, directives, items, imports }

}

// ── Import ────────────────────────────────────────────────────────────────

fn parse_import(&mut self) -> Result<(ImportKind, Option<String>, Span), ParseError> {

let start = self.current().span.clone();

self.advance(); // consume 'use'

let path_tok = if let TokenKind::StringLit(s) = &self.current().kind.clone() {

let s = s.clone(); self.advance(); s

} else {

return Err(self.error("expected use path string after `use`",

vec![r#"write: use "std -> io" from "io""#.to_string()]));

};

let alias = if matches!(self.current().kind, TokenKind::From) {

self.advance();

if let TokenKind::StringLit(a) = &self.current().kind.clone() {

let a = a.clone(); self.advance(); Some(a)

} else {

return Err(self.error("expected alias string after `from`", vec![]));

}

} else { None };

let span = start.merge(&self.current().span);

let kind = parse_use_path(&path_tok, alias.clone())

.ok_or_else(|| ParseError::new(

ParseErrorKind::Custom("invalid use path".into()),

span.clone(),

format!("cannot parse use path `{}`", path_tok),

vec![r#"valid forms: "std -> module", "vira -> pkg/1.0""#.to_string()],

))?;

Ok((kind, alias, span))

}

// ── Attributes ────────────────────────────────────────────────────────────

fn parse_attributes(&mut self) -> Vec<Attribute> {

let mut attrs = Vec::new();

while matches!(self.current().kind, TokenKind::Hash) {

let span = self.current().span.clone();

self.advance(); // #

if !matches!(self.current().kind, TokenKind::LBracket) { break; }

self.advance(); // [

let (name, _) = self.expect_ident().unwrap_or_else(|_| (String::new(), self.current().span.clone()));

let mut args = Vec::new();

if matches!(self.current().kind, TokenKind::LParen) {

self.advance(); // (

while !matches!(self.current().kind, TokenKind::RParen | TokenKind::EOF) {

let (k, _) = self.expect_ident().unwrap_or_else(|_| (String::new(), self.current().span.clone()));

if matches!(self.current().kind, TokenKind::Assign) {

self.advance();

let v = if let TokenKind::StringLit(s) = &self.current().kind.clone() {

let s = s.clone(); self.advance(); s

} else { String::new() };

args.push(AttrArg::KeyValue(k, v));

} else {

args.push(AttrArg::Ident(k));

}

if matches!(self.current().kind, TokenKind::Comma) { self.advance(); }

}

if matches!(self.current().kind, TokenKind::RParen) { self.advance(); }

}

if matches!(self.current().kind, TokenKind::RBracket) { self.advance(); }

let end_span = self.current().span.clone();

attrs.push(Attribute { name, args, span: span.merge(&end_span) });

self.skip_newlines();

}

attrs

}

// ── Items ─────────────────────────────────────────────────────────────────

fn parse_item(&mut self) -> Result<Item, ParseError> {

self.skip_newlines();

let attrs = self.parse_attributes();

let pub_ = if matches!(self.current().kind, TokenKind::Pub) {

self.advance(); true

} else { false };

match &self.current().kind {

TokenKind::Fn => self.parse_fn_with_attrs(pub_, attrs).map(Item::FnDef),

TokenKind::Struct => self.parse_struct(pub_).map(Item::StructDef),

TokenKind::Enum => self.parse_enum(pub_).map(Item::EnumDef),

TokenKind::Trait => self.parse_trait(pub_).map(Item::TraitDef),

TokenKind::Impl => self.parse_impl().map(Item::ImplBlock),

TokenKind::Type => self.parse_type_alias(pub_),

TokenKind::Async => {

self.advance();

let fn_def = self.parse_fn_with_attrs(pub_, attrs)?;

Ok(Item::FnDef(FnDef { is_async: true, ..fn_def }))

}

TokenKind::Mod => self.parse_mod_decl(pub_),

TokenKind::Extern => self.parse_extern_block_inline(),

TokenKind::Using => {

self.advance();

if let TokenKind::StringLit(_) = &self.current().kind.clone() { self.advance(); }

self.skip_newlines();

self.parse_item()

}

_ => Err(self.error(

format!("unexpected token `{}` at top level", self.current().text),

vec!["expected fn, struct, enum, trait, impl, type, mod, or extern".to_string()],

)),

}

}

fn parse_mod_decl(&mut self, pub_: bool) -> Result<Item, ParseError> {

let span = self.current().span.clone();

self.advance(); // mod

let (name, _) = self.expect_ident()?;

if matches!(self.current().kind, TokenKind::Is) {

self.advance(); self.skip_newlines();

let mut inner = Vec::new();

while !matches!(self.current().kind, TokenKind::End | TokenKind::EOF) {

self.skip_newlines();

if matches!(self.current().kind, TokenKind::End | TokenKind::EOF) { break; }

match self.parse_item() {

Ok(i) => inner.push(i),

Err(e) => { self.errors.report(e); self.recover(); }

}

self.skip_newlines();

}

self.expect(&TokenKind::End)?;

let end = self.current().span.clone();

Ok(Item::ModDecl { name, pub_, inline: Some(inner), span: span.merge(&end) })

} else {

let end = self.current().span.clone();

Ok(Item::ModDecl { name, pub_, inline: None, span: span.merge(&end) })

}

}

fn parse_fn(&mut self, pub_: bool) -> Result<FnDef, ParseError> {

self.parse_fn_with_attrs(pub_, vec![])

}

fn parse_fn_with_attrs(&mut self, pub_: bool, attrs: Vec<Attribute>) -> Result<FnDef, ParseError> {

let start = self.current().span.clone();

self.advance(); // fn

let is_async = if matches!(self.current().kind, TokenKind::Async) { self.advance(); true } else { false };

let is_unsafe = if matches!(self.current().kind, TokenKind::Unsafe) { self.advance(); true } else { false };

// Use expect_path_segment (not expect_ident) here: `new` and `write`

// are reserved keyword tokens but are also extremely common

// function/method names (`fn new(...)`, constructor-style; `fn

// write(...)`, e.g. inside `impl Buffer`). They're unambiguous in

// this position — nothing else can follow `fn` here — so accepting

// them avoids a confusing "expected identifier, found `new`" error

// on otherwise completely ordinary code (see tests/core/types_test.h#'s

// `impl Point is fn new(x, y) -> Point ... end end`).

let (name, _) = self.expect_path_segment()?;

let type_params = self.parse_generics_decl()?;

self.expect(&TokenKind::LParen)?;

let params = self.parse_params()?;

self.expect(&TokenKind::RParen)?;

let return_type = if matches!(self.current().kind, TokenKind::Arrow) {

self.advance(); Some(self.parse_type()?)

} else { None };

self.skip_newlines();

let body = self.parse_block()?;

let span = start.merge(&self.current().span);

Ok(FnDef { attrs, type_params, name, params, return_type, body, pub_, is_async, is_unsafe, span })

}

fn parse_params(&mut self) -> Result<Vec<Param>, ParseError> {

let mut params = Vec::new();

while !matches!(self.current().kind, TokenKind::RParen | TokenKind::EOF) {

self.skip_newlines();

if matches!(self.current().kind, TokenKind::RParen) { break; }

let span = self.current().span.clone();

let mutable = if matches!(self.current().kind, TokenKind::Mut) { self.advance(); true } else { false };

if matches!(self.current().kind, TokenKind::Self_) {

let s = self.advance().span.clone();

params.push(Param { name: "self".to_string(), ty: TypeExpr::Named("Self".to_string()), mutable, span: s });

} else {

let (name, _) = self.expect_ident()?;

self.expect(&TokenKind::Colon)?;

let ty = self.parse_type()?;

params.push(Param { name, ty, mutable, span });

}

if matches!(self.current().kind, TokenKind::Comma) { self.advance(); } else { break; }

}

Ok(params)

}

fn parse_block(&mut self) -> Result<Vec<Stmt>, ParseError> {

self.skip_newlines();

let mut stmts = Vec::new();

if matches!(self.current().kind, TokenKind::Is) {

self.advance(); self.skip_newlines();

while !matches!(self.current().kind, TokenKind::End | TokenKind::EOF) {

self.skip_newlines();

if matches!(self.current().kind, TokenKind::End | TokenKind::EOF) { break; }

match self.parse_stmt() {

Ok(s) => stmts.extend(s),

Err(e) => { self.errors.report(e); self.recover(); }

}

self.skip_newlines();

}

self.expect(&TokenKind::End)?;

} else if matches!(self.current().kind, TokenKind::Assign) {

self.advance();

let expr = self.parse_expr(0)?;

let span = expr.span().clone();

stmts.push(Stmt::Return(Some(expr), span));

} else {

return Err(self.error(

"expected `is` to start a block body",

vec!["write `is` before the body and `end` after".to_string()],

));

}

Ok(stmts)

}

/// Parse an if-branch body — stops at else/elsif/end without consuming them

fn parse_if_body(&mut self) -> Result<Vec<Stmt>, ParseError> {

self.skip_newlines();

// Must start with `is`

if !matches!(self.current().kind, TokenKind::Is) {

return Err(self.error(

"expected `is` after condition",

vec!["write: if cond is ... end".to_string()],

));

}

self.advance(); // consume `is`

self.skip_newlines();

let mut stmts = Vec::new();

loop {

self.skip_newlines();

match self.current().kind {

TokenKind::End | TokenKind::EOF => break,

TokenKind::Else | TokenKind::Elsif => break,

_ => {}

}

match self.parse_stmt() {

Ok(s) => stmts.extend(s),

Err(e) => { self.errors.report(e); self.recover(); }

}

}

// Only consume `end` if there is no else/elsif following

if matches!(self.current().kind, TokenKind::End) {

self.advance();

}

Ok(stmts)

}

fn parse_struct(&mut self, pub_: bool) -> Result<StructDef, ParseError> {

let start = self.current().span.clone();

self.advance(); // struct

let (name, _) = self.expect_ident()?;

let type_params = self.parse_generics_decl()?;

self.skip_newlines();

let mut fields = Vec::new();

if matches!(self.current().kind, TokenKind::Is) {

self.advance(); self.skip_newlines();

while !matches!(self.current().kind, TokenKind::End | TokenKind::EOF) {

self.skip_newlines();

if matches!(self.current().kind, TokenKind::End) { break; }

let fpub = if matches!(self.current().kind, TokenKind::Pub) { self.advance(); true } else { false };

let fspan = self.current().span.clone();

let (fname, _) = self.expect_ident()?;

self.expect(&TokenKind::Colon)?;

let fty = self.parse_type()?;

fields.push(StructField { name: fname, ty: fty, pub_: fpub, span: fspan });

self.skip_newlines();

}

self.expect(&TokenKind::End)?;

}

let span = start.merge(&self.current().span);

Ok(StructDef { attrs: vec![], type_params, name, fields, pub_, span })

}

fn parse_enum(&mut self, pub_: bool) -> Result<EnumDef, ParseError> {

let start = self.current().span.clone();

self.advance(); // enum

let (name, _) = self.expect_ident()?;

let type_params = self.parse_generics_decl()?;

self.skip_newlines();

let mut variants = Vec::new();

if matches!(self.current().kind, TokenKind::Is) {

self.advance(); self.skip_newlines();

while !matches!(self.current().kind, TokenKind::End | TokenKind::EOF) {

self.skip_newlines();

if matches!(self.current().kind, TokenKind::End) { break; }

let vspan = self.current().span.clone();

let (vname, _) = self.expect_ident()?;

let fields = if matches!(self.current().kind, TokenKind::LParen) {

self.advance();

let mut types = Vec::new();

while !matches!(self.current().kind, TokenKind::RParen | TokenKind::EOF) {

types.push(self.parse_type()?);

if matches!(self.current().kind, TokenKind::Comma) { self.advance(); }

}

self.expect(&TokenKind::RParen)?;

EnumVariantFields::Tuple(types)

} else if matches!(self.current().kind, TokenKind::Is) {

// Struct variant: Variant is field: T ... end

self.advance(); self.skip_newlines();

let mut sfields = Vec::new();

while !matches!(self.current().kind, TokenKind::End | TokenKind::EOF) {

self.skip_newlines();

if matches!(self.current().kind, TokenKind::End) { break; }

let fpub = if matches!(self.current().kind, TokenKind::Pub) { self.advance(); true } else { false };

let fs = self.current().span.clone();

let (fn_, _) = self.expect_ident()?;

self.expect(&TokenKind::Colon)?;

let ft = self.parse_type()?;

sfields.push(StructField { name: fn_, ty: ft, pub_: fpub, span: fs });

self.skip_newlines();

}

self.expect(&TokenKind::End)?;

EnumVariantFields::Struct(sfields)

} else {

EnumVariantFields::Unit

};

variants.push(EnumVariant { name: vname, fields, span: vspan });

if matches!(self.current().kind, TokenKind::Comma) { self.advance(); }

self.skip_newlines();

}

self.expect(&TokenKind::End)?;

}

let span = start.merge(&self.current().span);

Ok(EnumDef { attrs: vec![], type_params, name, variants, pub_, span })

}

fn parse_trait(&mut self, pub_: bool) -> Result<TraitDef, ParseError> {

let start = self.current().span.clone();

self.advance(); // trait

let (name, _) = self.expect_ident()?;

self.skip_newlines();

let mut methods = Vec::new();

if matches!(self.current().kind, TokenKind::Is) {

self.advance(); self.skip_newlines();

while !matches!(self.current().kind, TokenKind::End | TokenKind::EOF) {

self.skip_newlines();

if matches!(self.current().kind, TokenKind::End) { break; }

if matches!(self.current().kind, TokenKind::Fn) {

self.advance();

let mspan = self.current().span.clone();

let (mname, _) = self.expect_ident()?;

self.expect(&TokenKind::LParen)?;

let params = self.parse_params()?;

self.expect(&TokenKind::RParen)?;

let ret = if matches!(self.current().kind, TokenKind::Arrow) {

self.advance(); Some(self.parse_type()?)

} else { None };

self.skip_newlines();

let default_body = if matches!(self.current().kind, TokenKind::Is) {

Some(self.parse_block()?)

} else { None };

methods.push(TraitMethod { name: mname, params, return_type: ret, default_body, span: mspan });

} else {

let e = self.error("expected `fn` in trait", vec![]);

self.errors.report(e); self.recover();

}

self.skip_newlines();

}

self.expect(&TokenKind::End)?;

}

let span = start.merge(&self.current().span);

Ok(TraitDef { attrs: vec![], type_params: vec![], name, methods, pub_, span })

}

fn parse_impl(&mut self) -> Result<ImplBlock, ParseError> {

let start = self.current().span.clone();

self.advance(); // impl

let (type_name, _) = self.expect_ident()?;

let trait_name = if matches!(self.current().kind, TokenKind::Colon) {

self.advance(); let (t, _) = self.expect_ident()?; Some(t)

} else { None };

self.skip_newlines();

let mut methods = Vec::new();

if matches!(self.current().kind, TokenKind::Is) {

self.advance(); self.skip_newlines();

while !matches!(self.current().kind, TokenKind::End | TokenKind::EOF) {

self.skip_newlines();

if matches!(self.current().kind, TokenKind::End) { break; }

let pub_ = if matches!(self.current().kind, TokenKind::Pub) { self.advance(); true } else { false };