@divmain/jdm-asm 0.2.0 → 0.2.3

package/src/compiler/asc-compiler.ts

@@ -1,315 +0,0 @@
-/**
- * AssemblyScript compilation to WebAssembly.
- * Handles compiler invocation, optimization levels, and memory configuration.
- */
-
-import * as fs from 'fs';
-import * as path from 'path';
-import type { CompilerOptions } from './types';
-import { CompilationError, ErrorCode } from './errors';
-import { createVirtualFS, createASCFileSystemCallbacks, getCompilationOutput } from './virtual-fs';
-
-// ============================================================================
-// Compilation Thresholds and Memory Constants
-// ============================================================================
-
-/**
- * Threshold for determining if a module is "large" (40KB of source code).
- *
- * Empirically determined based on decision table compilation patterns:
- * - Tables with 1000+ rules generate >40KB of code
- * - These create deeply nested if/else chains that stress the optimizer
- * - Larger modules need more initial memory to avoid runtime growth overhead
- *
- * Large modules require:
- * 1. More initial memory pages (16 vs 4) for string allocations
- * 2. Lower optimization level (O2 vs O3) to avoid stack overflow in Binaryen
- * 3. Skipping WAT generation to avoid O(n²) memory complexity
- */
-const LARGE_MODULE_THRESHOLD_BYTES = 40000;
-
-/**
- * Threshold for "very large" modules (1MB of source code).
- * These modules skip optimization entirely to avoid Binaryen crashes.
- */
-const VERY_LARGE_MODULE_THRESHOLD_BYTES = 1_000_000;
-
-// Normal module memory configuration (for modules < 40KB)
-/** Initial memory pages for normal modules (256KB total) */
-const NORMAL_MODULE_INITIAL_PAGES = 4;
-/** Maximum memory pages for normal modules (1MB total) */
-const NORMAL_MODULE_MAX_PAGES = 16;
-
-// Large module memory configuration (for modules >= 40KB)
-/** Initial memory pages for large modules (1MB total) */
-const LARGE_MODULE_INITIAL_PAGES = 16;
-/** Maximum memory pages for large modules (16MB total) */
-const LARGE_MODULE_MAX_PAGES = 256;
-
-/**
- * Compilation settings based on code size.
- * Large modules need different optimization and memory settings.
- */
-export interface CompilationSettings {
-  /** Whether the module is considered large (>40KB) */
-  isLargeModule: boolean;
-  /** Initial WebAssembly memory pages (64KB each) */
-  initialMemoryPages: number;
-  /** Maximum WebAssembly memory pages */
-  maxMemoryPages: number;
-  /** Binaryen optimization level (0-3) */
-  optimizeLevel: number;
-  /** Binaryen shrink level (0-2) */
-  shrinkLevel: number;
-  /** Whether to generate WAT text format */
-  generateWat: boolean;
-}
-
-/**
- * Determine compilation settings based on code size.
- *
- * Memory pages are 64KB each (WASM_PAGE_SIZE_BYTES). Large modules need more
- * initial memory to avoid runtime allocation overhead during string operations
- * and table lookups.
- * - Normal modules: NORMAL_MODULE_INITIAL_PAGES (256KB), max NORMAL_MODULE_MAX_PAGES (1MB)
- * - Large modules: LARGE_MODULE_INITIAL_PAGES (1MB), max LARGE_MODULE_MAX_PAGES (16MB)
- *
- * Large modules (>LARGE_MODULE_THRESHOLD_BYTES) need more memory because:
- *  (1) decision tables generate many string allocations during lookup,
- *  (2) each string requires heap allocation at runtime, and
- *  (3) insufficient initial memory causes frequent growth operations which are slow.
- *
- * Optimization levels scaled by module size because:
- *  (1) Binaryen's optimizer recursively traverses deeply nested if/else chains,
- *  (2) decision tables with 1000+ rules create nesting depth that exceeds stack limits at O3,
- *  (3) O2 uses iterative algorithms that handle deep nesting,
- *  (4) very large modules (>1MB) disable optimization entirely to avoid 10+ minute compile times.
- *
- * WAT generation skipped for large modules because Binaryen's text emitter has O(n²)
- * memory complexity and crashes with OOM on modules >LARGE_MODULE_THRESHOLD_BYTES source.
- *
- * @param codeLength - Length of the AssemblyScript source code
- * @returns Compilation settings appropriate for the code size
- */
-export function getCompilationSettings(codeLength: number): CompilationSettings {
-  const isLargeModule = codeLength > LARGE_MODULE_THRESHOLD_BYTES;
-  const isVeryLargeModule = codeLength > VERY_LARGE_MODULE_THRESHOLD_BYTES;
-
-  let optimizeLevel: number;
-  let shrinkLevel: number;
-
-  if (isVeryLargeModule) {
-    // Very large module (>1MB source) - skip optimization to avoid Binaryen crash
-    optimizeLevel = 0;
-    shrinkLevel = 0;
-  } else if (isLargeModule) {
-    // Medium-large module (40KB-1MB) - use moderate optimization
-    optimizeLevel = 2;
-    shrinkLevel = 1;
-  } else {
-    // Small module (<40KB) - use full optimization
-    optimizeLevel = 3;
-    shrinkLevel = 2;
-  }
-
-  return {
-    isLargeModule,
-    initialMemoryPages: isLargeModule ? LARGE_MODULE_INITIAL_PAGES : NORMAL_MODULE_INITIAL_PAGES,
-    maxMemoryPages: isLargeModule ? LARGE_MODULE_MAX_PAGES : NORMAL_MODULE_MAX_PAGES,
-    optimizeLevel,
-    shrinkLevel,
-    generateWat: !isLargeModule,
-  };
-}
-
-/**
- * Create a secure temporary debug file with restricted permissions.
- *
- * Creates a temporary directory with a random name and writes the code to a file
- * with 0o600 permissions (owner read/write only).
- *
- * This function only writes files if a debug output path is provided via options
- * or the JDM_ASM_DEBUG_OUTPUT environment variable.
- *
- * @param code - The code content to write
- * @param basePath - Base directory for debug output (from options or env var)
- * @param suffix - Optional suffix for the filename (e.g., "-no-binary")
- * @returns Path to the created debug file, or null if debug output is disabled or write fails
- */
-function createSecureDebugFile(
-  code: string,
-  basePath: string | undefined,
-  suffix = '',
-): string | null {
-  // Only write debug files if explicitly requested
-  if (!basePath) {
-    return null;
-  }
-
-  try {
-    // Create a secure temporary directory with random name
-    const tmpDir = fs.mkdtempSync(path.join(basePath, 'jdm-asm-debug-'));
-
-    // Create debug file path
-    const debugFile = path.join(tmpDir, `assembly-debug${suffix}.ts`);
-
-    // Write file with restricted permissions (owner read/write only)
-    fs.writeFileSync(debugFile, code, { mode: 0o600 });
-
-    return debugFile;
-  } catch (error) {
-    // Debug output is best-effort: warn but don't break compilation
-    const errorMsg = error instanceof Error ? error.message : String(error);
-    console.warn(`[jdm-asm] Warning: Failed to write debug output to ${basePath}: ${errorMsg}`);
-    return null;
-  }
-}
-
-/**
- * Build compiler arguments based on options and settings.
- *
- * @param options - User-provided compiler options
- * @param settings - Size-based compilation settings
- * @returns Array of command-line arguments for the ASC compiler
- */
-export function buildCompilerArgs(
-  options: CompilerOptions,
-  settings: CompilationSettings,
-): string[] {
-  const args = [
-    'src/runtime/index.ts',
-    '--outFile',
-    'output.wasm',
-    '--runtime',
-    'incremental', // Use incremental GC runtime for memory reuse across evaluations
-    '--exportRuntime', // Export __new, __pin, __collect, etc.
-    '--initialMemory',
-    String(settings.initialMemoryPages),
-    '--maximumMemory',
-    String(settings.maxMemoryPages),
-  ];
-
-  // Only generate WAT for smaller modules (large ones crash Binaryen's text emitter)
-  if (settings.generateWat) {
-    args.push('--textFile', 'output.wat');
-  }
-
-  // Add optimization flags if requested
-  if (options.optimize) {
-    if (settings.optimizeLevel > 0) {
-      args.push('--optimize');
-    }
-    args.push('--optimizeLevel', String(settings.optimizeLevel));
-    args.push('--shrinkLevel', String(settings.shrinkLevel));
-  }
-
-  // Add debug flags if requested
-  if (options.debug) {
-    args.push('--debug', '--sourceMap');
-  }
-
-  // Disable assertions in production (non-debug) mode
-  if (!options.debug) {
-    args.push('--noAssert');
-  }
-
-  return args;
-}
-
-/**
- * Compile AssemblyScript code to WebAssembly.
- *
- * This function uses the AssemblyScript compiler to generate WASM from
- * the generated AssemblyScript source code using a virtual filesystem.
- *
- * **Filesystem Side Effects:**
- * If `options.debugOutputPath` is set or the `JDM_ASM_DEBUG_OUTPUT` environment
- * variable is defined, compilation failures will write the generated AssemblyScript
- * code to disk for debugging. Files are written to secure temporary directories
- * with restricted permissions (0o600) and are NOT automatically cleaned up.
- *
- * Note: This is the internal compilation function without caching.
- * Use compileAssemblyScript() from build.ts for cached compilation.
- *
- * @param code - The AssemblyScript source code to compile
- * @param options - Compiler options (optimize, debug, debugOutputPath, etc.)
- * @returns An object with the compiled binary and WAT text
- */
-export async function compileAssemblyScriptInternal(
-  code: string,
-  options: CompilerOptions,
-): Promise<{ binary: Uint8Array; wat: string }> {
-  // Import the AssemblyScript compiler
-  const ascModule = await import('assemblyscript/asc');
-
-  // Determine debug output path: explicit option takes precedence over environment variable
-  const debugOutputPath = options.debugOutputPath ?? process.env.JDM_ASM_DEBUG_OUTPUT;
-
-  // Save generated code before compilation so it's available for debugging even if
-  // compilation crashes the process (Binaryen can segfault on malformed input).
-  // Only write if debug output is explicitly enabled.
-  const debugFile = createSecureDebugFile(code, debugOutputPath);
-
-  // Set up virtual filesystem
-  const virtualFS = createVirtualFS(code);
-
-  // Get size-based compilation settings
-  const settings = getCompilationSettings(code.length);
-
-  // Build compiler arguments
-  const compilerArgs = buildCompilerArgs(options, settings);
-
-  // Get filesystem callbacks for ASC
-  const fsCallbacks = createASCFileSystemCallbacks(virtualFS);
-
-  // Create an in-memory stderr stream
-  let stderrOutput = '';
-  const stderrStream = ascModule.createMemoryStream((chunk: Uint8Array | string) => {
-    stderrOutput += typeof chunk === 'string' ? chunk : new TextDecoder().decode(chunk);
-  });
-
-  // Compile using the asc compiler with virtual filesystem
-  const { error } = await ascModule.main(compilerArgs, {
-    ...fsCallbacks,
-    stderr: stderrStream,
-  });
-
-  // Check for compilation errors
-  if (error) {
-    const debugFileInfo = debugFile
-      ? `\n\nGenerated code saved to ${debugFile}`
-      : '\n\n(Set debugOutputPath option or JDM_ASM_DEBUG_OUTPUT env var to save generated code for debugging)';
-
-    throw new CompilationError(
-      `AssemblyScript compilation failed:\n${stderrOutput || error.message}${debugFileInfo}`,
-      ErrorCode.PARSE_ERROR,
-      { field: 'assemblyScript' },
-      { stderrOutput },
-    );
-  }
-
-  // Get output from virtual filesystem
-  const output = getCompilationOutput(virtualFS);
-
-  if (!output.binary) {
-    const noBinaryDebugFile = createSecureDebugFile(code, debugOutputPath, '-no-binary');
-    stderrOutput = stderrOutput || '(no stderr output)';
-    const files = [...virtualFS.keys()].join(', ');
-
-    const debugFileInfo = noBinaryDebugFile
-      ? `\nGenerated code saved to ${noBinaryDebugFile}`
-      : '\n(Set debugOutputPath option or JDM_ASM_DEBUG_OUTPUT env var to save generated code for debugging)';
-
-    throw new CompilationError(
-      `Compilation produced no WASM binary output.\nCompiler stderr: ${stderrOutput}\nFiles in virtualFS: ${files}${debugFileInfo}`,
-      ErrorCode.PARSE_ERROR,
-      { field: 'assemblyScript' },
-      { stderrOutput, virtualFSFiles: files },
-    );
-  }
-
-  return {
-    binary: output.binary,
-    wat: output.wat ?? '',
-  };
-}

