@dallaylaen/ski-interpreter 2.8.0 → 2.8.2

package/CHANGELOG.md

@@ -5,6 +5,28 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.8.2] - 2026-04-26
+
+### Added
+
+- `examples/` are now included in the package
+
+### Fixed
+
+- removed stale .d.ts file from lib/
+
+## [2.8.1] - 2026-04-26
+
+### Added
+
+- `SKI.extras.equiv(expr1, expr2, options: InferOptions?)` to check if two expressions are computationally equivalent.
+- `./bin/ski.js compare <expr1> <expr2>` command to compare two expressions for equivalence.
+
+### Changed
+
+- `Expr.infer()` keeps adding variables to nonterminating expressions
+to catch e.g. `CK(WWW)` (never terminates but eqivalent to I).
+
 ## [2.8.0] - 2026-04-23
 
 ### BREAKING CHANGES

package/bin/ski.js

@@ -71,6 +71,23 @@ program
     inferExpression(expression);
   });
 
+program
+  .command('compare <expr1> <expr2>')
+  .description('Check if two expressions are equivalent')
+  .action((expr1, expr2) => {
+    const ski = new SKI();
+    const e1 = ski.parse(expr1);
+    const e2 = ski.parse(expr2);
+    const res = SKI.extras.equiv(e1, e2, runOptions);
+    if (res.equal)
+      console.log('Both expressions are equivalent to ' + res.canonical[0].format(format));
+    else
+      console.log(`Expressions differ:\n${res.canonical[0].format(format)}\n vs \n${res.canonical[1].format(format)}`);
+
+    console.log(`// ${res.steps} step(s)`);
+    process.exit(res.equal ? 0 : 1);
+  });
+
 // Extract subcommand
 program
   .command('extract <target> <terms...>')

package/example/collatz.ski

@@ -0,0 +1,30 @@
+// This file generates a trace of a Collatz 3n+1 sequence,
+// producing HUGE number of steps with very deep recursion,
+// and can thus be used as a rough performance benchmark.
+
+// `calc f n` == `f n`, provided n is a number, except that `n` is
+// forced into a redex position before being fed to `f`,
+// thus eliminating possible duplicate computations.
+
+T=CI;
+V=BCT;
+calc=BBB(T 0)(V(CB+));
+if=BBB(B(BW)C)C;
+half=C(V(C(V(T(KI))(C(B+)K)))(K 0))K;
+collatz=if(VCK)half(B(V+ 1)(B 3));
+dec=BBBCV(C(BT)+)(K 0)I;
+M=WI;
+wait4=BBB(BCC)(BCC);
+nil=KI;
+lst=BS(C(BB));
+fold=M(B(SI)(wait4M))(B(C(BV(BBBK))nil)(C(BBlst)));
+L=BWB;
+lazyy=M(B(SI)(wait4M));
+lesseq=C(BB(VT(KK)))(VT(K(KI)));
+P=M(C(BL(WC)));
+R=CC;
+v3=BBBCV;
+
+BML(B(S(B(BB(B(Bcalc(SV))))(Cif (Knil)))) (B(S(CB)))) (C lesseq 1) (collatz) 127
+// BML(B(S(B(BB(B((SV))))(Cif (Knil)))) (B(S(CB)))) (C lesseq 1) (collatz) 27
+

package/example/eval.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+
+/**
+ * A minimal example of evaluating a SKI expression.
+ */
+
+'use strict';
+
+const { SKI } = require('../lib/ski-interpreter.cjs');
+// SKI is the only export and contains other goodies as subkeys
+
+const [node, path, src] = process.argv;
+
+if (!src) {
+  console.log(`Usage: ${node} ${path} <src>`);
+  process.exit(1);
+}
+
+const ski = new SKI();
+
+// add some extra terms
+ski.add('M', 'SII'); // an alias
+ski.add('L', x => y => x.apply(y.apply(y))) // ditto but with a 'Native' js impl
+
+const expr = ski.parse(src);
+
+// expr.step() = 1 reduction, expr.run() = reduce to the end
+// expr.walk() = an iterator
+// all three return an object with { steps, expr, final } where:
+// - steps = the number of reductions performed so far
+// - expr = the resulting expression
+// - final = boolean indicating if the expression is in normal form (no more reductions possible)
+for (const step of expr.walk())
+  console.log(`[${step.steps}] ${step.expr}`);

