eyeleng 1.1.1 → 1.2.0

package/eyeleng.js

@@ -17,7 +17,7 @@
         queryProgram,
         queryRunOptions,
         formatTriples,
-        formatTrace,
+        formatProof,
         formatBindings,
         toJSON,
         resultTriples,
@@ -41,15 +41,28 @@
       
       const VERSION = readPackageVersion();
       
-      function help() {
+      function legacyHelp() {
         return `eyeleng ${VERSION}\n\nA dependency-free JavaScript implementation experiment for the SHACL 1.2 Rules draft, including SRL and RDF Rules syntax front-ends.\n\nUsage:\n  eyeleng [options] [file ...]\n\nOptions:\n  --all                 Print the full closure, including input facts\n  --json                Print JSON instead of compact triples/bindings\n  --trace               Print derivation trace to stderr, or include it in JSON\n  --stats               Print iteration and triple counts to stderr\n  --check               Parse and analyze only; do not run rules\n  --strict              Treat static warnings as errors, including recursive term generation\n  --deps                Print rule dependency edges during --check\n  --query TEXT          Run a raw SRL body pattern over the closure or backward planner\n  --query-file FILE     Read a raw SRL body pattern from a file\n  --query-mode MODE     Use auto, forward, or backward query planning (default auto)\n  --hybrid              Force aggressive hybrid orientation for function-like rules\n  --no-hybrid           Disable automatic hybrid forward/backward execution\n  --max-iterations N    Stop after N fixpoint iterations within a recursive layer\n  --no-imports          Parse IMPORTS/owl:imports but do not load imported rule sets\n  --rdf-messages        Parse input as an RDF Message Log\n  --include-message-facts Include payload facts while parsing RDF Message Logs\n  --syntax MODE         Use srl, rdf, or auto syntax detection (default auto)\n  --ruleset TERM        In RDF syntax, run only the selected srl:RuleSet\n  --version             Print version\n  -h, --help            Print this help\n\nWith no file arguments, eyeleng reads from stdin.\n`;
       }
       
+      function help() {
+        return legacyHelp().replace(
+          '  --trace               Print derivation trace to stderr, or include it in JSON',
+          '  --prove               Print proof explanations',
+        ).replace(
+          'Usage:\n  eyeleng [options] [file ...]',
+          'Usage: eyeleng [options] [file-or-url.n3|- ...]',
+        ).replace(
+          'With no file arguments, eyeleng reads from stdin.',
+          'With no input arguments, eyeleng prints this help. Use - to read from stdin.',
+        );
+      }
+      
       function parseArgs(argv) {
         const options = {
           all: false,
           json: false,
-          trace: false,
+          prove: false,
           stats: false,
           check: false,
           strict: false,
@@ -70,7 +83,7 @@
           const arg = argv[i];
           if (arg === '--all') options.all = true;
           else if (arg === '--json') options.json = true;
-          else if (arg === '--trace') options.trace = true;
+          else if (arg === '--prove') options.prove = true;
           else if (arg === '--stats') options.stats = true;
           else if (arg === '--check') options.check = true;
           else if (arg === '--strict') options.strict = true;
@@ -111,6 +124,8 @@
             options.version = true;
           } else if (arg === '-h' || arg === '--help') {
             options.help = true;
+          } else if (arg === '-') {
+            files.push(arg);
           } else if (arg.startsWith('-')) {
             throw new Error(`Unknown option ${arg}`);
           } else {
@@ -121,13 +136,26 @@
         return { options, files };
       }
       
-      function readInput(files) {
-        if (files.length === 0) return { source: fs.readFileSync(0, 'utf8'), filename: '<stdin>', baseIRI: null };
-        if (files.length === 1) {
-          const filename = path.resolve(files[0]);
-          return { source: fs.readFileSync(filename, 'utf8'), filename, baseIRI: pathToFileURL(filename).href };
+      async function readInput(files, fetchImpl = globalThis.fetch) {
+        const inputs = [];
+        let readStdin = false;
+        for (const spec of files) {
+          if (spec === '-') {
+            if (readStdin) throw new Error('Standard input (-) may only be specified once');
+            readStdin = true;
+            inputs.push({ source: fs.readFileSync(0, 'utf8'), filename: '<stdin>', baseIRI: null });
+          } else if (/^https?:\/\//i.test(spec)) {
+            if (typeof fetchImpl !== 'function') throw new Error(`Cannot fetch URL ${spec}: fetch is unavailable`);
+            const response = await fetchImpl(spec);
+            if (!response.ok) throw new Error(`Cannot fetch URL ${spec}: HTTP ${response.status}${response.statusText ? ` ${response.statusText}` : ''}`);
+            inputs.push({ source: await response.text(), filename: spec, baseIRI: spec });
+          } else {
+            const filename = path.resolve(spec);
+            inputs.push({ source: fs.readFileSync(filename, 'utf8'), filename, baseIRI: pathToFileURL(filename).href });
+          }
         }
-        return { source: files.map((file) => fs.readFileSync(file, 'utf8')).join('\n'), filename: '<input>', baseIRI: null };
+        if (inputs.length === 1) return inputs[0];
+        return { source: inputs.map((input) => input.source).join('\n'), filename: '<input>', baseIRI: null };
       }
       
       function createFileImportResolver() {
@@ -172,7 +200,7 @@
         return /^https?:/.test(name) ? compactIRI(name, prefixes) : name;
       }
       
-      function main(argv = process.argv.slice(2), io = process) {
+      async function main(argv = process.argv.slice(2), io = process) {
         try {
           const { options, files } = parseArgs(argv);
           if (options.help) {
@@ -183,7 +211,11 @@
             io.stdout.write(`${VERSION}\n`);
             return 0;
           }
-          const input = readInput(files);
+          if (files.length === 0) {
+            io.stdout.write(help());
+            return 0;
+          }
+          const input = await readInput(files);
           const compiled = compile(input.source, {
             filename: input.filename,
             baseIRI: input.baseIRI,
@@ -245,15 +277,18 @@
           }
       
           if (options.json) {
-            io.stdout.write(`${JSON.stringify(toJSON(result, { all: options.all, trace: options.trace, analysis: options.deps }), null, 2)}\n`);
+            io.stdout.write(`${JSON.stringify(toJSON(result, { all: options.all, proof: options.prove, analysis: options.deps }), null, 2)}\n`);
           } else if (result.query) {
             const out = formatBindings(result.query.bindings, result.prefixes, result.query.select);
             if (out) io.stdout.write(`${out}\n`);
           } else {
-            if (options.trace && result.trace.length > 0) io.stderr.write(`${formatTrace(result.trace, result.prefixes)}\n`);
             const triples = resultTriples(result, compiled.program, options);
             const out = formatTriples(triples, result.prefixes);
             if (out) io.stdout.write(`${out}\n`);
+            if (options.prove) {
+              const proof = formatProof(result.trace, result.prefixes);
+              if (proof) io.stdout.write(`${out ? '\n' : ''}${proof}\n`);
+            }
           }
       
           if (options.stats) {
@@ -271,9 +306,9 @@
         }
       }
       
-      if (require.main === module) process.exitCode = main();
+      if (require.main === module) main().then((code) => { process.exitCode = code; });
       
-      module.exports = { main, parseArgs, help, VERSION, createFileImportResolver };
+      module.exports = { main, parseArgs, readInput, help, VERSION, createFileImportResolver };
       
     },
     "src/api.js": function (require, module, exports) {
@@ -284,7 +319,7 @@
       const { parseRdfMessageLog, looksLikeRdfMessageLog } = require('./rdfMessages.js');
       const { evaluate } = require('./engine.js');
       const { analyze } = require('./analyze.js');
-      const { formatTriples, sortTriples, toJSON, formatTrace, formatBindings } = require('./format.js');
+      const { formatTriples, sortTriples, toJSON, formatTrace, formatProof, formatBindings } = require('./format.js');
       const { runQuery, queryResult, queryProgram, queryRunOptions, shouldUseHybridForQuery } = require('./query.js');
       const { resultTriples } = require('./output.js');
       
@@ -407,6 +442,7 @@
         sortTriples,
         toJSON,
         formatTrace,
+        formatProof,
         resultTriples,
       };
       
@@ -710,7 +746,7 @@
         }
       
         parseTripleStatement(options = {}) {
-          const subjectNode = this.parseGraphNode(options);
+          const subjectNode = this.parseGraphNode({ ...options, position: 'subject' });
           const triples = [...subjectNode.triples];
           triples.push(...this.parsePropertyListForSubject(subjectNode.term, options));
           return triples;
@@ -724,7 +760,7 @@
             if (terminators.some((value) => this.checkValue(value)) || this.checkValue('.')) break;
             const predicate = options.allowPath ? this.parseVerbPathOrSimple(options) : this.parseVerbTerm(options);
             do {
-              const objectNode = this.parseGraphNode(options);
+              const objectNode = this.parseGraphNode({ ...options, position: 'object' });
               triples.push(...objectNode.triples);
               const baseTriple = { s: subject, p: predicate, o: objectNode.term };
               triples.push(baseTriple);
@@ -791,6 +827,7 @@
               currentReifier = this.parseOptionalReifier(options);
               triples.push({ s: currentReifier, p: iri(RDF_REIFIES), o: reified });
             } else if (this.matchValue('{|')) {
+              if (this.checkValue('|}')) throw this.error('Annotation blocks may not be empty');
               const annotationSubject = currentReifier || this.freshGraphNode(options);
               triples.push({ s: annotationSubject, p: iri(RDF_REIFIES), o: reified });
               triples.push(...this.parsePropertyListForSubject(annotationSubject, options, ['|}']));
@@ -840,7 +877,7 @@
         }
       
         parseVerbTerm(options = {}) {
-          const term = this.parseTerm(options);
+          const term = this.parseTerm({ ...options, position: 'predicate' });
           if (term.type !== 'iri' && term.type !== 'var') throw this.error('Expected IRI or variable as predicate');
           return term;
         }
@@ -963,7 +1000,10 @@
           if (token.value === '<<(') return this.parseTripleTermAfterOpen(options);
           if (token.value === '<<') throw this.error('Use << s p o >> as a graph node reifier; use <<( s p o )>> for a triple term', token);
           if (token.type === 'word') {
-            if (token.value === 'a') return iri(RDF_TYPE);
+            if (token.value === 'a') {
+              if (options.position !== 'predicate') throw this.error('a is only allowed as a predicate', token);
+              return iri(RDF_TYPE);
+            }
             if (token.value === 'true') return literal(true, XSD_BOOLEAN);
             if (token.value === 'false') return literal(false, XSD_BOOLEAN);
             if (token.value.startsWith('_:')) return blankNode(token.value.slice(2));
@@ -997,7 +1037,13 @@
             return literal(coerceLexicalLiteral(token.value, datatype), datatype, null);
           }
           if (this.checkType('word') && /^@[A-Za-z]+(?:-[A-Za-z0-9]+)*(?:--[A-Za-z]+)?$/.test(this.peek().value)) {
-            const tag = this.advance().value.slice(1).toLowerCase();
+            const tagToken = this.advance();
+            const rawTag = tagToken.value.slice(1);
+            const direction = rawTag.includes('--') ? rawTag.slice(rawTag.lastIndexOf('--') + 2) : null;
+            if (direction && direction !== 'ltr' && direction !== 'rtl') {
+              throw this.error(`Invalid base direction --${direction}; expected --ltr or --rtl`, tagToken);
+            }
+            const tag = rawTag.toLowerCase();
             const [lang, langDir = null] = tag.split('--');
             return literal(token.value, null, lang, langDir);
           }
@@ -2776,6 +2822,7 @@
         const syntaxProfile = String(options.profile || options.profileId || '').toLowerCase();
         const rdf12Surface = syntaxProfile === 'turtle' || syntaxProfile === 'trig';
         const implicitStatementNodes = new Set();
+        function implicitStatementNodeKey(term) { return `${term.kind}:${term.value}`; }
       
         function freshBlank() { bnodeCounter += 1; return blank(`b${bnodeCounter}`); }
         function peek(offset = 0) { return tokens[i + offset]; }
@@ -2926,7 +2973,7 @@
           expect('>>');
           const node = reifier || freshBlank();
           out.push(triple(node, iri(RDF_REIFIES), tripleTerm(s, p, o), graph));
-          if (node.kind === 'blank') implicitStatementNodes.add(node.value);
+          implicitStatementNodes.add(implicitStatementNodeKey(node));
           return node;
         }
       
@@ -2955,7 +3002,7 @@
           if (accept(']')) return node;
           parsePredicateObjectList(node, out, graph);
           expect(']');
-          if (node.kind === 'blank') implicitStatementNodes.add(node.value);
+          if (node.kind === 'blank') implicitStatementNodes.add(implicitStatementNodeKey(node));
           return node;
         }
       
@@ -3033,9 +3080,8 @@
             if (options3.requireDot) expect('.'); else accept('.');
             return;
           }
-          if (peek()?.type === '<<' && peek(1)?.type === '(') throw new Error('Triple term cannot be used as a subject');
-          const subject = parseTerm(out, graph, { noLiteral: true, noA: true });
-          if ((peek()?.type === '.' || peek()?.type === '}' || peek()?.type === undefined) && subject.kind === 'blank' && implicitStatementNodes.has(subject.value)) {
+          const subject = parseTerm(out, graph, { noLiteral: !rdf12Surface, noA: true });
+          if ((peek()?.type === '.' || peek()?.type === '}' || peek()?.type === undefined) && implicitStatementNodes.has(implicitStatementNodeKey(subject))) {
             if (options3.requireDot) expect('.'); else accept('.');
             return;
           }
@@ -4522,6 +4568,7 @@
                   rule: rule.name || `rule#${ruleIndex + 1}`,
                   triple,
                   binding,
+                  uses: proofUses(rule.body, binding),
                 });
               }
             }
