@divmain/jdm-asm 0.2.0

package/src/compiler/switch-branch-detection.ts

@@ -0,0 +1,92 @@
+/**
+ * Switch branch detection algorithm for JDM decisions.
+ *
+ * This module identifies nodes that are exclusively reachable through switch node branches.
+ * These nodes are marked as "switchBranchTargets" and should be skipped during the main
+ * evaluation loop because the switch node evaluates them inline when taking a branch.
+ *
+ * WHY: Prevent double-evaluation - switch nodes evaluate branches inline, so downstream
+ * nodes must be skipped in the main evaluation loop to avoid executing them twice.
+ *
+ * OPTIMIZATION: Uses a single forward traversal through the graph to mark all nodes
+ * reachable from switch branches. This is O(n + m) instead of O(s × b × (n + m))
+ * where s = switches, b = branches, n = nodes, m = edges.
+ */
+
+import type { JDMDecision, JDMEdge } from './parser';
+
+/**
+ * Build an adjacency map for fast edge lookups.
+ * Maps each source node ID to an array of target node IDs.
+ *
+ * @param edges - All edges in the decision graph
+ * @returns Map from source node ID to array of target node IDs
+ */
+function buildAdjacencyMap(edges: JDMEdge[]): Map<string, string[]> {
+  const adjacencyMap = new Map<string, string[]>();
+
+  for (const edge of edges) {
+    const targets = adjacencyMap.get(edge.sourceId);
+    if (targets) {
+      targets.push(edge.targetId);
+    } else {
+      adjacencyMap.set(edge.sourceId, [edge.targetId]);
+    }
+  }
+
+  return adjacencyMap;
+}
+
+/**
+ * Find all nodes that are exclusively reachable through switch node branches.
+ *
+ * Optimized algorithm:
+ * 1. Build adjacency map once for O(1) edge lookups
+ * 2. Identify all direct targets of switch nodes
+ * 3. Use BFS with efficient queue operations to traverse from all switch targets
+ * 4. Marks all nodes reachable from switch branches in a single traversal
+ *
+ * Time complexity: O(n + m) where n = nodes, m = edges
+ * Space complexity: O(n + m) for adjacency map and visited set
+ *
+ * @param jdm - The parsed JDM decision
+ * @returns Set of node IDs that are switch branch targets
+ */
+export function findSwitchBranchTargets(jdm: JDMDecision): Set<string> {
+  // Build adjacency map once for O(1) lookups instead of O(m) filtering
+  const adjacencyMap = buildAdjacencyMap(jdm.edges);
+
+  // Find all direct targets of switch nodes
+  const switchNodes = jdm.nodes.filter((n) => n.type === 'switchNode');
+  const switchBranchTargets = new Set<string>();
+
+  // Collect all direct switch targets to start BFS from
+  const bfsQueue: string[] = [];
+  for (const switchNode of switchNodes) {
+    const targets = adjacencyMap.get(switchNode.id) || [];
+    for (const targetId of targets) {
+      if (!switchBranchTargets.has(targetId)) {
+        switchBranchTargets.add(targetId);
+        bfsQueue.push(targetId);
+      }
+    }
+  }
+
+  // Single BFS traversal from all switch targets
+  // Use index-based iteration instead of shift() to avoid O(n) array operations
+  let queueIndex = 0;
+  while (queueIndex < bfsQueue.length) {
+    const currentId = bfsQueue[queueIndex++];
+
+    // Get all outgoing edges using O(1) map lookup
+    const targets = adjacencyMap.get(currentId) || [];
+    for (const targetId of targets) {
+      if (!switchBranchTargets.has(targetId)) {
+        switchBranchTargets.add(targetId);
+        bfsQueue.push(targetId);
+      }
+    }
+  }
+
+  return switchBranchTargets;
+}

package/src/compiler/types.ts