package/example/example-quests.json

@@ -0,0 +1,83 @@
+{
+  "id": "dull6XUf",
+  "created_at": "2026-02-27T00:00:00",
+  "name": "Example quests",
+  "intro": "<p>A small template collection of combinatory logic exercises. Feel free to use this file as a starting point for your own quest chapter.</p>",
+  "content": [
+    {
+      "id": "YpgCLTl8",
+      "created_at": "2026-02-27T00:00:00",
+      "name": "I from SK",
+      "intro": [
+        "<p>The identity combinator <code>I</code> satisfies <code>I x = x</code>.",
+        "It can actually be derived from <code>S</code> and <code>K</code> alone &mdash;",
+        "no built-in <code>I</code> needed.</p>",
+        "<p>Find a term built only from <code>S</code> and <code>K</code> that behaves like <code>I</code>.</p>"
+      ],
+      "hint": "Think about what <code>S K K x</code> reduces to.",
+      "allow": "SK",
+      "input": "phi",
+      "cases": [
+        [ "phi x", "x" ],
+        [ "phi (K x y)", "K x y" ]
+      ]
+    },
+    {
+      "id": "vQsBd85P",
+      "created_at": "2026-02-27T00:00:00",
+      "name": "NAND for K/KI",
+      "intro": [
+        "<p>Using the Church encoding, <code>K</code> represents <b>true</b> and <code>KI</code> represents <b>false</b>.</p>",
+        "<p>Implement <code>nand</code>: it should return <code>K</code> (true) for every pair of inputs",
+        "except when <i>both</i> are <code>K</code> (true), in which case it returns <code>KI</code> (false).</p>",
+        "<p>Apply the result to <code>true</code> and <code>false</code> witnesses to observe it.</p>"
+      ],
+      "input": "phi",
+      "cases": [
+        [ "phi K     K     true false", "false" ],
+        [ "phi (KI)  K     true false", "true"  ],
+        [ "phi K     (KI)  true false", "true"  ],
+        [ "phi (KI)  (KI)  true false", "true"  ]
+      ]
+    },
+    {
+      "id": "IgVco9YW",
+      "created_at": "2026-02-27T00:00:00",
+      "name": "Linear basis from I and your own combinator",
+      "intro": [
+        "<p>It can be shown that <code>I</code>, <code>B</code>, and <code>C</code> (or <code>T</code>)",
+        "form a complete basis for <i>linear</i> combinators &mdash; those that use every argument",
+        "exactly once.</p>",
+        "<p>Surprisingly, <code>B</code> and <code>C</code> can be merged into a single combinator.",
+        "Your task is to <i>declare</i> such a combinator <code>P</code> (lambdas are allowed here),",
+        "and then <i>prove</i> the basis is complete by implementing <code>B</code> and <code>T</code>",
+        "using only <code>I</code> and your <code>P</code>.</p>"
+      ],
+      "input": [
+        {
+          "name": "P",
+          "lambdas": true,
+          "allow": "I-I",
+          "note": "Declare your own linear combinator (lambdas allowed, no built-ins)."
+        },
+        {
+          "name": "B",
+          "lambdas": false,
+          "allow": "I",
+          "note": "Implement <code>B a b c = a (b c)</code> using <code>P</code> and <code>I</code>."
+        },
+        {
+          "name": "T",
+          "lambdas": false,
+          "allow": "I",
+          "note": "Implement <code>T a b = b a</code> using <code>P</code> and <code>I</code>."
+        }
+      ],
+      "cases": [
+        [ { "caps": { "linear": true } }, "P" ],
+        [ "B a b c", "a (b c)" ],
+        [ "T a b", "b a" ]
+      ]
+    }
+  ]
+}

package/example/mini-quest.html

