@ascent-lang/dev 0.1.0

package/src/lexer/index.ts

@@ -0,0 +1,174 @@
+import type { Position, Span, Marker } from './token.js';
+import type { Token, TokenKind } from './token.js';
+import { isDigit, isAlpha, isAlphaNum, isWhitespace } from './chars.js';
+import { Cursor } from './cursor.js';
+import { resolveWord } from './keywords.js';
+
+export interface LexResult {
+  tokens: Token[];
+  errorMarkers: Marker[];
+}
+
+export class Lexer {
+  private c: Cursor;
+  private errorMarkers: Marker[] = [];
+
+  public constructor(src: string) {
+    this.c = new Cursor(src);
+  }
+
+  private token(kind: TokenKind, start: Position): Token {
+    return { kind, value: this.c.slice(start), span: this.c.spanFrom(start) };
+  }
+
+  private error(code: string, span: Span): Token {
+    this.errorMarkers.push({ code, span });
+    return { kind: 'ERROR', value: '', span };
+  }
+
+  private consumeWhile(pred: (ch: string) => boolean): void {
+    while (pred(this.c.peek())) {
+      this.c.advance();
+    }
+  }
+
+  private skipWhitespace(): void {
+    this.consumeWhile(isWhitespace);
+  }
+
+  private readWord(): Token {
+    const start = this.c.mark();
+    const firstCh = this.c.peek();
+    this.consumeWhile(isAlphaNum);
+    const kind = resolveWord(this.c.slice(start), firstCh);
+    return kind !== null ? this.token(kind, start) : this.error('L0001', this.c.spanFrom(start));
+  }
+
+  private readString(start: Position): Token {
+    let value = '';
+    while (true) {
+      const ch = this.c.peek();
+      if (ch === '\0' || ch === '\n') {
+        return this.error('L0003', this.c.spanFrom(start));
+      }
+      if (ch === '"') {
+        this.c.advance(); // consume closing '"'
+        return { kind: 'STR_LIT', value, span: this.c.spanFrom(start) };
+      }
+      if (ch === '\\') {
+        this.c.advance(); // consume '\'
+        const esc = this.c.peek();
+        this.c.advance(); // consume escape char
+        switch (esc) {
+          case 'n': value += '\n'; break;
+          case 't': value += '\t'; break;
+          case 'r': value += '\r'; break;
+          case '"': value += '"'; break;
+          case '\\': value += '\\'; break;
+          default: return this.error('L0001', this.c.spanFrom(start));
+        }
+      } else {
+        value += ch;
+        this.c.advance();
+      }
+    }
+  }
+
+  private readNumber(): Token {
+    const start = this.c.mark();
+    this.consumeWhile(isDigit);
+
+    // Float: only consume the dot when a digit follows — this keeps '3.method()'
+    // valid in later sections where '.' is the member-access operator.
+    let kind: TokenKind = 'INT_LIT';
+    if (this.c.peek() === '.' && isDigit(this.c.peek(1))) {
+      this.c.advance(); // '.'
+      this.consumeWhile(isDigit);
+      kind = 'FLOAT_LIT';
+    }
+
+    // A number may not be glued to a letter: 123abc / 1.5x are one malformed
+    // token, not a number followed by a name.
+    if (isAlpha(this.c.peek())) {
+      this.consumeWhile(isAlphaNum);
+      return this.error('L0002', this.c.spanFrom(start));
+    }
+
+    return this.token(kind, start);
+  }
+
+  private nextToken(): Token {
+    this.skipWhitespace();
+
+    if (this.c.atEnd()) {
+      const start = this.c.mark();
+      return this.token('EOF', start);
+    }
+
+    const ch = this.c.peek();
+
+    if (isDigit(ch)) {
+      return this.readNumber();
+    }
+    if (isAlpha(ch)) {
+      return this.readWord();
+    }
+
+    // A leading-dot float like .5 looks like a number attempt, so L0002 is
+    // more helpful than L0001 ("unexpected character").
+    if (ch === '.' && isDigit(this.c.peek(1))) {
+      const start = this.c.mark();
+      this.c.advance(); // '.'
+      this.consumeWhile(isDigit);
+      return this.error('L0002', this.c.spanFrom(start));
+    }
+
+    const start = this.c.mark();
+    this.c.advance();
+
+    switch (ch) {
+      case '+': return this.token('PLUS', start);
+      case '-': return this.token('MINUS', start);
+      case '*': return this.token('STAR', start);
+      case '/': return this.token('SLASH', start);
+      case '=':
+        if (this.c.match('=')) return this.token('EQ_EQ', start);
+        return this.token('EQUALS', start);
+      case '!':
+        // Bare '!' has no meaning — negation is the word 'not' (§5), so
+        // only '!=' is a valid token starting with '!'.
+        if (this.c.match('=')) return this.token('BANG_EQ', start);
+        return this.error('L0001', this.c.spanFrom(start));
+      case '<':
+        if (this.c.match('=')) return this.token('LT_EQ', start);
+        return this.token('LT', start);
+      case '>':
+        if (this.c.match('=')) return this.token('GT_EQ', start);
+        return this.token('GT', start);
+      case '"': return this.readString(start);
+      case '.': return this.token('DOT', start);
+      case ':': return this.token('COLON', start);
+      case ',': return this.token('COMMA', start);
+      case ';': return this.token('SEMICOLON', start);
+      case '(': return this.token('LPAREN', start);
+      case ')': return this.token('RPAREN', start);
+      case '{': return this.token('LBRACE', start);
+      case '}': return this.token('RBRACE', start);
+      case '[': return this.token('LBRACKET', start);
+      case ']': return this.token('RBRACKET', start);
+      default: return this.error('L0001', this.c.spanFrom(start));
+    }
+  }
+
+  public tokenize(): LexResult {
+    const tokens: Token[] = [];
+    while (true) {
+      const tok = this.nextToken();
+      tokens.push(tok);
+      if (tok.kind === 'EOF') {
+        break;
+      }
+    }
+    return { tokens, errorMarkers: this.errorMarkers };
+  }
+}

