@dallaylaen/ski-interpreter 2.7.0 → 2.8.1

package/CHANGELOG.md

@@ -5,6 +5,45 @@ 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.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
+
+- `parse()` no longer auto-inlines aliases unless they are redefined; known aliases are preserved by name.
+- `toposort()` signature changed to use options object instead of positional parameters.
+
+### Added
+
+- `Expr.declare()` — emits a complete, round-trippable declaration of an expression including its dependencies.
+- `parse(..., { canonize: true })` — calculates properties of intermediate aliases during parsing.
+- `annotate()` — public rename of the semi-official `_setup()` method, with added documentation.
+- Quest UI: "reveal solution" button added.
+- Quest UI: raw user input is now saved when a quest is solved.
+- CLI (`bin/ski.js`): outputs full declarations instead of bare expressions.
+
+### Changed
+
+- `toJSON()` now outputs back-parsable declaration instead of just string.
+- `toposort` moved into `expr.ts`.
+- `extras.ts` delegates to `Expr.declare()` instead of re-implementing the logic.
+- Internal type `{ ... }` renamed to `Record<string, Named>` for clarity.
+
+### Fixed
+
+- `Expr.toLambda` was incorrectly preparing term (#24).
+
 ## [2.7.0] - 2026-04-03
 
 ### 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...>')
@@ -166,20 +183,17 @@ function processLine (source, ski, onErr) {
     return; // nothing to see here
 
   try {
-    const expr = ski.parse(source);
+    const expr = ski.parse(source, { canonize: true });
+    if (expr instanceof SKI.classes.Alias)
+      ski.add(expr);
     const t0 = new Date();
-    const isAlias = expr instanceof SKI.classes.Alias;
-    const aliasName = isAlias ? expr.name : null;
 
     for (const state of expr.walk(runOptions)) {
-      if (state.final)
+      if (state.final) {
         console.log(`// ${state.steps} step(s) in ${new Date() - t0}ms`);
-
-      if (verbose || state.final)
-        console.log(state.expr.format(format));
-
-      if (state.final && isAlias && aliasName)
-        ski.add(aliasName, state.expr);
+        console.log(state.expr.declare({ ...format, inventory: ski.getTerms() }));
+      } else if (verbose)
+        console.log(state.expr.format(format) + ';');
     }
   } catch (err) {
     onErr(err);

package/lib/ski-interpreter.cjs.js

@@ -111,10 +111,13 @@ var control = {
 var native = {};
 var Expr = class _Expr {
   /**
+   * Add metadata based on user-supplied values and/or the properties of the term itself.
    *
-   *  Define properties of the term based on user supplied options and/or inference results.
-   *       Typically useful for declaring Native and Alias terms.
-   * @protected
+   * Typically applied to named terms shortly after instantiation.
+   *
+   * Experimental. Name and meaning may change in the future.
+   *
+   * @experimental
    * @param {Object} options
    * @param {string} [options.note] - a brief description what the term does
    * @param {number} [options.arity] - number of arguments the term is waiting for (if known)
@@ -124,7 +127,7 @@ var Expr = class _Expr {
    * @param {number} [options.maxArgs] - maximum number of arguments for inference, if canonize is true
    * @return {this}
    */
-  _setup(options = {}) {
+  annotate(options = {}) {
     if (options.fancy !== void 0 && this instanceof Named)
       this.fancyName = options.fancy;
     if (options.note !== void 0)
@@ -354,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 });
@@ -428,7 +429,9 @@ var Expr = class _Expr {
    */
   *toLambda(options = {}) {
     let expr = this.traverse((e) => {
-      if (e instanceof FreeVar || e instanceof App || e instanceof Lambda || e instanceof Alias)
+      if (e instanceof FreeVar)
+        return e;
+      if (e instanceof App || e instanceof Lambda || e instanceof Alias)
         return null;
       const guess = e.infer({ max: options.max, maxArgs: options.maxArgs });
       if (!guess.normal)
@@ -794,16 +797,26 @@ var Expr = class _Expr {
   diag(indent = "") {
     return indent + this.constructor.name + ": " + this;
   }
+  declare(options = {}) {
+    const { declaration: d = ["", "=", "; "], ...format } = options;
+    const res = toposort({ list: [this], env: format.inventory });
+    return res.list.map((s) => {
+      if (s instanceof Alias)
+        return d[0] + s.name + d[1] + s.impl.format({ ...format, inventory: res.env });
+      if (s instanceof FreeVar)
+        return d[0] + s.name + d[1];
+      return s.format({ ...format, inventory: res.env });
+    }).join(d[2]);
+  }
   /**
    * Convert the expression to a JSON-serializable format.
    * Sadly the format is not yet finalized and may change in the future.
    *
    * @experimental
-   * @returns {string}
    * @sealed
    */
   toJSON() {
-    return this.format();
+    return this.declare();
   }
 };
 var App = class _App extends Expr {
@@ -970,7 +983,7 @@ var Native = class extends Named {
   constructor(name, impl, opt = {}) {
     super(name);
     this.invoke = impl;
-    this._setup({ canonize: true, ...opt });
+    this.annotate({ canonize: true, ...opt });
   }
 };
 var Lambda = class _Lambda extends Expr {
@@ -1077,7 +1090,7 @@ var Alias = class extends Named {
     if (!(impl instanceof Expr))
       throw new Error("Attempt to create an alias for a non-expression: " + impl);
     this.impl = impl;
-    this._setup(options);
+    this.annotate(options);
     this.invoke = waitn(options.inline ? 0 : this.arity ?? 0)(impl);
     this.size = impl.size;
     if (options.inline)
@@ -1215,40 +1228,43 @@ function maybeLambda(args, expr, caps) {
 function nthvar(n) {
   return new FreeVar("abcdefgh"[n] ?? "x" + n);
 }
-var classes = { Expr, App, Named, FreeVar, Native, Lambda, Church, Alias };
-
-// src/toposort.ts
-function toposort(list, env) {
-  if (list instanceof Expr)
-    list = [list];
-  if (env) {
-    if (!list)
-      list = Object.keys(env).sort().map((k) => env[k]);
-  } else {
-    if (!list)
-      return { list: [], env: {} };
-    env = {};
-    for (const item of list) {
-      if (!(item instanceof Named))
-        continue;
-      if (env[item.name])
-        throw new Error("duplicate name " + item);
-      env[item.name] = item;
+function toposort(options) {
+  if (typeof options !== "object" || options === null || Array.isArray(options) || options instanceof Expr)
+    throw new Error("positional arguments to toposort are deprecated, use { list: ..., env: ... } instead");
+  const allow = options.allow ? { ...options.allow } : null;
+  const env = { ...options.env ?? {} };
+  const list = options.list instanceof Expr ? [options.list] : options.list ?? [];
+  if (allow) {
+    for (const term of list) {
+      if (term instanceof Named)
+        allow[term.name] = term;
     }
   }
+  for (const term of list) {
+    if (term instanceof Named && env[term.name] === term)
+      delete env[term.name];
+  }
   const out = [];
-  const seen = /* @__PURE__ */ new Set();
+  const seen = new Set(Object.values(env));
   const rec = (term) => {
     if (seen.has(term))
       return;
-    term.fold(false, (acc, e) => {
-      if (e !== term && e instanceof Named && env[e.name] === e) {
+    term.fold(void 0, (_, e) => {
+      if (!(e instanceof Named))
+        return;
+      if (allow && allow[e.name] !== e)
+        return;
+      if (!allow && e instanceof Alias && e.inline)
+        return;
+      if (e !== term) {
         rec(e);
-        return control.prune(false);
+        return control.prune();
       }
     });
     out.push(term);
     seen.add(term);
+    if (term instanceof Named)
+      env[term.name] ||= term;
   };
   for (const term of list)
     rec(term);
@@ -1257,6 +1273,7 @@ function toposort(list, env) {
     env
   };
 }
+var classes = { Expr, App, Named, FreeVar, Native, Lambda, Church, Alias };
 
 // src/parser.ts
 var Empty = class extends Expr {
@@ -1359,7 +1376,7 @@ var Parser = class {
   add(term, impl, options) {
     const named = this._named(term, impl);
     const opts = typeof options === "string" ? { note: options, canonize: false } : options ?? {};
-    named._setup({ canonize: this.annotate, ...opts });
+    named.annotate({ canonize: this.annotate, ...opts });
     const old = this.known[named.name];
     if (old instanceof Alias)
       old.makeInline();
@@ -1504,7 +1521,7 @@ var Parser = class {
       env[temp.name] = temp;
       delete env[name];
     }
-    const list = toposort(void 0, env).list;
+    const list = toposort({ list: Object.values(env), allow: {} }).list;
     const detour = /* @__PURE__ */ new Map();
     if (Object.keys(needDetour).length) {
       const rework = (expr) => {
@@ -1531,14 +1548,15 @@ var Parser = class {
     return out;
   }
   /**
-   * @template T
    * @param {string} source
    * @param {Object} [options]
-   * @param {{[keys: string]: Expr}} [options.env]
-   * @param {T} [options.scope]
-   * @param {boolean} [options.numbers]
-   * @param {boolean} [options.lambdas]
-   * @param {string} [options.allow]
+   * @param [options.env] - additional
+   * @param [options.scope] - assign this scope to unknown free variables
+   * @param {boolean} [options.numbers] - whether numbers are allowed
+   * @param {boolean} [options.lambdas] - whether lambdas are allowed
+   * @param {string} [options.allow] - restrict known terms
+   * @param [options.canonize] - whether to calculate canonical form, arity, and properties
+   *                             of intermediate aliases
    * @return {Expr}
    */
   parse(source, options = {}) {
@@ -1548,18 +1566,19 @@ var Parser = class {
     const jar = { ...options.env };
     let expr = new Empty();
     for (const item of lines) {
-      if (expr instanceof Alias)
-        expr.makeInline();
-      const def = item.match(/^([A-Z]|[a-z][a-z_0-9]*)\s*=(.*)$/s);
-      if (def && def[2] === "")
-        expr = new FreeVar(def[1], options.scope ?? FreeVar.global);
+      const [_, name, def] = item.match(/^([A-Z]|[a-z][a-z_0-9]*)\s*=(.*)$/s) || [];
+      if (name !== void 0) {
+        if (jar[name] instanceof Alias && jar[name] !== options.env?.[name]) {
+          jar[name].makeInline();
+        }
+        delete jar[name];
+      }
+      if (def === "")
+        expr = new FreeVar(name, options.scope ?? FreeVar.global);
       else
         expr = this.parseLine(item, jar, options);
-      if (def) {
-        if (jar[def[1]] !== void 0)
-          throw new Error("Attempt to redefine a known term: " + def[1]);
-        jar[def[1]] = expr;
-      }
+      if (name)
+        jar[name] = expr;
     }
     if (this.addContext) {
       if (expr instanceof Named)
@@ -1591,7 +1610,7 @@ var Parser = class {
   parseLine(source, env = {}, options = {}) {
     const aliased = source.match(/^\s*([A-Z]|[a-z][a-z_0-9]*)\s*=\s*(.*)$/s);
     if (aliased)
-      return new Alias(aliased[1], this.parseLine(aliased[2], env, options));
+      return new Alias(aliased[1], this.parseLine(aliased[2], env, options), { canonize: options.canonize });
     const opt = {
       numbers: options.numbers ?? this.hasNumbers,
       lambdas: options.lambdas ?? this.hasLambdas,
@@ -2066,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,
@@ -2129,72 +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 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";
 }
-function declare(expr, env = {}) {
-  const res = toposort([expr], env);
-  return res.list.map((s) => {
-    if (s instanceof Alias)
-      return s.name + "=" + s.impl.format({ inventory: res.env });
-    if (s instanceof FreeVar)
-      return s.name + "=";
-    return s.format({ inventory: res.env });
-  }).join("; ");
-}
-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;