@@ -0,0 +1,42 @@
+<!DOCTYPE html>
+<html>
+<head>
+    <meta charset="utf-8"/>
+    <title>Example Quests - Simple Kombinator Interpreter</title>
+    <script src="../docs/build/js/ski-quest.min.js"></script>
+    <style>
+        body {
+            font-family: sans-serif;
+            max-width: 860px;
+            margin: 0 auto;
+            padding: 1em;
+        }
+        #inventory {
+            border: 1px solid #ccc;
+            padding: 0.5em 1em;
+            margin-bottom: 1em;
+        }
+    </style>
+</head>
+<body>
+    <h1>Example Quests</h1>
+
+    <div id="inventory">
+        <b>Inventory</b>
+        <ul id="known"></ul>
+    </div>
+
+    <div id="quest"></div>
+
+<script>
+    const page = new QuestPage({
+        storePrefix: 'example-quests',
+        baseUrl: '.',
+        contentBox:   document.getElementById('quest'),
+        inventoryBox: document.getElementById('known'),
+    });
+
+    page.loadChapters(['example-quests.json']);
+</script>
+</body>
+</html>

package/example/reverse-linked-list.ski

@@ -0,0 +1,14 @@
+
+T=CI;
+V=BCT;
+L=BWB;
+
+nil = KI;
+
+fix = WSL;
+
+rev = V(fix (B(B(B(BC)(CBV))B)V)) nil;
+
+rev (V a (V b (V c (V d (V e nil)))))
+
+

package/example/t-foo-bar.ski

@@ -0,0 +1,5 @@
+// This is an example file written in SKI
+// usage: ./bin/ski.js <this file>
+// The expression below evaluates to bar(foo)
+
+S(K(SI))K foo bar

package/lib/ski-interpreter.cjs.js

