@fraczak/k 6.0.4 → 6.1.0

package/AGENTS.md

@@ -11,8 +11,8 @@
 - `npm install` installs dev dependencies and runs `prepare` to generate parsers.
 - `npm run prepare` regenerates `parser.mjs` and `valueParser.mjs` from `.jison` grammars.
 - `npm test` runs the full suite (`test.mjs`, `Code-derivation-tests/*.mjs`, `test-fingerprint.mjs`, `tests.sh`).
-- `node repl2.mjs` (or `k-repl`) starts the interactive REPL.
-- `./k.mjs <file.k>` executes a k script on binary pattern+value stream input from stdin or a file; use `k-parse` and `k-print` at the boundaries.
+- `node repl.mjs` (or `k-repl`) starts the interactive REPL.
+- `./k.mjs -k <file.k>` executes a k script on binary pattern+value stream input from stdin or a file; use `k-parse` and `k-print` at the boundaries.
 
 ## Coding Style & Naming Conventions
 - JavaScript uses ES modules (`.mjs`) with 2-space indentation and semicolons.

package/CHANGELOG.md

@@ -7,6 +7,22 @@ This project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [6.1.0] — 2026-05-20 — CLI aliases and help
+
+### Toolchain
+
+- Renamed the REPL entry point to `repl.mjs` and the installed binary to `k-repl`.
+- Unified installed command names around the `k-` prefix and source basenames.
+- Added `-h` / `--help` support across executable CLI scripts.
+- Added public aliases in `Examples/ieee.k` for `add`, `sub`, `mul`, `div`, comparisons, and `neg`.
+
+### Documentation
+
+- Reworked the README around typed data transformations, contributor entry points, and the IEEE example.
+- Updated CLI references across documentation to the current installed command names.
+
+---
+
 ## [6.0.0] — 2026-05-12 — First public release
 
 ### Language & Runtime
@@ -22,18 +38,18 @@ This project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 - Finite tree automaton type representation (`codes.mjs`).
 - Graph-based constraint propagation via `TypePatternGraph`.
 - SCC-aware convergence with configurable strategy (`auto` / `single_pass` / `fixed_point`).
-- `compileStats` API for inspecting convergence behaviour per SCC.
+- `compileStats` API for inspecting convergence behavior per SCC.
 
 ### Toolchain
 
 - `k` — CLI executor: reads binary pattern+value stream, applies a k script, writes result.
-- `k-repl` / `k-repl2` — interactive interpreter with tab-completion.
-- `k-pattern` — extract the canonical root pattern from a k script.
-- `k-compile-object` / `k-decompile-object` — object file compilation and decompilation.
+- `k-repl` — interactive interpreter with tab-completion.
+- `k-compile` / `k-decompile` — object file compilation and decompilation.
+- `k-compile-lib` / `k-extract-aliases` — library compilation and alias extraction.
 
 ### Codec Pipeline
 
-- Binary format: serialised pattern graph followed by value encoded under that pattern.
+- Binary format: serialized pattern graph followed by value encoded under that pattern.
 - JSON codec, UTF-8/UTF-16 string codec, IEEE 754 codec.
 - Polymorphic codec streams: pattern carried in-memory through projections and constructors.
 
@@ -45,4 +61,5 @@ This project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+[6.1.0]: https://github.com/fraczak/k/releases/tag/v6.1.0
 [6.0.0]: https://github.com/fraczak/k/releases/tag/v6.0.0

package/CLAUDE.md

@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Overview
 
-k-language is an experimental programming language for building and manipulating algebraic data types ("codes")—tree-shaped values built from product and tagged union. The native k-like notation is canonical; a JSON-like notation is available as a convenience for newcomers.
+k is an experimental language for describing algebraic data shapes and composing typed transformations over them. Data descriptions and transformations share one syntax; the native k-like notation is canonical, and a JSON-like notation is available as a convenience for textual values.
 
 ## Essential Commands
 
@@ -20,8 +20,8 @@ npm test  # Run comprehensive test suite (unit tests, derivation tests, shell te
 
 **Running k programs:**
 ```bash
-./k.mjs <file.k>      # Execute k script
-./repl2.mjs           # Start interactive REPL (or: k-repl)
+./k.mjs -k <file.k>   # Execute k script
+./repl.mjs            # Start interactive REPL (or: k-repl)
 ```
 
 ## Architecture
@@ -61,4 +61,4 @@ npm test  # Run comprehensive test suite (unit tests, derivation tests, shell te
 - No external runtime dependencies (only jiwson for parser generation)
 - Uses ES6 modules (.mjs files) throughout
 - Extensive test suite in `Code-derivation-tests/` for type system validation
