eyeleng 1.1.2 → 1.2.1

package/src/api.js

@@ -5,7 +5,7 @@ const { parseRdfSyntax, parseRdfDocument, rdfDocumentToProgram, looksLikeRdfRule
 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');
 
@@ -128,5 +128,6 @@ module.exports = {
   sortTriples,
   toJSON,
   formatTrace,
+  formatProof,
   resultTriples,
 };

package/src/cli.js

@@ -11,7 +11,7 @@ const {
   queryProgram,
   queryRunOptions,
   formatTriples,
-  formatTrace,
+  formatProof,
   formatBindings,
   toJSON,
   resultTriples,
@@ -35,15 +35,28 @@ function readPackageVersion() {
 
 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,
@@ -64,7 +77,7 @@ function parseArgs(argv) {
     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;
@@ -105,6 +118,8 @@ function parseArgs(argv) {
       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 {
@@ -115,13 +130,26 @@ function parseArgs(argv) {
   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() {
@@ -166,7 +194,7 @@ function formatRuleName(name, prefixes = {}) {
   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) {
@@ -177,7 +205,11 @@ function main(argv = process.argv.slice(2), io = process) {
       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,
@@ -239,15 +271,18 @@ function main(argv = process.argv.slice(2), io = process) {
     }
 
     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) {
@@ -265,6 +300,6 @@ function main(argv = process.argv.slice(2), io = process) {
   }
 }
 
-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 };

package/src/engine.js

@@ -202,6 +202,7 @@ function applyRuleOnce(program, store, ruleIndex, context) {
             rule: rule.name || `rule#${ruleIndex + 1}`,
             triple,
             binding,
+            uses: proofUses(rule.body, binding),
           });
         }
       }
@@ -212,6 +213,17 @@ function applyRuleOnce(program, store, ruleIndex, context) {
   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 {

package/src/format.js

@@ -20,6 +20,35 @@ function formatTrace(trace, prefixes = {}) {
   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
@@ -51,7 +80,7 @@ function toJSON(result, options = {}) {
     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;
@@ -80,4 +109,4 @@ function jsonSafeValue(value) {
   return value;
 }
 
-module.exports = { sortTriples, formatTriples, formatTrace, formatBindings, formatBinding, toJSON };
+module.exports = { sortTriples, formatTriples, formatTrace, formatProof, formatBindings, formatBinding, toJSON };

package/test/browser-bundle.test.js

@@ -44,6 +44,27 @@ test('playground inline scripts are syntactically valid', () => {
   assert.ok(checked > 0, 'expected at least one inline playground script');
 });
 
+test('playground embedded API exposes proof formatting', () => {
+  const html = fs.readFileSync(path.join(root, 'playground.html'), 'utf8');
+  const scripts = Array.from(html.matchAll(/<script(?<attrs>[^>]*)>(?<source>[\s\S]*?)<\/script>/g));
+  const bundleScript = scripts.find((match) => /__EYELENG_MODULES__/.test(match.groups.source));
+  assert.ok(bundleScript, 'expected an embedded playground API bundle');
+  const context = vm.createContext({ window: {} });
+  vm.runInContext(bundleScript.groups.source, context);
+  const modules = context.window.__EYELENG_MODULES__;
+  const mappings = context.window.__EYELENG_MAPPINGS__;
+  const cache = {};
+  function requireModule(id) {
+    if (cache[id]) return cache[id].exports;
+    const module = { exports: {} };
+    cache[id] = module;
+    const localRequire = (request) => requireModule((mappings[id] && mappings[id][request]) || request);
+    new Function('require', 'module', 'exports', modules[id])(localRequire, module, module.exports);
+    return module.exports;
+  }
+  assert.equal(typeof requireModule('src/api.js').formatProof, 'function');
+});
+
 
 test('playground loads version from package.json at runtime', () => {
   const html = fs.readFileSync(path.join(root, 'playground.html'), 'utf8');

package/test/cli.test.js

@@ -4,7 +4,7 @@ const assert = require('node:assert/strict');
 const fs = require('node:fs');
 const path = require('node:path');
 const { test, main } = require('./harness.js').createHarness('CLI');
-const { help, parseArgs } = require('../src/cli.js');
+const { help, parseArgs, readInput, main: cliMain } = require('../src/cli.js');
 
 function longOptions(text) {
   return Array.from(text.matchAll(/(^|\s)(--[a-z][a-z0-9-]*)\b/gm), (match) => match[2])
@@ -37,6 +37,11 @@ test('RDF Message Log flags are accepted by parseArgs', () => {
   assert.equal(parseArgs(['--include-message-facts']).options.includeMessageFacts, true);
 });
 
+test('--prove enables proof explanations and --trace is rejected', () => {
+  assert.equal(parseArgs(['--prove']).options.prove, true);
+  assert.throws(() => parseArgs(['--trace']), /Unknown option --trace/);
+});
+
 test('query mode flag is accepted by parseArgs', () => {
   assert.equal(parseArgs(['--query-mode', 'auto']).options.queryMode, 'auto');
   assert.equal(parseArgs(['--query-mode', 'forward']).options.queryMode, 'forward');
@@ -49,4 +54,31 @@ test('query mode flag is accepted by parseArgs', () => {
   assert.throws(() => parseArgs(['--stream-messages']), /Unknown option --stream-messages/);
 });
 
+test('stdin marker and URLs are accepted as inputs', async () => {
+  assert.deepEqual(parseArgs(['-']).files, ['-']);
+  assert.deepEqual(parseArgs(['https://example.test/rules.n3']).files, ['https://example.test/rules.n3']);
+  const input = await readInput(['https://example.test/rules.n3'], async () => ({
+    ok: true,
+    text: async () => 'DATA { <a> <b> <c> }',
+  }));
+  assert.equal(input.filename, 'https://example.test/rules.n3');
+  assert.equal(input.baseIRI, 'https://example.test/rules.n3');
+});
+
+test('no arguments print the same help as -h', async () => {
+  function capture() {
+    let stdout = '';
+    let stderr = '';
+    return {
+      io: { stdout: { write: (text) => { stdout += text; } }, stderr: { write: (text) => { stderr += text; } } },
+      output: () => ({ stdout, stderr }),
+    };
+  }
+  const empty = capture();
+  const explicit = capture();
+  assert.equal(await cliMain([], empty.io), 0);
+  assert.equal(await cliMain(['-h'], explicit.io), 0);
+  assert.deepEqual(empty.output(), explicit.output());
+});
+
 main();

package/tools/browser-bundle.js

@@ -129,6 +129,7 @@ function buildModuleWrapper() {
     'sortTriples',
     'toJSON',
     'formatTrace',
+    'formatProof',
   ];
 
   const chunks = [];

package/tools/bundle.js

@@ -106,7 +106,9 @@ function buildCli() {
   chunks.push('    __modules[id](localRequire, module, module.exports);');
   chunks.push('    return module.exports;');
   chunks.push('  }');
-  chunks.push(`  process.exitCode = __require(${js(cliEntry)}).main(process.argv.slice(2));`);
+  chunks.push(`  Promise.resolve(__require(${js(cliEntry)}).main(process.argv.slice(2)))`);
+  chunks.push('    .then((code) => { process.exitCode = code; })');
+  chunks.push("    .catch((error) => { console.error(error); process.exitCode = 1; });");
   chunks.push('}());');
   chunks.push('');
 
@@ -149,6 +151,41 @@ function buildBrowser() {
   writeFile(browserOutput, chunks);
 }
 
+function updatePlaygroundBundle() {
+  const { modules, mappings } = collectGraph('src/api.js');
+  const fallbackNames = [
+    'family.srl',
+    'socrates.srl',
+    'spec-2-2-recursion.srl',
+    'bmi.srl',
+    'stratified-negation.srl',
+    'spec-builtins.srl',
+    'spec-4-2-rdf-rules-syntax.ttl',
+    'basic-ruleset.ttl',
+  ];
+  const examples = {};
+  for (const name of fallbackNames) {
+    examples[name] = fs.readFileSync(path.join(root, 'examples', name), 'utf8');
+  }
+
+  const filename = path.join(root, playgroundOutput);
+  let html = fs.readFileSync(filename, 'utf8');
+  html = html.replace(
+    /^    window\.__EYELENG_MODULES__ = .*;$/m,
+    () => `    window.__EYELENG_MODULES__ = ${js(Object.fromEntries(modules.entries()))};`,
+  );
+  html = html.replace(
+    /^    window\.__EYELENG_MAPPINGS__ = .*;$/m,
+    () => `    window.__EYELENG_MAPPINGS__ = ${js(Object.fromEntries(mappings.entries()))};`,
+  );
+  html = html.replace(
+    /^    window\.__EYELENG_EXAMPLES__ = .*;$/m,
+    () => `    window.__EYELENG_EXAMPLES__ = ${js(examples)};`,
+  );
+  fs.writeFileSync(filename, html, 'utf8');
+  console.log(`updated ${playgroundOutput}`);
+}
+
 function indent(source, spaces) {
   const prefix = ' '.repeat(spaces);
   return source.split('\n').map((line) => prefix + line).join('\n');
@@ -156,3 +193,4 @@ function indent(source, spaces) {
 
 buildCli();
 buildBrowser();
+updatePlaygroundBundle();