eyelang 1.5.0 → 1.5.2

package/README.md

@@ -239,10 +239,10 @@ Predicate names and atom constants use the same lexical form. Namespace-like nam
 
 The CLI is output-oriented and uses `materialize/2` to decide what to print. Embedders can still use the JavaScript API and `Solver` directly for arbitrary goals and arities.
 
-Add `--stats` when you want lightweight solver counters on stderr without changing stdout:
+Add `-s` or `--stats` when you want lightweight solver counters on stderr without changing stdout:
 
 ```sh
-bin/eyelang --stats examples/sudoku.pl
+bin/eyelang -s examples/sudoku.pl
 ```
 
 The playground has matching `--stats` and `--proof` checkboxes, so browser runs can show the same counters or explanations like the CLI.
@@ -362,6 +362,7 @@ The repository includes examples for recursion, graph reachability, finite searc
 | [`delfour.pl`](https://github.com/eyereasoner/eyelang/blob/main/examples/delfour.pl) | Derives shopping and authorization recommendations. | [`output/delfour.pl`](https://github.com/eyereasoner/eyelang/blob/main/examples/output/delfour.pl) |
 | [`dense-hamiltonian-cycle.pl`](https://github.com/eyereasoner/eyelang/blob/main/examples/dense-hamiltonian-cycle.pl) | Searches a dense Hamiltonian cycle with aggregate minimization. | [`output/dense-hamiltonian-cycle.pl`](https://github.com/eyereasoner/eyelang/blob/main/examples/output/dense-hamiltonian-cycle.pl) |
 | [`deontic-logic.pl`](https://github.com/eyereasoner/eyelang/blob/main/examples/deontic-logic.pl) | Reports obligations, prohibitions, and violations. | [`output/deontic-logic.pl`](https://github.com/eyereasoner/eyelang/blob/main/examples/output/deontic-logic.pl) |
+| [`derived-backward-rule.pl`](https://github.com/eyereasoner/eyelang/blob/main/examples/derived-backward-rule.pl) | Derives an inverse-property backward rule from rule data. | [`output/derived-backward-rule.pl`](https://github.com/eyereasoner/eyelang/blob/main/examples/output/derived-backward-rule.pl) |
 | [`derived-rule.pl`](https://github.com/eyereasoner/eyelang/blob/main/examples/derived-rule.pl) | Derives conclusions from rule data. | [`output/derived-rule.pl`](https://github.com/eyereasoner/eyelang/blob/main/examples/output/derived-rule.pl) |
 | [`diamond-property.pl`](https://github.com/eyereasoner/eyelang/blob/main/examples/diamond-property.pl) | Checks the diamond property of a relation. | [`output/diamond-property.pl`](https://github.com/eyereasoner/eyelang/blob/main/examples/output/diamond-property.pl) |
 | [`dijkstra-findall-sort.pl`](https://github.com/eyereasoner/eyelang/blob/main/examples/dijkstra-findall-sort.pl) | Finds shortest paths using collected candidates. | [`output/dijkstra-findall-sort.pl`](https://github.com/eyereasoner/eyelang/blob/main/examples/output/dijkstra-findall-sort.pl) |
@@ -500,7 +501,7 @@ node bin/eyelang --help
 Useful profiling smoke test:
 
 ```sh
-bin/eyelang --stats examples/sudoku.pl > /dev/null
+bin/eyelang -s examples/sudoku.pl > /dev/null
 ```
 
 For a release:
@@ -513,7 +514,7 @@ For a release:
 
 ## Performance notes
 
-Use `--stats` for a quick sanity check while optimizing solver changes. It prints counters such as `solve_goals_calls`, `unify_calls`, `deterministic_rule_expansions`, `candidate_lists_selected`, `clause_candidates_considered`, `clauses_tried`, `max_depth`, and `max_solver_call_depth` to stderr, leaving normal output stable for golden-file tests. The `max_solver_call_depth` counter is especially useful for browser regressions, where the VM call stack can be tighter than a command-line run.
+Use `-s` or `--stats` for a quick sanity check while optimizing solver changes. It prints counters such as `solve_goals_calls`, `unify_calls`, `deterministic_rule_expansions`, `candidate_lists_selected`, `clause_candidates_considered`, `clauses_tried`, `max_depth`, and `max_solver_call_depth` to stderr, leaving normal output stable for golden-file tests. The `max_solver_call_depth` counter is especially useful for browser regressions, where the VM call stack can be tighter than a command-line run.
 
 eyelang hashes predicate groups by name and arity, then indexes clauses by scalar argument values. It also builds two-argument composite indexes for scalar pairs and probes those composite indexes without per-lookup heap allocation. This helps both large generated programs with many predicates and selective queries such as:
 

package/examples/derived-backward-rule.pl

@@ -0,0 +1,27 @@
+% Derived backward rule example adapted from Eyeling derived-backward-rule.n3.
+%
+% Eyeling source shape:
+%   parentOf invOf childOf.
+%   alice parentOf bob.
+%   { ?p invOf ?q. } => { { ?x ?q ?y. } <= { ?y ?p ?x. }. }.
+%   { ?x childOf ?y. } => { ?x hasParent ?y. }.
+%
+% The generated backward rule is represented as quoted formula data in
+% log_impliedBy/2, then mirrored as an ordinary eyelang rule so the generated
+% childOf relation can feed the ordinary hasParent rule.
+
+materialize(log_impliedBy, 2).
+materialize(childOf, 2).
+materialize(hasParent, 2).
+
+invOf(parentOf, childOf).
+parentOf(alice, bob).
+
+log_impliedBy(childOf(var(x), var(y)), parentOf(var(y), var(x))) :-
+  invOf(parentOf, childOf).
+
+childOf(X, Y) :-
+  log_impliedBy(childOf(var(x), var(y)), parentOf(var(y), var(x))),
+  parentOf(Y, X).
+
+hasParent(X, Y) :- childOf(X, Y).

package/examples/output/derived-backward-rule.pl

@@ -0,0 +1,3 @@
+log_impliedBy(childOf(var(x), var(y)), parentOf(var(y), var(x))).
+childOf(bob, alice).
+hasParent(bob, alice).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eyelang",
-  "version": "1.5.0",
+  "version": "1.5.2",
   "type": "module",
   "description": "A small rule engine for Prolog-style Horn clauses",
   "keywords": [

package/playground.html

@@ -466,6 +466,7 @@
   "delfour",
   "dense-hamiltonian-cycle",
   "deontic-logic",
+  "derived-backward-rule",
   "derived-rule",
   "diamond-property",
   "dijkstra",

package/src/cli.js

@@ -34,7 +34,7 @@ export async function main(argv) {
       return;
     } else if (!endOptions && (arg === '--proof' || arg === '-p')) {
       options.proof = true;
-    } else if (!endOptions && arg === '--stats') {
+    } else if (!endOptions && (arg === '--stats' || arg === '-s')) {
       options.stats = true;
     } else if (!endOptions && arg.startsWith('-') && arg !== '-') {
       throw new Error(`unknown option: ${arg}`);
@@ -142,7 +142,7 @@ Input:
 Options:
   -h, --help            Show this help text and exit.
   -p, --proof           Enable proof explanations.
-      --stats           Print solver statistics to stderr after execution.
+  -s, --stats           Print solver statistics to stderr after execution.
   -v, --version         Show the package version and exit.
   --                    Stop option parsing; following arguments are treated as files.
 `);

package/test/run-regression.js

@@ -171,7 +171,8 @@ why(
         const result = runCli([]);
         assertEqual(result.status, 0, 'exit status');
         assertIncludes(result.stdout, 'Usage:\n  eyelang [options] [file-or-url.pl|- ...]', 'stdout');
-        assertIncludes(result.stdout, '--proof', 'stdout');
+        assertIncludes(result.stdout, '-p, --proof', 'stdout');
+        assertIncludes(result.stdout, '-s, --stats', 'stdout');
         assertEqual(result.stderr, '', 'stderr');
       },
     },
@@ -225,6 +226,28 @@ why(
     },
 
 
+    {
+      name: '--stats prints solver statistics to stderr',
+      run: () => {
+        const result = runCli(['--stats', '-'], { input: 'p(a, b).\nq(X, Y) :- p(X, Y).\n' });
+        assertEqual(result.status, 0, 'exit status');
+        assertEqual(result.stdout, 'q(a, b).\n', 'stdout');
+        assertIncludes(result.stderr, 'eyelang stats:\n', 'stderr');
+        assertIncludes(result.stderr, '  solve_goals_calls:', 'stderr');
+      },
+    },
+    {
+      name: '-s prints solver statistics to stderr',
+      run: () => {
+        const result = runCli(['-s', '-'], { input: 'p(a, b).\nq(X, Y) :- p(X, Y).\n' });
+        assertEqual(result.status, 0, 'exit status');
+        assertEqual(result.stdout, 'q(a, b).\n', 'stdout');
+        assertIncludes(result.stderr, 'eyelang stats:\n', 'stderr');
+        assertIncludes(result.stderr, '  solve_goals_calls:', 'stderr');
+      },
+    },
+
+
     {
       name: 'double dash permits option-shaped file names',
       run: () => {