@@ -0,0 +1,136 @@
+import type { TSchema } from '@sinclair/typebox';
+import type { JDMDecision } from './parser';
+
+/**
+ * No-match behavior options for decision tables and switch nodes.
+ *
+ * This is a discriminated union to ensure type safety:
+ * - returnNull and throwError don't require additional data
+ * - returnDefault requires a value at type level
+ */
+export type NoMatchBehavior =
+  | { type: 'returnNull' }
+  | { type: 'throwError' }
+  | { type: 'returnDefault'; value: unknown };
+
+/**
+ * Context passed through compilation phases.
+ */
+export interface CompilationContext {
+  /** The parsed JDM */
+  jdm: JDMDecision;
+
+  /** Input schema (TypeBox) */
+  inputSchema: TSchema;
+
+  /** Output schema (TypeBox) */
+  outputSchema: TSchema;
+
+  /** Flattened input memory layout */
+  inputLayout: FlattenedLayout;
+
+  /** Flattened output memory layout */
+  outputLayout: FlattenedLayout;
+
+  /** Schema hash for runtime validation */
+  schemaHash: bigint;
+
+  /** Compiler options */
+  options: CompilerOptions;
+
+  /** Parse an expression string to AST */
+  parseExpression(expr: string): any;
+
+  /** Parse an expression in unary mode */
+  parseUnaryExpression(expr: string): any;
+
+  /** Get unique identifier for generated code */
+  getUniqueId(prefix: string): string;
+
+  /** Loader function to load sub-decision JDM files by reference key */
+  loadDecision(key: string): JDMDecision;
+
+  /** Cache of compiled sub-decisions (key -> compiled code) */
+  compiledSubDecisions: Map<string, AssemblyScriptCode>;
+
+  /** Track the current decision path for cycle detection */
+  decisionPath: string[];
+
+  /** Generated helper functions for higher-order operations */
+  helperFunctions: Map<string, string>;
+
+  /** Function node sources for JavaScript bridge (node ID -> JavaScript source code) */
+  functionSources?: Map<string, string>;
+}
+
+/**
+ * Flattened schema layout for direct memory access.
+ */
+export interface FlattenedLayout {
+  fields: Array<{
+    path: string; // e.g., "customer.age"
+    flatName: string; // e.g., "customer_age"
+    type: 'f64' | 'i32' | 'i64' | 'bool' | 'string' | 'array';
+    offset: number; // Byte offset in struct
+    size: number; // Bytes (fixed types) or -1 (variable)
+  }>;
+}
+
+/**
+ * Compiler options.
+ */
+export interface CompilerOptions {
+  optimize?: boolean;
+  debug?: boolean;
+  validate?: boolean;
+  /** How to handle cases where no rules match in decision tables/switches */
+  noMatchBehavior?: NoMatchBehavior;
+  /** Optional loader function to load sub-decision JDM files */
+  loadDecision?: (key: string) => JDMDecision;
+  /** Optional testDataRoot path for default loader to search */
+  testDataRoot?: string;
+  /**
+   * Optional path to write debug AssemblyScript files on compilation failure.
+   *
+   * When compilation fails, the generated AssemblyScript code is written to disk
+   * to aid debugging. This option controls where these files are written:
+   *
+   * - `undefined` (default): No debug files are written
+   * - `string`: Files are written to a secure temporary directory under this path
+   * - Environment variable `JDM_ASM_DEBUG_OUTPUT`: Falls back to this path if option not set
+   *
+   * **Filesystem Side Effects:**
+   * - Creates temporary directories with random names (e.g., `jdm-asm-debug-XXXXXX`)
+   * - Writes `.ts` files with 0o600 permissions (owner read/write only)
+   * - Files are NOT automatically cleaned up and may accumulate
+   *
+   * **Security:**
+   * - Uses `fs.mkdtempSync()` to create secure temporary directories
+   * - Files are created with restricted permissions (0o600)
+   * - Temporary directories have random names to prevent conflicts
+   */
+  debugOutputPath?: string;
+}
+
+/**
+ * Result of compilation.
+ */
+export interface CompilationResult {
+  /** Compiled WASM binary */
+  wasm: Uint8Array;
+  /** Schema hash for runtime validation */
+  schemaHash: bigint;
+  /** Generated marshaling code (JS) */
+  marshalCode: string;
+  /** Generated validation code (JS) */
+  validationCode: string;
+  /** WAT text format (if debug enabled) */
+  wat?: string;
+  /** Generated AssemblyScript source (if debug enabled) */
+  assemblyScript?: string;
+}
+
+/**
+ * Alias for generated AssemblyScript code strings.
+ */
+export type AssemblyScriptCode = string;

