@ascent-lang/dev 0.1.0

package/src/parser/index.ts

@@ -0,0 +1,50 @@
+import type { Token, Marker } from '../lexer/token.js';
+import type { ArgDef, Program } from './ast.js';
+import { TokenStream } from './token-stream.js';
+import { parseStmt } from './stmt.js';
+import { parseArgs } from './type-expr.js';
+
+export interface ParseResult {
+  program: Program | null;
+  errorMarkers: Marker[];
+}
+
+// The program is an optional 'args (…);' header followed by a
+// semicolon-separated run of statements up to EOF — the same
+// "item (sep item)* close" shape as a block, with EOF standing in for
+// the closing brace. `recover` is on, so a malformed statement is
+// synchronized past rather than aborting the whole parse.
+function parseProgram(ts: TokenStream): Program | null {
+  let args: ArgDef[] = [];
+  if (ts.peek().kind === 'KW_ARGS') {
+    const result = parseArgs(ts);
+    if (result === null) return null;
+    args = result;
+
+    if (ts.expect('SEMICOLON', 'S0011') === null) return null;
+  }
+
+  const parsed = ts.parseSeparated(() => parseStmt(ts), 'SEMICOLON', 'EOF', 'S0011', true);
+  if (parsed === null) return null;
+
+  return { args, stmts: parsed.items };
+}
+
+// The parser's public entry point. Phase 5 moved the grammar into
+// free functions over a TokenStream (token-stream.ts, expr.ts, stmt.ts,
+// type-expr.ts); this class is the thin wiring that owns the stream for
+// one parse and exposes the same `new Parser(tokens).parse()` API the
+// rest of the toolchain calls.
+export class Parser {
+  private readonly tokens: Token[];
+
+  public constructor(tokens: Token[]) {
+    this.tokens = tokens;
+  }
+
+  public parse(): ParseResult {
+    const ts = new TokenStream(this.tokens);
+    const program = parseProgram(ts);
+    return { program, errorMarkers: ts.errors };
+  }
+}

package/src/parser/printer.ts