package/src/lexer/keywords.ts

@@ -0,0 +1,43 @@
+import type { TokenKind } from './token.js';
+
+export const KEYWORDS: Record<string, TokenKind> = {
+  div: 'KW_DIV',
+  mod: 'KW_MOD',
+  fix: 'KW_FIX',
+  mut: 'KW_MUT',
+  if: 'KW_IF',
+  else: 'KW_ELSE',
+  while: 'KW_WHILE',
+  args: 'KW_ARGS',
+};
+
+// Built-in constructors: uppercase names that are part of the language
+// core but are not keywords — they are non-shadowable constructor names
+// (True, False, None) that happen to be built in rather than user-defined.
+export const CONSTRUCTORS: Record<string, TokenKind> = {
+  True: 'BOOL_LIT',
+  False: 'BOOL_LIT',
+  None: 'NONE_LIT',
+  Done: 'DONE_LIT',
+};
+
+// Built-in type names: recognised as TYPE_NAME tokens so the parser can
+// use them in type annotations (e.g. args declarations). Other uppercase
+// names that are neither constructors nor type names are still L0001.
+const BUILTIN_TYPES: Record<string, TokenKind> = {
+  Int: 'TYPE_NAME',
+  Float: 'TYPE_NAME',
+  Bool: 'TYPE_NAME',
+  String: 'TYPE_NAME',
+  List: 'TYPE_NAME',
+};
+
+// Returns the token kind for a scanned word, or null for an unrecognised
+// uppercase name (the caller must emit L0001). Lowercase words that are not
+// keywords resolve to SLOT rather than null.
+export function resolveWord(value: string, firstCh: string): TokenKind | null {
+  if (firstCh >= 'A' && firstCh <= 'Z') {
+    return CONSTRUCTORS[value] ?? BUILTIN_TYPES[value] ?? null;
+  }
+  return KEYWORDS[value] ?? 'SLOT';
+}

