@dallaylaen/ski-interpreter 2.2.0 → 2.2.1

package/CHANGELOG.md

@@ -5,6 +5,19 @@ 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.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 +33,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

@@ -68,16 +68,19 @@ all free variables are bound.
 This page contains small tasks of increasing complexity.
 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).
-
 # Installation
 
 ```bash
 npm install @dallaylaen/ski-interpreter
 ```
 
+# CLI
+
+REPL comes with the package as [bin/ski.js](bin/ski.js).
+
+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
@@ -149,6 +152,10 @@ const lambdaSteps = [...skiExpr.toLambda()];
 The `format` methods of the `Expr` class supports
 a number of options, see [the source code](src/expr.js) for details.
 
+`expr.diag()` will instead output indented
+expression tree (breadth-first) with class information
+and variables labeled for disambiguation.
+
 ## Variable scoping
 
 By default, parsed free variables are global and equal to any other variable with the same name.
@@ -183,6 +190,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
@@ -209,6 +219,17 @@ q.check('K(K(y x))') // nope! the variable scopes won't match
 
 See [quest page data](docs/quest-data/) for more examples.
 
+# 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.

package/lib/ski-interpreter.cjs.js

@@ -59,24 +59,34 @@ var require_internal = __commonJS({
       }
       return out;
     }
