eyeling 1.32.1 → 1.33.0

package/lib/eyelang/parser.mjs

@@ -0,0 +1,428 @@
+// Tokenizer and recursive-descent parser for the eyelang source language.
+// It preserves the compact Prolog-like syntax while producing Term objects for the solver.
+import { atom, compound, cons, emptyList, numberTerm, stringTerm, variable } from './term.mjs';
+
+const TOK = {
+  EOF: 'eof', ATOM: 'atom', VAR: 'var', STRING: 'string', NUMBER: 'number',
+  LPAREN: '(', RPAREN: ')', LBRACKET: '[', RBRACKET: ']', COMMA: ',', BAR: '|', DOT: '.', IF: ':-'
+};
+
+function isWhitespaceCode(code) {
+  return code === 32 || code === 9 || code === 10 || code === 13 || code === 12 || code === 11;
+}
+
+function isDigitCode(code) {
+  return code >= 48 && code <= 57;
+}
+
+function isVariableStart(text) {
+  const code = text.charCodeAt(0);
+  return code === 95 || (code >= 65 && code <= 90);
+}
+
+function isAtomCharCode(code) {
+  // Stop at whitespace and the punctuation tokens that have syntactic meaning.
+  return code > 0 &&
+    !isWhitespaceCode(code) &&
+    code !== 40 && code !== 41 && code !== 91 && code !== 93 &&
+    code !== 44 && code !== 124 && code !== 46 &&
+    code !== 39 && code !== 34 && code !== 58;
+}
+
+class Parser {
+  constructor(source, options = {}) {
+    this.source = String(source ?? '');
+    this.filename = options.filename ?? '<input>';
+    this.pos = 0;
+    this.line = 1;
+    this.anonymous = 0;
+    this.sourceMetadata = options.sourceMetadata !== false;
+    this.token = this.nextToken();
+  }
+  peek(offset = 0) {
+    return this.source[this.pos + offset] ?? '';
+  }
+  take() {
+    const ch = this.peek();
+    if (ch) {
+      this.pos++;
+      if (ch === '\n') this.line++;
+    }
+    return ch;
+  }
+  skipWhitespaceAndComments() {
+    const source = this.source;
+    const len = source.length;
+    while (true) {
+      while (this.pos < len) {
+        const code = source.charCodeAt(this.pos);
+        if (!isWhitespaceCode(code)) break;
+        if (code === 10) this.line++;
+        this.pos++;
+      }
+      if (source.charCodeAt(this.pos) === 37) { // % line comment
+        while (this.pos < len && source.charCodeAt(this.pos) !== 10) this.pos++;
+        continue;
+      }
+      break;
+    }
+  }
+  nextToken() {
+    // The tokenizer keeps just enough state for useful parse-line errors and
+    // treats quoted atoms and quoted strings differently, as Prolog syntax does.
+    this.skipWhitespaceAndComments();
+    const line = this.line;
+    const ch = this.peek();
+    if (!ch) return { type: TOK.EOF, text: '', line };
+
+    const punct = { '(': TOK.LPAREN, ')': TOK.RPAREN, '[': TOK.LBRACKET, ']': TOK.RBRACKET, ',': TOK.COMMA, '|': TOK.BAR, '.': TOK.DOT };
+    if (punct[ch]) {
+      this.take();
+      return { type: punct[ch], text: ch, line };
+    }
+    if (ch === ':' && this.peek(1) === '-') {
+      this.pos += 2;
+      return { type: TOK.IF, text: ':-', line };
+    }
+    if (ch === ':') throw new Error('colon names are not supported; use name or prefix_name');
+
+    if (ch === '"' || ch === "'") {
+      const quote = this.take();
+      let text = '';
+      while (true) {
+        if (!this.peek()) throw new Error(`parse line ${line}: unterminated quoted term`);
+        let value = this.take();
+        if (value === quote) {
+          if (this.peek() === quote) {
+            this.take();
+            value = quote;
+          } else {
+            break;
+          }
+        } else if (value === '\\' && this.peek()) {
+          const escaped = this.take();
+          if (escaped === 'n') value = '\n';
+          else if (escaped === 't') value = '\t';
+          else value = escaped;
+        }
+        text += value;
+      }
+      return { type: quote === '"' ? TOK.STRING : TOK.ATOM, text, line };
+    }
+
+    if (isDigitCode(ch.charCodeAt(0)) || (ch === '-' && isDigitCode(this.peek(1).charCodeAt(0)))) {
+      const start = this.pos;
+      if (this.peek() === '-') this.take();
+      while (isDigitCode(this.peek().charCodeAt(0))) this.take();
+      if (this.peek() === '.' && isDigitCode(this.peek(1).charCodeAt(0))) {
+        this.take();
+        while (isDigitCode(this.peek().charCodeAt(0))) this.take();
+      }
+      if ((this.peek() === 'e' || this.peek() === 'E')) {
+        let idx = this.pos + 1;
+        if (this.source[idx] === '+' || this.source[idx] === '-') idx++;
+        if (isDigitCode((this.source[idx] ?? '').charCodeAt(0))) {
+          this.take();
+          if (this.peek() === '+' || this.peek() === '-') this.take();
+          while (isDigitCode(this.peek().charCodeAt(0))) this.take();
+        }
+      }
+      return { type: TOK.NUMBER, text: this.source.slice(start, this.pos), line };
+    }
+
+    const start = this.pos;
+    while (this.pos < this.source.length && isAtomCharCode(this.source.charCodeAt(this.pos))) this.pos++;
+    if (this.pos === start) throw new Error(`parse line ${line}: bad character ${JSON.stringify(ch)}`);
+    let text = this.source.slice(start, this.pos);
+    let type = isVariableStart(text) ? TOK.VAR : TOK.ATOM;
+    if (type === TOK.VAR && text === '_') text = `__anon${this.anonymous++}`;
+    return { type, text, line };
+  }
+  advance() {
+    this.token = this.nextToken();
+  }
+  expect(type, desc = type) {
+    if (this.token.type !== type) throw new Error(`parse line ${this.token.line}: expected ${desc}, got ${this.token.text}`);
+  }
+  parseParenthesizedTerm() {
+    // Parenthesized comma terms are represented as right-associated ','/2
+    // compounds, which lets the solver flatten conjunctions uniformly.
+    this.expect(TOK.LPAREN, '(');
+    this.advance();
+    const items = [];
+    while (true) {
+      items.push(this.parseTerm());
+      if (this.token.type === TOK.COMMA) {
+        this.advance();
+        continue;
+      }
+      break;
+    }
+    this.expect(TOK.RPAREN, ')');
+    this.advance();
+    let term = items[items.length - 1];
+    for (let i = items.length - 2; i >= 0; i--) term = compound(',', [items[i], term]);
+    return term;
+  }
+  parseList() {
+    // Lists are lowered to './2' cons cells and [] so list predicates can work
+    // on a single canonical representation.
+    this.expect(TOK.LBRACKET, '[');
+    this.advance();
+    if (this.token.type === TOK.RBRACKET) {
+      this.advance();
+      return emptyList();
+    }
+    const items = [];
+    let tail = null;
+    while (true) {
+      items.push(this.parseTerm());
+      if (this.token.type === TOK.COMMA) {
+        this.advance();
+        continue;
+      }
+      if (this.token.type === TOK.BAR) {
+        this.advance();
+        tail = this.parseTerm();
+        this.expect(TOK.RBRACKET, ']');
+        this.advance();
+        break;
+      }
+      this.expect(TOK.RBRACKET, ']');
+      this.advance();
+      tail = emptyList();
+      break;
+    }
+    for (let i = items.length - 1; i >= 0; i--) tail = cons(items[i], tail);
+    return tail;
+  }
+  parseTerm() {
+    if (this.token.type === TOK.LPAREN) return this.parseParenthesizedTerm();
+    if (this.token.type === TOK.LBRACKET) return this.parseList();
+    if (this.token.type === TOK.VAR) {
+      const name = this.token.text;
+      this.advance();
+      return variable(name);
+    }
+    if (this.token.type === TOK.STRING) {
+      const value = this.token.text;
+      this.advance();
+      return stringTerm(value);
+    }
+    if (this.token.type === TOK.NUMBER) {
+      const value = this.token.text;
+      this.advance();
+      return numberTerm(value);
+    }
+    if (this.token.type === TOK.ATOM) {
+      const name = this.token.text;
+      this.advance();
+      if (this.token.type === TOK.LPAREN) {
+        this.advance();
+        const args = [];
+        if (this.token.type !== TOK.RPAREN) {
+          while (true) {
+            args.push(this.parseTerm());
+            if (this.token.type === TOK.COMMA) {
+              this.advance();
+              continue;
+            }
+            break;
+          }
+        }
+        this.expect(TOK.RPAREN, ')');
+        this.advance();
+        return compound(name, args);
+      }
+      return atom(name);
+    }
+    throw new Error(`parse line ${this.token.line}: bad term`);
+  }
+  parseProgram() {
+    const clauses = [];
+    while (this.token.type !== TOK.EOF) {
+      const line = this.token.line;
+      const head = this.parseTerm();
+      const body = [];
+      if (this.token.type === TOK.IF) {
+        this.advance();
+        while (true) {
+          body.push(this.parseTerm());
+          if (this.token.type === TOK.COMMA) {
+            this.advance();
+            continue;
+          }
+          break;
+        }
+      }
+      this.expect(TOK.DOT, '.');
+      this.advance();
+      const clause = { head, body };
+      if (this.sourceMetadata) clause.source = { filename: this.filename, line, clause: clauses.length + 1 };
+      clauses.push(clause);
+    }
+    return clauses;
+  }
+}
+
+
+export function parseClauses(source, options = {}) {
+  if (options.sourceMetadata === false) {
+    const clauses = parseClausesFastNoSource(source);
+    if (clauses) return clauses;
+  }
+  return new Parser(source, options).parseProgram();
+}
+
+function isSimpleName(text) {
+  if (!text) return false;
+  const first = text.charCodeAt(0);
+  if (!(first >= 97 && first <= 122)) return false;
+  for (let i = 1; i < text.length; i++) {
+    const code = text.charCodeAt(i);
+    if (!(code === 95 || (code >= 48 && code <= 57) || (code >= 65 && code <= 90) || (code >= 97 && code <= 122))) return false;
+  }
+  return true;
+}
+
+const SIMPLE_NUMBER = /^-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?$/;
+const SIMPLE_ARG_FORBIDDEN = /[\s()[\]|"']/;
+const FAST_BINARY_FACT = /^([a-z][A-Za-z0-9_]*)\(\s*([^,\s()[\]|"']+)\s*,\s*([^,\s()[\]|"']+)\s*\)\.$/;
+const FAST_BINARY_RULE = /^([a-z][A-Za-z0-9_]*)\(\s*([^,\s()[\]|"']+)\s*,\s*([^,\s()[\]|"']+)\s*\)\s*:-\s*([a-z][A-Za-z0-9_]*)\(\s*([^,\s()[\]|"']+)\s*,\s*([^,\s()[\]|"']+)\s*\)\.$/;
+
+function parseClausesFastNoSource(source) {
+  source = String(source ?? '');
+  const numberCache = new Map();
+  const stringCache = new Map();
+  const variableCache = new Map();
+  const clauses = [];
+  let anonymous = 0;
+  let chunk = '';
+
+  const cached = (cache, key, create) => {
+    const existing = cache.get(key);
+    if (existing) return existing;
+    const value = create(key);
+    cache.set(key, value);
+    return value;
+  };
+  const scalarOrVariableFast = (text) => {
+    if (!text) throw new Error('empty simple term');
+    const first = text.charCodeAt(0);
+    if (text === '_') return variable(`__anon${anonymous++}`);
+    if (first === 95 || (first >= 65 && first <= 90)) {
+      const existing = variableCache.get(text);
+      if (existing) return existing;
+      const value = variable(text);
+      variableCache.set(text, value);
+      return value;
+    }
+    if ((first === 45 || isDigitCode(first)) && SIMPLE_NUMBER.test(text)) return cached(numberCache, text, numberTerm);
+    if (first === 34 && text.endsWith('"')) return cached(stringCache, text.slice(1, -1), stringTerm);
+    return atom(text);
+  };
+  const scalarOrVariable = (text) => scalarOrVariableFast(text.trim());
+  const parseBinaryCompound = (text) => {
+    text = text.trim();
+    const open = text.indexOf('(');
+    if (open <= 0 || text[text.length - 1] !== ')') return null;
+    const name = text.slice(0, open).trim();
+    if (!isSimpleName(name)) return null;
+    const inner = text.slice(open + 1, -1);
+    if (inner.includes('(') || inner.includes(')') || inner.includes('[') || inner.includes(']') || inner.includes('|') || inner.includes('"') || inner.includes("'")) return null;
+    const comma = inner.indexOf(',');
+    if (comma < 0 || inner.indexOf(',', comma + 1) >= 0) return null;
+    const left = inner.slice(0, comma).trim();
+    const right = inner.slice(comma + 1).trim();
+    if (!left || !right || SIMPLE_ARG_FORBIDDEN.test(left) || SIMPLE_ARG_FORBIDDEN.test(right)) return null;
+    return compound(name, [scalarOrVariable(left), scalarOrVariable(right)]);
+  };
+  const parseFastBinaryMatch = (match) => {
+    return compound(match[1], [scalarOrVariableFast(match[2]), scalarOrVariableFast(match[3])]);
+  };
+  const parseFastBinaryRuleMatch = (match) => {
+    return {
+      head: compound(match[1], [scalarOrVariableFast(match[2]), scalarOrVariableFast(match[3])]),
+      body: [compound(match[4], [scalarOrVariableFast(match[5]), scalarOrVariableFast(match[6])])],
+    };
+  };
+  const parseFastLine = (text) => {
+    if (!text.endsWith('.')) return null;
+    const ruleMatch = FAST_BINARY_RULE.exec(text);
+    if (ruleMatch) return parseFastBinaryRuleMatch(ruleMatch);
+    const factMatch = FAST_BINARY_FACT.exec(text);
+    if (factMatch) return { head: parseFastBinaryMatch(factMatch), body: [] };
+    return null;
+  };
+  const parseSimple = (text) => {
+    if (!text.endsWith('.') || text.includes('\n')) return null;
+    const fast = parseFastLine(text);
+    if (fast) return fast;
+    text = text.slice(0, -1);
+    const rule = text.indexOf(':-');
+    if (rule < 0) {
+      const head = parseBinaryCompound(text);
+      return head ? { head, body: [] } : null;
+    }
+    const head = parseBinaryCompound(text.slice(0, rule));
+    const bodyGoal = parseBinaryCompound(text.slice(rule + 2));
+    return head && bodyGoal ? { head, body: [bodyGoal] } : null;
+  };
+
+  const flush = () => {
+    const text = chunk.trim();
+    chunk = '';
+    if (!text) return true;
+    const simple = parseSimple(text);
+    if (simple) {
+      clauses.push(simple);
+      return true;
+    }
+    try {
+      const parsed = new Parser(text, { sourceMetadata: false }).parseProgram();
+      clauses.push(...parsed);
+      return true;
+    } catch (_) {
+      return false;
+    }
+  };
+
+  let lineStart = 0;
+  while (lineStart <= source.length) {
+    let lineEnd = source.indexOf('\n', lineStart);
+    if (lineEnd < 0) lineEnd = source.length;
+    let line = source.slice(lineStart, lineEnd);
+    if (line.endsWith('\r')) line = line.slice(0, -1);
+    const trimmed = line.trim();
+    if (trimmed && !trimmed.startsWith('%')) {
+      if (!chunk && trimmed.endsWith('.')) {
+        const simple = parseFastLine(trimmed) ?? parseSimple(trimmed);
+        if (simple) clauses.push(simple);
+        else {
+          chunk = line + '\n';
+          if (!flush()) return null;
+        }
+      } else {
+        chunk += line + '\n';
+        if (trimmed.endsWith('.')) {
+          if (!flush()) return null;
+        }
+      }
+    }
+    if (lineEnd === source.length) break;
+    lineStart = lineEnd + 1;
+  }
+  if (chunk.trim() && !flush()) return null;
+  return clauses;
+}
+
+export function parseProgramText(source) {
+  return parseClauses(source);
+}
+
+export function parseGoalText(text) {
+  const clauses = parseClauses(`zz_goal(${text}).`);
+  const head = clauses[0]?.head;
+  if (!head || head.args.length < 1) throw new Error('bad goal');
+  return head.args[0];
+}

package/lib/eyelang/program.mjs

@@ -0,0 +1,244 @@
+// Program representation and clause indexing.
+// Indexes are deliberately conservative: they speed up common scalar arguments but never replace unification as the final check.
+import { ATOM, COMPOUND, Env, compound, deref, flattenConjunction, isScalar, termToString } from './term.mjs';
+import { parseClauses } from './parser.mjs';
+import { filenameLooksRdf, parseRdfClauses } from './rdf.mjs';
+
+export class Program {
+  constructor(clauses = [], options = {}) {
+    this.clauses = clauses;
+    this.groups = new Map();
+    this.materializedGroups = new Set();
+    this.hasMaterialize = false;
+    for (let index = 0; index < this.clauses.length; index++) {
+      const clause = this.clauses[index];
+      clause.index = index;
+      this.indexClause(clause);
+    }
+    this.applyDeclarations(options);
+  }
+  static parse(source, options = {}) {
+    return new Program(parseSourceClauses(source, options), options);
+  }
+  static parseSources(sources = [], options = {}) {
+    const clauses = [];
+    for (const source of sources) {
+      const parsed = typeof source === 'string'
+        ? parseSourceClauses(source, options)
+        : parseSourceClauses(source?.text ?? source?.source ?? '', { ...options, filename: source?.filename ?? '<input>' });
+      for (const clause of parsed) clauses.push(clause);
+    }
+    return new Program(clauses, options);
+  }
+  makeGroup(name, arity) {
+    // A group corresponds to one predicate indicator, for example edge/3.
+    // Single-argument and pair indexes cover the common case where queries bind
+    // one or two scalar arguments before calling the predicate.
+    const group = {
+      name,
+      arity,
+      clauses: [],
+      argIndexes: Array.from({ length: arity }, () => ({ buckets: new Map(), fallback: [] })),
+      pairIndexes: [],
+      memoized: false,
+      recursive: false,
+    };
+    if (arity > 2) {
+      for (let left = 0; left < arity; left++) {
+        for (let right = left + 1; right < arity; right++) {
+          group.pairIndexes.push({ left, right, buckets: new Map(), fallback: [] });
+        }
+      }
+    }
+    return group;
+  }
+  indexClause(clause) {
+    const head = clause.head;
+    if (head.type !== COMPOUND) return;
+    const key = `${head.name}/${head.arity}`;
+    let group = this.groups.get(key);
+    if (!group) {
+      group = this.makeGroup(head.name, head.arity);
+      this.groups.set(key, group);
+    }
+    group.clauses.push(clause);
+    for (let i = 0; i < head.arity; i++) indexOne(group.argIndexes[i], head.args[i], clause);
+    for (const pair of group.pairIndexes) indexPair(pair, head, clause);
+  }
+  findGroup(name, arity) {
+    return this.groups.get(`${name}/${arity}`) ?? null;
+  }
+  applyDeclarations(options = {}) {
+    for (const clause of this.clauses) {
+      const h = clause.head;
+      if (clause.body.length !== 0 || h.type !== COMPOUND || h.arity !== 2) continue;
+      const [name, arity] = h.args;
+      if (name.type !== ATOM || arity.type !== 'number') continue;
+      const key = `${name.name}/${Number(arity.name)}`;
+      if (h.name === 'memoize') {
+        const group = this.groups.get(key);
+        if (group) group.memoized = true;
+      } else if (h.name === 'materialize') {
+        this.hasMaterialize = true;
+        this.materializedGroups.add(key);
+      }
+    }
+    if (options.markRecursive !== false) this.markRecursivePredicates();
+  }
+  markRecursivePredicates() {
+    // Recursion is a group-level diagnostic hint. It is computed from predicate
+    // dependencies rather than from individual clauses when callers explicitly ask
+    // for it.
+    const groups = [...this.groups.values()];
+    const indexByGroup = new Map(groups.map((group, i) => [group, i]));
+    const deps = groups.map(() => new Set());
+    for (const group of groups) {
+      const groupIndex = indexByGroup.get(group);
+      for (const clause of group.clauses) {
+        const bodyGoals = clause.body.flatMap((goal) => goal.type === COMPOUND && goal.name === ',' && goal.arity === 2 ? flattenConjunction(goal) : [goal]);
+        for (const goal of bodyGoals) {
+          if (goal.type !== COMPOUND) continue;
+          const dep = this.findGroup(goal.name, goal.arity);
+          if (dep) deps[groupIndex].add(indexByGroup.get(dep));
+        }
+      }
+    }
+    for (const group of groups) {
+      const start = indexByGroup.get(group);
+      const seen = new Set();
+      const stack = [start];
+      let recursive = false;
+      while (stack.length && !recursive) {
+        const current = stack.pop();
+        if (seen.has(current)) continue;
+        seen.add(current);
+        for (const next of deps[current]) {
+          if (next === start) { recursive = true; break; }
+          if (!seen.has(next)) stack.push(next);
+        }
+      }
+      group.recursive = recursive;
+    }
+  }
+  hasMaterializeDeclarations() {
+    return this.hasMaterialize;
+  }
+  groupIsMaterialized(group) {
+    return this.materializedGroups.has(`${group.name}/${group.arity}`);
+  }
+  groupHasRule(group) {
+    return group.clauses.some((clause) => clause.body.length > 0);
+  }
+  sourceFactLines(predicateKeys = null) {
+    // Only facts for predicates that may be materialized need to be remembered.
+    // On data-heavy examples this avoids formatting tens of thousands of
+    // unrelated source facts just to suppress duplicate derived output.
+    const lines = new Set();
+    const env = new Env();
+    for (const clause of this.clauses) {
+      if (clause.body.length !== 0 || clause.head.type !== COMPOUND) continue;
+      if (predicateKeys && !predicateKeys.has(`${clause.head.name}/${clause.head.arity}`)) continue;
+      lines.add(`${termToString(clause.head, env, true)}.\n`);
+    }
+    return lines;
+  }
+  materializationGoals() {
+    const hasMaterialize = this.hasMaterializeDeclarations();
+    const goals = [];
+    for (const group of this.groups.values()) {
+      if (hasMaterialize) {
+        if (!this.groupIsMaterialized(group)) continue;
+      } else if (group.arity !== 2) {
+        continue;
+      }
+      if (!this.groupHasRule(group)) continue;
+      const args = [];
+      for (let i = 0; i < group.arity; i++) args.push({ type: 'var', name: `X${i}`, args: [] });
+      goals.push(compound(group.name, args));
+    }
+    return goals;
+  }
+}
+
+function indexOne(index, arg, clause) {
+  if (isScalar(arg)) {
+    const bucket = index.buckets.get(arg.name);
+    if (bucket) bucket.push(clause);
+    else index.buckets.set(arg.name, [clause]);
+  } else {
+    index.fallback.push(clause);
+  }
+}
+
+function pairKey(left, right) {
+  return `${left.name}\x1f${right.name}`;
+}
+
+function indexPair(pair, head, clause) {
+  const left = head.args[pair.left];
+  const right = head.args[pair.right];
+  if (isScalar(left) && isScalar(right)) {
+    const key = pairKey(left, right);
+    const bucket = pair.buckets.get(key);
+    if (bucket) bucket.push(clause);
+    else pair.buckets.set(key, [clause]);
+  } else {
+    pair.fallback.push(clause);
+  }
+}
+
+export function selectClauseCandidates(group, goal, env) {
+  // Pick the narrowest applicable index. Fallback clauses remain in the result
+  // because clauses with variables or compound heads can still unify later.
+  let bestPrimary = group.clauses;
+  let bestFallback = [];
+  let bestLen = group.clauses.length;
+  let indexed = false;
+  if (goal.type !== COMPOUND) return { primary: bestPrimary, fallback: bestFallback };
+
+  for (let i = 0; i < goal.arity; i++) {
+    const arg = deref(goal.args[i], env);
+    if (!isScalar(arg)) continue;
+    const index = group.argIndexes[i];
+    const bucket = index.buckets.get(arg.name) ?? [];
+    const candidateLen = bucket.length + index.fallback.length;
+    if (!indexed || candidateLen < bestLen) {
+      bestPrimary = bucket;
+      bestFallback = index.fallback;
+      bestLen = candidateLen;
+      indexed = true;
+      if (bestLen === 0) break;
+    }
+  }
+
+  for (const pair of group.pairIndexes) {
+    const left = deref(goal.args[pair.left], env);
+    const right = deref(goal.args[pair.right], env);
+    if (!isScalar(left) || !isScalar(right)) continue;
+    const bucket = pair.buckets.get(pairKey(left, right)) ?? [];
+    const candidateLen = bucket.length + pair.fallback.length;
+    if (!indexed || candidateLen < bestLen) {
+      bestPrimary = bucket;
+      bestFallback = pair.fallback;
+      bestLen = candidateLen;
+      indexed = true;
+      if (bestLen === 0) break;
+    }
+  }
+
+  return { primary: bestPrimary, fallback: bestFallback };
+}
+
+export function makeProgram(source, options = {}) {
+  return Program.parse(source, options);
+}
+
+export function parseSourceClauses(source, options = {}) {
+  const inputFormat = (options.inputFormat ?? options.format ?? 'eyelang').toString().toLowerCase();
+  const filename = options.filename ?? '<input>';
+  const autoRdf = inputFormat === 'auto' && filenameLooksRdf(filename);
+  if (inputFormat === 'rdf' || inputFormat === 'rdf12' || inputFormat === 'n3' || inputFormat === 'turtle' || inputFormat === 'ttl' || inputFormat === 'nt' || autoRdf) {
+    return parseRdfClauses(source, options);
+  }
+  return parseClauses(source, options);
+}