okf-wiki 1.1.1

First public release, published as one snapshot. What changed between
versions is in CHANGELOG.md.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
This commit is contained in:
Kjell Tore Guttormsen 2026-11-14 21:03:20 +01:00
commit 0fd86a23a3
Signed by: ktg
SSH key fingerprint: SHA256:JakMjO6FTBBzN0Bhfj9saOoEjaFxlSdYuZQQpM/lF9Q
227 changed files with 96077 additions and 0 deletions

175
tests/test_source_diff.py Normal file
View file

@ -0,0 +1,175 @@
"""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()