Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .gitattributes
Original file line number Diff line number Diff line change
Expand Up @@ -11,3 +11,6 @@
*.jpg binary
*.gif binary
*.ico binary

# Conformance vectors are compared byte-for-byte by every port's test suite
vectors/** text eol=lf
19 changes: 19 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,25 @@ share this file and, from 1.3.0, a single version number.
The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and the project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added

- **Core Conformance Corpus** (`vectors/`): 31 executable ISON/ISONL
documents with a per-port expectation each, run by the Python, TypeScript
and JavaScript suites on every push. One golden fixture used to be the only
thing saying the ports agree; the corpus says it per document, and records
where they still do not (`vectors/README.md` § Findings): TS/JS accept a
MultiGraph document that Python refuses (and that Rust, C# and C++ refuse
by their own unit tests - their corpus runners are still to come),
ison-ts/ison-js write the string `nan` bare where ison-py quotes it, and
ids or values beyond 2^53 come back rounded in TS/JS unless the value
happens to be exactly representable in binary64. Rust, C# and C++ columns
are `todo` until each gets a runner - admission is all-or-nothing per port.
- `scripts/corpus_digest.py` and `scripts/corpus_receipt.py`, which produce
what ISONGraphExt pins: the corpus digest and a per-port Core Conformance
Receipt with a derived posture.

## [1.4.1] — 2026-11-05

Four ways a graph's meaning changed between `dump` and `load`, found while
Expand Down
73 changes: 73 additions & 0 deletions ison-graph-js/src/vectors.test.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
/**
* Core Conformance Corpus runner for the JavaScript port.
* Reads vectors/manifest.ison with ison-parser and checks the 'js' column.
* Grammar and columns: vectors/README.md.
*/
import { describe, it, expect } from 'vitest';
import { readFileSync } from 'node:fs';
import { dirname, resolve } from 'node:path';
import { fileURLToPath } from 'node:url';
import { loads as parse } from 'ison-parser';
import { ISONGraph } from './index.js';

const VECTORS = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..', 'vectors');
const PORT = 'js';

const read = (rel) => readFileSync(resolve(VECTORS, rel), 'utf8');
const rows = parse(read('manifest.ison')).blocks
.filter((b) => b.kind === 'table' && b.name === 'vectors')
.flatMap((b) => b.rows);
const load = (rel, text) =>
rel.endsWith('.isonl') ? ISONGraph.fromIsonl(text) : ISONGraph.fromIson(text);
const emit = (g) => g.toIson() + '\n';

describe('Core Conformance Corpus (js)', () => {
it('manifest has rows', () => {
expect(rows.length).toBeGreaterThan(0);
});

it('is admitted: no todo in its column', () => {
expect(rows.filter((r) => r[PORT] === 'todo').map((r) => r.id)).toEqual([]);
});

describe.each(rows.map((r) => [r.id, r]))('%s', (_id, row) => {
it('behaves as the manifest says', () => {
const expectation = row[PORT];
const text = read(row.file);

if (expectation.startsWith('reject:')) {
let name = '';
try {
load(row.file, text);
} catch (e) {
name = e.name ?? e.constructor.name;
}
expect(name).toBe(expectation.slice('reject:'.length));
return;
}

const g = load(row.file, text);
expect(g.directed).toBe(row.directed);
expect(g.nodeCount()).toBe(row.nodes);
expect(g.edgeCount()).toBe(row.edges);

const out = emit(g);
if (expectation === 'defect') {
// Contradicts the spec (README Findings) - pin what the port does.
expect(emit(ISONGraph.fromIson(out))).toBe(out);
} else if (expectation === 'pass') {
expect(out).toBe(text);
} else if (expectation === 'pass:canonicalized') {
expect(out).toBe(read(row.canonical));
expect(emit(ISONGraph.fromIson(out))).toBe(out);
} else if (expectation === 'pass:lossy') {
// The loss must be real: if the port now preserves the input, the
// cell is stale and should become 'pass'.
expect(out, 'pass:lossy but output equals the file - promote the cell to pass').not.toBe(text);
expect(emit(ISONGraph.fromIson(out))).toBe(out);
} else {
throw new Error(`unknown expectation ${JSON.stringify(expectation)} for ${PORT}`);
}
});
});
});
75 changes: 75 additions & 0 deletions ison-graph-ts/src/vectors.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
/**
* Core Conformance Corpus runner for the TypeScript port.
* Reads vectors/manifest.ison with ison-ts and checks the 'ts' column.
* Grammar and columns: vectors/README.md.
*/
import { describe, it, expect } from 'vitest';
import { readFileSync } from 'node:fs';
import { dirname, resolve } from 'node:path';
import { fileURLToPath } from 'node:url';
import { parse } from 'ison-ts';
import { ISONGraph } from './index';