package/src/compiler/unary-ast-transforms.ts

@@ -0,0 +1,148 @@
+/**
+ * Unary AST transformation utilities.
+ *
+ * This module provides AST-level transformations specific to unary (decision table)
+ * context. These transformations are applied AFTER parsing to convert a standard AST
+ * into an AST that reflects the semantic meaning in unary context.
+ *
+ * Key transformations:
+ * - Bare identifiers → string literals (for implicit string matching)
+ * - Comparison without LHS → $ comparison (e.g., "> 100" → "$ > 100")
+ * - Multiple comma-separated values → OR chain
+ *
+ * This separates SEMANTIC transformations from SYNTACTIC parsing, keeping
+ * the parser focused solely on syntax-to-AST conversion.
+ */
+
+import type { ExpressionAST, BinaryOperator, BinaryOp } from './ast-types';
+
+/**
+ * Convert a bare Identifier node to a StringLiteral node.
+ *
+ * In decision table cells, unquoted words like "premium" are semantic values to match against,
+ * not variable references. This prevents errors when authors write intuitive cell values without
+ * quotes. This is a key DMN/JDM usability feature.
+ *
+ * This handles the common JDM/DMN convention where cell values like:
+ *   - premium      means match the string "premium" (identifier → string)
+ *   - "premium"    means match the string "premium" (already a string)
+ *
+ * We only convert top-level Identifiers. More complex expressions (member access,
+ * function calls, etc.) are left as-is since they likely involve actual variables.
+ *
+ * @param ast - The AST node that may be an Identifier
+ * @returns The AST node, with Identifier converted to StringLiteral if applicable
+ */
+export function convertIdentifierToStringLiteral(ast: ExpressionAST): ExpressionAST {
+  if (ast.type === 'Identifier') {
+    return { type: 'StringLiteral', value: (ast as { type: 'Identifier'; name: string }).name };
+  }
+  return ast;
+}
+
+/**
+ * Wrap an AST value in a comparison with DollarRef (the implicit cell input).
+ *
+ * In unary context, expressions like "> 100" implicitly compare against the input value.
+ * This function creates the full comparison AST: "$ <op> <value>".
+ *
+ * @param ast - The right-hand side value AST
+ * @param op - The comparison operator
+ * @returns A BinaryOp AST with DollarRef on the left
+ */
+export function wrapWithDollarComparison(ast: ExpressionAST, op: BinaryOperator): BinaryOp {
+  return {
+    type: 'BinaryOp',
+    op,
+    left: { type: 'DollarRef' },
+    right: ast,
+  };
+}
+
+/**
+ * Create an equality comparison with implicit identifier-to-string conversion.
+ *
+ * This is the default transformation for unary values - they become equality
+ * comparisons against the input value ($). For equality/inequality comparisons,
+ * bare identifiers are converted to string literals.
+ *
+ * @param ast - The value to compare against
+ * @param op - The equality operator (== or !=)
+ * @returns A BinaryOp AST representing the equality comparison
+ */
+export function createEqualityComparison(ast: ExpressionAST, op: '==' | '!='): BinaryOp {
+  const value = convertIdentifierToStringLiteral(ast);
+  return wrapWithDollarComparison(value, op);
+}
+
+/**
+ * Create an interval membership check.
+ *
+ * In unary context, interval notation like "[1..10]" becomes "$ in [1..10]".
+ *
+ * @param intervalAst - The interval AST node
+ * @returns A BinaryOp AST representing the membership check
+ */
+export function createIntervalCheck(intervalAst: ExpressionAST): BinaryOp {
+  return wrapWithDollarComparison(intervalAst, 'in');
+}
+
+/**
+ * Create an array membership check.
+ *
+ * In unary context, array literals like "['gold', 'platinum']" become
+ * "$ in ['gold', 'platinum']".
+ *
+ * @param arrayAst - The array literal AST node
+ * @returns A BinaryOp AST representing the membership check
+ */
+export function createArrayMembershipCheck(arrayAst: ExpressionAST): BinaryOp {
+  return wrapWithDollarComparison(arrayAst, 'in');
+}
+
+/**
+ * Combine multiple expression ASTs into an OR chain.
+ *
+ * In unary context, comma-separated values represent OR semantics.
+ * For example, "a, b, c" becomes "$ == 'a' or $ == 'b' or $ == 'c'".
+ *
+ * @param exprs - Array of expression ASTs to combine
+ * @returns A single AST representing the OR of all expressions
+ */
+export function combineWithOr(exprs: ExpressionAST[]): ExpressionAST {
+  if (exprs.length === 0) {
+    return { type: 'BooleanLiteral', value: true };
+  }
+  if (exprs.length === 1) {
+    return exprs[0];
+  }
+  return exprs.reduce((acc, expr) => ({
+    type: 'BinaryOp',
+    op: 'or',
+    left: acc,
+    right: expr,
+  }));
+}
+
+/**
+ * Combine multiple expression ASTs into an AND chain.
+ *
+ * Used for compound unary expressions like ">= 13 and < 15".
+ *
+ * @param exprs - Array of expression ASTs to combine
+ * @returns A single AST representing the AND of all expressions
+ */
+export function combineWithAnd(exprs: ExpressionAST[]): ExpressionAST {
+  if (exprs.length === 0) {
+    return { type: 'BooleanLiteral', value: true };
+  }
+  if (exprs.length === 1) {
+    return exprs[0];
+  }
+  return exprs.reduce((acc, expr) => ({
+    type: 'BinaryOp',
+    op: 'and',
+    left: acc,
+    right: expr,
+  }));
+}

