@dallaylaen/ski-interpreter 2.8.1 → 2.9.0

package/CHANGELOG.md

@@ -5,6 +5,41 @@ 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.9.0] - 2026-06-27
+
+### BREAKING CHANGES
+
+* SKI.extras.search is now a generator, yielding progress ticks as well as found terms, which may now be multiple.
+* Quest page now requires { chapters: [...] } instead of [...] in index.json.
+
+### Added
+
+* Examples: `example/find-monobase.js` to showcase nested search() usage.
+* Quest page: "New!" badge for quests newer than 30 days.
+* Quest page: Reordered for clearer narrative, more quests added.
+* `bin/ski.js search` diplays elapsed time.
+* `bin/ski.js -q` flag to suppress extra output.
+* `bin/ski.js file -` will process STDIN
+* Added a self-hosted [combinator cheat-sheet page](https://dallaylaen.github.io/ski-interpreter/combinator-birds.html) (#29).
+
+### Changed
+* `bin/ski.js search` output is now parseable (metadata commented out) 
+* Better Collatz conjecture in examples (thx @Darkwing3125) fixes #28
+
+### Fixed
+* Solved quests weren't displayed as solved
+* History button svg (thx @akuklev)
+
+## [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

package/bin/ski.js

@@ -11,6 +11,7 @@ const runOptions = {};
 /** @type FormatOptions */
 let format = {};
 let verbose = false;
+let quiet = false;
 
 const program = new Command();
 
@@ -19,6 +20,7 @@ program
   .description('Simple Kombinator Interpreter - a combinatory logic & lambda calculus parser and interpreter')
   .version(version)
   .option('-v, --verbose', 'Show all evaluation steps', () => { verbose = true; })
+  .option('-q, --quiet', 'Suppress comment lines in output', () => { quiet = true; })
   .option('--format <json>', 'Format for output expressions', setFormat)
   .option('--max <number>', 'Limit computation steps', raw => {
     const n = Number.parseInt(raw);
@@ -165,13 +167,19 @@ function evaluateExpression (expression) {
 
 function evaluateFile (filepath) {
   const ski = new SKI();
+  const onErr = err => {
+    console.error('' + err);
+    process.exit(3);
+  };
+  if (filepath === '-') {
+    let source = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', chunk => { source += chunk; });
+    process.stdin.on('end', () => { processLine(source, ski, onErr); });
+    return;
+  }
   fs.readFile(filepath, 'utf8')
-    .then(source => {
-      processLine(source, ski, err => {
-        console.error('' + err);
-        process.exit(3);
-      });
-    })
+    .then(source => { processLine(source, ski, onErr); })
     .catch(err => {
       console.error('ski: ' + err);
       process.exit(2);
@@ -190,7 +198,8 @@ function processLine (source, ski, onErr) {
 
     for (const state of expr.walk(runOptions)) {
       if (state.final) {
-        console.log(`// ${state.steps} step(s) in ${new Date() - t0}ms`);
+        if (!quiet)
+          console.log(`// ${state.steps} step(s) in ${new Date() - t0}ms`);
         console.log(state.expr.declare({ ...format, inventory: ski.getTerms() }));
       } else if (verbose)
         console.log(state.expr.format(format) + ';');
@@ -232,7 +241,7 @@ function displayInfer (guess) {
     console.log(guess.expr.format(format));
 
   for (const key of ['normal', 'proper', 'arity', 'discard', 'duplicate', 'steps']) {
-    if (guess[key] !== undefined)
+    if (guess[key] !== undefined && !quiet)
       console.log(`// ${key}: ${guess[key]}`);
   }
 }
@@ -312,19 +321,33 @@ function searchExpression (targetStr, termStrs, options) {
     process.exit(1);
   }
 
-  const res = SKI.extras.search(seed, { tries: options.maxTries, depth: options.maxDepth }, (e, p) => {
+  const t0 = new Date();
+  let lastProgress;
+  let found;
+  for (const progress of SKI.extras.search(seed, { tries: options.maxTries, depth: options.maxDepth }, (e, p) => {
     if (!p.expr)
-      return -1;
+      return { offset: -1 };
     if (p.expr.equals(expr))
-      return 1;
+      return { found: true, stop: true };
     return 0;
-  });
+  })) {
+    lastProgress = progress;
+    if (progress.found) {
+      found = progress.expr;
+      break;
+    }
+  }
+  const elapsed = new Date() - t0;
+  const { total = 0 } = lastProgress ?? {};
 
-  if (res.expr) {
-    console.log(`Found ${res.expr.format(format)} after ${res.total} tries.`);
+  if (found) {
+    console.log(found.format(format));
+    if (!quiet)
+      console.log(`// Found after ${total} tries in ${elapsed}ms.`);
     process.exit(0);
   } else {
-    console.error(`No equivalent expression found for ${target} after ${res.total} tries.`);
+    if (!quiet)
+      console.log(`// No expression was found after ${total} tries in ${elapsed}ms.`);
     process.exit(1);
   }
 }

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=C(W(C(CI(B(CB+)C))0))0; // courtesy of @Darkwing3125
+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/find-monobase.js

@@ -0,0 +1,108 @@
+'use strict';
+
+/**
+ * This script showcases advanced usage of SKI.extras.search.
+ *
+ * A monobase is a single term that allows to construct a given set of terms (for example, _all of them_)
+ * by only applying itself to itself.
+ * The most well-known example is perhaps the iota combinator: x->xSK.
+ *
+ * To achieve this, we apply a brute force search twice: first to find all possible candidate terms,
+ * and second to check if the term at hand is actually a monobase.
+ *
+ * The script keeps track of the target expression max size and reduces the search depth accordingly,
+ * to reduce the computational cost.
+ *
+ * Progress indicators are emitted in the meantime.
+ */
+
+const { SKI } = require('../src');
+
+const ski = new SKI();
+
+const { search, deepFormat } = SKI.extras;
+
+// Parse CLI arguments: seed seed seed ... -- target target target ...
+const args = process.argv.slice(2);
+const separatorIdx = args.indexOf('--');
+
+if (separatorIdx === -1 || separatorIdx === 0 || separatorIdx === args.length - 1) {
+  console.error('Usage: node find-monobase.js <seed> [<seed>...] -- <target> [<target>...]');
+  process.exit(1);
+}
+
+const seedStrs = args.slice(0, separatorIdx);
+const targetStrs = args.slice(separatorIdx + 1);
+
+const seed = seedStrs.map(s => ski.parse(s));
+const target = targetStrs.map(s => ski.parse(s));
+
+let best = 12;
+const t0 = new Date();
+
+for (const progress of search(seed, { depth: 100, max: 150, tries: 100_000_000, progressInterval: 100_000 }, (expr, prop) => {
+  if (!prop.expr)
+    return { offset: -1 };
+
+  // if (!prop.discard || !prop.duplicate)
+  //    return 0;
+
+  const term = new SKI.classes.Alias('X', expr);
+  const ret = checkBase([term], target, { depth: best, tries: 100_000, maxArgs: 8, max: 150 });
+  if (!ret)
+    return 0;
+
+  const maxlen = Math.max(
+    ...Object.values(ret)
+      .map(e => countIn(e, term))
+  );
+
+  if (maxlen <= best) {
+    console.log(`New best monobase(${maxlen}): X=${expr} in ${(new Date() - t0) / 1000}s`
+      , deepFormat(ret));
+    best = maxlen;
+    return { found: true };
+  }
+
+  return 0; // anyways...
+}))
+  console.log((new Date() - t0) / 1000, progress.total, progress.gen);
+
+/**
+ * @param { Expr[] } base
+ * @param { Expr[] } target
+ *
+ *
+ */
+
+function checkBase (base, target, options) {
+  const need = {};
+  target.forEach(t => { need[t.infer().expr] = t });
+  const found = {};
+
+  // console.log(deepFormat(target));
+
+  for (const progress of search(base, options, (e, p) => {
+    if (!p.expr) return { offset: -1 };
+    const maybe = need[p.expr];
+    if (!maybe) return 0;
+
+    //  console.log(`found ${maybe} as ${e}`);
+
+    found[maybe] = e;
+    delete need[p.expr];
+    return Object.keys(need).length === 0 ? { found: true, stop: true } : 0;
+  })) {
+    if (progress.found)
+      return found;
+  }
+
+  return undefined;
+}
+
+function countIn (expr, target) {
+  return expr.fold(0, (acc, e) => {
+    if (e === target)
+      return SKI.control.prune(acc + 1);
+  });
+}

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

@@ -1712,6 +1712,8 @@ var Quest = class {
     this.intro = list2str(options.intro);
     this.id = options.id;
     this.meta = meta;
+    if (meta.created_at)
+      this.created = new Date(meta.created_at);
     for (const c of cases ?? [])
       this.add(...c);
   }
@@ -1859,10 +1861,9 @@ var Quest = class {
         findings[field] = found;
     }
     if (options.date) {
-      const date = new Date(this.meta?.created_at);
-      if (isNaN(date.getTime()))
+      if (!this.created || isNaN(this.created.getTime()))
         findings.date = "invalid date format: " + this.meta?.created_at;
-      else if (date.getTime() < (/* @__PURE__ */ new Date("2024-07-15")).getTime() || date.getTime() > (/* @__PURE__ */ new Date()).getTime())
+      else if (this.created < /* @__PURE__ */ new Date("2024-07-15") || this.created > /* @__PURE__ */ new Date())
         findings.date = "date out of range: " + this.meta?.created_at;
     }
     return findings;
@@ -2156,7 +2157,7 @@ function deepFormat(obj, options = {}) {
     out[key] = deepFormat(obj[key], options);
   return out;
 }
-function search(seed, options, predicate) {
+function* search(seed, options, predicate) {
   const {
     depth = 16,
     infer = true,
@@ -2167,57 +2168,70 @@ function search(seed, options, predicate) {
   let total = 0;
   let probed = 0;
   const seen = {};
+  const parseResult = (raw) => {
+    if (raw === null || raw === void 0)
+      return {};
+    if (typeof raw === "number")
+      return raw > 0 ? { found: true, stop: true } : raw < 0 ? { offset: -1 } : {};
+    return raw;
+  };
   const maybeProbe = (term) => {
     total++;
     const props = infer ? term.infer({ max: options.max, maxArgs: options.maxArgs }) : null;
     if (hasSeen && props && props.expr) {
       const key = String(props.expr);
       if (seen[key])
-        return { res: -1, props };
+        return { res: { offset: -1 }, props };
       seen[key] = true;
     }
     probed++;
-    const res = predicate(term, props);
+    const res = parseResult(predicate(term, props));
     return { res, props };
   };
   for (const term of seed) {
-    const { res = 0 } = maybeProbe(term);
-    if (res > 0)
-      return { expr: term, total, probed, gen: 1 };
-    else if (res < 0)
-      continue;
-    cache[0].push(term);
+    const { res } = maybeProbe(term);
+    if (res.found)
+      yield { expr: term, found: true, step: false, gen: 0, total, probed, cache };
+    if (res.stop)
+      return;
+    if ((res.offset ?? 0) >= 0)
+      cache[0].push(term);
   }
   let lastProgress = 0;
   for (let gen = 1; gen < depth; gen++) {
-    if (options.progress) {
-      options.progress({ gen, total, probed, step: true });
-      lastProgress = total;
-    }
+    yield { found: false, step: true, gen, total, probed, cache };
+    lastProgress = total;
     for (let i = 0; i < gen; i++) {
       for (const a of cache[gen - i - 1] || []) {
         for (const b of cache[i] || []) {
-          if (total >= (options.tries ?? Infinity))
-            return { total, probed, gen, ...options.retain ? { cache } : {} };
-          if (options.progress && total - lastProgress >= progressInterval) {
-            options.progress({ gen, total, probed, step: false });
+          if (total >= (options.tries ?? Infinity)) {
+            yield { found: false, step: false, gen, total, probed, cache };
+            return;
+          }
+          if (total - lastProgress >= progressInterval) {
+            yield { found: false, step: false, gen, total, probed, cache };
             lastProgress = total;
           }
           const term = a.apply(b);
           const { res, props } = maybeProbe(term);
-          if ((res ?? 0) > 0)
-            return { expr: term, total, probed, gen, ...options.retain ? { cache } : {} };
-          else if ((res ?? 0) < 0)
+          if (res.found)
+            yield { expr: term, found: true, step: false, gen, total, probed, cache };
+          if (res.stop) {
+            yield { found: false, step: false, gen, total, probed, cache };
+            return;
+          }
+          if ((res.offset ?? 0) < 0)
             continue;
-          const offset = infer && props ? (props.expr ? 0 : 3) + (props.dup ? 1 : 0) + (props.proper ? 0 : 1) : 0;
-          if (!cache[gen + offset])
-            cache[gen + offset] = [];
-          cache[gen + offset].push(term);
+          const autoOffset = infer && props ? (props.expr ? 0 : 3) + (props.dup ? 1 : 0) + (props.proper ? 0 : 1) : 0;
+          const finalOffset = res.offset ?? autoOffset;
+          if (!cache[gen + finalOffset])
+            cache[gen + finalOffset] = [];
+          cache[gen + finalOffset].push(term);
         }
       }
     }
   }
-  return { total, probed, gen: depth, ...options.retain ? { cache } : {} };
+  yield { found: false, step: false, gen: depth, total, probed, cache };
 }
 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";