const VECTORS = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..', 'vectors');
const PORT = 'ts';

type Row = Record<string, any>;

const read = (rel: string): string => readFileSync(resolve(VECTORS, rel), 'utf8');
const rows: Row[] = parse(read('manifest.ison')).blocks
.filter((b: any) => b.kind === 'table' && b.name === 'vectors')
.flatMap((b: any) => b.rows as Row[]);
const load = (rel: string, text: string): ISONGraph =>
rel.endsWith('.isonl') ? ISONGraph.fromIsonl(text) : ISONGraph.fromIson(text);
const emit = (g: ISONGraph): string => g.toIson() + '\n';

describe('Core Conformance Corpus (ts)', () => {
it('manifest has rows', () => {
expect(rows.length).toBeGreaterThan(0);
});

it('is admitted: no todo in its column', () => {
expect(rows.filter(r => r[PORT] === 'todo').map(r => r.id)).toEqual([]);
});

describe.each(rows.map(r => [r.id as string, r] as const))('%s', (_id, row) => {
it('behaves as the manifest says', () => {
const expectation = row[PORT] as string;
const text = read(row.file);

if (expectation.startsWith('reject:')) {
let name = '';
try {
load(row.file, text);
} catch (e: any) {
name = e.name ?? e.constructor.name;
}
expect(name).toBe(expectation.slice('reject:'.length));
return;
}

const g = load(row.file, text);
expect(g.directed).toBe(row.directed);
expect(g.nodeCount()).toBe(row.nodes);
expect(g.edgeCount()).toBe(row.edges);

const out = emit(g);
if (expectation === 'defect') {
// Contradicts the spec (README Findings) - pin what the port does.
expect(emit(ISONGraph.fromIson(out))).toBe(out);
} else if (expectation === 'pass') {
expect(out).toBe(text);
} else if (expectation === 'pass:canonicalized') {
expect(out).toBe(read(row.canonical));
expect(emit(ISONGraph.fromIson(out))).toBe(out);
} else if (expectation === 'pass:lossy') {
// The loss must be real: if the port now preserves the input, the
// cell is stale and should become 'pass'.
expect(out, 'pass:lossy but output equals the file - promote the cell to pass').not.toBe(text);
expect(emit(ISONGraph.fromIson(out))).toBe(out);
} else {
throw new Error(`unknown expectation ${JSON.stringify(expectation)} for ${PORT}`);
}
});
});
});
108 changes: 108 additions & 0 deletions ison-graph/tests/test_corpus_scripts.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,108 @@
"""Tests for the repo-level corpus scripts (scripts/corpus_digest.py and
scripts/corpus_receipt.py). They live outside the package, so they are
imported by path."""

from __future__ import annotations

import hashlib
import importlib.util
import re
import sys
from pathlib import Path

import pytest

ROOT = Path(__file__).resolve().parents[2]
SCRIPTS = ROOT / "scripts"