package/src/compiler/unary-parser.ts

@@ -0,0 +1,301 @@
+/**
+ * Unary expression parser for decision table cells.
+ *
+ * This module provides parsing for unary mode expressions, which are used in
+ * decision table cells. The parser is responsible for SYNTACTIC analysis only -
+ * converting text to AST nodes. Semantic transformations (like converting
+ * identifiers to string literals) are handled by the unary-ast-transforms module.
+ *
+ * Separation of Concerns:
+ * - This module: Tokenization, lexing, parsing (text → AST)
+ * - unary-ast-transforms: Semantic transformations (AST → transformed AST)
+ * - unary-transform: Dollar reference substitution for compilation (AST → compiled AST)
+ */
+
+import { parser, lexer } from './expression-parser';
+import { type ExpressionAST, type BinaryOperator } from './ast-types';
+import { cstToAst } from './cst-visitor';
+import { CompilationError, ErrorCode, type SourceLocation } from './errors';
+import {
+  wrapWithDollarComparison,
+  createEqualityComparison,
+  createIntervalCheck,
+  createArrayMembershipCheck,
+  combineWithOr,
+  combineWithAnd,
+} from './unary-ast-transforms';
+
+/**
+ * Parse an expression in unary mode (for decision table cells).
+ *
+ * In DMN/JDM convention, decision table cells contain concise expressions that implicitly
+ * compare against the input column value ($). This allows table authors to write "premium"
+ * instead of "$ == 'premium'" or "> 100" instead of "$ > 100", making tables more readable.
+ *
+ * Unary mode transformations:
+ * - "admin"         -> $ == "admin"
+ * - > 100           -> $ > 100
+ * - [1..10]         -> $ in [1..10]
+ * - "a", "b", "c"   -> $ == "a" or $ == "b" or $ == "c"
+ * - $ > 100         -> $ > 100 (explicit $ disables transformations)
+ *
+ * @param input - The unary expression to parse
+ * @returns The AST node
+ */
+export function parseUnaryExpression(input: string): ExpressionAST {
+  const trimmed = input.trim();
+
+  // Empty cell = always matches
+  if (trimmed === '' || trimmed === '-') {
+    return { type: 'BooleanLiteral', value: true };
+  }
+
+  // Check if expression uses explicit $ - if so, parse as standard expression
+  if (trimmed.includes('$')) {
+    return parseStandardExpression(trimmed);
+  }
+
+  // Check for comma-separated values (OR semantics)
+  // But only if it's not an array literal
+  if (trimmed.includes(',') && !isArrayLiteral(trimmed)) {
+    const parts = splitByComma(trimmed);
+    const comparisons = parts.map((part) => transformUnaryPart(part.trim()));
+    return combineWithOr(comparisons);
+  }
+
+  // Check for compound expressions with 'and' or 'or' that need implicit $ expansion
+  // e.g., ">= 13 and < 15" should become "$ >= 13 and $ < 15"
+  const compoundResult = parseCompoundUnary(trimmed);
+  if (compoundResult) {
+    return compoundResult;
+  }
+
+  return transformUnaryPart(trimmed);
+}
+
+/**
+ * Parse a single unary part and apply semantic transformations.
+ *
+ * This function performs both parsing and transformation in a single step:
+ * 1. Parse the input using the standard expression parser
+ * 2. Apply unary-context semantic transformations (AST operations)
+ *
+ * @param input - The unary part to parse
+ * @returns The transformed AST node
+ */
+function transformUnaryPart(input: string): ExpressionAST {
+  // Check for comparison operator at start
+  const comparisonMatch = input.match(/^(==|!=|<=|>=|<|>)\s*(.+)$/);
+  if (comparisonMatch) {
+    const [, op, valueExpr] = comparisonMatch;
+    const value = parseStandardExpression(valueExpr);
+    // For equality/inequality comparisons, convert bare identifiers to strings
+    if (op === '==' || op === '!=') {
+      return createEqualityComparison(value, op as '==' | '!=');
+    }
+    return wrapWithDollarComparison(value, op as BinaryOperator);
+  }
+
+  // Check for interval notation
+  if (input.match(/^[[].+\.\..*[\])]$/)) {
+    const intervalAst = parseStandardExpression(input);
+    return createIntervalCheck(intervalAst);
+  }
+
+  // Check for array literal - use 'in' for membership
+  // e.g., "['gold', 'platinum']" should become "$ in ['gold', 'platinum']"
+  if (isArrayLiteral(input)) {
+    const arrayAst = parseStandardExpression(input);
+    return createArrayMembershipCheck(arrayAst);
+  }
+
+  // Default: equality comparison
+  // Convert bare identifiers to string literals for implicit equality
+  const value = parseStandardExpression(input);
+  return createEqualityComparison(value, '==');
+}
+
+/**
+ * Parse compound unary expressions that use 'and' or 'or' with implicit $
+ * Examples:
+ * - ">= 13 and < 15" -> "$ >= 13 and $ < 15"
+ * - "> 0 or == null" -> "$ > 0 or $ == null"
+ *
+ * @param input - The expression to parse
+ * @returns The AST if compound, null otherwise
+ */
+function parseCompoundUnary(input: string): ExpressionAST | null {
+  // Match patterns like: <op1> <val1> and/or <op2> <val2>
+  // We need to split by ' and ' or ' or ' while preserving quotes and brackets
+  const andParts = splitByLogicalOp(input, 'and');
+  if (andParts.length > 1) {
+    const comparisons = andParts.map((part) => transformUnaryPart(part.trim()));
+    return combineWithAnd(comparisons);
+  }
+
+  const orParts = splitByLogicalOp(input, 'or');
+  if (orParts.length > 1) {
+    const comparisons = orParts.map((part) => transformUnaryPart(part.trim()));
+    return combineWithOr(comparisons);
+  }
+
+  return null;
+}
+
+/**
+ * Split input by a logical operator (' and ' or ' or '), respecting quotes and brackets.
+ *
+ * This is a parsing helper that performs tokenization while respecting nested structures.
+ */
+function splitByLogicalOp(input: string, op: 'and' | 'or'): string[] {
+  const pattern = ` ${op} `;
+  const parts: string[] = [];
+  let current = '';
+  let depth = 0;
+  let inString = false;
+  let stringChar = '';
+  let i = 0;
+
+  while (i < input.length) {
+    const char = input[i];
+
+    if (inString) {
+      current += char;
+      if (char === stringChar && input[i - 1] !== '\\') {
+        inString = false;
+      }
+      i++;
+      continue;
+    }
+
+    if (char === '"' || char === "'") {
+      inString = true;
+      stringChar = char;
+      current += char;
+      i++;
+    } else if (char === '[' || char === '(' || char === '{') {
+      depth++;
+      current += char;
+      i++;
+    } else if (char === ']' || char === ')' || char === '}') {
+      depth--;
+      current += char;
+      i++;
+    } else if (depth === 0 && input.substring(i, i + pattern.length).toLowerCase() === pattern) {
+      parts.push(current);
+      current = '';
+      i += pattern.length;
+    } else {
+      current += char;
+      i++;
+    }
+  }
+
+  if (current) {
+    parts.push(current);
+  }
+  return parts;
+}
+
+/**
+ * Check if a string represents an array literal (not an interval).
+ *
+ * Arrays and intervals both use bracket syntax but have different semantics.
+ * Arrays check membership ($ in [1,2,3]), intervals check ranges ($ in [1..10]).
+ * Must detect .. to parse correctly.
+ */
+function isArrayLiteral(input: string): boolean {
+  return input.startsWith('[') && input.endsWith(']') && !input.includes('..');
+}
+
+/**
+ * Smart split by comma that respects brackets and strings.
+ *
+ * This is a parsing helper for tokenizing comma-separated unary values
+ * while respecting nested structures.
+ *
+ * Examples:
+ * - "a, b, c" -> ["a", "b", "c"]
+ * - "[1, 2], [3, 4]" -> ["[1, 2]", "[3, 4]"]
+ * - '"a, b", "c, d"' -> ['"a, b"', '"c, d"']
+ */
+function splitByComma(input: string): string[] {
+  const parts: string[] = [];
+  let current = '';
+  let depth = 0;
+  let inString = false;
+  let stringChar = '';
+
+  for (let i = 0; i < input.length; i++) {
+    const char = input[i];
+
+    if (inString) {
+      current += char;
+      // Check if string ends (and handle escaped quotes)
+      if (char === stringChar && input[i - 1] !== '\\') {
+        inString = false;
+      }
+      continue;
+    }
+
+    if (char === '"' || char === "'") {
+      inString = true;
+      stringChar = char;
+      current += char;
+    } else if (char === '[' || char === '(') {
+      depth++;
+      current += char;
+    } else if (char === ']' || char === ')') {
+      depth--;
+      current += char;
+    } else if (char === ',' && depth === 0) {
+      parts.push(current);
+      current = '';
+    } else {
+      current += char;
+    }
+  }
+
+  if (current) {
+    parts.push(current);
+  }
+  return parts;
+}
+
+/**
+ * Parse a standard (non-unary) expression.
+ *
+ * This is the core parsing function that converts an expression string to an AST.
+ * It uses the Chevrotain lexer and parser defined in expression-parser.ts,
+ * then converts the CST to AST using cst-visitor.ts.
+ *
+ * @param input - The expression string to parse
+ * @param location - Optional source location for error reporting
+ * @returns The AST node
+ */
+export function parseStandardExpression(input: string, location?: SourceLocation): ExpressionAST {
+  const lexingResult = lexer.tokenize(input);
+
+  if (lexingResult.errors.length > 0) {
+    throw new CompilationError(
+      `Lexer error: ${lexingResult.errors.map((e: any) => e.message).join(', ')}`,
+      ErrorCode.PARSE_ERROR,
+      location,
+      { expression: input },
+    );
+  }
+
+  parser.input = lexingResult.tokens;
+  const cst = parser.expression();
+
+  if (parser.errors.length > 0) {
+    throw new CompilationError(
+      `Parse error: ${parser.errors.map((e: any) => e.message).join(', ')}`,
+      ErrorCode.PARSE_ERROR,
+      location,
+      { expression: input },
+    );
+  }
+
+  return cstToAst(cst);
+}