eyeling 1.18.2 → 1.19.1

package/HANDBOOK.md

@@ -1777,12 +1777,16 @@ Install from npm:
 npm i eyeling
 ```
 
-Run a file:
+Run a self-contained example from stdin:
 
 ```bash
-npx eyeling examples/socrates.n3
+echo '@prefix : <http://example.org/> .
+:Socrates a :Man .
+{ ?x a :Man } => { ?x a :Mortal } .' | npx eyeling
 ```
 
+You can also pass a file path, or `-` to read explicitly from stdin.
+
 Show the available options:
 
 ```bash
@@ -1816,6 +1820,7 @@ The bundle contains the whole engine. The CLI path is the “canonical behavior
 The current CLI supports a small set of flags (see `lib/cli.js`):
 
 - `-a`, `--ast` — print the parsed AST as JSON and exit.
+- `--builtin <module.js>` — load a custom builtin module (repeatable).
 - `-d`, `--deterministic-skolem` — make `log:skolem` stable across runs.
 - `-e`, `--enforce-https` — rewrite `http://…` to `https://…` for dereferencing builtins.
 - `-p`, `--proof-comments` — include per-fact proof comment blocks in output.
@@ -1823,6 +1828,8 @@ The current CLI supports a small set of flags (see `lib/cli.js`):
 - `-t`, `--stream` — stream derived triples as soon as they are derived.
 - `-v`, `--version` — print version and exit.
 - `-h`, `--help` — show usage.
+- With no positional argument, Eyeling reads from stdin when input is piped.
+- Use `-` as the input path to read explicitly from stdin.
 
 ### 14.3 `lib/entry.js`: bundler-friendly exports
 

package/README.md

