@fraczak/k 6.3.2 → 6.4.0

package/backends/arm64/tests/integration.sh

@@ -0,0 +1,112 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+K_ROOT="$(cd "$SCRIPT_DIR/../../.." && pwd)"
+TMP_DIR=$(mktemp -d)
+trap 'rm -rf "$TMP_DIR"' EXIT
+
+echo "Running './backends/arm64/tests/integration.sh' ..."
+
+compare_json_envelope() {
+  local name=$1
+  local input=$2
+  local program=$3
+  printf '%s\n' "$input" |
+    node "$K_ROOT/codecs/json.mjs" --parse |
+    node "$K_ROOT/k.mjs" "$program" > "$TMP_DIR/native.kv"
+  printf '%s\n' "$input" |
+    node "$K_ROOT/codecs/json.mjs" --parse |
+    node "$K_ROOT/kvm.mjs" "$program" > "$TMP_DIR/kvm.kv"
+  printf '%s\n' "$input" |
+    node "$K_ROOT/codecs/json.mjs" --parse |
+    node "$K_ROOT/backends/arm64/bin/k-arm64.mjs" "$program" > "$TMP_DIR/arm64.kv"
+
+  if ! cmp -s "$TMP_DIR/native.kv" "$TMP_DIR/kvm.kv" ||
+     ! cmp -s "$TMP_DIR/native.kv" "$TMP_DIR/arm64.kv"; then
+    echo "output envelope mismatch for $name" >&2
+    exit 1
+  fi
+}
+
+echo "Testing basic tag injection..."
+node "$K_ROOT/codecs/unit.mjs" --parse |
+  node "$K_ROOT/backends/arm64/bin/k-arm64.mjs" '|ok' |
+  node "$K_ROOT/codecs/k-print.mjs" |
+  grep -qx '"ok"'
+
+echo "Testing record wrapping..."
+printf '{"a": {}, "b": {}}\n' |
+  node "$K_ROOT/codecs/k-parse.mjs" |
+  node "$K_ROOT/backends/arm64/bin/k-arm64.mjs" '|ok' |
+  node "$K_ROOT/codecs/k-print.mjs" |
+  grep -qx '{"ok":{"a":{},"b":{}}}'
+
+echo "Testing field projection with JSON codec..."
+printf '{"a":123,"b":true,"c":[1,2,"alsk"]}\n' |
+  node "$K_ROOT/codecs/json.mjs" --parse |
+  node "$K_ROOT/backends/arm64/bin/k-arm64.mjs" '.c' |
+  node "$K_ROOT/codecs/json.mjs" --print |
+  grep -qx '\[1,2,"alsk"\]'
+
+echo "Testing nested array projection..."
+compare_json_envelope "nested array string projection" \
+  '{"a":[1,2,"kupa"], "b": 123}' \
+  '.a.2'
+
+echo "Testing JSON number projection..."
+compare_json_envelope "projected JSON number" \
+  '{"a":[1,2,"kupa"], "b": 123}' \
+  '.b'
+
+echo "Testing closed product filter..."
+compare_json_envelope "closed product filter" \
+  '{"a":[1,2,"kupa"], "b": 123}' \
+  '?{X a, Y b}'
+
+echo "Testing record construction..."
+printf '{"a":[1,2,"kupa"], "b": 123}\n' |
+  node "$K_ROOT/codecs/json.mjs" --parse |
+  node "$K_ROOT/backends/arm64/bin/k-arm64.mjs" '{ .a.2 word, .b number }' |
+  node "$K_ROOT/codecs/json.mjs" --print |
+  grep -qx '{"number":123,"word":"kupa"}'
+
+echo "Testing standalone executable compilation and execution..."
+node "$K_ROOT/backends/arm64/bin/k-arm64-compile.mjs" -o "$TMP_DIR/dot-c" '.c'
+printf '{"a":123,"b":true,"c":[1,2,"alsk"]}\n' |
+  node "$K_ROOT/codecs/json.mjs" --parse |
+  node "$K_ROOT/backends/arm64/bin/k-arm64-run.mjs" "$TMP_DIR/dot-c" |
+  node "$K_ROOT/codecs/json.mjs" --print |
+  grep -qx '\[1,2,"alsk"\]'
+
+echo "Testing direct execution of compiled executable with --json..."
+printf '{"a":123,"b":true,"c":[1,2,"alsk"]}\n' |
+  node "$K_ROOT/codecs/json.mjs" --parse |
+  "$TMP_DIR/dot-c" --json |
+  grep -q 'exponent'
+
+echo "Testing compilation from .ko object..."
+node "$K_ROOT/objects/compile.mjs" '.c' "$TMP_DIR/dot-c.ko"
+printf '{"a":123,"b":true,"c":[1,2,"alsk"]}\n' |
+  node "$K_ROOT/codecs/json.mjs" --parse |
+  node "$K_ROOT/backends/arm64/bin/k-arm64.mjs" "$TMP_DIR/dot-c.ko" |
+  node "$K_ROOT/codecs/json.mjs" --print |
+  grep -qx '\[1,2,"alsk"\]'
+
+echo "Testing compilation to assembly (-S)..."
+node "$K_ROOT/backends/arm64/bin/k-arm64-compile.mjs" -S '.c' "$TMP_DIR/dot-c.s"
+test -s "$TMP_DIR/dot-c.s"
+grep -q "rel___main__" "$TMP_DIR/dot-c.s"
+
+echo "Testing library dependencies (--lib and --export)..."
+node "$K_ROOT/backends/arm64/bin/k-arm64-compile.mjs" \
+  --lib "$K_ROOT/Examples/arithmetics.k" \
+  --export plus:+ --export succ --export int \
+  '{succ int x,int y}+' \
+  -o "$TMP_DIR/lib-add"
+
+node "$K_ROOT/codecs/k-parse.mjs" <<< '{"x":{"succ":"zero"},"y":{"succ":{"succ":"zero"}}}' |
+  "$TMP_DIR/lib-add" --json |
+  grep -Fxq '{"+":{"1":"_"}}'
+
+echo "==> ARM64 Integration Tests Completed Successfully!"

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

