@fraczak/k 6.10.3 → 6.10.4

package/scripts/benchmark.mjs

@@ -733,7 +733,58 @@ function printSummary(document) {
   console.log("=============================================================\n");
 }
 
+function printHelp() {
+  console.log(`Usage: node scripts/benchmark.mjs [options]
+
+Unified Multi-Backend Benchmark Suite.
+Runs comprehensive arithmetic and IEEE benchmarks across Native JS,
+kVM, KIR-P, Wasm, and LLVM-JIT execution engines.
+
+Options:
+  --worker
+      Internal flag: execute an isolated benchmark worker job.
+  -h, --help
+      Show this help message and exit.
+
+Environment Variables:
+  BENCHMARK_CASES
+      Comma-separated benchmark cases to run (default: all).
+      Cases: ieee.add, ieee.sub, ieee.mul, ieee.div,
+             int.times.220d, int.gcd.90d, int.factorial.101,
+             int.factorial.242, int.factorial.1174
+  BENCHMARK_MODES
+      Comma-separated execution modes to run (default: all).
+      Modes: Native JS (Envelope-Aware), Native JS (Envelope-Free),
+             kVM Interpreter (Env-Free), KIR-P Export,
+             k-wasm, k-llvm-jit
+  BENCHMARK_SAMPLES
+      Number of measurement samples per benchmark (default: 3).
+  BENCHMARK_TIMEOUT_MS
+      Timeout per benchmark job in milliseconds (default: 120000).
+  BENCHMARK_JOBS
+      Maximum parallel worker concurrency (default: 1).
+  BENCHMARK_STRICT
+      Exit with non-zero exit code if any case fails ('1' to enable).
+  K_LLVM_RUNTIME_MODE
+      Default LLVM runtime compilation mode (default: fast).
+  K_LLVM_IEEE_RUNTIME_MODE
+      LLVM runtime mode for IEEE benchmarks (default: compact).
+  K_LLVM_CLANG_OPT
+      Clang optimization flag for LLVM (default: -O3).
+  K_LLVM_IEEE_CLANG_OPT
+      Clang optimization flag for IEEE LLVM (default: -O0).
+  K_LLVM_CACHE_DIR
+      Directory to cache compiled LLVM executable binaries.
+  K_BENCHMARK_RESULT_PATH
+      Custom destination file path for benchmark results JSON.`);
+}
+
 async function main() {
+  if (process.argv.includes("-h") || process.argv.includes("--help")) {
+    printHelp();
+    return;
+  }
+
   if (process.env.K_BENCHMARK_WORKER === "1" || process.argv.includes("--worker")) {
     await workerMain();
     return;

package/scripts/build-repl-html.mjs

@@ -10,6 +10,23 @@ const __dirname = path.dirname(__filename);
 const projectRoot = path.resolve(__dirname, "..");
 const workspaceRoot = path.resolve(projectRoot, "..");
 
+function printHelp() {
+  console.log(`Usage: node scripts/build-repl-html.mjs [options]
+
+Builds the standalone, self-contained K web REPL (repl.html).
+Bundles browser shims, virtual file system (core.k, Examples, Wasm),
+and UI components into a single zero-dependency HTML file.
+
+Options:
+  -h, --help
+      Show this help message and exit.`);
+}
+
+if (process.argv.includes("-h") || process.argv.includes("--help")) {
+  printHelp();
+  process.exit(0);
+}
+
 console.log("=== Building Self-Contained K REPL HTML ===");
 
 // 1. Node shims plugin for esbuild

package/scripts/generate-dependency-graph.mjs

@@ -8,7 +8,31 @@ import { execSync } from "node:child_process";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const root = path.resolve(__dirname, "..");
-const outPath = path.join(root, "DOCS", "dependency-graph.md");
+
+function printHelp() {
+  console.log(
+`Usage: node scripts/generate-dependency-graph.mjs [options] [out]
+
+Generates a Mermaid dependency diagram from tracked ESM imports.
+
+Arguments:
+  out-file
+      Destination markdown file path.
+      (default: DOCS/dependency-graph.md)
+
+Options:
+  -h, --help
+      Show this help message and exit.`);
+}
+
+if (process.argv.includes("-h") || process.argv.includes("--help")) {
+  printHelp();
+  process.exit(0);
+}
+
+const outPath = process.argv[2]
+  ? path.resolve(root, process.argv[2])
+  : path.join(root, "DOCS", "dependency-graph.md");
 
 function getTrackedMjsFiles() {
   const raw = execSync("git ls-files '*.mjs'", {

package/scripts/perf-ieee.mjs

@@ -52,6 +52,81 @@ import {
 import { compileWasmArtifactFromObject } from "../backends/wasm/src/wasm.mjs";
 import { compileARM64ArtifactFromObject } from "../backends/arm64/src/arm64.mjs";
 
+function printHelp() {
+  console.log(`Usage: node scripts/perf-ieee.mjs [options]
+
+IEEE 754 Floating-Point Arithmetic Benchmark Harness.
+Benchmarks add, sub, mul, and div on Examples/ieee.k across
+Native JS, kVM interpreter, LLVM, Wasm, and ARM64 backends.
+
+Options:
+  --opt=<levels>, --opts=<levels>
+      Comma-separated Clang optimization levels for LLVM (e.g. -O1,-O2).
+  --O0, --O1, --O2, --O3
+      Direct Clang optimization level flags for LLVM.
+  --full
+      Run full LLVM optimization sweep (-O0, -O1, -O2).
+  --wasm-in-process
+      Run WebAssembly in-process instead of persistent subprocess runner.
+  -h, --help
+      Show this help message and exit.
+
+Environment Variables:
+  BACKENDS
+      Target backend to run: 'llvm', 'wasm', or 'arm64'.
+  LLVM_ONLY
+      Run only LLVM backend ('1' to enable).
+  WASM_ONLY
+      Run only WebAssembly backend ('1' to enable).
+  ARM64_ONLY
+      Run only ARM64 backend ('1' to enable).
+  BACKENDS_ONLY
+      Skip JS and kVM interpreter baselines ('1' to enable).
+  VALUES
+      Comma-separated float values to benchmark
+      (default: 0.5,-4,0,Infinity,-Infinity,NaN).
+  ITERATIONS
+      Measured iterations per benchmark (default: 3).
+  ARM64_WARMUP_ITERATIONS
+      Warmup iterations for ARM64 backend (default: 1).
+  ARM64_OPT
+      ARM64 backend optimization flags (default: -O2).
+  ARM64_SPAWN_PER_CALL
+      Spawn process per ARM64 call instead of persistent ('1' or '0').
+  ARM64_PIPELINE
+      Use persistent pipelined runner for ARM64 ('1' or '0').
+  LLVM_WARMUP_ITERATIONS
+      Warmup iterations for LLVM backend (default: 1).
+  LLVM_SPAWN_PER_CALL
+      Spawn process per LLVM call instead of persistent ('1' or '0').
+  LLVM_PIPELINE
+      Use persistent pipelined runner for LLVM ('1' or '0').
+  LLVM_OPTS
+      Comma-separated Clang optimization levels for LLVM.
+  K_LLVM_IEEE_RUNTIME_MODE
+      LLVM runtime compilation mode for IEEE (default: fast).
+  K_LLVM_IEEE_CLANG_OPT
+      Clang optimization levels for IEEE LLVM (default: -O1).
+  K_LLVM_CACHE_DIR
+      Directory to cache compiled LLVM executable binaries.
+  PERF_FULL
+      Set to '1' to test multiple LLVM optimization levels
+      (-O0, -O1, -O2).
+  WASM_WARMUP_ITERATIONS
+      Warmup iterations for WebAssembly backend (default: 10).
+  WASM_RESET
+      Reset WebAssembly memory between iterations (default: 1).
+  WASM_PIPE
+      Use persistent subprocess for Wasm (default: 1, '0': in-process).
+  WASM_IN_PROCESS
+      Run WebAssembly in-process ('1' to enable).`);
+}
+
+if (process.argv.includes("-h") || process.argv.includes("--help")) {
+  printHelp();
+  process.exit(0);
+}
+
 // Backend selection
 const backendsEnv = process.env.BACKENDS?.toLowerCase();
 const llvmOnly = process.env.LLVM_ONLY === "1" || backendsEnv === "llvm";

package/scripts/perf-int.mjs

@@ -56,6 +56,73 @@ import {
 import { compileARM64ArtifactFromObject } from "../backends/arm64/src/arm64.mjs";
 import { compileWasmArtifactFromObject } from "../backends/wasm/src/wasm.mjs";
 
+function printHelp() {
+  console.log(`Usage: node scripts/perf-int.mjs [options]
+
+Big Integer Arithmetic Performance Benchmark Harness.
+Benchmarks plus, minus, times, and squaring scale on arithmetics.k
+across Native JS, kVM interpreter, LLVM, Wasm, and ARM64 backends.
+
+Options:
+  --wasm-in-process
+      Run WebAssembly in-process instead of persistent subprocess runner.
+  -h, --help
+      Show this help message and exit.
+
+Environment Variables:
+  BACKENDS
+      Target backend to run: 'llvm', 'wasm', or 'arm64'.
+  LLVM_ONLY
+      Run only LLVM backend ('1' to enable).
+  WASM_ONLY
+      Run only WebAssembly backend ('1' to enable).
+  ARM64_ONLY
+      Run only ARM64 backend ('1' to enable).
+  BACKENDS_ONLY
+      Skip JS and kVM interpreter baselines ('1' to enable).
+  INPUTS
+      Comma-separated integer strings to benchmark.
+  ITERATIONS
+      Measured iterations per benchmark (default: 3).
+  ARM64_WARMUP_ITERATIONS
+      Warmup iterations for ARM64 backend (default: 1).
+  ARM64_OPT
+      ARM64 backend optimization flags (default: -O2).
+  ARM64_SPAWN_PER_CALL
+      Spawn process per ARM64 call instead of persistent ('1' or '0').
+  ARM64_PIPELINE
+      Use persistent pipelined runner for ARM64 ('1' or '0').
+  LLVM_WARMUP_ITERATIONS
+      Warmup iterations for LLVM backend (default: 1).
+  LLVM_SPAWN_PER_CALL
+      Spawn process per LLVM call instead of persistent ('1' or '0').
+  LLVM_PIPELINE
+      Use persistent pipelined runner for LLVM ('1' or '0').
+  K_LLVM_CACHE_DIR
+      Directory to cache compiled LLVM executable binaries.
+  WASM_WARMUP_ITERATIONS
+      Warmup iterations for WebAssembly backend (default: 3).
+  WASM_RESET
+      Reset WebAssembly memory between iterations (default: 1).
+  WASM_PIPE
+      Use persistent subprocess for Wasm (default: 1, '0': in-process).
+  WASM_IN_PROCESS
+      Run WebAssembly in-process ('1' to enable).
+  SQUARING_INPUT
+      Initial integer for squaring benchmark (default: 987654321).
+  SQUARING_STEPS
+      Number of squaring steps (default: 10).
+  SQUARING_STEP_TIMEOUT_MS
+      Timeout per squaring step in milliseconds (default: 60000).
+  K_ARENA_CAPACITY_MB
+      Memory arena capacity in MB (default: 4096).`);
+}
+
+if (process.argv.includes("-h") || process.argv.includes("--help")) {
+  printHelp();
+  process.exit(0);
+}
+
 // Backend selection
 const backendsEnv = process.env.BACKENDS?.toLowerCase();
 const llvmOnly = process.env.LLVM_ONLY === "1" || backendsEnv === "llvm";