@fraczak/k 6.1.3 → 6.2.0

package/AGENTS.md

@@ -5,12 +5,12 @@
 - `k_compiler/` contains the Python prototype compiler and supporting modules.
 - `type_registry/` houses registry experiments and grammar artifacts.
 - `Examples/` and `DOCS/` provide sample programs and design notes.
-- Tests live in top-level `test*.mjs`, `Code-derivation-tests/`, and `tests.sh`.
+- Tests live in `tests/`, with type-derivation cases in `tests/code-derivation/`.
 
 ## Build, Test, and Development Commands
 - `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`).
+- `npm test` runs the full suite through `scripts/run-tests.mjs`.
 - `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.
 
@@ -21,8 +21,8 @@
 - Grammar sources are `parser.jison` and `valueParser.jison`; generated files should not be hand-edited.
 
 ## Testing Guidelines
-- Add runtime tests alongside `test.mjs` or new `test-*.mjs` files.
-- Add type-derivation coverage in `Code-derivation-tests/` (one case per file is typical).
+- Add runtime tests alongside `tests/test.mjs` or new `tests/test-*.mjs` files.
+- Add type-derivation coverage in `tests/code-derivation/` (one case per file is typical).
 - Verify locally with `npm test` before opening a PR.
 
 ## Commit & Pull Request Guidelines

package/CLAUDE.md

@@ -60,5 +60,5 @@ 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
+- Extensive test suite in `tests/code-derivation/` for type system validation
 - REPL supports commands like `:C name` (show canonical type), `:t name` (show relation type), and `:d name` (show relation definition)

package/DOCS/OBJECT_FILE_AND_PATTERN.md

@@ -305,3 +305,9 @@ shape is the same object payload shape with `main: null`:
 When a library is compiled with `--lib`, the output is the merged library
 closure. Imported codes, relations, aliases, and metadata are preserved, and the
 new source adds its own origins.
+
+The REPL `:klib` command uses active relation aliases as roots. It stores their
+transitive relation closure and omits historical content-addressed relations
+that remain in the live session after alias rebinding but are no longer
+reachable from an active alias. Its `codes` field remains the registered code
+snapshot needed to reload the library.

package/DOCS/REPL.md

@@ -11,9 +11,9 @@ The interpreter keeps a live `.klib`-style state in memory:
 - metadata origins used to recover aliases
 - the current value flowing through the session
 
-Raw k snippets compile on top of that state. You can also export the current
-session as a `.klib` library or compile an executable `.ko` object from an
-expression in the session context.
+Raw k snippets compile on top of that state. You can also export the active
+library closure as a `.klib` file or compile an executable `.ko` object from
+an expression in the session context.
 
 ## Prompt Model
 
@@ -49,7 +49,7 @@ complete.
 | `:codec list` | List loaded REPL codecs |
 | `:input type [codec]` | Read the next line as codec input for a singleton type |
 | `:load [--no-alias] file` | Load `.k` source or `.klib` into the current state |
-| `:klib file` | Export current state as a `.klib` library |
+| `:klib file` | Export the active relation closure as a `.klib` library |
 | `:ko file expr` | Export a `.ko` executable with `expr` as main |
 | `:val` | Print current value and JSON form |
 | `:reset` | Reset interpreter state |
@@ -62,7 +62,7 @@ Raw input is compiled as k source on top of the current state.
 Examples:
 
 ```k
-> {} |succ
+> {} |ok
 ```
 
 ```k
@@ -107,6 +107,8 @@ The interpreter keeps:
 
 Definitions are content-addressed. Rebinding an alias changes the name-to-hash
 mapping, but older canonical definitions remain available by hash.
+They stay available in the live session, but `:klib` omits historical
+relations that are no longer reachable from an active relation alias.
 
 ## Alias Resolution
 
@@ -184,8 +186,11 @@ against that code before becoming the current value.
 
 ### `:klib file`
 
-Writes the current interpreter state as a plain-JSON `.klib` library. The
-library has `main: null`; it has no binary header and no object payload version.
+Writes a plain-JSON `.klib` library rooted at the current relation aliases.
+Relations referenced by those aliases are included transitively. Historical
+relations retained in the live session are omitted when no active alias
+depends on them. The registered code snapshot is still included. The library
+has `main: null`; it has no binary header and no object payload version.
 
 ### `:ko file expr`
 
@@ -197,7 +202,7 @@ writes the resulting executable `.ko` object.
 Evaluated values print in k syntax together with the inferred envelope:
 
 ```text
-{succ: {succ: {zero: {}}}} ?<{} zero, X succ>=X
+{}|0|+1 ?<<{} 0, ...> +1, ...>
 ```
 
 `undefined` prints as:
