stone-lang 0.1.0

package/frontend/parsing/astBuilder.js

@@ -0,0 +1,2196 @@
+/**
+ * Stone Language Parser
+ *
+ * Converts token stream into Abstract Syntax Tree (AST)
+ */
+
+import { TokenType, Lexer } from "./tokenizer.js";
+import {
+  Program,
+  Assignment,
+  DestructuringAssignment,
+  IndexedAssignment,
+  TypeAlias,
+  Literal,
+  Identifier,
+  BinaryOp,
+  UnaryOp,
+  FunctionCall,
+  BranchExpression,
+  BranchPath,
+  LoopExpression,
+  LoopVariable,
+  ForDriver,
+  WhileDriver,
+  VariableUpdate,
+  ReturnStatement,
+  BreakStatement,
+  ContinueStatement,
+  Range,
+  ArrayLiteral,
+  ObjectLiteral,
+  BlockExpression,
+  MemberAccess,
+  StringInterpolation,
+  FunctionDefinition,
+  Parameter,
+  TypeAnnotation,
+  createLocation,
+  // Unified braces
+  BindingStructure,
+  Binding,
+  // Module types
+  ImportStatement,
+  NamespaceImportStatement,
+  ImportSpecifier,
+  ExportStatement,
+  SelectiveReExportStatement,
+  NamespaceReExportStatement,
+} from "./stoneAstTypes.js";
+
+export class Parser {
+  constructor(tokens, filename = "<stdin>") {
+    this.tokens = tokens;
+    this.filename = filename;
+    this.pos = 0;
+  }
+
+  /**
+   * Create a parse error with stage information
+   * @param {string} message - Error message
+   * @param {Object} token - Token for location info (optional)
+   * @returns {Error} Error with stage and location info
+   */
+  _parseError(message, token = null) {
+    const loc = token ? { line: token.line, column: token.column } : null;
+    const error = new Error(message);
+    error.stage = 'parse';
+    error.type = 'syntax';
+    error.location = loc;
+    return error;
+  }
+
+  /**
+   * Parse the entire program
+   */
+  parse() {
+    const statements = [];
+    const imports = [];
+    const exports = [];
+
+    while (!this.isAtEnd()) {
+      const stmt = this.parseStatement();
+      if (stmt) {
+        statements.push(stmt);
+        // Track imports and exports separately for module resolution
+        if (stmt.type === "ImportStatement" || stmt.type === "NamespaceImportStatement") {
+          imports.push(stmt);
+        }
+        if (stmt.type === "ExportStatement" || stmt.type === "SelectiveReExportStatement" || stmt.type === "NamespaceReExportStatement") {
+          exports.push(stmt);
+        }
+      }
+    }
+
+    const program = new Program(statements, this.createLocation());
+    program.imports = imports;
+    program.exports = exports;
+    return program;
+  }
+
+  /**
+   * Parse a single statement
+   */
+  parseStatement() {
+    while (this.match(TokenType.NEWLINE)) {
+      // Skip
+    }
+
+    if (this.isAtEnd()) return null;
+
+    // Import statement: import ... from ... OR import path/to/module
+    if (this.match(TokenType.IMPORT)) {
+      return this.parseImportStatement();
+    }
+
+    // Export statement: export fn ... OR export name = ...
+    if (this.match(TokenType.EXPORT)) {
+      return this.parseExportStatement();
+    }
+
+    // Type alias: type Name = TypeAnnotation
+    if (this.match(TokenType.TYPE)) {
+      return this.parseTypeAlias();
+    }
+
+    // Extension function: ext name(self: type, ...) = expr
+    if (this.match(TokenType.EXTENSION)) {
+      return this.parseFunctionDefinition(true);
+    }
+
+    // Function definition: fn name(params) = expr  OR  fn name(params) { ... }
+    if (this.match(TokenType.FN)) {
+      return this.parseFunctionDefinition(false);
+    }
+
+    // Return statement
+    if (this.match(TokenType.RETURN)) {
+      return this.parseReturn();
+    }
+
+    // Break statement
+    if (this.match(TokenType.BREAK)) {
+      return new BreakStatement(this.createLocation());
+    }
+
+    // Continue statement
+    if (this.match(TokenType.CONTINUE)) {
+      return new ContinueStatement(this.createLocation());
+    }
+
+    // Bare for/while loop without state block: for (i in range(n)) { body }
+    // This is syntactic sugar for { } for (i in range(n)) { body } with empty state
+    if (this.check(TokenType.FOR) || this.check(TokenType.WHILE)) {
+      const startLoc = this.createLocation();
+      // Create empty state block (no loop variables)
+      const emptyState = new BindingStructure([], null, startLoc);
+      return this.parseLoopWithState(emptyState, startLoc);
+    }
+
+    // Loop variable update with compound operators (+=, -=, *=, /=)
+    if (this.check(TokenType.IDENTIFIER)) {
+      const nextToken = this.tokens[this.pos + 1];
+      if (
+        nextToken &&
+        (nextToken.type === TokenType.PLUS_ASSIGN ||
+          nextToken.type === TokenType.MINUS_ASSIGN ||
+          nextToken.type === TokenType.STAR_ASSIGN ||
+          nextToken.type === TokenType.SLASH_ASSIGN)
+      ) {
+        const startLoc = this.createLocation();
+        const variableName = this.advance().value;
+        const operator = this.advance().value;
+        const value = this.parseExpression();
+        return new VariableUpdate(variableName, operator, value, startLoc);
+      }
+
+      // Increment/decrement operators (++, --)
+      if (
+        nextToken &&
+        (nextToken.type === TokenType.INCREMENT ||
+          nextToken.type === TokenType.DECREMENT)
+      ) {
+        const startLoc = this.createLocation();
+        const variableName = this.advance().value;
+        const operator = this.advance().value;
+        return new VariableUpdate(variableName, operator, null, startLoc);
+      }
+    }
+
+    // Try to parse as assignment or expression
+    return this.parseAssignmentOrExpression();
+  }
+
+  /**
+   * Parse import statement
+   * Supports forms:
+   * 1. Selective import: import name1, name2 as alias from path/to/module
+   * 2. Namespace import: import path/to/module [as Alias]
+   * 3. Quoted namespace import: import "path with spaces" [as Alias]
+   * 4. Quoted selective import: import name from "path with spaces"
+   * 5. Directory + inferred filename: import stats from "dir" -> resolves to "dir/stats.stn"
+   */
+  parseImportStatement() {
+    const startLoc = this.createLocation();
+
+    const firstToken = this.peek();
+
+    // Check for quoted path at the start (namespace import with quoted path)
+    if (firstToken.type === TokenType.STRING) {
+      const { path, isQuoted } = this.parseModulePath();
+      let alias = null;
+
+      if (this.matchContextualKeyword("as")) {
+        alias = this.consume(TokenType.IDENTIFIER, "Expected alias name after 'as'").value;
+      }
+
+      return new NamespaceImportStatement(path, alias, startLoc, isQuoted);
+    }
+
+    if (firstToken.type === TokenType.IDENTIFIER) {
+      // Could be selective or namespace import - need to look ahead
+      // Save position for backtracking
+      const savedPos = this.pos;
+
+      // Try parsing as selective import specifiers
+      const specifiers = [];
+
+      // Parse first identifier
+      let nameToken = this.advance();
+      let name = nameToken.value;
+      let specLoc = { line: nameToken.line, column: nameToken.column };
+      let alias = null;
+
+      if (this.matchContextualKeyword("as")) {
+        alias = this.consume(TokenType.IDENTIFIER, "Expected alias name after 'as'").value;
+      }
+
+      specifiers.push(new ImportSpecifier(name, alias, specLoc));
+
+      // Check for comma (more specifiers) or FROM (selective import)
+      while (this.match(TokenType.COMMA)) {
+        if (!this.check(TokenType.IDENTIFIER)) {
+          break;
+        }
+        nameToken = this.advance();
+        name = nameToken.value;
+        specLoc = { line: nameToken.line, column: nameToken.column };
+        alias = null;
+        if (this.matchContextualKeyword("as")) {
+          alias = this.consume(TokenType.IDENTIFIER, "Expected alias name after 'as'").value;
+        }
+        specifiers.push(new ImportSpecifier(name, alias, specLoc));
+      }
+
+      // If we see FROM, this is a selective import
+      if (this.match(TokenType.FROM)) {
+        const { path, isQuoted } = this.parseModulePath();
+
+        // For quoted paths with exactly ONE specifier, set inferredFilename
+        // This enables: import stats from "core logic/math" -> "core logic/math/stats.stn"
+        let inferredFilename = null;
+        if (isQuoted && specifiers.length === 1) {
+          inferredFilename = specifiers[0].importedName;
+        }
+
+        return new ImportStatement(specifiers, path, startLoc, isQuoted, inferredFilename);
+      }
+
+      // Otherwise, backtrack and parse as namespace import
+      this.pos = savedPos;
+    }
+
+    // Parse as namespace import: import path/to/module [as Alias]
+    const { path, isQuoted } = this.parseModulePath();
+    let alias = null;
+
+    if (this.matchContextualKeyword("as")) {
+      alias = this.consume(TokenType.IDENTIFIER, "Expected alias name after 'as'").value;
+    }
+
+    return new NamespaceImportStatement(path, alias, startLoc, isQuoted);
+  }
+
+  /**
+   * Parse a module path
+   * Handles:
+   *   - Identifier paths: path/to/module, ./relative/path, ../parent/path
+   *   - Quoted string paths: "path with spaces/to/module"
+   * Module paths use / as separator
+   * @returns {{ path: string, isQuoted: boolean }}
+   */
+  parseModulePath() {
+    // Check for quoted string path (ModuleLocator)
+    if (this.check(TokenType.STRING)) {
+      const stringToken = this.advance();
+      const path = stringToken.value;
+
+      // Validate: no empty path
+      if (!path || path.trim() === '') {
+        throw this._parseError(`Module path cannot be empty`, stringToken);
+      }
+
+      return { path, isQuoted: true };
+    }
+
+    // Existing identifier-based path parsing (ModulePath)
+    let path = "";
+
+    // Handle relative paths: ./ or ../
+    // Note: ".." is tokenized as RANGE, not two separate DOTs
+    if (this.check(TokenType.RANGE)) {
+      // Parent directory: ../
+      this.advance(); // consume the ".." (RANGE token)
+      path += "..";
+
+      // Expect slash after ..
+      if (this.match(TokenType.SLASH)) {
+        path += "/";
+      }
+    } else if (this.check(TokenType.DOT)) {
+      this.advance(); // consume single dot
+      path += ".";
+
+      // Expect slash after .
+      if (this.match(TokenType.SLASH)) {
+        path += "/";
+      }
+    }
+
+    // Helper to parse a path segment that may contain hyphens
+    // e.g., "test-stn-scripts" is parsed as one segment
+    const parsePathSegment = () => {
+      if (!this.check(TokenType.IDENTIFIER)) {
+        return null;
+      }
+      let segment = this.advance().value;
+
+      // Allow hyphens within path segments: identifier-identifier-...
+      // Check that the hyphen immediately follows (same line, no space implied by token positions)
+      while (this.check(TokenType.MINUS)) {
+        const minusToken = this.peek();
+        const prevToken = this.tokens[this.pos - 1];
+        // Only treat as hyphenated if on same line and appears contiguous
+        if (minusToken.line === prevToken.line) {
+          this.advance(); // consume the minus
+          if (this.check(TokenType.IDENTIFIER)) {
+            const nextToken = this.peek();
+            if (nextToken.line === minusToken.line) {
+              segment += "-" + this.advance().value;
+            } else {
+              // Minus followed by identifier on different line - put minus back conceptually
+              // Actually we can't put it back, so this is an error case
+              throw this._parseError(`Unexpected line break in hyphenated module path`, nextToken);
+            }
+          } else {
+            throw this._parseError(`Expected identifier after '-' in module path`, this.peek());
+          }
+        } else {
+          break;
+        }
+      }
+      return segment;
+    };
+
+    // Parse path segments separated by /
+    const firstSegment = parsePathSegment();
+    if (firstSegment) {
+      path += firstSegment;
+
+      while (this.match(TokenType.SLASH)) {
+        path += "/";
+        const segment = parsePathSegment();
+        if (segment) {
+          path += segment;
+        } else {
+          throw this._parseError(`Expected identifier after '/' in module path`, this.peek());
+        }
+      }
+    }
+
+    if (!path) {
+      throw this._parseError(`Expected module path`, this.peek());
+    }
+
+    return { path, isQuoted: false };
+  }
+
+  /**
+   * Parse export statement
+   * export fn name(...) = ...           - function export
+   * export name = value                 - local binding export
+   * export ./path [as alias]            - namespace re-export
+   * export name1, name2 from ./path     - selective re-export
+   */
+  parseExportStatement() {
+    const startLoc = this.createLocation();
+
+    // Extension function export: export ext name(self: type, ...) = ...
+    if (this.match(TokenType.EXTENSION)) {
+      const funcDef = this.parseFunctionDefinition(true);
+      return new ExportStatement(funcDef, startLoc);
+    }
+
+    // Function export: export fn name(...) { ... }
+    if (this.match(TokenType.FN)) {
+      const funcDef = this.parseFunctionDefinition(false);
+      return new ExportStatement(funcDef, startLoc);
+    }
+
+    // Namespace re-export starting with relative path: export ./path [as alias]
+    if (this.check(TokenType.DOT)) {
+      const { path: modulePath } = this.parseModulePath();
+      let alias = null;
+      if (this.matchContextualKeyword("as")) {
+        alias = this.consume(TokenType.IDENTIFIER, "Expected alias name after 'as'").value;
+      }
+      return new NamespaceReExportStatement(modulePath, alias, startLoc);
+    }
+
+    // Check for identifier - could be selective re-export or local binding export
+    if (this.check(TokenType.IDENTIFIER)) {
+      const savedPos = this.pos;
+
+      // Try parsing as selective re-export specifiers
+      const specifiers = [];
+      let name = this.advance().value;
+      let alias = null;
+
+      if (this.matchContextualKeyword("as")) {
+        alias = this.consume(TokenType.IDENTIFIER, "Expected alias name after 'as'").value;
+      }
+      specifiers.push({ name, alias });
+
+      // Check for more specifiers (comma-separated)
+      while (this.match(TokenType.COMMA)) {
+        if (!this.check(TokenType.IDENTIFIER)) break;
+        name = this.advance().value;
+        alias = null;
+        if (this.matchContextualKeyword("as")) {
+          alias = this.consume(TokenType.IDENTIFIER, "Expected alias name after 'as'").value;
+        }
+        specifiers.push({ name, alias });
+      }
+
+      // If followed by FROM, it's selective re-export
+      if (this.match(TokenType.FROM)) {
+        const { path: modulePath } = this.parseModulePath();
+
+        // Check for trailing `as alias` after module path (for single specifier only)
+        // Syntax: export name from ./path as alias
+        if (specifiers.length === 1 && specifiers[0].alias === null && this.matchContextualKeyword("as")) {
+          specifiers[0].alias = this.consume(TokenType.IDENTIFIER, "Expected alias name after 'as'").value;
+        }
+
+        return new SelectiveReExportStatement(specifiers, modulePath, startLoc);
+      }
+
+      // Backtrack - not a selective re-export
+      this.pos = savedPos;
+
+      // Try as local binding export: export name = value
+      const assignment = this.parseAssignmentOrExpression();
+      return new ExportStatement(assignment, startLoc);
+    }
+
+    throw this._parseError(`Expected function definition, assignment, or re-export after 'export'`, this.peek());
+  }
+
+  /**
+   * Parse type alias
+   * type Name = TypeAnnotation
+   */
+  parseTypeAlias() {
+    const startLoc = this.createLocation();
+
+    const name = this.consume(
+      TokenType.IDENTIFIER,
+      "Expected type alias name"
+    ).value;
+
+    this.consume(TokenType.ASSIGN, "Expected '=' after type alias name");
+
+    const typeAnnotation = this.parseTypeAnnotation();
+
+    return new TypeAlias(name, typeAnnotation, startLoc);
+  }
+
+  /**
+   * Parse function definition
+   * fn name(params) = expr
+   * fn name(params) { ... }
+   * extend fn name(self: type, ...) = expr  (when isExtension=true)
+   */
+  parseFunctionDefinition(isExtension = false) {
+    const startLoc = this.createLocation();
+
+    const name = this.consume(
+      TokenType.IDENTIFIER,
+      "Expected function name"
+    ).value;
+
+    // Parse parameters
+    this.consume(TokenType.LPAREN, "Expected '(' after function name");
+    const parameters = [];
+
+    if (!this.check(TokenType.RPAREN)) {
+      do {
+        const paramName = this.consume(
+          TokenType.IDENTIFIER,
+          "Expected parameter name"
+        ).value;
+        let typeAnnotation = null;
+        let defaultValue = null;
+
+        // Optional type annotation: param: Type
+        if (this.match(TokenType.COLON)) {
+          typeAnnotation = this.parseTypeAnnotation();
+        }
+
+        // Optional default value: param = value
+        if (this.match(TokenType.ASSIGN)) {
+          defaultValue = this.parseExpression();
+        }
+
+        parameters.push(new Parameter(paramName, typeAnnotation, defaultValue));
+      } while (this.match(TokenType.COMMA));
+    }
+
+    this.consume(TokenType.RPAREN, "Expected ')' after parameters");
+
+    // Validate extension function requirements
+    let selfType = null;
+    if (isExtension) {
+      if (parameters.length === 0) {
+        throw this._parseError(
+          "Extension function must have at least one parameter named 'self'",
+          this.peek()
+        );
+      }
+      const firstParam = parameters[0];
+      if (firstParam.name !== "self") {
+        throw this._parseError(
+          `Extension function's first parameter must be named 'self', got '${firstParam.name}'`,
+          this.peek()
+        );
+      }
+      if (!firstParam.typeAnnotation) {
+        throw this._parseError(
+          "Extension function's 'self' parameter must have a type annotation",
+          this.peek()
+        );
+      }
+      selfType = firstParam.typeAnnotation;
+    }
+
+    // Optional return type annotation
+    let returnType = null;
+    if (this.match(TokenType.ARROW)) {
+      returnType = this.parseTypeAnnotation();
+    }
+
+    // Expression form: fn name(params) = expr
+    if (this.match(TokenType.ASSIGN)) {
+      const body = this.parseExpression();
+      const funcDef = new FunctionDefinition(
+        name,
+        parameters,
+        returnType,
+        body,
+        true,
+        startLoc
+      );
+      funcDef.isExtension = isExtension;
+      funcDef.selfType = selfType;
+      return funcDef;
+    }
+
+    // Block form: fn name(params) { ... }
+    this.consume(
+      TokenType.LBRACE,
+      "Expected '=' or '{' after function signature"
+    );
+    const body = this.parseBlock();
+    this.consume(TokenType.RBRACE, "Expected '}' to end function body");
+
+    const funcDef = new FunctionDefinition(
+      name,
+      parameters,
+      returnType,
+      body,
+      false,
+      startLoc
+    );
+    funcDef.isExtension = isExtension;
+    funcDef.selfType = selfType;
+    return funcDef;
+  }
+
+  /**
+   * Parse assignment or expression statement
+   */
+  parseAssignmentOrExpression() {
+    const startLoc = this.createLocation();
+
+    // Check for indexed assignment: name[i] = ... or name[i][j] = ...
+    if (this.check(TokenType.IDENTIFIER)) {
+      const savedPos = this.pos;
+
+      // Try to parse as indexed assignment
+      const indexedResult = this.tryParseIndexedAssignment(startLoc);
+      if (indexedResult) {
+        return indexedResult;
+      }
+
+      // Restore position if not indexed assignment
+      this.pos = savedPos;
+    }
+
+    // Try to parse as regular assignment (possibly with destructuring)
+    if (this.check(TokenType.IDENTIFIER)) {
+      const savedPos = this.pos;
+
+      // Parse destructuring list: a, b, c  OR  a as x, b, c as z
+      const destructuring = this.parseDestructuringList();
+
+      // Check for type annotation BEFORE = (syntax: x: Int = 42, x: {name: string} = ...)
+      let typeAnnotation = null;
+      if (destructuring.length === 1 && this.check(TokenType.COLON)) {
+        // Check if next is a type start: identifier, { (record), or ( (function)
+        const aheadPos = this.pos + 1;
+        if (aheadPos < this.tokens.length) {
+          const nextType = this.tokens[aheadPos].type;
+          if (
+            nextType === TokenType.IDENTIFIER ||
+            nextType === TokenType.LBRACE ||
+            nextType === TokenType.LPAREN
+          ) {
+            this.advance(); // consume :
+            typeAnnotation = this.parseTypeAnnotation();
+          }
+        }
+      }
+
+      // Check if this is actually an assignment (= or :=)
+      const isDestructuringAssignment = this.match(TokenType.COLON_ASSIGN);
+      const isRegularAssignment =
+        !isDestructuringAssignment && this.match(TokenType.ASSIGN);
+
+      if (isDestructuringAssignment || isRegularAssignment) {
+        // Type annotation with := is not allowed
+        if (isDestructuringAssignment && typeAnnotation) {
+          throw this._parseError(
+            `Type annotations are not allowed with := operator`,
+            { line: startLoc.line, column: startLoc.column }
+          );
+        }
+
+        // Parse the right-hand side
+        const value = this.parseExpression();
+
+        // Handle destructuring with := operator
+        if (isDestructuringAssignment) {
+          // Special handling for LoopExpression - attach destructuring to the loop
+          if (value.type === "LoopExpression") {
+            value.destructuring = destructuring;
+            value.isDestructured = true;
+            // Only validate destructuring if there are multiple targets
+            // Single name binding (e.g., result := loop(...)) binds the whole loop result object
+            if (destructuring.length > 1) {
+              this.validateLoopDestructuring(value);
+            }
+            return new Assignment(destructuring[0].name, value, null, startLoc);
+          }
+
+          // For any other expression (including ObjectLiteral, Identifier, etc.)
+          // create a DestructuringAssignment node
+          return new DestructuringAssignment(destructuring, value, startLoc);
+        }
+
+        // Handle multi-variable destructuring with = (also requires loop/record)
+        if (isRegularAssignment && destructuring.length > 1) {
+          if (
+            value.type !== "LoopExpression" &&
+            value.type !== "ObjectLiteral"
+          ) {
+            throw this._parseError(
+              `Multi-variable assignment requires a loop or record expression`,
+              { line: startLoc.line, column: startLoc.column }
+            );
+          }
+
+          if (value.type === "LoopExpression") {
+            value.destructuring = destructuring;
+            value.isDestructured = false;
+            this.validateLoopDestructuring(value);
+          }
+
+          return new Assignment(destructuring[0].name, value, null, startLoc);
+        }
+
+        // Single variable assignment (standard case)
+        if (destructuring.length === 1) {
+          if (value.type === "LoopExpression") {
+            value.isDestructured = false;
+          }
+          // Promote number literals to complex when type annotation is :complex
+          let assignValue = value;
+          if (typeAnnotation?.kind === "simple" && typeAnnotation.details?.name === "complex") {
+            if (value?.type === "Literal" && value.literalType === "number") {
+              assignValue = new Literal(new Complex(value.value, 0), "complex", value.location);
+            } else if (value?.type === "UnaryOp" && value.operator === "-" &&
+                       value.operand?.type === "Literal" && value.operand.literalType === "number") {
+              // Handle negative numbers: -3 is parsed as UnaryOp("-", Literal(3))
+              assignValue = new Literal(new Complex(-value.operand.value, 0), "complex", value.location);
+            }
+          }
+          return new Assignment(
+            destructuring[0].name,
+            assignValue,
+            typeAnnotation,
+            startLoc
+          );
+        }
+      }
+
+      // Not an assignment - restore position and parse as expression
+      this.pos = savedPos;
+    }
+
+    // Parse as expression
+    const expr = this.parseExpression();
+    return expr;
+  }
+
+  /**
+   * Try to parse indexed assignment: name[i] = expr or name[i][j] = expr
+   * Returns null if not an indexed assignment
+   */
+  tryParseIndexedAssignment(startLoc) {
+    const targetName = this.advance().value;
+    const indices = [];
+
+    // Must have at least one [
+    if (!this.check(TokenType.LBRACKET)) {
+      return null;
+    }
+
+    // Collect all indices
+    while (this.match(TokenType.LBRACKET)) {
+      // Index must be a simple identifier for mapping
+      if (!this.check(TokenType.IDENTIFIER)) {
+        return null; // Not a mapping pattern, might be computed access
+      }
+
+      const indexName = this.advance().value;
+
+      if (!this.match(TokenType.RBRACKET)) {
+        return null;
+      }
+
+      indices.push(indexName);
+    }
+
+    // Must be followed by = for indexed assignment
+    if (!this.match(TokenType.ASSIGN)) {
+      return null;
+    }
+
+    // Parse the value expression
+    const value = this.parseExpression();
+
+    return new IndexedAssignment(targetName, indices, value, startLoc);
+  }
+
+  /**
+   * Parse destructuring list: a, b, c  OR  a as x, b, c as z
+   */
+  parseDestructuringList() {
+    const destructuring = [];
+
+    if (!this.check(TokenType.IDENTIFIER)) {
+      return destructuring;
+    }
+
+    let name = this.advance().value;
+    let alias = null;
+
+    if (this.matchContextualKeyword("as")) {
+      alias = this.consume(
+        TokenType.IDENTIFIER,
+        "Expected alias name after 'as'"
+      ).value;
+    }
+
+    destructuring.push({ name, alias });
+
+    while (this.match(TokenType.COMMA)) {
+      if (!this.check(TokenType.IDENTIFIER)) {
+        break;
+      }
+
+      name = this.advance().value;
+      alias = null;
+
+      if (this.matchContextualKeyword("as")) {
+        alias = this.consume(
+          TokenType.IDENTIFIER,
+          "Expected alias name after 'as'"
+        ).value;
+      }
+
+      destructuring.push({ name, alias });
+    }
+
+    return destructuring;
+  }
+
+  /**
+   * Validate that destructuring matches loop variables
+   */
+  validateLoopDestructuring(loopExpr) {
+    if (!loopExpr.destructuring) return;
+
+    const variableNames = new Set(loopExpr.variables.map((v) => v.name));
+
+    for (const { name } of loopExpr.destructuring) {
+      if (!variableNames.has(name)) {
+        throw this._parseError(
+          `Variable '${name}' does not match any loop variable. ` +
+            `Available variables: ${Array.from(variableNames).join(", ")}`,
+          { line: loopExpr.location.line, column: loopExpr.location.column }
+        );
+      }
+    }
+  }
+
+  /**
+   * Parse return statement
+   */
+  parseReturn() {
+    const startLoc = this.createLocation();
+    const value = this.parseExpression();
+    return new ReturnStatement(value, startLoc);
+  }
+
+  /**
+   * Parse an expression (entry point - lowest precedence)
+   */
+  parseExpression() {
+    return this.parseOr();
+  }
+
+  /**
+   * Parse logical OR: ||
+   */
+  parseOr() {
+    let expr = this.parseAnd();
+
+    while (this.match(TokenType.OR)) {
+      const opToken = this.previous();
+      const opLoc = { line: opToken.line, column: opToken.column };
+      const right = this.parseAnd();
+      expr = new BinaryOp("||", expr, right, opLoc);
+    }
+
+    return expr;
+  }
+
+  /**
+   * Parse logical AND: &&
+   */
+  parseAnd() {
+    let expr = this.parseComparison();
+
+    while (this.match(TokenType.AND)) {
+      const opToken = this.previous();
+      const opLoc = { line: opToken.line, column: opToken.column };
+      const right = this.parseComparison();
+      expr = new BinaryOp("&&", expr, right, opLoc);
+    }
+
+    return expr;
+  }
+
+  /**
+   * Parse comparison operations: <, >, <=, >=, ==, !=
+   */
+  parseComparison() {
+    let expr = this.parseAddition();
+
+    while (
+      this.match(
+        TokenType.LT,
+        TokenType.GT,
+        TokenType.LTE,
+        TokenType.GTE,
+        TokenType.EQ,
+        TokenType.NEQ
+      )
+    ) {
+      const opToken = this.previous();
+      const opLoc = { line: opToken.line, column: opToken.column };
+      const operator = opToken.value;
+      const right = this.parseAddition();
+      expr = new BinaryOp(operator, expr, right, opLoc);
+    }
+
+    return expr;
+  }
+
+  /**
+   * Parse addition and subtraction: +, -, .+, .-
+   */
+  parseAddition() {
+    let expr = this.parseMatrixMult();
+
+    while (
+      this.match(
+        TokenType.PLUS,
+        TokenType.MINUS,
+        TokenType.DOT_PLUS,
+        TokenType.DOT_MINUS
+      )
+    ) {
+      const opToken = this.previous();
+      const opLoc = { line: opToken.line, column: opToken.column };
+      const operator = opToken.value;
+      const right = this.parseMatrixMult();
+      expr = new BinaryOp(operator, expr, right, opLoc);
+    }
+
+    return expr;
+  }
+
+  /**
+   * Parse matrix multiplication: @
+   */
+  parseMatrixMult() {
+    let expr = this.parseMultiplication();
+
+    while (this.match(TokenType.AT)) {
+      const opToken = this.previous();
+      const opLoc = { line: opToken.line, column: opToken.column };
+      const right = this.parseMultiplication();
+      expr = new BinaryOp("@", expr, right, opLoc);
+    }
+
+    return expr;
+  }
+
+  /**
+   * Parse multiplication, division, modulo: *, /, %, .*, ./
+   */
+  parseMultiplication() {
+    let expr = this.parsePower();
+
+    while (
+      this.match(
+        TokenType.STAR,
+        TokenType.SLASH,
+        TokenType.PERCENT,
+        TokenType.DOT_STAR,
+        TokenType.DOT_SLASH
+      )
+    ) {
+      const opToken = this.previous();
+      const opLoc = { line: opToken.line, column: opToken.column };
+      const operator = opToken.value;
+      const right = this.parsePower();
+      expr = new BinaryOp(operator, expr, right, opLoc);
+    }
+
+    return expr;
+  }
+
+  /**
+   * Parse power: ^, .^ (right-associative)
+   */
+  parsePower() {
+    let expr = this.parseUnary();
+
+    // Right-associative: a ^ b ^ c = a ^ (b ^ c)
+    if (this.match(TokenType.CARET, TokenType.DOT_CARET)) {
+      const opToken = this.previous();
+      const opLoc = { line: opToken.line, column: opToken.column };
+      const operator = opToken.value;
+      const right = this.parsePower(); // Recursively parse right side
+      expr = new BinaryOp(operator, expr, right, opLoc);
+    }
+
+    return expr;
+  }
+
+  /**
+   * Parse unary operations: -, !
+   */
+  parseUnary() {
+    if (this.match(TokenType.MINUS)) {
+      const opToken = this.previous();
+      const opLoc = { line: opToken.line, column: opToken.column };
+      const operand = this.parseUnary();
+      return new UnaryOp("-", operand, opLoc);
+    }
+
+    if (this.match(TokenType.NOT)) {
+      const opToken = this.previous();
+      const opLoc = { line: opToken.line, column: opToken.column };
+      const operand = this.parseUnary();
+      return new UnaryOp("!", operand, opLoc);
+    }
+
+    return this.parsePostfix();
+  }
+
+  /**
+   * Parse postfix operations: member access, function calls, array access, transpose
+   */
+  parsePostfix() {
+    let expr = this.parsePrimary();
+
+    while (true) {
+      // Member access: obj.field or transpose: A.T
+      if (this.match(TokenType.DOT)) {
+        const dotToken = this.previous();
+        const dotLoc = { line: dotToken.line, column: dotToken.column };
+
+        // Accept IDENTIFIER or TYPE keyword as property name
+        // (TYPE is contextual - allowed as property name like obj.type)
+        let property;
+        if (this.check(TokenType.TYPE)) {
+          property = this.advance();
+        } else {
+          property = this.consume(TokenType.IDENTIFIER, "Expected property name");
+        }
+
+        expr = new MemberAccess(
+          expr,
+          new Identifier(property.value),
+          false,
+          dotLoc
+        );
+      }
+      // Array/computed access: obj[index]
+      else if (this.match(TokenType.LBRACKET)) {
+        const bracketToken = this.previous();
+        const bracketLoc = { line: bracketToken.line, column: bracketToken.column };
+        const index = this.parseExpression();
+        this.consume(TokenType.RBRACKET, "Expected ']'");
+        expr = new MemberAccess(expr, index, true, bracketLoc);
+      }
+      // Function call: func(args) or obj.method(args)
+      else if (this.check(TokenType.LPAREN) && (expr instanceof Identifier || expr instanceof MemberAccess)) {
+        this.advance();
+        const parenToken = this.previous();
+        const parenLoc = { line: parenToken.line, column: parenToken.column };
+        const args = this.parseArguments();
+        this.consume(TokenType.RPAREN, "Expected ')'");
+        if (expr instanceof Identifier) {
+          expr = new FunctionCall(expr.name, args, parenLoc);
+        } else {
+          // Method call: obj.method(args) becomes FunctionCall with callee expression
+          expr = new FunctionCall(null, args, parenLoc, expr);
+        }
+      } else {
+        break;
+      }
+    }
+
+    return expr;
+  }
+
+  /**
+   * Parse primary expressions (literals, identifiers, loops, branches, etc.)
+   */
+  parsePrimary() {
+    const startLoc = this.createLocation();
+
+    // Literals
+    if (this.match(TokenType.NUMBER)) {
+      const value = this.previous().value;
+
+      // Check for range operator
+      if (this.match(TokenType.RANGE)) {
+        // Default range (inclusive like ..=)
+        const end = this.parseExpression();
+        let step = null;
+        if (this.match(TokenType.BY)) {
+          step = this.parseExpression();
+        }
+        return new Range(
+          new Literal(value, "number", startLoc),
+          end,
+          true,
+          step,
+          startLoc
+        );
+      } else if (this.match(TokenType.RANGE_EXCLUSIVE)) {
+        const end = this.parseExpression();
+        let step = null;
+        if (this.match(TokenType.BY)) {
+          step = this.parseExpression();
+        }
+        return new Range(
+          new Literal(value, "number", startLoc),
+          end,
+          false,
+          step,
+          startLoc
+        );
+      } else if (this.match(TokenType.RANGE_INCLUSIVE)) {
+        const end = this.parseExpression();
+        let step = null;
+        if (this.match(TokenType.BY)) {
+          step = this.parseExpression();
+        }
+        return new Range(
+          new Literal(value, "number", startLoc),
+          end,
+          true,
+          step,
+          startLoc
+        );
+      }
+
+      return new Literal(value, "number", startLoc);
+    }
+
+    // Imaginary literal: 4i or 4j → Complex(0, 4)
+    if (this.match(TokenType.IMAGINARY)) {
+      const imagValue = this.previous().value;
+      return new Literal(new Complex(0, imagValue), "complex", startLoc);
+    }
+
+    if (this.match(TokenType.STRING)) {
+      return new Literal(this.previous().value, "string", startLoc);
+    }
+
+    if (this.match(TokenType.TRUE)) {
+      return new Literal(true, "bool", startLoc);
+    }
+
+    if (this.match(TokenType.FALSE)) {
+      return new Literal(false, "bool", startLoc);
+    }
+
+    if (this.match(TokenType.NONE)) {
+      return new Literal(null, "none", startLoc);
+    }
+
+    // F-string (string interpolation)
+    if (this.match(TokenType.F_STRING_START)) {
+      const fstringToken = this.previous();
+      const fstringLoc = { line: fstringToken.line, column: fstringToken.column };
+      return this.parseFString(fstringToken.value, fstringLoc);
+    }
+
+    // Array literal: [1, 2, 3]
+    if (this.match(TokenType.LBRACKET)) {
+      return this.parseArrayLiteral();
+    }
+
+    // Unified braces: binding structure or string-keyed object literal
+    // Syntax: { name = value, ... } for bindings (objects)
+    //         { "key": value, ... } for string-keyed objects (JSON-like)
+    //         { key: value, ... } for identifier-keyed objects (also JSON-like)
+    if (this.match(TokenType.LBRACE)) {
+      // String-keyed object literal: {"name": value} - for JSON compatibility
+      if (
+        this.check(TokenType.STRING) &&
+        this.checkAhead(TokenType.COLON, 1)
+      ) {
+        return this.parseObjectLiteral();
+      }
+      // Identifier-keyed object literal: {name: value} - for JSON compatibility
+      // Distinguished from binding with type (name: Type = value) by checking
+      // if the token after : is NOT a valid type start (IDENTIFIER, LBRACE, LPAREN)
+      if (
+        this.check(TokenType.IDENTIFIER) &&
+        this.checkAhead(TokenType.COLON, 1)
+      ) {
+        // Look at token after the colon (position + 2)
+        const afterColonType = this.tokens[this.pos + 2]?.type;
+        // If it's NOT a type start, it's an object literal property
+        if (
+          afterColonType !== TokenType.IDENTIFIER &&
+          afterColonType !== TokenType.LBRACE &&
+          afterColonType !== TokenType.LPAREN
+        ) {
+          return this.parseObjectLiteral();
+        }
+      }
+      if (this.check(TokenType.RBRACE)) {
+        // Empty object
+        this.advance();
+        return new ObjectLiteral([], startLoc);
+      }
+      // Binding structure: { name = value, ... } or { statements... }
+      // Could be standalone or followed by for/while driver (making it a loop)
+      const structure = this.parseBindingStructure(startLoc);
+
+      // Check if followed by driver → it's a loop expression
+      if (this.check(TokenType.FOR) || this.check(TokenType.WHILE)) {
+        return this.parseLoopWithState(structure, startLoc);
+      }
+
+      // Driverless loop: { state } { body } - infinite loop until break
+      if (this.check(TokenType.LBRACE)) {
+        return this.parseDriverlessLoop(structure, startLoc);
+      }
+
+      return structure;
+    }
+
+    // Branch expression (if/elif/else)
+    if (this.match(TokenType.IF)) {
+      const ifToken = this.previous();
+      const ifLoc = { line: ifToken.line, column: ifToken.column };
+      return this.parseBranchExpression(ifLoc);
+    }
+
+    // Identifier
+    if (this.match(TokenType.IDENTIFIER)) {
+      const name = this.previous().value;
+      return new Identifier(name, startLoc);
+    }
+
+    // Parenthesized expression
+    if (this.match(TokenType.LPAREN)) {
+      const expr = this.parseExpression();
+      this.consume(TokenType.RPAREN, "Expected ')' after expression");
+      return expr;
+    }
+
+    throw this._parseError(`Unexpected token: ${this.peek().type}`, this.peek());
+  }
+
+  /**
+   * Parse array literal: [1, 2, 3]
+   */
+  parseArrayLiteral() {
+    // Get location of [ which was just consumed before this function was called
+    const bracketToken = this.previous();
+    const startLoc = { line: bracketToken.line, column: bracketToken.column };
+    const elements = [];
+
+    if (!this.check(TokenType.RBRACKET)) {
+      do {
+        elements.push(this.parseExpression());
+      } while (this.match(TokenType.COMMA));
+    }
+
+    this.consume(TokenType.RBRACKET, "Expected ']'");
+    return new ArrayLiteral(elements, startLoc);
+  }
+
+  /**
+   * Parse object literal: {name: "Alice", age: 30} or {"name": "Alice"}
+   */
+  parseObjectLiteral() {
+    // Get location of { which was just consumed before this function was called
+    const braceToken = this.previous();
+    const startLoc = { line: braceToken.line, column: braceToken.column };
+    const properties = [];
+
+    if (!this.check(TokenType.RBRACE)) {
+      do {
+        // Key can be identifier, string, or 'type' keyword (contextual)
+        let key;
+        if (this.check(TokenType.IDENTIFIER)) {
+          key = this.advance().value;
+        } else if (this.check(TokenType.TYPE)) {
+          // Allow 'type' as field name (it's a contextual keyword)
+          key = this.advance().value;
+        } else if (this.check(TokenType.STRING)) {
+          key = this.advance().value;
+        } else {
+          throw this._parseError(`Expected property name`, this.peek());
+        }
+        this.consume(TokenType.COLON, "Expected ':' after property name");
+        const value = this.parseExpression();
+        properties.push({ key, value });
+      } while (this.match(TokenType.COMMA));
+    }
+
+    this.consume(TokenType.RBRACE, "Expected '}'");
+    return new ObjectLiteral(properties, startLoc);
+  }
+
+  /**
+   * Parse block expression: { statements... return value }
+   * A block expression is a sequence of statements ending with a return.
+   * @example { x = 5; y = x * 2; return y }
+   */
+  parseBlockExpression(startLoc) {
+    const body = this.parseBlock();
+    this.consume(TokenType.RBRACE, "Expected '}' after block expression");
+    return new BlockExpression(body, startLoc);
+  }
+
+  /**
+   * Parse f-string (string interpolation)
+   * @param {Array} parts - The f-string parts from tokenizer
+   * @param {Object} startLoc - Location of the f-string token
+   */
+  parseFString(parts, startLoc) {
+    const literals = [];
+    const expressions = [];
+
+    for (const part of parts) {
+      if (part.type === "literal") {
+        literals.push(part.value);
+      } else if (part.type === "interpolation") {
+        const lexer = new Lexer(part.value);
+        const tokens = lexer.tokenize();
+        const parser = new Parser(tokens);
+        const expr = parser.parseExpression();
+        expressions.push(expr);
+      }
+    }
+
+    return new StringInterpolation(
+      literals,
+      expressions,
+      startLoc
+    );
+  }
+
+  /**
+   * Parse binding structure: { name = value, name: type = value, ..., trailingExpr? }
+   *
+   * A binding structure is a unified construct for:
+   * - Object-like data: { x = 10, y = 20 } → { x: 10, y: 20 }
+   * - Blocks with computation: { x = 10, x + 1 } → 11
+   * - Loop state: { sum = 0 } for (x in xs) { sum' = sum + x }
+   *
+   * @param startLoc - Location where the { was found
+   */
+  parseBindingStructure(startLoc) {
+    const bindings = [];
+    let trailingExpr = null;
+
+    while (!this.check(TokenType.RBRACE) && !this.isAtEnd()) {
+      // Check if this looks like a binding: IDENTIFIER (: type)? =
+      if (this.isBindingStart()) {
+        const binding = this.parseBinding();
+        bindings.push(binding);
+      } else {
+        // Not a binding - it's either an effect, return statement, or trailing expression
+
+        // Handle return statements inside binding structures
+        if (this.match(TokenType.RETURN)) {
+          const returnExpr = this.parseExpression();
+          const returnStmt = new ReturnStatement(returnExpr, this.createLocation());
+
+          // If followed by }, this return is the trailing expression
+          if (this.check(TokenType.RBRACE)) {
+            trailingExpr = returnStmt;
+          } else {
+            // Return as an effect (e.g., early return in a conditional)
+            bindings.push(new Binding(null, returnStmt, null));
+          }
+        } else {
+          // Parse as expression
+          const expr = this.parseExpression();
+
+          // Check what comes next to determine if this is trailing or effect
+          // If followed by comma/newline and more content, it's an effect
+          // If followed by }, it's the trailing expression
+          if (this.check(TokenType.RBRACE)) {
+            trailingExpr = expr;
+          } else {
+            // It's an effect - wrap as a binding with no name (or store separately)
+            // For now, we treat effects as bindings with generated names (or we can just
+            // store them in a separate effects array - but let's keep it simple)
+            // Actually, looking at the spec, effects don't need to be bound.
+            // Let's store them as special "effect" bindings with null name.
+            bindings.push(new Binding(null, expr, null));
+          }
+        }
+      }
+
+      // Skip comma if present (commas and newlines are interchangeable separators)
+      this.match(TokenType.COMMA);
+    }
+
+    this.consume(TokenType.RBRACE, "Expected '}' after binding structure");
+    return new BindingStructure(bindings, trailingExpr, startLoc);
+  }
+
+  /**
+   * Check if current position looks like a binding start: IDENTIFIER (: type)? (= expr)?
+   * Uses lookahead to distinguish bindings from expressions
+   *
+   * Now also detects type descriptor bindings: name: type (without = value)
+   */
+  isBindingStart() {
+    // Allow both IDENTIFIER and TYPE keyword as binding name
+    // (TYPE is contextual - allowed as field name in objects)
+    if (!this.check(TokenType.IDENTIFIER) && !this.check(TokenType.TYPE)) {
+      return false;
+    }
+
+    // Save position for lookahead
+    const savedPos = this.pos;
+    this.advance(); // consume identifier/type
+
+    let isBinding = false;
+
+    // Check for optional type annotation
+    if (this.check(TokenType.COLON)) {
+      // Could be:
+      // - binding with type and value: name: Type = value
+      // - type descriptor: name: Type (no value, ends at comma/rbrace)
+      // - object literal property: key: value (NOT a binding)
+      this.advance(); // consume :
+
+      // Check if the first token after : is a valid type start
+      // Valid type starts: IDENTIFIER (simple type), LBRACE (record/dict type), LPAREN (function type)
+      // If it's something else (NUMBER, STRING literal, etc.), it's an object literal property
+      const nextType = this.peek().type;
+      if (
+        nextType !== TokenType.IDENTIFIER &&
+        nextType !== TokenType.LBRACE &&
+        nextType !== TokenType.LPAREN
+      ) {
+        // Not a type annotation - this is an object literal property like {key: 5}
+        this.pos = savedPos;
+        return false;
+      }
+
+      // Skip type annotation tokens
+      // Type annotations can contain: identifiers, <, >, commas (in generics), |, ?, [], {}
+      let parenDepth = 0;
+      let braceDepth = 0;
+      let bracketDepth = 0;
+      let angleDepth = 0;
+
+      while (!this.isAtEnd()) {
+        // Track nesting
+        if (this.check(TokenType.LPAREN)) parenDepth++;
+        else if (this.check(TokenType.RPAREN)) parenDepth--;
+        else if (this.check(TokenType.LBRACE)) braceDepth++;
+        else if (this.check(TokenType.RBRACE)) {
+          if (braceDepth === 0) {
+            // End of containing structure - this is a type descriptor without value
+            isBinding = true;
+            break;
+          }
+          braceDepth--;
+        }
+        else if (this.check(TokenType.LBRACKET)) bracketDepth++;
+        else if (this.check(TokenType.RBRACKET)) bracketDepth--;
+        else if (this.check(TokenType.LESS)) angleDepth++;
+        else if (this.check(TokenType.GREATER)) angleDepth--;
+
+        // At top level (not nested in generics/braces), check for terminators
+        if (parenDepth === 0 && braceDepth === 0 && bracketDepth === 0 && angleDepth === 0) {
+          if (this.check(TokenType.ASSIGN)) {
+            isBinding = true; // name: Type = value
+            break;
+          }
+          if (this.check(TokenType.COMMA)) {
+            // Type descriptor without value: name: Type,
+            isBinding = true;
+            break;
+          }
+        }
+
+        this.advance();
+      }
+    } else if (this.check(TokenType.ASSIGN)) {
+      // Simple binding: name =
+      isBinding = true;
+    }
+
+    // Restore position
+    this.pos = savedPos;
+    return isBinding;
+  }
+
+  /**
+   * Parse a single binding: name (: type)? (= expr)?
+   *
+   * Supports:
+   * - Regular binding: name = expr
+   * - Typed binding: name: type = expr
+   * - Type descriptor (no value): name: type
+   * - Type descriptor with default: name: type = default
+   */
+  parseBinding() {
+    // Accept both IDENTIFIER and TYPE keyword as binding name
+    // (TYPE is contextual - allowed as field name in objects like { type = "line" })
+    let name;
+    if (this.check(TokenType.TYPE)) {
+      name = this.advance().value;
+    } else {
+      name = this.consume(TokenType.IDENTIFIER, "Expected binding name").value;
+    }
+
+    let typeAnnotation = null;
+    let value = null;
+    let isTypeDescriptor = false;
+
+    if (this.match(TokenType.COLON)) {
+      typeAnnotation = this.parseTypeAnnotation();
+      isTypeDescriptor = true; // Has type annotation = type descriptor
+
+      // Check for optional default value
+      if (this.match(TokenType.ASSIGN)) {
+        value = this.parseExpression();
+      }
+      // If no = follows, this is a type descriptor without default (required field)
+    } else {
+      // No type annotation - regular binding requires a value
+      this.consume(TokenType.ASSIGN, "Expected '=' in binding");
+      value = this.parseExpression();
+    }
+
+    // Promote number literals to complex when type annotation is :complex
+    // This ensures `a:complex = -3` creates a Complex(-3, 0) at parse time
+    if (typeAnnotation?.kind === "simple" && typeAnnotation.details?.name === "complex") {
+      if (value?.type === "Literal" && value.literalType === "number") {
+        value = new Literal(new Complex(value.value, 0), "complex", value.location);
+      } else if (value?.type === "UnaryOp" && value.operator === "-" &&
+                 value.operand?.type === "Literal" && value.operand.literalType === "number") {
+        // Handle negative numbers: -3 is parsed as UnaryOp("-", Literal(3))
+        value = new Literal(new Complex(-value.operand.value, 0), "complex", value.location);
+      }
+    }
+
+    return new Binding(name, value, typeAnnotation, isTypeDescriptor);
+  }
+
+  /**
+   * Parse loop with state block: { state } driver { body }
+   * Called when we've already parsed the state block and see a driver keyword
+   *
+   * @param stateBlock - Already parsed BindingStructure for initial state
+   * @param startLoc - Location of the opening {
+   */
+  parseLoopWithState(stateBlock, startLoc) {
+    // Parse driver chain
+    const drivers = this.parseDriverChain();
+
+    // Parse body using parseBlock (supports full statement syntax including destructuring)
+    this.consume(TokenType.LBRACE, "Expected '{' to start loop body");
+    const bodyStatements = this.parseBlock();
+    this.consume(TokenType.RBRACE, "Expected '}' to end loop body");
+
+    // Convert BindingStructure bindings to LoopVariables for compatibility
+    const variables = stateBlock.bindings.map(b =>
+      new LoopVariable(b.name, b.value, b.typeAnnotation)
+    );
+
+    let loopExpr = new LoopExpression(variables, drivers, bodyStatements, null, startLoc);
+    loopExpr = this.validateAndNormalizeLoopDrivers(loopExpr);
+
+    return loopExpr;
+  }
+
+  /**
+   * Parse driverless (infinite) loop: { state } { body }
+   * This is an infinite loop that continues until break
+   *
+   * @param stateBlock - Already parsed BindingStructure for initial state
+   * @param startLoc - Location of the opening {
+   */
+  parseDriverlessLoop(stateBlock, startLoc) {
+    // Parse body using parseBlock
+    this.consume(TokenType.LBRACE, "Expected '{' to start loop body");
+    const bodyStatements = this.parseBlock();
+    this.consume(TokenType.RBRACE, "Expected '}' to end loop body");
+
+    // Convert BindingStructure bindings to LoopVariables
+    const variables = stateBlock.bindings.map(b =>
+      new LoopVariable(b.name, b.value, b.typeAnnotation)
+    );
+
+    // Create LoopExpression with empty drivers array (infinite loop)
+    return new LoopExpression(variables, [], bodyStatements, null, startLoc);
+  }
+
+  /**
+   * Convert BindingStructure to array of statements for backward compatibility
+   * This is a transitional helper until the executor is updated
+   */
+  bindingStructureToStatements(structure) {
+    const statements = [];
+
+    for (const binding of structure.bindings) {
+      if (binding.name === null) {
+        // Effect - just add the expression as a statement
+        if (binding.value) {
+          statements.push(binding.value);
+        }
+      } else if (binding.value) {
+        // Convert to Assignment - prime notation (sum') is handled by the executor context
+        // Assignment(target, value, typeAnnotation, location)
+        statements.push(new Assignment(
+          binding.name,  // Keep full name including prime suffix (sum')
+          binding.value,
+          binding.typeAnnotation,
+          binding.value.location
+        ));
+      }
+      // Skip type descriptor bindings without values (name: type) in block context
+      // They don't produce statements - they're just type declarations
+    }
+
+    // Add trailing expression as return if present
+    if (structure.trailingExpr) {
+      statements.push(new ReturnStatement(structure.trailingExpr, structure.trailingExpr.location));
+    }
+
+    return statements;
+  }
+
+  /**
+   * Parse driver chain: for(...) while(...) for(...)
+   */
+  parseDriverChain() {
+    const drivers = [];
+
+    while (this.check(TokenType.FOR) || this.check(TokenType.WHILE)) {
+      const driver = this.parseDriver();
+      if (driver) {
+        drivers.push(driver);
+      }
+    }
+
+    return drivers;
+  }
+
+  /**
+   * Parse a single driver: for(...) or while(...)
+   */
+  parseDriver() {
+    const startLoc = this.createLocation();
+
+    // for(pattern in iterable)
+    if (this.match(TokenType.FOR)) {
+      this.consume(TokenType.LPAREN, "Expected '(' after 'for'");
+
+      const pattern = this.consume(
+        TokenType.IDENTIFIER,
+        "Expected variable name in for driver"
+      ).value;
+
+      this.consume(TokenType.IN, "Expected 'in' after variable");
+
+      const iterable = this.parseExpression();
+
+      let step = null;
+      if (this.match(TokenType.BY)) {
+        step = this.parseExpression();
+      }
+
+      this.consume(TokenType.RPAREN, "Expected ')' after for driver");
+
+      return new ForDriver(pattern, iterable, step, startLoc);
+    }
+
+    // while(condition)
+    if (this.match(TokenType.WHILE)) {
+      this.consume(TokenType.LPAREN, "Expected '(' after 'while'");
+
+      const condition = this.parseExpression();
+
+      this.consume(TokenType.RPAREN, "Expected ')' after while condition");
+
+      return new WhileDriver(condition, startLoc);
+    }
+
+    return null;
+  }
+
+  /**
+   * Parse branch expression (if/elif/else)
+   * @param {Object} startLoc - Location of the 'if' keyword (passed from caller)
+   */
+  parseBranchExpression(startLoc) {
+    const paths = [];
+
+    // Parse 'if' branch
+    this.consume(TokenType.LPAREN, "Expected '(' after 'if'");
+    const ifCondition = this.parseExpression();
+    this.consume(TokenType.RPAREN, "Expected ')' after if condition");
+    this.consume(TokenType.LBRACE, "Expected '{' after if condition");
+    const ifBody = this.parseBlock();
+    this.consume(TokenType.RBRACE, "Expected '}' to end if body");
+
+    paths.push(new BranchPath("if", ifCondition, ifBody));
+
+    // Parse 'elif' branches
+    while (this.match(TokenType.ELIF)) {
+      this.consume(TokenType.LPAREN, "Expected '(' after 'elif'");
+      const elifCondition = this.parseExpression();
+      this.consume(TokenType.RPAREN, "Expected ')' after elif condition");
+      this.consume(TokenType.LBRACE, "Expected '{' after elif condition");
+      const elifBody = this.parseBlock();
+      this.consume(TokenType.RBRACE, "Expected '}' to end elif body");
+
+      paths.push(new BranchPath("elif", elifCondition, elifBody));
+    }
+
+    // Parse optional 'else' branch
+    // NOTE: else is required for value-producing conditionals but optional for side-effect only
+    if (this.match(TokenType.ELSE)) {
+      this.consume(TokenType.LBRACE, "Expected '{' after else");
+      const elseBody = this.parseBlock();
+      this.consume(TokenType.RBRACE, "Expected '}' to end else body");
+
+      paths.push(new BranchPath("else", null, elseBody));
+    }
+
+    return new BranchExpression(paths, startLoc);
+  }
+
+  /**
+   * Parse a block of statements
+   */
+  parseBlock() {
+    const statements = [];
+
+    while (!this.check(TokenType.RBRACE) && !this.isAtEnd()) {
+      const stmt = this.parseStatement();
+      if (stmt) {
+        statements.push(stmt);
+      }
+    }
+
+    return statements;
+  }
+
+  /**
+   * Parse function arguments
+   */
+  parseArguments() {
+    const args = [];
+
+    if (!this.check(TokenType.RPAREN)) {
+      do {
+        args.push(this.parseExpression());
+      } while (this.match(TokenType.COMMA));
+    }
+
+    return args;
+  }
+
+  /**
+   * Parse type annotation
+   *
+   * Supports:
+   * - Simple types: Int, Float, Bool, String, Unit
+   * - Generic types: Array<Float, 2>, List<Int>
+   * - Function types: (Int, Int) -> Float
+   * - Record types: { x: Int, y: Float }, { x: Int, .. }
+   * - Optional types: Int?, Array<Float, 2>?
+   */
+  parseTypeAnnotation() {
+    const location = this.createLocation();
+
+    // Check for literal type: "on" or 42 or "on" | "off"
+    if (this.check(TokenType.STRING) || this.check(TokenType.NUMBER) ||
+        (this.check(TokenType.MINUS) && this.checkAhead(TokenType.NUMBER, 1))) {
+      return this.parseLiteralTypeOrUnion(location);
+    }
+
+    // Check for function type: (T1, T2) -> R
+    if (this.check(TokenType.LPAREN)) {
+      return this.parseFunctionType(location);
+    }
+
+    // Check for record type: { x: Int, y: Float }
+    if (this.check(TokenType.LBRACE)) {
+      return this.parseRecordType(location);
+    }
+
+    // Simple or generic type: Int, Array<Float, 2>, List<Int>
+    const typeName = this.consume(
+      TokenType.IDENTIFIER,
+      "Expected type name"
+    ).value;
+
+    let typeAnnotation;
+
+    // Check for generic parameters: <T, R>
+    if (this.match(TokenType.LT)) {
+      const params = this.parseGenericParams();
+      this.consume(TokenType.GT, "Expected '>' after generic parameters");
+      typeAnnotation = new TypeAnnotation(
+        "generic",
+        { name: typeName, params },
+        location
+      );
+    } else {
+      typeAnnotation = new TypeAnnotation(
+        "simple",
+        { name: typeName },
+        location
+      );
+    }
+
+    // Check for optional marker: ?
+    if (this.match(TokenType.QUESTION)) {
+      typeAnnotation.isOptional = true;
+    }
+
+    // Check for promotion syntax: Type | converter(param) | converter2(param) | ...
+    if (this.match(TokenType.PIPE)) {
+      return this.parsePromotionChain(typeAnnotation, location);
+    }
+
+    return typeAnnotation;
+  }
+
+  /**
+   * Parse a literal type or literal union type.
+   * Examples: "on", 42, -5, "on" | "off", 0 | 1 | 2
+   */
+  parseLiteralTypeOrUnion(location) {
+    const firstLiteral = this.parseLiteralValue();
+    const primitiveKind = typeof firstLiteral === 'string' ? 'string' : 'num';
+    const values = [firstLiteral];
+
+    // Check for more | literal patterns
+    while (this.check(TokenType.PIPE)) {
+      // Peek ahead to see if this is a literal or a converter (identifier + lparen)
+      // Literal union: "on" | "off"
+      // Converter would be: Type | converter(param) - but we already parsed the first literal
+      const nextIsLiteral = this.checkAhead(TokenType.STRING, 1) ||
+                            this.checkAhead(TokenType.NUMBER, 1) ||
+                            (this.checkAhead(TokenType.MINUS, 1) && this.checkAhead(TokenType.NUMBER, 2));
+
+      if (!nextIsLiteral) {
+        break; // Not a literal, stop here
+      }
+
+      this.advance(); // consume the PIPE
+      const nextLiteral = this.parseLiteralValue();
+      const nextKind = typeof nextLiteral === 'string' ? 'string' : 'num';
+
+      if (nextKind !== primitiveKind) {
+        throw this._parseError(
+          `Literal union values must all be the same type (got ${primitiveKind} and ${nextKind})`
+        );
+      }
+      values.push(nextLiteral);
+    }
+
+    if (values.length === 1) {
+      return new TypeAnnotation("literal", {
+        value: firstLiteral,
+        primitiveKind: primitiveKind
+      }, location);
+    }
+
+    return new TypeAnnotation("literalUnion", {
+      values: values,
+      primitiveKind: primitiveKind
+    }, location);
+  }
+
+  /**
+   * Parse a single literal value (string or number, possibly negative).
+   */
+  parseLiteralValue() {
+    // Handle negative numbers
+    if (this.match(TokenType.MINUS)) {
+      const num = this.consume(TokenType.NUMBER, "Expected number after '-'").value;
+      return -num;
+    }
+
+    if (this.check(TokenType.STRING)) {
+      return this.advance().value;
+    }
+
+    if (this.check(TokenType.NUMBER)) {
+      return this.advance().value;
+    }
+
+    throw this._parseError("Expected string or number literal in type position");
+  }
+
+  /**
+   * Parse one or more converters after Type |
+   * Examples: Point | from_num(p), Point | from_num(p) | from_arr(p)
+   */
+  parsePromotionChain(targetType, location) {
+    const converters = [];
+    let firstParamRef = null;
+
+    do {
+      const converterName = this.consume(
+        TokenType.IDENTIFIER,
+        "Expected converter function name after '|'"
+      ).value;
+      this.consume(TokenType.LPAREN, "Expected '(' after converter function name");
+      const paramRef = this.consume(
+        TokenType.IDENTIFIER,
+        "Expected parameter reference in converter call"
+      ).value;
+      this.consume(TokenType.RPAREN, "Expected ')' after parameter reference");
+
+      // Validate all converters reference the same parameter
+      if (firstParamRef === null) {
+        firstParamRef = paramRef;
+      } else if (paramRef !== firstParamRef) {
+        throw this._parseError(
+          `All converters must reference the same parameter '${firstParamRef}', got '${paramRef}'`
+        );
+      }
+
+      converters.push({ funcName: converterName, paramRef: paramRef });
+    } while (this.match(TokenType.PIPE));
+
+    // Use the new multi-converter format
+    return new TypeAnnotation(
+      "promoted",
+      {
+        targetType: targetType,
+        converters: converters,
+        paramRef: firstParamRef
+      },
+      location
+    );
+  }
+
+  /**
+   * Check if the token at offset ahead matches the given type.
+   */
+  checkAhead(tokenType, offset) {
+    const index = this.current + offset;
+    if (index >= this.tokens.length) return false;
+    return this.tokens[index].type === tokenType;
+  }
+
+  /**
+   * Parse generic type parameters: <T, 2>, <Int>, etc.
+   * Handles both type parameters and numeric literals (for Array rank)
+   */
+  parseGenericParams() {
+    const params = [];
+
+    do {
+      // Check for number (like rank in Array<Float, 2>)
+      if (this.check(TokenType.NUMBER)) {
+        params.push(this.advance().value);
+      } else {
+        // It's a type
+        params.push(this.parseTypeAnnotation());
+      }
+    } while (this.match(TokenType.COMMA));
+
+    return params;
+  }
+
+  /**
+   * Parse function type: (Int, Int) -> Float
+   */
+  parseFunctionType(location) {
+    this.consume(TokenType.LPAREN, "Expected '(' for function type");
+
+    const paramTypes = [];
+    if (!this.check(TokenType.RPAREN)) {
+      do {
+        paramTypes.push(this.parseTypeAnnotation());
+      } while (this.match(TokenType.COMMA));
+    }
+
+    this.consume(TokenType.RPAREN, "Expected ')' after function parameters");
+    this.consume(TokenType.ARROW, "Expected '->' in function type");
+
+    const returnType = this.parseTypeAnnotation();
+
+    const typeAnnotation = new TypeAnnotation(
+      "function",
+      { paramTypes, returnType },
+      location
+    );
+
+    // Check for optional marker: ?
+    if (this.match(TokenType.QUESTION)) {
+      typeAnnotation.isOptional = true;
+    }
+
+    return typeAnnotation;
+  }
+
+  /**
+   * Parse record type: { x: Int, y: Float }
+   * Or dictionary type: {[string]: num}
+   * Note: Open records ({ x: Int, .. }) are no longer supported
+   */
+  parseRecordType(location) {
+    this.consume(TokenType.LBRACE, "Expected '{' for record type");
+
+    // Check for dictionary type: {[K]: V}
+    if (this.match(TokenType.LBRACKET)) {
+      const keyType = this.parseTypeAnnotation();
+      this.consume(TokenType.RBRACKET, "Expected ']' after key type");
+      this.consume(TokenType.COLON, "Expected ':' after key type");
+      const valueType = this.parseTypeAnnotation();
+      this.consume(TokenType.RBRACE, "Expected '}' after dictionary type");
+
+      const typeAnnotation = new TypeAnnotation(
+        "dictionary",
+        { keyType, valueType },
+        location
+      );
+
+      // Check for optional marker: ?
+      if (this.match(TokenType.QUESTION)) {
+        typeAnnotation.isOptional = true;
+      }
+
+      return typeAnnotation;
+    }
+
+    const fields = [];
+
+    if (!this.check(TokenType.RBRACE)) {
+      do {
+        // Check for deprecated open record marker: ..
+        if (this.check(TokenType.RANGE)) {
+          throw this._parseError(
+            "Open records (.. syntax) are no longer supported. All records must have exact fields.",
+            this.peek()
+          );
+        }
+
+        const fieldName = this.consume(
+          TokenType.IDENTIFIER,
+          "Expected field name"
+        ).value;
+        this.consume(TokenType.COLON, "Expected ':' after field name");
+        const fieldType = this.parseTypeAnnotation();
+
+        fields.push({ name: fieldName, type: fieldType });
+      } while (this.match(TokenType.COMMA));
+    }
+
+    this.consume(TokenType.RBRACE, "Expected '}' after record type");
+
+    const typeAnnotation = new TypeAnnotation(
+      "record",
+      { fields, open: false },
+      location
+    );
+
+    // Check for optional marker: ?
+    if (this.match(TokenType.QUESTION)) {
+      typeAnnotation.isOptional = true;
+    }
+
+    return typeAnnotation;
+  }
+
+  /**
+   * Validate and normalize loop drivers
+   */
+  validateAndNormalizeLoopDrivers(loopExpr) {
+    if (loopExpr.drivers) {
+      const forDrivers = loopExpr.drivers.filter((d) => d instanceof ForDriver);
+      const patterns = forDrivers.map((d) => d.pattern);
+      const seen = new Set();
+
+      for (const pattern of patterns) {
+        if (seen.has(pattern)) {
+          throw this._parseError(
+            `Duplicate iterator variable name '${pattern}'`,
+            { line: loopExpr.location.line, column: loopExpr.location.column }
+          );
+        }
+        seen.add(pattern);
+      }
+
+      if (loopExpr.variables) {
+        const stateVarNames = new Set(loopExpr.variables.map((v) => v.name));
+
+        for (const driver of forDrivers) {
+          if (stateVarNames.has(driver.pattern)) {
+            throw this._parseError(
+              `Iterator variable '${driver.pattern}' conflicts with loop state variable`,
+              { line: loopExpr.location.line, column: loopExpr.location.column }
+            );
+          }
+        }
+      }
+
+      for (const driver of loopExpr.drivers) {
+        if (driver instanceof ForDriver) {
+          if (!driver.iterable) {
+            throw this._parseError(
+              `For driver must have an iterable expression`,
+              { line: driver.location.line, column: driver.location.column }
+            );
+          }
+        } else if (driver instanceof WhileDriver) {
+          if (!driver.condition) {
+            throw this._parseError(
+              `While driver must have a condition expression`,
+              { line: driver.location.line, column: driver.location.column }
+            );
+          }
+        }
+      }
+    }
+
+    return loopExpr;
+  }
+
+  // Helper methods
+
+  match(...types) {
+    for (const type of types) {
+      if (this.check(type)) {
+        this.advance();
+        return true;
+      }
+    }
+    return false;
+  }
+
+  check(type) {
+    if (this.isAtEnd()) return false;
+    return this.peek().type === type;
+  }
+
+  /**
+   * Match a contextual keyword (an identifier with a specific value).
+   * Used for 'as' which is not a reserved keyword but acts as one in alias positions.
+   */
+  matchContextualKeyword(value) {
+    if (this.check(TokenType.IDENTIFIER) && this.peek().value === value) {
+      this.advance();
+      return true;
+    }
+    return false;
+  }
+
+  checkAhead(type, offset) {
+    const pos = this.pos + offset;
+    if (pos >= this.tokens.length) return false;
+    return this.tokens[pos].type === type;
+  }
+
+  consume(type, message) {
+    if (this.check(type)) return this.advance();
+
+    const token = this.peek();
+    throw this._parseError(`${message}, got ${token.type}`, token);
+  }
+
+  advance() {
+    if (!this.isAtEnd()) this.pos++;
+    return this.previous();
+  }
+
+  isAtEnd() {
+    return this.peek().type === TokenType.EOF;
+  }
+
+  peek() {
+    return this.tokens[this.pos];
+  }
+
+  previous() {
+    return this.tokens[this.pos - 1];
+  }
+
+  createLocation() {
+    const token = this.peek();
+    return createLocation(token.line, token.column, this.filename);
+  }
+}
+
+/**
+ * Build AST from source code
+ */
+export function buildASTFromSource(source, filename = "<stdin>") {
+  const lexer = new Lexer(source, filename);
+  const tokens = lexer.tokenize();
+  const parser = new Parser(tokens, filename);
+  return parser.parse();
+}
+
+/**
+ * Build AST from tokens
+ */
+export function buildASTFromTokens(tokens, filename = "<stdin>") {
+  const parser = new Parser(tokens, filename);
+  return parser.parse();
+}
+
+export const parse = buildASTFromSource;