eyelang 1.7.5 → 1.7.6

package/README.md

@@ -63,6 +63,7 @@ python3 -m http.server
 npm test
 npm run test:conformance
 npm run conformance:report
+# release preparation writes conformance-report.md via the preversion script
 npm run test:examples
 npm run test:regression
 ```

package/conformance-report.md

@@ -0,0 +1,26 @@
+# Conformance Eyelang report
+
+This report summarizes the file-based conformance corpus under `test/conformance/`.
+
+| Category | Positive | Errors | Warnings | Proofs | Total |
+|---|---:|---:|---:|---:|---:|
+| aggregation | 5 | 0 | 0 | 0 | 5 |
+| arithmetic | 12 | 0 | 0 | 0 | 12 |
+| atoms | 14 | 5 | 0 | 0 | 19 |
+| builtins | 2 | 0 | 0 | 0 | 2 |
+| context | 3 | 0 | 0 | 0 | 3 |
+| control | 5 | 0 | 0 | 0 | 5 |
+| declarations | 5 | 0 | 0 | 0 | 5 |
+| legacy-numbered | 104 | 0 | 0 | 0 | 104 |
+| lists | 18 | 1 | 0 | 0 | 19 |
+| materialize | 2 | 0 | 0 | 0 | 2 |
+| negation | 3 | 0 | 13 | 0 | 16 |
+| proofs | 0 | 0 | 0 | 8 | 8 |
+| rules | 2 | 1 | 0 | 0 | 3 |
+| strings | 15 | 0 | 0 | 0 | 15 |
+| syntax | 4 | 19 | 0 | 0 | 23 |
+| table | 2 | 0 | 0 | 0 | 2 |
+| terms | 10 | 1 | 0 | 0 | 11 |
+| unification | 4 | 0 | 0 | 0 | 4 |
+| variables | 8 | 8 | 0 | 0 | 16 |
+| **Total** | **218** | **35** | **13** | **8** | **274** |

package/docs/guide.md

@@ -503,7 +503,9 @@ Summarize the conformance corpus by category:
 npm run conformance:report
 ```
 
-The conformance suite lives in [`test/conformance/`](../test/conformance/) as a file-based eyelang corpus. Positive cases pair `cases/<name>.eye` with exact expected stdout under `expected/<name>.eye`; negative cases pair `errors/<name>.eye` with exact expected error text under `expected-errors/<name>.txt`; warning cases pair `warnings/<name>.eye` with exact `--warnings` stdout and stderr files under `expected-warnings/`. Cases may be grouped in category directories such as `arithmetic/`, `strings/`, `lists/`, `terms/`, `atoms/`, `variables/`, `negation/`, and `syntax/`, so another implementation can reuse the same corpus as an executable language contract. The suite covers the standard language surface from the language reference, including reusable built-ins, standard errors, and standard warnings. The regression suite lives in [`test/run-regression.mjs`](../test/run-regression.mjs) and covers CLI regressions, the public JavaScript API, and white-box invariants for parser, unification, and indexing behavior.
+Release preparation runs the same report and writes [`conformance-report.md`](../conformance-report.md), so each published package carries a current conformance summary.
+
+The conformance suite lives in [`test/conformance/`](../test/conformance/) as a file-based eyelang corpus. Positive cases pair `cases/<name>.eye` with exact expected stdout under `expected/<name>.eye`; negative cases pair `errors/<name>.eye` with exact expected error text under `expected-errors/<name>.txt`; warning cases pair `warnings/<name>.eye` with exact `--warnings` stdout and stderr files under `expected-warnings/`; proof cases pair `proofs/<name>.eye` with exact `--proof` output under `expected-proofs/`. Cases may be grouped in category directories such as `arithmetic/`, `strings/`, `lists/`, `terms/`, `atoms/`, `variables/`, `negation/`, and `syntax/`, so another implementation can reuse the same corpus as an executable language contract. The suite covers the standard language surface from the language reference, including reusable built-ins, standard errors, standard warnings, and the machine-readable `why/2` proof-output contract. The regression suite lives in [`test/run-regression.mjs`](../test/run-regression.mjs) and covers CLI regressions, the public JavaScript API, and white-box invariants for parser, unification, and indexing behavior.
 
 ## Development and release
 
