eyelang 0.1.0

package/index.d.ts

@@ -0,0 +1,80 @@
+export interface EyelangStats {
+  [key: string]: number;
+}
+
+export interface EyelangRunOptions {
+  proof?: boolean;
+  why?: boolean;
+  explain?: boolean;
+  [key: string]: unknown;
+}
+
+export interface EyelangRunResult {
+  stdout: string;
+  stats: EyelangStats;
+}
+
+export interface EyelangSourcePart {
+  text?: string;
+  source?: string;
+  filename?: string;
+}
+
+export class Program {
+  constructor(clauses?: unknown[], options?: EyelangRunOptions);
+  static parse(source: string, options?: EyelangRunOptions): Program;
+  static parseSources(sources?: Array<string | EyelangSourcePart>, options?: EyelangRunOptions): Program;
+  materializationGoals(): unknown[];
+  sourceFactLines(predicateKeys?: Set<string> | null): Set<string>;
+}
+
+export function makeProgram(clauses?: unknown[], options?: EyelangRunOptions): Program;
+export function parseClauses(source: string, options?: EyelangRunOptions): unknown[];
+export function parseProgramText(source: string, options?: EyelangRunOptions): unknown[];
+
+export class Env {
+  constructor(parent?: Env | null);
+}
+
+export class Solver {
+  constructor(program: Program, options?: EyelangRunOptions);
+  stats: EyelangStats;
+  solve(goals: unknown[], env?: Env, depth?: number): Iterable<Env>;
+}
+
+export class BuiltinRegistry {
+  constructor();
+}
+
+export function createDefaultRegistry(): BuiltinRegistry;
+export function getDefaultRegistry(): BuiltinRegistry;
+
+export function run(source: string | Program, options?: EyelangRunOptions): EyelangRunResult;
+
+export function whyProof(program: Program, goal: unknown, options?: EyelangRunOptions): { ok: boolean; text: string };
+export function whyNoProof(goal: unknown): string;
+
+export const ATOM: 'atom';
+export const VARIABLE: 'variable';
+export const COMPOUND: 'compound';
+export const NUMBER: 'number';
+export const STRING: 'string';
+export function atom(name: string): unknown;
+export function variable(name: string): unknown;
+export function compound(name: string, args?: unknown[]): unknown;
+export function termToString(term: unknown, env?: Env, quoted?: boolean): string;
+
+declare const eyelang: {
+  run: typeof run;
+  Program: typeof Program;
+  makeProgram: typeof makeProgram;
+  parseClauses: typeof parseClauses;
+  parseProgramText: typeof parseProgramText;
+  Solver: typeof Solver;
+  Env: typeof Env;
+  BuiltinRegistry: typeof BuiltinRegistry;
+  createDefaultRegistry: typeof createDefaultRegistry;
+  getDefaultRegistry: typeof getDefaultRegistry;
+};
+
+export default eyelang;

package/index.js

@@ -0,0 +1,4 @@
+// Public Eyelang JavaScript API.
+export * from './src/index.js';
+import * as eyelang from './src/index.js';
+export default eyelang;

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "eyelang",
+  "version": "0.1.0",
+  "description": "A small logic programming language for rules, goals, answers, and proofs.",
+  "type": "module",
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "bin": {
+    "eyelang": "./bin/eyelang.js"
+  },
+  "keywords": [
+    "logic",
+    "rules",
+    "prolog",
+    "reasoner",
+    "proofs"
+  ],
+  "license": "MIT",
+  "author": "Jos De Roo",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/eyereasoner/eyelang.git"
+  },
+  "homepage": "https://github.com/eyereasoner/eyelang#readme",
+  "files": [
+    "LICENSE.md",
+    "README.md",
+    "index.js",
+    "index.d.ts",
+    "bin",
+    "src",
+    "docs",
+    "examples",
+    "test"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node test/run-all.mjs",
+    "test:eyelang": "node test/run-all.mjs",
+    "test:conformance": "node test/run-conformance.mjs",
+    "test:examples": "node test/run-examples.mjs",
+    "test:regression": "node test/run-regression.mjs",
+    "preversion": "npm test",
+    "postversion": "git push origin HEAD --follow-tags"
+  }
+}