-- REPL supports commands like `--C name` (show canonical type) and `--R name` (show type derivation)
+- REPL supports commands like `:C name` (show canonical type), `:t name` (show relation type), and `:d name` (show relation definition)

package/DOCS/BIG_PICTURE.md

@@ -82,7 +82,7 @@ filter_label_list ::= /* empty */ | '...'
 
 Examples:
 
-```k-repl
+```text
   X                 -- any type
   ( ... )           -- any type
   { ... }           -- any product type
@@ -178,7 +178,7 @@ The normalization steps are:
 
 #### Example 1
 
-```k-repl
+```text
 $ bit = < {} o, {} i >;
 bit0 = | o $bit;
 bit1 = | i $bit;
@@ -242,7 +242,7 @@ Such a pattern is called _singleton pattern_, as only one type fits the pattern.
 
 Polymorphic list functions:
 
-```k-repl
+```text
 list? = ?< {} nil, {X car, Y cdr} cons > = Y;
 nil = {} |nil list?;
 singleton = {() car, nil cdr} |cons list?;
@@ -254,7 +254,7 @@ cdr = list? /cons .cdr;
 
 For example, the filter annotation for `car` is:
 
-```k-repl
+```text
 > :t car
 car : ?<{X1 car, X0 cdr} cons, $KL nil>=X0  -->  ?X1  (@...)
 > :C KL
@@ -301,7 +301,7 @@ A type can be translated into a Rust data structure, and a function can be trans
 
 Extending `@string` into `@bits`. 
 
-```k-repl
+```text
 $ bits = < {} _, bits 0, bits 1 >;
 ```
 

package/DOCS/BINARY_CODEC_STATUS_AND_TODO.md

@@ -51,9 +51,9 @@ value-payload DAG compression.
 
 ```bash
 echo '["zebara", "ela", "kupa", ala, owca]' | \
-  ./codecs/k-parse.mjs | \
-  ./k.mjs '{.1 0,.3 1}' | \
-  ./codecs/k-print.mjs
+  k-parse | \
+  k '{.1 0,.3 1}' | \
+  k-print
 ```
 
 Expected output:

package/DOCS/OBJECT_FILE_AND_PATTERN.md

@@ -133,7 +133,7 @@ Loading an object hydrates the type-pattern graphs back into runtime
 Object execution through `k.mjs`:
 
 ```sh
-echo "..." | ./some-codec --parse | ./k.mjs -k path/to/program.ko | ./some-codec --print
+echo "..." | some-codec --parse | k -k path/to/program.ko | some-codec --print
 ```
 
 The `-k` option accepts either an object file or a source `.k` file. `k.mjs`
@@ -143,17 +143,17 @@ compilation.
 Standalone helpers live in `objects/`:
 
 ```sh
-./objects/compile.mjs path/to/program.k path/to/program.ko
-./objects/compile-lib.mjs path/to/library.k path/to/library.klib
-./objects/decompile.mjs path/to/program.ko path/to/program.decompiled.k
-./objects/extract-aliases.mjs path/to/library.klib path/to/aliases.k
+k-compile path/to/program.k path/to/program.ko
+k-compile-lib path/to/library.k path/to/library.klib
+k-decompile path/to/program.ko path/to/program.decompiled.k
+k-extract-aliases path/to/library.klib path/to/aliases.k
 ```
 
 With no arguments, the helpers read from stdin and write to stdout:
 
 ```sh
-cat path/to/program.k | ./objects/compile.mjs > path/to/program.ko
-cat path/to/program.ko | ./objects/decompile.mjs > path/to/program.decompiled.k
+cat path/to/program.k | k-compile > path/to/program.ko
+cat path/to/program.ko | k-decompile > path/to/program.decompiled.k
 ```
 
 The decompiled source is canonical source regenerated from object IR. It uses
@@ -173,7 +173,7 @@ For a tiny source file:
 compile it with:
 
 ```sh
-./objects/compile.mjs id.k id.ko
+k-compile id.k id.ko
 ```
 
 The first bytes of `id.ko` are the binary container header:
@@ -259,7 +259,7 @@ succ = |succ;
 compile it with:
 
 ```sh