@@ -357,11 +357,9 @@ var Expr = class _Expr {
     let steps = 0;
     let expr = this;
     main: for (let i = 0; i < options.maxArgs; i++) {
-      const next = expr.run({ max: options.max - steps, maxSize: options.maxSize });
+      const next = expr.run({ max: Math.max((options.max - steps) / 2, 10), maxSize: options.maxSize });
       steps += next.steps;
-      if (!next.final)
-        break;
-      if (firstVar(next.expr)) {
+      if (next.final && firstVar(next.expr)) {
         expr = next.expr;
         if (!expr.any((e) => !(e instanceof FreeVar || e instanceof App)))
           return maybeLambda(probe, expr, { steps });
@@ -2087,6 +2085,77 @@ function canonize(term, options = {}) {
 }
 
 // src/extras.ts
+var formatSchema = {
+  html: (x) => typeof x === "boolean" ? void 0 : "must be a boolean",
+  terse: (x) => typeof x === "boolean" ? void 0 : "must be a boolean",
+  space: (x) => typeof x === "string" ? void 0 : "must be a string",
+  brackets: isStringPair,
+  var: isStringPair,
+  around: isStringPair,
+  redex: isStringPair,
+  lambda: isStringTriple,
+  inventory: (x) => {
+    if (typeof x !== "object" || x === null || x.constructor !== Object)
+      return "must be an object, not " + (x?.constructor?.name ?? typeof x);
+    const refined = x;
+    for (const key of Object.keys(refined)) {
+      if (!(refined[key] instanceof Expr))
+        return "key " + key + "is not an Expr";
+    }
+    return void 0;
+  }
+};
+function checkFormatOptions(raw) {
+  if (raw === null || raw === void 0)
+    return { value: {} };
+  if (typeof raw !== "object" || Array.isArray(raw) || raw.constructor !== Object)
+    return { error: { object: "Format options must be an object, not " + (raw?.constructor?.name ?? typeof raw) } };
+  const rec = raw;
+  const error = {};
+  for (const key in rec) {
+    if (formatSchema[key]) {
+      const err = formatSchema[key](rec[key]);
+      if (err)
+        error[key] = err;
+    } else
+      error[key] = "unknown option";
+  }
+  return Object.keys(error).length > 0 ? { error } : { value: rec };
+}
+function equiv(e1, e2, options = {}) {
+  let steps = 0;
+  const [n1, n2] = [e1, e2].map((x) => x.traverse((e) => {
+    const props = e.infer(options);
+    steps += props.steps ?? 0;
+    return props.expr;
+  }));
+  const normal = !!(n1 && n2);
+  return {
+    steps,
+    normal,
+    equal: normal ? n1.equals(n2) : false,
+    canonical: [n1, n2]
+  };
+}
+function declare(expr, env) {
+  return expr.declare({ inventory: env });
+}
+function deepFormat(obj, options = {}) {
+  if (obj instanceof Expr)
+    return obj.format(options);
+  if (obj instanceof Quest)
+    return "Quest(" + obj.name + ")";
+  if (obj instanceof Quest.Case)
+    return "Quest.Case";
+  if (Array.isArray(obj))
+    return obj.map((item) => deepFormat(item, options));
+  if (typeof obj !== "object" || obj === null || obj.constructor !== Object)
+    return obj;
+  const out = {};
+  for (const key in obj)
+    out[key] = deepFormat(obj[key], options);
+  return out;
+}
 function search(seed, options, predicate) {
   const {
     depth = 16,
@@ -2150,65 +2219,13 @@ function search(seed, options, predicate) {
   }
   return { total, probed, gen: depth, ...options.retain ? { cache } : {} };
 }
-function deepFormat(obj, options = {}) {
-  if (obj instanceof Expr)
-    return obj.format(options);
-  if (obj instanceof Quest)
-    return "Quest(" + obj.name + ")";
-  if (obj instanceof Quest.Case)
-    return "Quest.Case";
-  if (Array.isArray(obj))
-    return obj.map((item) => deepFormat(item, options));
-  if (typeof obj !== "object" || obj === null || obj.constructor !== Object)
-    return obj;
-  const out = {};
-  for (const key in obj)
-    out[key] = deepFormat(obj[key], options);
-  return out;
-}
-function declare(expr, env) {
-  return expr.declare({ inventory: env });
+function isStringPair(x) {
+  return Array.isArray(x) && x.length === 2 && typeof x[0] === "string" && typeof x[1] === "string" ? void 0 : "must be a pair of strings";
 }
-var isStringPair = (x) => Array.isArray(x) && x.length === 2 && typeof x[0] === "string" && typeof x[1] === "string" ? void 0 : "must be a pair of strings";
-var isStringTriple = (x) => Array.isArray(x) && x.length === 3 && typeof x[0] === "string" && typeof x[1] === "string" && typeof x[2] === "string" ? void 0 : "must be a triplet of strings";
-var schema = {
-  html: (x) => typeof x === "boolean" ? void 0 : "must be a boolean",
-  terse: (x) => typeof x === "boolean" ? void 0 : "must be a boolean",
-  space: (x) => typeof x === "string" ? void 0 : "must be a string",
-  brackets: isStringPair,
-  var: isStringPair,
-  around: isStringPair,
-  redex: isStringPair,
-  lambda: isStringTriple,
-  inventory: (x) => {
-    if (typeof x !== "object" || x === null || x.constructor !== Object)
-      return "must be an object, not " + (x?.constructor?.name ?? typeof x);
-    const refined = x;
-    for (const key of Object.keys(refined)) {
-      if (!(refined[key] instanceof Expr))
-        return "key " + key + "is not an Expr";
-    }
-    return void 0;
-  }
-};
-function checkFormatOptions(raw) {
-  if (raw === null || raw === void 0)
-    return { value: {} };
-  if (typeof raw !== "object" || Array.isArray(raw) || raw.constructor !== Object)
-    return { error: { object: "Format options must be an object, not " + (raw?.constructor?.name ?? typeof raw) } };
-  const rec = raw;
-  const error = {};
-  for (const key in rec) {
-    if (schema[key]) {
-      const err = schema[key](rec[key]);
-      if (err)
-        error[key] = err;
-    } else
-      error[key] = "unknown option";
-  }
-  return Object.keys(error).length > 0 ? { error } : { value: rec };
+function isStringTriple(x) {
+  return Array.isArray(x) && x.length === 3 && typeof x[0] === "string" && typeof x[1] === "string" && typeof x[2] === "string" ? void 0 : "must be a triplet of strings";
 }
-var extras = { search, deepFormat, declare, toposort, checkFormatOptions };
+var extras = { search, deepFormat, declare, toposort, checkFormatOptions, equiv };
 
 // src/index.ts
 extras.toposort = toposort;