@@ -4532,6 +4579,17 @@
         return { applications, added };
       }
       
+      function proofUses(body, binding) {
+        return body
+          .filter((clause) => clause.type === 'triple')
+          .map((clause) => ({
+            s: instantiateTerm(clause.triple.s, binding),
+            p: instantiateTerm(clause.triple.p, binding),
+            o: instantiateTerm(clause.triple.o, binding),
+          }))
+          .filter((triple) => ![triple.s, triple.p, triple.o].some((term) => term && term.type === 'var'));
+      }
+      
       function prepareBodyContext(program, store, context) {
         if (!context.hybridBackwardPredicates || context.hybridBackwardPredicates.size === 0) return context;
         return {
@@ -6322,6 +6380,35 @@
         return trace.map((entry) => `#${entry.iteration} ${entry.rule} => ${formatTriple(entry.triple, prefixes)}`).join('\n');
       }
       
+      function formatProof(trace, prefixes = {}) {
+        if (!trace.length) return '';
+        const lines = ['@prefix pe: <https://eyereasoner.github.io/pe#> .', ''];
+        for (const entry of trace) {
+          const conclusion = formatTriple(entry.triple, prefixes);
+          lines.push(`{ ${conclusion} } pe:why {`);
+          lines.push(`  { ${conclusion} }`);
+          lines.push(`    pe:by [ pe:rule ${quoteString(entry.rule)} ]${proofDetails(entry, prefixes)} .`);
+          lines.push('}.', '');
+        }
+        return lines.join('\n').trimEnd();
+      }
+      
+      function proofDetails(entry, prefixes) {
+        const details = [];
+        const bindings = Object.entries(entry.binding || {}).sort(([a], [b]) => a.localeCompare(b));
+        if (bindings.length > 0) {
+          details.push(`\n    pe:binding ${bindings.map(([name, value]) => `[ pe:var ${quoteString(name)}; pe:value ${formatTerm(value, prefixes)} ]`).join(', ')}`);
+        }
+        if (entry.uses && entry.uses.length > 0) {
+          details.push(`\n    pe:uses ${entry.uses.map((triple) => `{ ${formatTriple(triple, prefixes)} }`).join(', ')}`);
+        }
+        return details.length ? `;${details.join(';')}` : '';
+      }
+      
+      function quoteString(value) {
+        return `"${String(value).replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n')}"`;
+      }
+      
       function formatBindings(bindings, prefixes = {}, select = null) {
         const columns = select && select.length > 0 ? select : inferColumns(bindings);
         return bindings
@@ -6353,7 +6440,7 @@
           prefixes: result.prefixes,
           diagnostics: result.diagnostics || [],
           triples: sortTriples(triples, result.prefixes).map(jsonSafeTriple),
-          trace: options.trace ? result.trace : undefined,
+          proof: options.proof ? result.trace : undefined,
         };
         if (result.query) json.query = jsonSafeValue(result.query);
         if (result.analysis && options.analysis) json.analysis = result.analysis;
@@ -6382,7 +6469,7 @@
         return value;
       }
       