package/src/lexer/token.ts

@@ -0,0 +1,62 @@
+export type TokenKind =
+  | 'INT_LIT'    // a sequence of decimal digits: 0, 42, 1000
+  | 'FLOAT_LIT'  // a decimal number with a dot: 0.5, 3.14, 1.0
+  | 'STR_LIT'    // a double-quoted string: "hello"
+  | 'BOOL_LIT'   // True or False
+  | 'NONE_LIT'   // None
+  | 'DONE_LIT'   // Done — the unit constructor
+  | 'SLOT'       // a lowercase-starting identifier — a binding name
+  | 'PLUS'       // '+'
+  | 'MINUS'      // '-'
+  | 'STAR'       // '*'
+  | 'SLASH'      // '/', always real division — yields a Float
+  | 'KW_DIV'     // the keyword div — Int-only floor division
+  | 'KW_MOD'     // the keyword mod — Int-only floored modulo
+  | 'KW_FIX'     // the keyword fix — declares a fixed slot
+  | 'KW_MUT'     // the keyword mut — declares a mutable slot
+  | 'KW_IF'      // the keyword if — starts a conditional expression
+  | 'KW_ELSE'    // the keyword else — the alternative branch of an if
+  | 'KW_WHILE'   // the keyword while — starts a condition loop
+  | 'KW_ARGS'    // the keyword args — declares the program's typed inputs
+  | 'TYPE_NAME'  // a built-in type name: Int, Float, Bool, String
+  | 'COLON'      // ':' — separates a name from its type annotation
+  | 'EQUALS'     // '=' — used in slot declarations and updates
+  | 'EQ_EQ'      // '==' — structural equality
+  | 'BANG_EQ'    // '!=' — structural inequality
+  | 'LT'         // '<'
+  | 'LT_EQ'      // '<='
+  | 'GT'         // '>'
+  | 'GT_EQ'      // '>='
+  | 'DOT'        // '.' — method call operator
+  | 'COMMA'      // ','
+  | 'SEMICOLON'  // ';' — statement terminator
+  | 'LPAREN'     // '('
+  | 'RPAREN'     // ')'
+  | 'LBRACE'     // '{'
+  | 'RBRACE'     // '}'
+  | 'LBRACKET'   // '[' — list literal open / index open
+  | 'RBRACKET'   // ']' — list literal close / index close
+  | 'ERROR'      // a character or run the lexer couldn't recognise
+  | 'EOF';       // the sentinel that marks the end of source
+
+export interface Position {
+  offset: number;  // 0-based index into the source string
+  line: number;    // 1-based
+  column: number;  // 1-based
+}
+
+export interface Span {
+  start: Position;
+  end: Position;   // exclusive — points one past the last character
+}
+
+export interface Marker {
+  code: string;
+  span: Span;
+}
+
+export interface Token {
+  kind: TokenKind;
+  value: string;
+  span: Span;
+}

package/src/lib.ts

@@ -0,0 +1,33 @@
+// Public programmatic API for the Ascent language toolchain.
+// The `ascent` CLI (see index.ts) is the primary entry point, but the
+// individual stages are re-exported here so tools can embed the pipeline:
+//
+//   const { tokens, errorMarkers } = new Lexer(src).tokenize();
+//   const { program } = new Parser(tokens).parse();
+//   const { typedProgram } = typecheck(program!);
+//   const result = executeProgram(typedProgram!, new Environment());
+
+export { Lexer } from './lexer/index.js';
+export type { LexResult } from './lexer/index.js';
+
+export { Parser } from './parser/index.js';
+export type { ParseResult } from './parser/index.js';
+
+export { typecheck } from './parser/typechecker.js';
+export type { TypeCheckResult } from './parser/typechecker.js';
+
+export {
+  Environment,
+  evaluateExpr,
+  executeStmt,
+  executeProgram,
+} from './interpreter.js';
+export type { RuntimeValue, AssignResult } from './interpreter.js';
+
+export { formatExpr, formatStmt, formatValue } from './parser/printer.js';
+export { formatTypedStmt } from './parser/typed-printer.js';
+
+export * from './types/types.js';
+
+export { ERRORS, byCode } from './errors/index.js';
+export type { ErrorEntry, Category } from './errors/types.js';