package/src/bin.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+'use strict';
+
+import('./cli.js').then(({ main }) => main(process.argv.slice(2))).catch((error) => {
+  console.error(`eyelang: ${error && error.message ? error.message : String(error)}`);
+  process.exit(1);
+});

package/src/builtins/aggregation.js

@@ -0,0 +1,81 @@
+// Aggregation builtins that run a inner goal and collect, count, sum, or select the best answers.
+// Each handler clones the solver so the inner goal can enumerate independently of the outer goal.
+import { compareTerms, copyResolved, isDecimalInteger, lexicalValue, listFromItems, numberTerm, numberTextFromDouble, parseFiniteNumber, unify } from '../term.js';
+
+export const aggregationBuiltins = {
+  register(registry) {
+    registry.add('findall', 3, findall);
+    registry.add('countall', 2, countall);
+    registry.add('sumall', 3, sumall);
+    registry.add('aggregate_min', 5, aggregateBest(true));
+    registry.add('aggregate_max', 5, aggregateBest(false));
+  }
+};
+
+function* findall({ solver, goal, env }) {
+  const [template, innerGoal, bag] = goal.args;
+  const collector = solver.cloneForInnerGoal(10000000);
+  const collected = [];
+  for (const answerEnv of collector.solve([innerGoal], env.clone(), 0)) collected.push(copyResolved(template, answerEnv));
+  const next = env.clone();
+  if (unify(bag, listFromItems(collected), next)) yield next;
+}
+
+function* countall({ solver, goal, env }) {
+  const [innerGoal, count] = goal.args;
+  const collector = solver.cloneForInnerGoal(10000000);
+  let n = 0;
+  for (const _ of collector.solve([innerGoal], env.clone(), 0)) n++;
+  const next = env.clone();
+  if (unify(count, numberTerm(n), next)) yield next;
+}
+
+function* sumall({ solver, goal, env }) {
+  const [template, innerGoal, sum] = goal.args;
+  const collector = solver.cloneForInnerGoal(10000000);
+  let intSum = 0n;
+  let floatMode = false;
+  let floatSum = 0;
+  for (const answerEnv of collector.solve([innerGoal], env.clone(), 0)) {
+    const text = lexicalValue(template, answerEnv);
+    if (text == null) return;
+    if (!floatMode && isDecimalInteger(text)) intSum += BigInt(text);
+    else {
+      const value = parseFiniteNumber(text);
+      if (value == null) return;
+      if (!floatMode) { floatSum = Number(intSum); floatMode = true; }
+      floatSum += value;
+    }
+  }
+  const result = floatMode ? numberTextFromDouble(floatSum) : intSum.toString();
+  const next = env.clone();
+  if (unify(sum, numberTerm(result), next)) yield next;
+}
+
+function aggregateBest(wantMin) {
+  return function* ({ solver, goal, env }) {
+    const [keyTemplate, valueTemplate, innerGoal, bestKey, bestValue] = goal.args;
+    const collector = solver.cloneForInnerGoal(10000000);
+    let has = false;
+    let key = null;
+    let value = null;
+    for (const answerEnv of collector.solve([innerGoal], env.clone(), 0)) {
+      const candidateKey = copyResolved(keyTemplate, answerEnv);
+      const candidateValue = copyResolved(valueTemplate, answerEnv);
+      if (!has) {
+        has = true;
+        key = candidateKey;
+        value = candidateValue;
+      } else {
+        const cmp = compareTerms(candidateKey, key);
+        if ((wantMin && cmp < 0) || (!wantMin && cmp > 0)) {
+          key = candidateKey;
+          value = candidateValue;
+        }
+      }
+    }
+    if (!has) return;
+    const next = env.clone();
+    if (unify(bestKey, key, next) && unify(bestValue, value, next)) yield next;
+  };
+}

package/src/builtins/arithmetic.js

