@vibe-lang/runtime 0.2.5

package/src/runtime/validation.ts

@@ -0,0 +1,160 @@
+// Type validation and coercion utilities
+
+import type { VibeType, VibeTypeRequired } from '../ast';
+import { RuntimeError, type SourceLocation } from '../errors';
+import { isVibeValue, resolveValue } from './types';
+
+// Map array types to their element types (type-safe alternative to string slicing)
+const ARRAY_ELEMENT_TYPES: Record<string, VibeTypeRequired> = {
+  'text[]': 'text',
+  'json[]': 'json',
+  'boolean[]': 'boolean',
+  'number[]': 'number',
+  'prompt[]': 'prompt',
+};
+
+/**
+ * Validates a value against a type annotation and coerces if necessary.
+ * Returns { value, inferredType } where inferredType is set when no explicit type was given.
+ */
+export function validateAndCoerce(
+  value: unknown,
+  type: VibeType,
+  varName: string,
+  location?: SourceLocation,
+  source?: 'ai' | 'user'
+): { value: unknown; inferredType: VibeType } {
+  // Resolve VibeValue unless this is a direct AI result to an UNTYPED variable
+  // (source === 'ai' means the value came directly from an AI call)
+  // For typed variables, always resolve so type validation can work on the primitive value
+  const keepVibeValueWrapper = source === 'ai' && type === null;
+  if (!keepVibeValueWrapper) {
+    value = resolveValue(value);
+  }
+
+  // null is valid for any typed variable
+  if (value === null) {
+    return { value: null, inferredType: type };
+  }
+
+  // If no type annotation, infer from JavaScript type
+  if (!type) {
+    // For VibeValue, infer type from the underlying value, not the wrapper
+    const valueToInfer = resolveValue(value);
+
+    if (typeof valueToInfer === 'string') {
+      return { value, inferredType: 'text' };
+    }
+    if (typeof valueToInfer === 'boolean') {
+      return { value, inferredType: 'boolean' };
+    }
+    if (typeof valueToInfer === 'number') {
+      return { value, inferredType: 'number' };
+    }
+    if (typeof valueToInfer === 'object' && valueToInfer !== null) {
+      return { value, inferredType: 'json' };
+    }
+    // For other types (null, undefined), no type inference
+    return { value, inferredType: null };
+  }
+
+  // Validate array types (text[], json[], boolean[], number[], prompt[])
+  const elementType = ARRAY_ELEMENT_TYPES[type];
+  if (elementType) {
+    let arrayValue = value;
+
+    // If string, try to parse as JSON array
+    if (typeof value === 'string') {
+      try {
+        arrayValue = JSON.parse(value);
+      } catch {
+        throw new RuntimeError(`Variable '${varName}': invalid JSON array string`, location);
+      }
+    }
+
+    if (!Array.isArray(arrayValue)) {
+      throw new RuntimeError(`Variable '${varName}': expected ${type} (array), got ${typeof value}`, location);
+    }
+
+    // Validate each element recursively
+    const validatedElements = arrayValue.map((elem, i) => {
+      const { value: validated } = validateAndCoerce(elem, elementType, `${varName}[${i}]`, location);
+      return validated;
+    });
+
+    return { value: validatedElements, inferredType: type };
+  }
+
+  // Validate text type - must be a string
+  if (type === 'text') {
+    if (typeof value !== 'string') {
+      throw new RuntimeError(`Variable '${varName}': expected text (string), got ${typeof value}`, location);
+    }
+    return { value, inferredType: 'text' };
+  }
+
+  // Validate json type - must be object (not array)
+  if (type === 'json') {
+    let result = value;
+
+    // If string, try to parse as JSON
+    if (typeof value === 'string') {
+      try {
+        result = JSON.parse(value);
+      } catch {
+        throw new RuntimeError(`Variable '${varName}': invalid JSON string`, location);
+      }
+    }
+
+    // Validate the result is an object (not array, not primitive)
+    if (typeof result !== 'object' || result === null) {
+      throw new RuntimeError(`Variable '${varName}': expected json (object), got ${typeof value}`, location);
+    }
+    if (Array.isArray(result)) {
+      throw new RuntimeError(`Variable '${varName}': json type expects an object, not an array. Use json[] for arrays.`, location);
+    }
+    return { value: result, inferredType: 'json' };
+  }
+
+  // Validate boolean type - must be a boolean
+  if (type === 'boolean') {
+    if (typeof value !== 'boolean') {
+      throw new RuntimeError(`Variable '${varName}': expected boolean, got ${typeof value}`, location);
+    }
+    return { value, inferredType: 'boolean' };
+  }
+
+  // Validate number type - must be a finite number
+  if (type === 'number') {
+    if (typeof value !== 'number') {
+      throw new RuntimeError(`Variable '${varName}': expected number, got ${typeof value}`, location);
+    }
+    if (!Number.isFinite(value)) {
+      throw new RuntimeError(`Variable '${varName}': number must be finite, got ${value}`, location);
+    }
+    return { value, inferredType: 'number' };
+  }
+
+  // For prompt type, accept string values as-is
+  return { value, inferredType: type };
+}
+
+/**
+ * Strict boolean check - no truthy coercion allowed.
+ * Throws if value is not a boolean.
+ */
+export function requireBoolean(value: unknown, context: string): boolean {
+  // Handle VibeValue with error - throw the error
+  if (isVibeValue(value) && value.err && value.errDetails) {
+    throw new Error(`${value.errDetails.type}: ${value.errDetails.message}`);
+  }
+
+  // Auto-unwrap VibeValue
+  const unwrapped = resolveValue(value);
+
+  if (typeof unwrapped !== 'boolean') {
+    const valueType = unwrapped === null ? 'null' : typeof unwrapped;
+    throw new Error(`TypeError: ${context} must be a boolean, got ${valueType}`);
+  }
+  return unwrapped;
+}