package/src/parser/ast.ts

@@ -0,0 +1,64 @@
+import type { Span } from '../lexer/token.js';
+
+// TypeExpr is the AST node for a type written in source code.
+// It carries span information so the type checker can point at it in errors.
+export type TypeExpr =
+  | { kind: 'TypeName'; name: 'Int' | 'Float' | 'Bool' | 'String'; span: Span }
+  | { kind: 'ListType'; elem: TypeExpr; span: Span };
+
+export type Literal = (
+  | { kind: 'literal'; valueType: 'Int'; value: bigint; span: Span }
+  | { kind: 'literal'; valueType: 'Float'; value: number; span: Span }
+  | { kind: 'literal'; valueType: 'Bool'; value: boolean; span: Span }
+  | { kind: 'literal'; valueType: 'String'; value: string; span: Span }
+  | { kind: 'literal'; valueType: 'None'; span: Span }
+  | { kind: 'literal'; valueType: 'Done'; span: Span }
+);
+
+export type UnaryOp = '-';
+export type ArithmeticOp = '+' | '-' | '*' | '/' | 'div' | 'mod';
+export type ComparisonOp = '==' | '!=' | '<' | '<=' | '>' | '>=';
+export type BinaryOp = ArithmeticOp | ComparisonOp;
+
+// A block is itself an expression — it yields the value of its last
+// statement, or Done when empty (the '{}' unit value).
+export type Block = { kind: 'block'; stmts: Statement[]; span: Span };
+
+// 'else if' is sugar: the else branch is either a block or another
+// If, never a separate grammar rule.
+export type If = {
+  kind: 'if';
+  cond: Expr;
+  then: Block;
+  else: Block | If | null;
+  span: Span;
+};
+
+export type Expr = (
+  | Literal
+  | { kind: 'slot'; name: string; span: Span }
+  | { kind: 'call'; callee: string; args: Expr[]; span: Span }
+  | { kind: 'methodCall'; receiver: Expr; method: string; args: Expr[]; span: Span }
+  | { kind: 'list'; elements: Expr[]; span: Span }
+  | { kind: 'index'; list: Expr; index: Expr; span: Span }
+  | { kind: 'unary'; op: UnaryOp; operand: Expr; span: Span }
+  | { kind: 'binary'; op: BinaryOp; left: Expr; right: Expr; span: Span }
+  | Block
+  | If
+);
+
+// Unlike 'if', 'while' is a statement, not an expression — a loop has
+// no single meaningful result (zero iterations has no last value to
+// give), so it always yields Done rather than forcing a fake one.
+export type Statement = (
+  | { kind: 'fix'; name: string; typeAnnotation: TypeExpr | null; init: Expr; span: Span }
+  | { kind: 'mut'; name: string; typeAnnotation: TypeExpr | null; init: Expr; span: Span }
+  | { kind: 'assign'; name: string; value: Expr; span: Span }
+  | { kind: 'expr'; expr: Expr; span: Span }
+  | { kind: 'while'; cond: Expr; body: Block; span: Span }
+);
+
+export type ArgType = 'Int' | 'Float' | 'Bool' | 'String';
+export type ArgDef = { name: string; type: ArgType };
+
+export type Program = { args: ArgDef[]; stmts: Statement[] };

package/src/parser/expr.ts