@@ -0,0 +1,240 @@
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { execFileSync, execSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+import {
+  compileARM64Artifact,
+  compileARM64ArtifactFromKVM,
+  compileARM64ArtifactFromObject,
+  runARM64Artifact
+} from "../src/arm64.mjs";
+import {
+  compileKVMModuleToARM64,
+  emitMetadataC,
+  getTagEntries,
+  resetTagIds
+} from "../src/kvm2arm64.mjs";
+import { compileObjectBuffer, decodeObject } from "../../../object.mjs";
+import { objectToKVMArtifact } from "../../../kvm.mjs";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(__dirname, "../../..");
+
+console.log("==> Running ARM64 Backend Test Suite");
+
+// Helper to convert JSON value to wire buffer via codecs/k-parse.mjs
+function jsonToWire(jsonObj) {
+  const jsonStr = typeof jsonObj === "string" ? jsonObj : JSON.stringify(jsonObj);
+  return execFileSync("node", [path.join(ROOT, "codecs/k-parse.mjs")], {
+    input: jsonStr
+  });
+}
+
+// Helper to convert wire buffer to JSON value via codecs/k-print.mjs
+function wireToJSON(wireBuf) {
+  const outputStr = execFileSync("node", [path.join(ROOT, "codecs/k-print.mjs")], {
+    input: wireBuf,
+    encoding: "utf8"
+  });
+  return JSON.parse(outputStr.trim());
+}
+
+// 1. Identity / Unit Relation
+console.log("==> Test 1: Identity / Unit Relation");
+{
+  const source = `()`;
+  const artifact = compileARM64Artifact(source);
+  const inputWire = jsonToWire({});
+  const outWire = runARM64Artifact(artifact, inputWire);
+  const outJSON = wireToJSON(outWire);
+  assert.deepEqual(outJSON, {}, "Unit relation must return empty object {}");
+
+  // Test --json mode
+  const outJsonStr = runARM64Artifact(artifact, inputWire, { json: true });
+  assert.equal(outJsonStr.trim(), "{}", "--json mode must return {}");
+  console.log("  Passed!");
+}
+
+// 2. Boolean Negation (Variant Projection & Creation)
+console.log("==> Test 2: Boolean Negation (Variants)");
+{
+  const source = `
+    true = {} | true;
+    false = {} | false;
+    neg = < /true false, /false true >;
+    neg
+  `;
+  const artifact = compileARM64Artifact(source);
+
+  // Test neg(true) -> false
+  const trueWire = jsonToWire({ true: {} });
+  const falseWireOut = runARM64Artifact(artifact, trueWire);
+  assert.deepEqual(wireToJSON(falseWireOut), "false");
+
+  // Test neg(false) -> true
+  const falseWire = jsonToWire({ false: {} });
+  const trueWireOut = runARM64Artifact(artifact, falseWire);
+  assert.deepEqual(wireToJSON(trueWireOut), "true");
+
+  // Test --json mode
+  const jsonOut = runARM64Artifact(artifact, trueWire, { json: true });
+  assert.equal(jsonOut.trim(), '"false"');
+  console.log("  Passed!");
+}
+
+// 3. Product Projection and Field Swapping
+console.log("==> Test 3: Product Projection and Record Construction");
+{
+  const source = `
+    swap = { .y x, .x y };
+    swap
+  `;
+  const artifact = compileARM64Artifact(source);
+  const inWire = jsonToWire({ x: "a", y: "b" });
+  const outWire = runARM64Artifact(artifact, inWire);
+  assert.deepEqual(wireToJSON(outWire), { x: "b", y: "a" });
+  console.log("  Passed!");
+}
+
+// 4. Multi-branch Union with Backtracking
+console.log("==> Test 4: Multi-branch Union with Backtracking");
+{
+  const source = `
+    $ t = < {} a, {} b, {} c >;
+    classify = <
+      /a ({} | first),
+      /b ({} | second),
+      /c ({} | third)
+    >;
+    classify
+  `;
+  const artifact = compileARM64Artifact(source);
+
+  assert.deepEqual(wireToJSON(runARM64Artifact(artifact, jsonToWire({ a: {} }))), "first");
+  assert.deepEqual(wireToJSON(runARM64Artifact(artifact, jsonToWire({ b: {} }))), "second");
+  assert.deepEqual(wireToJSON(runARM64Artifact(artifact, jsonToWire({ c: {} }))), "third");
+  console.log("  Passed!");
+}
+
+// 5. Peano Addition with Tail-Call Optimization
+console.log("==> Test 5: Peano Addition with Tail Recursion Optimization");
+{
+  const source = `
+    $ nat = < {} 0, nat +1 >;
+    0 = {} | 0 $ nat;
+    inc = | +1 $ nat;
+    dec = $ nat / +1;
+    add = $ { nat x, nat y } <
+      { . x dec x, . y inc y } add,
+      . y
+    >;
+    add
+  `;
+  const artifact = compileARM64Artifact(source);
+
+  // 3 + 2 = 5
+  const n0 = "0";
+  const n1 = { "+1": n0 };
+  const n2 = { "+1": n1 };
+  const n3 = { "+1": n2 };
+  const n5 = { "+1": { "+1": n3 } };
+
+  const inWire = jsonToWire({ x: n3, y: n2 });
+  const outWire = runARM64Artifact(artifact, inWire);
+  assert.deepEqual(wireToJSON(outWire), n5);
+
+  // Test 0 + 2 = 2
+  const inWireZero = jsonToWire({ x: n0, y: n2 });
+  const outWireZero = runARM64Artifact(artifact, inWireZero);
+  assert.deepEqual(wireToJSON(outWireZero), n2);
+  console.log("  Passed!");
+}
+
+// 6. Deep Tail Recursion (testing stack safety with loop)
+console.log("==> Test 6: Deep Tail Recursion Loop");
+{
+  const source = `
+    $ nat = < {} 0, nat +1 >;
+    0 = {} | 0 $ nat;
+    inc = | +1 $ nat;
+    dec = $ nat / +1;
+    add = $ { nat x, nat y } <
+      { . x dec x, . y inc y } add,
+      . y
+    >;
+    add
+  `;
+  const artifact = compileARM64Artifact(source);
+
+  // Compute 50 + 1 = 51
+  let cur = "0";
+  for (let i = 0; i < 50; i++) cur = { "+1": cur };
+  const one = { "+1": "0" };
+
+  const inWire = jsonToWire({ x: cur, y: one });
+  const outWire = runARM64Artifact(artifact, inWire);
+  const outJSON = wireToJSON(outWire);
+
+  // Count the +1 depth
+  let count = 0;
+  let p = outJSON;
+  while (p && typeof p === "object" && "+1" in p) {
+    count++;
+    p = p["+1"];
+  }
+  assert.equal(count, 51, "50 + 1 must yield depth 51");
+  console.log("  Passed!");
+}
+
+// 7. Compilation to Assembly Text (-S)
+console.log("==> Test 7: Assembly Text Generation");
+{
+  const source = `true = {} | true; true`;
+  const { assembly, entryName } = compileARM64Artifact(source, { emit: "assembly" });
+  assert.ok(typeof assembly === "string", "Assembly output must be a string");
+  assert.ok(assembly.includes(".arch armv8-a"), "Assembly must target armv8-a");
+  assert.ok(assembly.includes(`.global ${entryName}`), "Assembly must export entry symbol");
+  assert.ok(assembly.includes("ret"), "Assembly must contain return instructions");
+  console.log("  Passed!");
+}
+
+// 8. Compilation from .kvm Artifact
+console.log("==> Test 8: Compilation from .kvm Artifact");
+{
+  const script = `
+    $ bool = < {} true, {} false >;
+    not = $ bool < /true ({} | false), /false ({} | true) >;
+    not
+  `;
+  const obj = decodeObject(compileObjectBuffer(script));
+  const kvm = objectToKVMArtifact(obj);
+
+  const artifact = compileARM64ArtifactFromKVM(kvm);
+  const inWire = jsonToWire({ true: {} });
+  const outWire = runARM64Artifact(artifact, inWire);
+  assert.deepEqual(wireToJSON(outWire), "false");
+  console.log("  Passed!");
+}
+
+// 9. Failure Case (Partial Relation Non-Match)
+console.log("==> Test 9: Failure Case (Relation Rejection)");
+{
+  const source = `
+    onlyA = /a ({} | success);
+    onlyA
+  `;
+  const artifact = compileARM64Artifact(source);
+  const inWireFail = jsonToWire({ b: {} });
+
+  assert.throws(
+    () => runARM64Artifact(artifact, inWireFail),
+    /failed with exit status 1/,
+    "Executable must exit with status 1 on partial relation failure"
+  );
+  console.log("  Passed!");
+}
+
+console.log("==> All ARM64 Backend Unit Tests Passed Successfully!");

package/backends/llvm/README.md

@@ -0,0 +1,135 @@
+# k-llvm
+
+Experimental LLVM backend prototype for `k`.
+
+This package lives under the `k` monorepo as `backends/llvm`. It consumes the
+backend bridge from the root `@fraczak/k` package and starts from compiled
+`.ko` objects:
+
+```text
+.k source -> .ko -> envelope-specialized KIR-P -> LLVM IR prototype
+```
+
+The first milestone is not performance. It is a stable backend pipeline that
+can load an object, specialize it through KIR-P, and produce an inspectable
+LLVM module.
+
+## Quick Start
+
+From the monorepo root, install the workspace dependencies, then run the
+backend from `backends/llvm`:
+
+```sh
+npm install
+cd backends/llvm
+node ../../objects/compile.mjs '()' /tmp/id.ko
+node ./bin/k-llvm-compile.mjs --input-pattern '[["open-product",[]]]' /tmp/id.ko /tmp/id.ll
+```
+
+The generated `.ll` embeds the envelope-specialized KIR-P contract as module
+data and exposes the first runtime ABI slice:
+
+```llvm
+%k_result = type { i32, ptr }
+
+define %k_result @k_main(ptr %rt, ptr %input)
+```
+
+`%rt` is an opaque runtime handle and `%input` is an opaque boxed `k_value*`.
+The first executable lowerings support identity, typed filters and singleton
+code filters, product field projection, product construction, variant
+construction, and variant projection. Unsupported operations return a nonzero
+status in `k_result`. These operations can compose through KIR `comp`.
+
+## CLI
+
+```sh
+k-llvm-build [options] object.ko output-exe
+k-llvm-compile [options] object.ko [output.ll]
+k-llvm-jit [options] object.ko
+k-llvm-run [options] object.ko [input.kv]
+```
+
+Options:
+
+- `--retype rel`: current option spelling for the relation to
+  envelope-specialize; defaults to the object's `main`.
+- `--input-pattern json-or-file`: KIR property-list input pattern; required
+  for `k-llvm-build`.
+- `--expect value-or-file`: for `k-llvm-run`, compare the output value against
+  expected value text.
+- `-h`, `--help`: show usage.
+
+Only `.ko` / `.klib` object input is supported in this first prototype.
+Source compilation remains owned by core `k`.
+Without `--expect`, `k-llvm-run` prints the result value as compact JSON.
+`k-llvm-build` emits a native executable that reads and writes the binary
+k pattern+value envelope used by `codecs/k-parse.mjs` and `codecs/k-print.mjs`.
+The executable checks the stdin envelope pattern against the compiled input
+pattern and encodes stdout with the compiled output pattern.
+`k-llvm-jit` reads the stdin binary envelope first, specializes the object with
+that input pattern, caches the native executable, and writes the compiled
+output envelope to stdout.
+The native envelope codec supports the k Unicode string encoding used for
+labels and tags.
+
+## Tests
+
+```sh
+npm test
+node ./scripts/conformance.mjs
+npm run perf:int
+npm run perf:ieee
+```
+
+The conformance runner reuses supported fixtures from `../../conformance`,
+emits LLVM IR for each fixture, generates a small C driver for the fixture
+input and expected value, links it with `runtime/krt.c`, and runs the binary.
+
+The performance runners mirror the `k-wasm` integer and IEEE harnesses. They
+load the real example programs from `@fraczak/k`, generate the same operation
+matrices, compare backend output to native `k` results, and time the native JS,
+kVM, and LLVM executable lanes. Set `LLVM_ONLY=1` to skip native timing,
+`ITERATIONS=N` to change samples, and `LLVM_STRICT=1` to make unsupported LLVM
+cases fail the process. The LLVM lane uses persistent executables by default;
+set `LLVM_PIPELINE=1` to measure parallel request pipelining or
+`LLVM_SPAWN_PER_CALL=1` to reproduce the older spawn-per-operation timing.
+
+## Scope
+
+Current output:
+
+- KIR-P envelope specialization through `@fraczak/k/backend-api.mjs`;
+- textual LLVM IR with embedded envelope-specialized KIR-P metadata;
+- boxed runtime ABI declarations;
+- identity, filter/code erasure, product projection/construction, and variant
+  construction/projection lowerings as `@k_main(k_rt*, k_value*) -> k_result`;
+- KIR `comp` lowering for sequencing supported operations;
+- KIR `empty` failure and ordered `union` branch selection;
+- KIR `ref` lowering to internal `%k_result` relation functions;
+- a tiny C runtime under `runtime/`.
+
+Next backend steps:
+
+- add an executable conformance mode once the runtime ABI exists.
+
+## Runtime ABI
+
+The C side owns all runtime allocation:
+
+```c
+typedef struct k_rt k_rt;
+typedef struct k_value k_value;
+
+typedef struct {
+  int32_t status;
+  k_value *value;
+} k_result;
+
+k_result k_main(k_rt *rt, k_value *input);
+```
+
+`runtime/krt.h` provides the initial boxed helpers for units, products,
+variants, and pointer equality. The representation is intentionally opaque so
+future KIR specialization can add unboxed fast paths without changing the
+external ABI.

package/backends/llvm/bin/k-llvm-build.mjs

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import { argv, exit } from "node:process";
+import { decodeObject } from "@fraczak/k/object.mjs";
+import { compileObjectToExecutable } from "../src/executable.mjs";
+
+function usage(stream = console.error) {
+  const prog = argv[1] || "k-llvm-build.mjs";
+  stream(`Usage: node ${prog} [options] object-file output-exe`);
+  stream("Compile a k .ko/.klib object into a native executable.");
+  stream("");
+  stream("The executable reads a binary k pattern+value envelope from stdin and");
+  stream("writes a binary k pattern+value envelope to stdout.");
+  stream("The stdin envelope pattern must match the compiled input pattern;");
+  stream("stdout is encoded with the compiled output pattern.");
+  stream("");
+  stream("Options:");
+  stream("  --retype rel            Relation to specialize. Defaults to object main.");
+  stream("  --input-pattern value   Required input pattern property-list JSON, or a file containing it.");
+  stream("  -h, --help              Show this help.");
+}
+
+function readMaybeFile(textOrPath) {
+  return fs.existsSync(textOrPath) ? fs.readFileSync(textOrPath, "utf8") : textOrPath;
+}
+
+function readPattern(inputPattern) {
+  if (inputPattern == null) return null;
+  return JSON.parse(readMaybeFile(inputPattern));
+}
+
+try {
+  const args = argv.slice(2);
+  if (args.includes("-h") || args.includes("--help")) {
+    usage(console.log);
+    exit(0);
+  }
+
+  let relation = null;
+  let inputPattern = null;
+  while (args.length > 0 && args[0].startsWith("--")) {
+    const option = args.shift();
+    if (option === "--retype") {
+      relation = args.shift();
+      if (!relation) throw new Error("--retype requires a relation name");
+    } else if (option === "--input-pattern") {
+      inputPattern = args.shift();
+      if (!inputPattern) throw new Error("--input-pattern requires JSON or a file path");
+    } else {
+      throw new Error(`Unknown option: ${option}`);
+    }
+  }
+
+  const objectPath = args.shift() || null;
+  const outputPath = args.shift() || null;
+  if (objectPath == null) throw new Error("object-file is required");
+  if (outputPath == null) throw new Error("output-exe is required");
+  if (args.length > 0) throw new Error(`Unexpected argument: ${args[0]}`);
+  if (inputPattern == null) throw new Error("--input-pattern is required for k-llvm-build");
+
+  const object = decodeObject(fs.readFileSync(objectPath));
+  compileObjectToExecutable(object, outputPath, {
+    relation: relation || object.main,
+    inputPattern: readPattern(inputPattern)
+  });
+} catch (error) {
+  console.error(error.stack || error.message || String(error));
+  usage();
+  exit(1);
+}

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

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import { argv, exit, stdin, stdout } from "node:process";
+import { compileBufferToLLVM } from "../src/llvm.mjs";
+
+function usage(stream = console.error) {
+  const prog = argv[1] || "k-llvm-compile.mjs";
+  stream(`Usage: node ${prog} [options] object-file [output.ll]`);
+  stream("Compile a k .ko/.klib object into prototype LLVM IR.");
+  stream("");
+  stream("Arguments:");
+  stream("  object-file     Input .ko or .klib file. Reads bytes from stdin when omitted.");
+  stream("  output.ll       Output LLVM IR path. Writes to stdout when omitted.");
+  stream("");
+  stream("Options:");
+  stream("  --retype rel            Relation to specialize. Defaults to object main.");
+  stream("  --input-pattern value   Input pattern property-list JSON, or a file containing it.");
+  stream("  -h, --help              Show this help.");
+}
+
+async function readStdinBytes() {
+  const chunks = [];
+  for await (const chunk of stdin) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  }
+  return Buffer.concat(chunks);
+}
+
+try {
+  const args = argv.slice(2);
+  if (args.includes("-h") || args.includes("--help")) {
+    usage(console.log);
+    exit(0);
+  }
+
+  let relation = null;
+  let inputPattern = null;
+  while (args.length > 0 && args[0].startsWith("--")) {
+    const option = args.shift();
+    if (option === "--retype") {
+      relation = args.shift();
+      if (!relation) throw new Error("--retype requires a relation name");
+    } else if (option === "--input-pattern") {
+      inputPattern = args.shift();
+      if (!inputPattern) throw new Error("--input-pattern requires JSON or a file path");
+    } else {
+      throw new Error(`Unknown option: ${option}`);
+    }
+  }
+  if (inputPattern == null) throw new Error("--input-pattern is required");
+
+  const inputPath = args.shift() || null;
+  const outputPath = args.shift() || null;
+  if (args.length > 0) throw new Error(`Unexpected argument: ${args[0]}`);
+
+  const input = inputPath == null ? await readStdinBytes() : fs.readFileSync(inputPath);
+  const { llvm } = compileBufferToLLVM(input, { relation, inputPattern });
+  if (outputPath == null) {
+    stdout.write(llvm);
+  } else {
+    fs.writeFileSync(outputPath, llvm);
+  }
+} catch (error) {
+  console.error(error.stack || error.message || String(error));
+  usage();
+  exit(1);
+}