-./objects/compile-lib.mjs defs.k defs.klib
+k-compile-lib defs.k defs.klib
 ```
 
 The output file is plain JSON and starts with `{`, not a binary prefix. Its

package/DOCS/PATTERNS.md

@@ -66,9 +66,10 @@ list
 
 In both cases, the compiler derives a root pattern from `__main__`.
 
-## `k-pattern`
+## Pattern Export Helper
 
-`k-pattern` extracts that root pattern from a k script.
+`patterns/from-k.mjs` extracts that root pattern from a k script. It is a
+repository helper, not an installed `package.json` binary.
 
 It:
 
@@ -84,7 +85,7 @@ It:
 Example:
 
 ```bash
-echo '?< {} nil, { $bits car, X cdr } cons > = X' | k-pattern
+echo '?< {} nil, { $bits car, X cdr } cons > = X' | node ./patterns/from-k.mjs
 ```
 
 Typical output:
@@ -101,8 +102,8 @@ The active wire format is:
 encode($pattern_value : $pattern) encode(value : decoded_pattern)
 ```
 
-So the property-list array printed by `k-pattern` is a readable externalization
-of the same pattern information carried in the wire stream.
+So the property-list array printed by `patterns/from-k.mjs` is a readable
+externalization of the same pattern information carried in the wire stream.
 
 `k-parse --input-pattern ...` and `k-parse --input-type ...` both ultimately
 produce the same kind of root pattern used to interpret textual values.

package/DOCS/REPL.md

@@ -1,7 +1,7 @@
 # k Interpreter
 
-`repl2.mjs` is the interactive k interpreter. `k-repl` and `k-repl2` both
-start it.
+`repl.mjs` is the interactive k interpreter. After linking or installing the
+package, start it with `k-repl`.
 
 The interpreter keeps a live `.klib`-style state in memory:
 

package/DOCS/book/06-values-in-memory.md

@@ -113,7 +113,7 @@ Each node in the value tree is encoded based on its automaton state:
 
 For type `bnat`, intuitively binary natural numbers defined by `$bnat = < bnat 0, bnat 1, {} _ >`, we get
 
-```k-repl
+```text
 > :C bnat
 $ bnat = < @... 0, @... 1, {} _ >;  -- @...
 ```

package/DOCS/book.md

@@ -1,5 +1,5 @@
 ---
-title: "k-language"
+title: "k"
 author: "W. Fraczak"
 ---
 
@@ -15,32 +15,28 @@ author: "W. Fraczak"
 
 </div>
 
-# The k-language Book
-
-This book describes the k programming language - a minimal functional language for transforming tree-structured data using partial functions and algebraic data types.
-
-## Table of Contents
-
-1. [Introduction](book/01-introduction.md)
-2. [Syntax and Values](book/02-syntax-and-values.md)  
-3. [Types as Finite Automata](book/03-types-as-finite-automata.md)
-4. [Partial Functions and Composition](book/04-partial-functions-and-composition.md)
-5. [Typing, Filters, and Normalization](book/05-typing-filters-and-normalization.md)
-6. [Values in Memory](book/06-values-in-memory.md)
-7. [The Partial Function ABI](book/07-the-partial-function-abi.md)
-8. [Operational Semantics and Execution](book/08-operational-semantics-and-execution.md)
-9. [Compiler Architecture](book/09-compiler-architecture.md)
-10. [From AST to Intermediate Representation](book/10-from-ast-to-intermediate-representation.md)
-11. [LLVM Basics](book/11-llvm-basics.md)
-12. [Code Generation](book/12-code-generation.md)
-13. [Linking and Execution](book/13-linking-and-execution.md)
-14. [Canonical Serialization](book/14-canonical-serialization.md)
-15. [Optimization and Folding](book/15-optimization-and-folding.md)
-16. [Toward a Universal Schema Registry](book/16-toward-a-universal-schema-registry.md)
+# The k Book
+
+This book describes the k programming language: a minimal functional language
+for transforming tree-structured data using partial functions and algebraic
+data types.
+
+## Available Chapters
+
+- [Introduction](book/01-introduction.md)
+- [Syntax and Values](book/02-syntax-and-values.md)
+- [Types as Finite Automata](book/03-types-as-finite-automata.md)
+- [Partial Functions and Composition](book/04-partial-functions-and-composition.md)
+- [Typing, Filters, and Normalization](book/05-typing-filters-and-normalization.md)
+- [Values in Memory](book/06-values-in-memory.md)
+- [The Partial Function ABI](book/07-the-partial-function-abi.md)
+- [Operational Semantics and Execution](book/08-operational-semantics-and-execution.md)
+- [Compiler Architecture](book/09-compiler-architecture.md)
+- [From AST to Intermediate Representation](book/10-from-ast-to-intermediate-representation.md)
+- [Canonical Serialization](book/14-canonical-serialization.md)
 
 ## Appendices
 
-- [Appendix A: Implementing a Prototype Compiler in Python](book/appendix-a-implementing-a-prototype-compiler-in-python.md)
 - [Appendix B: Incorporating External Predefined Types and Functions](book/appendix-b-incorporating-external-predefined-types-and-functions.md)
 
 ---