package/src/runtime/verbose-logger.ts

@@ -0,0 +1,459 @@
+/**
+ * Verbose Logger - JSONL logging for AI interactions, TS executions, and tool calls
+ *
+ * Outputs:
+ * - Main log: JSONL events to console and .vibe-logs/run-{timestamp}.jsonl
+ * - Context files: .vibe-logs/run-{timestamp}/do-000001.txt, etc.
+ */
+
+import { mkdirSync, writeFileSync, appendFileSync, existsSync } from 'fs';
+import { join, dirname } from 'path';
+import type {
+  LogEvent,
+  RunStartEvent,
+  RunCompleteEvent,
+  AIStartEvent,
+  AICompleteEvent,
+  ToolStartEvent,
+  ToolCompleteEvent,
+  TSStartEvent,
+  TSCompleteEvent,
+  AILogMessage,
+  TokenUsage,
+} from './types';
+
+export interface VerboseLoggerOptions {
+  logDir?: string;           // Base directory for logs (default: .vibe-logs)
+  printToConsole?: boolean;  // Print events to console (default: true)
+  writeToFile?: boolean;     // Write events to file (default: true)
+}
+
+interface AICallContext {
+  model: string;
+  modelDetails?: { name: string; provider: string; url?: string };
+  type: 'do' | 'vibe';
+  targetType: string | null;
+  messages: AILogMessage[];
+}
+
+/**
+ * VerboseLogger - Manages structured logging for Vibe runtime
+ */
+export class VerboseLogger {
+  private logDir: string;
+  private runTimestamp: string;
+  private mainLogPath: string;
+  private contextDir: string;
+  private printToConsole: boolean;
+  private writeToFile: boolean;
+
+  private seq = 0;
+  private counters = { do: 0, vibe: 0, ts: 0, tsf: 0 };
+  private events: LogEvent[] = [];
+  private startTime: number = 0;
+
+  constructor(options: VerboseLoggerOptions = {}) {
+    this.logDir = options.logDir ?? '.vibe-logs';
+    this.printToConsole = options.printToConsole ?? true;
+    this.writeToFile = options.writeToFile ?? true;
+
+    // Generate timestamp for this run
+    this.runTimestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+    this.mainLogPath = join(this.logDir, `run-${this.runTimestamp}.jsonl`);
+    this.contextDir = join(this.logDir, `run-${this.runTimestamp}`);
+  }
+
+  /**
+   * Initialize the logger (create directories)
+   */
+  private ensureDirectories(): void {
+    if (this.writeToFile) {
+      if (!existsSync(this.logDir)) {
+        mkdirSync(this.logDir, { recursive: true });
+      }
+      if (!existsSync(this.contextDir)) {
+        mkdirSync(this.contextDir, { recursive: true });
+      }
+    }
+  }
+
+  /**
+   * Generate next ID for a given type
+   */
+  private nextId(type: 'do' | 'vibe' | 'ts' | 'tsf'): string {
+    this.counters[type]++;
+    return `${type}-${String(this.counters[type]).padStart(6, '0')}`;
+  }
+
+  /**
+   * Log an event (console + file + in-memory)
+   */
+  private logEvent(event: LogEvent): void {
+    this.events.push(event);
+
+    const jsonLine = JSON.stringify(event);
+
+    if (this.printToConsole) {
+      console.log(jsonLine);
+    }
+
+    if (this.writeToFile) {
+      this.ensureDirectories();
+      appendFileSync(this.mainLogPath, jsonLine + '\n');
+    }
+  }
+
+  /**
+   * Write context file for an AI call
+   */
+  private writeContextFile(id: string, context: AICallContext): void {
+    if (!this.writeToFile) return;
+
+    this.ensureDirectories();
+
+    const lines: string[] = [
+      `=== AI Call: ${id} ===`,
+      `Model: ${context.modelDetails?.name ?? context.model} (${context.modelDetails?.provider ?? 'unknown'})`,
+      `Type: ${context.type}`,
+      `Target: ${context.targetType ?? 'text'}`,
+      `Timestamp: ${new Date().toISOString()}`,
+      '',
+      '=== MESSAGES ===',
+      '',
+    ];
+
+    for (const msg of context.messages) {
+      lines.push(`[${msg.role}]`);
+      lines.push(msg.content);
+
+      if (msg.toolCalls && msg.toolCalls.length > 0) {
+        lines.push('');
+        lines.push('Tool calls:');
+        for (const tc of msg.toolCalls) {
+          lines.push(`  - ${tc.toolName}(${JSON.stringify(tc.args)})`);
+        }
+      }
+
+      if (msg.toolResults && msg.toolResults.length > 0) {
+        lines.push('');
+        lines.push('Tool results:');
+        for (const tr of msg.toolResults) {
+          if (tr.error) {
+            lines.push(`  - Error: ${tr.error}`);
+          } else {
+            lines.push(`  - Result: ${JSON.stringify(tr.result)}`);
+          }
+        }
+      }
+
+      lines.push('');
+    }
+
+    lines.push('=== END MESSAGES ===');
+
+    const filePath = join(this.contextDir, `${id}.txt`);
+    writeFileSync(filePath, lines.join('\n'));
+  }
+
+  /**
+   * Write context file for a TS block
+   */
+  private writeTSContextFile(id: string, params: string[], paramValues: unknown[], body: string, location: { file: string; line: number }): void {
+    if (!this.writeToFile) return;
+
+    this.ensureDirectories();
+
+    const lines: string[] = [
+      `// TS Block: ${id}`,
+      `// Location: ${location.file}:${location.line}`,
+    ];
+
+    if (params.length > 0) {
+      const paramStr = params.map((p, i) => `${p} = ${JSON.stringify(paramValues[i])}`).join(', ');
+      lines.push(`// Params: ${paramStr}`);
+    }
+
+    lines.push('');
+    lines.push(body);
+
+    const filePath = join(this.contextDir, `${id}.ts`);
+    writeFileSync(filePath, lines.join('\n'));
+  }
+
+  /**
+   * Write context file for an imported TS function call
+   */
+  private writeTSFunctionContextFile(id: string, funcName: string, args: unknown[], location: { file: string; line: number }): void {
+    if (!this.writeToFile) return;
+
+    this.ensureDirectories();
+
+    const lines: string[] = [
+      `// TS Function Call: ${id}`,
+      `// Function: ${funcName}`,
+      `// Location: ${location.file}:${location.line}`,
+      '',
+      `${funcName}(`,
+    ];
+
+    for (let i = 0; i < args.length; i++) {
+      const comma = i < args.length - 1 ? ',' : '';
+      lines.push(`  ${JSON.stringify(args[i], null, 2).split('\n').join('\n  ')}${comma}`);
+    }
+
+    lines.push(')');
+
+    const filePath = join(this.contextDir, `${id}.ts`);
+    writeFileSync(filePath, lines.join('\n'));
+  }
+
+  // ============================================================================
+  // Public API
+  // ============================================================================
+
+  /**
+   * Log run start
+   */
+  start(file: string): void {
+    this.startTime = Date.now();
+
+    const event: RunStartEvent = {
+      seq: ++this.seq,
+      ts: new Date().toISOString(),
+      event: 'run_start',
+      file,
+    };
+
+    this.logEvent(event);
+  }
+
+  /**
+   * Log run completion
+   */
+  complete(status: 'completed' | 'error', error?: string): void {
+    const event: RunCompleteEvent = {
+      seq: ++this.seq,
+      ts: new Date().toISOString(),
+      event: 'run_complete',
+      durationMs: Date.now() - this.startTime,
+      status,
+      ...(error && { error }),
+    };
+
+    this.logEvent(event);
+  }
+
+  /**
+   * Log AI call start - returns the ID for this call
+   */
+  aiStart(
+    type: 'do' | 'vibe',
+    model: string,
+    prompt: string,
+    context: AICallContext
+  ): string {
+    const id = this.nextId(type);
+
+    const event: AIStartEvent = {
+      seq: ++this.seq,
+      ts: new Date().toISOString(),
+      event: 'ai_start',
+      id,
+      type,
+      model,
+      prompt: prompt.length > 100 ? prompt.slice(0, 100) + '...' : prompt,
+    };
+
+    this.logEvent(event);
+
+    // Write full context to file
+    this.writeContextFile(id, context);
+
+    return id;
+  }
+
+  /**
+   * Log AI call completion
+   */
+  aiComplete(
+    id: string,
+    durationMs: number,
+    usage?: TokenUsage,
+    toolCallCount = 0,
+    error?: string
+  ): void {
+    const event: AICompleteEvent = {
+      seq: ++this.seq,
+      ts: new Date().toISOString(),
+      event: 'ai_complete',
+      id,
+      durationMs,
+      ...(usage && { tokens: { in: usage.inputTokens, out: usage.outputTokens } }),
+      toolCalls: toolCallCount,
+      ...(error && { error }),
+    };
+
+    this.logEvent(event);
+  }
+
+  /**
+   * Log tool call start
+   */
+  toolStart(parentId: string, tool: string, args: Record<string, unknown>): void {
+    const event: ToolStartEvent = {
+      seq: ++this.seq,
+      ts: new Date().toISOString(),
+      event: 'tool_start',
+      parentId,
+      tool,
+      args,
+    };
+
+    this.logEvent(event);
+  }
+
+  /**
+   * Log tool call completion
+   */
+  toolComplete(
+    parentId: string,
+    tool: string,
+    durationMs: number,
+    success: boolean,
+    error?: string
+  ): void {
+    const event: ToolCompleteEvent = {
+      seq: ++this.seq,
+      ts: new Date().toISOString(),
+      event: 'tool_complete',
+      parentId,
+      tool,
+      durationMs,
+      success,
+      ...(error && { error }),
+    };
+
+    this.logEvent(event);
+  }
+
+  /**
+   * Log TS block start - returns the ID
+   */
+  tsBlockStart(
+    params: string[],
+    paramValues: unknown[],
+    body: string,
+    location: { file: string; line: number }
+  ): string {
+    const id = this.nextId('ts');
+
+    const event: TSStartEvent = {
+      seq: ++this.seq,
+      ts: new Date().toISOString(),
+      event: 'ts_start',
+      id,
+      tsType: 'block',
+      params,
+      location,
+    };
+
+    this.logEvent(event);
+
+    // Write TS code to context file
+    this.writeTSContextFile(id, params, paramValues, body, location);
+
+    return id;
+  }
+
+  /**
+   * Log imported TS function start - returns the ID
+   */
+  tsFunctionStart(
+    funcName: string,
+    args: unknown[],
+    location: { file: string; line: number }
+  ): string {
+    const id = this.nextId('tsf');
+
+    const event: TSStartEvent = {
+      seq: ++this.seq,
+      ts: new Date().toISOString(),
+      event: 'ts_start',
+      id,
+      tsType: 'function',
+      name: funcName,
+      params: [],  // We don't have param names for imported functions
+      location,
+    };
+
+    this.logEvent(event);
+
+    // Write function call to context file
+    this.writeTSFunctionContextFile(id, funcName, args, location);
+
+    return id;
+  }
+
+  /**
+   * Log TS block completion
+   */
+  tsBlockComplete(id: string, durationMs: number, error?: string): void {
+    const event: TSCompleteEvent = {
+      seq: ++this.seq,
+      ts: new Date().toISOString(),
+      event: 'ts_complete',
+      id,
+      tsType: 'block',
+      durationMs,
+      ...(error && { error }),
+    };
+
+    this.logEvent(event);
+  }
+
+  /**
+   * Log imported TS function completion
+   */
+  tsFunctionComplete(id: string, durationMs: number, error?: string): void {
+    const event: TSCompleteEvent = {
+      seq: ++this.seq,
+      ts: new Date().toISOString(),
+      event: 'ts_complete',
+      id,
+      tsType: 'function',
+      durationMs,
+      ...(error && { error }),
+    };
+
+    this.logEvent(event);
+  }
+
+  /**
+   * Get all logged events (for testing/inspection)
+   */
+  getEvents(): LogEvent[] {
+    return [...this.events];
+  }
+
+  /**
+   * Get the main log file path
+   */
+  getMainLogPath(): string {
+    return this.mainLogPath;
+  }
+
+  /**
+   * Get the context directory path
+   */
+  getContextDir(): string {
+    return this.contextDir;
+  }
+}
+
+/**
+ * Create a no-op logger (when verbose is disabled)
+ * Returns null - callers should check for null before logging
+ */
+export function createNoOpLogger(): null {
+  return null;
+}