-    var ActionWrapper = class {
+    var TraverseControl = class {
       /**
+       * @desc A wrapper for values returned by fold/traverse callbacks
+       *       which instructs the traversal to alter its behavior while
+       *       retaining the value in question.
+       *
+       *       This class is instantiated internally be `SKI.control.*` functions,
+       *       and is not intended to be used directly by client code.
+       *
        * @template T
        * @param {T} value
-       * @param {string} action
+       * @param {function(T): TraverseControl<T>} decoration
        */
-      constructor(value, action) {
+      constructor(value, decoration) {
         this.value = value;
-        this.action = action;
+        this.decoration = decoration;
       }
     };
     function unwrap(value) {
-      if (value instanceof ActionWrapper)
-        return [value.value ?? void 0, value.action];
+      if (value instanceof TraverseControl)
+        return [value.value ?? void 0, value.decoration];
       return [value ?? void 0, void 0];
     }
-    function prepareWrapper(action) {
-      return (value) => new ActionWrapper(value, action);
+    function prepareWrapper(label) {
+      const fun = (value) => new TraverseControl(value, fun);
+      fun.label = label;
+      fun.toString = () => "TraverseControl::" + label;
+      return fun;
     }
     module2.exports = { Tokenizer, restrict, unwrap, prepareWrapper };
   }
@@ -94,6 +104,7 @@ var require_expr = __commonJS({
     var control = {
       descend: prepareWrapper("descend"),
       prune: prepareWrapper("prune"),
+      redo: prepareWrapper("redo"),
       stop: prepareWrapper("stop")
     };
     var Expr = class _Expr {
@@ -109,7 +120,7 @@ var require_expr = __commonJS({
        *    env?: { [key: string]: Expr },
        *    src?: string,
        *    parser: object,
-       *  }} [context] // TODO proper type
+       *  }} [context]
        */
       constructor() {
         if (new.target === _Expr)
@@ -137,15 +148,21 @@ var require_expr = __commonJS({
             return e.impl.expand();
         }) ?? this;
       }
+      /**
+       * @desc Returns true if the expression contains only free variables and applications, false otherwise.
+       * @returns {boolean}
+       */
       freeOnly() {
         return !this.any((e) => !(e instanceof FreeVar || e instanceof App));
       }
       /**
        * @desc Traverse the expression tree, applying change() to each node.
        *       If change() returns an Expr, the node is replaced with that value.
-       *       Otherwise, the node is left descended further (if applicable)
+       *       Otherwise, the node is descended further (if applicable)
        *       or left unchanged.
        *
+       *       The traversal order is leftmost-outermost (LO), i.e. the same order as reduction steps are taken.
+       *
        *       Returns null if no changes were made, or the new expression otherwise.
        *
        * @param {(e:Expr) => (Expr|null)} change
@@ -179,18 +196,25 @@ var require_expr = __commonJS({
        * @experimental
        * @template T
        * @param {T} initial
-       * @param {(acc: T, expr: Expr) => ActionWrapper<T>} combine
+       * @param {(acc: T, expr: Expr) => TraverseValue<T>} combine
        * @returns {T}
        */
       fold(initial, combine) {
         const [value, _] = unwrap(this._fold(initial, combine));
         return value ?? initial;
       }
+      /**
+       * @template T
+       * @param {T} initial
+       * @param {(acc: T, expr: Expr) => TraverseValue<T>} combine
+       * @returns {TraverseValue<T>}
+       * @private
+       */
       _fold(initial, combine) {
         return combine(initial, this);
       }
       /**
-       * @desc rough estimate of the complexity of the term
+       * @desc rough estimate of the term's complexity
        * @return {number}
        */
       weight() {
@@ -232,7 +256,15 @@ var require_expr = __commonJS({
        * @param {{max: number, maxArgs: number, index: number}} options
        * @param {FreeVar[]} preArgs
        * @param {number} steps
-       * @returns {{normal: boolean, steps: number}|{normal: boolean, steps: number}|{normal: boolean, steps: number, expr: Lambda|*, arity?: *, skip?: Set<any>, dup?: Set<any>, duplicate, discard, proper: boolean}|*|{normal: boolean, steps: number}}
+       * @returns {{
+       *    normal: boolean,
+       *    steps: number,
+       *    expr?: Expr,
+       *    arity?: number,
+       *    skip?: Set<number>,
+       *    dup?: Set<number>,
+       *    duplicate, discard, proper: boolean
+       * }
        * @private
        */
       _infer(options, preArgs = [], steps = 0) {
@@ -289,7 +321,7 @@ var require_expr = __commonJS({
        *   latin?: number,
        * }} options
        * @param {number} [maxWeight] - maximum allowed weight of terms in the sequence
-       * @return {IterableIterator<{expr: Expr, steps: number?, comment: string?}>}
+       * @return {IterableIterator<{expr: Expr, steps?: number, comment?: string}>}
        */
       *toLambda(options = {}) {
         const expr = this.traverse((e) => {
@@ -382,7 +414,7 @@ var require_expr = __commonJS({
        * @desc Run uninterrupted sequence of step() applications
        *       until the expression is irreducible, or max number of steps is reached.
        *       Default number of steps = 1000.
-       * @param {{max: number?, steps: number?, throw: boolean?}|Expr} [opt]
+       * @param {{max?: number, steps?: number, throw?: boolean}|Expr} [opt]
        * @param {Expr} args
        * @return {{expr: Expr, steps: number, final: boolean}}
        */
@@ -411,7 +443,7 @@ var require_expr = __commonJS({
       /**
        * Execute step() while possible, yielding a brief description of events after each step.
        * Mnemonics: like run() but slower.
-       * @param {{max: number?}} options
+       * @param {{max?: number}} options
        * @return {IterableIterator<{final: boolean, expr: Expr, steps: number}>}
        */
       *walk(options = {}) {
@@ -586,6 +618,42 @@ var require_expr = __commonJS({
       _format(options, nargs) {
         throw new Error("No _format() method defined in class " + this.constructor.name);
       }
+      /**
+       * @desc Returns a string representation of the expression tree, with indentation to show structure.
+       *
+       *       Applications are flattened to avoid excessive nesting.
+       *       Variables include ids to distinguish different instances of the same variable name.
+       *
+       *       May be useful for debugging.
+       *
+       * @returns {string}
+       *
+       * @example
+       * > console.log(ski.parse('C 5 x (x->x x)').diag())
+       * App:
+       *   Native: C
+       *   Church: 5
+       *   FreeVar: x[53]
+       *   Lambda (x[54]):
+       *     App:
+       *       FreeVar: x[54]
+       *       FreeVar: x[54]
+       */
+      diag() {
+        const rec = (e, indent) => {
+          if (e instanceof App)
+            return [indent + "App:", ...e.unroll().flatMap((s) => rec(s, indent + "  "))];
+          if (e instanceof Lambda)
+            return [`${indent}Lambda (${e.arg}[${e.arg.id}]):`, ...rec(e.impl, indent + "  ")];
+          if (e instanceof Alias)
+            return [`Alias (${e.name}):`, ...rec(e.impl, indent + "  ")];
+          if (e instanceof FreeVar)
+            return [`${indent}FreeVar: ${e.name}[${e.id}]`];
+          return [`${indent}${e.constructor.name}: ${e}`];
+        };
+        const out = rec(this, "");
+        return out.join("\n");
+      }
       /**
        * @desc Convert the expression to a JSON-serializable format.
        * @returns {string}
@@ -662,15 +730,15 @@ var require_expr = __commonJS({
       }
       _fold(initial, combine) {
         const [value = initial, action = "descend"] = unwrap(combine(initial, this));
-        if (action === "prune")
+        if (action === control.prune)
           return value;
-        if (action === "stop")
+        if (action === control.stop)
           return control.stop(value);
         const [fValue = value, fAction = "descend"] = unwrap(this.fun._fold(value, combine));
-        if (fAction === "stop")
+        if (fAction === control.stop)
           return control.stop(fValue);
         const [aValue = fValue, aAction = "descend"] = unwrap(this.arg._fold(fValue, combine));
-        if (aAction === "stop")
+        if (aAction === control.stop)
           return control.stop(aValue);
         return aValue;
       }
@@ -714,10 +782,6 @@ var require_expr = __commonJS({
       unroll() {
         return [...this.fun.unroll(), this.arg];
       }
-      /**
-       * @desc Convert the expression to SKI combinatory logic
-       * @return {Expr}
-       */
       _rski(options) {
         if (options.steps >= options.max)
           return this;
@@ -915,12 +979,12 @@ var require_expr = __commonJS({
       }
       _fold(initial, combine) {
         const [value = initial, action = "descend"] = unwrap(combine(initial, this));
-        if (action === "prune")
+        if (action === control.prune)
           return value;
-        if (action === "stop")
+        if (action === control.stop)
           return control.stop(value);
         const [iValue, iAction] = unwrap(this.impl._fold(value, combine));
-        if (iAction === "stop")
+        if (iAction === control.stop)
           return control.stop(iValue);
         return iValue ?? value;
       }
@@ -1016,7 +1080,7 @@ var require_expr = __commonJS({
        *
        * @param {String} name
        * @param {Expr} impl
-       * @param {{canonize: boolean?, max: number?, maxArgs: number?, note: string?, terminal: boolean?}} [options]
+       * @param {{canonize?: boolean, max?: number, maxArgs?: number, note?: string, terminal?: boolean}} [options]
        */
       constructor(name, impl, options = {}) {
         super(name);
@@ -1032,6 +1096,15 @@ var require_expr = __commonJS({
         this.canonical = guess.expr;
         this.invoke = waitn(impl, this.arity);
       }
+      /**
+       * @property {boolean} [outdated] - whether the alias is outdated
+       *     and should be replaced with its definition when encountered.
+       * @property {boolean} [terminal] - whether the alias should behave like a standalone term
+       *     // TODO better name?
+       * @property {boolean} [proper] - whether the alias is a proper combinator (i.e. contains no free variables or constants)
+       * @property {number} [arity] - the number of arguments the alias waits for before expanding
+       * @property {Expr} [canonical] - equivalent lambda term.
+       */
       weight() {
         return this.terminal ? 1 : this.impl.weight();
       }
@@ -1042,13 +1115,13 @@ var require_expr = __commonJS({
         return predicate(this) || this.impl.any(predicate);
       }
       _fold(initial, combine) {
-        const [value = initial, action = "descend"] = unwrap(combine(initial, this));
-        if (action === "prune")
+        const [value = initial, action] = unwrap(combine(initial, this));
+        if (action === control.prune)
           return value;
-        if (action === "stop")
+        if (action === control.stop)
           return control.stop(value);
         const [iValue, iAction] = unwrap(this.impl._fold(value, combine));
-        if (iAction === "stop")
+        if (iAction === control.stop)
           return control.stop(iValue);
         return iValue ?? value;
       }
@@ -1060,9 +1133,10 @@ var require_expr = __commonJS({
       _infer(options, preArgs = [], steps = 0) {
         return this.impl._infer(options, preArgs, steps);
       }
+      // DO NOT REMOVE TYPE or tsc chokes with
+      //       TS2527: The inferred type of 'Alias' references an inaccessible 'this' type.
       /**
-       *
-       * @return {{expr: Expr, steps: number}}
+       * @return {{expr: Expr, steps: number, changed: boolean}}
        */
       step() {
         if (this.arity > 0)
@@ -1337,6 +1411,13 @@ var require_parser = __commonJS({
         this.allow.add(term.name);
         return this;
       }
+      /**
+       * @desc Internal helper for add() that creates an Alias or Native term from the given arguments.
+       * @param {Alias|string} term
+       * @param {string|Expr|function(Expr):Partial} impl
+       * @returns {Native|Alias}
+       * @private
+       */
       _named(term, impl) {
         if (term instanceof Alias)
           return new Alias(term.name, term.impl, { canonize: true });
@@ -1352,6 +1433,16 @@ var require_parser = __commonJS({
           return new Native(term, impl);
         throw new Error("add(): impl must be an Expr, a string, or a function with a signature Expr => ... => Expr");
       }
+      /**
+       * @desc Declare a new term if it is not known, otherwise just allow it.
+       *       Currently only used by quests.
+       *       Use with caution, this function may change its signature, behavior, or even be removed in the future.
+       *
+       * @experimental
+       * @param {string|Alias} name
+       * @param {string|Expr|function(Expr):Partial} impl
+       * @returns {SKI}
+       */
       maybeAdd(name, impl) {
         if (this.known[name])
           this.allow.add(name);
@@ -1363,7 +1454,7 @@ var require_parser = __commonJS({
        * @desc Declare and remove multiple terms at once
        *       term=impl adds term
        *       term= removes term
-       * @param {string[]]} list
+       * @param {string[]} list
        * @return {SKI} chainable
        */
       bulkAdd(list) {
@@ -1484,11 +1575,11 @@ var require_parser = __commonJS({
         return out;
       }
       /**
-       *
+       * @template T
        * @param {string} source
        * @param {Object} [options]
        * @param {{[keys: string]: Expr}} [options.env]
-       * @param {any} [options.scope]
+       * @param {T} [options.scope]
        * @param {boolean} [options.numbers]
        * @param {boolean} [options.lambdas]
        * @param {string} [options.allow]
@@ -1524,12 +1615,14 @@ var require_parser = __commonJS({
         return expr;
       }
       /**
-       *
+       * @desc Parse a single line of source code, without splitting it into declarations.
+       *       Internal, always use parse() instead.
+       * @template T
        * @param {String} source S(KI)I
        * @param {{[keys: string]: Expr}} env
        * @param {Object} [options]
        * @param {{[keys: string]: Expr}} [options.env] - unused, see 'env' argument
-       * @param {any} [options.scope]
+       * @param {T} [options.scope]
        * @param {boolean} [options.numbers]
        * @param {boolean} [options.lambdas]
        * @param {string} [options.allow]
@@ -1593,12 +1686,12 @@ var require_parser = __commonJS({
         };
       }
     };
-    SKI2.vars = function(context = {}) {
+    SKI2.vars = function(scope = {}) {
       const cache = {};
       return new Proxy({}, {
         get: (target, name) => {
           if (!(name in cache))
-            cache[name] = new FreeVar(name, context);
+            cache[name] = new FreeVar(name, scope);
           return cache[name];
         }
       });
@@ -1620,40 +1713,23 @@ var require_quest = __commonJS({
     var { Expr, FreeVar, Alias, Lambda } = SKI2.classes;
     var Quest2 = class {
       /**
-         * @description A combinator problem with a set of test cases for the proposed solution.
-         * @param {{
-         *    input: InputSpec | InputSpec[],
-         *    cases: TestCase[],
-         *
-         *    // the rest is optional
-      
-         *    allow?: string,
-         *    numbers?: boolean,
-         *    env?: string[],
-         *    engine?: SKI,
-         *    engineFull?: SKI,
-         *
-         *    // metadata, also any fields not listed here will go to quest.meta.???
-         *    id?: string|number,
-         *    name?: string,
-         *    intro?: string|string[], // multiple strings will be concatenated with spaces
-         * }} options
-         *
-         * @example const quest = new Quest({
-         *    input: 'identity',
-         *    cases: [
-         *      ['identity x', 'x'],
-         *    ],
-         *    allow: 'SK',
-         *    intro: 'Find a combinator that behaves like the identity function.',
-         * });
-         * quest.check('S K K'); // { pass: true, details: [...], ... }
-         * quest.check('K S');   // { pass: false, details: [...], ... }
-         * quest.check('K x');   // fail! internal variable x is not equal to free variable x,
-         *                       //     despite having the same name.
-         * quest.check('I');     // fail! I not in the allowed list.
-         */
-      constructor(options = {}) {
+       * @description A combinator problem with a set of test cases for the proposed solution.
+       * @param {QuestSpec} options
+       * @example const quest = new Quest({
+       *    input: 'identity',
+       *    cases: [
+       *      ['identity x', 'x'],
+       *    ],
+       *    allow: 'SK',
+       *    intro: 'Find a combinator that behaves like the identity function.',
+       * });
+       * quest.check('S K K'); // { pass: true, details: [...], ... }
+       * quest.check('K S');   // { pass: false, details: [...], ... }
+       * quest.check('K x');   // fail! internal variable x is not equal to free variable x,
+       *                       //     despite having the same name.
+       * quest.check('I');     // fail! I not in the allowed list.
+       */
+      constructor(options) {
         const { input, cases, allow, numbers, lambdas, engine, engineFull, ...meta } = options;
         const env = options.env ?? options.vars;
         this.engine = engine ?? new SKI2();
@@ -1746,7 +1822,11 @@ var require_quest = __commonJS({
             numbers: spec.numbers ?? this.restrict.numbers,
             lambdas: spec.lambdas ?? this.restrict.lambdas
           });
-          weight += impl.weight();
+          const arsenal = { ...this.engine.getTerms(), ...jar };
+          weight += impl.fold(0, (a, e) => {
+            if (e instanceof SKI2.classes.Named && arsenal[e.name] === e)
+              return SKI2.control.prune(a + 1);
+          });
           const expr = impl instanceof FreeVar ? impl : new Alias(spec.fancy ?? spec.name, impl, { terminal: true, canonize: false });
           jar[spec.name] = expr;
           prepared.push(expr);
@@ -1819,10 +1899,10 @@ var require_quest = __commonJS({
       /**
        * @param {FreeVar[]} input
        * @param {{
-       *    max: number?,
-       *    note: string?,
-       *    env: {string: Expr}?,
-       *    engine: SKI?
+       *    max?: number,
+       *    note?: string,
+       *    env?: {string: Expr},
+       *    engine?: SKI
        * }} options
        * @param {[e1: string, e2: string]} terms
        */