@@ -0,0 +1,146 @@
+import chalk from 'chalk';
+import type { Expr, Statement, TypeExpr } from './ast.js';
+import type { RuntimeValue } from '../interpreter.js';
+
+const formatTypeExpr = (te: TypeExpr): string => {
+  switch (te.kind) {
+    case 'TypeName': return te.name;
+    case 'ListType': return `List<${formatTypeExpr(te.elem)}>`;
+  }
+};
+
+// Returns the node as a list of lines so callers can prefix them with
+// branch characters (├─, └─) when embedding inside a parent node.
+const exprLines = (expr: Expr): string[] => {
+  switch (expr.kind) {
+    case 'literal':
+      switch (expr.valueType) {
+        case 'Int':
+          return [`${chalk.cyan('Lit')} ${chalk.yellow(String(expr.value))}`];
+        case 'Float':
+          return [`${chalk.cyan('Lit')} ${chalk.yellow(String(expr.value))}`];
+        case 'Bool':
+          return [`${chalk.cyan('Lit')} ${chalk.yellow(expr.value ? 'True' : 'False')}`];
+        case 'String':
+          return [`${chalk.cyan('Lit')} ${chalk.green(JSON.stringify(expr.value))}`];
+        case 'None':
+          return [`${chalk.cyan('Lit')} ${chalk.yellow('None')}`];
+        case 'Done':
+          return [`${chalk.cyan('Lit')} ${chalk.yellow('Done')}`];
+      }
+    case 'slot':
+      return [`${chalk.cyan('Slot')} ${chalk.green(expr.name)}`];
+    case 'call': {
+      const argLines = expr.args.flatMap((arg, i) =>
+        branch(exprLines(arg), i === expr.args.length - 1)
+      );
+      return [`${chalk.cyan('Call')} ${chalk.green(expr.callee)}`, ...argLines];
+    }
+    case 'methodCall': {
+      const children = [expr.receiver, ...expr.args];
+      const childLines = children.flatMap((child, i) =>
+        branch(exprLines(child), i === children.length - 1)
+      );
+      return [`${chalk.cyan('MethodCall')} ${chalk.green('.' + expr.method)}`, ...childLines];
+    }
+    case 'list': {
+      if (expr.elements.length === 0) {
+        return [`${chalk.cyan('List')} ${chalk.dim('[]')}`];
+      }
+      const elementLines = expr.elements.flatMap((el, i) =>
+        branch(exprLines(el), i === expr.elements.length - 1)
+      );
+      return [`${chalk.cyan('List')}`, ...elementLines];
+    }
+    case 'index': {
+      const listLines = branch(exprLines(expr.list), false);
+      const indexLines = branch(exprLines(expr.index), true);
+      return [`${chalk.cyan('Index')}`, ...listLines, ...indexLines];
+    }
+    case 'unary': {
+      const operand = branch(exprLines(expr.operand), true);
+      return [`${chalk.cyan('Unary')} ${chalk.magenta(expr.op)}`, ...operand];
+    }
+    case 'binary': {
+      const left = branch(exprLines(expr.left), false);
+      const right = branch(exprLines(expr.right), true);
+      return [`${chalk.cyan('Binary')} ${chalk.magenta(expr.op)}`, ...left, ...right];
+    }
+    case 'block': {
+      if (expr.stmts.length === 0) {
+        return [`${chalk.cyan('Block')} ${chalk.dim('(empty)')}`];
+      }
+      const lines = expr.stmts.flatMap((stmt, i) =>
+        branch(stmtLines(stmt), i === expr.stmts.length - 1)
+      );
+      return [`${chalk.cyan('Block')}`, ...lines];
+    }
+    case 'if': {
+      const condLines = branch(exprLines(expr.cond), false);
+      const thenLines = branch(exprLines(expr.then), expr.else === null);
+      const elseLines = expr.else !== null ? branch(exprLines(expr.else), true) : [];
+      return [`${chalk.cyan('If')}`, ...condLines, ...thenLines, ...elseLines];
+    }
+  }
+};
+
+// Prefixes a child's lines with tree-drawing characters.
+// Used by parent nodes (Binary, Unary, …) when they are added.
+export const branch = (lines: string[], isLast: boolean): string[] => {
+  const head = chalk.dim(isLast ? '└─ ' : '├─ ');
+  const body = chalk.dim(isLast ? '   ' : '│  ');
+  return lines.map((line, i) => (i === 0 ? head : body) + line);
+};
+
+export const formatExpr = (expr: Expr): string => {
+  return exprLines(expr).join('\n');
+};
+
+// Same line-list shape as exprLines, for the same reason: a block needs
+// to embed a statement's lines and prefix them with tree-drawing chars.
+const stmtLines = (stmt: Statement): string[] => {
+  switch (stmt.kind) {
+    case 'fix':
+    case 'mut': {
+      const init = branch(exprLines(stmt.init), true);
+      const label = stmt.kind === 'fix' ? 'Fix' : 'Mut';
+      const ann = stmt.typeAnnotation !== null ? chalk.dim(`: ${formatTypeExpr(stmt.typeAnnotation)}`) : '';
+      return [`${chalk.cyan(label)} ${chalk.green(stmt.name)}${ann}`, ...init];
+    }
+    case 'assign': {
+      const value = branch(exprLines(stmt.value), true);
+      return [`${chalk.cyan('Assign')} ${chalk.green(stmt.name)}`, ...value];
+    }
+    case 'expr':
+      return exprLines(stmt.expr);
+    case 'while': {
+      const cond = branch(exprLines(stmt.cond), false);
+      const body = branch(exprLines(stmt.body), true);
+      return [`${chalk.cyan('While')}`, ...cond, ...body];
+    }
+  }
+};
+
+export const formatStmt = (stmt: Statement): string => stmtLines(stmt).join('\n');
+
+export const formatValue = (value: RuntimeValue): string => {
+  switch (value.type) {
+    case 'Int':
+      return chalk.yellow(String(value.value));
+    case 'Float':
+      const floatStr = String(value.value);
+      return floatStr.includes('.') ? chalk.yellow(floatStr) : chalk.yellow(floatStr + '.0');
+    case 'Bool':
+      return chalk.yellow(value.value ? 'True' : 'False');
+    case 'String':
+      return chalk.green(JSON.stringify(value.value));
+    case 'List': {
+      const items = value.elements.map(formatValue).join(', ');
+      return chalk.yellow(`[${items}]`);
+    }
+    case 'None':
+      return chalk.yellow('None');
+    case 'Done':
+      return chalk.yellow('Done');
+  }
+};

package/src/parser/stmt.ts

