@divmain/jdm-asm 0.2.0

package/tests/helpers/test-harness.ts

@@ -0,0 +1,28 @@
+/**
+ * Legacy test-harness.ts - Re-exports for backward compatibility
+ *
+ * This file has been split into focused helpers:
+ * - test-harness-wasm.ts: WASM-only testing (compilation, execution, marshaling)
+ * - test-harness-comparison.ts: zen-engine compatibility testing
+ *
+ * All exports are preserved for backward compatibility with existing tests.
+ */
+
+// Re-export everything from the new focused modules
+export {
+  compile,
+  evaluateCompiled,
+  inferSchema,
+  runWasmTest,
+  runSimpleWasmTest,
+  type WasmTestConfig,
+  type SimpleWasmTestConfig,
+} from './test-harness-wasm';
+
+export {
+  runCompatibilityTest,
+  runSimpleCompatibilityTest,
+  matchers,
+  type TestConfig,
+  type SimpleTestConfig,
+} from './test-harness-comparison';

package/tests/helpers/wasm-test.ts

@@ -0,0 +1,659 @@
+/**
+ * WASM test utilities for compiling and evaluating JDM decisions.
+ *
+ * These helpers simplify the process of compiling JDM to WASM and
+ * evaluating decisions in tests, reducing boilerplate and ensuring
+ * consistent test patterns.
+ *
+ * @module tests/helpers/wasm-test
+ */
+
+import { readFileSync } from 'fs';
+import { type TSchema, Type } from '@sinclair/typebox';
+import { compile, type JDMDecision, type CompilationResult } from '../../src/compiler';
+import { createCompiledDecision, type CompiledDecision } from '../../src/compiler/runtime';
+
+/**
+ * Options for compiling and evaluating JDM.
+ */
+export interface CompileAndEvaluateOptions {
+  /**
+   * Input schema for the decision.
+   * If not provided, will be inferred from the input value.
+   */
+  inputSchema?: TSchema;
+
+  /**
+   * Output schema for the decision.
+   * If not provided, will be inferred from expected shape or use a generic object.
+   */
+  outputSchema?: TSchema;
+
+  /**
+   * Enable debug mode for compilation (includes AssemblyScript source and WAT in result).
+   * @default false
+   */
+  debug?: boolean;
+
+  /**
+   * Skip input validation during evaluation.
+   * @default false
+   */
+  skipValidation?: boolean;
+}
+
+/**
+ * Result of compileAndEvaluate operations.
+ */
+export interface EvaluationResult<T = unknown> {
+  /** The evaluation result */
+  result: T;
+  /** The compiled decision (can be reused for additional evaluations) */
+  decision: CompiledDecision;
+  /** The raw compilation result */
+  compilation: CompilationResult;
+}
+
+/**
+ * Compile a JDM file and evaluate with the given input.
+ *
+ * This is the primary helper for file-based JDM tests. It handles:
+ * - Loading the JDM file
+ * - Schema inference if not provided
+ * - Compilation to WASM
+ * - Evaluation with the input
+ *
+ * @param jdmPath - Path to the JDM JSON file
+ * @param input - Input data for evaluation
+ * @param options - Optional compilation/evaluation options
+ * @returns The evaluation result
+ *
+ * @example
+ * ```typescript
+ * // Simple usage
+ * const result = await compileAndEvaluate(
+ *   'test-data/simple-decision.json',
+ *   { age: 25, income: 50000 }
+ * );
+ * expect(result).toEqual({ eligible: true });
+ *
+ * // With explicit schemas
+ * const result = await compileAndEvaluate(
+ *   'path/to/decision.json',
+ *   { x: 10 },
+ *   {
+ *     inputSchema: Type.Object({ x: Type.Number() }),
+ *     outputSchema: Type.Object({ y: Type.Number() }),
+ *   }
+ * );
+ * ```
+ */
+export async function compileAndEvaluate<I extends Record<string, unknown>, O = unknown>(
+  jdmPath: string,
+  input: I,
+  options: CompileAndEvaluateOptions = {},
+): Promise<O> {
+  const jdmContent = readFileSync(jdmPath, 'utf-8');
+  const jdm = JSON.parse(jdmContent) as JDMDecision;
+  return compileAndEvaluateInline(jdm, input, options);
+}
+
+/**
+ * Compile an inline JDM object and evaluate with the given input.
+ *
+ * Use this when you want to define the JDM directly in your test
+ * without a separate file.
+ *
+ * @param jdm - The JDM decision object
+ * @param input - Input data for evaluation
+ * @param options - Optional compilation/evaluation options
+ * @returns The evaluation result
+ *
+ * @example
+ * ```typescript
+ * const jdm = createExpressionJDM([
+ *   { key: 'doubled', value: 'x * 2' }
+ * ]);
+ * const result = await compileAndEvaluateInline(jdm, { x: 21 });
+ * expect(result).toEqual({ doubled: 42 });
+ * ```
+ */
+export async function compileAndEvaluateInline<I extends Record<string, unknown>, O = unknown>(
+  jdm: JDMDecision | object,
+  input: I,
+  options: CompileAndEvaluateOptions = {},
+): Promise<O> {
+  const { debug = false } = options;
+
+  // Infer schemas if not provided
+  const inputSchema = options.inputSchema ?? inferSchema(input);
+  const outputSchema = options.outputSchema ?? Type.Object({});
+
+  // Compile to WASM
+  const compiled = await compile({
+    jdm: jdm as JDMDecision,
+    inputSchema,
+    outputSchema,
+    debug,
+  });
+
+  // Create decision instance and evaluate
+  const decision = await createCompiledDecision(
+    compiled,
+    // FIXME: Double undefined - second param should be validation schema or options object
+    options.skipValidation ? undefined : undefined,
+  );
+
+  const result = await decision.evaluate<I, O>(input);
+  return result;
+}
+
+/**
+ * Compile and evaluate with full result details.
+ *
+ * Returns the compiled decision for potential reuse, along with
+ * the compilation result for debugging.
+ *
+ * @param jdm - The JDM decision object or path to file
+ * @param input - Input data for evaluation
+ * @param options - Optional compilation/evaluation options
+ * @returns Full evaluation result including decision and compilation
+ *
+ * @example
+ * ```typescript
+ * const { result, decision, compilation } = await compileAndEvaluateFull(
+ *   jdm,
+ *   input,
+ *   { debug: true }
+ * );
+ *
+ * // Reuse decision for multiple evaluations
+ * const result2 = await decision.evaluate({ x: 100 });
+ *
+ * // Debug: inspect generated code
+ * console.log(compilation.assemblyScript);
+ * ```
+ */
+export async function compileAndEvaluateFull<I extends Record<string, unknown>, O = unknown>(
+  jdm: JDMDecision | object | string,
+  input: I,
+  options: CompileAndEvaluateOptions = {},
+): Promise<EvaluationResult<O>> {
+  const { debug = false } = options;
+
+  // Load JDM if path provided
+  const jdmObj =
+    typeof jdm === 'string'
+      ? (JSON.parse(readFileSync(jdm, 'utf-8')) as JDMDecision)
+      : (jdm as JDMDecision);
+
+  // Infer schemas if not provided
+  const inputSchema = options.inputSchema ?? inferSchema(input);
+  const outputSchema = options.outputSchema ?? Type.Object({});
+
+  // Compile to WASM
+  const compiled = await compile({
+    jdm: jdmObj,
+    inputSchema,
+    outputSchema,
+    debug,
+  });
+
+  // Create decision instance and evaluate
+  const decision = await createCompiledDecision(compiled);
+  const result = await decision.evaluate<I, O>(input);
+
+  return {
+    result,
+    decision,
+    compilation: compiled,
+  };
+}
+
+/**
+ * Create a minimal JDM decision with expression nodes.
+ *
+ * This helper creates a simple JDM structure for testing expression
+ * evaluation without needing to define the full JDM JSON.
+ *
+ * @param expressions - Array of key-value expressions to evaluate
+ * @returns A complete JDM decision object
+ *
+ * @example
+ * ```typescript
+ * // Single expression
+ * const jdm = createExpressionJDM([{ key: 'result', value: 'x + y' }]);
+ *
+ * // Multiple expressions
+ * const jdm = createExpressionJDM([
+ *   { key: 'sum', value: 'a + b' },
+ *   { key: 'product', value: 'a * b' },
+ *   { key: 'isPositive', value: 'a > 0 and b > 0' },
+ * ]);
+ * ```
+ */
+export function createExpressionJDM(
+  expressions: Array<{ key: string; value: string }>,
+): JDMDecision {
+  return {
+    nodes: [
+      {
+        id: 'input-1',
+        type: 'inputNode' as any,
+        position: { x: 0, y: 0 },
+        name: 'Request',
+      },
+      {
+        id: 'expr-1',
+        type: 'expressionNode' as any,
+        position: { x: 200, y: 0 },
+        name: 'Expression',
+        content: {
+          expressions: expressions.map((e, i) => ({
+            id: `expr-${i}`,
+            key: e.key,
+            value: e.value,
+          })),
+        },
+      },
+      {
+        id: 'output-1',
+        type: 'outputNode' as any,
+        position: { x: 400, y: 0 },
+        name: 'Response',
+      },
+    ],
+    edges: [
+      {
+        id: 'edge-1',
+        sourceId: 'input-1',
+        targetId: 'expr-1',
+        type: 'edge',
+      },
+      {
+        id: 'edge-2',
+        sourceId: 'expr-1',
+        targetId: 'output-1',
+        type: 'edge',
+      },
+    ],
+  };
+}
+
+/**
+ * Create a JDM decision with a decision table.
+ *
+ * This helper creates a JDM with a decision table for testing
+ * rule-based decision logic.
+ *
+ * @param rules - Array of rules with inputs and outputs
+ * @param hitPolicy - Hit policy for the decision table
+ * @returns A complete JDM decision object
+ *
+ * @example
+ * ```typescript
+ * const jdm = createDecisionTableJDM(
+ *   [
+ *     { inputs: { age: '>= 18' }, outputs: { category: '"adult"' } },
+ *     { inputs: { age: '< 18' }, outputs: { category: '"minor"' } },
+ *   ],
+ *   'first'
+ * );
+ * ```
+ */
+export function createDecisionTableJDM(
+  rules: Array<{
+    inputs: Record<string, string>;
+    outputs: Record<string, string>;
+  }>,
+  hitPolicy: 'first' | 'collect' = 'first',
+): JDMDecision {
+  // Extract input and output field names from rules
+  const inputFields = new Set<string>();
+  const outputFields = new Set<string>();
+
+  for (const rule of rules) {
+    Object.keys(rule.inputs).forEach((k) => inputFields.add(k));
+    Object.keys(rule.outputs).forEach((k) => outputFields.add(k));
+  }
+
+  // Create input columns
+  const inputs = Array.from(inputFields).map((field, i) => ({
+    id: `input-col-${i}`,
+    name: field,
+    field,
+    type: 'expression' as const,
+  }));
+
+  // Create output columns
+  const outputs = Array.from(outputFields).map((field, i) => ({
+    id: `output-col-${i}`,
+    name: field,
+    field,
+    type: 'expression' as const,
+  }));
+
+  // Create rules
+  const tableRules = rules.map((rule, i) => ({
+    _id: `rule-${i}`,
+    ...Object.fromEntries(inputs.map((inp) => [inp.id, rule.inputs[inp.field] ?? ''])),
+    ...Object.fromEntries(outputs.map((out) => [out.id, rule.outputs[out.field] ?? ''])),
+  }));
+
+  return {
+    nodes: [
+      {
+        id: 'input-1',
+        type: 'inputNode' as any,
+        position: { x: 0, y: 0 },
+        name: 'Request',
+      },
+      {
+        id: 'table-1',
+        type: 'decisionTableNode' as any,
+        position: { x: 200, y: 0 },
+        name: 'Decision Table',
+        content: {
+          hitPolicy,
+          inputs,
+          outputs,
+          rules: tableRules,
+        },
+      },
+      {
+        id: 'output-1',
+        type: 'outputNode' as any,
+        position: { x: 400, y: 0 },
+        name: 'Response',
+      },
+    ],
+    edges: [
+      {
+        id: 'edge-1',
+        sourceId: 'input-1',
+        targetId: 'table-1',
+        type: 'edge',
+      },
+      {
+        id: 'edge-2',
+        sourceId: 'table-1',
+        targetId: 'output-1',
+        type: 'edge',
+      },
+    ],
+  };
+}
+
+/**
+ * Create a JDM decision with a switch node.
+ *
+ * @param conditions - Array of condition/content pairs
+ * @returns A complete JDM decision object
+ *
+ * @example
+ * ```typescript
+ * const jdm = createSwitchJDM([
+ *   { condition: 'score >= 90', expressions: [{ key: 'grade', value: '"A"' }] },
+ *   { condition: 'score >= 80', expressions: [{ key: 'grade', value: '"B"' }] },
+ *   { condition: 'true', expressions: [{ key: 'grade', value: '"C"' }] }, // default
+ * ]);
+ * ```
+ */
+export function createSwitchJDM(
+  conditions: Array<{
+    condition: string;
+    expressions: Array<{ key: string; value: string }>;
+  }>,
+): JDMDecision {
+  const nodes: any[] = [
+    {
+      id: 'input-1',
+      type: 'inputNode',
+      position: { x: 0, y: 0 },
+      name: 'Request',
+    },
+    {
+      id: 'switch-1',
+      type: 'switchNode',
+      position: { x: 200, y: 0 },
+      name: 'Switch',
+      content: {
+        hitPolicy: 'first',
+        statements: conditions.map((c, i) => ({
+          id: `stmt-${i}`,
+          condition: c.condition,
+        })),
+      },
+    },
+    {
+      id: 'output-1',
+      type: 'outputNode',
+      position: { x: 600, y: 0 },
+      name: 'Response',
+    },
+  ];
+
+  const edges: any[] = [
+    {
+      id: 'edge-input-switch',
+      sourceId: 'input-1',
+      targetId: 'switch-1',
+      type: 'edge',
+    },
+  ];
+
+  // Create expression nodes for each condition
+  conditions.forEach((c, i) => {
+    const exprNodeId = `expr-${i}`;
+    nodes.push({
+      id: exprNodeId,
+      type: 'expressionNode',
+      position: { x: 400, y: i * 100 },
+      name: `Expression ${i + 1}`,
+      content: {
+        expressions: c.expressions.map((e, j) => ({
+          id: `expr-${i}-${j}`,
+          key: e.key,
+          value: e.value,
+        })),
+      },
+    });
+
+    // Edge from switch to expression (with sourceHandle for the statement)
+    edges.push({
+      id: `edge-switch-expr-${i}`,
+      sourceId: 'switch-1',
+      sourceHandle: `stmt-${i}`,
+      targetId: exprNodeId,
+      type: 'edge',
+    });
+
+    // Edge from expression to output
+    edges.push({
+      id: `edge-expr-output-${i}`,
+      sourceId: exprNodeId,
+      targetId: 'output-1',
+      type: 'edge',
+    });
+  });
+
+  return { nodes, edges };
+}
+
+/**
+ * Infer a TypeBox schema from a value.
+ *
+ * This is a simple schema inference for testing purposes.
+ * For production use, prefer explicit schemas.
+ *
+ * @param value - The value to infer schema from
+ * @returns A TypeBox schema matching the value structure
+ */
+export function inferSchema(value: unknown): TSchema {
+  if (value === null) {
+    return Type.Null();
+  }
+  if (value === undefined) {
+    return Type.Unknown();
+  }
+  if (typeof value === 'boolean') {
+    return Type.Boolean();
+  }
+  if (typeof value === 'number') {
+    return Type.Number();
+  }
+  if (typeof value === 'string') {
+    return Type.String();
+  }
+
+  if (Array.isArray(value)) {
+    if (value.length === 0) {
+      return Type.Array(Type.Unknown());
+    }
+    // Use first element to infer array type
+    return Type.Array(inferSchema(value[0]));
+  }
+
+  if (typeof value === 'object') {
+    const properties: Record<string, TSchema> = {};
+    for (const [key, val] of Object.entries(value)) {
+      properties[key] = inferSchema(val);
+    }
+    return Type.Object(properties);
+  }
+
+  return Type.Unknown();
+}
+
+/**
+ * Compile a JDM decision and return the compiled result.
+ *
+ * Use this when you need access to the compilation result
+ * without immediately evaluating.
+ *
+ * @param jdm - The JDM decision object or path to file
+ * @param options - Compilation options
+ * @returns The compilation result
+ *
+ * @example
+ * ```typescript
+ * const compiled = await compileJDM(jdm, {
+ *   inputSchema: MyInputSchema,
+ *   outputSchema: MyOutputSchema,
+ *   debug: true,
+ * });
+ *
+ * // Inspect generated code
+ * console.log(compiled.assemblyScript);
+ *
+ * // Create multiple decision instances
+ * const decision1 = await createCompiledDecision(compiled);
+ * const decision2 = await createCompiledDecision(compiled);
+ * ```
+ */
+export async function compileJDM(
+  jdm: JDMDecision | object | string,
+  options: {
+    inputSchema?: TSchema;
+    outputSchema?: TSchema;
+    debug?: boolean;
+  } = {},
+): Promise<CompilationResult> {
+  const { debug = false } = options;
+
+  // Load JDM if path provided
+  const jdmObj =
+    typeof jdm === 'string'
+      ? (JSON.parse(readFileSync(jdm, 'utf-8')) as JDMDecision)
+      : (jdm as JDMDecision);
+
+  // Default schemas
+  const inputSchema = options.inputSchema ?? Type.Object({});
+  const outputSchema = options.outputSchema ?? Type.Object({});
+
+  return compile({
+    jdm: jdmObj,
+    inputSchema,
+    outputSchema,
+    debug,
+  });
+}
+
+/**
+ * Test assertion helper for comparing evaluation results.
+ *
+ * Handles floating point comparison and nested object comparison.
+ *
+ * @param actual - The actual evaluation result
+ * @param expected - The expected result
+ * @param message - Optional error message prefix
+ */
+export function assertEvaluationResult(
+  actual: unknown,
+  expected: unknown,
+  message = 'Evaluation result mismatch',
+): void {
+  const compare = (a: unknown, b: unknown, path: string): void => {
+    if (a === b) {
+      return;
+    }
+
+    // Handle null/undefined
+    if (a === null || b === null || a === undefined || b === undefined) {
+      if (a !== b) {
+        throw new Error(`${message} at ${path}: expected ${b}, got ${a}`);
+      }
+      return;
+    }
+
+    // Handle numbers with floating point tolerance
+    if (typeof a === 'number' && typeof b === 'number') {
+      const tolerance = 1e-10;
+      if (Math.abs(a - b) > tolerance) {
+        throw new Error(`${message} at ${path}: expected ${b}, got ${a}`);
+      }
+      return;
+    }
+
+    // Handle arrays
+    if (Array.isArray(a) && Array.isArray(b)) {
+      if (a.length !== b.length) {
+        throw new Error(
+          `${message} at ${path}: array length mismatch (expected ${b.length}, got ${a.length})`,
+        );
+      }
+      for (let i = 0; i < a.length; i++) {
+        compare(a[i], b[i], `${path}[${i}]`);
+      }
+      return;
+    }
+
+    // Handle objects
+    if (typeof a === 'object' && typeof b === 'object') {
+      const aObj = a as Record<string, unknown>;
+      const bObj = b as Record<string, unknown>;
+      const aKeys = Object.keys(aObj);
+      const bKeys = Object.keys(bObj);
+
+      // Check for missing keys
+      for (const key of bKeys) {
+        if (!(key in aObj)) {
+          throw new Error(`${message} at ${path}: missing key "${key}"`);
+        }
+      }
+
+      // Compare values
+      for (const key of aKeys) {
+        compare(aObj[key], bObj[key], `${path}.${key}`);
+      }
+      return;
+    }
+
+    // Direct comparison for primitives
+    if (a !== b) {
+      throw new Error(`${message} at ${path}: expected ${b}, got ${a}`);
+    }
+  };
+
+  compare(actual, expected, 'root');
+}