@@ -0,0 +1,313 @@
+import type { Token, TokenKind } from '../lexer/token.js';
+import type { Expr, BinaryOp, UnaryOp } from './ast.js';
+import type { TokenStream } from './token-stream.js';
+import { parseBlock, parseIf } from './stmt.js';
+
+// ---- Pratt parsing ----------------------------------------------------
+//
+// A Pratt parser recognises an expression as an atom (a "nud" — null
+// denotation, a value that doesn't look left at anything) optionally
+// followed by a chain of infix or postfix operators (each a "led" —
+// left denotation, because it combines the value already parsed with
+// whatever comes after it).
+//
+// Every operator — prefix, infix, or postfix — has a binding power: a
+// number saying how tightly it grabs its operands. Higher binds
+// tighter — that's what encodes precedence: '*' outbinds '+', so
+// `1 + 2 * 3` parses as `1 + (2 * 3)`, not `(1 + 2) * 3`. The parsing
+// loop only accepts an operator when its binding power is at least
+// `minBp` — the "how tight does the *caller* need things bound"
+// threshold passed down on each recursive call.
+//
+// This ladder is the single source of truth for what binds tighter
+// than what: postfix (`.method()`, `[index]`) binds tightest, then
+// unary '-', then '*'/'/'/'div'/'mod', then '+'/'-', then the
+// comparisons, loosest. Every table below is keyed off these numbers
+// instead of inlining its own.
+const BP = {
+  COMPARISON: 1,
+  ADDITIVE: 2,
+  MULTIPLICATIVE: 3,
+  UNARY: 4,
+  POSTFIX: 4,
+} as const;
+
+// Every binary operator this parser knows about has one row in this
+// table. Adding the next one means adding a row, never touching the
+// loop below. '*', '/', 'div' and 'mod' all share a binding power —
+// they're the same precedence tier — so all four outbind '+', which
+// in turn outbinds the comparisons — `1 + 2 < 3 * 4` groups as
+// `(1 + 2) < (3 * 4)`. Comparisons are also marked `assoc: 'none'`:
+// unlike '+' or '*', two of them can never sit side by side
+// (`a < b < c` is rejected, not silently grouped one way or the other).
+const INFIX_OPS: Partial<Record<TokenKind, { op: BinaryOp; bp: number; assoc: 'left' | 'none' }>> = {
+  EQ_EQ: { op: '==', bp: BP.COMPARISON, assoc: 'none' },
+  BANG_EQ: { op: '!=', bp: BP.COMPARISON, assoc: 'none' },
+  LT: { op: '<', bp: BP.COMPARISON, assoc: 'none' },
+  LT_EQ: { op: '<=', bp: BP.COMPARISON, assoc: 'none' },
+  GT: { op: '>', bp: BP.COMPARISON, assoc: 'none' },
+  GT_EQ: { op: '>=', bp: BP.COMPARISON, assoc: 'none' },
+  PLUS: { op: '+', bp: BP.ADDITIVE, assoc: 'left' },
+  MINUS: { op: '-', bp: BP.ADDITIVE, assoc: 'left' },
+  STAR: { op: '*', bp: BP.MULTIPLICATIVE, assoc: 'left' },
+  SLASH: { op: '/', bp: BP.MULTIPLICATIVE, assoc: 'left' },
+  KW_DIV: { op: 'div', bp: BP.MULTIPLICATIVE, assoc: 'left' },
+  KW_MOD: { op: 'mod', bp: BP.MULTIPLICATIVE, assoc: 'left' },
+};
+
+// Postfix table — dot-calls and indexing are "led" operators exactly
+// like the binary ones above (they look left at the value already
+// parsed), so they're declared here and dispatched on in the loop
+// below instead of being special-cased ahead of the INFIX_OPS lookup.
+// Both bind at POSTFIX — tighter than unary or any binary operator —
+// which is why `-a.b()[0]` parses as `-(a.b()[0])`.
+const POSTFIX_OPS: Partial<Record<TokenKind, { bp: number }>> = {
+  DOT: { bp: BP.POSTFIX },
+  LBRACKET: { bp: BP.POSTFIX },
+};
+
+// Prefix table — unary '-' is the Pratt parser's other operator kind
+// (a "nud" that still takes an operand, parsed in parseAtom below).
+// Only one entry today, but its binding power is declared here rather
+// than inlined at the call site.
+const PREFIX_OPS: Partial<Record<TokenKind, { op: UnaryOp; bp: number }>> = {
+  MINUS: { op: '-', bp: BP.UNARY },
+};
+
+export function parseExpr(ts: TokenStream, minBp = 0): Expr | null {
+  let left = parseAtom(ts);
+  if (left === null) {
+    return null;
+  }
+
+  // Tracks whether a non-associative (comparison-tier) operator has
+  // already been consumed at this call's level — a second one directly
+  // beside it (`a < b < c`) is a chain, not a grouping choice, so it's
+  // rejected here rather than silently parsed left- or right-first.
+  let chained = false;
+
+  while (true) {
+    const kind = ts.peek().kind;
+
+    // Postfix: expr.method(args) or expr[index] — dispatched by table
+    // rather than special-cased ahead of the INFIX_OPS lookup below.
+    const postfix = POSTFIX_OPS[kind];
+    if (postfix !== undefined) {
+      if (postfix.bp < minBp) break;
+      left = kind === 'DOT' ? parseMethodCall(ts, left) : parseIndex(ts, left);
+      if (left === null) return null;
+      continue;
+    }
+
+    const infix = INFIX_OPS[kind];
+    if (infix === undefined || infix.bp < minBp) {
+      break;
+    }
+
+    if (infix.assoc === 'none') {
+      if (chained) {
+        ts.report('S0008', ts.peek().span);
+        return null;
+      }
+      chained = true;
+    }
+
+    ts.advance(); // consume the operator
+
+    // Left-associativity — `1 + 2 + 3` must parse as `(1 + 2) + 3`,
+    // not `1 + (2 + 3)`. Parsing the right-hand side with `bp + 1`
+    // (instead of `bp`) is what enforces that: it stops a second '+'
+    // from being absorbed into the *right* operand, forcing it to
+    // instead be picked up by the loop one level up. Non-associative
+    // operators reuse the same `bp + 1` call — it still keeps looser
+    // operators out of the right operand, and the `chained` check
+    // above is what stops them from reappearing at this level.
+    const right = parseExpr(ts, infix.bp + 1);
+    if (right === null) {
+      return null;
+    }
+
+    left = {
+      kind: 'binary',
+      op: infix.op,
+      left,
+      right,
+      span: { start: left.span.start, end: right.span.end }
+    };
+  }
+
+  return left;
+}
+
+// 'receiver.method(args)' — DOT already confirmed on lookahead by the
+// Pratt loop; this consumes it through the closing ')'.
+function parseMethodCall(ts: TokenStream, receiver: Expr): Expr | null {
+  ts.advance(); // consume '.'
+
+  const methodTok = ts.peek();
+  if (methodTok.kind !== 'SLOT') {
+    ts.report('S0012', methodTok.span);
+    return null;
+  }
+  ts.advance(); // consume method name
+
+  if (ts.peek().kind !== 'LPAREN') {
+    ts.report('S0001', ts.peek().span);
+    return null;
+  }
+  ts.advance(); // consume '('
+
+  const parsed = ts.parseSeparated(() => parseExpr(ts), 'COMMA', 'RPAREN', 'S0001');
+  if (parsed === null) return null;
+
+  return {
+    kind: 'methodCall',
+    receiver,
+    method: methodTok.value,
+    args: parsed.items,
+    span: { start: receiver.span.start, end: parsed.close.span.end },
+  };
+}
+
+// 'list[index]' — LBRACKET already confirmed on lookahead by the Pratt loop.
+function parseIndex(ts: TokenStream, list: Expr): Expr | null {
+  ts.advance(); // consume '['
+
+  const index = parseExpr(ts);
+  if (index === null) return null;
+
+  const rbracket = ts.expect('RBRACKET', 'S0013');
+  if (rbracket === null) return null;
+
+  return {
+    kind: 'index',
+    list,
+    index,
+    span: { start: list.span.start, end: rbracket.span.end },
+  };
+}
+
+// parseAtom parses the smallest possible expression: a single literal
+// that doesn't depend on any operator. This is the Pratt parser's nud —
+// every future one (parenthesized groups, unary '-', identifiers) is
+// just another case added here, never a change to the loop above.
+function parseAtom(ts: TokenStream): Expr | null {
+  const tok = ts.peek();
+
+  if (tok.kind === 'INT_LIT') {
+    ts.advance();
+    return {
+      kind: 'literal',
+      valueType: 'Int',
+      value: BigInt(tok.value),
+      span: tok.span
+    };
+  }
+
+  if (tok.kind === 'FLOAT_LIT') {
+    ts.advance();
+    return {
+      kind: 'literal',
+      valueType: 'Float',
+      value: parseFloat(tok.value),
+      span: tok.span
+    };
+  }
+
+  if (tok.kind === 'STR_LIT') {
+    ts.advance();
+    return { kind: 'literal', valueType: 'String', value: tok.value, span: tok.span };
+  }
+
+  if (tok.kind === 'BOOL_LIT') {
+    ts.advance();
+    return {
+      kind: 'literal',
+      valueType: 'Bool',
+      value: tok.value === 'True',
+      span: tok.span
+    };
+  }
+
+  if (tok.kind === 'NONE_LIT') {
+    ts.advance();
+    return { kind: 'literal', valueType: 'None', span: tok.span };
+  }
+
+  if (tok.kind === 'DONE_LIT') {
+    ts.advance();
+    return { kind: 'literal', valueType: 'Done', span: tok.span };
+  }
+
+  if (tok.kind === 'SLOT') {
+    ts.advance();
+    if (ts.peek().kind === 'LPAREN') {
+      return parseCall(ts, tok);
+    }
+    return { kind: 'slot', name: tok.value, span: tok.span };
+  }
+
+  if (tok.kind === 'LPAREN') {
+    ts.advance();
+    const inner = parseExpr(ts);
+    if (inner === null) {
+      return null;
+    }
+    const closing = ts.peek();
+    if (closing.kind !== 'RPAREN') {
+      ts.report('S0001', closing.span);
+      return null;
+    }
+    ts.advance(); // consume ')'
+    return inner;
+  }
+
+  const prefix = PREFIX_OPS[tok.kind];
+  if (prefix !== undefined) {
+    const start = tok.span.start;
+    ts.advance();
+    const operand = parseExpr(ts, prefix.bp);
+    if (operand === null) {
+      return null;
+    }
+    return { kind: 'unary', op: prefix.op, operand, span: { start, end: operand.span.end } };
+  }
+
+  if (tok.kind === 'LBRACKET') {
+    return parseList(ts);
+  }
+
+  if (tok.kind === 'LBRACE') {
+    return parseBlock(ts);
+  }
+
+  if (tok.kind === 'KW_IF') {
+    return parseIf(ts);
+  }
+
+  ts.report('S0002', tok.span);
+  return null;
+}
+
+// 'name(arg, arg, …)' — callee token already consumed by parseAtom.
+function parseCall(ts: TokenStream, callee: Token): Expr | null {
+  ts.advance(); // consume '('
+  const parsed = ts.parseSeparated(() => parseExpr(ts), 'COMMA', 'RPAREN', 'S0001');
+  if (parsed === null) return null;
+
+  return {
+    kind: 'call',
+    callee: callee.value,
+    args: parsed.items,
+    span: { start: callee.span.start, end: parsed.close.span.end },
+  };
+}
+
+// '[' expr, expr, … ']' — list literal. Already peeked '[' in parseAtom.
+function parseList(ts: TokenStream): Expr | null {
+  const openTok = ts.advance(); // consume '['
+  const parsed = ts.parseSeparated(() => parseExpr(ts), 'COMMA', 'RBRACKET', 'S0013');
+  if (parsed === null) return null;
+
+  return { kind: 'list', elements: parsed.items, span: { start: openTok.span.start, end: parsed.close.span.end } };
+}