def _import(name: str):
spec = importlib.util.spec_from_file_location(name, SCRIPTS / f"{name}.py")
module = importlib.util.module_from_spec(spec)
sys.modules[name] = module
spec.loader.exec_module(module)
return module


digest_mod = _import("corpus_digest")


def _make(tmp_path: Path, files: dict[str, bytes]) -> Path:
for rel, data in files.items():
p = tmp_path / rel
p.parent.mkdir(parents=True, exist_ok=True)
p.write_bytes(data)
return tmp_path


def test_digest_is_sha256_over_sorted_path_and_bytes(tmp_path):
root = _make(tmp_path, {"b/two.ison": b"2\n", "a.ison": b"1\n"})
expected = hashlib.sha256(b"a.ison\0" + b"1\n" + b"\0" + b"b/two.ison\0" + b"2\n" + b"\0").hexdigest()
assert digest_mod.corpus_digest(root) == expected


def test_digest_ignores_creation_order(tmp_path):
a = _make(tmp_path / "x", {"a.ison": b"1\n", "b.ison": b"2\n"})
b = _make(tmp_path / "y", {"b.ison": b"2\n", "a.ison": b"1\n"})
assert digest_mod.corpus_digest(a) == digest_mod.corpus_digest(b)


def test_digest_changes_when_a_byte_changes(tmp_path):
root = _make(tmp_path, {"a.ison": b"1\n"})
before = digest_mod.corpus_digest(root)
(root / "a.ison").write_bytes(b"1 \n")
assert digest_mod.corpus_digest(root) != before


def test_real_corpus_digest_is_stable_across_two_calls():
d1 = digest_mod.corpus_digest(ROOT / "vectors")
d2 = digest_mod.corpus_digest(ROOT / "vectors")
assert d1 == d2 and len(d1) == 64


receipt_mod = _import("corpus_receipt")


@pytest.mark.parametrize("cells,runner,expected", [
(["pass", "reject:X", "pass:canonicalized"], True, "FULL"),
(["pass", "pass:lossy"], True, "LOSSY_KNOWN"),
(["pass", "defect"], True, "KNOWN_DEFECT"),
(["pass:lossy", "defect"], True, "KNOWN_DEFECT"),
(["todo", "todo"], False, "PARTIAL"),
(["pass", "todo"], True, "INCONCLUSIVE"),
(["pass"], False, "INCONCLUSIVE"),
])
def test_posture(cells, runner, expected):
assert receipt_mod.posture(cells, runner) == expected


def test_receipt_for_python_is_full_and_counts_add_up():
r = receipt_mod.build_receipt(ROOT, "python")
assert r["port"] == "python"
assert r["core_format"] == "isongraph"
assert r["semantic_spec"] == "ISONGraph-Semantic/2-draft"
assert r["corpus_version"] == 1
assert len(r["corpus_digest"]) == 64
assert re.fullmatch(r"[0-9a-f]{40}", r["core_commit"])
assert re.fullmatch(r"[0-9a-f]{40}", r["corpus_commit"])
assert r["posture"] == "FULL"
assert r["total"] == r["pass"] + r["canonicalized"] + r["lossy"] + r["defect"] + r["rejected_as_expected"] + r["todo"]
assert r["todo"] == 0


def test_receipt_for_ts_is_known_defect():
r = receipt_mod.build_receipt(ROOT, "ts")
assert r["posture"] == "KNOWN_DEFECT"
assert r["defect"] >= 1 and r["lossy"] >= 1


def test_receipt_for_rust_is_partial():
r = receipt_mod.build_receipt(ROOT, "rust")
assert r["posture"] == "PARTIAL" and r["todo"] == r["total"]


def test_receipt_cli_prints_ison(capsys):
assert receipt_mod.main(["corpus_receipt.py", "--port", "python"]) == 0
out = capsys.readouterr().out
assert out.startswith("meta.core_conformance_receipt\n")
assert " FULL" in out
Loading
Loading