@@ -0,0 +1,208 @@
+// Numeric builtins for integer-preserving arithmetic, floating point functions, comparisons, and ranges.
+// The code keeps BigInt paths where possible so large eyelang integers remain exact.
+import { compareIntegerText, deref, isDecimalInteger, lexicalValue, numberTerm, numberTextFromDouble, parseFiniteNumber, unify } from '../term.js';
+
+const unaryNames = ['neg', 'abs', 'sin', 'cos', 'tan', 'asin', 'acos', 'sqrt', 'floor', 'ceiling', 'trunc', 'rounded', 'exp', 'log'];
+const binaryNames = ['add', 'sub', 'mul', 'div', 'mod', 'min', 'max', 'pow', 'atan2'];
+const compareNames = ['lt', 'gt', 'le', 'ge'];
+
+export const arithmeticBuiltins = {
+  register(registry) {
+    for (const name of unaryNames) registry.add(name, 2, unary(name), { deterministic: true });
+    for (const name of binaryNames) registry.add(name, 3, binary(name), { deterministic: true });
+    for (const name of compareNames) registry.add(name, 2, compare(name), { deterministic: true });
+    registry.add('between', 3, between);
+    registry.add('smallest_divisor_from', 3, smallestDivisorFrom, { deterministic: true });
+  }
+};
+
+
+function unary(name) {
+  return function* ({ goal, env }) {
+    const text = lexicalValue(goal.args[0], env);
+    if (text == null) return;
+    let out = null;
+    if ((name === 'neg' || name === 'abs' || name === 'floor' || name === 'ceiling' || name === 'trunc' || name === 'rounded') && isDecimalInteger(text)) {
+      const value = BigInt(text);
+      if (name === 'neg') out = (-value).toString();
+      else if (name === 'abs') out = (value < 0n ? -value : value).toString();
+      else out = value.toString();
+    } else {
+      const input = parseFiniteNumber(text);
+      if (input == null) return;
+      let value;
+      if (name === 'neg') value = -input;
+      else if (name === 'abs') value = Math.abs(input);
+      else if (name === 'sin') value = Math.sin(input);
+      else if (name === 'cos') value = Math.cos(input);
+      else if (name === 'tan') value = Math.tan(input);
+      else if (name === 'asin') value = Math.asin(input);
+      else if (name === 'acos') value = Math.acos(input);
+      else if (name === 'sqrt') { if (input < 0) return; value = Math.sqrt(input); }
+      else if (name === 'floor') value = Math.floor(input);
+      else if (name === 'ceiling') value = Math.ceil(input);
+      else if (name === 'trunc') value = Math.trunc(input);
+      else if (name === 'rounded') value = Math.round(input);
+      else if (name === 'exp') value = Math.exp(input);
+      else if (name === 'log') {
+        if (input <= 0) return;
+        value = logCompat(input);
+      }
+      out = (name === 'floor' || name === 'ceiling' || name === 'trunc' || name === 'rounded')
+        ? String(Math.trunc(value))
+        : numberTextFromDouble(value);
+    }
+    const next = env.clone();
+    if (out != null && unify(goal.args[1], numberTerm(out), next)) yield next;
+  };
+}
+
+function binary(name) {
+  return function* ({ goal, env }) {
+    const leftText = lexicalValue(goal.args[0], env);
+    const rightText = lexicalValue(goal.args[1], env);
+    if (leftText == null || rightText == null) return;
+    let out = null;
+    if (isDecimalInteger(leftText) && isDecimalInteger(rightText) && name !== 'mod' && name !== 'atan2') {
+      const a = BigInt(leftText);
+      const b = BigInt(rightText);
+      if (name === 'add') out = (a + b).toString();
+      else if (name === 'sub') out = (a - b).toString();
+      else if (name === 'mul') out = (a * b).toString();
+      else if (name === 'div') { if (b === 0n) return; out = (a / b).toString(); }
+      else if (name === 'min') out = (a <= b ? a : b).toString();
+      else if (name === 'max') out = (a >= b ? a : b).toString();
+      else if (name === 'pow') { if (b < 0n) return; out = (a ** b).toString(); }
+    } else if (name === 'mod') {
+      if (!isDecimalInteger(leftText) || !isDecimalInteger(rightText)) return;
+      const a = BigInt(leftText), b = BigInt(rightText);
+      if (b === 0n) return;
+      out = (a % b).toString();
+    } else {
+      const a = parseFiniteNumber(leftText), b = parseFiniteNumber(rightText);
+      if (a == null || b == null) return;
+      let value;
+      if (name === 'add') value = a + b;
+      else if (name === 'sub') value = a - b;
+      else if (name === 'mul') value = a * b;
+      else if (name === 'div') { if (b === 0) return; value = a / b; }
+      else if (name === 'pow') value = Math.pow(a, b);
+      else if (name === 'min') value = Math.min(a, b);
+      else if (name === 'max') value = Math.max(a, b);
+      else if (name === 'atan2') value = Math.atan2(a, b);
+      out = numberTextFromDouble(value);
+    }
+    const next = env.clone();
+    if (out != null && unify(goal.args[2], numberTerm(out), next)) yield next;
+  };
+}
+
+function compare(name) {
+  return function* ({ goal, env }) {
+    const left = lexicalValue(goal.args[0], env);
+    const right = lexicalValue(goal.args[1], env);
+    if (left == null || right == null) return;
+    const cmp = compareLexicalOrNumeric(left, right);
+    const pass = name === 'lt' ? cmp < 0 : name === 'gt' ? cmp > 0 : name === 'le' ? cmp <= 0 : cmp >= 0;
+    if (pass) yield env;
+  };
+}
+
+export function compareLexicalOrNumeric(left, right) {
+  if (isDecimalInteger(left) && isDecimalInteger(right)) return compareIntegerText(left, right);
+  const dur = compareDuration(left, right);
+  if (dur != null) return dur;
+  const a = parseFiniteNumber(left), b = parseFiniteNumber(right);
+  if (a != null && b != null) return a < b ? -1 : a > b ? 1 : 0;
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+function compareDuration(a, b) {
+  const pa = parseDuration(a), pb = parseDuration(b);
+  if (!pa || !pb) return null;
+  for (let i = 0; i < 3; i++) if (pa[i] !== pb[i]) return pa[i] < pb[i] ? -1 : 1;
+  return 0;
+}
+function parseDuration(text) {
+  const m = /^P(?:(\d+)Y)?(?:(\d+)M)?(?:(\d+)D)?$/.exec(text);
+  if (!m || (!m[1] && !m[2] && !m[3])) return null;
+  return [Number(m[1] ?? 0), Number(m[2] ?? 0), Number(m[3] ?? 0)];
+}
+
+function* between({ goal, env }) {
+  const lowText = lexicalValue(goal.args[0], env), highText = lexicalValue(goal.args[1], env);
+  if (!isDecimalInteger(lowText) || !isDecimalInteger(highText)) return;
+  const lowNumber = Number(lowText), highNumber = Number(highText);
+  const output = deref(goal.args[2], env);
+  if (Number.isSafeInteger(lowNumber) && Number.isSafeInteger(highNumber)) {
+    if (output.type === 'var') {
+      for (let value = lowNumber; value <= highNumber; value++) {
+        const next = env.clone();
+        next.bind(output.name, numberTerm(String(value)));
+        yield next;
+      }
+      return;
+    }
+    for (let value = lowNumber; value <= highNumber; value++) {
+      const next = env.clone();
+      if (unify(goal.args[2], numberTerm(String(value)), next)) yield next;
+    }
+    return;
+  }
+  const low = BigInt(lowText), high = BigInt(highText);
+  if (output.type === 'var') {
+    for (let value = low; value <= high; value++) {
+      const next = env.clone();
+      next.bind(output.name, numberTerm(value.toString()));
+      yield next;
+    }
+    return;
+  }
+  for (let value = low; value <= high; value++) {
+    const next = env.clone();
+    if (unify(goal.args[2], numberTerm(value.toString()), next)) yield next;
+  }
+}
+
+function* smallestDivisorFrom({ goal, env }) {
+  const nText = lexicalValue(goal.args[0], env), dText = lexicalValue(goal.args[1], env);
+  if (!isDecimalInteger(nText) || !isDecimalInteger(dText)) return;
+  const n = BigInt(nText), start = BigInt(dText);
+  if (n < 0n || start <= 0n) return;
+  let result = n;
+  for (let c = start; c > 0n && c <= n / c; c++) {
+    if (n % c === 0n) { result = c; break; }
+  }
+  const next = env.clone();
+  if (unify(goal.args[2], numberTerm(result.toString()), next)) yield next;
+}
+
+
+const f64 = new Float64Array(1);
+const u64 = new BigUint64Array(f64.buffer);
+
+function nextUp(value) {
+  if (!Number.isFinite(value)) return value;
+  if (value === 0) return Number.MIN_VALUE;
+  f64[0] = value;
+  u64[0] += value > 0 ? 1n : -1n;
+  return f64[0];
+}
+
+function nextDown(value) {
+  if (!Number.isFinite(value)) return value;
+  if (value === 0) return -Number.MIN_VALUE;
+  f64[0] = value;
+  u64[0] += value > 0 ? -1n : 1n;
+  return f64[0];
+}
+
+function logCompat(input) {
+  const value = Math.log(input);
+  // V8 and glibc libm differ by one ulp for a few values reached by the
+  // Newton-Raphson example. Align this pure-JS port with the native eyelang
+  // reference while leaving ordinary log(1), log(2), log(10), and log(e) alone.
+  if (input > 2.5 && input < 2.7182818 && value > 0.95 && value < 1.0) return nextUp(value);
+  if (input > 2.7182818 && input < 2.718281828459 && value > 0.999999999999 && value < 1.0) return nextDown(value);
+  return value;
+}

package/src/builtins/context.js

@@ -0,0 +1,42 @@
+// Context builtins that treat comma conjunctions as first-class data terms.
+// These are used by examples that construct or inspect rule bodies programmatically.
+import { atom, deref, isConjunction, listFromItems, unify } from '../term.js';
+
+export const contextBuiltins = {
+  register(registry) {
+    registry.add('holds', 2, holdsTerm);
+    registry.add('holds', 3, holdsParts);
+  }
+};
+
+function* emitContextTerm(context, term, env) {
+  context = deref(context, env);
+  if (isConjunction(context)) {
+    yield* emitContextTerm(context.args[0], term, env);
+    yield* emitContextTerm(context.args[1], term, env);
+    return;
+  }
+  const next = env.clone();
+  if (unify(term, context, next)) yield next;
+}
+
+function* emitContextParts(context, name, args, env) {
+  context = deref(context, env);
+  if (isConjunction(context)) {
+    yield* emitContextParts(context.args[0], name, args, env);
+    yield* emitContextParts(context.args[1], name, args, env);
+    return;
+  }
+  if (context.type !== 'atom' && context.type !== 'compound') return;
+  const next = env.clone();
+  const argList = context.type === 'compound' ? listFromItems(context.args) : listFromItems([]);
+  if (unify(name, atom(context.name), next) && unify(args, argList, next)) yield next;
+}
+
+function* holdsTerm({ goal, env }) {
+  yield* emitContextTerm(goal.args[0], goal.args[1], env);
+}
+
+function* holdsParts({ goal, env }) {
+  yield* emitContextParts(goal.args[0], goal.args[1], goal.args[2], env);
+}

package/src/builtins/control.js

@@ -0,0 +1,34 @@
+// Control builtins.  These intentionally use bounded nested solvers so not/1 and once/1 only ask for the answers they need.
+export const controlBuiltins = {
+  register(registry) {
+    registry.add('not', 1, notBuiltin);
+    registry.add('once', 1, onceBuiltin);
+    registry.add('forall', 2, forallBuiltin);
+  }
+};
+
+function* notBuiltin({ solver, goal, env }) {
+  const limited = solver.cloneForInnerGoal(1);
+  let found = false;
+  for (const _ of limited.solve([goal.args[0]], env.clone(), 0)) { found = true; break; }
+  if (!found) yield env;
+}
+
+function* onceBuiltin({ solver, goal, env }) {
+  const limited = solver.cloneForInnerGoal(1);
+  for (const answerEnv of limited.solve([goal.args[0]], env.clone(), 0)) {
+    yield answerEnv;
+    break;
+  }
+}
+
+function* forallBuiltin({ solver, goal, env }) {
+  const generator = solver.cloneForInnerGoal(10000000);
+  for (const answerEnv of generator.solve([goal.args[0]], env.clone(), 0)) {
+    const checker = solver.cloneForInnerGoal(1);
+    let ok = false;
+    for (const _ of checker.solve([goal.args[1]], answerEnv.clone(), 0)) { ok = true; break; }
+    if (!ok) return;
+  }
+  yield env;
+}

package/src/builtins/core.js

@@ -0,0 +1,78 @@
+// Core relational builtins that do not naturally belong to arithmetic, strings, lists, or aggregation.
+// They are deterministic filters/projections and should avoid enumerating additional answers.
+import { stringTerm, lexicalValue, unify } from '../term.js';
+
+function* ok(env) { yield env; }
+
+export const coreBuiltins = {
+  register(registry) {
+    registry.add('eq', 2, function* ({ goal, env }) {
+      const next = env.clone();
+      if (unify(goal.args[0], goal.args[1], next)) yield next;
+    }, { deterministic: true });
+
+    registry.add('neq', 2, function* ({ goal, env }) {
+      const attempt = env.clone();
+      if (!unify(goal.args[0], goal.args[1], attempt)) yield env;
+    }, { deterministic: true });
+
+    registry.add('local_time', 1, function* ({ goal, env }) {
+      const next = env.clone();
+      if (unify(goal.args[0], stringTerm(localDateText()), next)) yield next;
+    }, { deterministic: true });
+
+    registry.add('difference', 3, function* ({ goal, env }) {
+      const endText = lexicalValue(goal.args[0], env);
+      const startText = lexicalValue(goal.args[1], env);
+      if (!endText || !startText) return;
+      const end = parseISODate(endText);
+      const start = parseISODate(startText);
+      if (!end || !start || compareDateParts(end, start) < 0) return;
+      let [ey, em, ed] = end;
+      const [sy, sm, sd] = start;
+      if (ed < sd) {
+        let bm = em - 1;
+        let by = ey;
+        if (bm === 0) { bm = 12; by--; }
+        ed += daysInMonth(by, bm);
+        em--;
+        if (em === 0) { em = 12; ey--; }
+      }
+      if (em < sm) { em += 12; ey--; }
+      const duration = formatDuration(ey - sy, em - sm, ed - sd);
+      const next = env.clone();
+      if (unify(goal.args[2], stringTerm(duration), next)) yield next;
+    }, { deterministic: true });
+  }
+};
+
+
+function localDateText() {
+  const fixed = typeof process !== 'undefined' ? process.env?.EYELANG_LOCAL_TIME : null;
+  if (fixed) return fixed;
+
+  const now = new Date();
+  const yyyy = now.getFullYear();
+  const mm = String(now.getMonth() + 1).padStart(2, '0');
+  const dd = String(now.getDate()).padStart(2, '0');
+  return `${yyyy}-${mm}-${dd}`;
+}
+
+function parseISODate(text) {
+  const m = /^(\d{4})-(\d{2})-(\d{2})/.exec(text);
+  if (!m) return null;
+  const y = Number(m[1]), mo = Number(m[2]), d = Number(m[3]);
+  if (mo < 1 || mo > 12 || d < 1 || d > daysInMonth(y, mo)) return null;
+  return [y, mo, d];
+}
+function daysInMonth(y, m) {
+  return [0,31,((y%4===0&&y%100!==0)||y%400===0)?29:28,31,30,31,30,31,31,30,31,30,31][m] ?? 0;
+}
+function compareDateParts(a, b) {
+  for (let i = 0; i < 3; i++) if (a[i] !== b[i]) return a[i] < b[i] ? -1 : 1;
+  return 0;
+}
+function formatDuration(y, m, d) {
+  if (y === 0 && m === 0 && d === 0) return 'P0D';
+  return `P${y ? `${y}Y` : ''}${m ? `${m}M` : ''}${d ? `${d}D` : ''}`;
+}