@divmain/jdm-asm 0.2.0

package/src/compiler/unary-transform.ts

@@ -0,0 +1,161 @@
+/**
+ * Unary expression transformation utilities for decision table compilation.
+ *
+ * In decision tables, expressions are evaluated in a "unary" context where
+ * the $ symbol is automatically bound to the input field's value. Since
+ * AssemblyScript doesn't support closures, we transform the AST to replace
+ * DollarRef nodes with pre-compiled code.
+ *
+ * This module provides:
+ * - InlineCode: A marker type for pre-compiled code in ASTs
+ * - replaceDollarRefWithCode: AST transformer for dollar reference substitution
+ * - compileExpressionWithInlineCode: Compiler that handles InlineCode nodes
+ */
+
+import type { CompilationContext } from './types';
+import { compileExpression, compileBinaryOpWithValues } from './nodes/expression';
+
+/**
+ * Special marker type for inline code that should be inserted directly.
+ *
+ * Used when AST transformation requires embedding already-compiled code.
+ * For example, when compiling "$ > 100" where $ refers to a field value,
+ * we replace the DollarRef node with an InlineCode node containing the
+ * pre-compiled field access code.
+ */
+export interface InlineCode {
+  type: 'InlineCode';
+  code: string;
+}
+
+/**
+ * Recursively replace DollarRef nodes in an AST with InlineCode nodes
+ * containing the pre-compiled field expression.
+ *
+ * This transformation enables unary expression compilation in AssemblyScript
+ * by substituting $ references with actual field access code at compile time.
+ *
+ * @param ast - The AST node to transform
+ * @param compiledField - The pre-compiled code for the field value
+ * @returns The transformed AST with InlineCode nodes instead of DollarRef
+ *
+ * @example
+ * // Original AST for "$ > 100":
+ * // { type: "BinaryOp", op: ">", left: { type: "DollarRef" }, right: { type: "NumberLiteral", value: 100 } }
+ * //
+ * // After transformation with compiledField = 'ctx.get("creditScore")':
+ * // { type: "BinaryOp", op: ">", left: { type: "InlineCode", code: 'ctx.get("creditScore")' }, right: { type: "NumberLiteral", value: 100 } }
+ */
+export function replaceDollarRefWithCode(ast: any, compiledField: string): any {
+  if (!ast || typeof ast !== 'object') {
+    return ast;
+  }
+
+  // If this is a DollarRef, replace it with InlineCode containing the compiled field
+  if (ast.type === 'DollarRef') {
+    return { type: 'InlineCode', code: compiledField } as InlineCode;
+  }
+
+  // Recursively transform child nodes
+  const result: any = { type: ast.type };
+
+  for (const key of Object.keys(ast)) {
+    if (key === 'type') {
+      continue;
+    }
+
+    const value = ast[key];
+    if (Array.isArray(value)) {
+      result[key] = value.map((item) => replaceDollarRefWithCode(item, compiledField));
+    } else if (value && typeof value === 'object') {
+      result[key] = replaceDollarRefWithCode(value, compiledField);
+    } else {
+      result[key] = value;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Compile an AST that may contain InlineCode nodes.
+ *
+ * This compiler extends the standard expression compiler to handle InlineCode
+ * nodes, which contain pre-compiled code that should be inserted directly.
+ * It's used after replaceDollarRefWithCode to compile the transformed AST.
+ *
+ * @param ast - The AST node to compile (may contain InlineCode nodes)
+ * @param context - The compilation context
+ * @returns Compiled AssemblyScript code string
+ */
+export function compileExpressionWithInlineCode(ast: any, context: CompilationContext): string {
+  // Handle InlineCode nodes specially - just return the pre-compiled code
+  if (ast.type === 'InlineCode') {
+    return (ast as InlineCode).code;
+  }
+
+  // For nodes with binary operations
+  if (ast.type === 'BinaryOp') {
+    const left = compileExpressionWithInlineCode(ast.left, context);
+    const right = compileExpressionWithInlineCode(ast.right, context);
+    return compileBinaryOpWithValues(ast.op, left, right);
+  }
+
+  // For unary operations
+  if (ast.type === 'UnaryOp') {
+    const operand = compileExpressionWithInlineCode(ast.operand, context);
+    switch (ast.op) {
+      case 'not':
+        return `Value.Bool(!(${operand}).asBool())`;
+      case '-':
+        return `negateValue(${operand})`;
+      default:
+        throw new Error(`Unknown unary operator: ${ast.op}`);
+    }
+  }
+
+  // For function calls, compile args recursively to handle InlineCode
+  if (ast.type === 'FunctionCall') {
+    const callee = ast.callee;
+    if (callee.type === 'Identifier') {
+      const args = ast.args.map((arg: any) => compileExpressionWithInlineCode(arg, context));
+      const numArgs = args.length;
+
+      // Use helper functions to create argument arrays
+      if (numArgs === 1) {
+        return `evaluateFunction("${callee.name}", makeArgs1(${args[0]}))`;
+      } else if (numArgs === 2) {
+        return `evaluateFunction("${callee.name}", makeArgs2(${args[0]}, ${args[1]}))`;
+      } else if (numArgs === 3) {
+        return `evaluateFunction("${callee.name}", makeArgs3(${args[0]}, ${args[1]}, ${args[2]}))`;
+      } else {
+        return `evaluateFunction("${callee.name}", [${args.join(', ')}])`;
+      }
+    }
+    throw new Error('Only direct function calls are supported');
+  }
+
+  // For member access
+  if (ast.type === 'MemberAccess') {
+    const obj = compileExpressionWithInlineCode(ast.object, context);
+    return `getProperty(${obj}, "${ast.property}")`;
+  }
+
+  // For index access
+  if (ast.type === 'IndexAccess') {
+    const obj = compileExpressionWithInlineCode(ast.object, context);
+    const idx = compileExpressionWithInlineCode(ast.index, context);
+    return `getIndex(${obj}, ${idx})`;
+  }
+
+  // For ternary operations
+  if (ast.type === 'TernaryOp') {
+    const cond = compileExpressionWithInlineCode(ast.condition, context);
+    const cons = compileExpressionWithInlineCode(ast.consequent, context);
+    const alt = compileExpressionWithInlineCode(ast.alternate, context);
+    return `(${cond}.asBool() ? ${cons} : ${alt})`;
+  }
+
+  // For other node types, delegate to standard compileExpression
+  return compileExpression(ast, context);
+}

package/src/compiler/utils.ts

@@ -0,0 +1,27 @@
+/**
+ * Sanitize an ID for use as an AssemblyScript identifier.
+ * Replaces hyphens and other special characters with underscores.
+ *
+ * @param id - The ID to sanitize
+ * @returns A valid AssemblyScript identifier
+ */
+export function sanitizeId(id: string): string {
+  // Replace hyphens and other non-alphanumeric characters (except underscores) with underscores
+  return id.replace(/[^a-zA-Z0-9_]/g, '_');
+}
+
+/**
+ * Convert a node name to a camelCase key.
+ * Used for wrapping decision table outputs with the node name.
+ * Example: "RiskFactors" -> "riskFactors", "DiscountRules" -> "discountRules"
+ *
+ * @param name - The node name to convert
+ * @returns A camelCase key
+ */
+export function nodeNameToKey(name: string): string {
+  if (!name || name.length === 0) {
+    return name;
+  }
+  // Lowercase the first character
+  return name.charAt(0).toLowerCase() + name.slice(1);
+}

package/src/compiler/virtual-fs.ts

@@ -0,0 +1,90 @@
+/**
+ * Virtual filesystem for in-memory AssemblyScript compilation.
+ * Manages file mappings for the ASC compiler.
+ */
+
+import {
+  RUNTIME_VALUES,
+  RUNTIME_CONTEXT,
+  RUNTIME_EXPRESSIONS,
+  RUNTIME_TABLES,
+  RUNTIME_MEMORY,
+  RUNTIME_STRINGS,
+  RUNTIME_ARRAYS,
+} from './runtime/index';
+
+/** VirtualFS stores files as string or Uint8Array content */
+export type VirtualFS = Map<string, string | Uint8Array>;
+
+/**
+ * Create a virtual filesystem with runtime libraries and user code.
+ * @param code - User's AssemblyScript code to compile
+ * @returns Configured virtual filesystem
+ */
+export function createVirtualFS(code: string): VirtualFS {
+  const virtualFS: VirtualFS = new Map();
+  virtualFS.set('src/runtime/index.ts', code);
+  virtualFS.set('src/runtime/values.ts', RUNTIME_VALUES);
+  virtualFS.set('src/runtime/context.ts', RUNTIME_CONTEXT);
+  virtualFS.set('src/runtime/expressions.ts', RUNTIME_EXPRESSIONS);
+  virtualFS.set('src/runtime/tables.ts', RUNTIME_TABLES);
+  virtualFS.set('src/runtime/memory.ts', RUNTIME_MEMORY);
+  virtualFS.set('src/runtime/strings.ts', RUNTIME_STRINGS);
+  virtualFS.set('src/runtime/arrays.ts', RUNTIME_ARRAYS);
+  return virtualFS;
+}
+
+/**
+ * Create ASC-compatible file system callbacks.
+ * @param virtualFS - The virtual filesystem to use
+ * @returns Object with readFile, writeFile, listFiles functions for ASC compiler
+ */
+export function createASCFileSystemCallbacks(virtualFS: VirtualFS) {
+  return {
+    readFile(name: string, baseDir: string): string | null {
+      // Try multiple path variations to find the file
+      const possibleKeys = [
+        // 'src/runtime/index.ts'
+        name,
+        // './src/runtime/index.ts' or 'src/runtime/index.ts'
+        baseDir ? `${baseDir}/${name}` : name,
+        // Remove leading ./
+        name.startsWith('./') ? name.slice(2) : name,
+      ];
+
+      for (const key of possibleKeys) {
+        const content = virtualFS.get(key);
+        if (typeof content === 'string') {
+          return content;
+        }
+      }
+      return null;
+    },
+    writeFile(name: string, data: Uint8Array | string, baseDir: string): void {
+      const key = baseDir ? `${baseDir}/${name}` : name;
+      virtualFS.set(key, data);
+    },
+    listFiles(dirname: string, baseDir: string): string[] | null {
+      const prefix = baseDir ? `${baseDir}/${dirname}` : dirname;
+      return [...virtualFS.keys()].filter((f) => f.startsWith(prefix));
+    },
+  };
+}
+
+/**
+ * Get output files from virtual filesystem after compilation.
+ * @param virtualFS - The virtual filesystem
+ * @returns Object with binary and wat files (may be undefined if not present)
+ */
+export function getCompilationOutput(virtualFS: VirtualFS): {
+  binary: Uint8Array | undefined;
+  wat: string | undefined;
+} {
+  // The compiler writes to ./output.wasm (with ./ prefix)
+  const binary = virtualFS.get('output.wasm') || virtualFS.get('./output.wasm');
+  const wat = virtualFS.get('output.wat') || virtualFS.get('./output.wat');
+  return {
+    binary: binary instanceof Uint8Array ? binary : undefined,
+    wat: typeof wat === 'string' ? wat : undefined,
+  };
+}

package/src/compiler/wasm-instantiate.ts

@@ -0,0 +1,127 @@
+/**
+ * WebAssembly module instantiation and runtime support.
+ * Handles loading compiled WASM and setting up the host environment.
+ */
+
+import { CompilationError, ErrorCode } from './errors';
+import { RuntimeError } from './runtime';
+
+/**
+ * Type for WebAssembly exports from compiled AssemblyScript module.
+ */
+export interface WasmExports {
+  /** Main evaluation function - takes input pointer, returns output pointer */
+  evaluate: (inputPtr: number) => number;
+  /** Allocate memory for a new object */
+  __new: (size: number, id: number) => number;
+  /** Pin an object to prevent garbage collection */
+  __pin: (ptr: number) => number;
+  /** Unpin a previously pinned object */
+  __unpin: (ptr: number) => void;
+  /** WebAssembly linear memory */
+  memory?: WebAssembly.Memory;
+}
+
+/**
+ * Create the host environment imports for WASM instantiation.
+ *
+ * This sets up the abort handler and any other host functions
+ * required by the AssemblyScript runtime.
+ *
+ * @returns WebAssembly imports object
+ */
+export function createHostImports(): WebAssembly.Imports {
+  return {
+    env: {
+      abort: (msg: number, file: number, line: number, col: number) => {
+        // Log to stderr for debugging (useful for runtime errors in production)
+        console.error(`WASM abort at ${file}:${line}:${col}, msg: ${msg}`);
+        throw new RuntimeError(`WASM abort at ${file}:${line}:${col}`);
+      },
+    },
+  };
+}
+
+/**
+ * Validate that required exports exist on the WASM module.
+ *
+ * @param exports - Raw exports from WebAssembly instance
+ * @returns Typed WasmExports object
+ * @throws CompilationError if required exports are missing
+ */
+export function validateWasmExports(exports: unknown): WasmExports {
+  if (!exports || typeof exports !== 'object') {
+    throw new CompilationError(
+      'Compiled WASM module has no exports',
+      ErrorCode.INVALID_NODE_STRUCTURE,
+      { field: 'wasm.exports' },
+    );
+  }
+
+  const wasmExports = exports as WasmExports;
+
+  if (!wasmExports.evaluate) {
+    throw new CompilationError(
+      'Compiled WASM module does not export required function: evaluate',
+      ErrorCode.INVALID_NODE_STRUCTURE,
+      { field: 'wasm.exports.evaluate' },
+    );
+  }
+
+  if (!wasmExports.__new) {
+    throw new CompilationError(
+      'Compiled WASM module does not export required function: __new',
+      ErrorCode.INVALID_NODE_STRUCTURE,
+      { field: 'wasm.exports.__new' },
+    );
+  }
+
+  if (!wasmExports.memory) {
+    throw new CompilationError(
+      'Compiled WASM module does not export required function: memory',
+      ErrorCode.INVALID_NODE_STRUCTURE,
+      { field: 'wasm.exports.memory' },
+    );
+  }
+
+  return wasmExports;
+}
+
+/**
+ * Instantiate compiled WASM and return evaluation function.
+ *
+ * Note: JS <-> WASM serialization is handled by the marshal/unmarshal functions
+ * generated by marshal-gen.ts. This function is maintained for backward compatibility.
+ *
+ * @param binary - Compiled WASM binary
+ * @returns Object with an evaluate function (not yet implemented)
+ */
+export async function instantiateWasm(
+  binary: Uint8Array,
+): Promise<{ evaluate: (input: object) => object }> {
+  // Compile the WASM binary
+  const module = await WebAssembly.compile(binary.buffer as ArrayBuffer);
+
+  // Define the host environment
+  const imports = createHostImports();
+
+  // Instantiate with host environment
+  const instance = await WebAssembly.instantiate(module, imports);
+
+  // Validate exports
+  validateWasmExports(instance.exports);
+
+  return {
+    evaluate(_input: object): object {
+      // TODO: Implement JS <-> WASM serialization
+      // This will use wasmExports.__new to allocate memory, serialize the input object,
+      // call evaluate, and deserialize the result back to JavaScript.
+      // This functionality will be implemented with schema-driven typed serialization.
+
+      throw new RuntimeError(
+        'JS <-> WASM serialization not yet implemented. ' +
+          'This will be implemented with schema-driven typed serialization.',
+      );
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1 @@
+export * from './compiler/index';