@fraczak/k 6.0.4 → 6.1.1

package/codecs/ieee.mjs

@@ -6,6 +6,13 @@ import { decodeWire, encodeToWire } from "./runtime/prefix-codec.mjs";
 import { FLOAT64_PATTERN } from "./runtime/ieee-pattern.mjs";
 const UNIT = new Product({});
 
+function usage(stream = console.error) {
+  stream(`Usage: ${argv[1]} --parse | --print`);
+  stream("  --parse      Read a float literal from stdin, write binary pattern+value stream.");
+  stream("  --print      Read binary pattern+value stream from stdin, write a float literal.");
+  stream("  -h, --help   Show this help.");
+}
+
 function bitValue(bit) {
   return new Variant(bit === 0 ? "0" : "1", UNIT);
 }
@@ -116,10 +123,13 @@ function readAll(stream) {
 
 async function main() {
   const args = argv.slice(2);
+  if (args.includes("-h") || args.includes("--help")) {
+    usage(console.log);
+    exit(0);
+  }
+
   if (args.length !== 1 || (args[0] !== "--parse" && args[0] !== "--print")) {
-    console.error("Usage: ieee.mjs --parse | --print");
-    console.error("  --parse  read a float literal from stdin, write binary pattern+value stream");
-    console.error("  --print  read binary pattern+value stream from stdin, write a float literal");
+    usage();
     exit(1);
   }
 

package/codecs/int.mjs

@@ -17,6 +17,13 @@ import { stdin, stdout, argv, exit } from "node:process";
 import { Product, Variant } from "../Value.mjs";
 import { decodeWire, encodeToWire } from "./runtime/prefix-codec.mjs";
 
+function usage(stream = console.error) {
+  stream(`Usage: ${argv[1]} --parse | --print`);
+  stream("  --parse      Read a decimal integer from stdin, write binary pattern+value stream.");
+  stream("  --print      Read binary pattern+value stream from stdin, write decimal integer.");
+  stream("  -h, --help   Show this help.");
+}
+
 // Closed pattern for $ int = < bits '+', bits '-' >
 // with $ bits = < {} _, bits 0, bits 1 >
 const INT_PATTERN = [
@@ -79,10 +86,13 @@ function printIntValue(value) {
 
 async function main() {
   const args = argv.slice(2);
+  if (args.includes("-h") || args.includes("--help")) {
+    usage(console.log);
+    exit(0);
+  }
+
   if (args.length !== 1 || (args[0] !== "--parse" && args[0] !== "--print")) {
-    console.error("Usage: int.mjs --parse | --print");
-    console.error("  --parse  read a decimal integer from stdin, write binary pattern+value stream");
-    console.error("  --print  read binary pattern+value stream from stdin, write decimal integer");
+    usage();
     exit(1);
   }
 

package/codecs/json.mjs

@@ -4,6 +4,13 @@ import { stdin, stdout, argv, exit } from "node:process";
 import { decodeWire, encodeToWire } from "./runtime/prefix-codec.mjs";
 import { fromJsonValue, toJsonValue, patternFromJsonValue } from "./json-codec.mjs";
 
+function usage(stream = console.error) {
+  stream(`Usage: ${argv[1]} --parse | --print`);
+  stream("  --parse      Read JSON from stdin, write binary pattern+value stream.");
+  stream("  --print      Read binary pattern+value stream from stdin, write JSON.");
+  stream("  -h, --help   Show this help.");
+}
+
 function readAll(stream) {
   return new Promise((resolve, reject) => {
     const chunks = [];
@@ -15,10 +22,13 @@ function readAll(stream) {
 
 async function main() {
   const args = argv.slice(2);
+  if (args.includes("-h") || args.includes("--help")) {
+    usage(console.log);
+    exit(0);
+  }
+
   if (args.length !== 1 || (args[0] !== "--parse" && args[0] !== "--print")) {
-    console.error("Usage: json.mjs --parse | --print");
-    console.error("  --parse  read JSON from stdin, write binary pattern+value stream");
-    console.error("  --print  read binary pattern+value stream from stdin, write JSON");
+    usage();
     exit(1);
   }
 

package/codecs/k-parse.mjs

@@ -49,6 +49,11 @@ async function main() {
   const prog = argv[1];
   const args = argv.slice(2);
 
+  if (args.includes("-h") || args.includes("--help")) {
+    usage(prog);
+    return exit(0);
+  }
+
   let inputTypeArg = null;
   let inputPatternArg = null;
   let valueFile = null;

package/codecs/k-print.mjs

@@ -4,6 +4,15 @@ import fs from "node:fs";
 import { argv, stdin, stdout } from "node:process";
 import { decodeWire } from "./runtime/prefix-codec.mjs";
 
+function usage(stream = console.error) {
+  stream(`Usage: ${argv[1]} [--debug] [file]`);
+  stream("  Read a binary pattern+value stream and print the decoded textual value.");
+  stream("");
+  stream("Options:");
+  stream("  --debug      Print decoded pattern and value as JSON.");
+  stream("  -h, --help   Show this help.");
+}
+
 function readAll(stream) {
   return new Promise((resolve, reject) => {
     const chunks = [];
@@ -15,6 +24,11 @@ function readAll(stream) {
 
 async function main() {
   const args = argv.slice(2);
+  if (args.includes("-h") || args.includes("--help")) {
+    usage(console.log);
+    return;
+  }
+
   let debug = false;
   let fileArg = null;
 
@@ -24,7 +38,8 @@ async function main() {
     } else if (fileArg == null) {
       fileArg = arg;
     } else {
-      throw new Error("Usage: k-print [--debug] [file]");
+      usage();
+      process.exit(1);
     }
   }
 

package/codecs/show.mjs

@@ -5,6 +5,15 @@ import { argv, stdin, stdout, stderr } from "node:process";
 import { decodeWire } from "./runtime/prefix-codec.mjs";
 import { propertyListToFilter, valueToK } from "./runtime/show-value.mjs";
 
+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.");
+}
+
 function readAll(stream) {
   return new Promise((resolve, reject) => {
     const chunks = [];
@@ -16,10 +25,15 @@ function readAll(stream) {
 
 async function main() {
   const args = argv.slice(2);
+  if (args.includes("-h") || args.includes("--help")) {
+    usage(console.log);
+    return;
+  }
+
   let fileArg = null;
   for (const arg of args) {
     if (fileArg == null) fileArg = arg;
-    else { console.error("Usage: show.mjs [wire-file]"); process.exit(1); }
+    else { usage(); process.exit(1); }
   }
 
   const buffer = fileArg ? fs.readFileSync(fileArg) : await readAll(stdin);

package/codecs/unit.mjs

@@ -4,6 +4,13 @@ import { stdin, stdout, argv, exit } from "node:process";
 import { Product } from "../Value.mjs";
 import { decodeWire, encodeToWire } from "./runtime/prefix-codec.mjs";
 
+function usage(stream = console.error) {
+  stream(`Usage: ${argv[1]} --parse | --print`);
+  stream("  --parse      Ignore stdin and write the unit binary pattern+value stream.");
+  stream("  --print      Validate the unit binary pattern+value stream and write {}.");
+  stream("  -h, --help   Show this help.");
+}
+
 const UNIT_PATTERN = [
   ["closed-product", []]
 ];
@@ -23,10 +30,13 @@ function unitEncoding() {
 
 async function main() {
   const args = argv.slice(2);
+  if (args.includes("-h") || args.includes("--help")) {
+    usage(console.log);
+    exit(0);
+  }
+
   if (args.length !== 1 || (args[0] !== "--parse" && args[0] !== "--print")) {
-    console.error("Usage: unit.mjs --parse | --print");
-    console.error("  --parse  ignore stdin and write the unit binary pattern+value stream");
-    console.error("  --print  validate the unit binary pattern+value stream and write {}");
+    usage();
     exit(1);
   }
 

package/codecs/utf16.mjs

@@ -3,6 +3,13 @@
 import { stdin, stdout, argv, exit } from "node:process";
 import { encodeText, decodeText } from "./string-codec.mjs";
 
+function usage(stream = console.error) {
+  stream(`Usage: ${argv[1]} --parse | --print`);
+  stream("  --parse      Read UTF-16 text from stdin (BOM-aware), write binary pattern+value stream of k string.");
+  stream("  --print      Read binary pattern+value stream of k string, write UTF-16LE text with BOM.");
+  stream("  -h, --help   Show this help.");
+}
+
 function readAll(stream) {
   return new Promise((resolve, reject) => {
     const chunks = [];
@@ -43,10 +50,13 @@ function encodeUtf16Output(text) {
 
 async function main() {
   const args = argv.slice(2);
+  if (args.includes("-h") || args.includes("--help")) {
+    usage(console.log);
+    exit(0);
+  }
+
   if (args.length !== 1 || (args[0] !== "--parse" && args[0] !== "--print")) {
-    console.error("Usage: utf16.mjs --parse | --print");
-    console.error("  --parse  read UTF-16 text from stdin (BOM-aware), write binary pattern+value stream of k string");
-    console.error("  --print  read binary pattern+value stream of k string, write UTF-16LE text with BOM");
+    usage();
     exit(1);
   }
 

package/codecs/utf8.mjs

@@ -3,6 +3,13 @@
 import { stdin, stdout, argv, exit } from "node:process";
 import { encodeText, decodeText } from "./string-codec.mjs";
 
+function usage(stream = console.error) {
+  stream(`Usage: ${argv[1]} --parse | --print`);
+  stream("  --parse      Read UTF-8 text from stdin, write binary pattern+value stream of k string.");
+  stream("  --print      Read binary pattern+value stream of k string, write UTF-8 text.");
+  stream("  -h, --help   Show this help.");
+}
+
 function readAll(stream) {
   return new Promise((resolve, reject) => {
     const chunks = [];
@@ -14,10 +21,13 @@ function readAll(stream) {
 
 async function main() {
   const args = argv.slice(2);
+  if (args.includes("-h") || args.includes("--help")) {
+    usage(console.log);
+    exit(0);
+  }
+
   if (args.length !== 1 || (args[0] !== "--parse" && args[0] !== "--print")) {
-    console.error("Usage: utf8.mjs --parse | --print");
-    console.error("  --parse  read UTF-8 text from stdin, write binary pattern+value stream of k string");
-    console.error("  --print  read binary pattern+value stream of k string, write UTF-8 text");
+    usage();
     exit(1);
   }
 

package/k-vscode/README.md

@@ -1,7 +1,8 @@
 # k language — VS Code extension
 
-Syntax highlighting and snippets for the **k language**: a language for composing
-first-order partial functions over algebraic data types (products and tagged unions).
+Syntax highlighting and snippets for the **k language**: a small language for
+typed data transformations over algebraic data types (products and tagged
+unions).
 
 ## Features
 

package/k.mjs

@@ -13,7 +13,10 @@ let kScript, inputStream;
 
 function usage() {
   console.error(`Usage: ${prog} [ --lib lib-file ]... ( k-expr | -k file ) [ input-file ]`);
-  console.error(`       E.g.,  echo '["zebara","ela"]' | ./codecs/k-parse.mjs --input-type '$x=<{} zebara, {} ela>; $v={x 0, x 1}; $v' | ${prog} '{.1 0}'`);
+  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.");
 }
 
 function compileFile(path, libraries) {
@@ -27,6 +30,11 @@ function compileFile(path, libraries) {
 
 ({ kScript, inputStream } = ((args) => {
   try {
+    if (args.includes("-h") || args.includes("--help")) {
+      usage();
+      return exit(0);
+    }
+
     const libraries = [];
     // Parse --lib flags
     while (args.length > 0 && args[0] === "--lib") {

package/k_compiler/runtime.c

@@ -0,0 +1,205 @@
+#include "runtime.h"
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+typedef enum {
+  K_NODE_PRODUCT = 1,
+  K_NODE_VARIANT = 2
+} KNodeKind;
+
+typedef struct {
+  const char *label;
+  KValue value;
+} KField;
+
+struct KNode {
+  KNodeKind kind;
+  const char *type_id;
+  union {
+    struct {
+      int field_count;
+      KField *fields;
+    } product;
+    struct {
+      const char *tag;
+      KValue child;
+    } variant;
+  } as;
+};
+
+static char *krt_strdup(const char *value) {
+  size_t len = strlen(value);
+  char *result = (char *)malloc(len + 1);
+  memcpy(result, value, len + 1);
+  return result;
+}
+
+static const char *krt_infer_variant_type(const char *label, KValue child) {
+  if (child == NULL) return "";
+  if (child->type_id != NULL && child->type_id[0] != '\0') {
+    return child->type_id;
+  }
+  if (strcmp(label, "zero") == 0 || strcmp(label, "succ") == 0) {
+    return "@w8iSHeQQE738vEmWNGja3FQWk3XuExQKZ2pbm8ApEdkF";
+  }
+  return "";
+}
+
+static KOpt krt_ok(KValue value) {
+  KOpt result;
+  result.ok = 1;
+  result.value = value;
+  return result;
+}
+
+static const char *json_extract_string(const char *json, const char *key) {
+  static char buffer[256];
+  char pattern[64];
+  const char *cursor;
+  const char *start;
+  size_t length = 0;
+
+  snprintf(pattern, sizeof(pattern), "\"%s\":\"", key);
+  cursor = strstr(json, pattern);
+  if (cursor == NULL) return NULL;
+  start = cursor + strlen(pattern);
+
+  while (start[length] != '\0' && start[length] != '"') {
+    if (start[length] == '\\' && start[length + 1] != '\0') {
+      length += 2;
+      continue;
+    }
+    length += 1;
+  }
+
+  if (length >= sizeof(buffer)) {
+    length = sizeof(buffer) - 1;
+  }
+  memcpy(buffer, start, length);
+  buffer[length] = '\0';
+  return buffer;
+}
+
+static KValue product_field(KValue input, const char *label) {
+  int index;
+  if (input == NULL || input->kind != K_NODE_PRODUCT) return NULL;
+  for (index = 0; index < input->as.product.field_count; index += 1) {
+    if (strcmp(input->as.product.fields[index].label, label) == 0) {
+      return input->as.product.fields[index].value;
+    }
+  }
+  return NULL;
+}
+
+KOpt krt_fail(void) {
+  KOpt result;
+  result.ok = 0;
+  result.value = NULL;
+  return result;
+}
+
+KOpt krt_return_input(KValue input) {
+  return krt_ok(input);
+}
+
+KValue krt_new_product(const char *type_id, int field_count, const char *const *labels, KValue const *values) {
+  int index;
+  KNode *node = (KNode *)calloc(1, sizeof(KNode));
+  node->kind = K_NODE_PRODUCT;
+  node->type_id = krt_strdup(type_id == NULL ? "" : type_id);
+  node->as.product.field_count = field_count;
+  node->as.product.fields = field_count > 0 ? (KField *)calloc((size_t)field_count, sizeof(KField)) : NULL;
+
+  for (index = 0; index < field_count; index += 1) {
+    node->as.product.fields[index].label = krt_strdup(labels[index]);
+    node->as.product.fields[index].value = values[index];
+  }
+  return node;
+}
+
+KValue krt_new_variant(const char *type_id, const char *label, KValue child) {
+  KNode *node = (KNode *)calloc(1, sizeof(KNode));
+  node->kind = K_NODE_VARIANT;
+  node->type_id = krt_strdup(type_id == NULL ? "" : type_id);
+  node->as.variant.tag = krt_strdup(label);
+  node->as.variant.child = child;
+  return node;
+}
+
+KOpt krt_guard_code(KValue input, const char *type_id) {
+  if (input == NULL) return krt_fail();
+  if (type_id == NULL || type_id[0] == '\0') return krt_ok(input);
+  if (strcmp(input->type_id, type_id) == 0) return krt_ok(input);
+  return krt_fail();
+}
+
+KOpt krt_guard_type_var(KValue input, const char *var_name) {
+  (void)var_name;
+  if (input == NULL) return krt_fail();
+  return krt_ok(input);
+}
+
+KOpt krt_guard_shape(KValue input, const char *shape_descriptor_json) {
+  const char *shape;
+  if (input == NULL) return krt_fail();
+  shape = json_extract_string(shape_descriptor_json, "shape");
+  if (shape == NULL || strcmp(shape, "any") == 0) return krt_ok(input);
+  if (strcmp(shape, "product") == 0 && input->kind == K_NODE_PRODUCT) return krt_ok(input);
+  if (strcmp(shape, "union") == 0 && input->kind == K_NODE_VARIANT) return krt_ok(input);
+  return krt_fail();
+}
+
+KOpt krt_project_field(KValue input, const char *projection_descriptor_json) {
+  const char *label = json_extract_string(projection_descriptor_json, "label");
+  KValue child = product_field(input, label);
+  if (label == NULL || child == NULL) return krt_fail();
+  return krt_ok(child);
+}
+
+KOpt krt_project_variant(KValue input, const char *projection_descriptor_json) {
+  const char *label = json_extract_string(projection_descriptor_json, "label");
+  if (label == NULL || input == NULL || input->kind != K_NODE_VARIANT) return krt_fail();
+  if (strcmp(input->as.variant.tag, label) != 0) return krt_fail();
+  return krt_ok(input->as.variant.child);
+}
+
+KOpt krt_make_product(const char *type_id, int field_count, const char *const *labels, KValue const *values) {
+  return krt_ok(krt_new_product(type_id, field_count, labels, values));
+}
+
+KOpt krt_make_variant(KValue child, const char *label, const char *type_id) {
+  const char *resolved_type = type_id;
+  if (resolved_type == NULL || resolved_type[0] == '\0') {
+    resolved_type = krt_infer_variant_type(label, child);
+  }
+  return krt_ok(krt_new_variant(resolved_type, label, child));
+}
+
+void krt_print_value(KValue value) {
+  int index;
+  if (value == NULL) {
+    printf("<null>");
+    return;
+  }
+
+  if (value->kind == K_NODE_PRODUCT) {
+    if (value->as.product.field_count == 0) {
+      printf("{}");
+      return;
+    }
+    printf("{");
+    for (index = 0; index < value->as.product.field_count; index += 1) {
+      if (index > 0) printf(", ");
+      printf("%s:", value->as.product.fields[index].label);
+      krt_print_value(value->as.product.fields[index].value);
+    }
+    printf("}");
+    return;
+  }
+
+  printf("%s(", value->as.variant.tag);
+  krt_print_value(value->as.variant.child);
+  printf(")");
+}

package/k_compiler/runtime.h

@@ -0,0 +1,34 @@
+#ifndef K_COMPILER_RUNTIME_H
+#define K_COMPILER_RUNTIME_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef struct KNode KNode;
+typedef KNode *KValue;
+
+typedef struct {
+  int ok;
+  KValue value;
+} KOpt;
+
+KOpt krt_fail(void);
+KOpt krt_return_input(KValue input);
+KOpt krt_guard_code(KValue input, const char *type_id);
+KOpt krt_guard_type_var(KValue input, const char *var_name);
+KOpt krt_guard_shape(KValue input, const char *shape_descriptor_json);
+KOpt krt_project_field(KValue input, const char *projection_descriptor_json);
+KOpt krt_project_variant(KValue input, const char *projection_descriptor_json);
+KOpt krt_make_product(const char *type_id, int field_count, const char *const *labels, KValue const *values);
+KOpt krt_make_variant(KValue child, const char *label, const char *type_id);
+
+KValue krt_new_product(const char *type_id, int field_count, const char *const *labels, KValue const *values);
+KValue krt_new_variant(const char *type_id, const char *label, KValue child);
+void krt_print_value(KValue value);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif

package/objects/README.md

@@ -4,17 +4,17 @@ CLI tools for compiling and inspecting k object files (`.ko`) and library files
 
 ## Tools
 
-### compile.mjs
+### `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.
 
 ```bash
-./objects/compile.mjs [--lib lib-file]... [k-file [object-file]]
+k-compile [--lib lib-file]... [k-file [object-file]]
 ```
 
-### compile-lib.mjs
+### `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
@@ -25,27 +25,30 @@ 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]]
+k-compile-lib [--lib lib-file]... [k-file [lib-file]]
 ```
 
-### decompile.mjs
+### `k-decompile`
 
 Decompiles a `.ko` or `.klib` back into human-readable k source.
 
 ```bash
-./objects/decompile.mjs [object-file [k-file]]
+k-decompile [object-file [k-file]]
 ```
 
-### extract-aliases.mjs
+### `k-extract-aliases`
 
 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]]
+k-extract-aliases [object-file [k-file]]
 ```
 
+The installed names are `k-` plus the source basename without `.mjs`. Every
+installed object binary supports `-h` and `--help`.
+
 ## Current Format Notes
 
 - `.klib` files are plain UTF-8 JSON, not binary containers.

package/package.json

@@ -1,11 +1,11 @@
 {
     "name": "@fraczak/k",
-    "version": "6.0.4",
+    "version": "6.1.1",
     "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": {
         "prepare": "jiwson -m es6 parser.jison -o parser.mjs; jiwson -m es6 valueParser.jison -o valueParser.mjs; ",
-        "test": "node test.mjs; for f in Code-derivation-tests/*.mjs; do echo $f; node $f; done; node test-fingerprint.mjs; node test-hash-fuzz.mjs; node test-hash-normalization.mjs; node test-k-object.mjs; node test-repl2.mjs; ./tests.sh",
+        "test": "node test.mjs; for f in Code-derivation-tests/*.mjs; do echo $f; node $f; done; node test-fingerprint.mjs; node test-hash-fuzz.mjs; node test-hash-normalization.mjs; node test-k-object.mjs; node test-repl.mjs; ./tests.sh",
         "deps:graph": "node scripts/generate-dependency-graph.mjs"
     },
     "repository": {
@@ -16,14 +16,20 @@
     "license": "ISC",
     "bin": {
         "k": "./k.mjs",
-        "k-compile-object": "./objects/compile.mjs",
-        "k-decompile-object": "./objects/decompile.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",
+        "k-int": "./codecs/int.mjs",
+        "k-json": "./codecs/json.mjs",
         "k-parse": "./codecs/k-parse.mjs",
-        "k-pattern": "./patterns/from-k.mjs",
         "k-print": "./codecs/k-print.mjs",
-        "k-repl": "./repl2.mjs",
-        "k-repl2": "./repl2.mjs"
+        "k-repl": "./repl.mjs",
+        "k-show": "./codecs/show.mjs",
+        "k-unit": "./codecs/unit.mjs",
+        "k-utf16": "./codecs/utf16.mjs",
+        "k-utf8": "./codecs/utf8.mjs"
     },
     "devDependencies": {
         "jiwson": "^0.1.2"