@vibe-lang/runtime 0.2.9 → 0.2.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibe-lang/runtime",
-  "version": "0.2.9",
+  "version": "0.2.10",
   "description": "Vibe language runtime and CLI",
   "main": "src/index.ts",
   "type": "module",

package/src/ast/index.ts

@@ -64,6 +64,7 @@ export type Statement =
   | ToolDeclaration
   | ReturnStatement
   | BreakStatement
+  | ThrowStatement
   | IfStatement
   | ForInStatement
   | WhileStatement
@@ -181,6 +182,11 @@ export interface BreakStatement extends BaseNode {
   type: 'BreakStatement';
 }
 
+export interface ThrowStatement extends BaseNode {
+  type: 'ThrowStatement';
+  message: Expression;  // The error message expression
+}
+
 export interface IfStatement extends BaseNode {
   type: 'IfStatement';
   condition: Expression;

package/src/lexer/index.ts

@@ -46,6 +46,7 @@ export const Function = token({ name: 'Function', pattern: /function/, longer_al
 export const Tool = token({ name: 'Tool', pattern: /tool/, longer_alt: Identifier });
 export const Return = token({ name: 'Return', pattern: /return/, longer_alt: Identifier });
 export const Break = token({ name: 'Break', pattern: /break/, longer_alt: Identifier });
+export const Throw = token({ name: 'Throw', pattern: /throw/, longer_alt: Identifier });
 export const If = token({ name: 'If', pattern: /if/, longer_alt: Identifier });
 export const Else = token({ name: 'Else', pattern: /else/, longer_alt: Identifier });
 export const While = token({ name: 'While', pattern: /while/, longer_alt: Identifier });
@@ -255,6 +256,7 @@ export const allTokens = [
   Tool,
   Return,
   Break,
+  Throw,
   If,
   Else,
   While,

package/src/parser/index.ts

@@ -38,6 +38,7 @@ class VibeParser extends CstParser {
       { ALT: () => this.SUBRULE(this.toolDeclaration) },
       { ALT: () => this.SUBRULE(this.returnStatement) },
       { ALT: () => this.SUBRULE(this.breakStatement) },
+      { ALT: () => this.SUBRULE(this.throwStatement) },
       { ALT: () => this.SUBRULE(this.ifStatement) },
       { ALT: () => this.SUBRULE(this.forInStatement) },
       { ALT: () => this.SUBRULE(this.whileStatement) },
@@ -444,6 +445,11 @@ class VibeParser extends CstParser {
     this.CONSUME(T.Break);
   });
 
+  private throwStatement = this.RULE('throwStatement', () => {
+    this.CONSUME(T.Throw);
+    this.SUBRULE(this.expression);  // Error message is required
+  });
+
   private ifStatement = this.RULE('ifStatement', () => {
     this.CONSUME(T.If);
     this.SUBRULE(this.expression);

package/src/parser/parse.ts

@@ -4,7 +4,7 @@ import { vibeAstVisitor } from './visitor';
 import { setCurrentFile } from './visitor/helpers';
 import { ParserError } from '../errors';
 import type { Program } from '../ast';
-import type { IRecognitionException } from 'chevrotain';
+import type { IRecognitionException, IToken } from 'chevrotain';
 
 export interface ParseOptions {
   /** File path to include in source locations (for error reporting) */
@@ -20,6 +20,18 @@ function improveErrorMessage(error: IRecognitionException): string {
   const currentToken = error.token;
   const message = error.message;
 
+  // Reserved word used where identifier expected
+  // Detected: message mentions "Identifier" and current token is a keyword/type token (not Identifier)
+  if (message.includes('Identifier') && currentToken?.image && currentToken?.tokenType?.name) {
+    const tokenTypeName = currentToken.tokenType.name;
+    // If parser expected Identifier but got a keyword/type token, it's a reserved word
+    if (tokenTypeName !== 'Identifier') {
+      const isType = tokenTypeName.endsWith('Type');
+      const kind = isType ? 'reserved type name' : 'reserved keyword';
+      return `Invalid identifier '${currentToken.image}' - '${currentToken.image}' is a ${kind}`;
+    }
+  }
+
   // Missing type annotation for function/tool parameter
   // Detected: in "parameter" or "toolParameter" rule, expected Colon, previous token is Identifier
   if (
@@ -53,6 +65,103 @@ function improveErrorMessage(error: IRecognitionException): string {
   return message;
 }
 
+interface DelimiterInfo {
+  type: 'brace' | 'paren' | 'bracket';
+  token: IToken;
+  line: number;
+  column: number;
+}
+
+/**
+ * Check for unclosed or mismatched delimiters before parsing.
+ * Returns a ParserError if there's a delimiter issue, null otherwise.
+ */
+function checkDelimiters(tokens: IToken[], source: string, file?: string): ParserError | null {
+  const stack: DelimiterInfo[] = [];
+
+  const delimiterPairs: Record<string, { open: 'brace' | 'paren' | 'bracket'; close: 'brace' | 'paren' | 'bracket' }> = {
+    LBrace: { open: 'brace', close: 'brace' },
+    RBrace: { open: 'brace', close: 'brace' },
+    LParen: { open: 'paren', close: 'paren' },
+    RParen: { open: 'paren', close: 'paren' },
+    LBracket: { open: 'bracket', close: 'bracket' },
+    RBracket: { open: 'bracket', close: 'bracket' },
+  };
+
+  const delimiterNames: Record<string, string> = {
+    brace: 'brace',
+    paren: 'parenthesis',
+    bracket: 'bracket',
+  };
+
+  const openingChars: Record<string, string> = {
+    brace: '{',
+    paren: '(',
+    bracket: '[',
+  };
+
+  const closingChars: Record<string, string> = {
+    brace: '}',
+    paren: ')',
+    bracket: ']',
+  };
+
+  for (const token of tokens) {
+    const tokenName = token.tokenType.name;
+
+    // Opening delimiters
+    if (tokenName === 'LBrace' || tokenName === 'LParen' || tokenName === 'LBracket') {
+      const type = delimiterPairs[tokenName].open;
+      stack.push({
+        type,
+        token,
+        line: token.startLine ?? 1,
+        column: token.startColumn ?? 1,
+      });
+    }
+    // Closing delimiters
+    else if (tokenName === 'RBrace' || tokenName === 'RParen' || tokenName === 'RBracket') {
+      const expectedType = delimiterPairs[tokenName].close;
+
+      if (stack.length === 0) {
+        // Unmatched closing delimiter
+        return new ParserError(
+          `Unmatched closing ${delimiterNames[expectedType]} '${closingChars[expectedType]}'`,
+          token.image,
+          { line: token.startLine ?? 1, column: token.startColumn ?? 1, file },
+          source
+        );
+      }
+
+      const top = stack.pop()!;
+      if (top.type !== expectedType) {
+        // Mismatched delimiter - report at the closing delimiter but mention the opening
+        return new ParserError(
+          `Mismatched delimiters: expected closing ${delimiterNames[top.type]} '${closingChars[top.type]}' to match '${openingChars[top.type]}' at line ${top.line}, but found '${closingChars[expectedType]}'`,
+          token.image,
+          { line: token.startLine ?? 1, column: token.startColumn ?? 1, file },
+          source
+        );
+      }
+    }
+  }
+
+  // Check for unclosed delimiters
+  if (stack.length > 0) {
+    // Report the first unclosed delimiter (deepest nesting level that's unclosed)
+    // We want to report the innermost unclosed one, which is the last on the stack
+    const unclosed = stack[stack.length - 1];
+    return new ParserError(
+      `Unclosed ${delimiterNames[unclosed.type]} '${openingChars[unclosed.type]}' - missing '${closingChars[unclosed.type]}'`,
+      openingChars[unclosed.type],
+      { line: unclosed.line, column: unclosed.column, file },
+      source
+    );
+  }
+
+  return null;
+}
+
 /**
  * Parse a Vibe source code string into an AST
  */
@@ -63,6 +172,13 @@ export function parse(source: string, options?: ParseOptions): Program {
   // Tokenize
   const tokens = tokenize(source);
 
+  // Check for unclosed/mismatched delimiters first
+  // This provides better error messages than the parser for delimiter issues
+  const delimiterError = checkDelimiters(tokens, source, options?.file);
+  if (delimiterError) {
+    throw delimiterError;
+  }
+
   // Parse to CST
   vibeParser.input = tokens;
   const cst = vibeParser.program();

package/src/parser/test/errors/model-declaration.test.ts

@@ -133,7 +133,18 @@ model myModel = {
   name: "test"
   apiKey: "key"
 }
-`)).toThrow();
+`)).toThrow(/[Mm]issing comma/);
+  });
+
+  test('export model missing comma separator', () => {
+    expect(() => parse(`
+export model gemini3Flash = {
+  name: 'gemini-flash-3',
+  provider: 'google',
+  apiKey: env('GOOGLE_API_KEY')
+  url: 'https://api.google.com/v1',
+}
+`)).toThrow(/[Mm]issing comma/);
   });
 
   test('properties with double comma', () => {

package/src/parser/test/errors/unclosed-delimiters.test.ts

@@ -1,80 +1,175 @@
 import { describe, expect, test } from 'bun:test';
 import { parse } from '../../parse';
+import { ParserError } from '../../../errors';
 
 describe('Syntax Errors - Unclosed Delimiters', () => {
   // ============================================================================
-  // Unclosed braces
+  // Unclosed braces - with location verification
   // ============================================================================
 
-  test('unclosed block statement', () => {
-    expect(() => parse(`
+  test('unclosed block statement reports location of opening brace', () => {
+    try {
+      parse(`
 {
   let x = "hello"
-`)).toThrow();
+`);
+      expect.unreachable('Should have thrown');
+    } catch (e) {
+      expect(e).toBeInstanceOf(ParserError);
+      const err = e as ParserError;
+      expect(err.message).toContain("Unclosed brace '{'");
+      expect(err.location?.line).toBe(2); // Line where { is
+      expect(err.location?.column).toBe(1);
+    }
   });
 
-  test('unclosed function body', () => {
-    expect(() => parse(`
+  test('unclosed function body reports location of opening brace', () => {
+    try {
+      parse(`
 function foo() {
   return "hello"
-`)).toThrow();
+`);
+      expect.unreachable('Should have thrown');
+    } catch (e) {
+      expect(e).toBeInstanceOf(ParserError);
+      const err = e as ParserError;
+      expect(err.message).toContain("Unclosed brace '{'");
+      expect(err.location?.line).toBe(2); // Line where function { is
+      expect(err.location?.column).toBe(16); // Column where { is
+    }
   });
 
-  test('unclosed if block', () => {
-    expect(() => parse(`
+  test('unclosed if block reports location of opening brace', () => {
+    try {
+      parse(`
 if true {
   let x = "yes"
-`)).toThrow();
+`);
+      expect.unreachable('Should have thrown');
+    } catch (e) {
+      expect(e).toBeInstanceOf(ParserError);
+      const err = e as ParserError;
+      expect(err.message).toContain("Unclosed brace '{'");
+      expect(err.location?.line).toBe(2);
+    }
   });
 
-  test('unclosed else block', () => {
-    expect(() => parse(`
+  test('unclosed else block reports location of opening brace', () => {
+    try {
+      parse(`
 if true {
   let x = "yes"
 } else {
   let y = "no"
-`)).toThrow();
+`);
+      expect.unreachable('Should have thrown');
+    } catch (e) {
+      expect(e).toBeInstanceOf(ParserError);
+      const err = e as ParserError;
+      expect(err.message).toContain("Unclosed brace '{'");
+      expect(err.location?.line).toBe(4); // Line where else { is
+    }
   });
 
-  test('nested unclosed braces', () => {
-    expect(() => parse(`
+  test('nested unclosed braces reports innermost unclosed', () => {
+    try {
+      parse(`
 function outer() {
   if true {
     let x = "nested"
 }
-`)).toThrow();
+`);
+      expect.unreachable('Should have thrown');
+    } catch (e) {
+      expect(e).toBeInstanceOf(ParserError);
+      const err = e as ParserError;
+      // The innermost unclosed brace is the 'if' block's brace
+      // But actually the outer function brace is unclosed since only one } appears
+      expect(err.message).toContain("Unclosed brace '{'");
+      expect(err.location?.line).toBe(2); // The function's { is unclosed
+    }
   });
 
   // ============================================================================
-  // Unclosed parentheses
+  // Unclosed parentheses - with location verification
   // ============================================================================
 
-  test('unclosed function call', () => {
-    expect(() => parse(`
+  test('unclosed function call reports location of opening paren', () => {
+    try {
+      parse(`
 foo("hello"
-`)).toThrow();
+`);
+      expect.unreachable('Should have thrown');
+    } catch (e) {
+      expect(e).toBeInstanceOf(ParserError);
+      const err = e as ParserError;
+      expect(err.message).toContain("Unclosed parenthesis '('");
+      expect(err.location?.line).toBe(2); // Line where ( is
+    }
   });
 
-  test('unclosed function params', () => {
-    expect(() => parse(`
+  test('unclosed function params reports location of opening paren', () => {
+    try {
+      parse(`
 function greet(name, age
-`)).toThrow();
+`);
+      expect.unreachable('Should have thrown');
+    } catch (e) {
+      expect(e).toBeInstanceOf(ParserError);
+      const err = e as ParserError;
+      expect(err.message).toContain("Unclosed parenthesis '('");
+      expect(err.location?.line).toBe(2);
+    }
   });
 
-  test('unclosed grouped expression', () => {
-    expect(() => parse(`
+  test('unclosed grouped expression reports location', () => {
+    try {
+      parse(`
 let x = ("hello"
-`)).toThrow();
+`);
+      expect.unreachable('Should have thrown');
+    } catch (e) {
+      expect(e).toBeInstanceOf(ParserError);
+      const err = e as ParserError;
+      expect(err.message).toContain("Unclosed parenthesis '('");
+      expect(err.location?.line).toBe(2);
+    }
   });
 
-  test('nested unclosed parens in call', () => {
-    expect(() => parse(`
+  test('nested unclosed parens reports innermost', () => {
+    try {
+      parse(`
 outer(inner("deep"
-`)).toThrow();
+`);
+      expect.unreachable('Should have thrown');
+    } catch (e) {
+      expect(e).toBeInstanceOf(ParserError);
+      const err = e as ParserError;
+      // inner( is the innermost unclosed
+      expect(err.message).toContain("Unclosed parenthesis '('");
+    }
+  });
+
+  // ============================================================================
+  // Unclosed brackets - with location verification
+  // ============================================================================
+
+  test('unclosed array literal reports location', () => {
+    try {
+      parse(`
+let arr = [1, 2, 3
+`);
+      expect.unreachable('Should have thrown');
+    } catch (e) {
+      expect(e).toBeInstanceOf(ParserError);
+      const err = e as ParserError;
+      expect(err.message).toContain("Unclosed bracket '['");
+      expect(err.location?.line).toBe(2);
+    }
   });
 
   // ============================================================================
-  // Unclosed strings
+  // Unclosed strings (handled by lexer, not delimiter checker)
   // ============================================================================
 
   test('unclosed double quote string', () => {
@@ -102,15 +197,86 @@ let x = vibe "what is 2+2?
   });
 
   // ============================================================================
-  // Mixed unclosed delimiters
+  // Mismatched delimiters
   // ============================================================================
 
-  test('unclosed brace and paren', () => {
-    expect(() => parse(`
+  test('mismatched closing brace vs paren', () => {
+    try {
+      parse(`
 function test() {
   foo(
 }
-`)).toThrow();
+`);
+      expect.unreachable('Should have thrown');
+    } catch (e) {
+      expect(e).toBeInstanceOf(ParserError);
+      const err = e as ParserError;
+      expect(err.message).toContain("Mismatched delimiters");
+      expect(err.message).toContain("expected closing parenthesis");
+    }
+  });
+
+  test('unmatched closing brace', () => {
+    try {
+      parse(`
+let x = 1
+}
+`);
+      expect.unreachable('Should have thrown');
+    } catch (e) {
+      expect(e).toBeInstanceOf(ParserError);
+      const err = e as ParserError;
+      expect(err.message).toContain("Unmatched closing brace");
+      expect(err.location?.line).toBe(3);
+    }
+  });
+
+  test('unmatched closing paren', () => {
+    try {
+      parse(`
+let x = 1)
+`);
+      expect.unreachable('Should have thrown');
+    } catch (e) {
+      expect(e).toBeInstanceOf(ParserError);
+      const err = e as ParserError;
+      expect(err.message).toContain("Unmatched closing parenthesis");
+    }
+  });
+
+  test('unmatched closing bracket', () => {
+    try {
+      parse(`
+let x = 1]
+`);
+      expect.unreachable('Should have thrown');
+    } catch (e) {
+      expect(e).toBeInstanceOf(ParserError);
+      const err = e as ParserError;
+      expect(err.message).toContain("Unmatched closing bracket");
+    }
+  });
+
+  // ============================================================================
+  // While loop specific (from user's example)
+  // ============================================================================
+
+  test('unclosed while loop reports location of opening brace', () => {
+    try {
+      parse(`
+let keepGoing = true
+let count = 0
+
+while keepGoing {
+   count = count + 1
+`);
+      expect.unreachable('Should have thrown');
+    } catch (e) {
+      expect(e).toBeInstanceOf(ParserError);
+      const err = e as ParserError;
+      expect(err.message).toContain("Unclosed brace '{'");
+      expect(err.location?.line).toBe(5); // Line where while { is
+    }
   });
 
   test('unclosed string inside unclosed block', () => {

package/src/parser/test/errors/unexpected-tokens.test.ts

@@ -31,7 +31,21 @@ function() {
 function let() {
   return "hello"
 }
-`)).toThrow();
+`)).toThrow(/reserved keyword/);
+  });
+
+  test('function with type name as name', () => {
+    expect(() => parse(`
+function text(x: text, y: number): text {
+  return x + y
+}
+`)).toThrow(/reserved type name/);
+  });
+
+  test('variable with keyword as name', () => {
+    expect(() => parse(`
+let return = 5
+`)).toThrow(/reserved keyword/);
   });
 
   // ============================================================================

package/src/parser/visitor.ts

@@ -61,6 +61,7 @@ class VibeAstVisitor extends BaseVibeVisitor {
     if (ctx.toolDeclaration) return this.visit(ctx.toolDeclaration);
     if (ctx.returnStatement) return this.visit(ctx.returnStatement);
     if (ctx.breakStatement) return this.visit(ctx.breakStatement);
+    if (ctx.throwStatement) return this.visit(ctx.throwStatement);
     if (ctx.ifStatement) return this.visit(ctx.ifStatement);
     if (ctx.forInStatement) return this.visit(ctx.forInStatement);
     if (ctx.whileStatement) return this.visit(ctx.whileStatement);
@@ -409,6 +410,14 @@ class VibeAstVisitor extends BaseVibeVisitor {
     return { type: 'BreakStatement', location: tokenLocation(ctx.Break[0]) };
   }
 
+  throwStatement(ctx: { Throw: IToken[]; expression: CstNode[] }): AST.ThrowStatement {
+    return {
+      type: 'ThrowStatement',
+      message: this.visit(ctx.expression),
+      location: tokenLocation(ctx.Throw[0]),
+    };
+  }
+
   ifStatement(ctx: { If: IToken[]; expression: CstNode[]; blockStatement: CstNode[]; ifStatement?: CstNode[] }): AST.IfStatement {
     const alternate = ctx.ifStatement ? this.visit(ctx.ifStatement) : ctx.blockStatement.length > 1 ? this.visit(ctx.blockStatement[1]) : null;
     return { type: 'IfStatement', condition: this.visit(ctx.expression), consequent: this.visit(ctx.blockStatement[0]), alternate, location: tokenLocation(ctx.If[0]) };

package/src/runtime/exec/statements.ts

@@ -3,7 +3,7 @@
 import * as AST from '../../ast';
 import type { SourceLocation } from '../../errors';
 import type { RuntimeState, VibeValue } from '../types';
-import { createVibeValue, resolveValue, isVibeValue } from '../types';
+import { createVibeValue, createVibeError, resolveValue, isVibeValue } from '../types';
 import { currentFrame } from '../state';
 import { requireBoolean, validateAndCoerce } from '../validation';
 import { execDeclareVar } from './variables';
@@ -441,6 +441,53 @@ export function execReturnValue(state: RuntimeState): RuntimeState {
   return { ...state, callStack: newCallStack, instructionStack: newInstructionStack, lastResult: validatedReturnValue };
 }
 
+/**
+ * Throw statement - evaluate message and throw error.
+ */
+export function execThrowStatement(state: RuntimeState, stmt: AST.ThrowStatement): RuntimeState {
+  return {
+    ...state,
+    instructionStack: [
+      { op: 'exec_expression', expr: stmt.message, location: stmt.message.location },
+      { op: 'throw_error', location: stmt.location },
+      ...state.instructionStack,
+    ],
+  };
+}
+
+/**
+ * Throw error - create error value and unwind to function boundary.
+ * Uses lastResult as the error message.
+ */
+export function execThrowError(state: RuntimeState, location: SourceLocation): RuntimeState {
+  // Get the error message from lastResult
+  const messageValue = resolveValue(state.lastResult);
+  const message = typeof messageValue === 'string' ? messageValue : String(messageValue);
+
+  // Create error VibeValue
+  const errorValue = createVibeError(message, location);
+
+  // Check if we're at top level (only main frame) or in a function
+  const isTopLevel = state.callStack.length === 1;
+
+  if (isTopLevel) {
+    // At top level - complete with error but keep the frame for variable access
+    return { ...state, status: 'completed', instructionStack: [], lastResult: errorValue };
+  }
+
+  // In a function - unwind like return: pop frame and skip to after pop_frame instruction
+  const newCallStack = state.callStack.slice(0, -1);
+
+  // Find and skip past the pop_frame instruction
+  let newInstructionStack = state.instructionStack;
+  const popFrameIndex = newInstructionStack.findIndex((i) => i.op === 'pop_frame');
+  if (popFrameIndex !== -1) {
+    newInstructionStack = newInstructionStack.slice(popFrameIndex + 1);
+  }
+
+  return { ...state, callStack: newCallStack, instructionStack: newInstructionStack, lastResult: errorValue };
+}
+
 /**
  * Execute statements at index - sequential statement execution.
  */
@@ -598,6 +645,9 @@ export function execStatement(state: RuntimeState, stmt: AST.Statement): Runtime
     case 'BreakStatement':
       return execBreakStatement(state, stmt);
 
+    case 'ThrowStatement':
+      return execThrowStatement(state, stmt);
+
     default:
       throw new Error(`Unknown statement type: ${(stmt as AST.Statement).type}`);
   }

package/src/runtime/index.ts

@@ -185,13 +185,12 @@ export class Runtime {
     return resolveValue(variable?.value);
   }
 
-  // Get raw value including VibeValue wrapper if present
+  // Get raw VibeValue wrapper (for testing error state, toolCalls, etc.)
   getRawValue(name: string): unknown {
     const frame = this.state.callStack[this.state.callStack.length - 1];
     if (!frame) return undefined;
 
-    const variable = frame.locals[name];
-    return variable?.value;
+    return frame.locals[name];
   }
 
   // Get all AI interactions (for debugging)

package/src/runtime/modules.ts

@@ -9,7 +9,7 @@ import { resolve, dirname, join } from 'path';
 
 // Map system module names to their implementation files
 const SYSTEM_MODULES: Record<string, string> = {
-  'system': join(__dirname, 'stdlib', 'index.ts'),
+  'system/utils': join(__dirname, 'stdlib', 'utils', 'index.ts'),
   'system/tools': join(__dirname, 'stdlib', 'tools', 'index.ts'),
 };