@divmain/jdm-asm 0.2.0 → 0.2.3

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

@@ -1,92 +0,0 @@
-/**
- * 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

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

@@ -1,148 +0,0 @@
-/**
- * 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

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