@divmain/jdm-asm 0.2.0

package/src/compiler/cst-visitor.ts

@@ -0,0 +1,434 @@
+import { parser } from './expression-parser';
+import {
+  type ExpressionAST,
+  type StringLiteral,
+  type Interval,
+  type TemplateLiteral,
+  type ArrayLiteral,
+  type ObjectLiteral,
+  type BinaryOperator,
+} from './ast-types';
+import type { CstNode } from 'chevrotain';
+
+const BaseCstVisitor = parser.getBaseCstVisitorConstructor();
+
+/**
+ * Converts Chevrotain CST to our AST format.
+ */
+class ExpressionAstBuilder extends BaseCstVisitor {
+  constructor() {
+    super();
+    this.validateVisitor();
+  }
+
+  expression(ctx: any): ExpressionAST {
+    const condition = this.visit(ctx.condition);
+
+    if (ctx.Question) {
+      return {
+        type: 'TernaryOp',
+        condition,
+        consequent: this.visit(ctx.consequent),
+        alternate: this.visit(ctx.alternate),
+      };
+    }
+
+    return condition;
+  }
+
+  nullCoalescingExpression(ctx: any): ExpressionAST {
+    let result = this.visit(ctx.lhs);
+
+    if (ctx.rhs) {
+      for (const rhsNode of ctx.rhs) {
+        result = {
+          type: 'BinaryOp',
+          op: '??',
+          left: result,
+          right: this.visit(rhsNode),
+        };
+      }
+    }
+
+    return result;
+  }
+
+  orExpression(ctx: any): ExpressionAST {
+    let result = this.visit(ctx.lhs);
+
+    if (ctx.rhs) {
+      for (const rhsNode of ctx.rhs) {
+        result = {
+          type: 'BinaryOp',
+          op: 'or',
+          left: result,
+          right: this.visit(rhsNode),
+        };
+      }
+    }
+
+    return result;
+  }
+
+  andExpression(ctx: any): ExpressionAST {
+    let result = this.visit(ctx.lhs);
+
+    if (ctx.rhs) {
+      for (const rhsNode of ctx.rhs) {
+        result = {
+          type: 'BinaryOp',
+          op: 'and',
+          left: result,
+          right: this.visit(rhsNode),
+        };
+      }
+    }
+
+    return result;
+  }
+
+  comparisonExpression(ctx: any): ExpressionAST {
+    const lhs = this.visit(ctx.lhs);
+
+    if (!ctx.rhs) {
+      return lhs;
+    }
+
+    // Determine operator
+    let op: BinaryOperator;
+    if (ctx.Eq) {
+      op = '==';
+    } else if (ctx.NotEq) {
+      op = '!=';
+    } else if (ctx.Lt) {
+      op = '<';
+    } else if (ctx.Gt) {
+      op = '>';
+    } else if (ctx.LtEq) {
+      op = '<=';
+    } else if (ctx.GtEq) {
+      op = '>=';
+    } else if (ctx.In) {
+      op = ctx.Not ? 'not in' : 'in';
+    } else {
+      throw new Error('Unknown comparison operator');
+    }
+
+    return {
+      type: 'BinaryOp',
+      op,
+      left: lhs,
+      right: this.visit(ctx.rhs),
+    };
+  }
+
+  additiveExpression(ctx: any): ExpressionAST {
+    return this.buildLeftAssociativeBinaryOp(ctx, ['Plus', 'Minus'], ['+', '-']);
+  }
+
+  multiplicativeExpression(ctx: any): ExpressionAST {
+    return this.buildLeftAssociativeBinaryOp(ctx, ['Mult', 'Div', 'Mod'], ['*', '/', '%']);
+  }
+
+  // Power is right-associative, handled differently via recursion in grammar
+  powerExpression(ctx: any): ExpressionAST {
+    const base = this.visit(ctx.base);
+
+    if (ctx.exponent) {
+      return {
+        type: 'BinaryOp',
+        op: '^',
+        left: base,
+        right: this.visit(ctx.exponent),
+      };
+    }
+
+    return base;
+  }
+
+  unaryExpression(ctx: any): ExpressionAST {
+    if (ctx.Not || ctx.NotNot) {
+      return { type: 'UnaryOp', op: 'not', operand: this.visit(ctx.operand) };
+    }
+    if (ctx.Minus) {
+      return { type: 'UnaryOp', op: '-', operand: this.visit(ctx.operand) };
+    }
+    return this.visit(ctx.postfixExpression);
+  }
+
+  postfixExpression(ctx: any): ExpressionAST {
+    let result = this.visit(ctx.primaryExpression);
+
+    // Collect all postfix operations with their source positions
+    type PostfixOp =
+      | { type: 'member'; offset: number; idx: number }
+      | { type: 'index'; offset: number; idx: number }
+      | { type: 'call'; offset: number; idx: number };
+
+    const ops: PostfixOp[] = [];
+
+    if (ctx.Dot) {
+      for (let i = 0; i < ctx.Dot.length; i++) {
+        ops.push({ type: 'member', offset: ctx.Dot[i].startOffset, idx: i });
+      }
+    }
+
+    if (ctx.LBracket) {
+      for (let i = 0; i < ctx.LBracket.length; i++) {
+        ops.push({ type: 'index', offset: ctx.LBracket[i].startOffset, idx: i });
+      }
+    }
+
+    if (ctx.LParen) {
+      for (let i = 0; i < ctx.LParen.length; i++) {
+        ops.push({ type: 'call', offset: ctx.LParen[i].startOffset, idx: i });
+      }
+    }
+
+    // Sort by source position to apply in correct order: Chevrotain collects each operator
+    // type separately, but the actual evaluation order depends on source position when multiple
+    // operator types can appear.
+    //
+    // We must sort by position to reconstruct left-to-right evaluation order
+    ops.sort((a, b) => a.offset - b.offset);
+
+    // Apply each operation in order
+    for (const op of ops) {
+      if (op.type === 'member') {
+        const prop = ctx.property[op.idx].image;
+        result = { type: 'MemberAccess', object: result, property: prop };
+      } else if (op.type === 'index') {
+        const indexExpr = ctx.index[op.idx];
+        result = { type: 'IndexAccess', object: result, index: this.visit(indexExpr) };
+      } else if (op.type === 'call') {
+        // Check if there's an argumentList for this call
+        const args =
+          ctx.argumentList && ctx.argumentList[op.idx] ? this.visit(ctx.argumentList[op.idx]) : [];
+        result = { type: 'FunctionCall', callee: result, args };
+      }
+    }
+
+    return result;
+  }
+
+  primaryExpression(ctx: any): ExpressionAST {
+    if (ctx.NumberLiteral) {
+      const raw = ctx.NumberLiteral[0].image.replace(/_/g, '');
+      return { type: 'NumberLiteral', value: parseFloat(raw) };
+    }
+    if (ctx.StringLiteral) {
+      const raw = ctx.StringLiteral[0].image;
+      const value = this.unescapeString(raw.slice(1, -1));
+      return { type: 'StringLiteral', value };
+    }
+    if (ctx.True) {
+      return { type: 'BooleanLiteral', value: true };
+    }
+    if (ctx.False) {
+      return { type: 'BooleanLiteral', value: false };
+    }
+    if (ctx.Null) {
+      return { type: 'NullLiteral' };
+    }
+    if (ctx.Hash) {
+      return { type: 'HashRef' };
+    }
+    if (ctx.Dollar) {
+      return { type: 'DollarRef' };
+    }
+    if (ctx.Identifier) {
+      return { type: 'Identifier', name: ctx.Identifier[0].image };
+    }
+    if (ctx.arrayLiteralExpression) {
+      return this.visit(ctx.arrayLiteralExpression);
+    }
+    if (ctx.objectLiteralExpression) {
+      return this.visit(ctx.objectLiteralExpression);
+    }
+    if (ctx.expression) {
+      return this.visit(ctx.expression);
+    }
+    if (ctx.intervalExpression) {
+      return this.visit(ctx.intervalExpression);
+    }
+    if (ctx.templateLiteral) {
+      return this.visit(ctx.templateLiteral);
+    }
+
+    throw new Error('Unknown primary expression');
+  }
+
+  intervalExpression(ctx: any): Interval {
+    const startBracket = ctx.startBracket[0];
+    const endBracket = ctx.endBracket[0];
+
+    return {
+      type: 'Interval',
+      start: this.visit(ctx.start) as ExpressionAST,
+      end: this.visit(ctx.end) as ExpressionAST,
+      startInclusive: startBracket.tokenType.name === 'LBracket',
+      endInclusive: endBracket.tokenType.name === 'RBracket',
+    };
+  }
+
+  arrayLiteralExpression(ctx: any): ArrayLiteral {
+    if (!ctx.argumentList) {
+      return { type: 'ArrayLiteral', elements: [] };
+    }
+    const args = this.visit(ctx.argumentList);
+    return { type: 'ArrayLiteral', elements: args as ExpressionAST[] };
+  }
+
+  objectLiteralExpression(ctx: any): ObjectLiteral {
+    if (!ctx.objectPropertyList) {
+      return { type: 'ObjectLiteral', properties: [] };
+    }
+    const props = this.visit(ctx.objectPropertyList);
+    return {
+      type: 'ObjectLiteral',
+      properties: props as Array<{ key: string; value: ExpressionAST }>,
+    };
+  }
+
+  objectPropertyList(ctx: any): Array<{ key: string; value: ExpressionAST }> {
+    return ctx.prop.map(
+      (propNode: CstNode) => this.visit(propNode) as { key: string; value: ExpressionAST },
+    );
+  }
+
+  objectProperty(ctx: any): { key: string; value: ExpressionAST } {
+    const keyToken = ctx.key[0];
+    const key =
+      keyToken.tokenType.name === 'StringLiteral'
+        ? this.unescapeString(keyToken.image.slice(1, -1))
+        : keyToken.image;
+    const value = this.visit(ctx.value) as ExpressionAST;
+    return { key, value };
+  }
+
+  templateLiteral(ctx: any): TemplateLiteral | StringLiteral {
+    // Handle simple template with no substitution
+    if (ctx.TemplateNoSub) {
+      const raw = ctx.TemplateNoSub[0].image;
+      return { type: 'StringLiteral', value: this.unescapeString(raw.slice(1, -1)) };
+    }
+
+    // Handle template with interpolation
+    const parts: Array<{ text: string } | { expr: ExpressionAST }> = [];
+
+    // Extract text from TemplateHead (remove ` and ${)
+    const headRaw = ctx.TemplateHead[0].image;
+    const headText = this.unescapeString(headRaw.slice(1, -2));
+    if (headText) {
+      parts.push({ text: headText });
+    }
+
+    // Add expressions and middle parts
+    for (let i = 0; i < ctx.expr.length; i++) {
+      parts.push({ expr: this.visit(ctx.expr[i]) as ExpressionAST });
+
+      if (ctx.TemplateMiddle && ctx.TemplateMiddle[i]) {
+        const midRaw = ctx.TemplateMiddle[i].image;
+        const midText = this.unescapeString(midRaw.slice(1, -2));
+        if (midText) {
+          parts.push({ text: midText });
+        }
+      }
+    }
+
+    // Extract text from TemplateTail (remove } and `)
+    const tailRaw = ctx.TemplateTail[0].image;
+    const tailText = this.unescapeString(tailRaw.slice(1, -1));
+    if (tailText) {
+      parts.push({ text: tailText });
+    }
+
+    // Template literals with no interpolation (just text) can be converted to simple string
+    // literals, avoiding runtime template processing overhead.
+    if (parts.every((p) => 'text' in p)) {
+      const combined = parts.map((p) => (p as { text: string }).text).join('');
+      return { type: 'StringLiteral', value: combined };
+    }
+
+    return { type: 'TemplateLiteral', parts };
+  }
+
+  argumentList(ctx: any): ExpressionAST[] {
+    return ctx.arg.map((argNode: CstNode) => this.visit(argNode) as ExpressionAST);
+  }
+
+  /**
+   * Helper to unescape string literals.
+   * Handles basic escape sequences like \n, \t, \", \', \\, etc.
+   */
+  private unescapeString(s: string): string {
+    return s
+      .replace(/\\n/g, '\n')
+      .replace(/\\t/g, '\t')
+      .replace(/\\r/g, '\r')
+      .replace(/\\'/g, "'")
+      .replace(/"/g, '"')
+      .replace(/\\\\/g, '\\');
+  }
+
+  /**
+   * Helper for left-associative binary operators.
+   * Collects all operator tokens, sorts them by position, and pairs them with RHS operands.
+   */
+  private buildLeftAssociativeBinaryOp(
+    ctx: any,
+    tokenNames: string[],
+    ops: BinaryOperator[],
+  ): ExpressionAST {
+    let result = this.visit(ctx.lhs) as ExpressionAST;
+
+    if (!ctx.rhs) {
+      // No right-hand side: return just the left expression
+      return result;
+    }
+
+    // Collect all operator tokens with their corresponding operator symbol
+    const operatorTokens: Array<{ op: BinaryOperator; offset: number }> = [];
+    for (let j = 0; j < tokenNames.length; j++) {
+      const tokens = ctx[tokenNames[j]];
+      if (tokens) {
+        for (const token of tokens) {
+          operatorTokens.push({ op: ops[j], offset: token.startOffset });
+        }
+      }
+    }
+
+    // Sort operators by their position in the source
+    operatorTokens.sort((a, b) => a.offset - b.offset);
+
+    // Build the expression tree left-to-right
+    for (let i = 0; i < ctx.rhs.length; i++) {
+      const op = operatorTokens[i]?.op;
+      if (!op) {
+        throw new Error(`Operator not found for ${tokenNames.join(', ')}`);
+      }
+
+      result = {
+        type: 'BinaryOp',
+        op,
+        left: result,
+        right: this.visit(ctx.rhs[i]) as ExpressionAST,
+      };
+    }
+
+    return result;
+  }
+}
+
+export const astBuilder = new ExpressionAstBuilder();
+
+/**
+ * Convert a CST (Concrete Syntax Tree) to an AST (Abstract Syntax Tree).
+ * CST contains low-level parsing artifacts; AST simplifies structure for compilation
+ *
+ * @param cst - The CST from the Chevrotain parser
+ * @returns The AST node
+ */
+export function cstToAst(cst: CstNode): ExpressionAST {
+  return astBuilder.visit(cst);
+}

package/src/compiler/errors.ts

@@ -0,0 +1,227 @@
+/**
+ * Error handling infrastructure for the JDM compiler.
+ *
+ * This module provides:
+ * - CompilationError: The main error class for all compilation failures
+ * - ErrorCode: A comprehensive enumeration of all possible error types
+ * - SourceLocation: Detailed location information for error reporting
+ * - ErrorCollector: Aggregates non-fatal expression errors for batch reporting
+ */
+
+/**
+ * Detailed source location for error reporting.
+ */
+export interface SourceLocation {
+  /** ID of the node where the error occurred */
+  nodeId?: string;
+  /** Name of the node where the error occurred */
+  nodeName?: string;
+  /** Field name within the node */
+  field?: string;
+  /** Line number in source JDM */
+  line?: number;
+  /** Column number in source JDM */
+  column?: number;
+}
+
+/**
+ * Enumeration of all possible compilation error codes.
+ *
+ * Errors are categorized into three types:
+ * - Structural errors: Critical JDM structure issues that fail compilation immediately
+ * - Feature errors: Unsupported features that cannot be handled
+ * - Expression errors: Issues in expression parsing that can be collected and reported together
+ */
+export enum ErrorCode {
+  // Structural errors (fail immediately)
+  INVALID_JSON = 'INVALID_JSON',
+  INVALID_NODE_STRUCTURE = 'INVALID_NODE_STRUCTURE',
+  MISSING_INPUT_NODE = 'MISSING_INPUT_NODE',
+  MISSING_OUTPUT_NODE = 'MISSING_OUTPUT_NODE',
+  MULTIPLE_INPUT_NODES = 'MULTIPLE_INPUT_NODES',
+  CYCLE_DETECTED = 'CYCLE_DETECTED',
+  INVALID_EDGE = 'INVALID_EDGE',
+
+  // Feature errors (fail immediately)
+  UNSUPPORTED_FUNCTION_NODE = 'UNSUPPORTED_FUNCTION_NODE',
+  UNSUPPORTED_EXPRESSION = 'UNSUPPORTED_EXPRESSION',
+
+  // Expression errors (collected, reported together)
+  PARSE_ERROR = 'PARSE_ERROR',
+  UNKNOWN_FUNCTION = 'UNKNOWN_FUNCTION',
+  TYPE_MISMATCH = 'TYPE_MISMATCH',
+  UNKNOWN_FIELD = 'UNKNOWN_FIELD',
+
+  // Schema errors
+  SCHEMA_MISMATCH = 'SCHEMA_MISMATCH',
+  INVALID_SCHEMA = 'INVALID_SCHEMA',
+}
+
+/**
+ * Custom error class for compilation failures.
+ *
+ * Provides structured error information including error code, source location,
+ * and additional context for debugging.
+ */
+export class CompilationError extends Error {
+  readonly name = 'CompilationError';
+
+  constructor(
+    message: string,
+    public readonly code: ErrorCode,
+    public readonly location?: SourceLocation,
+    public readonly context?: Record<string, unknown>,
+  ) {
+    super(message);
+    // Exclude the CompilationError constructor frame from the stack trace.
+    // Without this, stack traces would include an unhelpful constructor frame,
+    // making it harder to identify the actual error source in compiled code.
+    // Only available on V8-based engines (Node.js, Chrome, Edge).
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, CompilationError);
+    }
+  }
+
+  /**
+   * Get a formatted error message with location information.
+   */
+  getFormattedMessage(): string {
+    const parts: string[] = [];
+
+    if (this.location) {
+      const locParts: string[] = [];
+      if (this.location.nodeName) {
+        locParts.push(this.location.nodeName);
+      }
+      if (this.location.nodeId) {
+        locParts.push(`(id: ${this.location.nodeId})`);
+      }
+      if (this.location.field) {
+        locParts.push(`.${this.location.field}`);
+      }
+      // Combine line and column: @10:5
+      if (this.location.line !== undefined && this.location.column !== undefined) {
+        locParts.push(`@${this.location.line}:${this.location.column}`);
+      } else if (this.location.line !== undefined) {
+        locParts.push(`@${this.location.line}`);
+      } else if (this.location.column !== undefined) {
+        locParts.push(`:${this.location.column}`);
+      }
+
+      if (locParts.length > 0) {
+        parts.push(`[${locParts.join(' ')}]`);
+      }
+    }
+
+    parts.push(`[${this.code}]`);
+    parts.push(this.message);
+
+    return parts.join(' ');
+  }
+}
+
+/**
+ * Collector for non-fatal errors during expression parsing.
+ *
+ * This allows the parser to continue and collect multiple errors rather than
+ * failing on the first one, providing a better user experience by reporting
+ * all issues at once.
+ *
+ * @example
+ * const collector = new ErrorCollector();
+ * collector.add(new CompilationError('Undefined variable', ErrorCode.UNKNOWN_FIELD, { nodeName: 'AgeCheck' }));
+ * collector.add(new CompilationError('Type mismatch', ErrorCode.TYPE_MISMATCH, { nodeName: 'AgeCheck' }));
+ * collector.throwIfErrors(); // Throws with aggregated message
+ */
+export class ErrorCollector {
+  private errors: CompilationError[] = [];
+
+  /**
+   * Add an error to the collector.
+   */
+  add(error: CompilationError): void {
+    this.errors.push(error);
+  }
+
+  /**
+   * Check if any errors have been collected.
+   */
+  hasErrors(): boolean {
+    return this.errors.length > 0;
+  }
+
+  /**
+   * Throw if there are any collected errors.
+   *
+   * Single errors throw directly to preserve original context and stack trace. Multiple
+   * errors are aggregated into one with numbered list, so developers see all problems at
+   * once instead of fixing issues one-by-one through repeated compile attempts.
+   */
+  throwIfErrors(): void {
+    if (this.errors.length === 0) {
+      return;
+    }
+
+    if (this.errors.length === 1) {
+      throw this.errors[0];
+    }
+
+    const message =
+      `${this.errors.length} compilation errors:\n` +
+      this.errors
+        .map((e, i) => {
+          const prefix = `  ${i + 1}. ${e.code}`;
+          const formatted = e.getFormattedMessage();
+          // getFormattedMessage() includes [CODE] prefix, but we already show the code in
+          // our numbered list, so strip it to avoid "1. CODE: [CODE] message"
+          const rest = formatted.replace(`[${e.code}]`, '').trim();
+          return `${prefix}${rest ? ': ' + rest : ''}`;
+        })
+        .join('\n');
+
+    // Use the location from the first error as the aggregated error's location
+    const firstErrorLocation = this.errors[0].location;
+    throw new CompilationError(message, ErrorCode.PARSE_ERROR, firstErrorLocation);
+  }
+}
+
+/**
+ * Type guard to check if an error is a CompilationError.
+ */
+export function isCompilationError(error: unknown): error is CompilationError {
+  return error instanceof CompilationError;
+}
+
+/**
+ * Type guard to check if an error code is a structural error.
+ */
+export function isStructuralError(code: ErrorCode): boolean {
+  return [
+    ErrorCode.INVALID_JSON,
+    ErrorCode.INVALID_NODE_STRUCTURE,
+    ErrorCode.MISSING_INPUT_NODE,
+    ErrorCode.MISSING_OUTPUT_NODE,
+    ErrorCode.MULTIPLE_INPUT_NODES,
+    ErrorCode.CYCLE_DETECTED,
+    ErrorCode.INVALID_EDGE,
+  ].includes(code);
+}
+
+/**
+ * Type guard to check if an error code is a feature error.
+ */
+export function isFeatureError(code: ErrorCode): boolean {
+  return [ErrorCode.UNSUPPORTED_FUNCTION_NODE, ErrorCode.UNSUPPORTED_EXPRESSION].includes(code);
+}
+
+/**
+ * Type guard to check if an error code is an expression error.
+ */
+export function isExpressionError(code: ErrorCode): boolean {
+  return [
+    ErrorCode.PARSE_ERROR,
+    ErrorCode.UNKNOWN_FUNCTION,
+    ErrorCode.TYPE_MISMATCH,
+    ErrorCode.UNKNOWN_FIELD,
+  ].includes(code);
+}