@@ -0,0 +1,176 @@
+import type { Token } from '../lexer/token.js';
+import type { Expr, Statement, Block, If, TypeExpr } from './ast.js';
+import type { TokenStream } from './token-stream.js';
+import { parseExpr } from './expr.js';
+import { parseTypeExpr } from './type-expr.js';
+
+// A block is '{' stmt* '}', each statement separated by ';' — the
+// same "item (sep item)* close" shape as a call's args or a list
+// literal, just with SEMICOLON as the separator and RBRACE as the
+// close (§ design.md: "semicolons terminate every statement"; the
+// trailing one is optional exactly like a list's trailing comma).
+// `openTok` lets parseRequiredBlock pass in a '{' it already consumed
+// via `expect`; parseAtom, which hasn't consumed one, omits it and
+// this consumes its own.
+export function parseBlock(ts: TokenStream, openTok?: Token): Block | null {
+  openTok ??= ts.advance(); // consume '{' unless already consumed
+  const parsed = ts.parseSeparated(() => parseStmt(ts), 'SEMICOLON', 'RBRACE', 'S0005', true);
+  if (parsed === null) return null;
+
+  return { kind: 'block', stmts: parsed.items, span: { start: openTok.span.start, end: parsed.close.span.end } };
+}
+
+// The parenthesized test shared by 'if' and 'while' — '(' expr ')'.
+// The body braces already delimit the construct, but the test stays
+// parenthesized to match the C-family/TS surface (§5).
+function parseCond(ts: TokenStream): Expr | null {
+  if (ts.expect('LPAREN', 'S0006') === null) return null;
+
+  const cond = parseExpr(ts);
+  if (cond === null) {
+    return null;
+  }
+
+  if (ts.expect('RPAREN', 'S0001') === null) return null;
+
+  return cond;
+}
+
+// A mandatory body block — every 'if'/'while' branch needs one, even
+// single-statement (§2: no dangling-else, no goto-fail class of bug).
+function parseRequiredBlock(ts: TokenStream): Block | null {
+  const openTok = ts.expect('LBRACE', 'S0007');
+  if (openTok === null) return null;
+  return parseBlock(ts, openTok);
+}
+
+// 'if (cond) { } else if (cond) { } else { }' — 'else if' is not its
+// own grammar rule, it's an If recursively parsed as the else branch.
+// It's an expression (see parseAtom), but it clusters with the other
+// braced control constructs, so it lives here beside 'while'.
+export function parseIf(ts: TokenStream): If | null {
+  const ifTok = ts.advance(); // consume 'if'
+
+  const cond = parseCond(ts);
+  if (cond === null) {
+    return null;
+  }
+
+  const thenBlock = parseRequiredBlock(ts);
+  if (thenBlock === null) {
+    return null;
+  }
+
+  let elseBranch: Block | If | null = null;
+  if (ts.peek().kind === 'KW_ELSE') {
+    ts.advance(); // consume 'else'
+    elseBranch = ts.peek().kind === 'KW_IF' ? parseIf(ts) : parseRequiredBlock(ts);
+    if (elseBranch === null) {
+      return null;
+    }
+  }
+
+  return {
+    kind: 'if',
+    cond,
+    then: thenBlock,
+    else: elseBranch,
+    span: { start: ifTok.span.start, end: (elseBranch ?? thenBlock).span.end },
+  };
+}
+
+// 'while (cond) { }' — a statement, not an expression (§5): a loop has
+// no single meaningful result, so it isn't usable where a value is
+// expected the way 'if' is.
+function parseWhile(ts: TokenStream): Statement | null {
+  const whileTok = ts.advance(); // consume 'while'
+
+  const cond = parseCond(ts);
+  if (cond === null) {
+    return null;
+  }
+
+  const body = parseRequiredBlock(ts);
+  if (body === null) {
+    return null;
+  }
+
+  return { kind: 'while', cond, body, span: { start: whileTok.span.start, end: body.span.end } };
+}
+
+// 'fix' and 'mut' share every rule but the keyword itself and the
+// mutability it grants — one parse method, told which by 'kind'.
+function parseDecl(ts: TokenStream, kind: 'fix' | 'mut'): Statement | null {
+  const kwTok = ts.advance(); // consume 'fix' or 'mut'
+
+  const nameTok = ts.peek();
+  if (nameTok.kind !== 'SLOT') {
+    ts.report('S0003', nameTok.span);
+    return null;
+  }
+  ts.advance(); // consume slot name
+
+  let typeAnnotation: TypeExpr | null = null;
+  if (ts.peek().kind === 'COLON') {
+    ts.advance(); // consume ':'
+    typeAnnotation = parseTypeExpr(ts);
+    if (typeAnnotation === null) return null;
+  }
+
+  if (ts.expect('EQUALS', 'S0004') === null) return null;
+
+  const init = parseExpr(ts);
+  if (init === null) {
+    return null;
+  }
+
+  return {
+    kind,
+    name: nameTok.value,
+    typeAnnotation,
+    init,
+    span: { start: kwTok.span.start, end: init.span.end },
+  };
+}
+
+// 'name = expr;' — reassigns a slot already declared with 'fix' or
+// 'mut'. Whether that's actually allowed (the slot must be 'mut') is
+// a name-binding rule, not a grammar rule, so it's checked at
+// evaluation time (interpreter.ts), not here.
+function parseAssign(ts: TokenStream): Statement | null {
+  const nameTok = ts.advance(); // consume slot name
+  ts.advance(); // consume '='
+
+  const value = parseExpr(ts);
+  if (value === null) {
+    return null;
+  }
+
+  return {
+    kind: 'assign',
+    name: nameTok.value,
+    value,
+    span: { start: nameTok.span.start, end: value.span.end },
+  };
+}
+
+export function parseStmt(ts: TokenStream): Statement | null {
+  if (ts.peek().kind === 'KW_FIX') {
+    return parseDecl(ts, 'fix');
+  }
+  if (ts.peek().kind === 'KW_MUT') {
+    return parseDecl(ts, 'mut');
+  }
+  if (ts.peek().kind === 'KW_WHILE') {
+    return parseWhile(ts);
+  }
+  if (ts.peek().kind === 'SLOT' && ts.peekNext().kind === 'EQUALS') {
+    return parseAssign(ts);
+  }
+
+  const expr = parseExpr(ts);
+  if (expr === null) {
+    return null;
+  }
+  return { kind: 'expr', expr, span: expr.span };
+}