@@ -531,7 +533,8 @@ For a release:
 2. update `README.md` and the language reference;
 3. regenerate golden outputs if behavior changed;
 4. run `npm run test:eyelang`;
-5. publish the repository with the browser playground assets if publishing the playground. The playground includes controls equivalent to CLI `--stats` and `--proof`.
+5. run `npm run conformance:report -- conformance-report.md`;
+6. publish the repository with the browser playground assets if publishing the playground. The playground includes controls equivalent to CLI `--stats` and `--proof`.
 
 ## Relationship to Eyeling
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eyelang",
-  "version": "1.7.5",
+  "version": "1.7.6",
   "description": "A small Prolog-like logic programming language for rules, goals, answers, and proofs.",
   "type": "module",
   "main": "./index.js",
@@ -30,6 +30,7 @@
     "playground.html",
     "bin",
     "src",
+    "conformance-report.md",
     "docs",
     "examples",
     "test"
@@ -43,7 +44,7 @@
     "test:conformance": "node test/run-conformance.mjs",
     "test:examples": "node test/run-examples.mjs",
     "test:regression": "node test/run-regression.mjs",
-    "preversion": "npm test",
+    "preversion": "npm test && npm run conformance:report -- conformance-report.md",
     "postversion": "git push origin HEAD --follow-tags",
     "conformance:report": "node test/run-conformance-report.mjs"
   }

package/test/conformance/README.md

@@ -2,7 +2,7 @@
 
 This directory contains the executable conformance cases for the Eyelang language and reference engine. The normative language description is in the [Eyelang language reference](../../../docs/language-reference.md).
 
-The suite is intentionally file-based so another implementation can run the same programs and compare exact standard output, expected errors, and expected warnings. The conformance corpus is part of the public language contract, not just an implementation smoke test.
+The suite is intentionally file-based so another implementation can run the same programs and compare exact standard output, expected errors, expected warnings, and expected proof output. The conformance corpus is part of the public language contract, not just an implementation smoke test.
 
 A normal positive case consists of:
 
@@ -20,6 +20,11 @@ Expected-warning cases consist of:
 - `conformance/expected-warnings/<name>.eye` — exact expected standard output;
 - `conformance/expected-warnings/<name>.txt` — exact expected standard error.
 
+Expected-proof cases consist of:
+
+- `conformance/proofs/<name>.eye` — input program run through the CLI with `--proof`;
+- `conformance/expected-proofs/<name>.eye` — exact expected standard output, including both answer facts and `why/2` proof facts.
+
 Case names may be nested in category directories such as `arithmetic/`, `strings/`, `lists/`, `terms/`, `atoms/`, `variables/`, `negation/`, or `syntax/`. Expected files mirror the same relative path.
 
 ## Running the suite
@@ -40,6 +45,7 @@ Summarize conformance coverage by category:
 
 ```sh
 npm run conformance:report
+npm run conformance:report -- conformance-report.md
 ```
 
 Run matching conformance cases by passing a filename or directory fragment:
