"""Edges of the change warning (contract K4) that the frozen eval does not cover: `okfwiki.sources diff` and `marks`. The eval (`tests/test_change_warning.py`) holds the whole output on one planted pair of roots. These tests hold what it leaves open, one choice each: - a page in a subfolder is named by its path under the collection, with "/" (chose this because the auditor names pages that way, `okfwiki.audit.load_bundle`, so a mark and a finding name the same page the same way); - a page without frontmatter cites nothing, so it is never marked (sources live in the frontmatter, SPEC section 11.1); - a page whose frontmatter cannot be read stops marks with exit 2 (chose this because such a page may cite a changed source, and a list that skipped it would be a negative nobody measured; the auditor reports the page itself); - two roots with another collection stop diff with exit 2 (chose this because their paths can only match by chance, so every "gone" and "new" would be noise); - a source whose kind changed is changed, also with the same bytes (chose this because the kind decides what the source is to the build, a main page or history, so the pages on it must be looked at again; the report keeps both sha256). Every source and page here is synthetic (bread and gardening). Run: python3 -m unittest discover -s tests -p 'test_source_diff.py' """ from __future__ import annotations import hashlib import io import json import sys import tempfile import unittest from contextlib import redirect_stderr, redirect_stdout from pathlib import Path from typing import Any ROOT = Path(__file__).resolve().parents[1] sys.path.insert(0, str(ROOT)) from okfwiki import sources # noqa: E402 OLD_AT = "2026-10-08T06:30:00Z" NEW_AT = "2026-10-09T06:30:00Z" BREAD = "# Bread\n\nFlour, water and salt.\n" SOIL = "# Soil\n\nCompost feeds the soil.\n" def sha(data: bytes) -> str: return hashlib.sha256(data).hexdigest() def run_main(argv: list[str]) -> tuple[int, str, str]: out, err = io.StringIO(), io.StringIO() with redirect_stdout(out), redirect_stderr(err): code = sources.main(argv) return code, out.getvalue(), err.getvalue() def write_root(root: Path, files: dict[str, tuple[str, str]], frozen_at: str, collection: str = "garden") -> bytes: """A K1 root from {name: (kind, text)}; returns the manifest's bytes.""" (root / "kilde").mkdir(parents=True) entries = [] for name, (kind, text) in sorted(files.items()): data = text.encode("utf-8") (root / "kilde" / name).write_bytes(data) entry: dict[str, Any] = {"bytes": len(data), "kind": kind, "lines": len(text.splitlines()), "main_topic": kind == "docs", "path": f"kilde/{name}", "sha256": sha(data), "url": f"https://example.org/{name}"} if kind == "release-notes": entry["version"] = "1.0.0" entries.append(entry) text = sources.dump({"collection": collection, "frozen_at": frozen_at, "schema": sources.SCHEMA, "sources": entries, "subset_of": None}) (root / sources.MANIFEST).write_text(text, encoding="utf-8") return text.encode("utf-8") def page(*resources: str) -> str: cites = "".join(f" - id: s-{n}\n resource: /kilde/{r}\n" for n, r in enumerate(resources, 1)) return f"---\ntype: Concept\ntitle: Bread\nsources:\n{cites}---\n\n# Bread\n\nA loaf.[^s-1]\n" def diff_doc(changed: list[str] = [], gone: list[str] = []) -> dict[str, Any]: stamp = {"frozen_at": OLD_AT, "manifest_sha256": "a" * 64} return {"changed": [{"kind": "docs", "new_sha256": "b" * 64, "old_sha256": "c" * 64, "path": f"kilde/{n}"} for n in changed], "gone": [{"kind": "docs", "path": f"kilde/{n}"} for n in gone], "new": stamp, "new_sources": [], "old": stamp, "schema": "okf-wiki/source-diff/1", "unchanged": 0} class Base(unittest.TestCase): def setUp(self) -> None: self._tmp = tempfile.TemporaryDirectory() self.tmp = Path(self._tmp.name) def tearDown(self) -> None: self._tmp.cleanup() class DiffEdgeTest(Base): def test_roots_of_another_collection_cannot_be_compared(self) -> None: write_root(self.tmp / "old", {"docs-en-bread.md": ("docs", BREAD)}, OLD_AT, collection="garden") write_root(self.tmp / "new", {"docs-en-bread.md": ("docs", BREAD)}, NEW_AT, collection="bakery") code, out, err = run_main(["diff", str(self.tmp / "old"), str(self.tmp / "new")]) self.assertEqual((code, out), (2, "")) self.assertIn("collection", err) def test_a_source_whose_kind_changed_is_changed_even_with_the_same_bytes(self) -> None: write_root(self.tmp / "old", {"docs-en-bread.md": ("docs", BREAD), "docs-en-soil.md": ("docs", SOIL)}, OLD_AT) new = write_root(self.tmp / "new", {"docs-en-bread.md": ("release-notes", BREAD), "docs-en-soil.md": ("docs", SOIL)}, NEW_AT) code, out, _ = run_main(["diff", str(self.tmp / "old"), str(self.tmp / "new")]) self.assertEqual(code, 1) doc = json.loads(out) h = sha(BREAD.encode()) self.assertEqual(doc["changed"], [{"kind": "release-notes", "new_sha256": h, "old_sha256": h, "path": "kilde/docs-en-bread.md"}]) self.assertEqual(doc["unchanged"], 1) self.assertEqual(doc["new"]["manifest_sha256"], sha(new)) def test_diff_is_also_a_function_that_returns_the_report(self) -> None: write_root(self.tmp / "old", {"docs-en-bread.md": ("docs", BREAD)}, OLD_AT) write_root(self.tmp / "new", {"docs-en-soil.md": ("docs", SOIL)}, NEW_AT) report = sources.diff(self.tmp / "old", self.tmp / "new") self.assertEqual(report["gone"], [{"kind": "docs", "path": "kilde/docs-en-bread.md"}]) self.assertEqual(report["new_sources"], [{"kind": "docs", "path": "kilde/docs-en-soil.md"}]) self.assertTrue(sources.has_change(report)) class MarksEdgeTest(Base): def setUp(self) -> None: super().setUp() self.wiki = self.tmp / "wiki" self.wiki.mkdir() self.diff = self.tmp / "diff.json" self.diff.write_text(sources.dump(diff_doc(changed=["docs-en-bread.md"])), encoding="utf-8") def marks(self) -> tuple[int, str, str]: return run_main(["marks", str(self.wiki), "--diff", str(self.diff)]) def test_a_page_in_a_subfolder_is_named_by_its_path_under_the_collection(self) -> None: (self.wiki / "baking").mkdir() (self.wiki / "baking" / "loaf.md").write_text(page("docs-en-bread.md"), encoding="utf-8") code, out, _ = self.marks() self.assertEqual(code, 1) self.assertEqual(json.loads(out)["pages"], [{"page": "baking/loaf.md", "sources": [ {"change": "changed", "path": "kilde/docs-en-bread.md"}]}]) def test_pages_are_sorted_on_their_name_as_a_string_and_a_source_cited_twice_is_listed_once(self) -> None: # "a-b.md" sorts before "a/b.md" as a string ("-" < "/"), though a walk of the folder gives the other order. (self.wiki / "a").mkdir() (self.wiki / "a" / "b.md").write_text(page("docs-en-bread.md"), encoding="utf-8") (self.wiki / "a-b.md").write_text(page("docs-en-bread.md", "docs-en-bread.md"), encoding="utf-8") code, out, _ = self.marks() self.assertEqual(code, 1) mark = [{"change": "changed", "path": "kilde/docs-en-bread.md"}] self.assertEqual(json.loads(out)["pages"], [{"page": "a-b.md", "sources": mark}, {"page": "a/b.md", "sources": mark}]) def test_a_page_without_frontmatter_cites_nothing_and_is_not_marked(self) -> None: (self.wiki / "notes.md").write_text("# Notes\n\nSee /kilde/docs-en-bread.md for bread.\n", encoding="utf-8") code, out, _ = self.marks() self.assertEqual((code, out), (0, sources.dump({"pages": [], "schema": "okf-wiki/source-marks/1"}))) def test_a_page_whose_frontmatter_cannot_be_read_stops_marks(self) -> None: (self.wiki / "loaf.md").write_text(page("docs-en-bread.md"), encoding="utf-8") (self.wiki / "broken.md").write_text("---\ntype: [Concept\n---\n\n# Broken\n", encoding="utf-8") code, out, err = self.marks() self.assertEqual((code, out), (2, "")) self.assertIn("broken.md", err) def test_a_diff_of_another_schema_cannot_be_used(self) -> None: self.diff.write_text(sources.dump({**diff_doc(), "schema": "okf-wiki/source-manifest/1"}), encoding="utf-8") self.assertEqual(self.marks()[0], 2) def test_a_collection_that_is_not_a_folder_cannot_be_marked(self) -> None: code, _, _ = run_main(["marks", str(self.tmp / "nowhere"), "--diff", str(self.diff)]) self.assertEqual(code, 2) if __name__ == "__main__": unittest.main()