@starpak/lang 0.0.0-stage → 0.1.2

package/src/parser.ts

@@ -0,0 +1,1251 @@
+/**
+ * Spak Lang - Recursive descent parser
+ *
+ * Produces an AST (`Program`) from Spak source. The grammar follows
+ * docs/syntax/spak-lang.md.
+ */
+
+import type {
+  ArrayPattern,
+  Assign,
+  AwaitExpr,
+  Binary,
+  Block,
+  BreakStmt,
+  Call,
+  ClassDecl,
+  ContinueStmt,
+  Decorator,
+  ElifBranch,
+  Expr,
+  ExportDecl,
+  ExportDefault,
+  FnDecl,
+  ForIn,
+  ForNumeric,
+  FunctionExpr,
+  Ident,
+  IfStmt,
+  ImportClause,
+  ImportDecl,
+  Index,
+  MatchArm,
+  MatchStmt,
+  Member,
+  Param,
+  Pattern,
+  Position,
+  Program,
+  Range,
+  RepeatStmt,
+  ReturnStmt,
+  SpawnStmt,
+  Spread,
+  Statement,
+  StringLit,
+  Table,
+  TableField,
+  TablePattern,
+  TablePatternEntry,
+  ThrowStmt,
+  TryStmt,
+  TypeAliasDecl,
+  TypeAnn,
+  UnlessStmt,
+  VarDecl,
+  VarName,
+  WhileStmt,
+} from './ast'
+import { tokenize } from './lexer'
+import { Token, TokenType } from './token'
+
+/**
+ * Binary operator precedence, low to high. `^` is right-associative.
+ */
+const BINARY_PRECEDENCE: Record<string, number> = {
+  'or': 1,
+  'and': 2,
+  '==': 3,
+  '~=': 3,
+  '<': 3,
+  '<=': 3,
+  '>': 3,
+  '>=': 3,
+  '|>': 4,
+  '??': 5,
+  '..': 6,
+  '+': 7,
+  '-': 7,
+  '*': 8,
+  '/': 8,
+  '//': 8,
+  '%': 8,
+  '^': 10,
+}
+
+const UNARY_PRECEDENCE = 9
+
+const BLOCK_END_KEYWORDS = [
+  'end', 'else', 'elseif', 'when', 'until', 'catch', 'finally',
+]
+
+const PRIMITIVE_TYPE_NAMES = new Set([
+  'any', 'nil', 'number', 'string', 'boolean', 'table', 'function',
+])
+
+/** Statement kinds that may carry a `---` doc comment. */
+const DOC_STATEMENTS = new Set([
+  'FnDecl', 'ClassDecl', 'VarDecl', 'TypeAliasDecl', 'ExportDecl', 'ImportDecl',
+])
+
+function isNameToken(token: Token): boolean {
+  return token.type === TokenType.Identifier || token.type === TokenType.Keyword
+}
+
+class Parser {
+  private tokens: Token[]
+  private pos = 0
+
+  constructor(source: string) {
+    this.tokens = tokenize(source)
+  }
+
+  /* ---------------------------------------------------------------- */
+  /* Token helpers                                                     */
+  /* ---------------------------------------------------------------- */
+
+  private peek(offset = 0): Token {
+    const index = this.pos + offset
+    return this.tokens[index < this.tokens.length ? index : this.tokens.length - 1]
+  }
+
+  private next(): Token {
+    const token = this.peek()
+    if (this.pos < this.tokens.length - 1) this.pos++
+    return token
+  }
+
+  private at(type: TokenType, value?: string): boolean {
+    const token = this.peek()
+    return token.type === type && (value === undefined || token.value === value)
+  }
+
+  private atKeyword(value: string): boolean {
+    return this.at(TokenType.Keyword, value)
+  }
+
+  private atOperator(value: string): boolean {
+    return this.at(TokenType.Operator, value)
+  }
+
+  private match(type: TokenType, value?: string): boolean {
+    if (!this.at(type, value)) return false
+    this.next()
+    return true
+  }
+
+  private matchKeyword(value: string): boolean {
+    return this.match(TokenType.Keyword, value)
+  }
+
+  private matchOperator(value: string): boolean {
+    return this.match(TokenType.Operator, value)
+  }
+
+  private expect(type: TokenType, value?: string, message?: string): Token {
+    if (this.at(type, value)) return this.next()
+    const token = this.peek()
+    throw this.error(message ?? `Expected ${value ?? type} but got "${token.value}"`, token)
+  }
+
+  private expectKeyword(value: string): Token {
+    return this.expect(TokenType.Keyword, value, `Expected "${value}"`)
+  }
+
+  private expectName(message: string): Token {
+    if (isNameToken(this.peek())) return this.next()
+    throw this.error(message)
+  }
+
+  private error(message: string, token: Token = this.peek()): SyntaxError {
+    return new SyntaxError(`${message} at ${token.line}:${token.column}`)
+  }
+
+  private loc(token: Token): Position {
+    return { line: token.line, column: token.column }
+  }
+
+  private skipNewlines(): void {
+    while (this.at(TokenType.Newline)) this.next()
+  }
+
+  private skipSeparators(): void {
+    while (this.at(TokenType.Newline) || this.at(TokenType.Semicolon)) this.next()
+  }
+
+  private isBlockEnd(): boolean {
+    const token = this.peek()
+    return token.type === TokenType.Keyword && BLOCK_END_KEYWORDS.includes(token.value)
+  }
+
+  private isStatementEnd(): boolean {
+    const token = this.peek()
+    return token.type === TokenType.EOF
+      || token.type === TokenType.Newline
+      || token.type === TokenType.Semicolon
+      || this.isBlockEnd()
+  }
+
+  /* ---------------------------------------------------------------- */
+  /* Program & statements                                              */
+  /* ---------------------------------------------------------------- */
+
+  parseProgram(): Program {
+    const start = this.peek()
+    const body: Statement[] = []
+    this.skipSeparators()
+    while (!this.at(TokenType.EOF)) {
+      const before = this.pos
+      body.push(this.parseStatement())
+      if (this.pos === before) throw this.error('Unexpected token')
+      this.skipSeparators()
+    }
+    return { kind: 'Program', body, loc: this.loc(start) }
+  }
+
+  private parseStatement(): Statement {
+    const doc = this.peek().doc
+    const statement = this.parseStatementCore()
+    if (doc && DOC_STATEMENTS.has(statement.kind)) {
+      ;(statement as FnDecl | ClassDecl | VarDecl | TypeAliasDecl | ExportDecl | ImportDecl).doc = doc
+    }
+    return statement
+  }
+
+  private parseStatementCore(): Statement {
+    const token = this.peek()
+
+    if (token.type === TokenType.Operator && token.value === '@') {
+      return this.parseDecoratedDeclaration()
+    }
+
+    if (token.type === TokenType.Keyword) {
+      switch (token.value) {
+        case 'global':
+          return this.parseVarDeclaration('global')
+        case 'const':
+          return this.parseVarDeclaration('const')
+        case 'import':
+          return this.parseImport()
+        case 'export':
+          return this.parseExport()
+        case 'type':
+          return this.parseTypeAlias()
+        case 'fn':
+          return this.parseFnDecl([], false, false)
+        case 'class':
+          return this.parseClassDecl([])
+        case 'async':
+          if (this.peek(1).type === TokenType.Keyword && this.peek(1).value === 'fn') {
+            this.next()
+            return this.parseFnDecl([], true, false)
+          }
+          break
+        case 'throw':
+          return this.parseThrow()
+        case 'spawn':
+          return this.parseSpawn()
+        case 'if':
+          return this.parseIf()
+        case 'unless':
+          return this.parseUnless()
+        case 'while':
+          return this.parseWhile()
+        case 'repeat':
+          return this.parseRepeat()
+        case 'for':
+          return this.parseFor()
+        case 'return':
+          return this.parseReturn()
+        case 'break': {
+          const keyword = this.next()
+          return { kind: 'BreakStmt', loc: this.loc(keyword) } as BreakStmt
+        }
+        case 'continue': {
+          const keyword = this.next()
+          return { kind: 'ContinueStmt', loc: this.loc(keyword) } as ContinueStmt
+        }
+        case 'match':
+          return this.parseMatch()
+        case 'try':
+          return this.parseTry()
+      }
+    }
+
+    return this.parseSimpleStatement()
+  }
+
+  private parseBlock(terminators: string[]): Block {
+    const start = this.peek()
+    const body: Statement[] = []
+    this.skipSeparators()
+    while (!this.at(TokenType.EOF)) {
+      const token = this.peek()
+      if (token.type === TokenType.Keyword && terminators.includes(token.value)) break
+      const before = this.pos
+      body.push(this.parseStatement())
+      if (this.pos === before) throw this.error('Unexpected token')
+      this.skipSeparators()
+    }
+    return { kind: 'Block', body, loc: this.loc(start) }
+  }
+
+  private parseVarDeclaration(scope: 'local' | 'global' | 'const'): VarDecl {
+    const keyword = this.next()
+    const names: VarName[] = []
+    do {
+      const name = this.expect(TokenType.Identifier, undefined, 'Expected variable name')
+      const entry: VarName = { name: name.value }
+      if (this.matchOperator(':')) entry.type = this.parseType()
+      names.push(entry)
+    } while (this.matchOperator(','))
+
+    const values = this.matchOperator('=') ? this.parseExprList() : []
+    return { kind: 'VarDecl', names, values, scope, loc: this.loc(keyword) }
+  }
+
+  private parseSimpleStatement(): Statement {
+    const start = this.peek()
+
+    // Destructuring assignment: `{ x, y } = p` / `[a, b] = list`.
+    if (this.atOperator('{') || this.atOperator('[')) {
+      const saved = this.pos
+      try {
+        const target = this.parsePattern()
+        if (this.matchOperator('=')) {
+          const values = this.parseExprList()
+          const node: Assign = { kind: 'Assign', targets: [target], values, loc: this.loc(start) }
+          return node
+        }
+      } catch {
+        // Not a pattern; rewind and parse it as an expression instead.
+      }
+      this.pos = saved
+    }
+
+    const first = this.parseExpression()
+
+    // Typed declaration without a keyword: x: number = 1
+    if (first.kind === 'Ident' && this.atOperator(':')) {
+      this.next()
+      const type = this.parseType()
+      const name: VarName = { name: first.name, type }
+      const values = this.matchOperator('=') ? this.parseExprList() : []
+      return { kind: 'VarDecl', names: [name], values, scope: 'local', loc: first.loc }
+    }
+
+    const targets: Array<Expr | Pattern> = [first]
+    while (this.matchOperator(',')) targets.push(this.parseExpression())
+
+    if (this.matchOperator('=')) {
+      const values = this.parseExprList()
+      // Assignment is declaration: plain identifiers create local bindings.
+      if (targets.every((target) => target.kind === 'Ident')) {
+        const names: VarName[] = targets.map((target) => ({ name: (target as Ident).name }))
+        return { kind: 'VarDecl', names, values, scope: 'local', loc: this.loc(start) }
+      }
+      return { kind: 'Assign', targets, values, loc: this.loc(start) } as Assign
+    }
+
+    if (targets.length > 1) throw this.error('Expected "=" in assignment')
+    return { kind: 'ExprStmt', expr: first, loc: this.loc(start) }
+  }
+
+  private parsePattern(): Pattern {
+    if (this.atOperator('{')) return this.parseTablePattern()
+    if (this.atOperator('[')) return this.parseArrayPattern()
+    throw this.error('Expected destructuring pattern')
+  }
+
+  private parseTablePattern(): TablePattern {
+    const start = this.expect(TokenType.Operator, '{')
+    const entries: TablePatternEntry[] = []
+    this.skipNewlines()
+
+    while (!this.atOperator('}')) {
+      const key = this.expectName('Expected field name in table pattern')
+      const entry: TablePatternEntry = { key: key.value }
+      if (this.matchOperator('=')) {
+        const value = this.parseExpression()
+        // `{ a = first }` renames, any other value is a default.
+        if (value.kind === 'Ident') entry.target = (value as Ident).name
+        else entry.default = value
+      }
+      entries.push(entry)
+      this.skipNewlines()
+      if (!this.matchOperator(',')) break
+      this.skipNewlines()
+    }
+
+    this.expect(TokenType.Operator, '}', 'Expected "}"')
+    return { kind: 'TablePattern', entries, loc: this.loc(start) }
+  }
+
+  private parseArrayPattern(): ArrayPattern {
+    const start = this.expect(TokenType.Operator, '[')
+    const elements: string[] = []
+    this.skipNewlines()
+
+    while (!this.atOperator(']')) {
+      const name = this.expectName('Expected name in array pattern')
+      elements.push(name.value)
+      this.skipNewlines()
+      if (!this.matchOperator(',')) break
+      this.skipNewlines()
+    }
+
+    this.expect(TokenType.Operator, ']', 'Expected "]"')
+    return { kind: 'ArrayPattern', elements, loc: this.loc(start) }
+  }
+
+  private parseFnDecl(decorators: Decorator[], isAsync: boolean, isMethod: boolean): FnDecl {
+    const start = this.expectKeyword('fn')
+    let name = this.expect(TokenType.Identifier, undefined, 'Expected function name').value
+    let receiver: string | undefined
+    if (this.matchOperator(':')) {
+      receiver = name
+      name = this.expect(TokenType.Identifier, undefined, 'Expected method name').value
+    }
+
+    const params = this.parseParams()
+    const returnType = this.matchOperator(':') ? this.parseType() : undefined
+
+    let body: Block | undefined
+    let exprBody: Expr | undefined
+    if (this.matchOperator('=')) {
+      exprBody = this.parseExpression()
+    } else {
+      body = this.parseBlock(['end'])
+      this.expectKeyword('end')
+    }
+
+    const decl: FnDecl = {
+      kind: 'FnDecl',
+      name,
+      params,
+      returnType,
+      body,
+      exprBody,
+      isMethod: isMethod || !!receiver,
+      decorators,
+      loc: this.loc(start),
+    }
+    if (receiver) decl.receiver = receiver
+    if (isAsync) decl.async = true
+    return decl
+  }
+
+  private parseParams(): Param[] {
+    this.expect(TokenType.Operator, '(', 'Expected "("')
+    const params: Param[] = []
+    this.skipNewlines()
+
+    while (!this.atOperator(')')) {
+      if (this.matchOperator('...')) {
+        params.push({ name: '...', rest: true })
+        this.skipNewlines()
+        break
+      }
+      const name = this.expect(TokenType.Identifier, undefined, 'Expected parameter name')
+      const param: Param = { name: name.value }
+      if (this.matchOperator(':')) param.type = this.parseType()
+      if (this.matchOperator('=')) param.default = this.parseExpression()
+      params.push(param)
+      this.skipNewlines()
+      if (!this.matchOperator(',')) break
+      this.skipNewlines()
+    }
+
+    this.expect(TokenType.Operator, ')', 'Expected ")"')
+    return params
+  }
+
+  private parseDecorators(): Decorator[] {
+    const decorators: Decorator[] = []
+    while (this.atOperator('@')) {
+      const at = this.next()
+      const name = this.expect(TokenType.Identifier, undefined, 'Expected decorator name').value
+      const args = this.atOperator('(') ? this.parseArguments() : []
+      decorators.push({ kind: 'Decorator', name, args, loc: this.loc(at) })
+      this.skipNewlines()
+    }
+    return decorators
+  }
+
+  private parseDecoratedDeclaration(): Statement {
+    const decorators = this.parseDecorators()
+    if (this.atKeyword('class')) return this.parseClassDecl(decorators)
+    if (this.atKeyword('async') && this.peek(1).value === 'fn') {
+      this.next()
+      return this.parseFnDecl(decorators, true, false)
+    }
+    if (this.atKeyword('fn')) return this.parseFnDecl(decorators, false, false)
+    throw this.error('Expected "fn" or "class" after decorator')
+  }
+
+  private parseClassDecl(decorators: Decorator[]): ClassDecl {
+    const start = this.expectKeyword('class')
+    const name = this.expect(TokenType.Identifier, undefined, 'Expected class name').value
+    const superClass = this.matchKeyword('extends')
+      ? this.expect(TokenType.Identifier, undefined, 'Expected super class name').value
+      : undefined
+
+    const members: Array<FnDecl | VarDecl> = []
+    this.skipSeparators()
+    while (!this.atKeyword('end') && !this.at(TokenType.EOF)) {
+      const doc = this.peek().doc
+      let member: FnDecl | VarDecl
+      if (this.atOperator('@')) {
+        member = this.parseClassMember(this.parseDecorators())
+      } else {
+        member = this.parseClassMember([])
+      }
+      if (doc) member.doc = doc
+      members.push(member)
+      this.skipSeparators()
+    }
+
+    this.expectKeyword('end')
+    return { kind: 'ClassDecl', name, superClass, members, decorators, loc: this.loc(start) }
+  }
+
+  /** Parses one class body member, with decorators already consumed. */
+  private parseClassMember(decorators: Decorator[]): FnDecl | VarDecl {
+    if (this.atKeyword('async') && this.peek(1).value === 'fn') {
+      this.next()
+      return this.parseFnDecl(decorators, true, true)
+    }
+    if (this.atKeyword('fn')) return this.parseFnDecl(decorators, false, true)
+    return this.parseField(decorators)
+  }
+
+  private parseField(decorators: Decorator[] = []): VarDecl {
+    const name = this.expectName('Expected field name')
+    const entry: VarName = { name: name.value }
+    if (this.matchOperator(':')) entry.type = this.parseType()
+    const values = this.matchOperator('=') ? [this.parseExpression()] : []
+    const decl: VarDecl = { kind: 'VarDecl', names: [entry], values, scope: 'local', loc: this.loc(name) }
+    if (decorators.length) decl.decorators = decorators
+    return decl
+  }
+
+  private parseIf(): IfStmt {
+    const start = this.expectKeyword('if')
+    const cond = this.parseExpression()
+    this.expectKeyword('then')
+    const then = this.parseBlock(['elseif', 'else', 'end'])
+
+    const elifs: ElifBranch[] = []
+    while (this.matchKeyword('elseif')) {
+      const elifCond = this.parseExpression()
+      this.expectKeyword('then')
+      const body = this.parseBlock(['elseif', 'else', 'end'])
+      elifs.push({ cond: elifCond, body })
+    }
+
+    const elseBody = this.matchKeyword('else') ? this.parseBlock(['end']) : undefined
+    this.expectKeyword('end')
+    return { kind: 'IfStmt', cond, then, elifs, else: elseBody, loc: this.loc(start) }
+  }
+
+  private parseUnless(): UnlessStmt {
+    const start = this.expectKeyword('unless')
+    const cond = this.parseExpression()
+    this.expectKeyword('do')
+    const body = this.parseBlock(['end'])
+    this.expectKeyword('end')
+    return { kind: 'UnlessStmt', cond, body, loc: this.loc(start) }
+  }
+
+  private parseWhile(): WhileStmt {
+    const start = this.expectKeyword('while')
+    const cond = this.parseExpression()
+    this.expectKeyword('do')
+    const body = this.parseBlock(['end'])
+    this.expectKeyword('end')
+    return { kind: 'WhileStmt', cond, body, loc: this.loc(start) }
+  }
+
+  private parseRepeat(): RepeatStmt {
+    const start = this.expectKeyword('repeat')
+    const body = this.parseBlock(['until'])
+    this.expectKeyword('until')
+    const cond = this.parseExpression()
+    return { kind: 'RepeatStmt', body, cond, loc: this.loc(start) }
+  }
+
+  private parseFor(): Statement {
+    const start = this.expectKeyword('for')
+    const first = this.expect(TokenType.Identifier, undefined, 'Expected loop variable')
+    const vars = [first.value]
+    while (this.atOperator(',')) {
+      this.next()
+      vars.push(this.expect(TokenType.Identifier, undefined, 'Expected loop variable').value)
+    }
+
+    if (this.matchOperator('=')) {
+      if (vars.length > 1) throw this.error('Numeric for accepts a single variable')
+      const from = this.parseExpression()
+      this.expect(TokenType.Operator, ',', 'Expected "," in numeric for')
+      const to = this.parseExpression()
+      const step = this.matchOperator(',') ? this.parseExpression() : undefined
+      this.expectKeyword('do')
+      const body = this.parseBlock(['end'])
+      this.expectKeyword('end')
+      const node: ForNumeric = {
+        kind: 'ForNumeric',
+        varName: first.value,
+        from,
+        to,
+        step,
+        inclusive: true,
+        body,
+        loc: this.loc(start),
+      }
+      return node
+    }
+
+    this.expectKeyword('in')
+    const iter = this.parseRangeExpr()
+    this.expectKeyword('do')
+    const body = this.parseBlock(['end'])
+    this.expectKeyword('end')
+    const node: ForIn = { kind: 'ForIn', vars, iter, body, loc: this.loc(start) }
+    return node
+  }
+
+  private parseReturn(): ReturnStmt {
+    const start = this.expectKeyword('return')
+    const values = this.isStatementEnd() ? [] : this.parseExprList()
+    return { kind: 'ReturnStmt', values, loc: this.loc(start) }
+  }
+
+  private parseThrow(): ThrowStmt {
+    const start = this.expectKeyword('throw')
+    if (this.isStatementEnd()) throw this.error('Expected expression after "throw"')
+    return { kind: 'ThrowStmt', value: this.parseExpression(), loc: this.loc(start) }
+  }
+
+  private parseSpawn(): SpawnStmt {
+    const start = this.expectKeyword('spawn')
+    if (this.isStatementEnd()) throw this.error('Expected expression after "spawn"')
+    return { kind: 'SpawnStmt', value: this.parseExpression(), loc: this.loc(start) }
+  }
+
+  private parseMatch(): MatchStmt {
+    const start = this.expectKeyword('match')
+    const subject = this.parseExpression()
+    this.skipSeparators()
+
+    const arms: MatchArm[] = []
+    while (this.atKeyword('when')) {
+      const when = this.next()
+      const patterns = this.parseExprList()
+      const guard = this.matchKeyword('if') ? this.parseExpression() : undefined
+      this.expectKeyword('then')
+      const body = this.parseBlock(['when', 'else', 'end'])
+      arms.push({ patterns, guard, body, loc: this.loc(when) })
+      this.skipSeparators()
+    }
+
+    const elseBody = this.matchKeyword('else') ? this.parseBlock(['end']) : undefined
+    this.expectKeyword('end')
+    return { kind: 'MatchStmt', subject, arms, elseBody, loc: this.loc(start) }
+  }
+
+  private parseTry(): TryStmt {
+    const start = this.expectKeyword('try')
+    const body = this.parseBlock(['catch', 'finally', 'end'])
+
+    let catchVar: string | undefined
+    let catchType: TypeAnn | undefined
+    let catchBody: Block | undefined
+    if (this.matchKeyword('catch')) {
+      if (this.at(TokenType.Identifier)) {
+        catchVar = this.next().value
+        if (this.matchOperator(':')) catchType = this.parseType()
+      }
+      catchBody = this.parseBlock(['finally', 'end'])
+    }
+
+    const finallyBody = this.matchKeyword('finally') ? this.parseBlock(['end']) : undefined
+    this.expectKeyword('end')
+    return { kind: 'TryStmt', body, catchVar, catchType, catchBody, finallyBody, loc: this.loc(start) }
+  }
+
+  private parseImport(): ImportDecl {
+    const start = this.expectKeyword('import')
+    const clauses: ImportClause[] = []
+    let source: string
+
+    if (this.at(TokenType.String)) {
+      source = this.next().value
+    } else if (this.matchOperator('{')) {
+      this.skipNewlines()
+      while (!this.atOperator('}')) {
+        const name = this.expect(TokenType.Identifier, undefined, 'Expected import name')
+        const clause: ImportClause = { name: name.value }
+        if (this.matchKeyword('as')) {
+          clause.alias = this.expect(TokenType.Identifier, undefined, 'Expected alias').value
+        }
+        clauses.push(clause)
+        this.skipNewlines()
+        if (!this.matchOperator(',')) break
+        this.skipNewlines()
+      }
+      this.expect(TokenType.Operator, '}', 'Expected "}"')
+      this.expectKeyword('from')
+      source = this.expect(TokenType.String, undefined, 'Expected module path').value
+    } else if (this.matchOperator('*')) {
+      this.expectKeyword('as')
+      const alias = this.expect(TokenType.Identifier, undefined, 'Expected namespace alias')
+      clauses.push({ name: '*', alias: alias.value })
+      this.expectKeyword('from')
+      source = this.expect(TokenType.String, undefined, 'Expected module path').value
+    } else {
+      const name = this.expect(TokenType.Identifier, undefined, 'Expected import name')
+      const clause: ImportClause = { name: name.value }
+      if (this.matchKeyword('as')) {
+        clause.alias = this.expect(TokenType.Identifier, undefined, 'Expected alias').value
+      }
+      clauses.push(clause)
+      this.expectKeyword('from')
+      source = this.expect(TokenType.String, undefined, 'Expected module path').value
+    }
+
+    return { kind: 'ImportDecl', clauses, source, loc: this.loc(start) }
+  }
+
+  private parseExport(): Statement {
+    const start = this.expectKeyword('export')
+    if (this.matchKeyword('default')) {
+      const expr = this.parseExpression()
+      const node: ExportDefault = { kind: 'ExportDefault', expr, loc: this.loc(start) }
+      return node
+    }
+
+    let declaration: Statement
+    if (this.atKeyword('const')) declaration = this.parseVarDeclaration('const')
+    else if (this.atKeyword('global')) declaration = this.parseVarDeclaration('global')
+    else if (this.atKeyword('fn')) declaration = this.parseFnDecl([], false, false)
+    else if (this.atKeyword('class')) declaration = this.parseClassDecl([])
+    else if (this.atKeyword('type')) declaration = this.parseTypeAlias()
+    else if (this.atKeyword('async') && this.peek(1).value === 'fn') {
+      this.next()
+      declaration = this.parseFnDecl([], true, false)
+    } else {
+      throw this.error('Expected declaration after "export"')
+    }
+
+    if (declaration.kind === 'VarDecl') declaration.export = true
+    const node: ExportDecl = { kind: 'ExportDecl', declaration, loc: this.loc(start) }
+    return node
+  }
+
+  private parseTypeAlias(): TypeAliasDecl {
+    const start = this.expectKeyword('type')
+    const name = this.expect(TokenType.Identifier, undefined, 'Expected type name').value
+    this.expect(TokenType.Operator, '=', 'Expected "=" in type alias')
+    const type = this.parseType()
+    return { kind: 'TypeAliasDecl', name, type, loc: this.loc(start) }
+  }
+
+  /* ---------------------------------------------------------------- */
+  /* Types                                                             */
+  /* ---------------------------------------------------------------- */
+
+  private parseType(): TypeAnn {
+    const start = this.peek()
+    const types = [this.parseTypePostfix()]
+    while (this.matchOperator('|')) types.push(this.parseTypePostfix())
+    if (types.length === 1) return types[0]
+    return { kind: 'union', types, loc: this.loc(start) }
+  }
+
+  private parseTypePostfix(): TypeAnn {
+    let type = this.parseTypePrimary()
+    while (this.matchOperator('?')) {
+      type = { kind: 'optional', type, inner: type, loc: type.loc }
+    }
+    return type
+  }
+
+  private parseTypePrimary(): TypeAnn {
+    const token = this.peek()
+
+    if (this.matchOperator('(')) {
+      const params: TypeAnn[] = []
+      this.skipNewlines()
+      while (!this.atOperator(')')) {
+        params.push(this.parseType())
+        this.skipNewlines()
+        if (!this.matchOperator(',')) break
+        this.skipNewlines()
+      }
+      this.expect(TokenType.Operator, ')', 'Expected ")"')
+      this.expect(TokenType.Operator, '->', 'Expected "->" in function type')
+      const returns = this.parseType()
+      return { kind: 'fn', params, returns, loc: this.loc(token) }
+    }
+
+    if (this.matchOperator('[')) {
+      const element = this.parseType()
+      this.expect(TokenType.Operator, ']', 'Expected "]"')
+      return { kind: 'array', element, loc: this.loc(token) }
+    }
+
+    if (this.matchOperator('{')) {
+      this.skipNewlines()
+      const entries: Array<{ name: string; type: TypeAnn }> = []
+      while (!this.atOperator('}')) {
+        const member = this.expect(TokenType.Identifier, undefined, 'Expected type member name')
+        this.expect(TokenType.Operator, ':', 'Expected ":" in type')
+        const type = this.parseType()
+        entries.push({ name: member.value, type })
+        this.skipNewlines()
+        if (!this.matchOperator(',')) break
+        this.skipNewlines()
+      }
+      this.expect(TokenType.Operator, '}', 'Expected "}"')
+
+      if (entries.length === 1 && PRIMITIVE_TYPE_NAMES.has(entries[0].name)) {
+        return {
+          kind: 'dict',
+          key: { kind: 'named', name: entries[0].name, loc: this.loc(token) },
+          value: entries[0].type,
+          loc: this.loc(token),
+        }
+      }
+      return { kind: 'record', fields: entries, loc: this.loc(token) }
+    }
+
+    if (token.type === TokenType.Identifier || this.atKeyword('nil')) {
+      this.next()
+      return { kind: 'named', name: token.value, loc: this.loc(token) }
+    }
+
+    throw this.error('Expected type annotation')
+  }
+
+  /* ---------------------------------------------------------------- */
+  /* Expressions                                                       */
+  /* ---------------------------------------------------------------- */
+
+  private parseExprList(): Expr[] {
+    const list = [this.parseExpression()]
+    while (this.matchOperator(',')) list.push(this.parseExpression())
+    return list
+  }
+
+  private parseExpression(minPrecedence = 1): Expr {
+    let left = this.parseUnary()
+
+    while (true) {
+      const token = this.peek()
+      const op = token.value
+      const precedence = BINARY_PRECEDENCE[op]
+      if (precedence === undefined || precedence < minPrecedence) break
+
+      const isOperator = token.type === TokenType.Operator
+        || (token.type === TokenType.Keyword && (op === 'and' || op === 'or'))
+      if (!isOperator) break
+
+      this.next()
+      const right = this.parseExpression(op === '^' ? precedence : precedence + 1)
+      const binary: Binary = { kind: 'Binary', op, left, right, loc: left.loc }
+      left = binary
+    }
+
+    return left
+  }
+
+  private parseUnary(): Expr {
+    const token = this.peek()
+    if (token.type === TokenType.Keyword && token.value === 'not') {
+      this.next()
+      return {
+        kind: 'Unary',
+        op: 'not',
+        argument: this.parseExpression(UNARY_PRECEDENCE),
+        loc: this.loc(token),
+      }
+    }
+    if (token.type === TokenType.Keyword && token.value === 'await') {
+      this.next()
+      const node: AwaitExpr = {
+        kind: 'AwaitExpr',
+        argument: this.parseExpression(UNARY_PRECEDENCE),
+        loc: this.loc(token),
+      }
+      return node
+    }
+    if (token.type === TokenType.Operator && (token.value === '-' || token.value === '#')) {
+      this.next()
+      return {
+        kind: 'Unary',
+        op: token.value,
+        argument: this.parseExpression(UNARY_PRECEDENCE),
+        loc: this.loc(token),
+      }
+    }
+    return this.parsePostfix()
+  }
+
+  private parsePostfix(): Expr {
+    let expr = this.parsePrimary()
+
+    while (true) {
+      const token = this.peek()
+
+      if (token.type === TokenType.Operator && token.value === '(') {
+        const args = this.parseArguments()
+        const call: Call = { kind: 'Call', callee: expr, args, loc: expr.loc }
+        expr = call
+        continue
+      }
+
+      if (token.type === TokenType.Operator && (token.value === '.' || token.value === '?.')) {
+        this.next()
+        const property = this.expectName('Expected property name')
+        const member: Member = {
+          kind: 'Member',
+          object: expr,
+          property: property.value,
+          loc: expr.loc,
+        }
+        if (token.value === '?.') member.optional = true
+        expr = member
+        continue
+      }
+
+      if (token.type === TokenType.Operator && token.value === '[') {
+        this.next()
+        this.skipNewlines()
+        const index = this.parseRangeExpr()
+        this.skipNewlines()
+        this.expect(TokenType.Operator, ']', 'Expected "]"')
+        const node: Index = { kind: 'Index', object: expr, index, loc: expr.loc }
+        if (index.kind === 'Range') node.isRange = true
+        expr = node
+        continue
+      }
+
+      // Method call: a:b(args). A bare `:` is a type annotation instead.
+      if (
+        token.type === TokenType.Operator && token.value === ':'
+        && isNameToken(this.peek(1))
+        && this.peek(2).type === TokenType.Operator && this.peek(2).value === '('
+      ) {
+        this.next()
+        const property = this.next()
+        const member: Member = {
+          kind: 'Member',
+          object: expr,
+          property: property.value,
+          loc: expr.loc,
+        }
+        const args = this.parseArguments()
+        const call: Call = { kind: 'Call', callee: member, args, isMethod: true, loc: expr.loc }
+        expr = call
+        continue
+      }
+
+      break
+    }
+
+    return expr
+  }
+
+  private parseArguments(): Expr[] {
+    this.expect(TokenType.Operator, '(', 'Expected "("')
+    const args: Expr[] = []
+    this.skipNewlines()
+    while (!this.atOperator(')')) {
+      if (this.atOperator('...')) {
+        const spreadToken = this.next()
+        const spread: Spread = { kind: 'Spread', loc: this.loc(spreadToken) }
+        if (!this.atOperator(')') && !this.atOperator(',')) spread.argument = this.parseExpression()
+        args.push(spread)
+      } else {
+        args.push(this.parseExpression())
+      }
+      this.skipNewlines()
+      if (!this.matchOperator(',')) break
+      this.skipNewlines()
+    }
+    this.expect(TokenType.Operator, ')', 'Expected ")"')
+    return args
+  }
+
+  private parsePrimary(): Expr {
+    const token = this.peek()
+
+    switch (token.type) {
+      case TokenType.Number: {
+        this.next()
+        return {
+          kind: 'NumberLit',
+          value: Number(token.value.replace(/_/g, '')),
+          loc: this.loc(token),
+        }
+      }
+      case TokenType.String: {
+        this.next()
+        const literal: StringLit = { kind: 'StringLit', value: token.value, loc: this.loc(token) }
+        if (token.value.includes('\n')) literal.multiline = true
+        return literal
+      }
+      case TokenType.FString: {
+        this.next()
+        const literal: StringLit = {
+          kind: 'StringLit',
+          value: token.value,
+          fstring: true,
+          parts: parseFStringParts(token),
+          loc: this.loc(token),
+        }
+        if (token.value.includes('\n')) literal.multiline = true
+        return literal
+      }
+      case TokenType.Identifier: {
+        this.next()
+        const ident: Ident = { kind: 'Ident', name: token.value, loc: this.loc(token) }
+        return ident
+      }
+      case TokenType.Keyword:
+        return this.parseKeywordPrimary(token)
+      case TokenType.Operator:
+        if (token.value === '{') return this.parseTable()
+        if (token.value === '(') {
+          this.next()
+          const expr = this.parseExpression()
+          this.expect(TokenType.Operator, ')', 'Expected ")"')
+          return expr
+        }
+        break
+    }
+
+    throw this.error(`Unexpected token "${token.value}"`)
+  }
+
+  private parseKeywordPrimary(token: Token): Expr {
+    switch (token.value) {
+      case 'true':
+      case 'false':
+        this.next()
+        return { kind: 'BoolLit', value: token.value === 'true', loc: this.loc(token) }
+      case 'nil':
+        this.next()
+        return { kind: 'NilLit', loc: this.loc(token) }
+      case 'self':
+        this.next()
+        return { kind: 'SelfExpr', loc: this.loc(token) }
+      case 'fn':
+        return this.parseFunctionExpr(false)
+      case 'async':
+        if (this.peek(1).type === TokenType.Keyword && this.peek(1).value === 'fn') {
+          this.next()
+          return this.parseFunctionExpr(true)
+        }
+        break
+    }
+    throw this.error(`Unexpected keyword "${token.value}"`)
+  }
+
+  private parseFunctionExpr(isAsync: boolean): FunctionExpr {
+    const start = this.expectKeyword('fn')
+    const params = this.parseParams()
+    const returnType = this.matchOperator(':') ? this.parseType() : undefined
+
+    let body: Block | undefined
+    let exprBody: Expr | undefined
+    if (this.matchOperator('->')) {
+      exprBody = this.parseExpression()
+    } else {
+      body = this.parseBlock(['end'])
+      this.expectKeyword('end')
+    }
+
+    const node: FunctionExpr = {
+      kind: 'FunctionExpr',
+      params,
+      returnType,
+      body,
+      exprBody,
+      loc: this.loc(start),
+    }
+    if (isAsync) node.async = true
+    return node
+  }
+
+  private parseTable(): Table {
+    const start = this.expect(TokenType.Operator, '{')
+    const fields: TableField[] = []
+
+    while (true) {
+      this.skipNewlines()
+      if (this.atOperator('}')) break
+
+      if (this.matchOperator('[')) {
+        const key = this.parseExpression()
+        this.expect(TokenType.Operator, ']', 'Expected "]"')
+        this.expect(TokenType.Operator, '=', 'Expected "="')
+        const value = this.parseExpression()
+        fields.push({ key, value })
+      } else if (
+        isNameToken(this.peek())
+        && this.peek(1).type === TokenType.Operator
+        && this.peek(1).value === '='
+      ) {
+        const key = this.next()
+        this.next()
+        const value = this.parseExpression()
+        const keyNode: Ident = { kind: 'Ident', name: key.value, loc: this.loc(key) }
+        fields.push({ key: keyNode, value })
+      } else if (this.peek().type === TokenType.Identifier && this.isTableFieldEnd(this.peek(1))) {
+        const shorthand = this.next()
+        const ident: Ident = { kind: 'Ident', name: shorthand.value, loc: this.loc(shorthand) }
+        fields.push({ key: ident, value: ident })
+      } else {
+        fields.push({ value: this.parseExpression() })
+      }
+
+      this.skipNewlines()
+      if (this.matchOperator(',') || this.match(TokenType.Semicolon)) continue
+      if (this.atOperator('}')) break
+    }
+
+    this.expect(TokenType.Operator, '}', 'Expected "}"')
+    return { kind: 'Table', fields, loc: this.loc(start) }
+  }
+
+  private isTableFieldEnd(token: Token): boolean {
+    return token.type === TokenType.Newline
+      || token.type === TokenType.Semicolon
+      || token.type === TokenType.EOF
+      || (token.type === TokenType.Operator && (token.value === ',' || token.value === '}'))
+  }
+
+  /**
+   * Range is only meaningful in `for ... in` heads and slices, where `..`
+   * must not be treated as string concatenation.
+   */
+  private parseRangeExpr(): Expr {
+    const start = this.peek()
+    const expr = this.parseExpression()
+
+    if (expr.kind === 'Binary' && expr.op === '..') {
+      const range: Range = {
+        kind: 'Range',
+        from: expr.left,
+        to: expr.right,
+        inclusive: true,
+        loc: expr.loc,
+      }
+      return range
+    }
+
+    if (this.atOperator('..') || this.atOperator('..<')) {
+      const inclusive = this.next().value === '..'
+      const to = this.parseExpression()
+      const range: Range = { kind: 'Range', from: expr, to, inclusive, loc: this.loc(start) }
+      return range
+    }
+
+    return expr
+  }
+
+  /** Parses a complete standalone expression (used by f-string interpolation). */
+  parseExpressionOnly(): Expr {
+    const expr = this.parseExpression()
+    if (!this.at(TokenType.EOF)) throw this.error('Unexpected token in expression')
+    return expr
+  }
+}
+
+/** Splits an f-string body into literal text and parsed interpolation expressions. */
+function parseFStringParts(token: Token): Array<string | Expr> {
+  const raw = token.value
+  const parts: Array<string | Expr> = []
+  let text = ''
+  let index = 0
+
+  while (index < raw.length) {
+    const ch = raw[index]
+    if (ch === '{' && raw[index + 1] === '{') {
+      text += '{'
+      index += 2
+      continue
+    }
+    if (ch === '}' && raw[index + 1] === '}') {
+      text += '}'
+      index += 2
+      continue
+    }
+    if (ch === '{') {
+      const close = findInterpolationEnd(raw, index + 1)
+      if (close < 0) {
+        throw new SyntaxError(
+          `Unterminated f-string interpolation (line ${token.line}, column ${token.column})`,
+        )
+      }
+      if (text) {
+        parts.push(text)
+        text = ''
+      }
+      parts.push(new Parser(raw.slice(index + 1, close)).parseExpressionOnly())
+      index = close + 1
+      continue
+    }
+    text += ch
+    index++
+  }
+
+  if (text) parts.push(text)
+  return parts
+}
+
+/** Finds the `}` closing an interpolation, skipping nested braces and strings. */
+function findInterpolationEnd(raw: string, from: number): number {
+  let depth = 1
+  let quote = ''
+
+  for (let i = from; i < raw.length; i++) {
+    const ch = raw[i]
+    if (quote) {
+      if (ch === '\\') i++
+      else if (ch === quote) quote = ''
+      continue
+    }
+    if (ch === '"' || ch === "'") {
+      quote = ch
+      continue
+    }
+    if (ch === '{') depth++
+    else if (ch === '}') {
+      depth--
+      if (depth === 0) return i
+    }
+  }
+
+  return -1
+}
+
+export function parse(source: string): Program {
+  return new Parser(source).parseProgram()
+}
+
+/** Parses a single expression; mainly useful for tooling and f-string chunks. */
+export function parseExpression(source: string): Expr {
+  return new Parser(source).parseExpressionOnly()
+}