package/src/parser/token-stream.ts

@@ -0,0 +1,121 @@
+import type { Token, TokenKind, Marker, Span } from '../lexer/token.js';
+
+// The token stream is everything the grammar productions in expr.ts,
+// stmt.ts and type-expr.ts share but that isn't grammar itself: the
+// cursor (peek/advance/peekNext), the error log, and the two
+// stream-level combinators (expect, parseSeparated) built on top of
+// them. Each production is a free function taking one of these, instead
+// of a method on a monolithic Parser — so "how do I read the next
+// token" lives in one place and the grammar files only describe grammar.
+export class TokenStream {
+  private readonly tokens: Token[];
+  private pos: number = 0;
+
+  // The accumulated diagnostics. Productions append via report()/expect();
+  // the top-level parse() hands this straight out as errorMarkers.
+  public readonly errors: Marker[] = [];
+
+  public constructor(tokens: Token[]) {
+    this.tokens = tokens;
+  }
+
+  // The lexer guarantees the last token is always EOF, so the fallback
+  // is only reached if pos somehow exceeds the array — it never will.
+  public peek(): Token {
+    return this.tokens[this.pos] ?? this.tokens[this.tokens.length - 1]!;
+  }
+
+  public advance(): Token {
+    return this.tokens[this.pos++] ?? this.tokens[this.tokens.length - 1]!;
+  }
+
+  // Looks past the current token without consuming anything — needed to
+  // tell an assignment ('x = …') apart from an expression starting with
+  // a slot reference, which otherwise look identical for one token.
+  public peekNext(): Token {
+    return this.tokens[this.pos + 1] ?? this.tokens[this.tokens.length - 1]!;
+  }
+
+  // Record a diagnostic at a given span. The one place productions push
+  // to the error log when they need to report something expect() can't
+  // express (e.g. "this token was fine but the *next* thing is wrong").
+  public report(code: string, span: Span): void {
+    this.errors.push({ code, span });
+  }
+
+  // Consume-or-diagnose: the shape every "expect this exact token here"
+  // check in the grammar shares. Returns the consumed token, or records
+  // `code` at the offending token's span and returns null.
+  public expect(kind: TokenKind, code: string): Token | null {
+    const tok = this.peek();
+    if (tok.kind !== kind) {
+      this.report(code, tok.span);
+      return null;
+    }
+    return this.advance();
+  }
+
+  // Keywords that start a statement outright (mirrors parseStmt's own
+  // dispatch in stmt.ts). synchronize() treats one of these as a safe
+  // place to resume, since it's a far more reliable restart point than
+  // an arbitrary token that merely happens to also start an expression.
+  private static readonly STMT_START_KINDS: ReadonlySet<TokenKind> = new Set(['KW_FIX', 'KW_MUT', 'KW_WHILE']);
+
+  // Panic-mode recovery: skip tokens until the next statement boundary —
+  // the separator, the enclosing close token, EOF, or a statement-start
+  // keyword — without consuming whichever of those it lands on. Only
+  // parseSeparated's `recover` path calls this; it never reports a
+  // diagnostic itself, since the caller already recorded one for
+  // whatever failed before giving up and calling this.
+  private synchronize(sep: TokenKind, close: TokenKind): void {
+    while (this.peek().kind !== sep && this.peek().kind !== close && this.peek().kind !== 'EOF') {
+      if (TokenStream.STMT_START_KINDS.has(this.peek().kind)) return;
+      this.advance();
+    }
+  }
+
+  // Parses `item (sep item)* close`, allowing an empty list and a
+  // trailing separator right before `close`. `close` is returned
+  // alongside the items since callers need its span to close off the
+  // enclosing node.
+  //
+  // Without `recover`, a failing item or a missing close token aborts
+  // the whole list — the right call for a call's args or a list
+  // literal, where a bad element can't be recovered from without
+  // guessing. With `recover` (set only by parseBlock and parseProgram),
+  // a failing item instead calls synchronize() and keeps going, so one
+  // malformed statement doesn't take the rest of the file's diagnostics
+  // down with it. The list can still come back null if synchronize()
+  // runs all the way to EOF without ever finding `close`.
+  public parseSeparated<T>(
+    parseItem: () => T | null,
+    sep: TokenKind,
+    close: TokenKind,
+    closeCode: string,
+    recover = false,
+  ): { items: T[]; close: Token } | null {
+    const items: T[] = [];
+    if (this.peek().kind !== close) {
+      for (; ;) {
+        const item = parseItem();
+        if (item === null) {
+          if (!recover) return null;
+          this.synchronize(sep, close);
+          if (this.peek().kind === close || this.peek().kind === 'EOF') break;
+          if (this.peek().kind === sep) {
+            this.advance(); // consume the separator synchronize stopped on
+            if (this.peek().kind === close) break; // trailing separator after a recovered statement
+          }
+          continue;
+        }
+        items.push(item);
+        if (this.peek().kind !== sep) break;
+        this.advance(); // consume separator
+        if (this.peek().kind === close) break; // trailing separator
+      }
+    }
+    const closeTok = this.expect(close, closeCode);
+    if (closeTok === null) return null;
+    return { items, close: closeTok };
+  }
+}