@@ -7,8 +7,9 @@ A compact [Notation3 (N3)](https://notation3.org/) reasoner in **JavaScript**.
 ## Quick start
 
 ```bash
-npm i eyeling
-npx eyeling examples/socrates.n3
+echo '@prefix : <http://example.org/> .
+:Socrates a :Man .
+{ ?x a :Man } => { ?x a :Mortal } .' | npx eyeling
 ```
 
 ## Read more

package/eyeling.js

@@ -3670,7 +3670,7 @@ function evalBuiltin(goal, subst, facts, backRules, depth, varGen, maxResults) {
   //   - subject = GraphTerm: explicit scope, run immediately (no closure gating)
   //   - subject = positive integer literal N (>= 1): delay until saturated closure level >= N
   //   - subject = Var: treat as priority 1 (do not bind)
-  //   - any other subject: backward-compatible default priority 1
+  //   - any other subject: invalid, so the builtin fails
   if (pv === LOG_NS + 'includes') {
     let scopeFacts = null;
     let scopeBackRules = backRules;
@@ -3698,7 +3698,8 @@ function evalBuiltin(goal, subst, facts, backRules, depth, varGen, maxResults) {
         prio = 1; // do not bind
       } else {
         const p0 = __logNaturalPriorityFromTerm(g.s);
-        if (p0 !== null) prio = p0;
+        if (p0 === null) return [];
+        prio = p0;
       }
 
       const snap = facts.__scopedSnapshot || null;
@@ -3781,7 +3782,8 @@ function evalBuiltin(goal, subst, facts, backRules, depth, varGen, maxResults) {
         prio = 1; // do not bind
       } else {
         const p0 = __logNaturalPriorityFromTerm(g.s);
-        if (p0 !== null) prio = p0;
+        if (p0 === null) return [];
+        prio = p0;
       }
 
       const snap = facts.__scopedSnapshot || null;
@@ -4536,6 +4538,11 @@ function formatN3SyntaxError(err, text, path) {
 }
 
 // CLI entry point (invoked when eyeling.js is run directly)
+function readTextFromStdinSync() {
+  const fs = require('node:fs');
+  return fs.readFileSync(0, { encoding: 'utf8' });
+}
+
 function main() {
   // Drop "node" and script name; keep only user-provided args
   // Expand combined short options: -pt == -p -t
@@ -4555,7 +4562,8 @@ function main() {
 
   function printHelp(toStderr = false) {
     const msg =
-      `Usage: ${prog} [options] <file.n3>\n\n` +
+      `Usage: ${prog} [options] [file.n3|-]\n\n` +
+      `When no file is given and stdin is piped, read N3 from stdin.\n\n` +
       `Options:\n` +
       `  -a, --ast                    Print parsed AST as JSON and exit.\n` +
       `      --builtin <module.js>    Load a custom builtin module (repeatable).\n` +
@@ -4626,12 +4634,13 @@ function main() {
   }
 
   // Positional args (the N3 file)
-  if (positional.length === 0) {
+  const useImplicitStdin = positional.length === 0 && !process.stdin.isTTY;
+  if (positional.length === 0 && !useImplicitStdin) {
     printHelp(false);
     process.exit(0);
   }
-  if (positional.length !== 1) {
-    console.error('Error: expected exactly one input <file.n3>.');
+  if (positional.length > 1) {
+    console.error('Error: expected at most one input [file.n3|-].');
     printHelp(true);
     process.exit(1);
   }
@@ -4646,13 +4655,17 @@ function main() {
     }
   }
 
-  const filePath = positional[0];
+  const sourceLabel = useImplicitStdin || positional[0] === '-' ? '<stdin>' : positional[0];
   let text;
   try {
-    const fs = require('fs');
-    text = fs.readFileSync(filePath, { encoding: 'utf8' });
+    if (sourceLabel === '<stdin>') text = readTextFromStdinSync();
+    else {
+      const fs = require('node:fs');
+      text = fs.readFileSync(sourceLabel, { encoding: 'utf8' });
+    }
   } catch (e) {
-    console.error(`Error reading file ${JSON.stringify(filePath)}: ${e.message}`);
+    if (sourceLabel === '<stdin>') console.error(`Error reading stdin: ${e.message}`);
+    else console.error(`Error reading file ${JSON.stringify(sourceLabel)}: ${e.message}`);
     process.exit(1);
   }
 
@@ -4666,7 +4679,7 @@ function main() {
     engine.setTracePrefixes(prefixes);
   } catch (e) {
     if (e && e.name === 'N3SyntaxError') {
-      console.error(formatN3SyntaxError(e, text, filePath));
+      console.error(formatN3SyntaxError(e, text, sourceLabel));
       process.exit(1);
     }
     throw e;

package/lib/builtins.js

@@ -3190,7 +3190,7 @@ function evalBuiltin(goal, subst, facts, backRules, depth, varGen, maxResults) {
   //   - subject = GraphTerm: explicit scope, run immediately (no closure gating)
   //   - subject = positive integer literal N (>= 1): delay until saturated closure level >= N
   //   - subject = Var: treat as priority 1 (do not bind)
-  //   - any other subject: backward-compatible default priority 1
+  //   - any other subject: invalid, so the builtin fails
   if (pv === LOG_NS + 'includes') {
     let scopeFacts = null;
     let scopeBackRules = backRules;
@@ -3218,7 +3218,8 @@ function evalBuiltin(goal, subst, facts, backRules, depth, varGen, maxResults) {
         prio = 1; // do not bind
       } else {
         const p0 = __logNaturalPriorityFromTerm(g.s);
-        if (p0 !== null) prio = p0;
+        if (p0 === null) return [];
+        prio = p0;
       }
 
       const snap = facts.__scopedSnapshot || null;
@@ -3301,7 +3302,8 @@ function evalBuiltin(goal, subst, facts, backRules, depth, varGen, maxResults) {
         prio = 1; // do not bind
       } else {
         const p0 = __logNaturalPriorityFromTerm(g.s);
-        if (p0 !== null) prio = p0;
+        if (p0 === null) return [];
+        prio = p0;
       }
 
       const snap = facts.__scopedSnapshot || null;

package/lib/cli.js

@@ -45,6 +45,11 @@ function formatN3SyntaxError(err, text, path) {
 }
 
 // CLI entry point (invoked when eyeling.js is run directly)
+function readTextFromStdinSync() {
+  const fs = require('node:fs');
+  return fs.readFileSync(0, { encoding: 'utf8' });
+}
+
 function main() {
   // Drop "node" and script name; keep only user-provided args
   // Expand combined short options: -pt == -p -t
@@ -64,7 +69,8 @@ function main() {
 
   function printHelp(toStderr = false) {
     const msg =
-      `Usage: ${prog} [options] <file.n3>\n\n` +
+      `Usage: ${prog} [options] [file.n3|-]\n\n` +
+      `When no file is given and stdin is piped, read N3 from stdin.\n\n` +
       `Options:\n` +
       `  -a, --ast                    Print parsed AST as JSON and exit.\n` +
       `      --builtin <module.js>    Load a custom builtin module (repeatable).\n` +
@@ -135,12 +141,13 @@ function main() {
   }
 
   // Positional args (the N3 file)
-  if (positional.length === 0) {
+  const useImplicitStdin = positional.length === 0 && !process.stdin.isTTY;
+  if (positional.length === 0 && !useImplicitStdin) {
     printHelp(false);
     process.exit(0);
   }
-  if (positional.length !== 1) {
-    console.error('Error: expected exactly one input <file.n3>.');
+  if (positional.length > 1) {
+    console.error('Error: expected at most one input [file.n3|-].');
     printHelp(true);
     process.exit(1);
   }
@@ -155,13 +162,17 @@ function main() {
     }
   }
 
-  const filePath = positional[0];
+  const sourceLabel = useImplicitStdin || positional[0] === '-' ? '<stdin>' : positional[0];
   let text;
   try {
-    const fs = require('fs');
-    text = fs.readFileSync(filePath, { encoding: 'utf8' });
+    if (sourceLabel === '<stdin>') text = readTextFromStdinSync();
+    else {
+      const fs = require('node:fs');
+      text = fs.readFileSync(sourceLabel, { encoding: 'utf8' });
+    }
   } catch (e) {
-    console.error(`Error reading file ${JSON.stringify(filePath)}: ${e.message}`);
+    if (sourceLabel === '<stdin>') console.error(`Error reading stdin: ${e.message}`);
+    else console.error(`Error reading file ${JSON.stringify(sourceLabel)}: ${e.message}`);
     process.exit(1);
   }
 
@@ -175,7 +186,7 @@ function main() {
     engine.setTracePrefixes(prefixes);
   } catch (e) {
     if (e && e.name === 'N3SyntaxError') {
-      console.error(formatN3SyntaxError(e, text, filePath));
+      console.error(formatN3SyntaxError(e, text, sourceLabel));
       process.exit(1);
     }
     throw e;

package/package.json

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

package/test/api.test.js

@@ -1462,6 +1462,42 @@ _:x :hates { _:foo :making :mess }.
     notExpect: [/:(?:test)\s+:(?:is)\s+false\s*\./],
   },
 
+  {
+    name: '59b regression: log:includes rejects non-scope literal or term subjects',
+    opt: { proofComments: false },
+    input: `@prefix : <http://example.org/> .
+@prefix log: <http://www.w3.org/2000/10/swap/log#> .
+@base <http://example.org/> .
+
+{ false log:includes true. } => { :result :has :fail-literal-1. }.
+{ "foo" log:includes true. } => { :result :has :fail-literal-2. }.
+{ :foo log:includes true. } => { :result :has :fail-literal-3. }.
+{ 0 log:includes true. } => { :result :has :fail-literal-4. }.
+{ 42.3 log:includes true. } => { :result :has :fail-literal-5. }.
+{ (:foo 1 _:x) log:includes true. } => { :result :has :fail-literal-6. }.
+
+{ } => {
+  :test :contains :fail-literal-1, :fail-literal-2, :fail-literal-3, :fail-literal-4, :fail-literal-5, :fail-literal-6.
+}.
+`,
+    expect: [
+      /:(?:test)\s+:(?:contains)\s+:(?:fail-literal-1)\s*\./,
+      /:(?:test)\s+:(?:contains)\s+:(?:fail-literal-2)\s*\./,
+      /:(?:test)\s+:(?:contains)\s+:(?:fail-literal-3)\s*\./,
+      /:(?:test)\s+:(?:contains)\s+:(?:fail-literal-4)\s*\./,
+      /:(?:test)\s+:(?:contains)\s+:(?:fail-literal-5)\s*\./,
+      /:(?:test)\s+:(?:contains)\s+:(?:fail-literal-6)\s*\./,
+    ],
+    notExpect: [
+      /:(?:result)\s+:(?:has)\s+:(?:fail-literal-1)\s*\./,
+      /:(?:result)\s+:(?:has)\s+:(?:fail-literal-2)\s*\./,
+      /:(?:result)\s+:(?:has)\s+:(?:fail-literal-3)\s*\./,
+      /:(?:result)\s+:(?:has)\s+:(?:fail-literal-4)\s*\./,
+      /:(?:result)\s+:(?:has)\s+:(?:fail-literal-5)\s*\./,
+      /:(?:result)\s+:(?:has)\s+:(?:fail-literal-6)\s*\./,
+    ],
+  },
+
   {
     name: '60 regression: log:includes must match quoted triples with variable predicates',
     opt: { proofComments: false },
@@ -1762,6 +1798,55 @@ _:x :hates { _:foo :making :mess }.
     },
     expect: [/http:\/\/example\.org\/ancestor/m],
   },
+  {
+    name: '67 CLI stdin: accepts piped N3 when no file argument is given',
+    run() {
+      const input = `@prefix : <http://example.org/> .
+:Socrates a :Man .
+{ ?x a :Man } => { ?x a :Mortal } .
+`;
+      const r = spawnSync(process.execPath, [path.join(ROOT, 'eyeling.js')], {
+        input,
+        encoding: 'utf8',
+        stdio: ['pipe', 'pipe', 'pipe'],
+      });
+      if (r.error) throw r.error;
+      if (r.status !== 0) {
+        const err = new Error(`CLI failed with exit ${r.status}`);
+        err.code = r.status;
+        err.stdout = r.stdout;
+        err.stderr = r.stderr;
+        throw err;
+      }
+      return r.stdout;
+    },
+    expect: [/:(?:Socrates)\s+a\s+:(?:Mortal)\s*\./],
+  },
+  {
+    name: '68 CLI stdin: accepts explicit - for stdin',
+    run() {
+      const input = `@prefix : <http://example.org/> .
+:Socrates a :Man .
+{ ?x a :Man } => { ?x a :Mortal } .
+`;
+      const r = spawnSync(process.execPath, [path.join(ROOT, 'eyeling.js'), '-'], {
+        input,
+        encoding: 'utf8',
+        stdio: ['pipe', 'pipe', 'pipe'],
+      });
+      if (r.error) throw r.error;
+      if (r.status !== 0) {
+        const err = new Error(`CLI failed with exit ${r.status}`);
+        err.code = r.status;
+        err.stdout = r.stdout;
+        err.stderr = r.stderr;
+        throw err;
+      }
+      return r.stdout;
+    },
+    expect: [/:(?:Socrates)\s+a\s+:(?:Mortal)\s*\./],
+  },
+
   {
     name: '240 custom builtin module can be loaded via --builtin',
     run() {