package/src/runtime.ts

@@ -0,0 +1,2 @@
+// Re-export from new location for backwards compatibility
+export * from './runtime/index';

package/src/semantic/analyzer-context.ts

@@ -0,0 +1,62 @@
+/**
+ * Analyzer Context
+ *
+ * Shared interface and types for semantic analyzer modules.
+ * Provides a clean way to pass analyzer state to helper functions.
+ */
+import type { SourceLocation } from '../errors';
+import type { SymbolTable, SymbolKind } from './symbol-table';
+import type { TsFunctionSignature } from './ts-signatures';
+
+/**
+ * Context interface passed to analyzer helper functions.
+ * Contains the shared state needed for semantic analysis.
+ */
+export interface AnalyzerContext {
+  /** Symbol table for scope management */
+  symbols: SymbolTable;
+
+  /** Map of imported TS function names to their signatures */
+  tsImportSignatures: Map<string, TsFunctionSignature>;
+
+  /** Base path for resolving imports */
+  basePath?: string;
+
+  /** Original source code (for error messages) */
+  source?: string;
+
+  /** Whether currently inside a function body */
+  inFunction: boolean;
+
+  /** Whether at top level (not in a block) */
+  atTopLevel: boolean;
+
+  /** Current loop nesting depth (0 = not in a loop) */
+  loopDepth: number;
+
+  /** Report an error at the given location */
+  error(message: string, location: SourceLocation): void;
+
+  /** Declare a symbol in the current scope */
+  declare(
+    name: string,
+    kind: SymbolKind,
+    location: SourceLocation,
+    options?: {
+      paramCount?: number;
+      typeAnnotation?: string | null;
+      paramTypes?: string[];
+      returnType?: string | null;
+    }
+  ): void;
+}
+
+/**
+ * Mutable context state that can be modified during analysis.
+ * Separate from AnalyzerContext to make mutation explicit.
+ */
+export interface AnalyzerState {
+  inFunction: boolean;
+  atTopLevel: boolean;
+  loopDepth: number;
+}