-      module.exports = { sortTriples, formatTriples, formatTrace, formatBindings, formatBinding, toJSON };
+      module.exports = { sortTriples, formatTriples, formatTrace, formatProof, formatBindings, formatBinding, toJSON };
       
     },
     "src/query.js": function (require, module, exports) {
@@ -6534,5 +6621,7 @@
     __modules[id](localRequire, module, module.exports);
     return module.exports;
   }
-  process.exitCode = __require("src/cli.js").main(process.argv.slice(2));
+  Promise.resolve(__require("src/cli.js").main(process.argv.slice(2)))
+    .then((code) => { process.exitCode = code; })
+    .catch((error) => { console.error(error); process.exitCode = 1; });
 }());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eyeleng",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "The EYE Logic Engine: a JavaScript implementation of SHACL Rules, including SRL and RDF Rules syntax front-ends.",
   "keywords": [
     "SRL",

package/playground.html

@@ -438,7 +438,7 @@
           <div class="checks" aria-label="Reasoning options">
             <label class="toggle"><input id="all-output" type="checkbox" /> Print full closure (--all)</label>
             <label class="toggle"><input id="json-output" type="checkbox" /> JSON output (--json)</label>
-            <label class="toggle"><input id="trace-output" type="checkbox" /> Include derivation trace (--trace)</label>
+            <label class="toggle"><input id="trace-output" type="checkbox" /> Include proof explanations (--prove)</label>
             <label class="toggle"><input id="strict-mode" type="checkbox" /> Treat warnings as errors (--strict)</label>
             <label class="toggle"><input id="check-only" type="checkbox" /> Check only, do not run rules</label>
             <label class="toggle"><input id="show-analysis" type="checkbox" /> Include analysis in JSON</label>
@@ -946,7 +946,7 @@
           if (els.json.checked) {
             text = JSON.stringify(eyeleng.toJSON(result, {
               all: els.all.checked,
-              trace: els.trace.checked,
+              proof: els.trace.checked,
               analysis: els.analysis.checked,
             }), null, 2);
           } else if (result.query) {
@@ -955,8 +955,8 @@
             const triples = els.all.checked ? result.closure : result.inferred;
             text = eyeleng.formatTriples(triples, result.prefixes);
             if (els.trace.checked && result.trace.length > 0) {
-              const trace = eyeleng.formatTrace(result.trace, result.prefixes);
-              text = (text ? text + '\n\n' : '') + '# Trace\n' + trace;
+              const proof = eyeleng.formatProof(result.trace, result.prefixes);
+              text = (text ? text + '\n\n' : '') + proof;
             }
           }
           if (!text) text = '(no output)';