@dallaylaen/ski-interpreter 2.2.0 → 2.3.0

package/CHANGELOG.md

@@ -5,6 +5,56 @@ 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.3.0] - 2026-02-28
+
+### BREAKING CHANGES
+
+- `ski.js` CLI interface changed (see below)
+- Quest page css changes (see below)
+- `diag()` does not indent `Alias` to reduce diffs
+- Swapped `Expr.expect()` arguments: expected.expect(actual).
+Mnemonic: expected is always an expr, actual may be whatever.
+
+### Added
+
+- `Quest.Group` class and `Quest.verify()` for quest self-check capability.
+- `Quest.selfCheck({ accepted: ..., rejected: ... })` replaces the homegrown `solution` mechanism.
+- `{order: LI|LO}` option to `Expr.traverse()` for left-innermost / left-outermost traversal order.
+- `FreeVar.global` constant as an explicit replacement for the `context=SKI` convention.
+- `TermInfo` typedef for `infer()` results.
+- CLI (`bin/ski.js`) rewritten with `commander`, now supports subcommands: `repl`, `eval`, `file`, `quest-check`.
+- Quest authoring guide added to docs.
+- `expr.expect(actual)` now returns `diag()` as -actual / +expected.
+
+### Fixed
+
+- `infer()` now limits recursion depth to prevent stack overflows (#10).
+- Alias indentation in `diag()` output corrected.
+- Quest page links fixed after previous rewrite.
+- Aliases are no longer canonized without an explicit request.
+
+### Changed
+
+- `toLambda()` and `toSKI()` rewritten using left-innermost traverse.
+- `Church` is now a descendant of `Expr` instead of `Native` (minor speedup).
+- `Expr.constructor` removed for a minor speedup.
+- `parser.add()` now accepts an options object in place of a plain note string.
+- Quest solutions moved to `data/quest-solutions.json`; removed from quest-data.
+- Quest nav items use stable `.ski-quest-nav-item` class instead of fragile `.ski-quest-index a`.
+
+## [2.2.1] - 2026-02-22
+
+### Added
+
+- `Expr.diag()` outputs an expression as an indented tree (breadth-first) with class names and variables labeled for deduplication.
+- `lib/ski-quest.min.js` bundle to create quest pages.
+- The [playground](https://dallaylaen.github.io/ski-interpreter/playground.html) gets history!
+
+### Fixed
+
+- Greatly improved type definitions.
+- Quests calculate solution complexity via `fold()`.
+
 ## [2.2.0] - 2026-02-14
 
 ### BREAKING CHANGES
@@ -20,6 +70,7 @@ that give the initial expression when applied
 from left to right: `((a, b), (c, d)) => [a, b, (c, d)]`
 - Parser: Support for chained assignments (`'foo=bar=baz'` expressions)
 - Parser: Support for multi-line comment syntax (`/* comments */`)
+- `SKI_REPL=1 node -r @dallaylaen/ski-interpreter` will now start a REPL with the `SKI` class available globally.
 
 ### Changed
 

package/README.md

@@ -1,5 +1,7 @@
 # Simple Kombinator Interpreter
 
+> **A humane tooling for inhuman logic**
+
 This package contains a
 [combinatory logic](https://en.wikipedia.org/wiki/Combinatory_logic)
 and [lambda calculus](https://en.wikipedia.org/wiki/Lambda_calculus)
@@ -49,11 +51,12 @@ back to human readable form.
 
 # Execution strategy
 
-Applications and native terms use normal strategy, i.e. the first term in the tree
+Applications and native terms use leftmost-outermost strategy, i.e. the first term in the tree
 that has enough arguments is executed and the step ends there.
 
-Lambda terms are lazy, i.e. the body is not touched until
-all free variables are bound.
+Lambda terms are lazy, i.e. the body is not touched whatsoever
+until all the free variables are bound.
+This is consistent with combinator behavior under LO order.
 
 # Playground
 
@@ -62,15 +65,13 @@ all free variables are bound.
   * all of the above features (except comparison and JS-native terms) in your browser
   * expressions have permalinks
   * can configure verbosity and execution speed
+  * switchable visual highlighting of redexes and outline of subexpressions
 
 * [Quests](https://dallaylaen.github.io/ski-interpreter/quest.html)
 
-This page contains small tasks of increasing complexity.
+This page contains small combinatory logic exercises of increasing (hopefully) diffuculty.
 Each task requires the user to build a combinator with specific properties.
-
-# CLI
-
-REPL comes with the package as [bin/ski.js](bin/ski.js).
+New combinators are unlocked as the user progresses.
 
 # Installation
 
@@ -78,6 +79,35 @@ REPL comes with the package as [bin/ski.js](bin/ski.js).
 npm install @dallaylaen/ski-interpreter
 ```
 
+# CLI
+
+[bin/ski.js](bin/ski.js) - also available as `npx ski` - contains several subcommands:
+
+## Subcommands
+
+* **`repl`** - Start an interactive REPL
+  * `--verbose` - Show all evaluation steps
+  * Built-in commands (type `!help` in REPL):
+    * `!ls` - List all defined terms
+    * `!help` - Show available commands
+
+* **`eval <expression>`** - Evaluate a single expression
+  * `--verbose` - Show all evaluation steps
+  * Example: `ski eval "S K K x"`
+
+* **`file <filepath>`** - Evaluate expressions from a file
+  * `--verbose` - Show all evaluation steps
+  * Example: `ski file script.ski`
+
+* **`quest-check <files...>`** - Validate quest definition files
+  * `--solution <file>` - Load solutions from a JSON file for verification
+  * Example: `ski quest-check quest1.json quest2.json --solution solutions.json`
+
+If no subcommand is provided, help is displayed.
+
+Running `SKI_REPL=1 node -r @dallaylaen/ski-interpreter/bin/ski.js`
+will start a node shell with the `SKI` class available as a global variable.
+
 # Usage
 
 ## A minimal example
@@ -146,8 +176,38 @@ const lambdaSteps = [...skiExpr.toLambda()];
 
 ## Fancy formatting
 
-The `format` methods of the `Expr` class supports
-a number of options, see [the source code](src/expr.js) for details.
+`expr.format(options?)` converts an expression to a string with fine-grained
+control over notation. Called without arguments it is equivalent to
+`expr.toString()`.
+
+```javascript
+const expr = ski.parse('S K K');
+
+expr.format()                        // 'S K K'  (default, terse)
+expr.format({ terse: false })        // 'S(K)(K)' — every argument gets parentheses
+expr.format({ html: true })          // HTML-safe: free vars wrapped in <var>,
+                                     // '->' becomes '-&gt;', fancyName used when set
+
+// Custom lambda notation
+expr.format({ lambda: ['', '=>', ''], terse: false })    // JavaScript style
+expr.format({ lambda: ['&lambda;', '.', ''] })           // math style
+expr.format({ lambda: ['(', '->', ')'], around: ['(', ')'], brackets: ['', ''] })
+                                                         // Lisp style, still parseable
+
+// Redex highlighting (e.g. for step-by-step HTML output)
+ski.parse('I x').format({ html: true, redex: ['<b>', '</b>'] })
+// '<b>I</b> <var>x</var>'
+
+// inventory: show listed aliases by name, expand everything else
+const { T } = ski.getTerms();
+expr.format({ inventory: { T } })    // keeps T as 'T', expands any other aliases
+```
+
+The `brackets`, `var`, `around`, and `redex` options each take a `[open, close]`
+pair of strings; `lambda` takes a `[prefix, separator, suffix]` triple.
+
+`expr.diag()` will instead output an indented expression tree (breadth-first)
+with class information and variables labeled for disambiguation.
 
 ## Variable scoping
 
@@ -183,6 +243,9 @@ expr.traverse(e => e.equals(SKI.I) ? SKI.S.apply(SKI.K, SKI.K) : null);
 // replaces all I's with S K K
 // here a returned `Expr` object replaces the subexpression,
 // whereas `null` means "leave it alone and descend if possible"
+
+expr.fold(0, (acc, e) => acc + (e.equals(SKI.K) ? acc+1 : acc));
+// counts the number of K's in the expression
 ```
 
 ## Test cases
@@ -207,12 +270,24 @@ q.check('K'); // fail
 q.check('K(K(y x))') // nope! the variable scopes won't match
 ```
 
-See [quest page data](docs/quest-data/) for more examples.
+See also [the quest guide](./docs/quest-intro.md) for more details on building your own quests or even interactive quest pages.
+
+# Package contents
+
+* `lib/ski-interpreter.cjs.js` - main entry point for Node.js;
+* `lib/ski-interpreter.esm.js` - main entry point for ES modules;
+* `lib/ski-interpreter.min.js` - minified version for browsers;
+* `lib/ski-quest.min.js` - script with the interpreter
+plus `QuestBox`, `QuestChapter`, and `QuestPage` classes
+for building interactive quest pages from JSON-encoded quest data;
+* `bin/ski.js` - a CLI REPL;
+* `types` - TypeScript type definitions.
 
 # Thanks
 
 * [@ivanaxe](https://github.com/ivanaxe) for luring me into [icfpc 2011](http://icfpc2011.blogspot.com/2011/06/task-description-contest-starts-now.html) where I was introduced to combinators.
 * [@akuklev](https://github.com/akuklev) for explaining functional programming to me so many times that I actually got some idea.
+* [One happy fellow](https://github.com/happyfellow-one) whose [riddle](https://blog.happyfellow.dev/a-riddle/) trolled me into writing an early `traverse` prototype.
 
 # Prior art and inspiration
 

package/bin/ski.js

@@ -1,121 +1,234 @@
 #!/usr/bin/env -S node --stack-size=20600
 
 const fs = require('node:fs/promises');
+const { Command } = require('commander');
 
 const { SKI } = require('../lib/ski-interpreter.cjs');
+const { Quest } = require('../src/quest.js');
+
+const program = new Command();
+
+program
+  .name('ski')
+  .description('Simple Kombinator Interpreter - a combinatory logic & lambda calculus parser and interpreter')
+  .version('2.2.1');
+
+// REPL subcommand
+program
+  .command('repl')
+  .description('Start interactive REPL')
+  .option('--verbose', 'Show all evaluation steps')
+  .action((options) => {
+    startRepl(options.verbose);
+  });
 
-const [myname, options, positional] = parseArgs(process.argv);
+// Eval subcommand
+program
+  .command('eval <expression>')
+  .description('Evaluate a single expression')
+  .option('--verbose', 'Show all evaluation steps')
+  .action((expression, options) => {
+    evaluateExpression(expression, options.verbose);
+  });
 
-if (options.help) {
-  console.error(myname + ': usage: ' + myname + '[-q | -v ] -e <expression>');
-  process.exit(1);
-}
+// File subcommand
+program
+  .command('file <filepath>')
+  .description('Evaluate expressions from a file')
+  .option('--verbose', 'Show all evaluation steps')
+  .action((filepath, options) => {
+    evaluateFile(filepath, options.verbose);
+  });
 
-if ((typeof options.e === 'string' && positional.length) > 0 || positional.length > 1) {
-  console.error(myname + ': either -e <expr> or exactly one filename must be given');
-  process.exit(1);
-}
+// Quest-check subcommand
+program
+  .command('quest-check <files...>')
+  .description('Check quest files for validity')
+  .option('--solution <file>', 'Load solutions from file')
+  .action((files, options) => {
+    questCheck(files, options.solution);
+  });
+
+// Default to REPL if no command provided
+program
+  .showHelpAfterError(true)
+  .parse(process.argv);
 
-const ski = new SKI();
+if (!process.argv.slice(2).length)
+  startRepl(false);
 
-if (options.e === undefined && !positional.length) {
-  // interactive console
+function startRepl (verbose) {
   const readline = require('readline');
+  const ski = new SKI();
+
   const rl = readline.createInterface({
     input:    process.stdin,
     output:   process.stdout,
     prompt:   '> ',
     terminal: true,
   });
-  if (!options.q)
-    console.log('Welcome to SKI interactive shell. Known combinators: ' + ski.showRestrict());
+
+  console.log('Welcome to SKI interactive shell. Known combinators: ' + ski.showRestrict());
+
   rl.on('line', str => {
-    const flag = str.match(/^\s*([-+])([qvt])\s*$/);
-    if (flag)
-      options[flag[2]] = flag[1] === '+';
-    else {
-      runLine(err => {
-        console.log('' + err)
-      })(str);
+    if (str.match(/\S/)) {
+      if (str.startsWith('!'))
+        handleCommand(str, ski);
+      else {
+        processLine(str, ski, verbose, err => {
+          console.log('' + err);
+        });
+      }
     }
     rl.prompt();
   });
+
   rl.once('close', () => {
-    if (!options.q)
-      console.log('Bye, and may your bird fly high!');
-    process.exit(0)
+    console.log('Bye, and may thy bird fly high!');
+    process.exit(0);
   });
+
   rl.prompt();
-} else {
-  const prom = positional.length > 0
-    ? fs.readFile(positional[0], 'utf8')
-    : Promise.resolve(options.e);
+}
 
-  prom.then(runLine(err => { console.error('' + err); process.exit(3) })).catch(err => {
-    console.error(myname + ': ' + err);
-    process.exit(2);
+function evaluateExpression (expression, verbose) {
+  const ski = new SKI();
+  processLine(expression, ski, verbose, err => {
+    console.error('' + err);
+    process.exit(3);
   });
 }
 
-function runLine (onErr) {
-  return function (source) {
-    if (!source.match(/\S/))
-      return 0; // nothing to see here
-    try {
-      const expr = ski.parse(source);
-
-      const t0 = new Date();
-      for (const state of expr.walk()) {
-        if (state.final && !options.q)
-          console.log(`// ${state.steps} step(s) in ${new Date() - t0}ms`);
-        if (options.v || state.final)
-          console.log('' + state.expr.format({ terse: options.t }));
-        if (state.final && expr instanceof SKI.classes.Alias)
-          ski.add(expr.name, state.expr);
-      }
-      return 0;
-    } catch (err) {
-      onErr(err);
-      return 1;
-    }
-  }
+function evaluateFile (filepath, verbose) {
+  const ski = new SKI();
+  fs.readFile(filepath, 'utf8')
+    .then(source => {
+      processLine(source, ski, verbose, err => {
+        console.error('' + err);
+        process.exit(3);
+      });
+    })
+    .catch(err => {
+      console.error('ski: ' + err);
+      process.exit(2);
+    });
 }
 
-function parseArgs (argv) {
-  const [_, script, ...list] = argv;
-
-  const todo = {
-    '--':     () => { pos.push(...list) },
-    '--help': () => { opt.help = true },
-    '-q':     () => { opt.q = true },
-    '-v':     () => { opt.v = true },
-    '-c':     () => { opt.t = false },
-    '-t':     () => { opt.t = true },
-    '-e':     () => {
-      if (list.length < 1)
-        throw new Error('option -e requires an argument');
-      opt.e = list.shift();
-    },
-  };
+function processLine (source, ski, verbose, onErr) {
+  if (!source.match(/\S/))
+    return; // nothing to see here
+
+  try {
+    const expr = ski.parse(source);
+    const t0 = new Date();
+    const isAlias = expr instanceof SKI.classes.Alias;
+    const aliasName = isAlias ? expr.name : null;
 
-  // TODO replace with a relevant dependency
-  const pos = [];
-  const opt = {};
+    for (const state of expr.walk()) {
+      if (state.final)
+        console.log(`// ${state.steps} step(s) in ${new Date() - t0}ms`);
 
-  while (list.length > 0) {
-    const next = list.shift();
+      if (verbose || state.final)
+        console.log('' + state.expr.format());
 
-    if (!next.match(/^-/)) {
-      pos.push(next);
-      continue;
+      if (state.final && isAlias && aliasName)
+        ski.add(aliasName, state.expr);
     }
+  } catch (err) {
+    onErr(err);
+  }
+}
 
-    const action = todo[next];
-    if (typeof action !== 'function')
-      throw new Error('Unknown option ' + next + '; see ski.js --help');
+async function questCheck (files, solutionFile) {
+  try {
+    // Load solutions if provided
+    let solutions = null;
+    if (solutionFile) {
+      const data = await fs.readFile(solutionFile, 'utf8');
+      solutions = JSON.parse(data);
+    }
+
+    // Load and verify each quest file
+    let hasErrors = false;
+    const seenIds = new Set();
+
+    for (const file of files) {
+      try {
+        const data = await fs.readFile(file, 'utf8');
+        const questData = JSON.parse(data);
+
+        // Handle both single quest objects and quest groups
+        const entry = Array.isArray(questData) ? { content: questData } : questData;
+
+        try {
+          const group = new Quest.Group(entry);
+
+          // Verify the group
+          const findings = group.verify({
+            date: true,
+            solutions,
+            seen: seenIds
+          });
+
+          // Check for errors
+          const hasGroupErrors = Object.keys(findings).some(key => {
+            if (key === 'content') {
+              const contentErrors = findings.content?.filter(item => item !== null);
+              return contentErrors && contentErrors.length > 0;
+            }
+            return findings[key];
+          });
+
+          if (hasGroupErrors) {
+            hasErrors = true;
+            console.error(`Error in ${file}:`);
+            console.error(JSON.stringify(findings, null, 2));
+          } else
+            console.log(`✓ ${file}`);
+        } catch (err) {
+          hasErrors = true;
+          console.error(`Error parsing quest group in ${file}:`, err.message);
+        }
+      } catch (err) {
+        hasErrors = true;
+        console.error(`Error reading file ${file}:`, err.message);
+      }
+    }
 
-    action();
+    // Exit with appropriate code
+    process.exit(hasErrors ? 1 : 0);
+  } catch (err) {
+    console.error('Error in quest-check:', err.message);
+    process.exit(2);
   }
+}
+
+function handleCommand (input, ski) {
+  const parts = input.trim().split(/\s+/);
+  const cmd = parts[0];
+
+  const dispatch = {
+    '!ls': () => {
+      const terms = ski.getTerms();
+      const list = Object.keys(terms).sort();
+      for (const name of list) {
+        const term = terms[name];
+        if (term instanceof SKI.classes.Alias)
+          console.log(`  ${name} = ${term.impl}`);
+        else if (term instanceof SKI.classes.Native)
+          console.log(`  ${name} ${term.props?.expr ?? '(native)'}`);
+      }
+    },
+    '!help': () => {
+      console.log('Available commands:');
+      console.log('  !ls    - List term inventory');
+      console.log('  !help  - Show this help message');
+    },
+    '': () => {
+      console.log(`Unknown command: ${cmd}`);
+      console.log('Type !help for available commands.');
+    }
+  };
 
-  return [script, opt, pos];
+  (dispatch[cmd] || dispatch[''])(...parts.slice(1));
 }