@divmain/jdm-asm 0.2.0

package/src/compiler/graph.ts

@@ -0,0 +1,197 @@
+import { DirectedGraph } from 'graphology';
+import { topologicalSort } from 'graphology-dag';
+import { type JDMNode, type JDMEdge, type JDMDecision, NodeType } from './parser';
+import { CompilationError, ErrorCode, type SourceLocation } from './errors';
+
+export type JDMGraph = DirectedGraph<JDMNode, JDMEdge>;
+
+export function buildGraph(jdm: JDMDecision): JDMGraph {
+  const graph = new DirectedGraph<JDMNode, JDMEdge>();
+
+  // Map provides O(1) lookups for edge validation and node existence checks
+  const nodeMap = new Map<string, JDMNode>();
+  for (const node of jdm.nodes) {
+    graph.addNode(node.id, node);
+    nodeMap.set(node.id, node);
+  }
+
+  // Switch nodes can have multiple edges to same target (different cases/handles pointing to
+  // same node), but topological sort only needs one edge per source→target pair to establish
+  // ordering dependencies.
+  const addedEdges = new Set<string>();
+
+  // Add edges and check for self-references
+  for (const edge of jdm.edges) {
+    if (!nodeMap.has(edge.sourceId) || !nodeMap.has(edge.targetId)) {
+      const sourceNode = nodeMap.get(edge.sourceId);
+      const targetNode = nodeMap.get(edge.targetId);
+      throw new CompilationError(
+        `Invalid edge "${edge.id}": references non-existent node`,
+        ErrorCode.INVALID_EDGE,
+        {
+          nodeId: edge.sourceId,
+          nodeName: sourceNode?.name ?? targetNode?.name,
+          field: !nodeMap.has(edge.sourceId) ? 'sourceId' : 'targetId',
+        },
+      );
+    }
+
+    // Check for self-references (edge where source equals target)
+    if (edge.sourceId === edge.targetId) {
+      const node = graph.getNodeAttributes(edge.sourceId);
+      const location: SourceLocation = { nodeId: edge.sourceId, nodeName: node.name };
+      throw new CompilationError(
+        `Self-reference detected: node "${node.name || edge.sourceId}" references itself through edge "${edge.id}"`,
+        ErrorCode.CYCLE_DETECTED,
+        location,
+      );
+    }
+
+    // For topological ordering, we only need one edge between any two nodes.
+    // Switch nodes may have multiple edges to the same target (via different handles).
+    // We track the edge pair to avoid duplicates while preserving all edges in jdm.edges
+    // for the switch node compilation to use.
+    const edgePairKey = `${edge.sourceId}->${edge.targetId}`;
+    if (!addedEdges.has(edgePairKey)) {
+      graph.addEdgeWithKey(edge.id, edge.sourceId, edge.targetId, edge);
+      addedEdges.add(edgePairKey);
+    }
+  }
+
+  return graph;
+}
+
+/**
+ * Find a cycle path in the graph using DFS. Graphology's cycle detection only returns a boolean,
+ * but we need the actual cycle path to provide better error messages showing the problematic node
+ * sequence to users.
+ *
+ * @param graph - The graph to search
+ * @returns Array of node IDs representing the cycle, or null if no cycle
+ */
+function findCyclePath(graph: JDMGraph): string[] | null {
+  const visited = new Set<string>();
+  const recursionStack = new Set<string>();
+  const parentMap = new Map<string, string | null>();
+
+  function dfs(nodeId: string, path: string[]): string[] | null {
+    visited.add(nodeId);
+    recursionStack.add(nodeId);
+    path.push(nodeId);
+
+    const neighbors = graph.outNeighbors(nodeId);
+    for (const neighborId of neighbors) {
+      if (!visited.has(neighborId)) {
+        parentMap.set(neighborId, nodeId);
+        const cycle = dfs(neighborId, path);
+        if (cycle) {
+          return cycle;
+        }
+      } else if (recursionStack.has(neighborId)) {
+        // Found a back edge - reconstruct the cycle path
+        // Path contains full traversal, but cycle only starts where we revisit a node.
+        // Slicing gives just the cycle portion (e.g., A→B→C→B extracts B→C→B).
+        const startIndex = path.indexOf(neighborId);
+        const cycle = [...path.slice(startIndex), neighborId];
+        return cycle;
+      }
+    }
+
+    recursionStack.delete(nodeId);
+    path.pop();
+    return null;
+  }
+
+  // Start DFS from each unvisited node
+  for (const nodeId of graph.nodes()) {
+    if (!visited.has(nodeId)) {
+      const cycle = dfs(nodeId, []);
+      if (cycle) {
+        return cycle;
+      }
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Format a cycle path as a readable string.
+ *
+ * @param cycle - Array of node IDs representing a cycle
+ * @param graph - The graph to get node names from
+ * @returns Formatted string like "Node1 -> Node2 -> Node3 -> Node1"
+ */
+function formatCyclePath(cycle: string[], graph: JDMGraph): string {
+  return cycle
+    .map((nodeId) => {
+      const node = graph.getNodeAttributes(nodeId);
+      return node.name || nodeId;
+    })
+    .join(' -> ');
+}
+
+export function validateGraph(graph: JDMGraph): void {
+  // Check for cycles using DFS to find the actual cycle path
+  const cyclePath = findCyclePath(graph);
+  if (cyclePath) {
+    const formattedPath = formatCyclePath(cyclePath, graph);
+    throw new CompilationError(
+      `Circular dependency detected: ${formattedPath}`,
+      ErrorCode.CYCLE_DETECTED,
+      { nodeId: cyclePath[0], nodeName: graph.getNodeAttributes(cyclePath[0]).name },
+    );
+  }
+
+  // Check for single input node
+  const inputNodes: string[] = [];
+  const outputNodes: string[] = [];
+
+  graph.forEachNode((nodeId, attrs) => {
+    if (attrs.type === NodeType.INPUT) {
+      inputNodes.push(nodeId);
+    }
+    if (attrs.type === NodeType.OUTPUT) {
+      outputNodes.push(nodeId);
+    }
+  });
+
+  if (inputNodes.length !== 1) {
+    // If there are multiple input nodes, include the first one in the location
+    const firstInputNode = inputNodes.length > 0 ? graph.getNodeAttributes(inputNodes[0]) : null;
+    throw new CompilationError(
+      `Expected exactly 1 input node, found ${inputNodes.length}`,
+      ErrorCode.MULTIPLE_INPUT_NODES,
+      firstInputNode ? { nodeId: firstInputNode.id, nodeName: firstInputNode.name } : undefined,
+    );
+  }
+  if (outputNodes.length === 0) {
+    throw new CompilationError(
+      'Expected at least 1 output node, found 0',
+      ErrorCode.MISSING_OUTPUT_NODE,
+      { field: 'outputNode' },
+    );
+  }
+}
+
+/**
+ * Get nodes in topological order for evaluation.
+ * This ensures dependencies are evaluated before dependents.
+ */
+export function getEvaluationOrder(graph: JDMGraph): string[] {
+  return topologicalSort(graph);
+}
+
+/**
+ * Get all nodes that feed into a given node.
+ */
+export function getInputNodes(graph: JDMGraph, nodeId: string): JDMNode[] {
+  return graph.inNeighbors(nodeId).map((id) => graph.getNodeAttributes(id));
+}
+
+/**
+ * Get all nodes that a given node feeds into.
+ */
+export function getOutputNodes(graph: JDMGraph, nodeId: string): JDMNode[] {
+  return graph.outNeighbors(nodeId).map((id) => graph.getNodeAttributes(id));
+}

package/src/compiler/index.ts

@@ -0,0 +1,199 @@
+// src/compiler/index.ts
+import type { TSchema } from '@sinclair/typebox';
+import { parseJDM, type JDMDecision } from './parser';
+import { compileDecision } from './codegen';
+import { compileAssemblyScript } from './build';
+import { flattenSchema, computeSchemaHash } from './schema';
+import { generateMarshalCode, generateValidationCode } from './marshal-gen';
+import type {
+  CompilerOptions,
+  CompilationResult,
+  CompilationContext,
+  NoMatchBehavior,
+} from './types';
+import { readFileSync } from 'fs';
+import path from 'path';
+
+/**
+ * Type guard for Node.js file system errors.
+ */
+function isFileNotFoundError(error: unknown): boolean {
+  return error !== null && typeof error === 'object' && 'code' in error && error.code === 'ENOENT';
+}
+
+/**
+ * Creates a filesystem-based loader for sub-decision JDM files.
+ *
+ * This loader performs I/O by reading from the filesystem and may throw filesystem errors
+ * (e.g., ENOENT for missing files, EACCES for permission denied).
+ *
+ * Supports both zen-engine compatibility (flat structure in zen-reference/) and organized test
+ * structure (nested by feature in sub-decisions/). This dual approach allows us to port
+ * zen-engine fixtures without reorganization while providing better organization for our own
+ * tests.
+ *
+ * @param testDataRoot - Optional root directory for test data. Defaults to "test-data/" in current working directory.
+ * @returns A loader function that reads JDM files from the filesystem
+ * @throws Error if file is not found in any search path
+ * @throws Error for other filesystem errors (permissions, invalid content, etc.)
+ */
+function createFilesystemLoader(testDataRoot?: string): (key: string) => JDMDecision {
+  const root = testDataRoot || path.join(process.cwd(), 'test-data');
+  const possiblePaths = [
+    root,
+    path.join(root, 'sub-decisions'),
+    path.join(root, 'sub-decisions/basic'),
+    path.join(root, 'sub-decisions/simple-multi'),
+    path.join(root, 'sub-decisions/complex-multi'),
+    path.join(root, 'sub-decisions/diamond'),
+    path.join(root, 'sub-decisions/error-propagation'),
+    path.join(root, 'zen-reference'),
+  ];
+
+  return (key: string): JDMDecision => {
+    for (const basePath of possiblePaths) {
+      try {
+        const filePath = path.join(basePath, key);
+        const content = readFileSync(filePath, 'utf-8');
+        return parseJDM(content);
+      } catch (error) {
+        // Only try next path for file-not-found errors
+        // Let other errors (parse errors, permission denied) propagate immediately
+        if (isFileNotFoundError(error)) {
+          continue;
+        }
+        throw error;
+      }
+    }
+    throw new Error(
+      `Failed to load sub-decision "${key}": not found in any search path (${possiblePaths.join(', ')})`,
+    );
+  };
+}
+
+// Re-export parser, graph, optimizer, runtime, validation, types, and errors
+export * from './parser';
+export * from './graph';
+export * from './types';
+export * from './errors';
+export * from './optimizer';
+export * from './runtime';
+export * from './runtime-codegen';
+
+// Validation modules - split by concern:
+// - compile-time-validation: Static analysis of JDM structure and references
+// - runtime-validation-codegen: Validation code that executes at runtime
+export * from './compile-time-validation';
+export * from './runtime-validation-codegen';
+
+// Backward compatibility: re-export from input-validation (deprecated)
+export * from './input-validation';
+
+// Export cache utilities for advanced usage
+export {
+  clearCache,
+  getCacheStats,
+  pruneCache,
+  isCacheEnabled,
+  getCacheDirectory,
+  getCacheHealth,
+} from './cache';
+
+/**
+ * Main entry point: Compile JDM to WASM with schema-driven marshaling.
+ *
+ * @example
+ * const result = await compile({
+ *   inputSchema: InputSchema,
+ *   outputSchema: OutputSchema,
+ *   jdm: jdmJson,
+ *   optimize: true,
+ * });
+ */
+export async function compile(options: {
+  inputSchema: TSchema;
+  outputSchema: TSchema;
+  jdm: string | JDMDecision;
+  optimize?: boolean;
+  debug?: 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?: CompilerOptions['loadDecision'];
+  /** Optional testDataRoot path for default loader to search */
+  testDataRoot?: string;
+}): Promise<CompilationResult> {
+  const opts: CompilerOptions = {
+    optimize: options.optimize ?? true,
+    debug: options.debug ?? false,
+    // Validation disabled during compilation for performance (compile-time checks).
+    // Schema validation is generated as separate code (generateValidationCode()) that
+    // the runtime can call before evaluation.
+    validate: false,
+    noMatchBehavior: options.noMatchBehavior,
+  };
+
+  // Phase 1: Parse and validate JDM
+  const parsed = parseJDM(options.jdm);
+
+  // Phase 2: Flatten schemas to memory layout
+  const inputLayout = flattenSchema(options.inputSchema);
+  const outputLayout = flattenSchema(options.outputSchema);
+
+  // Phase 3: Compute schema hash for runtime validation
+  const schemaHash = computeSchemaHash(options.inputSchema, options.outputSchema);
+
+  // Phase 4: Build compilation context
+  const context: CompilationContext = {
+    jdm: parsed,
+    inputSchema: options.inputSchema,
+    outputSchema: options.outputSchema,
+    inputLayout,
+    outputLayout,
+    schemaHash,
+    options: opts,
+    parseExpression: (expr) => parseStandardExpression(expr),
+    parseUnaryExpression: (expr) => parseUnaryExpressionImpl(expr),
+    getUniqueId: createIdGenerator(),
+    loadDecision: options.loadDecision ?? createFilesystemLoader(options.testDataRoot),
+    // Avoids duplicate compilation when multiple nodes reference same sub-decision
+    compiledSubDecisions: new Map(),
+    // Detects circular references to prevent infinite loops during compilation
+    decisionPath: [],
+    helperFunctions: new Map(),
+  };
+
+  // Phase 5: Generate AssemblyScript code
+  const asCode = compileDecision(parsed, context);
+
+  // Phase 6: Compile to WASM
+  const { binary, wat } = await compileAssemblyScript(asCode, opts);
+
+  // Phase 7: Generate JS marshaling code
+  const marshalCode = generateMarshalCode(inputLayout, outputLayout, schemaHash);
+  const validationCode = generateValidationCode(options.inputSchema);
+
+  return {
+    wasm: binary,
+    schemaHash,
+    marshalCode,
+    validationCode,
+    wat: opts.debug ? wat : undefined,
+    assemblyScript: opts.debug ? asCode : undefined,
+  };
+}
+
+function createIdGenerator(): (prefix: string) => string {
+  const counters = new Map<string, number>();
+  return (prefix: string) => {
+    const count = counters.get(prefix) ?? 0;
+    counters.set(prefix, count + 1);
+    return `${prefix}_${count}`;
+  };
+}
+
+// Import parse functions
+import {
+  parseStandardExpression,
+  parseUnaryExpression as parseUnaryExpressionImpl,
+} from './unary-parser';

package/src/compiler/input-validation.ts

@@ -0,0 +1,33 @@
+/**
+ * Input/Output validation for decision models.
+ *
+ * @deprecated This module re-exports from compile-time-validation.ts and
+ * runtime-validation-codegen.ts for backward compatibility. Import directly
+ * from those modules instead:
+ *
+ * - compile-time-validation.ts: Static analysis of JDM structure and references
+ *   (collectIdentifiers, validateInputReferences, validateAllInputReferences, etc.)
+ *
+ * - runtime-validation-codegen.ts: Validation code that executes at runtime
+ *   (validateRuntimeInputs, validateRuntimeOutputs)
+ */
+
+// Re-export compile-time validation functions
+export {
+  collectIdentifiers,
+  validateInputReferences,
+  collectOutputAssignments,
+  validateOutputReferences,
+  validateAllInputReferences,
+  validateAllOutputReferences,
+} from './compile-time-validation';
+
+// Re-export runtime validation functions and types
+export {
+  validateRuntimeInputs,
+  validateRuntimeOutputs,
+  validateRuntimeInputsDetailed,
+  validateRuntimeOutputsDetailed,
+  type ValidationError,
+  type ValidationResult,
+} from './runtime-validation-codegen';

package/src/compiler/marshal-gen.ts

@@ -0,0 +1,21 @@
+/**
+ * Marshaling Code Generation - Backward Compatibility Module
+ *
+ * This module re-exports code generation utilities from their focused modules
+ * for backward compatibility. New code should import directly from the specific
+ * modules in src/compiler/codegen/:
+ *
+ * - codegen/js-marshal.ts: JavaScript marshaling code generation
+ * - codegen/js-validation.ts: JavaScript validation code generation
+ *
+ * @deprecated Import from specific codegen modules instead:
+ *   - `import { generateMarshalCode } from "./codegen/js-marshal"`
+ *   - `import { generateValidationCode } from "./codegen/js-validation"`
+ */
+
+// Re-export all code generation functions for backward compatibility
+export {
+  generateMarshalCode,
+  generateValidationCode,
+  _generateUnmarshalBody,
+} from './codegen/index';

package/src/compiler/nodes/context-resolvers.ts

@@ -0,0 +1,197 @@
+// ============================================================================
+// Context Resolver Strategy Pattern
+// ============================================================================
+//
+// The ContextResolver interface provides a strategy for resolving identifiers
+// and dollar references in different compilation contexts. This replaces three
+// separate compilation functions with a single unified function plus small
+// strategy implementations.
+//
+// Three modes:
+// 1. Standard: $ -> ctx.get("$"), identifiers -> ctx.get("name")
+// 2. LocalDollar: $ -> Value.Object(dollarVar), identifiers -> ctx.get("name")
+// 3. Scoped: $ -> Value.Object(resultVar), identifiers -> scopedCtx.get("name")
+
+/**
+ * Strategy interface for resolving context references during expression compilation.
+ *
+ * Different compilation contexts require different resolutions:
+ * - In standard expressions, $ refers to the global context
+ * - In expression nodes, $ refers to the local result object being built
+ * - In scoped expressions (inputField), identifiers resolve from a scoped context
+ */
+export interface ContextResolver {
+  /** Resolve an identifier reference (e.g., "firstName") */
+  resolveIdentifier(name: string): string;
+
+  /** Resolve a $ reference */
+  resolveDollarRef(): string;
+
+  /** Resolve a # reference (current element in higher-order functions) */
+  resolveHashRef(): string;
+
+  /** Resolve a member access path rooted at $ (e.g., "$.foo.bar" returns "foo.bar") */
+  resolveDollarPath(path: string): string;
+
+  /** Resolve a $nodes.X.Y path */
+  resolveNodesPath(path: string): string;
+
+  /** Get the context variable name for use in helper functions */
+  getContextVar(): string;
+
+  /** Create a child resolver for use inside helper functions (e.g., object literals) */
+  createChildResolver(): ContextResolver;
+
+  /** Get extra parameters for generated helper function signatures */
+  getHelperParams(): string;
+
+  /** Get extra arguments for calls to generated helper functions */
+  getHelperArgs(): string;
+}
+
+/**
+ * Standard context resolver: $ and identifiers resolve from the global context.
+ * Used in switch conditions, decision tables, and other standard expressions.
+ */
+export class StandardContextResolver implements ContextResolver {
+  resolveIdentifier(name: string): string {
+    return `ctx.get("${name}")`;
+  }
+
+  resolveDollarRef(): string {
+    return `ctx.get("$")`;
+  }
+
+  resolveHashRef(): string {
+    return `ctx.get("#")`;
+  }
+
+  resolveDollarPath(path: string): string {
+    // In standard mode, $.foo.bar -> getProperty(ctx.get("$"), "foo", "bar")
+    // Actually use nested getProperty calls for each segment
+    const segments = path.split('.');
+    let result = `ctx.get("$")`;
+    for (const segment of segments) {
+      result = `getProperty(${result}, "${segment}")`;
+    }
+    return result;
+  }
+
+  resolveNodesPath(path: string): string {
+    return `ctx.get("${path}")`;
+  }
+
+  getContextVar(): string {
+    return 'ctx';
+  }
+
+  createChildResolver(): ContextResolver {
+    // Child is same as parent in standard mode
+    return this;
+  }
+
+  getHelperParams(): string {
+    return '';
+  }
+
+  getHelperArgs(): string {
+    return '';
+  }
+}
+
+/**
+ * Local dollar resolver: $ refers to a local Map variable (e.g., "result").
+ * Used in expression nodes where $ references the output being built.
+ */
+export class LocalDollarContextResolver implements ContextResolver {
+  constructor(private dollarVar: string = 'result') {}
+
+  resolveIdentifier(name: string): string {
+    return `ctx.get("${name}")`;
+  }
+
+  resolveDollarRef(): string {
+    return `Value.Object(${this.dollarVar})`;
+  }
+
+  resolveHashRef(): string {
+    return `ctx.get("#")`;
+  }
+
+  resolveDollarPath(path: string): string {
+    // $.foo.bar looks up "foo.bar" as a flat key in the local result map
+    // Expression nodes store keys like "eligibility.specialOffers" as flat strings
+    return `(${this.dollarVar}.has("${path}") ? ${this.dollarVar}.get("${path}") : Value.Null())`;
+  }
+
+  resolveNodesPath(path: string): string {
+    return `ctx.get("${path}")`;
+  }
+
+  getContextVar(): string {
+    return 'ctx';
+  }
+
+  createChildResolver(): ContextResolver {
+    // Child resolver references 'parentResult' to maintain access to outer scope
+    // Example: {a: 5, nested: {b: $.a}} - nested object's $.a refers to outer result
+    return new LocalDollarContextResolver('parentResult');
+  }
+
+  getHelperParams(): string {
+    return ', parentResult: Map<string, Value>';
+  }
+
+  getHelperArgs(): string {
+    return `, ${this.dollarVar}`;
+  }
+}
+
+/**
+ * Scoped context resolver: identifiers resolve from a scoped context variable.
+ * Used for inputField scoping and loop mode where a subset of the context is available.
+ */
+export class ScopedContextResolver implements ContextResolver {
+  constructor(
+    private ctxVar: string = 'scopedCtx',
+    private resultVar: string = 'itemResult',
+  ) {}
+
+  resolveIdentifier(name: string): string {
+    return `${this.ctxVar}.get("${name}")`;
+  }
+
+  resolveDollarRef(): string {
+    return `Value.Object(${this.resultVar})`;
+  }
+
+  resolveHashRef(): string {
+    return `${this.ctxVar}.get("#")`;
+  }
+
+  resolveDollarPath(path: string): string {
+    // $.foo looks up "foo" in the local result variable
+    return `(${this.resultVar}.has("${path}") ? ${this.resultVar}.get("${path}") : Value.Null())`;
+  }
+
+  resolveNodesPath(path: string): string {
+    return `${this.ctxVar}.get("${path}")`;
+  }
+
+  getContextVar(): string {
+    return this.ctxVar;
+  }
+
+  createChildResolver(): ContextResolver {
+    // In scoped context, child keeps the same context var and result var
+    return this;
+  }
+
+  getHelperParams(): string {
+    return `, ${this.ctxVar}: Context, ${this.resultVar}: Map<string, Value>`;
+  }
+
+  getHelperArgs(): string {
+    return `, ${this.ctxVar}, ${this.resultVar}`;
+  }
+}