@divmain/jdm-asm 0.2.0 → 0.2.3

package/src/compiler/cst-visitor.ts

@@ -1,434 +0,0 @@
-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

@@ -1,227 +0,0 @@
-/**
- * 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);
-}