package/src/compiler/ast-types.ts

@@ -1,215 +0,0 @@
-/**
- * Union type of all expression AST nodes.
- */
-export type ExpressionAST =
-  | NumberLiteral
-  | StringLiteral
-  | BooleanLiteral
-  | NullLiteral
-  | Identifier
-  | DollarRef
-  | HashRef
-  | BinaryOp
-  | UnaryOp
-  | TernaryOp
-  | MemberAccess
-  | IndexAccess
-  | FunctionCall
-  | Interval
-  | TemplateLiteral
-  | ArrayLiteral
-  | ObjectLiteral;
-
-export interface NumberLiteral {
-  type: 'NumberLiteral';
-  value: number;
-}
-
-export interface StringLiteral {
-  type: 'StringLiteral';
-  value: string;
-}
-
-export interface BooleanLiteral {
-  type: 'BooleanLiteral';
-  value: boolean;
-}
-
-export interface NullLiteral {
-  type: 'NullLiteral';
-}
-
-export interface Identifier {
-  type: 'Identifier';
-  name: string;
-}
-
-/**
- * Dollar reference - used in unary mode to refer to the current value.
- * Represents `$` in decision table cell expressions.
- */
-export interface DollarRef {
-  type: 'DollarRef';
-}
-
-/**
- * Hash reference - used in higher-order functions to refer to current element.
- * Represents `#` in expressions like `filter(items, # > 5)`.
- */
-export interface HashRef {
-  type: 'HashRef';
-}
-
-export interface BinaryOp {
-  type: 'BinaryOp';
-  op: BinaryOperator;
-  left: ExpressionAST;
-  right: ExpressionAST;
-}
-
-export type BinaryOperator =
-  // Arithmetic
-  | '+'
-  | '-'
-  | '*'
-  | '/'
-  | '%'
-  | '^'
-  // Comparison
-  | '=='
-  | '!='
-  | '<'
-  | '>'
-  | '<='
-  | '>='
-  // Logical
-  | 'and'
-  | 'or'
-  | '??'
-  // Membership
-  | 'in'
-  | 'not in';
-
-export interface UnaryOp {
-  type: 'UnaryOp';
-  op: UnaryOperator;
-  operand: ExpressionAST;
-}
-
-export type UnaryOperator = 'not' | '-';
-
-export interface TernaryOp {
-  type: 'TernaryOp';
-  condition: ExpressionAST;
-  consequent: ExpressionAST;
-  alternate: ExpressionAST;
-}
-
-export interface MemberAccess {
-  type: 'MemberAccess';
-  object: ExpressionAST;
-  property: string;
-}
-
-export interface IndexAccess {
-  type: 'IndexAccess';
-  object: ExpressionAST;
-  index: ExpressionAST;
-}
-
-export interface FunctionCall {
-  type: 'FunctionCall';
-  callee: ExpressionAST;
-  args: ExpressionAST[];
-}
-
-export interface Interval {
-  type: 'Interval';
-  start: ExpressionAST;
-  end: ExpressionAST;
-  startInclusive: boolean;
-  endInclusive: boolean;
-}
-
-export interface TemplateLiteral {
-  type: 'TemplateLiteral';
-  parts: Array<{ text: string } | { expr: ExpressionAST }>;
-}
-
-export interface ArrayLiteral {
-  type: 'ArrayLiteral';
-  elements: ExpressionAST[];
-}
-
-export interface ObjectLiteral {
-  type: 'ObjectLiteral';
-  properties: Array<{ key: string; value: ExpressionAST }>;
-}
-
-export function isNumberLiteral(node: ExpressionAST): node is NumberLiteral {
-  return node.type === 'NumberLiteral';
-}
-
-export function isStringLiteral(node: ExpressionAST): node is StringLiteral {
-  return node.type === 'StringLiteral';
-}
-
-export function isBooleanLiteral(node: ExpressionAST): node is BooleanLiteral {
-  return node.type === 'BooleanLiteral';
-}
-
-export function isNullLiteral(node: ExpressionAST): node is NullLiteral {
-  return node.type === 'NullLiteral';
-}
-
-export function isIdentifier(node: ExpressionAST): node is Identifier {
-  return node.type === 'Identifier';
-}
-
-export function isDollarRef(node: ExpressionAST): node is DollarRef {
-  return node.type === 'DollarRef';
-}
-
-export function isHashRef(node: ExpressionAST): node is HashRef {
-  return node.type === 'HashRef';
-}
-
-export function isBinaryOp(node: ExpressionAST): node is BinaryOp {
-  return node.type === 'BinaryOp';
-}
-
-export function isUnaryOp(node: ExpressionAST): node is UnaryOp {
-  return node.type === 'UnaryOp';
-}
-
-export function isTernaryOp(node: ExpressionAST): node is TernaryOp {
-  return node.type === 'TernaryOp';
-}
-
-export function isMemberAccess(node: ExpressionAST): node is MemberAccess {
-  return node.type === 'MemberAccess';
-}
-
-export function isIndexAccess(node: ExpressionAST): node is IndexAccess {
-  return node.type === 'IndexAccess';
-}
-
-export function isFunctionCall(node: ExpressionAST): node is FunctionCall {
-  return node.type === 'FunctionCall';
-}
-
-export function isInterval(node: ExpressionAST): node is Interval {
-  return node.type === 'Interval';
-}
-
-export function isTemplateLiteral(node: ExpressionAST): node is TemplateLiteral {
-  return node.type === 'TemplateLiteral';
-}
-
-export function isArrayLiteral(node: ExpressionAST): node is ArrayLiteral {
-  return node.type === 'ArrayLiteral';
-}
-
-export function isObjectLiteral(node: ExpressionAST): node is ObjectLiteral {
-  return node.type === 'ObjectLiteral';
-}