@@ -212,16 +217,16 @@ Evaluated values print in k syntax together with the inferred envelope:
 ## Example Session
 
 ```text
-> :type nat = <{} zero, nat succ>
+> :type nat = <{} 0, nat +1>
 $ nat = @...
-> :rel succ = |succ
-succ = @...
-> {} |zero
-{zero: {}} ?<{} zero, X succ>=X
-> :t succ
-succ : ?X  -->  ?<{} zero, X succ>=X  (@...)
+> :rel inc = |+1
+inc = @...
+> {} |0
+{}|0 ?<{} 0, ...>
+> :t inc
+inc : ?X0  -->  ?<X0 +1, ...>  (@...)
 > :klib nat.klib
 saved nat.klib
-> :ko succ.ko succ
-saved succ.ko (succ)
+> :ko inc.ko inc
+saved inc.ko (inc)
 ```

package/README.md

@@ -55,8 +55,8 @@ from `x` to `y` and recurses. When that no longer applies, it returns `y`.
 In the REPL:
 
 ```text
-> { {} |0 inc inc x, {} |0 inc y } add
-{}|0|+1|+1|+1 ?<X0 +1, {} 0, ...>=X0
+> { 0 inc inc x, 0 inc y } add
+{}|0|+1|+1|+1 ?<X0 +1, {} 0>=X0
 ```
 
 That evaluates `2 + 1` to `3`: a value starts at `0`, and each `+1` tag adds
@@ -277,13 +277,14 @@ compose with `.result` when only the floating-point value is needed.
 
 ```bash
 npm run prepare   # regenerate parsers from .jison grammars
-npm test          # run the full suite
+npm test          # run the fail-fast full suite with per-test timings
 ```
 
-The test suite covers:
+The test runner prints each test before execution and reports its elapsed time
+afterward. It stops immediately when a test fails. The suite covers:
 
 - core runtime and parser behavior
-- type derivation cases in `Code-derivation-tests/`
+- type derivation cases in `tests/code-derivation/`
 - hash/fingerprint stability
 - object file round-trips
 - REPL scripted interaction

package/export.mjs

