@divmain/jdm-asm 0.2.0 → 0.2.3

package/src/compiler/graph.ts

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

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

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

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

@@ -1,197 +0,0 @@
-// ============================================================================
-// 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}`;
-  }
-}