package/src/compiler/build.ts

@@ -1,56 +0,0 @@
-/**
- * Compile AssemblyScript code to WebAssembly.
- *
- * This module provides the main entry point for WASM compilation with caching.
- * Implementation details are delegated to specialized modules:
- * - virtual-fs.ts: Virtual filesystem for in-memory ASC compilation
- * - asc-compiler.ts: AssemblyScript compiler invocation and configuration
- * - wasm-instantiate.ts: WASM module instantiation and host environment
- */
-
-import type { CompilerOptions } from './types';
-import { computeCacheKey, readCacheFromDisk, writeCacheToDisk, isCacheEnabled } from './cache';
-import { compileAssemblyScriptInternal } from './asc-compiler';
-
-// Re-export for backward compatibility
-export { instantiateWasm } from './wasm-instantiate';
-
-/**
- * Compile AssemblyScript code to WebAssembly.
- *
- * This function uses the AssemblyScript compiler to generate WASM from
- * the generated AssemblyScript source code using a virtual filesystem.
- *
- * Supports disk-based caching to avoid redundant compilations.
- * Cache is keyed on: AssemblyScript code + runtime libraries + compiler options.
- *
- * **Filesystem Side Effects:**
- * - Compilation may read/write cache files (unless disabled via JDM_ASM_NO_CACHE=1)
- * - If `options.debugOutputPath` is set or `JDM_ASM_DEBUG_OUTPUT` env var is defined,
- *   compilation failures will write debug files to disk (see CompilerOptions.debugOutputPath)
- *
- * @param code - The AssemblyScript source code to compile
- * @param options - Compiler options (optimize, debug, debugOutputPath, etc.)
- * @returns An object with the compiled binary and WAT text
- */
-export async function compileAssemblyScript(
-  code: string,
-  options: CompilerOptions,
-): Promise<{ binary: Uint8Array; wat: string }> {
-  // Check cache first (unless disabled)
-  if (isCacheEnabled()) {
-    const cacheKey = computeCacheKey(code, options);
-    const cached = readCacheFromDisk(cacheKey);
-    if (cached) {
-      return cached;
-    }
-
-    // Compile and cache the result
-    const result = await compileAssemblyScriptInternal(code, options);
-    writeCacheToDisk(cacheKey, result);
-    return result;
-  }
-
-  // Cache disabled, compile directly
-  return compileAssemblyScriptInternal(code, options);
-}