@@ -113,6 +113,16 @@ function theID(alias, rel, scc, name) {
 export function assignCanonicalNames(scc, rels, relAlias) {
   const newAlias = scc.reduce( (newAlias,relName) => {
     const relDef = rels[relName];
+    // Rehashing an imported recursive relation would create a wrapper around its canonical hash.
+    if (
+      relDef.def.op == "ref" &&
+      relDef.def.ref.startsWith("@") &&
+      rels[relDef.def.ref]?._library
+    ) {
+      rels[relName] = rels[relDef.def.ref];
+      newAlias[relName] = relDef.def.ref;
+      return newAlias;
+    }
     if (relDef.def.op == "ref" && rels[relDef.def.ref] != undefined) {
       // inlining if direct alias to a non built-in relation
       // relDef.def = rels[relDef.def.ref]; // simplifyRel(rels[relDef.def.ref],rels);

package/k-vscode/README.md

@@ -16,6 +16,13 @@ unions).
   - Canonical content-addressed references: `@base58hash`
   - Quoted label strings: `"label"`, `'label'` (with escape sequences)
   - The `...` any/open pattern marker
+- **Code-definition backgrounds** applied uniformly from the opening `$` through
+  the terminating `;`
+- **Nested expression backgrounds** for filters and `$` code expressions inside
+  relations, with code-expression backgrounds layered over filter backgrounds
+- **k Contrast color theme** with:
+  - Separate foreground colors for type names, relation identifiers, labels, tags,
+    filter variables, canonical type names, and canonical relation names
 - **Snippets** for every common pattern (trigger via `Tab` after prefix):
 
 | Prefix | Inserts |
@@ -48,13 +55,15 @@ unions).
 
 1. Open the `k-vscode/` folder in VS Code.
 2. Press **F5** — this opens an Extension Development Host with the extension loaded.
+3. Expression backgrounds activate automatically. Run **Preferences: Color Theme**
+   and select **k Contrast** to use the bundled foreground token palette.
 
 ### Build and install a VSIX
 
 ```bash
 cd k-vscode
 npm install
-npx vsce package        # produces k-language-0.2.0.vsix
+npx vsce package --no-dependencies  # produces k-language-0.2.0.vsix
 ```
 
 Then in VS Code: **Extensions → ⋯ → Install from VSIX…** and select the generated file.

package/k-vscode/extension.js

@@ -0,0 +1,273 @@
+const vscode = require("vscode");
+
+const NAME_START = /[a-zA-Z0-9_+\-]/;
+const NAME_PART = /[a-zA-Z0-9_?!+\-]/;
+const OPEN_TO_CLOSE = new Map([
+  ["{", "}"],
+  ["<", ">"],
+  ["(", ")"]
+]);
+const CLOSERS = new Set(OPEN_TO_CLOSE.values());
+
+function lex(text) {
+  const tokens = [];
+  let index = 0;
+
+  while (index < text.length) {
+    const char = text[index];
+    const next = text[index + 1];
+
+    if (/\s/.test(char)) {
+      index++;
+      continue;
+    }
+
+    if (char === "/" && next === "*") {
+      const end = text.indexOf("*/", index + 2);
+      index = end === -1 ? text.length : end + 2;
+      continue;
+    }
+
+    if (
+      (char === "/" && next === "/") ||
+      (char === "-" && next === "-") ||
+      (char === "\\" && next === "\\") ||
+      char === "#" ||
+      char === "%"
+    ) {
+      const end = text.indexOf("\n", index + 1);
+      index = end === -1 ? text.length : end + 1;
+      continue;
+    }
+
+    if (char === "\"" || char === "'") {
+      const start = index++;
+      while (index < text.length) {
+        const current = text[index++];
+        if (current === "\\") {
+          index++;
+        } else if (current === char) {
+          break;
+        }
+      }
+      tokens.push({ value: text.slice(start, index), start, end: index });
+      continue;
+    }
+
+    if (NAME_START.test(char)) {
+      const start = index++;
+      while (index < text.length && NAME_PART.test(text[index])) index++;
+      tokens.push({ value: text.slice(start, index), start, end: index });
+      continue;
+    }
+
+    tokens.push({ value: char, start: index, end: index + 1 });
+    index++;
+  }
+
+  return tokens;
+}
+
+function isName(token) {
+  return token != null && NAME_START.test(token.value[0]);
+}
+
+function findDefinitionEnd(tokens, startIndex) {
+  const stack = [];
+
+  for (let index = startIndex; index < tokens.length; index++) {
+    const value = tokens[index].value;
+    const closer = OPEN_TO_CLOSE.get(value);
+    if (closer) {
+      stack.push(closer);
+    } else if (CLOSERS.has(value)) {
+      if (value !== stack.at(-1)) return -1;
+      stack.pop();
+    } else if (value === ";" && stack.length === 0) {
+      return index;
+    }
+  }
+
+  return -1;
+}
+
+function findMatching(tokens, startIndex) {
+  const firstCloser = OPEN_TO_CLOSE.get(tokens[startIndex]?.value);
+  if (!firstCloser) return -1;
+
+  const stack = [firstCloser];
+  for (let index = startIndex + 1; index < tokens.length; index++) {
+    const value = tokens[index].value;
+    const closer = OPEN_TO_CLOSE.get(value);
+    if (closer) {
+      stack.push(closer);
+    } else if (CLOSERS.has(value)) {
+      if (value !== stack.at(-1)) return -1;
+      stack.pop();
+      if (stack.length === 0) return index;
+    }
+  }
+
+  return -1;
+}
+
+function parseCodeEnd(tokens, startIndex) {
+  const token = tokens[startIndex];
+  if (!token) return -1;
+
+  if (isName(token)) return startIndex + 1;
+
+  if (token.value === "@" && isName(tokens[startIndex + 1])) {
+    return startIndex + 2;
+  }
+
+  if (token.value === "{" || token.value === "<") {
+    const matching = findMatching(tokens, startIndex);
+    return matching === -1 ? -1 : matching + 1;
+  }
+
+  return -1;
+}
+
+function parseFilterEnd(tokens, startIndex) {
+  const token = tokens[startIndex];
+  if (!token) return -1;
+
+  let endIndex;
+  if (token.value === "$") {
+    endIndex = parseCodeEnd(tokens, startIndex + 1);
+  } else if (token.value === "(" || token.value === "{" || token.value === "<") {
+    const matching = findMatching(tokens, startIndex);
+    endIndex = matching === -1 ? -1 : matching + 1;
+  } else if (isName(token)) {
+    endIndex = startIndex + 1;
+  } else {
+    return -1;
+  }
+
+  if (
+    endIndex !== -1 &&
+    tokens[endIndex]?.value === "=" &&
+    isName(tokens[endIndex + 1])
+  ) {
+    endIndex += 2;
+  }
+
+  return endIndex;
+}
+
+function collectBackgroundRanges(text) {
+  const tokens = lex(text);
+  const type = [];
+  const filter = [];
+
+  let index = tokens[0]?.value === "~" ? 1 : 0;
+  while (index < tokens.length) {
+    const isTypeDefinition =
+      tokens[index]?.value === "$" &&
+      isName(tokens[index + 1]) &&
+      tokens[index + 2]?.value === "=";
+    const isRelationDefinition =
+      isName(tokens[index]) &&
+      tokens[index + 1]?.value === "=";
+
+    if (!isTypeDefinition && !isRelationDefinition) break;
+
+    const equalsIndex = index + (isTypeDefinition ? 2 : 1);
+    const endIndex = findDefinitionEnd(tokens, equalsIndex + 1);
+    if (endIndex === -1) break;
+
+    if (isTypeDefinition) {
+      type.push({
+        start: tokens[index].start,
+        end: tokens[endIndex].end
+      });
+    }
+    index = endIndex + 1;
+  }
+
+  for (let tokenIndex = 0; tokenIndex < tokens.length; tokenIndex++) {
+    if (tokens[tokenIndex].value === "?") {
+      const endIndex = parseFilterEnd(tokens, tokenIndex + 1);
+      if (endIndex !== -1) {
+        filter.push({
+          start: tokens[tokenIndex].start,
+          end: tokens[endIndex - 1].end
+        });
+      }
+      continue;
+    }
+
+    if (tokens[tokenIndex].value !== "$") continue;
+
+    const isDefinition =
+      isName(tokens[tokenIndex + 1]) &&
+      tokens[tokenIndex + 2]?.value === "=";
+    if (isDefinition) continue;
+
+    const endIndex = parseCodeEnd(tokens, tokenIndex + 1);
+    if (endIndex !== -1) {
+      type.push({
+        start: tokens[tokenIndex].start,
+        end: tokens[endIndex - 1].end
+      });
+    }
+  }
+
+  return { type, filter };
+}
+
+function toVscodeRanges(document, ranges) {
+  return ranges.map(({ start, end }) => new vscode.Range(
+    document.positionAt(start),
+    document.positionAt(end)
+  ));
+}
+
+function activate(context) {
+  const filterDecoration = vscode.window.createTextEditorDecorationType({
+    backgroundColor: "rgba(58, 45, 32, 0.82)"
+  });
+  const typeDecoration = vscode.window.createTextEditorDecorationType({
+    backgroundColor: "rgba(38, 53, 39, 0.92)"
+  });
+
+  context.subscriptions.push(filterDecoration, typeDecoration);
+
+  function updateEditor(editor) {
+    if (editor.document.languageId !== "k") return;
+
+    const ranges = collectBackgroundRanges(editor.document.getText());
+    editor.setDecorations(
+      filterDecoration,
+      toVscodeRanges(editor.document, ranges.filter)
+    );
+    editor.setDecorations(
+      typeDecoration,
+      toVscodeRanges(editor.document, ranges.type)
+    );
+  }
+
+  function updateVisibleEditors() {
+    for (const editor of vscode.window.visibleTextEditors) updateEditor(editor);
+  }
+
+  context.subscriptions.push(
+    vscode.window.onDidChangeVisibleTextEditors(updateVisibleEditors),
+    vscode.workspace.onDidChangeTextDocument(({ document }) => {
+      for (const editor of vscode.window.visibleTextEditors) {
+        if (editor.document === document) updateEditor(editor);
+      }
+    })
+  );
+
+  updateVisibleEditors();
+}
+
+function deactivate() {}
+
+module.exports = {
+  activate,
+  collectBackgroundRanges,
+  deactivate
+};

package/k-vscode/package.json

@@ -23,6 +23,21 @@
   "categories": [
     "Programming Languages"
   ],
+  "main": "./extension.js",
+  "activationEvents": [
+    "onLanguage:k"
+  ],
+  "files": [
+    "extension.js",
+    "language-configuration.json",
+    "README.md",
+    "snippets/k.json",
+    "syntaxes/k.tmLanguage.json",
+    "themes/k-contrast-color-theme.json"
+  ],
+  "scripts": {
+    "test": "node test/background-ranges.test.js"
+  },
   "contributes": {
     "languages": [
       {
@@ -44,6 +59,13 @@
         "path": "./syntaxes/k.tmLanguage.json"
       }
     ],
+    "themes": [
+      {
+        "label": "k Contrast",
+        "uiTheme": "vs-dark",
+        "path": "./themes/k-contrast-color-theme.json"
+      }
+    ],
     "snippets": [
       {
         "language": "k",