@@ -51,14 +57,14 @@ node test/run-conformance.mjs variables/
 node test/run-conformance.mjs error/variables
 ```
 
-The runner executes normal materialized programs in-process through the public JavaScript API so small conformance cases avoid measuring Node startup overhead. Warning cases intentionally use the CLI because warning output is a host-interface contract.
+The runner executes normal materialized programs in-process through the public JavaScript API so small conformance cases avoid measuring Node startup overhead. Warning and proof cases intentionally use the CLI because warning output and `why/2` proof output are host-interface contracts.
 
 ## Scope
 
-The conformance corpus is a single eyelang suite. It covers the standard language described by the language reference: lexical syntax, facts, definite clauses, first-order terms, lists, conjunction, structured unification, left-to-right goal-directed proof search, materialized output, read-back printing, standard built-ins, declarations, warnings, errors, and standard host behavior.
+The conformance corpus is a single eyelang suite. It covers the standard language described by the language reference: lexical syntax, facts, definite clauses, first-order terms, lists, conjunction, structured unification, left-to-right goal-directed proof search, materialized output, read-back printing, standard built-ins, declarations, warnings, errors, proof output, and standard host behavior.
 
 The suite deliberately does not separate `core` and `extension` profiles. Reusable built-ins such as arithmetic, strings, lists, aggregation, context terms, term inspection, and search control are part of the standard eyelang conformance surface. Implementation-specific built-ins may still exist in downstream hosts, but they should have their own tests outside this corpus unless they are standardized.
 
 ## Updating expected output
 
-There is no committed auto-accept mode. To update an expected file, run the matching case with the conformance runner, inspect the result, and replace the corresponding file under `conformance/expected/`, `conformance/expected-errors/`, or `conformance/expected-warnings/` deliberately.
+There is no committed auto-accept mode. To update an expected file, run the matching case with the conformance runner, inspect the result, and replace the corresponding file under `conformance/expected/`, `conformance/expected-errors/`, `conformance/expected-warnings/`, or `conformance/expected-proofs/` deliberately.

package/test/conformance/cases/strings/trim_tabs_and_spaces.eye

@@ -1,2 +1,3 @@
 materialize(answer, 1).
-answer(?x) :- trim("  hello  ", ?x).
+answer(?x) :- trim("	 hello 
+", ?x).

package/test/conformance/expected-proofs/proofs/bindings_nested_term.eye

@@ -0,0 +1,16 @@
+answer(pair(a, [b, c])).
+why(
+  answer(pair(a, [b, c])),
+  proof(
+    goal(answer(pair(a, [b, c]))),
+    by(rule("<stdin>", clause(3))),
+    bindings([binding("?term", pair(a, [b, c]))]),
+    uses([
+      proof(
+        goal(source(pair(a, [b, c]))),
+        by(fact("<stdin>", clause(2)))
+      )
+    ])
+  )
+).
+

package/test/conformance/expected-proofs/proofs/builtin_numeric.eye

@@ -0,0 +1,16 @@
+answer(5).
+why(
+  answer(5),
+  proof(
+    goal(answer(5)),
+    by(rule("<stdin>", clause(2))),
+    bindings([binding("?x", 5)]),
+    uses([
+      proof(
+        goal(add(2, 3, 5)),
+        by(builtin(add, 3))
+      )
+    ])
+  )
+).
+

package/test/conformance/expected-proofs/proofs/conjunction_order.eye

@@ -0,0 +1,19 @@
+answer(ok).
+why(
+  answer(ok),
+  proof(
+    goal(answer(ok)),
+    by(rule("<stdin>", clause(4))),
+    uses([
+      proof(
+        goal(left(ok)),
+        by(fact("<stdin>", clause(2)))
+      ),
+      proof(
+        goal(right(ok)),
+        by(fact("<stdin>", clause(3)))
+      )
+    ])
+  )
+).
+

package/test/conformance/expected-proofs/proofs/iri_atom.eye

@@ -0,0 +1,16 @@
+label(<urn:example:a>, "Alice").
+why(
+  label(<urn:example:a>, "Alice"),
+  proof(
+    goal(label(<urn:example:a>, "Alice")),
+    by(rule("<stdin>", clause(3))),
+    bindings([binding("?iri", <urn:example:a>), binding("?name", "Alice")]),
+    uses([
+      proof(
+        goal(name(<urn:example:a>, "Alice")),
+        by(fact("<stdin>", clause(2)))
+      )
+    ])
+  )
+).
+

package/test/conformance/expected-proofs/proofs/list_builtin.eye

@@ -0,0 +1,20 @@
+answer(b).
+why(
+  answer(b),
+  proof(
+    goal(answer(b)),
+    by(rule("<stdin>", clause(2))),
+    bindings([binding("?x", b)]),
+    uses([
+      proof(
+        goal(member(b, [a, b])),
+        by(builtin(member, 2))
+      ),
+      proof(
+        goal(eq(b, b)),
+        by(builtin(eq, 2))
+      )
+    ])
+  )
+).
+

package/test/conformance/expected-proofs/proofs/once_child.eye

@@ -0,0 +1,22 @@
+answer(a).
+why(
+  answer(a),
+  proof(
+    goal(answer(a)),
+    by(rule("<stdin>", clause(4))),
+    bindings([binding("?x", a)]),
+    uses([
+      proof(
+        goal(once(choice(a))),
+        by(builtin(once, 1)),
+        uses([
+          proof(
+            goal(choice(a)),
+            by(fact("<stdin>", clause(2)))
+          )
+        ])
+      )
+    ])
+  )
+).
+

package/test/conformance/expected-proofs/proofs/rule_fact.eye

@@ -0,0 +1,16 @@
+answer(ok).
+why(
+  answer(ok),
+  proof(
+    goal(answer(ok)),
+    by(rule("<stdin>", clause(3))),
+    bindings([binding("?x", ok)]),
+    uses([
+      proof(
+        goal(seed(ok)),
+        by(fact("<stdin>", clause(2)))
+      )
+    ])
+  )
+).
+

package/test/conformance/expected-proofs/proofs/table_recursive.eye

@@ -0,0 +1,59 @@
+path(a, b).
+why(
+  path(a, b),
+  proof(
+    goal(path(a, b)),
+    by(rule("<stdin>", clause(5))),
+    bindings([binding("?x", a), binding("?y", b)]),
+    uses([
+      proof(
+        goal(edge(a, b)),
+        by(fact("<stdin>", clause(3)))
+      )
+    ])
+  )
+).
+
+path(b, c).
+why(
+  path(b, c),
+  proof(
+    goal(path(b, c)),
+    by(rule("<stdin>", clause(5))),
+    bindings([binding("?x", b), binding("?y", c)]),
+    uses([
+      proof(
+        goal(edge(b, c)),
+        by(fact("<stdin>", clause(4)))
+      )
+    ])
+  )
+).
+
+path(a, c).
+why(
+  path(a, c),
+  proof(
+    goal(path(a, c)),
+    by(rule("<stdin>", clause(6))),
+    bindings([binding("?x", a), binding("?z", c), binding("?y", b)]),
+    uses([
+      proof(
+        goal(edge(a, b)),
+        by(fact("<stdin>", clause(3)))
+      ),
+      proof(
+        goal(path(b, c)),
+        by(rule("<stdin>", clause(5))),
+        bindings([binding("?x", b), binding("?y", c)]),
+        uses([
+          proof(
+            goal(edge(b, c)),
+            by(fact("<stdin>", clause(4)))
+          )
+        ])
+      )
+    ])
+  )
+).
+

package/test/conformance/proofs/proofs/bindings_nested_term.eye

@@ -0,0 +1,4 @@
+% Reference 12: proof bindings preserve nested compound terms.
+materialize(answer, 1).
+source(pair(a, [b, c])).
+answer(?term) :- source(?term).

package/test/conformance/proofs/proofs/builtin_numeric.eye

@@ -0,0 +1,3 @@
+% Reference 12: built-ins are proof leaves identified by builtin(Name, Arity).
+materialize(answer, 1).
+answer(?x) :- add(2, 3, ?x).

package/test/conformance/proofs/proofs/conjunction_order.eye

@@ -0,0 +1,5 @@
+% Reference 12: proof output records conjunction children in source goal order.
+materialize(answer, 1).
+left(ok).
+right(ok).
+answer(ok) :- left(ok), right(ok).

package/test/conformance/proofs/proofs/iri_atom.eye

@@ -0,0 +1,4 @@
+% Reference 12: proof output preserves angle-bracket IRI atom read-back.
+materialize(label, 2).
+name(<urn:example:a>, "Alice").
+label(?iri, ?name) :- name(?iri, ?name).

package/test/conformance/proofs/proofs/list_builtin.eye

@@ -0,0 +1,3 @@
+% Reference 12: proof output preserves list read-back for built-in goals.
+materialize(answer, 1).
+answer(?x) :- member(?x, [a, b]), eq(?x, b).

package/test/conformance/proofs/proofs/once_child.eye

@@ -0,0 +1,5 @@
+% Reference 12: once/1 proof output includes the proof for the selected child goal.
+materialize(answer, 1).
+choice(a).
+choice(b).
+answer(?x) :- once(choice(?x)).

package/test/conformance/proofs/proofs/rule_fact.eye

@@ -0,0 +1,4 @@
+% Reference 12: proof output records the source rule and source fact used for an answer.
+materialize(answer, 1).
+seed(ok).
+answer(?x) :- seed(?x).

package/test/conformance/proofs/proofs/table_recursive.eye

@@ -0,0 +1,7 @@
+% Reference 12: tabled recursive proofs still explain the successful derivation path.
+materialize(path, 2).
+table(path, 2).
+edge(a, b).
+edge(b, c).
+path(?x, ?y) :- edge(?x, ?y).
+path(?x, ?z) :- edge(?x, ?y), path(?y, ?z).

package/test/run-conformance-report.mjs

@@ -7,12 +7,14 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)));
+const packageRoot = path.resolve(root, '..');
 const conformanceRoot = path.join(root, 'conformance');
 
 const KINDS = [
   { kind: 'cases', expectedKind: 'expected', expectedExt: '.eye', column: 'positive' },
   { kind: 'errors', expectedKind: 'expected-errors', expectedExt: '.txt', column: 'errors' },
   { kind: 'warnings', expectedKind: 'expected-warnings', expectedExt: '.eye', column: 'warnings' },
+  { kind: 'proofs', expectedKind: 'expected-proofs', expectedExt: '.eye', column: 'proofs' },
 ];
 
 export function buildConformanceReport() {
@@ -45,8 +47,9 @@ export function buildConformanceReport() {
     positive: acc.positive + row.positive,
     errors: acc.errors + row.errors,
     warnings: acc.warnings + row.warnings,
+    proofs: acc.proofs + row.proofs,
     total: acc.total + row.total,
-  }), { positive: 0, errors: 0, warnings: 0, total: 0 });
+  }), { positive: 0, errors: 0, warnings: 0, proofs: 0, total: 0 });
 
   return { rows, total, issues: issues.sort() };
 }
@@ -57,14 +60,14 @@ export function formatConformanceReport(report = buildConformanceReport()) {
     '',
     'This report summarizes the file-based conformance corpus under `test/conformance/`.',
     '',
-    '| Category | Positive | Errors | Warnings | Total |',
-    '|---|---:|---:|---:|---:|',
+    '| Category | Positive | Errors | Warnings | Proofs | Total |',
+    '|---|---:|---:|---:|---:|---:|',
   ];
 
   for (const row of report.rows) {
-    lines.push(`| ${row.category} | ${row.positive} | ${row.errors} | ${row.warnings} | ${row.total} |`);
+    lines.push(`| ${row.category} | ${row.positive} | ${row.errors} | ${row.warnings} | ${row.proofs} | ${row.total} |`);
   }
-  lines.push(`| **Total** | **${report.total.positive}** | **${report.total.errors}** | **${report.total.warnings}** | **${report.total.total}** |`);
+  lines.push(`| **Total** | **${report.total.positive}** | **${report.total.errors}** | **${report.total.warnings}** | **${report.total.proofs}** | **${report.total.total}** |`);
 
   if (report.issues.length > 0) {
     lines.push('', '## Corpus issues', '');
@@ -95,7 +98,7 @@ function categoryOf(file) {
 function ensureCategory(categories, category) {
   let counts = categories.get(category);
   if (!counts) {
-    counts = { positive: 0, errors: 0, warnings: 0, total: 0 };
+    counts = { positive: 0, errors: 0, warnings: 0, proofs: 0, total: 0 };
     categories.set(category, counts);
   }
   return counts;
@@ -103,6 +106,15 @@ function ensureCategory(categories, category) {
 
 if (process.argv[1] != null && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
   const report = buildConformanceReport();
-  process.stdout.write(formatConformanceReport(report));
+  const text = formatConformanceReport(report);
+  const outputPath = process.argv[2] ?? null;
+  if (outputPath == null) {
+    process.stdout.write(text);
+  } else {
+    const resolved = path.resolve(packageRoot, outputPath);
+    fs.mkdirSync(path.dirname(resolved), { recursive: true });
+    fs.writeFileSync(resolved, text);
+    process.stdout.write(`wrote ${path.relative(packageRoot, resolved)}\n`);
+  }
   if (report.issues.length > 0) process.exit(1);
 }

package/test/run-conformance.mjs

@@ -20,6 +20,7 @@ export function runConformance(reporter = new TestReporter(), requestedFilter =
   for (const file of listCaseFiles('cases', filter)) runCaseFile(reporter, file);
   for (const file of listCaseFiles('errors', filter)) runErrorFile(reporter, file);
   for (const file of listCaseFiles('warnings', filter)) runWarningFile(reporter, file);
+  for (const file of listCaseFiles('proofs', filter)) runProofFile(reporter, file);
   reporter.sectionTotal(`conformance ${label}`);
 }
 
@@ -70,6 +71,11 @@ function runWarningFile(reporter, file) {
   reporter.test(`warning/${name}`, () => runWarningCase(name, file));
 }
 
+function runProofFile(reporter, file) {
+  const name = file.slice(0, -4);
+  reporter.test(`proof/${name}`, () => runProofCase(name, file));
+}
+
 function runCase(name, file) {
   const casesDir = path.join(root, 'conformance', 'cases');
   const expectedDir = path.join(root, 'conformance', 'expected');
@@ -122,6 +128,29 @@ function runWarningCase(name, file) {
   compareExpectedFile(expectedStderr, result.stderr, name, 'warning stderr');
 }
 
+function runProofCase(name, file) {
+  const proofsDir = path.join(root, 'conformance', 'proofs');
+  const expectedDir = path.join(root, 'conformance', 'expected-proofs');
+  const programFile = path.join(proofsDir, file);
+  const expected = path.join(expectedDir, `${name}.eye`);
+  const text = fs.readFileSync(programFile, 'utf8');
+  const result = spawnSync(process.execPath, [cliBin, '--proof', '-'], {
+    cwd: packageRoot,
+    input: text,
+    encoding: 'utf8',
+  });
+
+  if (result.status !== 0) {
+    throw new Error(`proof case ${name} exited with ${result.status}\n${result.stderr}`.trimEnd());
+  }
+  if (result.stderr !== '') {
+    throw new Error(`proof case ${name} wrote unexpected stderr\n${result.stderr}`.trimEnd());
+  }
+
+  compareExpectedFile(expected, result.stdout, name, 'proof output');
+  Program.parse(result.stdout);
+}
+
 function compareExpectedFile(expected, actual, name, kind) {
   if (!fs.existsSync(expected)) {
     throw new Error(`missing expected ${kind} file: ${path.relative(root, expected)}`);

package/test/run-regression.mjs

@@ -372,12 +372,22 @@ function documentationSyncCases() {
         const report = buildConformanceReport();
         assertArrayEqual(report.issues, [], 'conformance report issues');
         assertEqual(report.total.total >= 250, true, 'conformance case count');
-        assertEqual(report.total.positive + report.total.errors + report.total.warnings, report.total.total, 'conformance total');
+        assertEqual(report.total.positive + report.total.errors + report.total.warnings + report.total.proofs, report.total.total, 'conformance total');
         const text = formatConformanceReport(report);
         assertIncludes(text, '| variables |', 'report');
+        assertIncludes(text, '| Proofs |', 'report');
         assertIncludes(text, '| **Total** |', 'report');
       },
     },
+
+    {
+      name: 'committed conformance report is current',
+      run: () => {
+        const reportFile = path.join(packageRoot, 'conformance-report.md');
+        assertEqual(fs.existsSync(reportFile), true, 'conformance-report.md exists');
+        assertEqual(fs.readFileSync(reportFile, 'utf8'), formatConformanceReport(buildConformanceReport()), 'conformance-report.md');
+      },
+    },
     {
       name: 'source-checkout setup docs match package bin',
       run: () => {