@fraczak/k 7.0.2 → 7.1.0

package/codecs/show.mjs

@@ -6,13 +6,27 @@ import { isMainEntrypoint } from "./runtime/cli-entry.mjs";
 import { decodeWire } from "./runtime/prefix-codec.mjs";
 import { propertyListToFilter, valueToK } from "./runtime/show-value.mjs";
 
+function helpText() {
+  const prog = argv[1] || "show.mjs";
+  return [
+    "Pass a binary wire stream through unchanged on stdout while",
+    "printing the decoded value and filter to stderr.",
+    "",
+    `Usage: ${prog} [wire-file]`,
+    "",
+    "Arguments:",
+    "  wire-file    Input binary wire file (default: stdin).",
+    "",
+    "Options:",
+    "  -h, --help   Show this help.",
+    "",
+    "Examples:",
+    `  echo '"hello"' | k-parse | ${prog} | k-print`
+  ].join("\n");
+}
+
 function usage(stream = console.error) {
-  stream(`Usage: ${argv[1]} [wire-file]`);
-  stream("  Pass the wire stream through unchanged on stdout.");
-  stream("  Print the decoded value and filter to stderr.");
-  stream("");
-  stream("Options:");
-  stream("  -h, --help   Show this help.");
+  stream(helpText());
 }
 
 function readAll(stream) {

package/k.mjs

@@ -4,27 +4,58 @@
 import fs from "node:fs";
 import { argv, stdin, exit, stdout } from "node:process";
 import k from "./index.mjs";
-import { decodeWire, encodeToWire } from "./codecs/runtime/prefix-codec.mjs";
-import { decodeObject, objectToFunction, loadLibrary } from "./object.mjs";
-
-const prog = argv[1];
+import {
+  decodeWire,
+  encodeToWire
+} from "./codecs/runtime/prefix-codec.mjs";
+import {
+  compileLibrary,
+  decodeObject,
+  objectToFunction,
+  loadLibrary
+} from "./object.mjs";
 
 let kScript, inputStream;
 
-function usage() {
-  console.error(`Usage: ${prog} [ --lib lib-file ] [ --export spec ]... ( k-expr | 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 one .klib dependency before compiling.");
-  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 helpText() {
+  const prog = argv[1] || "k.mjs";
+  return [
+    "Compile and execute a k expression or file over a binary",
+    "pattern+value wire stream using the JavaScript interpreter.",
+    "",
+    `Usage: ${prog} [options]`,
+    "       ( source-snippet | input-file ) [ input-wire-file ]",
+    "",
+    "Arguments:",
+    "  source-snippet   Inline k source snippet.",
+    "  input-file       Source .k, .ko, or .klib 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'.",
+    "  -h, --help       Show this help.",
+    "",
+    "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());
 }
 
 function isFile(filePath) {
   try {
     return fs.statSync(filePath).isFile();
   } catch (error) {
-    if (error?.code === "ENOENT" || error?.code === "ENOTDIR") return false;
+    if (error?.code === "ENOENT" || error?.code === "ENOTDIR") {
+      return false;
+    }
     throw error;
   }
 }
@@ -41,7 +72,7 @@ function compileFile(filePath, libraries, preamble) {
 ({ kScript, inputStream } = ((args) => {
   try {
     if (args.includes("-h") || args.includes("--help")) {
-      usage();
+      usage(console.log);
       return exit(0);
     }
 
@@ -53,9 +84,18 @@ function compileFile(filePath, libraries, preamble) {
         args.shift();
         const libPath = args.shift();
         if (!libPath) throw new Error("--lib requires a file argument");
-        if (libraries.length > 0) throw new Error("--lib may be specified at most once");
-        const libBuffer = fs.readFileSync(libPath);
-        libraries.push(loadLibrary(decodeObject(libBuffer)));
+        if (libraries.length > 0) {
+          throw new Error("--lib may be specified at most once");
+        }
+        if (libPath.endsWith(".k")) {
+          const raw = fs.readFileSync(libPath, "utf8");
+          libraries.push(
+            loadLibrary(compileLibrary(raw, { source: libPath }))
+          );
+        } else {
+          const libBuffer = fs.readFileSync(libPath);
+          libraries.push(loadLibrary(decodeObject(libBuffer)));
+        }
       } else if (args[0] === "--export") {
         args.shift();
         const spec = args.shift();

package/kir.mjs

@@ -601,20 +601,27 @@ export default {
 };
 
 function helpText() {
+  const prog = argv[1] || "kir.mjs";
   return [
     "Export the KIR-P JSON view from a k .ko or .klib object.",
     "",
-    `Usage: ${argv[1]} [options] [object-file]`,
+    `Usage: ${prog} [options] [object-file]`,
     "",
     "Arguments:",
-    "  object-file    Input .ko or .klib file. Reads from stdin when omitted.",
+    "  object-file            Input .ko or .klib file (default: stdin).",
     "",
     "Options:",
+    "  -o, --output path      Specify output file path explicitly.",
     "  --retype rel           Export retyped KIR-P for relation rel.",
-    "  --input-pattern json   Input pattern property-list JSON, or a file containing it.",
-    "  -h, --help     Show this help.",
+    "  --input-pattern json   Input pattern JSON or file for spec.",
+    "  -h, --help             Show this help.",
     "",
-    "KIR-P is an inspection/export view; retyping also emits KIR-P."
+    "KIR-P is an inspection/export view; retyping also emits KIR-P.",
+    "",
+    "Examples:",
+    `  ${prog} program.ko`,
+    `  ${prog} program.ko -o program.kir.json`,
+    `  ${prog} --retype main --input-pattern pattern.json program.ko`
   ].join("\n");
 }
 
@@ -643,32 +650,64 @@ async function main() {
 
   let retypeRelation = null;
   let inputPatternArg = null;
-  while (args.length > 0 && args[0].startsWith("--")) {
-    const option = args.shift();
-    if (option === "--retype") {
+  let explicitOutput = null;
+  const remainingArgs = [];
+  while (args.length > 0) {
+    const arg = args[0];
+    if (arg === "-o" || arg === "--output") {
+      args.shift();
+      explicitOutput = args.shift();
+      if (!explicitOutput) {
+        throw new Error("-o/--output requires a file argument");
+      }
+    } else if (arg === "--retype") {
+      args.shift();
       retypeRelation = args.shift();
       if (!retypeRelation) throw new Error("--retype requires a relation name");
-    } else if (option === "--input-pattern") {
+    } else if (arg === "--input-pattern") {
+      args.shift();
       inputPatternArg = args.shift();
-      if (!inputPatternArg) throw new Error("--input-pattern requires JSON or a file path");
+      if (!inputPatternArg) {
+        throw new Error("--input-pattern requires JSON or a file path");
+      }
+    } else if (arg.startsWith("-")) {
+      throw new Error(`Unknown option: ${arg}`);
     } else {
-      throw new Error(`Unknown option: ${option}`);
+      remainingArgs.push(args.shift());
     }
   }
 
-  const inputPath = args.shift() || null;
-  if (args.length > 0) {
-    throw new Error(`Unexpected argument: ${args[0]}`);
+  const inputPath = remainingArgs.shift() || null;
+  if (remainingArgs.length > 0) {
+    throw new Error(`Unexpected argument: ${remainingArgs[0]}`);
   }
 
-  const buffer = inputPath == null ? await readStdinBytes() : fs.readFileSync(inputPath);
+  const buffer = inputPath == null
+    ? await readStdinBytes()
+    : fs.readFileSync(inputPath);
   const object = decodeObject(buffer);
+  let outputData;
   if (retypeRelation != null) {
-    if (inputPatternArg == null) throw new Error("--retype requires --input-pattern");
-    const inputPatternText = fs.existsSync(inputPatternArg) ? fs.readFileSync(inputPatternArg, "utf8") : inputPatternArg;
-    stdout.write(JSON.stringify(retypeObjectRelation(object, retypeRelation, JSON.parse(inputPatternText)), null, 2) + "\n");
+    if (inputPatternArg == null) {
+      throw new Error("--retype requires --input-pattern");
+    }
+    const inputPatternText = fs.existsSync(inputPatternArg)
+      ? fs.readFileSync(inputPatternArg, "utf8")
+      : inputPatternArg;
+    outputData = retypeObjectRelation(
+      object,
+      retypeRelation,
+      JSON.parse(inputPatternText)
+    );
+  } else {
+    outputData = objectToKIRP(object);
+  }
+
+  const json = JSON.stringify(outputData, null, 2) + "\n";
+  if (explicitOutput) {
+    fs.writeFileSync(explicitOutput, json, "utf8");
   } else {
-    stdout.write(JSON.stringify(objectToKIRP(object), null, 2) + "\n");
+    stdout.write(json);
   }
 }
 

package/kvm.mjs

@@ -9,7 +9,12 @@ import {
 } from "./run.mjs";
 import { decodeWire, encodeToWire } from "./codecs/runtime/prefix-codec.mjs";
 import { intersectPropertyListPatterns } from "./codecs/runtime/codec.mjs";
-import { compileObjectBuffer, decodeObject, loadLibrary } from "./object.mjs";
+import {
+  compileLibrary,
+  compileObjectBuffer,
+  decodeObject,
+  loadLibrary
+} from "./object.mjs";
 import codes from "./codes.mjs";
 import { isMainEntrypoint } from "./codecs/runtime/cli-entry.mjs";
 import { isIntrinsic, unsupportedIntrinsic } from "./intrinsics.mjs";
@@ -964,20 +969,43 @@ export default {
   specializeKVM
 };
 
-function usage() {
+function helpText() {
   const prog = argv[1] || "kvm.mjs";
-  console.error(`Usage: node ${prog} [ options ] ( k-expr | input-file ) [ input-file ]`);
-  console.error("Options:");
-  console.error("  --lib file          Load one .klib dependency before compiling.");
-  console.error("  --export spec       Export a library alias into scope. 'name' or 'libname:localname'. May be repeated.");
-  console.error("  --envelope-free     Run the interpreter in envelope-free mode.");
-  console.error("  -h, --help          Show this help.");
+  return [
+    "Execute a k expression or file via the kVM bytecode interpreter",
+    "over a binary pattern+value wire stream.",
+    "",
+    `Usage: ${prog} [options]`,
+    "       ( source-snippet | input-file ) [ input-wire-file ]",
+    "",
+    "Arguments:",
+    "  source-snippet   Inline k source snippet.",
+    "  input-file       Source .k, .ko, or .klib 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'.",
+    "  --envelope-free  Run the interpreter in envelope-free mode.",
+    "  -h, --help       Show this help.",
+    "",
+    "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() {
   const args = argv.slice(2);
   if (args.includes("-h") || args.includes("--help")) {
-    usage();
+    usage(console.log);
     return exit(0);
   }
 
@@ -994,9 +1022,18 @@ async function main() {
       args.shift();
       const libPath = args.shift();
       if (!libPath) throw new Error("--lib requires a file argument");
-      if (libraries.length > 0) throw new Error("--lib may be specified at most once");
-      const libBuffer = fs.readFileSync(libPath);
-      libraries.push(loadLibrary(decodeObject(libBuffer)));
+      if (libraries.length > 0) {
+        throw new Error("--lib may be specified at most once");
+      }
+      if (libPath.endsWith(".k")) {
+        const raw = fs.readFileSync(libPath, "utf8");
+        libraries.push(
+          loadLibrary(compileLibrary(raw, { source: libPath }))
+        );
+      } else {
+        const libBuffer = fs.readFileSync(libPath);
+        libraries.push(loadLibrary(decodeObject(libBuffer)));
+      }
     } else if (args[0] === "--export") {
       args.shift();
       const spec = args.shift();

package/objects/compile.mjs

@@ -13,38 +13,43 @@ import {
 import { objectToKVMArtifact } from "../kvm.mjs";
 
 function helpText() {
+  const prog = argv[1] || "compile.mjs";
   return [
-    "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.",
+    "Compile k source, .ko, or .klib into .ko, .klib, or .kvm output.",
+    "Output format is inferred from the output extension or --format.",
     "",
-    `Usage: ${argv[1]} [options] [source-snippet | input-file [output-file]]`,
+    `Usage: ${prog} [options]`,
+    "       [source-snippet | input-file [output-file]]",
     "",
     "Arguments:",
-    "  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.",
+    "  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 one .klib or .k library dependency before compiling.",
-    "  --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.",
+    "  -o, --output path  Specify output file path explicitly.",
+    "  --format fmt       Output format: ko, klib, or kvm.",
+    "                     Overrides extension detection.",
+    "  --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.",
     "",
-    "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.",
+    "Existing input paths are read as files. A non-existing input with",
+    ".k, .ko, or .klib extension is reported as missing; otherwise it is",
+    "compiled as inline k source.",
     "",
     ".kvm is a polymorphic kVM template artifact (layer: KVM-P).",
     "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]} --lib Examples/arithmetics.k --export plus:+ --export succ --export int '{succ int x,int y}+' a.kvm`,
-    `  ${argv[1]} --lib core.klib --export add --export mul:times program.k program.ko`
+    `  ${prog} 'x = |x; x x'`,
+    `  ${prog} program.k -o program.ko`,
+    `  ${prog} program.k program.klib`,
+    `  ${prog} program.k program.kvm`,
+    `  ${prog} --lib core.klib --export add program.k program.ko`
   ].join("\n");
 }
 
@@ -144,6 +149,7 @@ try {
 
   const libraries = [];
   let format = null;
+  let explicitOutput = null;
   const exports = [];
 
   while (args.length > 0) {
@@ -151,7 +157,13 @@ try {
       args.shift();
       break;
     }
-    if (args[0] === "--lib") {
+    if (args[0] === "-o" || args[0] === "--output") {
+      args.shift();
+      explicitOutput = args.shift();
+      if (!explicitOutput) {
+        throw new Error("-o/--output requires a file argument");
+      }
+    } else if (args[0] === "--lib") {
       args.shift();
       const libPath = args.shift();
       if (!libPath) throw new Error("--lib requires a file argument");
@@ -172,7 +184,7 @@ try {
       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("--")) {
+    } else if (args[0].startsWith("-")) {
       throw new Error(`Unknown option: ${args[0]}`);
     } else {
       break;
@@ -180,11 +192,13 @@ try {
   }
 
   const inputArg = args.shift() || null;
-  const outputPath = args.shift() || null;
+  const positionalOutput = args.shift() || null;
   if (args.length > 0) {
     throw new Error(`Unexpected argument: ${args[0]}`);
   }
 
+  const outputPath = explicitOutput || positionalOutput || null;
+
   const outputFormat = format || inferFormat(outputPath);
   const input = resolveInput(inputArg);
   const inputType = input.type;

package/objects/decompile.mjs

@@ -5,20 +5,24 @@ import { argv, exit, stdin, stdout } from "node:process";
 import { decompileObjectBuffer } from "../object.mjs";
 
 function helpText() {
+  const prog = argv[1] || "decompile.mjs";
   return [
     "Decompile a .ko or .klib object into readable k source.",
     "",
-    `Usage: ${argv[1]} [ object-file [ k-file ] ]`,
+    `Usage: ${prog} [options] [ object-file [ k-file ] ]`,
     "",
     "Arguments:",
-    "  object-file  Input .ko or .klib path. Reads object data from stdin when omitted.",
-    "  k-file       Output .k path. Writes source to stdout when omitted.",
+    "  object-file        Input .ko or .klib path.",
+    "                     Reads object data from stdin when omitted.",
+    "  k-file             Output .k path (default: stdout).",
     "",
     "Options:",
-    "  -h, --help   Show this help.",
+    "  -o, --output path  Specify output file path explicitly.",
+    "  -h, --help         Show this help.",
     "",
-    "Example:",
-    `  ${argv[1]} program.ko program.decompiled.k`
+    "Examples:",
+    `  ${prog} program.ko -o program.decompiled.k`,
+    `  ${prog} program.ko program.decompiled.k`
   ].join("\n");
 }
 
@@ -35,13 +39,39 @@ async function readStdinBuffer() {
 }
 
 try {
-  const [, , objectPath, outputPath] = argv;
-  if (objectPath === "-h" || objectPath === "--help") {
+  const rawArgs = argv.slice(2);
+  if (rawArgs.includes("-h") || rawArgs.includes("--help")) {
     usage(console.log);
     exit(0);
   }
 
-  const objectBuffer = objectPath == null ? await readStdinBuffer() : fs.readFileSync(objectPath);
+  let explicitOutput = null;
+  const remainingArgs = [];
+  while (rawArgs.length > 0) {
+    const arg = rawArgs[0];
+    if (arg === "-o" || arg === "--output") {
+      rawArgs.shift();
+      explicitOutput = rawArgs.shift();
+      if (!explicitOutput) {
+        throw new Error("-o/--output requires a file argument");
+      }
+    } else if (arg.startsWith("-")) {
+      throw new Error(`Unknown option: ${arg}`);
+    } else {
+      remainingArgs.push(rawArgs.shift());
+    }
+  }
+
+  const objectPath = remainingArgs.shift() || null;
+  const positionalOutput = remainingArgs.shift() || null;
+  if (remainingArgs.length > 0) {
+    throw new Error(`Unexpected argument: ${remainingArgs[0]}`);
+  }
+  const outputPath = explicitOutput || positionalOutput || null;
+
+  const objectBuffer = objectPath == null
+    ? await readStdinBuffer()
+    : fs.readFileSync(objectPath);
   const source = decompileObjectBuffer(objectBuffer);
   if (outputPath == null) {
     stdout.write(source);
@@ -49,7 +79,7 @@ try {
     fs.writeFileSync(outputPath, source);
   }
 } catch (error) {
-  console.error(error);
+  console.error(error.message || String(error));
   usage();
   exit(1);
 }

package/objects/extract-aliases.mjs

@@ -5,24 +5,28 @@ import { argv, exit, stdin, stdout } from "node:process";
 import { extractAliasesFromObjectBuffer } from "../object.mjs";
 
 function helpText() {
+  const prog = argv[1] || "extract-aliases.mjs";
   return [
-    "Extract metadata aliases from a .ko or .klib as a valid k source snippet.",
+    "Extract metadata aliases from a .ko or .klib as valid k source.",
     "",
-    `Usage: ${argv[1]} [ object-file [ k-file ] ]`,
+    `Usage: ${prog} [options] [ object-file [ k-file ] ]`,
     "",
-    "Output is grouped by metadata type (code, then rel), then sorted by alias",
-    "name and compiledAt. Earlier definitions of the same alias are commented",
-    "out so only the latest one remains active.",
+    "Output is grouped by metadata type (code, then rel), then sorted",
+    "by alias name and compiledAt. Earlier definitions of the same alias",
+    "are commented out so only the latest one remains active.",
     "",
     "Arguments:",
-    "  object-file  Input .ko or .klib path. Reads object data from stdin when omitted.",
-    "  k-file       Output .k path. Writes source to stdout when omitted.",
+    "  object-file        Input .ko or .klib path.",
+    "                     Reads object data from stdin when omitted.",
+    "  k-file             Output .k path (default: stdout).",
     "",
     "Options:",
-    "  -h, --help   Show this help.",
+    "  -o, --output path  Specify output file path explicitly.",
+    "  -h, --help         Show this help.",
     "",
-    "Example:",
-    `  ${argv[1]} core.klib aliases.k`
+    "Examples:",
+    `  ${prog} core.klib -o aliases.k`,
+    `  ${prog} core.klib aliases.k`
   ].join("\n");
 }
 
@@ -39,13 +43,39 @@ async function readStdinBuffer() {
 }
 
 try {
-  const [, , objectPath, outputPath] = argv;
-  if (objectPath === "-h" || objectPath === "--help") {
+  const rawArgs = argv.slice(2);
+  if (rawArgs.includes("-h") || rawArgs.includes("--help")) {
     usage(console.log);
     exit(0);
   }
 
-  const objectBuffer = objectPath == null ? await readStdinBuffer() : fs.readFileSync(objectPath);
+  let explicitOutput = null;
+  const remainingArgs = [];
+  while (rawArgs.length > 0) {
+    const arg = rawArgs[0];
+    if (arg === "-o" || arg === "--output") {
+      rawArgs.shift();
+      explicitOutput = rawArgs.shift();
+      if (!explicitOutput) {
+        throw new Error("-o/--output requires a file argument");
+      }
+    } else if (arg.startsWith("-")) {
+      throw new Error(`Unknown option: ${arg}`);
+    } else {
+      remainingArgs.push(rawArgs.shift());
+    }
+  }
+
+  const objectPath = remainingArgs.shift() || null;
+  const positionalOutput = remainingArgs.shift() || null;
+  if (remainingArgs.length > 0) {
+    throw new Error(`Unexpected argument: ${remainingArgs[0]}`);
+  }
+  const outputPath = explicitOutput || positionalOutput || null;
+
+  const objectBuffer = objectPath == null
+    ? await readStdinBuffer()
+    : fs.readFileSync(objectPath);
   const source = extractAliasesFromObjectBuffer(objectBuffer);
   if (outputPath == null) {
     stdout.write(source);
@@ -53,7 +83,7 @@ try {
     fs.writeFileSync(outputPath, source);
   }
 } catch (error) {
-  console.error(error);
+  console.error(error.message || String(error));
   usage();
   exit(1);
 }