@divmain/jdm-asm 0.2.1 → 0.2.3

package/src/compiler/cache.ts

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

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

@@ -1,15 +0,0 @@
-/**
- * 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';