eyeling 1.5.15 → 1.5.16

package/README.md

@@ -4,12 +4,13 @@ A minimal [Notation3 (N3)](https://notation3.org/) reasoner in **JavaScript**.
 
 `eyeling` is:
 
-- a single self-contained file (`eyeling.js`, no external deps),
-- intentionally tiny and close in spirit to EYE,
-- a practical N3/Turtle superset (enough for lots of real rulesets),
-- supports forward (`=>`) + backward (`<=`) chaining over Horn-style rules,
-- prints only newly derived forward facts, optionally preceded by compact proof comments,
-- we never want to leak raw data, hence pass-only-new and backward rules for functions that work with raw data, and of course we also keep all reasoning in the browser.
+- a single self-contained file (`eyeling.js`, no external deps)
+- intentionally tiny and close in spirit to EYE
+- a practical N3/Turtle superset (enough for lots of real rulesets)
+- supports forward (`=>`) + backward (`<=`) chaining over Horn-style rules
+- prints only newly derived forward facts, optionally preceded by compact proof comments
+- we never want to leak raw data, hence pass-only-new and backward rules for functions that work with raw data
+- and of course we also keep all reasoning in the browser
 
 ## Playground (in your browser)
 
@@ -18,21 +19,22 @@ Try it here:
 - [Eyeling playground](https://eyereasoner.github.io/eyeling/demo)
 
 The playground runs `eyeling` client-side. You can:
-- edit an N3 program directly,
-- load an N3 program from a URL,
-- share a link with the program encoded in the URL fragment (`#...`).  
+
+- edit an N3 program directly
+- load an N3 program from a URL
+- share a link with the program encoded in the URL fragment (`#...`)
 
 ### Example (Socrates)
 
 This link preloads a small “Socrates is Mortal” ruleset:
 
-[Socrates example](https://eyereasoner.github.io/eyeling/demo#%23%20------------------%0A%23%20Socrates%20inference%0A%23%20------------------%0A%0A%40prefix%20rdfs%3A%20%3Chttp%3A%2F%2Fwww.w3.org%2F2000%2F01%2Frdf-schema%23%3E.%0A%40prefix%20%3A%20%3Chttp%3A%2F%2Fexample.org%2Fsocrates%23%3E.%0A%0A%23%20facts%0A%3ASocrates%20a%20%3AHuman.%0A%3AHuman%20rdfs%3AsubClassOf%20%3AMortal.%0A%0A%23%20subclass%20rule%0A%7B%0A%20%20%20%20%3FS%20a%20%3FA.%0A%20%20%20%20%3FA%20rdfs%3AsubClassOf%20%3FB.%0A%7D%20%3D%3E%20%7B%0A%20%20%20%20%3FS%20a%20%3FB.%0A%7D%2E%0A)
+- [Socrates example](https://eyereasoner.github.io/eyeling/demo#%23%20------------------%0A%23%20Socrates%20inference%0A%23%20------------------%0A%0A%40prefix%20rdfs%3A%20%3Chttp%3A%2F%2Fwww.w3.org%2F2000%2F01%2Frdf-schema%23%3E.%0A%40prefix%20%3A%20%3Chttp%3A%2F%2Fexample.org%2Fsocrates%23%3E.%0A%0A%23%20facts%0A%3ASocrates%20a%20%3AHuman.%0A%3AHuman%20rdfs%3AsubClassOf%20%3AMortal.%0A%0A%23%20subclass%20rule%0A%7B%0A%20%20%20%20%3FS%20a%20%3FA.%0A%20%20%20%20%3FA%20rdfs%3AsubClassOf%20%3FB.%0A%7D%20%3D%3E%20%7B%0A%20%20%20%20%3FS%20a%20%3FB.%0A%7D%2E%0A)
 
 ## Quick start (Node.js)
 
 ### Requirements
 
-- A reasonably recent Node.js (anything modern with `BigInt` support is fine).
+- Node.js >= 18 (anything modern with `BigInt` support is fine)
 
 ### Install (npm)
 
@@ -53,7 +55,7 @@ npx eyeling examples/socrates.n3
 ### JavaScript API (Node)
 
 ```js
-const { reason } = require('eyeling');
+const { reason } = require("eyeling");
 
 const input = `
 @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>.
@@ -72,7 +74,7 @@ console.log(output);
 ESM:
 
 ```js
-import eyeling from 'eyeling';
+import eyeling from "eyeling";
 
 const output = eyeling.reason({ proofComments: false }, input);
 console.log(output);
@@ -80,6 +82,28 @@ console.log(output);
 
 Note: the API currently shells out to the bundled `eyeling.js` CLI under the hood (simple + robust).
 
+### Testing
+
+From a repo checkout:
+
+```bash
+npm test
+```
+
+Or run individual suites:
+
+```bash
+npm run test:api
+npm run test:examples
+npm run test:package
+npm run test:packlist
+```
+
+- `test:api` runs an independent JS API test suite (does not rely on `examples/`).
+- `test:examples` runs the `examples/test` runner and compares against the golden outputs in `examples/output`.
+- `test:package` does a “real consumer” smoke test: `npm pack` → install tarball into a temp project → run API + CLI + examples.
+- `test:packlist` sanity-checks what will be published in the npm tarball (and the CLI shebang/bin wiring).
+
 ### Run a single file
 
 From the repo root:
@@ -94,10 +118,10 @@ node eyeling.js examples/socrates.n3
 
 By default, `eyeling`:
 
-1. parses the input (facts + rules),
-2. runs **forward chaining to a fixpoint**,
-3. prints only **newly derived forward facts** (not the original input facts),
-4. prints a compact per-triple explanation as `#` comments (can be disabled).
+1. parses the input (facts + rules)
+2. runs **forward chaining to a fixpoint**
+3. prints only **newly derived forward facts** (not the original input facts)
+4. prints a compact per-triple explanation as `#` comments (can be disabled)
 
 ### Options
 
@@ -116,7 +140,8 @@ node eyeling.js -n examples/socrates.n3
 npm run test:examples
 ```
 
-This runs `eyeling.js` over each example and compares against the golden outputs in `examples/output`.
+This runs `eyeling.js` over each example and compares against the golden outputs in `examples/output`
+(works both in a git checkout and in an npm-installed package).
 
 ## What output do I get?
 
@@ -131,14 +156,14 @@ The proof comments are compact “local justifications” per derived triple (no
 
 ### Forward + backward chaining
 
-* **Forward chaining to fixpoint** for forward rules written as `{ P } => { C } .`
-* **Backward chaining (SLD-style)** for backward rules written as `{ H } <= { B } .` and for built-ins.
+- **Forward chaining to fixpoint** for forward rules written as `{ P } => { C } .`
+- **Backward chaining (SLD-style)** for backward rules written as `{ H } <= { B } .` and for built-ins.
 
 Forward rule premises are proved using:
 
-* ground facts (input + derived),
-* backward rules,
-* built-ins.
+- ground facts (input + derived)
+- backward rules
+- built-ins
 
 The CLI prints only newly derived forward facts.
 
@@ -146,63 +171,59 @@ The CLI prints only newly derived forward facts.
 
 `eyeling` stays tiny, but includes a few key performance mechanisms:
 
-* facts are indexed for matching:
-
-  * by predicate, and (when possible) by **(predicate, object)** (important for type-heavy workloads),
-* duplicate detection uses a fast key path when a triple is fully IRI/Literal-shaped,
-* backward rules are indexed by head predicate,
-* the backward prover is **iterative** (explicit stack), so deep chains won’t blow the JS call stack,
-* for very deep backward chains, substitutions may be compactified (semantics-preserving) to avoid quadratic “copy a growing substitution object” behavior.
+- facts are indexed for matching:
+  - by predicate, and (when possible) by **(predicate, object)** (important for type-heavy workloads)
+- duplicate detection uses a fast key path when a triple is fully IRI/Literal-shaped
+- backward rules are indexed by head predicate
+- the backward prover is **iterative** (explicit stack), so deep chains won’t blow the JS call stack
+- for very deep backward chains, substitutions may be compactified (semantics-preserving) to avoid quadratic “copy a growing substitution object” behavior
 
 ## Parsing: practical N3 subset
 
 Supported:
 
-* `@prefix` / `@base`
-* triples with `;` and `,`
-* variables `?x`
-* blank nodes:
-
-  * anonymous `[]`
-  * property lists `[ :p :o; :q :r ]`
-  * collections `( ... )`
-* quoted formulas `{ ... }`
-* implications:
-
-  * forward rules `{ P } => { C } .`
-  * backward rules `{ H } <= { B } .`
-* datatyped literals with `^^`
-* `#` line comments
+- `@prefix` / `@base`
+- triples with `;` and `,`
+- variables `?x`
+- blank nodes:
+  - anonymous `[]`
+  - property lists `[ :p :o; :q :r ]`
+- collections `( ... )`
+- quoted formulas `{ ... }`
+- implications:
+  - forward rules `{ P } => { C } .`
+  - backward rules `{ H } <= { B } .`
+- datatyped literals with `^^`
+- `#` line comments
 
 Non-goals / current limits:
 
-* not a full W3C N3 grammar (some edge cases for identifiers, quantifiers, advanced syntax),
-* quoted formulas are matched as whole formulas (no pattern matching inside formulas yet),
-* proof output is local per derived triple (not a global exported proof tree).
+- not a full W3C N3 grammar (some edge cases for identifiers, quantifiers, advanced syntax)
+- quoted formulas are matched as whole formulas (no pattern matching inside formulas yet)
+- proof output is local per derived triple (not a global exported proof tree)
 
 ## Blank nodes and quantification (pragmatic N3/EYE-style)
 
 `eyeling` follows the usual N3 intuition:
 
-1. blank nodes in facts are normal RDF blanks (`_:b1`, `_:b2`, … within a run),
-2. blank nodes in rule premises behave like rule-scoped universals (similar to variables),
-3. blank nodes only in rule conclusions behave like existentials:
-   each rule firing generates fresh Skolem blanks (`_:sk_0`, `_:sk_1`, …).
+1. blank nodes in facts are normal RDF blanks (`_:b1`, `_:b2`, … within a run)
+2. blank nodes in rule premises behave like rule-scoped universals (similar to variables)
+3. blank nodes only in rule conclusions behave like existentials: each rule firing generates fresh Skolem blanks (`_:sk_0`, `_:sk_1`, …)
 
 Equal facts up to renaming of Skolem IDs are treated as duplicates and are not re-added.
 
 ## Rule-producing rules (meta-rules)
 
-`eyeling` understands the `log:implies` / `log:impliedBy` idiom:
+`eyeling` understands the `log:implies` / `log:impliedBy` idiom.
 
 Top level:
 
-* `{ P } log:implies { C } .` becomes a forward rule `{ P } => { C } .`
-* `{ H } log:impliedBy { B } .` becomes a backward rule `{ H } <= { B } .`
+- `{ P } log:implies { C } .` becomes a forward rule `{ P } => { C } .`
+- `{ H } log:impliedBy { B } .` becomes a backward rule `{ H } <= { B } .`
 
 During reasoning:
 
-* any **derived** `log:implies` / `log:impliedBy` triple with formula subject/object is turned into a new live forward/backward rule.
+- any **derived** `log:implies` / `log:impliedBy` triple with formula subject/object is turned into a new live forward/backward rule.
 
 ## Inference fuse — `{ ... } => false.`
 
@@ -211,6 +232,7 @@ Rules whose conclusion is `false` are treated as hard failures:
 ```n3
 :stone :color :black .
 :stone :color :white .
+
 { ?X :color :black . ?X :color :white . } => false.
 ```
 
@@ -220,13 +242,12 @@ As soon as the premise is provable, `eyeling` exits with status code `2`.
 
 `eyeling` implements a pragmatic subset of common N3 builtin families and evaluates them during backward goal proving:
 
-* **crypto**: `crypto:md5` `crypto:sha` `crypto:sha256` `crypto:sha512`
-* **list**: `list:append` `list:first` `list:firstRest` `list:in` `list:iterate` `list:last` `list:length` `list:map` `list:member` `list:memberAt` `list:notMember` `list:remove` `list:reverse` `list:sort`
-* **log**: `log:collectAllIn` `log:equalTo` `log:forAllIn` `log:impliedBy` `log:implies` `log:notEqualTo` `log:notIncludes` `log:skolem` `log:uri`
-* **math**: `math:absoluteValue` `math:acos` `math:asin` `math:atan` `math:cos` `math:cosh` `math:degrees` `math:difference` `math:equalTo` `math:exponentiation` `math:greaterThan` `math:lessThan` `math:negation` `math:notEqualTo` `math:notGreaterThan` `math:notLessThan` `math:product` `math:quotient` `math:remainder` `math:rounded` `math:sin` `math:sinh` `math:sum` `math:tan` `math:tanh`
-* **string**: `string:concatenation` `string:contains` `string:containsIgnoringCase` `string:endsWith` `string:equalIgnoringCase` `string:format` `string:greaterThan` `string:lessThan` `string:matches` `string:notEqualIgnoringCase` `string:notGreaterThan` `string:notLessThan` `string:notMatches` `string:replace` `string:scrape` `string:startsWith`
-* **time**: `time:localTime`
-
+- **crypto**: `crypto:md5` `crypto:sha` `crypto:sha256` `crypto:sha512`
+- **list**: `list:append` `list:first` `list:firstRest` `list:in` `list:iterate` `list:last` `list:length` `list:map` `list:member` `list:memberAt` `list:notMember` `list:remove` `list:reverse` `list:sort`
+- **log**: `log:collectAllIn` `log:equalTo` `log:forAllIn` `log:impliedBy` `log:implies` `log:notEqualTo` `log:notIncludes` `log:skolem` `log:uri`
+- **math**: `math:absoluteValue` `math:acos` `math:asin` `math:atan` `math:cos` `math:cosh` `math:degrees` `math:difference` `math:equalTo` `math:exponentiation` `math:greaterThan` `math:lessThan` `math:negation` `math:notEqualTo` `math:notGreaterThan` `math:notLessThan` `math:product` `math:quotient` `math:remainder` `math:rounded` `math:sin` `math:sinh` `math:sum` `math:tan` `math:tanh`
+- **string**: `string:concatenation` `string:contains` `string:containsIgnoringCase` `string:endsWith` `string:equalIgnoringCase` `string:format` `string:greaterThan` `string:lessThan` `string:matches` `string:notEqualIgnoringCase` `string:notGreaterThan` `string:notLessThan` `string:notMatches` `string:replace` `string:scrape` `string:startsWith`
+- **time**: `time:localTime`
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eyeling",
-  "version": "1.5.15",
+  "version": "1.5.16",
   "description": "A minimal Notation3 (N3) reasoner in JavaScript.",
   "main": "./index.js",
   "keywords": [