@divmain/jdm-asm 0.2.0

package/src/compiler/cache.ts

@@ -0,0 +1,414 @@
+/**
+ * Caches compiled WASM modules keyed by source code + runtime + compiler options.
+ * WASM compilation via AssemblyScript is expensive (~250ms per decision), so caching
+ * identical compilations significantly improves the speed of iterative development
+ * and testing.
+ */
+
+import { createHash } from 'crypto';
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+  readdirSync,
+  statSync,
+  unlinkSync,
+} from 'fs';
+import { join, dirname } from 'path';
+
+// Import runtime source strings to include in cache key
+import {
+  RUNTIME_VALUES,
+  RUNTIME_CONTEXT,
+  RUNTIME_EXPRESSIONS,
+  RUNTIME_TABLES,
+  RUNTIME_MEMORY,
+  RUNTIME_STRINGS,
+  RUNTIME_ARRAYS,
+} from './runtime/index';
+
+// Package version - included in cache key to invalidate cache across compiler versions
+let packageVersion: string = '';
+
+function getPackageVersion(): string {
+  if (packageVersion === '') {
+    try {
+      // Try to find package.json from this file's location
+      const packagePath = join(dirname(__dirname), '..', 'package.json');
+      const pkg = JSON.parse(readFileSync(packagePath, 'utf-8'));
+      packageVersion = pkg.version || 'unknown';
+    } catch {
+      packageVersion = 'unknown';
+    }
+  }
+  return packageVersion;
+}
+
+/**
+ * Cache directory location
+ */
+function getCacheDir(): string {
+  // Use node_modules/.cache/jdm-asm for caching
+  // This is a common convention and gets cleaned up with node_modules
+  const cacheDir = join(process.cwd(), 'node_modules', '.cache', 'jdm-asm');
+  return cacheDir;
+}
+
+/**
+ * Ensure the cache directory exists
+ * @throws Error if directory creation fails
+ */
+function ensureCacheDir(): string {
+  const cacheDir = getCacheDir();
+  if (!existsSync(cacheDir)) {
+    try {
+      mkdirSync(cacheDir, { recursive: true });
+    } catch (error) {
+      const errorMsg = error instanceof Error ? error.message : String(error);
+      throw new Error(`Failed to create cache directory at ${cacheDir}: ${errorMsg}`);
+    }
+  }
+  return cacheDir;
+}
+
+/**
+ * Compute a stable hash for cache key.
+ */
+export function computeCacheKey(
+  assemblyScriptCode: string,
+  options: { optimize?: boolean; debug?: boolean },
+): string {
+  const hash = createHash('sha256');
+
+  // Include package version
+  hash.update(`version:${getPackageVersion()}\n`);
+
+  // Include compiler options
+  hash.update(`optimize:${options.optimize ?? true}\n`);
+  hash.update(`debug:${options.debug ?? false}\n`);
+
+  // Include all runtime source files: runtime code changes affect WASM output, so
+  // must be part of cache key
+  hash.update('---RUNTIME_VALUES---\n');
+  hash.update(RUNTIME_VALUES);
+  hash.update('---RUNTIME_CONTEXT---\n');
+  hash.update(RUNTIME_CONTEXT);
+  hash.update('---RUNTIME_EXPRESSIONS---\n');
+  hash.update(RUNTIME_EXPRESSIONS);
+  hash.update('---RUNTIME_TABLES---\n');
+  hash.update(RUNTIME_TABLES);
+  hash.update('---RUNTIME_MEMORY---\n');
+  hash.update(RUNTIME_MEMORY);
+  hash.update('---RUNTIME_STRINGS---\n');
+  hash.update(RUNTIME_STRINGS);
+  hash.update('---RUNTIME_ARRAYS---\n');
+  hash.update(RUNTIME_ARRAYS);
+
+  // Include the generated AssemblyScript code
+  hash.update('---ASSEMBLYSCRIPT---\n');
+  hash.update(assemblyScriptCode);
+
+  // Return first 32 characters of hex digest (128 bits - sufficient for cache key)
+  return hash.digest('hex').slice(0, 32);
+}
+
+/**
+ * Cache entry format
+ */
+interface CacheEntry {
+  version: string;
+  timestamp: number;
+  binary: string; // Base64 encoded WASM binary
+  wat: string;
+}
+
+/**
+ * Read cached WASM compilation result from disk if available
+ */
+export function readCacheFromDisk(cacheKey: string): { binary: Uint8Array; wat: string } | null {
+  const cacheDir = getCacheDir();
+  const cachePath = join(cacheDir, `${cacheKey}.json`);
+
+  if (!existsSync(cachePath)) {
+    return null;
+  }
+
+  try {
+    const content = readFileSync(cachePath, 'utf-8');
+    const entry: CacheEntry = JSON.parse(content);
+
+    // Version changes invalidate cache to prevent incompatible compiled code from being used
+    // when the compiler implementation changes between releases
+    if (entry.version !== getPackageVersion()) {
+      // Version mismatch, invalidate
+      unlinkSync(cachePath);
+      return null;
+    }
+
+    // Decode binary from base64
+    const binary = new Uint8Array(Buffer.from(entry.binary, 'base64'));
+    return { binary, wat: entry.wat };
+  } catch (error) {
+    // Distinguish between different error types for better diagnostics
+    if (error && typeof error === 'object' && 'code' in error) {
+      const code = (error as { code: string }).code;
+
+      // ENOENT (file not found) is benign - cache miss
+      if (code === 'ENOENT') {
+        return null;
+      }
+
+      // EACCES/EPERM (permission denied) should warn the user
+      if (code === 'EACCES' || code === 'EPERM') {
+        const errorMsg = error instanceof Error ? error.message : String(error);
+        console.warn(
+          `[jdm-asm] Warning: Cache file exists but cannot be read due to permissions: ${cachePath}\n${errorMsg}`,
+        );
+        return null;
+      }
+    }
+
+    // Cache corruption or other errors are benign since we can regenerate the result.
+    // Failing fast would hurt UX when cache is just a performance optimization, not critical.
+    // Try to clean up corrupted cache file
+    try {
+      unlinkSync(cachePath);
+    } catch (cleanupError) {
+      // If we can't delete it, just warn (might be permission issue)
+      if (cleanupError && typeof cleanupError === 'object' && 'code' in cleanupError) {
+        const code = (cleanupError as { code: string }).code;
+        if (code === 'EACCES' || code === 'EPERM') {
+          console.warn(
+            `[jdm-asm] Warning: Cannot clean up corrupted cache file (permission denied): ${cachePath}`,
+          );
+        }
+      }
+    }
+    return null;
+  }
+}
+
+/**
+ * Write compilation result to disk cache
+ * Failures are logged as warnings but do not throw since caching is optional
+ */
+export function writeCacheToDisk(
+  cacheKey: string,
+  result: { binary: Uint8Array; wat: string },
+): void {
+  try {
+    const cacheDir = ensureCacheDir();
+    const cachePath = join(cacheDir, `${cacheKey}.json`);
+
+    const entry: CacheEntry = {
+      version: getPackageVersion(),
+      timestamp: Date.now(),
+      binary: Buffer.from(result.binary).toString('base64'),
+      wat: result.wat,
+    };
+
+    writeFileSync(cachePath, JSON.stringify(entry));
+  } catch (error) {
+    // Cache write failures should not break compilation since caching is a performance
+    // optimization, not a requirement. Warn the user so they know cache isn't working.
+    const errorMsg = error instanceof Error ? error.message : String(error);
+
+    // Provide more specific guidance for common errors
+    if (error && typeof error === 'object' && 'code' in error) {
+      const code = (error as { code: string }).code;
+
+      if (code === 'ENOSPC') {
+        console.warn(`[jdm-asm] Warning: Failed to write cache (disk full): ${errorMsg}`);
+      } else if (code === 'EACCES' || code === 'EPERM' || code === 'EROFS') {
+        console.warn(
+          `[jdm-asm] Warning: Failed to write cache (permission denied or read-only filesystem): ${errorMsg}`,
+        );
+      } else {
+        console.warn(`[jdm-asm] Warning: Failed to write cache: ${errorMsg}`);
+      }
+    } else {
+      console.warn(`[jdm-asm] Warning: Failed to write cache: ${errorMsg}`);
+    }
+  }
+}
+
+/**
+ * Get the cache directory path
+ * Exposes where compiled WASM modules are stored on disk
+ */
+export function getCacheDirectory(): string {
+  return getCacheDir();
+}
+
+/**
+ * Get cache health diagnostics
+ * Returns information about cache status, any issues, and recent operations
+ */
+export function getCacheHealth(): {
+  enabled: boolean;
+  directory: string;
+  directoryExists: boolean;
+  accessible: boolean;
+  stats: {
+    entries: number;
+    totalSize: number;
+    oldestEntry: number | null;
+    newestEntry: number | null;
+  };
+  issues: string[];
+} {
+  const enabled = isCacheEnabled();
+  const directory = getCacheDir();
+  const directoryExists = existsSync(directory);
+  const issues: string[] = [];
+
+  // Check if cache is disabled
+  if (!enabled) {
+    issues.push('Cache is disabled via JDM_ASM_NO_CACHE environment variable');
+  }
+
+  // Check if directory exists
+  if (enabled && !directoryExists) {
+    issues.push('Cache directory does not exist yet (will be created on first write)');
+  }
+
+  // Check if directory is accessible
+  let accessible = false;
+  if (directoryExists) {
+    try {
+      // Try to read the directory to check accessibility
+      readdirSync(directory);
+      accessible = true;
+    } catch (error) {
+      accessible = false;
+      issues.push(
+        `Cache directory exists but is not accessible: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+  }
+
+  // Get cache stats if accessible
+  const stats = accessible
+    ? getCacheStats()
+    : {
+        entries: 0,
+        totalSize: 0,
+        oldestEntry: null,
+        newestEntry: null,
+      };
+
+  return {
+    enabled,
+    directory,
+    directoryExists,
+    accessible,
+    stats,
+    issues,
+  };
+}
+
+/**
+ * Clear the entire cache
+ */
+export function clearCache(): void {
+  const cacheDir = getCacheDir();
+  if (!existsSync(cacheDir)) {
+    return;
+  }
+
+  const files = readdirSync(cacheDir);
+  for (const file of files) {
+    if (file.endsWith('.json')) {
+      try {
+        unlinkSync(join(cacheDir, file));
+      } catch {}
+    }
+  }
+}
+
+/**
+ * Get cache statistics
+ */
+export function getCacheStats(): {
+  entries: number;
+  totalSize: number;
+  oldestEntry: number | null;
+  newestEntry: number | null;
+} {
+  const cacheDir = getCacheDir();
+  if (!existsSync(cacheDir)) {
+    return { entries: 0, totalSize: 0, oldestEntry: null, newestEntry: null };
+  }
+
+  const files = readdirSync(cacheDir).filter((f) => f.endsWith('.json'));
+  let totalSize = 0;
+  let oldestEntry: number | null = null;
+  let newestEntry: number | null = null;
+
+  for (const file of files) {
+    const stat = statSync(join(cacheDir, file));
+    totalSize += stat.size;
+
+    const mtime = stat.mtimeMs;
+    if (oldestEntry === null || mtime < oldestEntry) {
+      oldestEntry = mtime;
+    }
+    if (newestEntry === null || mtime > newestEntry) {
+      newestEntry = mtime;
+    }
+  }
+
+  return { entries: files.length, totalSize, oldestEntry, newestEntry };
+}
+
+/**
+ * Prune old cache entries (keep most recent N entries or entries younger than maxAge)
+ */
+export function pruneCache(
+  options: {
+    maxEntries?: number;
+    maxAgeMs?: number;
+  } = {},
+): number {
+  const { maxEntries = 100, maxAgeMs = 7 * 24 * 60 * 60 * 1000 } = options; // Default: 100 entries, 7 days
+  const cacheDir = getCacheDir();
+
+  if (!existsSync(cacheDir)) {
+    return 0;
+  }
+
+  const files = readdirSync(cacheDir)
+    .filter((f) => f.endsWith('.json'))
+    .map((f) => {
+      const stat = statSync(join(cacheDir, f));
+      return { name: f, mtime: stat.mtimeMs };
+    })
+    .sort((a, b) => b.mtime - a.mtime); // Sort by newest first
+
+  const now = Date.now();
+  let removed = 0;
+
+  for (let i = 0; i < files.length; i++) {
+    const file = files[i];
+    const age = now - file.mtime;
+
+    // Remove if exceeds max entries or max age
+    if (i >= maxEntries || age > maxAgeMs) {
+      try {
+        unlinkSync(join(cacheDir, file.name));
+        removed++;
+      } catch {}
+    }
+  }
+
+  return removed;
+}
+
+/**
+ * Check if caching is enabled
+ * Can be disabled via JDM_ASM_NO_CACHE=1 environment variable
+ */
+export function isCacheEnabled(): boolean {
+  return process.env.JDM_ASM_NO_CACHE !== '1';
+}

package/src/compiler/code-generators.ts

@@ -0,0 +1,211 @@
+/**
+ * Code generation helpers for shared AssemblyScript code patterns.
+ *
+ * These helpers generate AssemblyScript code strings that can be used across
+ * different compiler modules to avoid duplication.
+ */
+
+import { sanitizeId } from './utils';
+
+/**
+ * Generate AssemblyScript code to assign a value to a nested path in the context.
+ *
+ * This handles dotted paths like "cart.items.total" by navigating/creating the
+ * necessary object hierarchy in the context. The algorithm:
+ * 1. Splits the path by "."
+ * 2. Gets or creates the root object from context
+ * 3. Navigates/creates intermediate objects for each part
+ * 4. Sets the final value at the leaf
+ *
+ * @param path - The dotted path string (e.g., "cart.items.total")
+ * @param valueExpr - The AssemblyScript expression for the value to assign
+ * @param prefix - Optional prefix for generated variable names to avoid collisions (default: "__np")
+ * @returns AssemblyScript code string that performs the nested assignment
+ */
+export function generateNestedPathAssignment(
+  path: string,
+  valueExpr: string,
+  prefix: string = '__np',
+): string {
+  return `// Store value at nested path: ${path}
+{
+  const ${prefix}_value = ${valueExpr};
+  const ${prefix}_parts = "${path}".split(".");
+  const ${prefix}_rootKey = ${prefix}_parts[0];
+  // Get or create the root object
+  let ${prefix}_rootObj: Map<string, Value>;
+  if (ctx.data.has(${prefix}_rootKey) && ctx.data.get(${prefix}_rootKey).isObject()) {
+    ${prefix}_rootObj = ctx.data.get(${prefix}_rootKey).asObject();
+  } else {
+    ${prefix}_rootObj = new Map<string, Value>();
+    ctx.set(${prefix}_rootKey, Value.Object(${prefix}_rootObj));
+  }
+  // Navigate/create nested objects for intermediate parts
+  let ${prefix}_current = ${prefix}_rootObj;
+  for (let ${prefix}_j = 1; ${prefix}_j < ${prefix}_parts.length - 1; ${prefix}_j++) {
+    const ${prefix}_part = ${prefix}_parts[${prefix}_j];
+    if (${prefix}_current.has(${prefix}_part) && ${prefix}_current.get(${prefix}_part).isObject()) {
+      ${prefix}_current = ${prefix}_current.get(${prefix}_part).asObject();
+    } else {
+      const ${prefix}_newObj = new Map<string, Value>();
+      ${prefix}_current.set(${prefix}_part, Value.Object(${prefix}_newObj));
+      ${prefix}_current = ${prefix}_newObj;
+    }
+  }
+  // Set the final value at the leaf of the path
+  ${prefix}_current.set(${prefix}_parts[${prefix}_parts.length - 1], ${prefix}_value);
+}`;
+}
+
+/**
+ * Generate AssemblyScript code to build a final result from accumulated context.
+ *
+ * This extracts all user-facing keys from the context (excluding internal namespaces)
+ * and builds a Map suitable for returning as a Value.Object result.
+ *
+ * The generated code:
+ * 1. Creates a new Map for the result
+ * 2. Iterates over all keys in ctx.data
+ * 3. Filters out internal keys ($*, #, acc)
+ * 4. Copies remaining keys to the result map
+ *
+ * @param resultVarName - The name of the variable to store the result in
+ * @param prefix - Optional prefix for loop variables to avoid collisions (default: "__bfr")
+ * @returns AssemblyScript code string that builds the result map
+ */
+export function generateBuildFinalResultCode(
+  resultVarName: string,
+  prefix: string = '__bfr',
+): string {
+  return `// Build final result from accumulated context
+let ${resultVarName} = new Map<string, Value>();
+const ${prefix}_keys = ctx.data.keys();
+for (let ${prefix}_i = 0; ${prefix}_i < ${prefix}_keys.length; ${prefix}_i++) {
+  const ${prefix}_key = ${prefix}_keys[${prefix}_i];
+  // $nodes/$ are internal namespaces
+  // # is iteration variable,
+  // acc is accumulator
+  // None should appear in final output, only actual output field names
+  if (!${prefix}_key.startsWith("$") && ${prefix}_key !== "#" && ${prefix}_key !== "acc") {
+    ${resultVarName}.set(${prefix}_key, ctx.data.get(${prefix}_key));
+  }
+}`;
+}
+
+/**
+ * Generate AssemblyScript code to evaluate a single node and handle its outputPath and passThrough settings.
+ *
+ * This is the standard node evaluation pattern used across the codebase. It:
+ * 1. Calls the node's evaluateNode function
+ * 2. Stores the result in $nodes.<nodeName>
+ * 3. Handles outputPath if specified (storing result at the given path)
+ * 4. Handles passThrough merge if the node is configured for it
+ *
+ * @param nodeId - The raw node ID
+ * @param nodeName - The name of the node (for context storage)
+ * @param node - The JDM node definition (optional, for outputPath/passThrough handling)
+ * @returns AssemblyScript code string that evaluates the node
+ */
+export function generateNodeEvaluationCode(
+  nodeId: string,
+  nodeName: string,
+  node?: {
+    type?: string;
+    content?: { outputPath?: string; passThrough?: boolean; outputs?: Array<{ field?: string }> };
+  },
+): string {
+  const sanitizedId = sanitizeId(nodeId);
+  const statements: string[] = [];
+
+  // Call the node's evaluateNode function and store result
+  statements.push(`ctx.set("$nodes.${nodeName}", evaluateNode_${sanitizedId}(ctx));`);
+
+  if (!node) {
+    return statements.join('\n    ');
+  }
+
+  const outputPath = node.content?.outputPath;
+  if (outputPath) {
+    if (!outputPath.includes('.')) {
+      statements.push(`ctx.set("${outputPath}", ctx.get("$nodes.${nodeName}"));`);
+    } else {
+      statements.push(generateNestedPathAssignment(outputPath, `ctx.get("$nodes.${nodeName}")`));
+    }
+  }
+
+  // Determine if we should merge node results into context
+  // Expression nodes compute values meant for the output, so their results should flow
+  // through to the final result regardless of passThrough setting. Decision tables with
+  // dotted output fields (e.g., "flag.turnover") similarly need merging to build nested
+  // output structures.
+  const hasOutputFields =
+    node.type === 'decisionTableNode' &&
+    node.content?.outputs?.some((o: { field?: string }) => o.field && o.field.includes('.'));
+  const shouldMerge =
+    node.type === 'expressionNode' || node.content?.passThrough === true || hasOutputFields;
+
+  if (shouldMerge) {
+    statements.push(generatePassThroughMergeCode(nodeName));
+  }
+
+  return statements.join('\n    ');
+}
+
+/**
+ * Generate AssemblyScript code to merge passThrough node results into the context.
+ *
+ * This handles both simple keys (e.g., "status") and nested paths (e.g., "evaluation.score").
+ * For nested paths, it navigates/creates the necessary object hierarchy in the context.
+ *
+ * The generated code:
+ * 1. Gets the node result from `$nodes.<nodeName>`
+ * 2. Iterates over all keys in the result
+ * 3. For simple keys, sets them directly in the context
+ * 4. For nested paths, navigates/creates intermediate objects and sets the leaf value
+ *
+ * @param nodeName - The name of the node whose results should be merged
+ * @returns AssemblyScript code string that performs the merge
+ */
+export function generatePassThroughMergeCode(nodeName: string): string {
+  // Generate the nested path assignment code for use inside the loop
+  // We use a special prefix "__pt" to avoid collisions with other generated code
+  const nestedPathCode = `const __pt_parts = __key.split(".");
+        const __pt_rootKey = __pt_parts[0];
+        let __pt_rootObj: Map<string, Value>;
+        if (ctx.data.has(__pt_rootKey) && ctx.data.get(__pt_rootKey).isObject()) {
+          __pt_rootObj = ctx.data.get(__pt_rootKey).asObject();
+        } else {
+          __pt_rootObj = new Map<string, Value>();
+          ctx.set(__pt_rootKey, Value.Object(__pt_rootObj));
+        }
+        let __pt_current = __pt_rootObj;
+        for (let __pt_j = 1; __pt_j < __pt_parts.length - 1; __pt_j++) {
+          const __pt_part = __pt_parts[__pt_j];
+          if (__pt_current.has(__pt_part) && __pt_current.get(__pt_part).isObject()) {
+            __pt_current = __pt_current.get(__pt_part).asObject();
+          } else {
+            const __pt_newObj = new Map<string, Value>();
+            __pt_current.set(__pt_part, Value.Object(__pt_newObj));
+            __pt_current = __pt_newObj;
+          }
+        }
+        __pt_current.set(__pt_parts[__pt_parts.length - 1], __value);`;
+
+  return `// Merge passThrough results for ${nodeName}
+{
+  const __nodeResult = ctx.get("$nodes.${nodeName}");
+  if (__nodeResult.isObject()) {
+    const __resultMap = __nodeResult.asObject();
+    const __keys = __resultMap.keys();
+    for (let __i = 0; __i < __keys.length; __i++) {
+      const __key = __keys[__i];
+      const __value = __resultMap.get(__key);
+      if (__key.includes(".")) {
+        ${nestedPathCode}
+      } else {
+        ctx.set(__key, __value);
+      }
+    }
+  }
+}`;
+}

package/src/compiler/codegen/index.ts

@@ -0,0 +1,15 @@
+/**
+ * Code Generation Module Index
+ *
+ * This module provides code generation utilities for the JDM compiler,
+ * organized by target language and concern:
+ *
+ * - JavaScript marshaling: Generates JS code for WASM memory serialization/deserialization
+ * - JavaScript validation: Generates JS code for input validation against TypeBox schemas
+ */
+
+// JavaScript marshaling code generation
+export { generateMarshalCode, _generateUnmarshalBody } from './js-marshal';
+
+// JavaScript validation code generation
+export { generateValidationCode } from './js-validation';