package/src/parser/type-expr.ts

@@ -0,0 +1,63 @@
+import type { TypeExpr, ArgDef, ArgType } from './ast.js';
+import type { TokenStream } from './token-stream.js';
+
+// 'Int', 'Float', 'Bool', 'String', or 'List<Type>' — used in type annotations.
+export function parseTypeExpr(ts: TokenStream): TypeExpr | null {
+  const tok = ts.peek();
+  if (tok.kind !== 'TYPE_NAME') {
+    ts.report('S0010', tok.span);
+    return null;
+  }
+  ts.advance(); // consume type name
+
+  if (tok.value === 'List') {
+    if (ts.expect('LT', 'S0010') === null) return null;
+
+    const elem = parseTypeExpr(ts);
+    if (elem === null) return null;
+
+    const gt = ts.expect('GT', 'S0010');
+    if (gt === null) return null;
+
+    return { kind: 'ListType', elem, span: { start: tok.span.start, end: gt.span.end } };
+  }
+
+  const name = tok.value as 'Int' | 'Float' | 'Bool' | 'String';
+  return { kind: 'TypeName', name, span: tok.span };
+}
+
+// 'name: Type' — one entry in an args declaration. Unlike a slot's type
+// annotation this only allows a bare type name (no 'List<…>'), so it
+// reads the TYPE_NAME token directly rather than going through
+// parseTypeExpr.
+function parseArgDef(ts: TokenStream): ArgDef | null {
+  const nameTok = ts.peek();
+  if (nameTok.kind !== 'SLOT') {
+    ts.report('S0003', nameTok.span);
+    return null;
+  }
+  ts.advance(); // consume name
+
+  if (ts.expect('COLON', 'S0009') === null) return null;
+
+  const typeTok = ts.peek();
+  if (typeTok.kind !== 'TYPE_NAME') {
+    ts.report('S0010', typeTok.span);
+    return null;
+  }
+  ts.advance(); // consume type name
+
+  return { name: nameTok.value, type: typeTok.value as ArgType };
+}
+
+// 'args (name: Type, …)' — the program's typed input declaration.
+export function parseArgs(ts: TokenStream): ArgDef[] | null {
+  ts.advance(); // consume 'args'
+
+  if (ts.expect('LPAREN', 'S0006') === null) return null;
+
+  const parsed = ts.parseSeparated(() => parseArgDef(ts), 'COMMA', 'RPAREN', 'S0001');
+  if (parsed === null) return null;
+
+  return parsed.items;
+}