eyeling 1.17.2 → 1.18.1

package/lib/builtins.js

@@ -61,6 +61,152 @@ function __useNumericCacheKey(key) {
   return typeof key === 'string' && key.length <= MAX_NUMERIC_CACHE_KEY_LEN;
 }
 
+// ---------------------------------------------------------------------------
+// Custom builtin registry
+// ---------------------------------------------------------------------------
+const __customBuiltinHandlers = new Map(); // predicate IRI -> evaluator(ctx) => deltas[]
+const __loadedBuiltinModuleIds = new Set();
+
+function __validateBuiltinIri(iri) {
+  if (typeof iri !== 'string' || !iri) {
+    throw new TypeError('Custom builtin IRI must be a non-empty string');
+  }
+}
+
+function registerBuiltin(iri, handler) {
+  __validateBuiltinIri(iri);
+  if (typeof handler !== 'function') {
+    throw new TypeError(`Custom builtin ${iri} must be registered with a function handler`);
+  }
+  __customBuiltinHandlers.set(iri, handler);
+  return handler;
+}
+
+function unregisterBuiltin(iri) {
+  return __customBuiltinHandlers.delete(iri);
+}
+
+function listBuiltinIris() {
+  return Array.from(__customBuiltinHandlers.keys()).sort();
+}
+
+function __buildBuiltinRegistrationApi() {
+  return {
+    registerBuiltin,
+    unregisterBuiltin,
+    listBuiltinIris,
+    internIri,
+    internLiteral,
+    literalParts,
+    termToJsString,
+    termToJsStringDecoded,
+    termToN3,
+    iriValue,
+    unifyTerm,
+    applySubstTerm,
+    applySubstTriple,
+    proveGoals,
+    isGroundTerm,
+    computeConclusionFromFormula,
+    skolemIriFromGroundTerm,
+    parseBooleanLiteralInfo,
+    parseNumericLiteralInfo,
+    parseXsdDecimalToBigIntScale,
+    pow10n,
+    normalizeLiteralForFastKey,
+    literalsEquivalentAsXsdString,
+    materializeRdfLists,
+    terms: { Literal, Iri, Var, Blank, ListTerm, OpenListTerm, GraphTerm, Triple, Rule },
+    ns: { RDF_NS, XSD_NS, CRYPTO_NS, MATH_NS, TIME_NS, LIST_NS, LOG_NS, STRING_NS },
+  };
+}
+
+function registerBuiltinModule(mod, origin = '<builtin-module>') {
+  if (!mod) throw new TypeError(`Builtin module ${origin} did not export anything`);
+
+  const api = __buildBuiltinRegistrationApi();
+
+  if (typeof mod === 'function') {
+    mod(api);
+    return true;
+  }
+
+  if (typeof mod.register === 'function') {
+    mod.register(api);
+    return true;
+  }
+
+  const candidates = [];
+  if (mod && typeof mod.builtins === 'object' && mod.builtins) candidates.push(mod.builtins);
+  if (mod && typeof mod.default === 'object' && mod.default) candidates.push(mod.default);
+  candidates.push(mod);
+
+  let registeredAny = false;
+  for (const obj of candidates) {
+    if (!obj || typeof obj !== 'object' || Array.isArray(obj)) continue;
+    for (const [iri, handler] of Object.entries(obj)) {
+      if (typeof handler !== 'function') continue;
+      registerBuiltin(iri, handler);
+      registeredAny = true;
+    }
+    if (registeredAny) return true;
+  }
+
+  throw new TypeError(
+    `Builtin module ${origin} must export a function, a { register() } object, or an object mapping predicate IRIs to handlers`,
+  );
+}
+
+function loadBuiltinModule(specifier, options = {}) {
+  if (typeof require !== 'function') {
+    throw new Error('Custom builtin modules can only be loaded when require() is available');
+  }
+  if (typeof specifier !== 'string' || !specifier) {
+    throw new TypeError('Builtin module specifier must be a non-empty string');
+  }
+
+  const path = require('node:path');
+  const resolved = options && options.resolveFrom ? path.resolve(options.resolveFrom, specifier) : specifier;
+  const moduleId = String(resolved);
+  if (__loadedBuiltinModuleIds.has(moduleId)) return moduleId;
+
+  const loaded = require(resolved);
+  registerBuiltinModule(loaded, moduleId);
+  __loadedBuiltinModuleIds.add(moduleId);
+  return moduleId;
+}
+
+function __evalRegisteredBuiltin(pv, goal, subst, facts, backRules, depth, varGen, maxResults) {
+  const handler = __customBuiltinHandlers.get(pv);
+  if (typeof handler !== 'function') return null;
+
+  const ctx = {
+    iri: pv,
+    goal,
+    subst,
+    facts,
+    backRules,
+    depth,
+    varGen,
+    maxResults,
+    api: __buildBuiltinRegistrationApi(),
+  };
+
+  try {
+    const out = handler(ctx);
+    if (out == null) return [];
+    if (!Array.isArray(out)) {
+      throw new TypeError(`Custom builtin ${pv} must return an array of substitution deltas`);
+    }
+    return out;
+  } catch (err) {
+    if (err && typeof err === 'object' && typeof err.message === 'string') {
+      err.message = `Error in custom builtin ${pv}: ${err.message}`;
+    }
+    throw err;
+  }
+}
+
 //
 // Engine hooks (injected once by makeBuiltins)
 //
