@fraczak/k 6.2.2 → 6.2.3

package/k.mjs

@@ -12,19 +12,20 @@ const prog = argv[1];
 let kScript, inputStream;
 
 function usage() {
-  console.error(`Usage: ${prog} [ --lib lib-file ]... ( k-expr | -k file ) [ input-file ]`);
+  console.error(`Usage: ${prog} [ --lib lib-file ]... [ --export spec ]... ( k-expr | -k file ) [ input-file ]`);
   console.error(`       E.g.,  echo '["zebara","ela"]' | k-parse --input-type '$x=<{} zebara, {} ela>; $v={x 0, x 1}; $v' | ${prog} '{.1 0}'`);
   console.error("Options:");
-  console.error("  --lib file   Load a .klib dependency before compiling. May be repeated.");
-  console.error("  -h, --help   Show this help.");
+  console.error("  --lib file      Load a .klib dependency before compiling. May be repeated.");
+  console.error("  --export spec   Export a library alias into scope. 'name' or 'libname:localname'. May be repeated.");
+  console.error("  -h, --help      Show this help.");
 }
 
-function compileFile(path, libraries) {
-  const buffer = fs.readFileSync(path);
+function compileFile(filePath, libraries, preamble) {
+  const buffer = fs.readFileSync(filePath);
   try {
     return objectToFunction(decodeObject(buffer));
   } catch {
-    return k.compile(buffer.toString("utf8"), { libraries });
+    return k.compile(preamble + buffer.toString("utf8"), { libraries });
   }
 }
 
@@ -36,13 +37,48 @@ function compileFile(path, libraries) {
     }
 
     const libraries = [];
-    // Parse --lib flags
-    while (args.length > 0 && args[0] === "--lib") {
-      args.shift();
-      const libPath = args.shift();
-      if (!libPath) throw new Error("--lib requires a file argument");
-      const libBuffer = fs.readFileSync(libPath);
-      libraries.push(loadLibrary(decodeObject(libBuffer)));
+    const exports = [];
+    // Parse --lib and --export flags
+    while (args.length > 0 && args[0].startsWith("--")) {
+      if (args[0] === "--lib") {
+        args.shift();
+        const libPath = args.shift();
+        if (!libPath) throw new Error("--lib requires a file argument");
+        const libBuffer = fs.readFileSync(libPath);
+        libraries.push(loadLibrary(decodeObject(libBuffer)));
+      } else if (args[0] === "--export") {
+        args.shift();
+        const spec = args.shift();
+        if (!spec) throw new Error("--export requires a spec argument");
+        exports.push(spec);
+      } else {
+        break;
+      }
+    }
+
+    function buildExportPreamble() {
+      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";
     }
 
     let kScriptStr = (function (arg) {
@@ -50,9 +86,9 @@ function compileFile(path, libraries) {
         throw new Error("Missing script argument");
       }
       if (arg === "-k") {
-        return compileFile(args.shift(), libraries);
+        return compileFile(args.shift(), libraries, buildExportPreamble());
       } else {
-        return arg;
+        return buildExportPreamble() + arg;
       }
     })(args.shift());
     let kScript = typeof kScriptStr === "function" ? kScriptStr : k.compile(kScriptStr, { libraries });

package/objects/README.md

@@ -6,27 +6,17 @@ CLI tools for compiling and inspecting k object files (`.ko`) and library files
 
 ### `k-compile`
 
-Compiles a `.k` source file into an executable object file (`.ko`).
-The output contains only the codes and relations reachable from `main`.
-Each stored relation includes `typeDerivation.status` for backend eligibility.
+Compiles `.k` source into an executable object file (`.ko`), library file
+(`.klib`), or kVM JSON (`.kvm`). Output format is inferred from the output
+extension, or from `--format`.
 
 ```bash
-k-compile [--lib lib-file]... [k-file [object-file]]
+k-compile [--lib lib-file]... [--format ko|klib|kvm] [source-snippet | input-file [output-file]]
 ```
 
-### `k-compile-lib`
-
-Compiles a `.k` source file into a library file (`.klib`).
-The output is plain JSON with no binary header. It contains the library closure
-formed from loaded `--lib` dependencies plus the compiled source definitions,
-with `main: null`.
-Use `--lib` to build on top of existing libraries.
-Each stored relation includes `typeDerivation.status`; libraries may contain a
-mix of converged and non-converged relations.
-
-```bash
-k-compile-lib [--lib lib-file]... [k-file [lib-file]]
-```
+Existing input paths are read as files. A non-existing input with `.k`, `.ko`,
+or `.klib` extension is reported as a missing file; otherwise it is compiled as
+inline k source, in the same style as `k.mjs`.
 
 ### `k-decompile`
 

package/objects/compile.mjs

@@ -1,26 +1,50 @@
 #!/usr/bin/env node
 
 import fs from "node:fs";
+import path from "node:path";
 import { argv, exit, stdin, stdout } from "node:process";
-import { compileObjectBuffer, decodeObject, loadLibrary } from "../object.mjs";
+import {
+  compileObjectBuffer,
+  compileLibraryBuffer,
+  decodeObject,
+  loadLibrary
+} from "../object.mjs";
+import { lowerToKVM } from "../kvm.mjs";
+import { annotate } from "../index.mjs";
 
 function helpText() {
   return [
-    "Compile a k source file into an executable .ko object.",
-    "The object records type-derivation convergence for each stored relation.",
+    "Compile a k source, .ko, or .klib into .ko, .klib, or .kvm output.",
+    "Output format is inferred from the output file extension, or from --format.",
     "",
-    `Usage: ${argv[1]} [ --lib lib-file ]... [ k-file [ object-file ] ]`,
+    `Usage: ${argv[1]} [options] [source-snippet | input-file [output-file]]`,
     "",
     "Arguments:",
-    "  k-file       Source .k file to compile. Reads UTF-8 source from stdin when omitted.",
-    "  object-file  Output .ko path. Writes binary object data to stdout when omitted.",
+    "  source-snippet  Inline k source, in the same style as k.mjs.",
+    "  input-file      Source .k, .ko, or .klib file. Reads UTF-8 source from stdin when omitted.",
+    "  output-file     Output path (.ko, .klib, or .kvm). Writes to stdout when omitted.",
     "",
     "Options:",
-    "  --lib file   Load a .klib dependency before compiling. May be repeated.",
-    "  -h, --help   Show this help.",
+    "  --lib file       Load a .klib dependency before compiling. May be repeated.",
+    "  --export spec    Export a library alias into the source scope. May be repeated.",
+    "                   spec is 'name' or 'libname:localname'.",
+    "  --format fmt     Output format: ko, klib, or kvm. Overrides extension detection.",
+    "  -h, --help       Show this help.",
     "",
-    "Example:",
-    `  ${argv[1]} --lib core.klib program.k program.ko`
+    "Existing input paths are read as files. A non-existing input with .k, .ko,",
+    "or .klib extension is reported as a missing file; otherwise it is compiled",
+    "as inline k source.",
+    "",
+    "When input is .ko and output is .kvm, the object's relations are lowered",
+    "to kVM. A .klib input can only be copied to .klib output.",
+    "",
+    "Examples:",
+    `  ${argv[1]} 'x = |x; x x'`,
+    `  ${argv[1]} program.k program.ko`,
+    `  ${argv[1]} program.k program.klib`,
+    `  ${argv[1]} program.k program.kvm`,
+    `  ${argv[1]} program.ko program.kvm`,
+    `  ${argv[1]} --lib core.klib --export add --export mul:times program.k program.ko`
   ].join("\n");
 }
 
@@ -28,12 +52,100 @@ function usage(stream = console.error) {
   stream(helpText());
 }
 
-async function readStdinText() {
+async function readStdinBytes() {
   const chunks = [];
   for await (const chunk of stdin) {
     chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
   }
-  return Buffer.concat(chunks).toString("utf8");
+  return Buffer.concat(chunks);
+}
+
+function inferFormat(outputPath) {
+  if (!outputPath) return "ko";
+  const ext = path.extname(outputPath).toLowerCase();
+  if (ext === ".klib") return "klib";
+  if (ext === ".kvm") return "kvm";
+  return "ko";
+}
+
+function inferInputType(inputPath) {
+  if (!inputPath) return "k";
+  const ext = path.extname(inputPath).toLowerCase();
+  if (ext === ".ko") return "ko";
+  if (ext === ".klib") return "klib";
+  return "k";
+}
+
+function resolveInput(inputArg) {
+  if (inputArg == null) {
+    return { kind: "stdin", type: "k", sourceName: "<stdin>" };
+  }
+
+  const ext = path.extname(inputArg).toLowerCase();
+  if (fs.existsSync(inputArg)) {
+    return {
+      kind: "file",
+      type: inferInputType(inputArg),
+      path: inputArg,
+      sourceName: inputArg
+    };
+  }
+
+  if (ext === ".k" || ext === ".ko" || ext === ".klib") {
+    throw new Error(`Input file not found: ${inputArg}`);
+  }
+
+  return {
+    kind: "inline",
+    type: "k",
+    source: inputArg,
+    sourceName: "<inline>"
+  };
+}
+
+function buildExportPreamble(exports, libraries) {
+  if (exports.length === 0) return "";
+  // Build a combined alias map from all libraries: name -> @hash
+  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";
+}
+
+function compileToKVM(source, options) {
+  const defs = annotate(source, options);
+  const kvmProgram = {};
+  for (const [name, relDef] of Object.entries(defs.rels)) {
+    kvmProgram[name] = lowerToKVM(relDef, name);
+  }
+  return JSON.stringify(kvmProgram, null, 2) + "\n";
+}
+
+function objectToKVM(object) {
+  const kvmProgram = {};
+  for (const [name, relDef] of Object.entries(object.rels)) {
+    kvmProgram[name] = lowerToKVM(relDef, name);
+  }
+  return JSON.stringify(kvmProgram, null, 2) + "\n";
 }
 
 try {
@@ -44,24 +156,101 @@ try {
   }
 
   const libraries = [];
-  while (args.length > 0 && args[0] === "--lib") {
-    args.shift();
-    const libPath = args.shift();
-    if (!libPath) throw new Error("--lib requires a file argument");
-    libraries.push(loadLibrary(decodeObject(fs.readFileSync(libPath))));
+  let format = null;
+  const exports = [];
+
+  while (args.length > 0) {
+    if (args[0] === "--") {
+      args.shift();
+      break;
+    }
+    if (args[0] === "--lib") {
+      args.shift();
+      const libPath = args.shift();
+      if (!libPath) throw new Error("--lib requires a file argument");
+      libraries.push(loadLibrary(decodeObject(fs.readFileSync(libPath))));
+    } 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)");
+      exports.push(spec);
+    } else if (args[0] === "--format") {
+      args.shift();
+      format = args.shift();
+      if (!["ko", "klib", "kvm"].includes(format))
+        throw new Error(`Unknown format: ${format}. Use ko, klib, or kvm.`);
+    } else if (args[0].startsWith("--")) {
+      throw new Error(`Unknown option: ${args[0]}`);
+    } else {
+      break;
+    }
+  }
+
+  const inputArg = args.shift() || null;
+  const outputPath = args.shift() || null;
+  if (args.length > 0) {
+    throw new Error(`Unexpected argument: ${args[0]}`);
+  }
+
+  const outputFormat = format || inferFormat(outputPath);
+  const input = resolveInput(inputArg);
+  const inputType = input.type;
+
+  let output;
+
+  if (inputType === "ko" || inputType === "klib") {
+    const buffer = input.kind === "stdin" ? await readStdinBytes() : fs.readFileSync(input.path);
+    const object = decodeObject(buffer);
+    if (inputType === "klib") {
+      libraries.push(loadLibrary(object));
+    }
+
+    if (outputFormat === "kvm") {
+      if (inputType === "klib") {
+        throw new Error("Cannot produce .kvm from .klib alone; use a .ko or .k input.");
+      }
+      output = objectToKVM(object);
+    } else if (outputFormat === "ko") {
+      if (inputType === "ko") {
+        // already a .ko, just copy
+        output = buffer;
+      } else {
+        throw new Error("Cannot produce .ko from .klib without a main expression; provide .k source instead.");
+      }
+    } else if (outputFormat === "klib") {
+      if (inputType === "klib") {
+        output = buffer;
+      } else {
+        throw new Error("Cannot produce .klib from .ko; provide .k source instead.");
+      }
+    }
+  } else {
+    // Input is .k source
+    const rawSource = input.kind === "stdin"
+      ? (await readStdinBytes()).toString("utf8")
+      : input.kind === "inline"
+        ? input.source
+        : fs.readFileSync(input.path, "utf8");
+    const preamble = buildExportPreamble(exports, libraries);
+    const source = preamble + rawSource;
+    const opts = { source: input.sourceName, libraries };
+
+    if (outputFormat === "ko") {
+      output = compileObjectBuffer(source, opts);
+    } else if (outputFormat === "klib") {
+      output = compileLibraryBuffer(source, opts);
+    } else if (outputFormat === "kvm") {
+      output = compileToKVM(source, opts);
+    }
   }
 
-  const sourcePath = args.shift();
-  const outputPath = args.shift();
-  const source = sourcePath == null ? await readStdinText() : fs.readFileSync(sourcePath, "utf8");
-  const objectBuffer = compileObjectBuffer(source, { source: sourcePath || "<stdin>", libraries });
   if (outputPath == null) {
-    stdout.write(objectBuffer);
+    stdout.write(output);
   } else {
-    fs.writeFileSync(outputPath, objectBuffer);
+    fs.writeFileSync(outputPath, output);
   }
 } catch (error) {
-  console.error(error);
+  console.error(error.message || String(error));
   usage();
   exit(1);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@fraczak/k",
-    "version": "6.2.2",
+    "version": "6.2.3",
     "description": "k — a language for composing first-order partial functions over algebraic data types (products and tagged unions); includes runtime, type derivation, REPL, and codec toolchain",
     "main": "index.mjs",
     "scripts": {
@@ -18,7 +18,6 @@
     "bin": {
         "k": "./k.mjs",
         "k-compile": "./objects/compile.mjs",
-        "k-compile-lib": "./objects/compile-lib.mjs",
         "k-decompile": "./objects/decompile.mjs",
         "k-extract-aliases": "./objects/extract-aliases.mjs",
         "k-ieee": "./codecs/ieee.mjs",

package/scripts/benchmark-idempotency.mjs

@@ -44,7 +44,7 @@ function formatBytes(value) {
   return `${value} B`;
 }
 
-console.log(`compile-lib/decompile round-trip benchmark (${iterations} iterations)`);
+console.log(`compile/decompile .klib round-trip benchmark (${iterations} iterations)`);
 console.log("example, median, min, max, object");
 
 for (const example of benchmarkExamples) {
@@ -54,9 +54,9 @@ for (const example of benchmarkExamples) {
   for (let i = 0; i < iterations; i++) {
     const out = mkdtempSync(join(tmpdir(), `k-idempotency-bench-${example.replaceAll("/", "_")}-`));
     const t0 = performance.now();
-    run(["objects/compile-lib.mjs", example, join(out, "1.klib")]);
+    run(["objects/compile.mjs", example, join(out, "1.klib")]);
     run(["objects/decompile.mjs", join(out, "1.klib"), join(out, "1.k")]);
-    run(["objects/compile-lib.mjs", join(out, "1.k"), join(out, "2.klib")]);
+    run(["objects/compile.mjs", join(out, "1.k"), join(out, "2.klib")]);
     run(["objects/decompile.mjs", join(out, "2.klib"), join(out, "2.k")]);
     times.push(performance.now() - t0);
     size = statSync(join(out, "1.klib")).size;

package/tests/integration.sh

@@ -8,6 +8,23 @@ echo "Running './tests/integration.sh' ..."
 TMP_DIR=`mktemp -d`
 trap 'rm -rf "$TMP_DIR"' EXIT
 
+./objects/compile.mjs 'x = |x; x x' "$TMP_DIR/inline.ko"
+./objects/decompile.mjs "$TMP_DIR/inline.ko" | grep -q '^----- main -----$'
+printf '()' | ./objects/compile.mjs > "$TMP_DIR/stdin.ko"
+./objects/decompile.mjs "$TMP_DIR/stdin.ko" | grep -q '^----- main -----$'
+./objects/compile.mjs --format kvm '()' | grep -q '"__main__"'
+./objects/compile.mjs "$TMP_DIR/stdin.ko" "$TMP_DIR/stdin.kvm"
+grep -q '"__main__"' "$TMP_DIR/stdin.kvm"
+./objects/compile.mjs 'id = ();' "$TMP_DIR/export.klib"
+./objects/compile.mjs --lib "$TMP_DIR/export.klib" --export id:alias 'alias' "$TMP_DIR/export.ko"
+./objects/decompile.mjs "$TMP_DIR/export.ko" | grep -q '^----- main -----$'
+node ./codecs/unit.mjs --parse | ./k.mjs --lib "$TMP_DIR/export.klib" --export id:alias 'alias' | node ./codecs/unit.mjs --print | grep -qx '{}'
+if ./objects/compile.mjs "$TMP_DIR/missing.k" > "$TMP_DIR/missing.out" 2> "$TMP_DIR/missing.err"; then
+  echo "expected missing .k input to fail" >&2
+  exit 1
+fi
+grep -q 'Input file not found:' "$TMP_DIR/missing.err"
+
 echo '["zebara", "ela", "kupa", ala, owca]' | node ./codecs/k-parse.mjs | ./k.mjs '{.1 0,.3 1}' | node ./codecs/k-print.mjs
 echo 
 echo '-21' | node ./codecs/int.mjs --parse | node ./codecs/int.mjs --print | grep -qx -- '-21'
@@ -16,7 +33,7 @@ node ./codecs/unit.mjs --parse | node ./codecs/unit.mjs --print | grep -qx '{}'
 echo 
 printf 'A🙂\nBé~\t' | ./codecs/utf8.mjs --parse | ./k.mjs -k Examples/byte.k |./codecs/utf8.mjs --print
 echo
-./objects/compile-lib.mjs Examples/ieee.k "$TMP_DIR/ieee.klib"
+./objects/compile.mjs Examples/ieee.k "$TMP_DIR/ieee.klib"
 MUL=`./objects/extract-aliases.mjs "$TMP_DIR/ieee.klib" | grep '^mul = @' | sed 's/^mul = \(@[^;]*\);.*$/\1/'`
 DIV=`./objects/extract-aliases.mjs "$TMP_DIR/ieee.klib" | grep '^div = @' | sed 's/^div = \(@[^;]*\);.*$/\1/'`
 ARG=0.12

package/objects/compile-lib.mjs

@@ -1,67 +0,0 @@
-#!/usr/bin/env node
-
-import fs from "node:fs";
-import { argv, exit, stdin, stdout } from "node:process";
-import { compileLibraryBuffer, decodeObject, loadLibrary } from "../object.mjs";
-
-function helpText() {
-  return [
-    "Compile a k source file into a plain-JSON .klib library object.",
-    "The library records type-derivation convergence for each stored relation.",
-    "",
-    `Usage: ${argv[1]} [ --lib lib-file ]... [ k-file [ lib-file ] ]`,
-    "",
-    "Arguments:",
-    "  k-file    Source .k file to compile. Reads UTF-8 source from stdin when omitted.",
-    "  lib-file  Output .klib path. Writes plain JSON library data to stdout when omitted.",
-    "",
-    "Options:",
-    "  --lib file   Load a .klib dependency before compiling. May be repeated.",
-    "  -h, --help   Show this help.",
-    "",
-    "Example:",
-    `  ${argv[1]} --lib core.klib library.k library.klib`
-  ].join("\n");
-}
-
-function usage(stream = console.error) {
-  stream(helpText());
-}
-
-async function readStdinText() {
-  const chunks = [];
-  for await (const chunk of stdin) {
-    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
-  }
-  return Buffer.concat(chunks).toString("utf8");
-}
-
-try {
-  const args = argv.slice(2);
-  if (args.includes("-h") || args.includes("--help")) {
-    usage(console.log);
-    exit(0);
-  }
-
-  const libraries = [];
-  while (args.length > 0 && args[0] === "--lib") {
-    args.shift();
-    const libPath = args.shift();
-    if (!libPath) throw new Error("--lib requires a file argument");
-    libraries.push(loadLibrary(decodeObject(fs.readFileSync(libPath))));
-  }
-
-  const sourcePath = args.shift();
-  const outputPath = args.shift();
-  const source = sourcePath == null ? await readStdinText() : fs.readFileSync(sourcePath, "utf8");
-  const objectBuffer = compileLibraryBuffer(source, { source: sourcePath || "<stdin>", libraries });
-  if (outputPath == null) {
-    stdout.write(objectBuffer);
-  } else {
-    fs.writeFileSync(outputPath, objectBuffer);
-  }
-} catch (error) {
-  console.error(error);
-  usage();
-  exit(1);
-}