@fraczak/k 6.0.2 → 6.0.4

package/objects/README.md

@@ -8,6 +8,7 @@ CLI tools for compiling and inspecting k object files (`.ko`) and library files
 
 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.
 
 ```bash
 ./objects/compile.mjs [--lib lib-file]... [k-file [object-file]]
@@ -16,8 +17,12 @@ The output contains only the codes and relations reachable from `main`.
 ### compile-lib.mjs
 
 Compiles a `.k` source file into a library file (`.klib`).
-The output contains all codes and relations defined in the source (no main entry point).
+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
 ./objects/compile-lib.mjs [--lib lib-file]... [k-file [lib-file]]
@@ -31,6 +36,28 @@ Decompiles a `.ko` or `.klib` back into human-readable k source.
 ./objects/decompile.mjs [object-file [k-file]]
 ```
 
+### extract-aliases.mjs
+
+Extracts metadata aliases from a `.ko` or `.klib` as a valid k definition
+snippet. Output is grouped by metadata type (`code`, then `rel`), then sorted by
+alias name and `compiledAt`.
+
+```bash
+./objects/extract-aliases.mjs [object-file [k-file]]
+```
+
+## Current Format Notes
+
+- `.klib` files are plain UTF-8 JSON, not binary containers.
+- `.ko` files use the `KOBJ\n` binary header followed by a JSON payload.
+- There is no object payload version field in either format.
+- `typeDerivation` belongs only to relations and currently stores only
+  `status`.
+- Source `start` / `end` ranges live on `meta[hash].origins[]` entries.
+- Origin entries do not have `kind`; the metadata entry has `type: "code"` or
+  `type: "rel"`.
+- Stored relation bodies do not include generated input/output boundary filters.
+
 ## Further reading
 
 - [DOCS/OBJECT_FILE_AND_PATTERN.md](../DOCS/OBJECT_FILE_AND_PATTERN.md) — object file format and pattern encoding

package/objects/compile-lib.mjs

@@ -4,8 +4,28 @@ import fs from "node:fs";
 import { argv, exit, stdin, stdout } from "node:process";
 import { compileLibraryBuffer, decodeObject, loadLibrary } from "../object.mjs";
 
-function usage() {
-  console.error(`Usage: ${argv[1]} [ --lib lib-file ]... [ k-file [ lib-file ] ]`);
+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() {
@@ -18,6 +38,11 @@ async function readStdinText() {
 
 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();

package/objects/compile.mjs

@@ -4,8 +4,28 @@ import fs from "node:fs";
 import { argv, exit, stdin, stdout } from "node:process";
 import { compileObjectBuffer, decodeObject, loadLibrary } from "../object.mjs";
 
-function usage() {
-  console.error(`Usage: ${argv[1]} [ --lib lib-file ]... [ k-file [ object-file ] ]`);
+function helpText() {
+  return [
+    "Compile a k source file into an executable .ko object.",
+    "The object records type-derivation convergence for each stored relation.",
+    "",
+    `Usage: ${argv[1]} [ --lib lib-file ]... [ k-file [ object-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.",
+    "",
+    "Options:",
+    "  --lib file   Load a .klib dependency before compiling. May be repeated.",
+    "  -h, --help   Show this help.",
+    "",
+    "Example:",
+    `  ${argv[1]} --lib core.klib program.k program.ko`
+  ].join("\n");
+}
+
+function usage(stream = console.error) {
+  stream(helpText());
 }
 
 async function readStdinText() {
@@ -18,6 +38,11 @@ async function readStdinText() {
 
 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();

package/objects/decompile.mjs

@@ -4,8 +4,26 @@ import fs from "node:fs";
 import { argv, exit, stdin, stdout } from "node:process";
 import { decompileObjectBuffer } from "../object.mjs";
 
-function usage() {
-  console.error(`Usage: ${argv[1]} [ object-file [ k-file ] ]`);
+function helpText() {
+  return [
+    "Decompile a .ko or .klib object into readable k source.",
+    "",
+    `Usage: ${argv[1]} [ 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.",
+    "",
+    "Options:",
+    "  -h, --help   Show this help.",
+    "",
+    "Example:",
+    `  ${argv[1]} program.ko program.decompiled.k`
+  ].join("\n");
+}
+
+function usage(stream = console.error) {
+  stream(helpText());
 }
 
 async function readStdinBuffer() {
@@ -18,6 +36,11 @@ async function readStdinBuffer() {
 
 try {
   const [, , objectPath, outputPath] = argv;
+  if (objectPath === "-h" || objectPath === "--help") {
+    usage(console.log);
+    exit(0);
+  }
+
   const objectBuffer = objectPath == null ? await readStdinBuffer() : fs.readFileSync(objectPath);
   const source = decompileObjectBuffer(objectBuffer);
   if (outputPath == null) {

package/objects/extract-aliases.mjs

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import { argv, exit, stdin, stdout } from "node:process";
+import { extractAliasesFromObjectBuffer } from "../object.mjs";
+
+function helpText() {
+  return [
+    "Extract metadata aliases from a .ko or .klib as a valid k source snippet.",
+    "",
+    `Usage: ${argv[1]} [ 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.",
+    "",
+    "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.",
+    "",
+    "Options:",
+    "  -h, --help   Show this help.",
+    "",
+    "Example:",
+    `  ${argv[1]} core.klib aliases.k`
+  ].join("\n");
+}
+
+function usage(stream = console.error) {
+  stream(helpText());
+}
+
+async function readStdinBuffer() {
+  const chunks = [];
+  for await (const chunk of stdin) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  }
+  return Buffer.concat(chunks);
+}
+
+try {
+  const [, , objectPath, outputPath] = argv;
+  if (objectPath === "-h" || objectPath === "--help") {
+    usage(console.log);
+    exit(0);
+  }
+
+  const objectBuffer = objectPath == null ? await readStdinBuffer() : fs.readFileSync(objectPath);
+  const source = extractAliasesFromObjectBuffer(objectBuffer);
+  if (outputPath == null) {
+    stdout.write(source);
+  } else {
+    fs.writeFileSync(outputPath, source);
+  }
+} catch (error) {
+  console.error(error);
+  usage();
+  exit(1);
+}