@@ -1466,6 +1612,9 @@ function evalBuiltin(goal, subst, facts, backRules, depth, varGen, maxResults) {
     if (pv !== allow1 && pv !== allow2) return [];
   }
 
+  const registeredBuiltinResult = __evalRegisteredBuiltin(pv, g, subst, facts, backRules, depth, varGen, maxResults);
+  if (registeredBuiltinResult !== null) return registeredBuiltinResult;
+
   // -----------------------------------------------------------------
   // 4.1 crypto: builtins
   // -----------------------------------------------------------------
@@ -3677,6 +3826,8 @@ function isBuiltinPred(p) {
     return true;
   }
 
+  if (__customBuiltinHandlers.has(v)) return true;
+
   return (
     v.startsWith(CRYPTO_NS) ||
     v.startsWith(MATH_NS) ||
@@ -3834,6 +3985,11 @@ function listHasTriple(list, tr) {
 
 module.exports = {
   makeBuiltins,
+  registerBuiltin,
+  unregisterBuiltin,
+  registerBuiltinModule,
+  loadBuiltinModule,
+  listBuiltinIris,
   // shared helpers used by engine/explain
   parseBooleanLiteralInfo,
   parseNumericLiteralInfo,

package/lib/cli.js

@@ -55,7 +55,7 @@ function main() {
       argv.push(a);
       continue;
     }
-    // Combined short flags (no flag in eyeling takes a value)
+    // Combined short flags (the long --builtin option takes a value)
     for (const ch of a.slice(1)) argv.push('-' + ch);
   }
   const prog = String(process.argv[1] || 'eyeling')
@@ -67,6 +67,7 @@ function main() {
       `Usage: ${prog} [options] <file.n3>\n\n` +
       `Options:\n` +
       `  -a, --ast                    Print parsed AST as JSON and exit.\n` +
+      `      --builtin <module.js>    Load a custom builtin module (repeatable).\n` +
       `  -d, --deterministic-skolem   Make log:skolem stable across reasoning runs.\n` +
       `  -e, --enforce-https          Rewrite http:// IRIs to https:// for log dereferencing builtins.\n` +
       `  -h, --help                   Show this help and exit.\n` +
@@ -89,6 +90,27 @@ function main() {
     process.exit(0);
   }
 
+  const builtinModules = [];
+  const positional = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--builtin') {
+      const next = argv[i + 1];
+      if (!next || next.startsWith('-')) {
+        console.error('Error: --builtin expects a module path.');
+        process.exit(1);
+      }
+      builtinModules.push(next);
+      i += 1;
+      continue;
+    }
+    if (typeof a === 'string' && a.startsWith('--builtin=')) {
+      builtinModules.push(a.slice('--builtin='.length));
+      continue;
+    }
+    if (!a.startsWith('-')) positional.push(a);
+  }
+
   const showAst = argv.includes('--ast') || argv.includes('-a');
   const streamMode = argv.includes('--stream') || argv.includes('-t');
 
@@ -113,7 +135,6 @@ function main() {
   }
 
   // Positional args (the N3 file)
-  const positional = argv.filter((a) => !a.startsWith('-'));
   if (positional.length === 0) {
     printHelp(false);
     process.exit(0);
@@ -124,6 +145,16 @@ function main() {
     process.exit(1);
   }
 
+  for (const spec of builtinModules) {
+    try {
+      if (typeof engine.loadBuiltinModule === 'function')
+        engine.loadBuiltinModule(spec, { resolveFrom: process.cwd() });
+    } catch (e) {
+      console.error(`Error loading builtin module ${JSON.stringify(spec)}: ${e && e.message ? e.message : String(e)}`);
+      process.exit(1);
+    }
+  }
+
   const filePath = positional[0];
   let text;
   try {

package/lib/engine.js

@@ -40,6 +40,11 @@ const { liftBlankRuleVars } = require('./rules');
 
 const {
   makeBuiltins,
+  registerBuiltin,
+  unregisterBuiltin,
+  registerBuiltinModule,
+  loadBuiltinModule,
+  listBuiltinIris,
   // helpers used by engine core
   parseBooleanLiteralInfo,
   parseNumericLiteralInfo,
@@ -526,6 +531,10 @@ const { evalBuiltin, isBuiltinPred } = makeBuiltins({
   termsEqualNoIntDecimal,
 });
 
+try {
+  registerBuiltinModule(require('./builtin-sudoku'), './builtin-sudoku');
+} catch (_) {}
+
 // Initialize proof/output helpers (implemented in lib/explain.js).
 const { printExplanation, collectOutputStringsFromFacts } = makeExplain({
   applySubstTerm,
@@ -3194,6 +3203,7 @@ function reasonStream(input, opts = {}) {
     enforceHttps = false,
     rdfjs = false,
     dataFactory = null,
+    builtinModules = null,
   } = opts;
 
   const parsedInput = normalizeParsedReasonerInputSync(input);
@@ -3203,6 +3213,12 @@ function reasonStream(input, opts = {}) {
   deref.setEnforceHttpsEnabled(!!enforceHttps);
   proofCommentsEnabled = !!proof;
 
+  if (Array.isArray(builtinModules)) {
+    for (const spec of builtinModules) loadBuiltinModule(spec);
+  } else if (typeof builtinModules === 'string' && builtinModules) {
+    loadBuiltinModule(builtinModules);
+  }
+
   let prefixes, triples, frules, brules, logQueryRules;
 
   if (parsedInput) {
@@ -3427,4 +3443,9 @@ module.exports = {
   setTracePrefixes,
   getDeterministicSkolemEnabled,
   setDeterministicSkolemEnabled,
+  registerBuiltin,
+  unregisterBuiltin,
+  registerBuiltinModule,
+  loadBuiltinModule,
+  listBuiltinIris,
 };

package/package.json

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

package/test/api.test.js

@@ -1762,6 +1762,35 @@ _:x :hates { _:foo :making :mess }.
     },
     expect: [/http:\/\/example\.org\/ancestor/m],
   },
+  {
+    name: '240 custom builtin module can be loaded via --builtin',
+    run() {
+      const tmp = require('node:fs').mkdtempSync(
+        require('node:path').join(require('node:os').tmpdir(), 'eyeling-builtin-'),
+      );
+      const modPath = require('node:path').join(tmp, 'hello-builtin.js');
+      require('node:fs').writeFileSync(
+        modPath,
+        `module.exports = ({ registerBuiltin, internLiteral, unifyTerm, terms }) => {\n` +
+          `  const { Var } = terms;\n` +
+          `  registerBuiltin("http://example.org/custom#hello", ({ goal, subst }) => {\n` +
+          `    const lit = internLiteral("\\"world\\"");\n` +
+          `    if (goal.o instanceof Var) { const s2 = { ...subst }; s2[goal.o.name] = lit; return [s2]; }\n` +
+          `    const s2 = unifyTerm(goal.o, lit, subst);\n` +
+          `    return s2 !== null ? [s2] : [];\n` +
+          `  });\n` +
+          `};\n`,
+        'utf8',
+      );
+      const out = reasonQuiet(
+        { builtinModules: [modPath] },
+        `@prefix : <http://example.org/> .\n@prefix cb: <http://example.org/custom#> .\n{ :x cb:hello ?o . } => { :x :value ?o . } .\n:x cb:hello ?o .\n`,
+      );
+      require('node:fs').rmSync(tmp, { recursive: true, force: true });
+      return out;
+    },
+    expect: [/:x :value "world" \./m],
+  },
 ];
 
 let passed = 0;