@fraczak/k 7.0.2 → 7.2.0

package/backends/llvm/tests/test-llvm.mjs

@@ -1,7 +1,14 @@
 import assert from "node:assert";
 import { compileObjectBuffer, decodeObject } from "@fraczak/k/object.mjs";
-import { compileObjectToLLVM, compileLLVMArtifactFromKVM, emitLLVMModule, llvmIdentifier } from "../src/llvm.mjs";
+import {
+  compileObjectToLLVM,
+  compileLLVMArtifactFromKVM,
+  compileLLVMArtifactFromPKIR,
+  emitLLVMModule,
+  llvmIdentifier
+} from "../src/llvm.mjs";
 import { objectToKVMArtifact } from "@fraczak/k/kvm.mjs";
+import { compileRelationToPKIR } from "@fraczak/k/backend-api.mjs";
 
 function kirP(body, { patternGraph = null } = {}) {
   return {
@@ -270,4 +277,18 @@ assert.match(kvmLLVM, /source_filename = "k-llvm:__main__"/);
 assert.match(kvmLLVM, /define %k_result @k_main/);
 assert.match(kvmLLVM, /store ptr %product_fields\d+, ptr %ptr_slot\d+/);
 
+// Test PKIR lowering via compileObjectToLLVM with usePKIR: true
+const pkirObjectLLVM = compileObjectToLLVM(productObject, {
+  usePKIR: true
+});
+assert.match(pkirObjectLLVM.llvm, /source_filename = "k-llvm:__main__"/);
+assert.match(pkirObjectLLVM.llvm, /define %k_result @k_main/);
+
+// Test compileLLVMArtifactFromPKIR directly
+const mainRel = productObject.rels[productObject.main || "__main__"];
+const pkirFromRel = compileRelationToPKIR(mainRel, "__main__");
+const pkirLLVM = compileLLVMArtifactFromPKIR(pkirFromRel);
+assert.match(pkirLLVM, /source_filename = "k-llvm:__main__"/);
+assert.match(pkirLLVM, /define %k_result @k_main/);
+
 console.log("OK");

package/backends/wasm/bin/k-wasm-compile.mjs

@@ -9,22 +9,39 @@ import {
   resolveProgramInput
 } from "../src/cli.mjs";
 
-function usage(stream = console.error) {
+function helpText() {
   const prog = argv[1] || "k-wasm-compile.mjs";
-  stream(`Usage: node ${prog} [options] [source-snippet | input-file [wasm-file]]`);
-  stream("Compile k source, .ko, or .kvm input into a standalone WebAssembly artifact.");
-  stream("");
-  stream("Arguments:");
-  stream("  source-snippet  Inline k source, in the same style as k.mjs.");
-  stream("  input-file      Source .k, .ko, or .kvm file. Reads UTF-8 source from stdin when omitted.");
-  stream("  wasm-file       Output .wasm path. Writes the binary artifact to stdout when omitted.");
-  stream("");
-  stream("Options:");
-  stream("  -o, --output     Specify output file path explicitly.");
-  stream("  --lib file       Load one .klib dependency before compiling.");
-  stream("  --export spec    Export a library alias into source scope. May be repeated.");
-  stream("                   spec is 'name' or 'libname:localname'.");
-  stream("  -h, --help       Show this help.");
+  return [
+    "Compile k source, .ko, .kvm, or .pkir into a WebAssembly (.wasm)",
+    "artifact.",
+    "",
+    `Usage: ${prog} [options]`,
+    "       [source-snippet | input-file [output-wasm]]",
+    "",
+    "Arguments:",
+    "  source-snippet   Inline k source snippet (in the style of k.mjs).",
+    "  input-file       Source .k, .ko, .kvm, or .pkir file.",
+    "                   Reads UTF-8 source from stdin when omitted.",
+    "  output-wasm      Output .wasm path. Writes to stdout if omitted.",
+    "",
+    "Options:",
+    "  -o, --output path  Specify output file path explicitly.",
+    "  --pkir             Lower via Polymorphic K IR (PKIR).",
+    "  --lib file         Load one .klib or .k library before compiling.",
+    "  --export spec      Export library alias into scope. Repeatable.",
+    "                     spec is 'name' or 'libname:localname'.",
+    "  -h, --help         Show this help.",
+    "",
+    "Examples:",
+    `  ${prog} 'x = |x; x x' program.wasm`,
+    `  ${prog} program.k -o program.wasm`,
+    `  ${prog} --pkir program.k -o program.wasm`,
+    `  ${prog} --lib core.klib --export add program.k program.wasm`
+  ].join("\n");
+}
+
+function usage(stream = console.error) {
+  stream(helpText());
 }
 
 try {
@@ -41,18 +58,28 @@ try {
     if (arg === "-o" || arg === "--output") {
       args.shift();
       explicitOutput = args.shift();
-      if (!explicitOutput) throw new Error("-o/--output requires a file argument");
+      if (!explicitOutput) {
+        throw new Error("-o/--output requires a file argument");
+      }
     } else {
       remainingArgs.push(args.shift());
     }
   }
 
-  const { libraries, exportSpecs } = parseCompileOptions(remainingArgs);
-  const input = resolveProgramInput(remainingArgs, { allowStdinSource: true });
+  const { libraries, exportSpecs, usePKIR } =
+    parseCompileOptions(remainingArgs);
+  const input = resolveProgramInput(remainingArgs, {
+    allowStdinSource: true
+  });
   const positionalOutput = remainingArgs.shift();
   if (remainingArgs.length > 0) throw new Error("Too many arguments");
   const outputPath = explicitOutput || positionalOutput || null;
-  const artifact = await compileProgramInput(input, { libraries, exportSpecs, stdin });
+  const artifact = await compileProgramInput(input, {
+    libraries,
+    exportSpecs,
+    stdin,
+    usePKIR
+  });
   if (outputPath == null) {
     stdout.write(artifact);
   } else {
@@ -60,6 +87,5 @@ try {
   }
 } catch (error) {
   console.error(error.stack || error.message || String(error));
-  usage();
   exit(1);
 }

package/backends/wasm/bin/k-wasm-run.mjs

@@ -5,31 +5,54 @@ import { argv, exit, stdin, stdout, stderr } from "node:process";
 
 import { instantiateWasmArtifact } from "../src/wasm.mjs";
 
-function usage(stream = console.error) {
+function helpText() {
   const prog = argv[1] || "k-wasm-run.mjs";
-  stream(`Usage: node ${prog} [ --server ] wasm-file [ input-file ]`);
-  stream("Run a standalone k WebAssembly artifact over a binary pattern+value stream.");
-  stream("");
-  stream("Arguments:");
-  stream("  wasm-file   Input .wasm artifact produced by k-wasm-compile.");
-  stream("  input-file  Optional binary input stream. Reads stdin when omitted.");
-  stream("");
-  stream("Options:");
-  stream("  --server    Run as a persistent server reading framed requests from stdin.");
-  stream("  -h, --help  Show this help.");
+  return [
+    "Run a standalone WebAssembly (.wasm) artifact over a binary",
+    "pattern+value wire stream.",
+    "",
+    `Usage: ${prog} [options] wasm-file [ input-wire-file ]`,
+    "",
+    "Arguments:",
+    "  wasm-file        Input .wasm artifact produced by k-wasm-compile.",
+    "  input-wire-file  Optional binary wire input (default: stdin).",
+    "",
+    "Options:",
+    "  --server    Run as persistent server reading framed requests from",
+    "              stdin.",
+    "  -h, --help  Show this help.",
+    "",
+    "Environment Variables:",
+    "  K_TRACE, TRACE  When '1', output phase tracing metrics to stderr.",
+    "",
+    "Examples:",
+    `  echo '"hello"' | k-json --parse | \\`,
+    `    ${prog} prog.wasm | k-json --print`,
+    `  ${prog} prog.wasm input.wire > output.wire`,
+    `  ${prog} --server prog.wasm`
+  ].join("\n");
+}
+
+function usage(stream = console.error) {
+  stream(helpText());
 }
 
 function readAll(stream) {
   return new Promise((resolve, reject) => {
     const chunks = [];
-    stream.on("data", (chunk) => chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)));
+    stream.on("data", (chunk) => {
+      chunks.push(
+        Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)
+      );
+    });
     stream.on("end", () => resolve(Buffer.concat(chunks)));
     stream.on("error", reject);
   });
 }
 
 async function runServer(runner) {
-  const tracing = process.env.K_TRACE === "1" || process.env.TRACE === "1";
+  const tracing =
+    process.env.K_TRACE === "1" || process.env.TRACE === "1";
   let inBuffer = Buffer.alloc(0);
   let readStartNs = 0n;
 
@@ -82,10 +105,17 @@ async function runServer(runner) {
           const encodeNs = trace.encodeNs;
           const ipcWriteNs = Number(tEnd - writeStart);
           const totalNs = Number(tEnd - (readStartNs > 0n ? readStartNs : t1));
-          stderr.write(`K_TRACE_PHASES backend=wasm ipc_read_ns=${ipcReadNs} decode_ns=${decodeNs} flat_in_ns=${flatInNs} eval_ns=${evalNs} flat_out_ns=${flatOutNs} encode_ns=${encodeNs} ipc_write_ns=${ipcWriteNs} total_ns=${totalNs}\n`);
+          stderr.write(
+            `K_TRACE_PHASES backend=wasm ipc_read_ns=${ipcReadNs} ` +
+              `decode_ns=${decodeNs} flat_in_ns=${flatInNs} ` +
+              `eval_ns=${evalNs} flat_out_ns=${flatOutNs} ` +
+              `encode_ns=${encodeNs} ipc_write_ns=${ipcWriteNs} ` +
+              `total_ns=${totalNs}\n`
+          );
         }
       } catch (err) {
-        stderr.write(`Wasm server error: ${err.stack || err.message || String(err)}\n`);
+        const msg = err.stack || err.message || String(err);
+        stderr.write(`Wasm server error: ${msg}\n`);
         exit(1);
       }
 
@@ -102,7 +132,7 @@ async function main() {
   }
 
   const isServer = rawArgs.includes("--server");
-  const args = rawArgs.filter(a => a !== "--server");
+  const args = rawArgs.filter((a) => a !== "--server");
 
   const wasmPath = args.shift();
   if (!wasmPath) throw new Error("Missing .wasm artifact path");
@@ -111,7 +141,9 @@ async function main() {
   const runner = await instantiateWasmArtifact(artifact);
 
   if (isServer) {
-    if (args.length > 0) throw new Error("Too many arguments for --server mode");
+    if (args.length > 0) {
+      throw new Error("Too many arguments for --server mode");
+    }
     await runServer(runner);
     return;
   }
@@ -119,14 +151,23 @@ async function main() {
   const inputPath = args.shift();
   if (args.length > 0) throw new Error("Too many arguments");
 
-  const input = await readAll(inputPath == null ? stdin : fs.createReadStream(inputPath));
-  const tracing = process.env.K_TRACE === "1" || process.env.TRACE === "1";
+  const inputStream =
+    inputPath == null ? stdin : fs.createReadStream(inputPath);
+  const input = await readAll(inputStream);
+  const tracing =
+    process.env.K_TRACE === "1" || process.env.TRACE === "1";
   if (tracing) {
     const res = runner.execute(input, { trace: true });
     stdout.write(res.outputWire);
     if (res.trace) {
       const trace = res.trace;
-      stderr.write(`K_TRACE_PHASES backend=wasm ipc_read_ns=0 decode_ns=${trace.decodeNs} flat_in_ns=${trace.flatInNs} eval_ns=${trace.evalNs} flat_out_ns=${trace.flatOutNs} encode_ns=${trace.encodeNs} ipc_write_ns=0 total_ns=${trace.evalNs}\n`);
+      stderr.write(
+        `K_TRACE_PHASES backend=wasm ipc_read_ns=0 ` +
+          `decode_ns=${trace.decodeNs} flat_in_ns=${trace.flatInNs} ` +
+          `eval_ns=${trace.evalNs} flat_out_ns=${trace.flatOutNs} ` +
+          `encode_ns=${trace.encodeNs} ipc_write_ns=0 ` +
+          `total_ns=${trace.evalNs}\n`
+      );
     }
   } else {
     stdout.write(runner.execute(input));

package/backends/wasm/bin/k-wasm.mjs

@@ -12,16 +12,40 @@ import {
 } from "../src/cli.mjs";
 import { runWasmArtifact } from "../src/wasm.mjs";
 
-function usage(stream = console.error) {
+function helpText() {
   const prog = argv[1] || "k-wasm.mjs";
-  stream(`Usage: node ${prog} [options] ( source-snippet | input-file ) [ input-file ]`);
-  stream("Compile k source, .ko, or .kvm input to WebAssembly in memory and run it over a binary pattern+value stream.");
-  stream("");
-  stream("Options:");
-  stream("  --lib file       Load one .klib dependency before compiling.");
-  stream("  --export spec    Export a library alias into source scope. May be repeated.");
-  stream("                   spec is 'name' or 'libname:localname'.");
-  stream("  -h, --help       Show this help.");
+  return [
+    "Compile k source, .ko, .kvm, or .pkir to WebAssembly in memory",
+    "and run it over a binary pattern+value wire stream.",
+    "",
+    `Usage: ${prog} [options]`,
+    "       ( source-snippet | input-file ) [ input-wire-file ]",
+    "",
+    "Arguments:",
+    "  source-snippet   Inline k source snippet (in the style of k.mjs).",
+    "  input-file       Source .k, .ko, .kvm, or .pkir file.",
+    "  input-wire-file  Optional binary wire input (default: stdin).",
+    "",
+    "Options:",
+    "  --lib file        Load one .klib or .k library before compiling.",
+    "  --export spec     Export library alias into scope. Repeatable.",
+    "                    spec is 'name' or 'libname:localname'.",
+    "  --pkir            Lower via Polymorphic K IR (PKIR).",
+    "  -h, --help        Show this help.",
+    "",
+    "Environment Variables:",
+    "  K_TRACE, TRACE    When '1', output phase tracing to stderr.",
+    "",
+    "Examples:",
+    `  echo '"abc"' | k-parse | ${prog} '{.1 0}' | k-print`,
+    `  echo '{"x":1,"y":2}' | k-json --parse | \\`,
+    `    ${prog} --lib Examples/poly.k --export concat \\`,
+    `      's={()xs,()ys}concat; s' | k-json --print`
+  ].join("\n");
+}
+
+function usage(stream = console.error) {
+  stream(helpText());
 }
 
 async function main() {
@@ -31,19 +55,29 @@ async function main() {
     return;
   }
 
-  const { libraries, exportSpecs } = parseCompileOptions(args);
+  const { libraries, exportSpecs, usePKIR } = parseCompileOptions(args);
   const programInput = resolveProgramInput(args);
   const inputPath = args.shift();
   if (args.length > 0) throw new Error("Too many arguments");
 
-  const inputBuffer = await readAll(inputPath == null ? stdin : fs.createReadStream(inputPath));
+  const inputBuffer = await readAll(
+    inputPath == null ? stdin : fs.createReadStream(inputPath)
+  );
+  if (inputBuffer.length === 0) {
+    throw new Error("No input wire data received on stdin");
+  }
+
   const { pattern: inputEnvelopePattern } = decodeWire(inputBuffer);
-  const artifact = await compileProgramInput(programInput, { libraries, exportSpecs, inputEnvelopePattern });
+  const artifact = await compileProgramInput(programInput, {
+    libraries,
+    exportSpecs,
+    inputEnvelopePattern,
+    usePKIR
+  });
   stdout.write(await runWasmArtifact(artifact, inputBuffer));
 }
 
 main().catch((error) => {
   console.error(error.stack || error.message || String(error));
-  usage();
   exit(1);
 });

package/backends/wasm/src/cli.mjs

@@ -1,26 +1,112 @@
 import fs from "node:fs";
 import path from "node:path";
 
-import { decodeObject, loadLibrary } from "@fraczak/k/backend-api.mjs";
+import {
+  compileLibrary,
+  decodeObject,
+  loadLibrary
+} from "@fraczak/k/backend-api.mjs";
 import {
   compileWasmArtifact,
   compileWasmArtifactFromKVM,
-  compileWasmArtifactFromObject
+  compileWasmArtifactFromObject,
+  compileWasmArtifactFromPKIR
 } from "./wasm.mjs";
 
 function readAll(stream) {
   return new Promise((resolve, reject) => {
     const chunks = [];
-    stream.on("data", (chunk) => chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)));
+    stream.on("data", (chunk) => {
+      chunks.push(
+        Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)
+      );
+    });
     stream.on("end", () => resolve(Buffer.concat(chunks)));
     stream.on("error", reject);
   });
 }
 
+export function buildExportPreamble(exports = [], libraries = []) {
+  if (exports.length === 0) return "";
+  const aliasMap = {};
+  for (const lib of libraries) {
+    for (const [name, hash] of Object.entries(lib.relAlias || {})) {
+      if (name !== "__main__") aliasMap[name] = hash;
+    }
+    for (const [hash, entry] of Object.entries(lib.meta || {})) {
+      if (entry?.type !== "rel") continue;
+      for (const origin of entry?.origins || []) {
+        if (origin?.name && origin.name !== "__main__") {
+          aliasMap[origin.name] = hash;
+        }
+      }
+    }
+  }
+  const lines = [];
+  for (const spec of exports) {
+    const [libName, localName] = spec.includes(":")
+      ? spec.split(":", 2)
+      : [spec, spec];
+    const hash = aliasMap[libName];
+    if (!hash) {
+      throw new Error(
+        `--export: '${libName}' not found in loaded libraries`
+      );
+    }
+    const body = hash.startsWith("@") ? hash.slice(1) : hash;
+    lines.push(`${localName} = @${body};`);
+  }
+  return lines.join("\n") + "\n";
+}
+
+export function loadLibraryFromPath(libPath) {
+  const ext = path.extname(libPath).toLowerCase();
+  if (ext === ".klib" || ext === ".ko") {
+    return loadLibrary(decodeObject(fs.readFileSync(libPath)));
+  }
+  if (ext === ".k") {
+    let depLibs = [];
+    const baseName = path.basename(libPath);
+    if (baseName === "poly.k") {
+      const dir = path.dirname(libPath);
+      const arithPath = path.join(dir, "arithmetics.k");
+      if (fs.existsSync(arithPath)) {
+        const arithLib = loadLibrary(
+          compileLibrary(fs.readFileSync(arithPath, "utf8"), {
+            source: arithPath
+          })
+        );
+        depLibs.push(arithLib);
+      }
+    }
+    const rawSource = fs.readFileSync(libPath, "utf8");
+    if (depLibs.length > 0) {
+      const neededExports = [
+        "0", "int", "inc", "dec", "nat", "zero_int?", "neg?", "GT"
+      ];
+      const preamble = buildExportPreamble(neededExports, depLibs);
+      const compiled = compileLibrary(preamble + rawSource, {
+        source: libPath,
+        libraries: depLibs
+      });
+      const mergedLib = loadLibrary(compiled);
+      for (const dep of depLibs) {
+        for (const [k, v] of Object.entries(dep.relAlias || {})) {
+          if (!mergedLib.relAlias[k]) mergedLib.relAlias[k] = v;
+        }
+      }
+      return mergedLib;
+    }
+    return loadLibrary(compileLibrary(rawSource, { source: libPath }));
+  }
+  throw new Error(`Unsupported library extension: ${ext}`);
+}
+
 function parseCompileOptions(args) {
   const libraries = [];
   const exportSpecs = [];
   let loadedLibrary = false;
+  let usePKIR = false;
 
   while (args.length > 0) {
     if (args[0] === "--") {
@@ -28,25 +114,34 @@ function parseCompileOptions(args) {
       break;
     }
     if (args[0] === "--lib") {
-      if (loadedLibrary) throw new Error("--lib may only be specified once");
+      if (loadedLibrary) {
+        throw new Error("--lib may only be specified once");
+      }
       args.shift();
       const libPath = args.shift();
       if (!libPath) throw new Error("--lib requires a file argument");
-      libraries.push(loadLibrary(decodeObject(fs.readFileSync(libPath))));
+      libraries.push(loadLibraryFromPath(libPath));
       loadedLibrary = true;
     } else if (args[0] === "--export") {
       args.shift();
       const spec = args.shift();
-      if (!spec) throw new Error("--export requires a spec argument (name or libname:localname)");
+      if (!spec) {
+        throw new Error(
+          "--export requires a spec argument (name or libname:localname)"
+        );
+      }
       exportSpecs.push(spec);
+    } else if (args[0] === "--pkir") {
+      args.shift();
+      usePKIR = true;
     } else if (args[0].startsWith("--")) {
-      throw new Error(`Unknown option: ${args[0]}`);
+      break;
     } else {
       break;
     }
   }
 
-  return { libraries, exportSpecs };
+  return { libraries, exportSpecs, usePKIR };
 }
 
 function fileInputType(filePath) {
@@ -54,6 +149,7 @@ function fileInputType(filePath) {
   if (ext === ".ko") return "ko";
   if (ext === ".kvm") return "kvm";
   if (ext === ".klib") return "klib";
+  if (ext === ".pkir") return "pkir";
   return "source-file";
 }
 
@@ -68,38 +164,55 @@ function resolveProgramInput(args, { allowStdinSource = false } = {}) {
   if (fs.existsSync(inputArg)) {
     const kind = fileInputType(inputArg);
     if (kind === "klib") {
-      throw new Error("Cannot compile a .klib library to WebAssembly without a main relation; load it with --lib.");
+      throw new Error(
+        "Cannot compile a .klib library to WebAssembly without a main " +
+          "relation; load it with --lib."
+      );
     }
     return { kind, path: inputArg, sourceName: inputArg };
   }
 
-  if ([".k", ".ko", ".kvm", ".klib", ".wasm"].includes(ext)) {
+  if ([".k", ".ko", ".kvm", ".klib", ".wasm", ".pkir"].includes(ext)) {
     throw new Error(`Input file not found: ${inputArg}`);
   }
 
-  return { kind: "inline-source", source: inputArg, sourceName: "<inline>" };
+  return {
+    kind: "inline-source",
+    source: inputArg,
+    sourceName: "<inline>"
+  };
 }
 
 async function compileProgramInput(
   input,
-  { libraries = [], exportSpecs = [], stdin = null, inputEnvelopePattern = null } = {}
+  {
+    libraries = [],
+    exportSpecs = [],
+    stdin = null,
+    inputEnvelopePattern = null,
+    usePKIR = false
+  } = {}
 ) {
   if (input.kind === "inline-source") {
     return compileWasmArtifact(input.source, {
       libraries,
       exports: exportSpecs,
       source: input.sourceName,
-      inputEnvelopePattern
+      inputEnvelopePattern,
+      usePKIR
     });
   }
 
   if (input.kind === "stdin-source") {
-    if (!stdin) throw new Error("stdin source requested without a stdin stream");
+    if (!stdin) {
+      throw new Error("stdin source requested without a stdin stream");
+    }
     return compileWasmArtifact((await readAll(stdin)).toString("utf8"), {
       libraries,
       exports: exportSpecs,
       source: input.sourceName,
-      inputEnvelopePattern
+      inputEnvelopePattern,
+      usePKIR
     });
   }
 
@@ -108,18 +221,27 @@ async function compileProgramInput(
       libraries,
       exports: exportSpecs,
       source: input.sourceName,
-      inputEnvelopePattern
+      inputEnvelopePattern,
+      usePKIR
     });
   }
 
   if (input.kind === "ko") {
-    return compileWasmArtifactFromObject(decodeObject(fs.readFileSync(input.path)), {
-      inputEnvelopePattern
+    const obj = decodeObject(fs.readFileSync(input.path));
+    return compileWasmArtifactFromObject(obj, {
+      inputEnvelopePattern,
+      usePKIR
     });
   }
 
+  if (input.kind === "pkir") {
+    const pkir = JSON.parse(fs.readFileSync(input.path, "utf8"));
+    return compileWasmArtifactFromPKIR(pkir);
+  }
+
   if (input.kind === "kvm") {
-    return compileWasmArtifactFromKVM(JSON.parse(fs.readFileSync(input.path, "utf8")));
+    const kvm = JSON.parse(fs.readFileSync(input.path, "utf8"));
+    return compileWasmArtifactFromKVM(kvm);
   }
 
   throw new Error(`Unsupported input kind: ${input.kind}`);