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

236
tests/test_folder_watch.py Normal file
View file

@ -0,0 +1,236 @@
"""The change warning for a folder (motor B15): `okfwiki.sources` records the folder a copy was read from, reads it
again from there (`reread`), and checks it in one command any scheduler can run (`watch`), with no tie to collection 1.
Choices held here, one test each or more:
- the manifest of a folder copy names the folder (`folder`, its resolved path), so a new reading needs only the copy;
a copy frozen before the field existed gets the folder from its entries (`url` less the `original` path), and a copy
whose entries do not agree, or that was not read from a folder, cannot be read again;
- a difference names the file as the user knows it (`original`) beside its path under kilde/;
- watch reads the folder again into INTO/latest, writes diff.json (and marks.json with --bundle) there, keeps the lines
it last reported in INTO/watch-state.json, and exits 1 only when something is new since the last run (0 when not),
so a scheduler can act on the exit code; INTO inside the watched folder is refused, since the next reading would
take the watch's own files for documents.
Every document here is synthetic (gardening). Run: python3 -m unittest discover -s tests -p 'test_folder_watch.py'
"""
from __future__ import annotations
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
FROZEN = "2026-11-08T06:00:00Z"
LATER = "2026-11-09T06:00:00Z"
LAST = "2026-11-10T06:00:00Z"
def run_main(argv: list[str]) -> tuple[int, 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 manifest(root: Path) -> dict[str, Any]:
doc: dict[str, Any] = json.loads((root / "source-manifest.json").read_text(encoding="utf-8"))
return doc
def page(cites: list[str]) -> str:
lines = "".join(f" - resource: /{c}\n x-locator: line 3\n" for c in cites)
return f"---\ntype: concept\ntitle: X\nsources:\n{lines}---\n\nText.\n"
class WatchBase(unittest.TestCase):
def setUp(self) -> None:
self._tmp = tempfile.TemporaryDirectory()
self.tmp = Path(self._tmp.name)
self.src = self.tmp / "Hagebok"
self.write({"Såing.md": "# Såing\n\nSå i april.\n", "Jord/Kompost.md": "# Kompost\n\nVend hver uke.\n",
"stell.txt": "Vann om kvelden.\n"})
self.root = self.tmp / "sources"
code, text = run_main(["folder", str(self.src), "--collection", "hage", "--out", str(self.root),
"--frozen-at", FROZEN])
self.assertEqual(code, 0, text)
def tearDown(self) -> None:
self._tmp.cleanup()
def write(self, files: dict[str, str]) -> None:
for rel, text in files.items():
p = self.src / rel
p.parent.mkdir(parents=True, exist_ok=True)
p.write_text(text, encoding="utf-8")
def change_folder(self) -> None:
self.write({"Såing.md": "# Såing\n\nSå i mai.\n", "Nytt/Høst.md": "# Høst\n\nHøst i september.\n"})
(self.src / "stell.txt").unlink()
class FolderRecordTest(WatchBase):
def test_the_manifest_names_the_folder_it_was_read_from(self) -> None:
self.assertEqual(manifest(self.root)["folder"], str(self.src.resolve()))
self.assertEqual(sources.check(self.root), [])
def test_check_refuses_a_folder_that_is_not_an_absolute_path(self) -> None:
doc = manifest(self.root)
for bad in ("", "Hagebok", 7):
doc["folder"] = bad
(self.root / "source-manifest.json").write_text(json.dumps(doc), encoding="utf-8")
self.assertTrue(any(p.startswith("folder is") for p in sources.check(self.root)), bad)
class RereadTest(WatchBase):
def reread(self, out: Path, root: Path | None = None) -> tuple[int, str]:
return run_main(["reread", str(root or self.root), "--out", str(out), "--frozen-at", LATER])
def test_reread_reads_the_recorded_folder_again_as_the_same_collection(self) -> None:
self.change_folder()
out = self.tmp / "sources-2"
code, text = self.reread(out)
self.assertEqual(code, 0, text)
self.assertIn(str(self.src.resolve()), text)
doc = manifest(out)
self.assertEqual((doc["collection"], doc["frozen_at"], doc["folder"]), ("hage", LATER, str(self.src.resolve())))
self.assertEqual(sources.check(out), [])
report = sources.diff(self.root, out)
self.assertEqual([e["path"] for e in report["changed"]], ["kilde/saaing.md"])
self.assertEqual([e["path"] for e in report["new_sources"]], ["kilde/nytt__hoest.md"])
self.assertEqual([e["path"] for e in report["gone"]], ["kilde/stell.txt"])
def test_a_copy_frozen_before_the_folder_field_gets_the_folder_from_its_entries(self) -> None:
doc = manifest(self.root)
del doc["folder"]
(self.root / "source-manifest.json").write_text(json.dumps(doc), encoding="utf-8")
out = self.tmp / "sources-2"
code, text = self.reread(out)
self.assertEqual(code, 0, text)
self.assertEqual(manifest(out)["folder"], str(self.src.resolve()))
self.assertEqual(sources.diff(self.root, out)["unchanged"], 3)
def test_entries_that_name_two_folders_cannot_be_read_again(self) -> None:
doc = manifest(self.root)
del doc["folder"]
doc["sources"][0]["url"] = (self.tmp / "Annen" / doc["sources"][0]["original"]).as_uri()
(self.root / "source-manifest.json").write_text(json.dumps(doc), encoding="utf-8")
code, text = self.reread(self.tmp / "sources-2")
self.assertEqual(code, 2, text)
self.assertIn("more than one folder", text)
def test_a_copy_not_read_from_a_folder_cannot_be_read_again(self) -> None:
doc = manifest(self.root)
del doc["folder"]
for e in doc["sources"]:
e["url"] = "https://example.org/" + e["original"]
(self.root / "source-manifest.json").write_text(json.dumps(doc), encoding="utf-8")
code, text = self.reread(self.tmp / "sources-2")
self.assertEqual(code, 2, text)
self.assertIn("not read from a folder", text)
def test_a_folder_that_is_gone_cannot_be_read_again(self) -> None:
moved = self.tmp / "Flyttet"
self.src.rename(moved)
code, text = self.reread(self.tmp / "sources-2")
self.assertEqual(code, 2, text)
self.assertIn(str(self.src.resolve()), text)
class DiffOriginalTest(WatchBase):
def test_each_difference_names_the_file_as_the_user_knows_it(self) -> None:
self.change_folder()
out = self.tmp / "sources-2"
self.assertEqual(run_main(["reread", str(self.root), "--out", str(out), "--frozen-at", LATER])[0], 0)
report = sources.diff(self.root, out)
self.assertEqual(report["changed"][0]["original"], "Såing.md")
self.assertEqual(report["new_sources"][0]["original"], "Nytt/Høst.md")
self.assertEqual(report["gone"][0]["original"], "stell.txt")
class WatchTest(WatchBase):
def setUp(self) -> None:
super().setUp()
self.into = self.tmp / "watch"
self.wiki = self.tmp / "wiki"
self.wiki.mkdir()
(self.wiki / "saaing.md").write_text(page(["kilde/saaing.md"]), encoding="utf-8")
(self.wiki / "stell.md").write_text(page(["kilde/stell.txt", "kilde/saaing.md"]), encoding="utf-8")
(self.wiki / "kompost.md").write_text(page(["kilde/jord__kompost.md"]), encoding="utf-8")
def watch(self, at: str, *extra: str) -> tuple[int, str]:
return run_main(["watch", str(self.root), "--into", str(self.into), "--frozen-at", at, *extra])
def test_an_unchanged_folder_reports_nothing_and_exits_0(self) -> None:
code, text = self.watch(LATER)
self.assertEqual(code, 0, text)
self.assertIn("0 new, 0 changed, 0 gone, 3 unchanged", text)
self.assertIn(" nothing differs\n", text)
self.assertEqual(sources.check(self.into / "latest"), [])
self.assertEqual(json.loads((self.into / "latest" / "diff.json").read_text(encoding="utf-8"))["unchanged"], 3)
def test_a_change_is_reported_by_original_name_with_the_pages_marked_and_exits_1(self) -> None:
self.change_folder()
code, text = self.watch(LATER, "--bundle", str(self.wiki))
self.assertEqual(code, 1, text)
self.assertIn("1 new, 1 changed, 1 gone, 1 unchanged", text)
self.assertIn("changed Såing.md (kilde/saaing.md), 2 page(s) marked", text)
self.assertIn("new Nytt/Høst.md (kilde/nytt__hoest.md)", text)
self.assertIn("gone stell.txt (kilde/stell.txt), 1 page(s) marked", text)
self.assertIn(f"2 page(s) marked in {self.wiki}", text)
marks = json.loads((self.into / "latest" / "marks.json").read_text(encoding="utf-8"))
self.assertEqual([p["page"] for p in marks["pages"]], ["saaing.md", "stell.md"])
def test_a_second_run_says_only_what_is_new_since_the_first(self) -> None:
self.change_folder()
self.assertEqual(self.watch(LATER)[0], 1)
code, text = self.watch(LAST)
self.assertEqual(code, 0, text)
self.assertIn("nothing new since the last run", text)
self.write({"Jord/Kompost.md": "# Kompost\n\nVend hver annen uke.\n"})
code, text = self.watch(LAST)
self.assertEqual(code, 1, text)
self.assertIn("changed Jord/Kompost.md", text)
self.assertNotIn("Såing.md", text.split("New since the last run:")[1])
def test_a_new_frozen_copy_starts_the_report_over(self) -> None:
self.change_folder()
self.assertEqual(self.watch(LATER)[0], 1)
rebuilt = self.tmp / "sources-rebuilt"
self.assertEqual(run_main(["reread", str(self.root), "--out", str(rebuilt), "--frozen-at", LATER])[0], 0)
code, text = run_main(["watch", str(rebuilt), "--into", str(self.into), "--frozen-at", LAST])
self.assertEqual(code, 0, text)
self.assertIn("0 new, 0 changed, 0 gone, 3 unchanged", text)
def test_latest_is_replaced_whole(self) -> None:
self.assertEqual(self.watch(LATER)[0], 0)
self.change_folder()
self.assertEqual(self.watch(LAST)[0], 1)
doc = manifest(self.into / "latest")
self.assertEqual(doc["frozen_at"], LAST)
self.assertEqual(sorted(p.name for p in self.into.iterdir()), ["latest", "watch-state.json"])
def test_into_inside_the_watched_folder_is_refused(self) -> None:
code, text = run_main(["watch", str(self.root), "--into", str(self.src / "watch"), "--frozen-at", LATER])
self.assertEqual(code, 2, text)
self.assertIn("inside the folder", text)
self.assertFalse((self.src / "watch").exists())
def test_a_copy_that_fails_check_cannot_be_watched(self) -> None:
(self.root / "kilde" / "saaing.md").chmod(0o644)
(self.root / "kilde" / "saaing.md").write_text("# Endret\n", encoding="utf-8")
code, text = self.watch(LATER)
self.assertEqual(code, 2, text)
self.assertIn("fails check", text)
if __name__ == "__main__":
unittest.main()