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

972
tests/test_kassemble.py Normal file
View file

@ -0,0 +1,972 @@
"""Tests for okfwiki/kassemble.py: K's pages from accepted fragments, by code, with no model call.
AssembleTest and the tests after it are ported from the trial's AssembleTest (evals/tests/test_p1_build.py) with rev 4
Step 12: code makes no link (links come only from a links file, placed by klink.place), each fragment's provenance is
x-provenance on its source entry, an existing output is refused without --replace and swapped with it, and format
choices (a)-(h) of PLAN.md section Rammer hold on the pages.
Wave 2, order 10 (Step 10, K2 points 11-14 and 17): the pages the compiler or the guard named are main pages and carry
x-main-for (sorted, no duplicates, left out on every other page); a main page lists the pages whose home it is under
"## Related concepts" as inline, relative links, and those are the only links code writes; the weekly pages, history by
K1, go under "## History" with the week from the file name; a link to a page that is gone is dropped and the page that
held it is listed. test_no_link_is_added_by_code became test_code_adds_only_the_home_links_the_model_chose.
The replacement test is order 5's addition (choice 4 of 06.10): one source's contribution can be replaced or removed
on its own. Six synthetic sources about bread go through the whole code path in two packs of three: order, blocks,
skeleton, pack, accept, build. Then source 3's fragments are replaced and the bundle is built again, and then source 3
is removed and the bundle is built a third time. Pages that do not cite source 3 must stay byte-identical, `generated`
included; pages that cite it change only in its sentences; pages only it fed disappear, and index.md follows. The
fragment files stand in for the compiler's output. Every fixture is synthetic text about bread or gardening (CLAUDE.md
rule 3).
Run: python3 -m unittest discover -s tests -p 'test_kassemble.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
from unittest import mock
import yaml
ROOT = Path(__file__).resolve().parents[1]
sys.path.insert(0, str(ROOT))
from okfwiki import audit, claims, kassemble, kblocks, klink, kpack, sources, view # noqa: E402
DOC_A = """# Sourdough
Sourdough bread rises with wild yeast instead of packet yeast.
## Starter
A starter is a mix of flour and water that ferments for about a week.
Feed the starter once a day with equal weights of flour and water.
## Flour
Rye flour makes a starter more lively than white flour.
"""
DOC_B = """# Proofing
Proofing is the last rise before the loaf goes into the oven.
## Cold proofing
A night in the fridge slows the rise and deepens the taste.
"""
DOC_C = """# Scoring
Scoring is a shallow cut across the top of the loaf.
Bakers score with a razor blade on a handle, called a lame.
## Starter strength
A strong starter doubles in size within six hours of a feed.
"""
DOC_D = """# Oven
A hot oven gives the crust its colour.
Bake the loaf when the dough springs back slowly from a finger.
## Steam
Steam in the first minutes lets the loaf open along its cuts.
"""
REL_1 = """## 1.2.0
- The starter guide now lists rye flour.
"""
REL_2 = """## 1.10.0
- The oven guide now covers steam.
"""
A, B, C, D = "docs-en-a.md", "docs-en-b.md", "docs-en-c.md", "docs-en-d.md"
R1, R2 = "release-v1.2.0.md", "release-v1.10.0.md"
SOURCES = {A: DOC_A, B: DOC_B, C: DOC_C, D: DOC_D, R1: REL_1, R2: REL_2}
T1, T2, T3 = "2026-10-08T10:00:00Z", "2026-10-09T10:00:00Z", "2026-10-10T10:00:00Z"
UNTOUCHED = {"sourdough.md", "flour.md", "proofing.md", "oven.md", "steam.md"} # the pages that never cite C
def run(module: Any, args: list[str]) -> int:
with redirect_stdout(io.StringIO()), redirect_stderr(io.StringIO()):
code: int = module.main(args)
return code
def frontmatter(text: str) -> dict[str, Any]:
"""The page's frontmatter, read as the auditor reads it (timestamps stay strings, format choice c)."""
data: dict[str, Any] = yaml.load(text.split("\n---\n", 1)[0].removeprefix("---\n"), Loader=audit._Loader)
return data
def body(text: str) -> str:
return text.split("\n---\n", 1)[1]
class Bakery(unittest.TestCase):
"""Six sources in two packs of three, accepted and built once at T1."""
def setUp(self) -> None:
self._tmp = tempfile.TemporaryDirectory()
tmp = Path(self._tmp.name)
self.root = tmp / "sources"
(self.root / "kilde").mkdir(parents=True)
for name, text in SOURCES.items():
(self.root / "kilde" / name).write_text(text, encoding="utf-8")
self.work = tmp / "work"
self.out = tmp / "bundle"
self.blocks = self.work / "blocks.json"
order = self.work / "order.txt"
self.ok(kblocks, ["order", str(self.root), "--out", str(order)])
self.ok(kblocks, ["blocks", str(self.root), "--order", str(order), "--out", str(self.blocks)])
self.ok(kpack, ["skeleton", "--sources", str(self.root), "--work", str(self.work)])
packs = {
1: [self.frag("Sourdough", A, "rises with wild yeast", "Sourdough rises with wild yeast.", eid="sourdough"),
self.frag("Starter", A, "ferments for about a week",
"A starter is flour and water that ferments for about a week.", eid="starter"),
self.frag("Starter", A, "equal weights of flour and water",
"Feed it once a day with equal weights of flour and water.", eid="starter"),
self.frag("Flour", A, "more lively than white flour",
"Rye flour makes a starter more lively than white flour.", eid="flour"),
self.frag("Proofing", B, "the last rise before the loaf goes into the oven",
"Proofing is the last rise before baking.", eid="proofing"),
self.frag("Proofing", B, "slows the rise", "A night in the fridge slows the rise.", eid="proofing"),
self.frag("Scoring", C, "a shallow cut across the top",
"Scoring is a shallow cut across the top of the loaf.", eid="scoring"),
self.frag("Starter", C, "doubles in size within six hours",
"A strong starter doubles within six hours of a feed.", eid="starter")],
2: [self.frag("Oven", D, "gives the crust its colour", "A hot oven colours the crust.", eid="oven"),
self.frag("Proofing", D, "springs back slowly from a finger",
"Bake when the dough springs back slowly.", provenance="inferred", eid="proofing"),
self.frag("Steam", D, "lets the loaf open along its cuts", "Steam lets the loaf open along its cuts.",
eid="steam"),
self.frag("Starter", R1, "lists rye flour", "The starter guide gained rye flour.", eid="starter"),
self.frag("Oven", R2, "covers steam", "The oven guide gained a part on steam.", eid="oven")],
}
for n, fragments in packs.items():
self.ok(kpack, ["pack", str(n), "--blocks", str(self.blocks), "--sources", str(self.root),
"--work", str(self.work), "--size", "3"])
path = self.work / "K-fragments" / f"pack-{n}.json"
path.parent.mkdir(parents=True, exist_ok=True)
path.write_text(json.dumps({"fragments": fragments}), encoding="utf-8")
self.ok(kpack, ["accept", str(n), "--blocks", str(self.blocks), "--sources", str(self.root),
"--work", str(self.work)])
self.build(T1, replace=False)
self.first = self.snapshot()
def tearDown(self) -> None:
self._tmp.cleanup()
def ok(self, module: Any, args: list[str]) -> None:
self.assertEqual(run(module, args), 0, args)
def frag(self, concept: str, file: str, quote: str, text: str, provenance: str = "documented",
eid: str | None = None, tests: dict[str, str] | None = None) -> dict[str, Any]:
"""A fragment anchored on the block whose line holds the quote, as the compiler would write it."""
line = next(n for n, raw in enumerate(SOURCES[file].split("\n"), 1) if quote in raw)
doc = json.loads(self.blocks.read_text(encoding="utf-8"))
block = next(b for b in doc["blocks"] if b["file"] == file and b["start"] <= line <= b["end"])
f: dict[str, Any] = {"concept": concept, "status": "existing" if tests is None else "new", "text": text,
"anchor": {"file": file, "start": block["start"], "end": block["end"]}, "quote": quote,
"provenance": provenance}
if eid is not None:
f["id"] = eid
if tests is not None:
f["tests"] = tests
return f
def build(self, at: str, replace: bool = True) -> None:
args = ["build", "--work", str(self.work), "--sources", str(self.root), "--out", str(self.out), "--at", at]
self.ok(kassemble, args + (["--replace"] if replace else []))
def snapshot(self) -> dict[str, bytes]:
return {p.name: p.read_bytes() for p in sorted(self.out.iterdir())}
def replace_c(self) -> None:
fragments = [
self.frag("Scoring", C, "a shallow cut across the top", "Scoring guides how the loaf opens in the oven.",
provenance="inferred", eid="scoring"),
self.frag("Lame", C, "called a lame", "A lame is a razor blade on a handle.",
tests={"topic_shape": "a tool for bakers", "citation": "Bakers score with a lame"}),
self.frag("Starter", C, "doubles in size within six hours",
"A strong starter doubles in size within six hours.", eid="starter"),
]
path = self.work / "K-fragments" / "replace-c.json"
path.write_text(json.dumps({"fragments": fragments}), encoding="utf-8")
self.ok(kpack, ["replace", C, "--fragments", str(path), "--blocks", str(self.blocks), "--sources",
str(self.root), "--work", str(self.work)])
def remove_c(self) -> None:
self.ok(kpack, ["remove", C, "--work", str(self.work)])
@staticmethod
def cites(page: bytes, file: str) -> bool:
srcs = frontmatter(page.decode("utf-8")).get("sources") or []
return any(s.get("resource") == "/kilde/" + file for s in srcs)
def labels_of(self, page: bytes, file: str) -> set[str]:
srcs = frontmatter(page.decode("utf-8")).get("sources") or []
return {str(s["id"]) for s in srcs if s.get("resource") == "/kilde/" + file}
def other_lines(self, page: bytes, file: str) -> list[str]:
"""The non-blank body lines that cite no label of `file`: what another source contributed."""
labels = self.labels_of(page, file)
return [line for line in body(page.decode("utf-8")).split("\n")
if line.strip() and not any(f"[^{x}]" in line for x in labels)]
def assert_changed_only_in(self, old: bytes, new: bytes, file: str, at: str) -> None:
fm_old, fm_new = frontmatter(old.decode("utf-8")), frontmatter(new.decode("utf-8"))
others = [s for s in fm_old["sources"] if s.get("resource") != "/kilde/" + file]
self.assertEqual([s for s in fm_new["sources"] if s.get("resource") != "/kilde/" + file], others)
self.assertEqual({k: v for k, v in fm_new.items() if k not in ("sources", "generated")},
{k: v for k, v in fm_old.items() if k not in ("sources", "generated")})
self.assertEqual(fm_new["generated"]["at"], at)
self.assertEqual(self.other_lines(new, file), self.other_lines(old, file))
self.assertNotEqual(new, old)
def index_entries(self) -> list[str]:
return [line for line in (self.out / "index.md").read_text(encoding="utf-8").split("\n") if line.startswith("- ")]
def assert_clean(self) -> None:
# link-rule (c) is retired in Step 7 and this collection has no links; every other check must pass.
found = [f for f in audit.audit(self.out, self.root) if f.check != "link-rule"]
self.assertEqual(found, [])
class ReplaceOneSourceTest(Bakery):
def test_the_fixture_has_the_pages_it_is_written_for(self) -> None:
pages = {n for n in self.first if n not in ("index.md", "log.md")}
self.assertEqual(pages, UNTOUCHED | {"starter.md", "scoring.md"})
self.assertEqual({n for n in pages if self.cites(self.first[n], C)}, {"starter.md", "scoring.md"})
self.assert_clean()
def test_pages_that_do_not_cite_the_replaced_source_stay_byte_identical(self) -> None:
self.replace_c()
self.build(T2)
second = self.snapshot()
for name in sorted(UNTOUCHED):
self.assertEqual(second[name], self.first[name], name)
self.assertEqual(frontmatter(second[name].decode("utf-8"))["generated"]["at"], T1, name)
self.assert_clean()
def test_pages_that_cite_it_change_only_in_its_sentences(self) -> None:
self.replace_c()
self.build(T2)
second = self.snapshot()
self.assert_changed_only_in(self.first["starter.md"], second["starter.md"], C, T2)
self.assertIn("A strong starter doubles in size within six hours.", second["starter.md"].decode("utf-8"))
self.assertIn("Scoring guides how the loaf opens in the oven.", second["scoring.md"].decode("utf-8"))
self.assertIn("lame.md", second) # a concept the new fragments create gets its page
self.assertEqual(frontmatter(second["lame.md"].decode("utf-8"))["generated"]["at"], T2)
self.assertEqual(len(self.index_entries()), len(UNTOUCHED) + 3)
def test_removing_the_source_drops_the_pages_only_it_fed(self) -> None:
self.replace_c()
self.build(T2)
self.remove_c()
self.build(T3)
third = self.snapshot()
self.assertNotIn("scoring.md", third)
self.assertNotIn("lame.md", third)
self.assertFalse(any("scoring.md" in e or "lame.md" in e for e in self.index_entries()))
self.assertEqual(len(self.index_entries()), len(UNTOUCHED) + 1)
for name in sorted(UNTOUCHED):
self.assertEqual(third[name], self.first[name], name)
self.assertFalse(self.cites(third["starter.md"], C))
self.assertEqual(self.other_lines(third["starter.md"], C), self.other_lines(self.first["starter.md"], C))
self.assertEqual(frontmatter(third["starter.md"].decode("utf-8"))["generated"]["at"], T3)
self.assert_clean()
def test_the_log_gains_one_entry_per_build_and_no_old_line_is_rewritten(self) -> None:
logs = [self.first["log.md"].decode("utf-8")]
self.replace_c()
self.build(T2)
logs.append((self.out / "log.md").read_text(encoding="utf-8"))
self.remove_c()
self.build(T3)
logs.append((self.out / "log.md").read_text(encoding="utf-8"))
for old, new in zip(logs, logs[1:]):
old_lines, new_lines = old.split("\n"), new.split("\n")
it = iter(new_lines)
self.assertTrue(all(line in it for line in old_lines), "an old log line was changed or reordered")
entries = [line for line in new_lines if line.startswith("* ")]
self.assertEqual(len(entries), len([line for line in old_lines if line.startswith("* ")]) + 1)
# ---------------------------------------------------------------------------------------------- ported assembly tests
DOC_TOMATO = """# Growing tomatoes
Source: https://example.org/garden/tomatoes
How to grow tomatoes in a small garden.
## Soil
Tomatoes need deep, loose soil with `compost` mixed in.
Water the soil every morning.
* **Sun**: full sun for eight hours.
* **Space**: forty centimetres between plants,
more in a wet summer.
## Overview
The Kitchen Garden keeps tomatoes and basil together.
"""
DOC_BASIL = """# Growing basil
Source: https://example.org/garden/basil
## Soil
Basil likes warm soil and the Kitchen Garden.
Plant Sweet Genovese early.
"""
GARDEN_RELEASES = {
"release-v1.2.3.md": "## 1.2.3\n\n- Added the `compost` command to the Kitchen Garden planner.\n",
"release-v1.10.0.md": "## 1.10.0\n\n- The Kitchen Garden planner now shows `compost` levels.\n",
"release-v1.9.2.md": "## 1.9.2\n\n- Basil seedlings get their own tray.\n",
}
FRONTMATTER_KEYS = {"type", "title", "description", "sources", "x-aliases", "x-merge-candidate", "x-main-for",
"generated"}
ENTRY_KEYS = {"id", "resource", "title", "x-locator", "x-quote", "x-span", "x-provenance"}
def record(cid: str, file: str, start: int, end: int, text: str, quote: str, quote_line: int, position: int,
version: str | None = None, provenance: str = "documented", pack: int = 1) -> dict[str, Any]:
return {"pack": pack, "position": position, "file": file, "start": start, "end": end, "section": "Garden",
"text": text, "quote": quote, "quote_line": quote_line, "version": version, "provenance": provenance,
"concept_id": cid, "outcome": "existing"}
def entry(eid: str, title: str, kind: str = "skeleton", merge_of: str | None = None) -> dict[str, Any]:
return {"id": eid, "title": title, "aliases": [title], "kind": kind, "merge_of": merge_of, "origin": None}
def main(source: str, cid: str, by: str = "compiler") -> dict[str, Any]:
return {"source": source, "concept_id": cid, "pack": 1, "by": by}
def home(source: str, cid: str, target: str, by: str = "compiler") -> dict[str, Any]:
return {"source": source, "concept_id": cid, "home": target, "pack": 1, "by": by}
class IndexDescriptionTest(Bakery):
"""SPEC 8: "Entries SHOULD include the description from the linked concept's frontmatter." """
def test_every_entry_carries_its_pages_description(self) -> None:
entries = self.index_entries()
pages = {n: frontmatter(b.decode("utf-8")) for n, b in self.first.items() if n not in ("index.md", "log.md")}
self.assertEqual(len(entries), len(pages))
for name, fm in sorted(pages.items()):
self.assertIn(f"- [{fm['title']}]({name}) - {fm['description']}", entries, name)
self.assert_clean()
def test_brackets_in_a_description_cannot_make_a_link(self) -> None:
page = kassemble.Page("crumb.md", {"title": "Crumb", "description": "See [open crumb](holes.md) here."}, "\n")
self.assertEqual(kassemble.index_text({"crumb.md": page}).split("\n")[-2],
"- [Crumb](crumb.md) - See (open crumb)(holes.md) here.")
class OtherNamesTest(unittest.TestCase):
"""A concept's other names (the catalogue's aliases) stand on its page as `x-aliases` and on its index line; SPEC
4.1 has no key for another name ("alias" stands 0 times in SPEC.md), and 4.1 allows a producer's own keys."""
def test_the_other_names_are_the_aliases_that_are_not_the_title_each_once_whatever_the_case(self) -> None:
self.assertEqual(["Loaf", "`loaves`"],
kassemble.other_names("Loaves", ["Loaves", "Loaf", "loaves", "`loaves`", "LOAF", " "]))
self.assertEqual([], kassemble.other_names("Loaves", None))
def models(self, aliases: list[str]) -> dict[str, kassemble.Page]:
with tempfile.TemporaryDirectory() as tmp:
kilde = Path(tmp)
(kilde / "docs-en-bread.md").write_text("# Bread\n\nA loaf rests before it is cut.\n", encoding="utf-8")
index = {"entries": [dict(entry("loaf", "Loaf"), aliases=aliases)]}
rec = record("loaf", "docs-en-bread.md", 3, 3, "A loaf rests before cutting.", "A loaf rests", 3, 1)
return kassemble.page_models(index, [rec], kilde)
def test_a_page_carries_its_other_names_and_a_page_without_any_has_no_key(self) -> None:
self.assertEqual(["Loaves of bread", "Bread loaf"],
self.models(["Loaf", "Loaves of bread", "Bread loaf"])["loaf.md"].fm["x-aliases"])
self.assertNotIn("x-aliases", self.models(["Loaf", "LOAF"])["loaf.md"].fm)
def test_the_index_line_ends_with_the_other_names_so_a_search_of_the_index_finds_them(self) -> None:
pages = self.models(["Loaf", "Loaves of bread", "Bread [loaf]"])
self.assertEqual("- [Loaf](loaf.md) - A loaf rests before cutting. (also: Loaves of bread; Bread (loaf))",
kassemble.index_text(pages).split("\n")[-2])
def test_the_description_is_the_first_sentence_of_the_pages_own_fragments_not_of_one_merged_in(self) -> None:
with tempfile.TemporaryDirectory() as tmp:
kilde = Path(tmp)
(kilde / "docs-en-bread.md").write_text("# Bread\n\nA loaf rests.\nA loaf has a crust.\n", encoding="utf-8")
index = {"entries": [entry("loaf", "Loaf")]}
moved = dict(record("loaf", "docs-en-bread.md", 3, 3, "A bread loaf rests.", "A loaf rests", 3, 1),
merged_from="bread-loaf")
own = record("loaf", "docs-en-bread.md", 4, 4, "A loaf has a crust.", "A loaf has a crust", 4, 2)
page = kassemble.page_models(index, [moved, own], kilde)["loaf.md"]
self.assertEqual("A loaf has a crust.", page.fm["description"])
self.assertLess(page.body.index("A bread loaf rests."), page.body.index("A loaf has a crust."))
only = kassemble.page_models(index, [moved], kilde)["loaf.md"]
self.assertEqual("A bread loaf rests.", only.fm["description"])
class AssembleTest(unittest.TestCase):
"""The trial's assembly fixture, as records accept would write them: basil is source 1, tomatoes source 2."""
def setUp(self) -> None:
self._tmp = tempfile.TemporaryDirectory()
self.tmp = Path(self._tmp.name)
self.root = self.tmp / "sources"
(self.root / "kilde").mkdir(parents=True)
for name, text in {"docs-en-tomatoes.md": DOC_TOMATO, "docs-en-basil.md": DOC_BASIL,
**GARDEN_RELEASES}.items():
(self.root / "kilde" / name).write_text(text, encoding="utf-8")
self.work = self.tmp / "work"
(self.work / "K-work").mkdir(parents=True)
self.index = {"entries": [entry("soil", "Soil"), entry("pruning", "Pruning"),
entry("kitchen-garden", "Kitchen Garden", "new"),
entry("kitchen-garden-planner", "Kitchen Garden planner", "merge-candidate",
"kitchen-garden")]}
self.records = [
record("soil", "docs-en-tomatoes.md", 8, 9, "Tomatoes need deep, loose soil.", "deep, loose soil", 8, 2),
record("kitchen-garden", "docs-en-tomatoes.md", 17, 17,
"The Kitchen Garden keeps tomatoes and basil together.", "Kitchen Garden", 17, 2,
provenance="merged"),
record("kitchen-garden", "release-v1.2.3.md", 3, 3, "The planner gained a compost command.",
"Kitchen Garden planner", 3, 3, "1.2.3"),
record("soil", "docs-en-basil.md", 6, 7, "Basil likes warm soil near the [Kitchen Garden](kitchen-garden.md).",
"Basil likes warm soil", 6, 1, provenance="inferred"),
record("kitchen-garden", "release-v1.10.0.md", 3, 3, "The planner shows compost levels.",
"shows `compost` levels", 3, 5, "1.10.0"),
record("kitchen-garden-planner", "release-v1.9.2.md", 3, 3, "Seedlings get their own tray.",
"Basil seedlings get their own tray", 3, 4, "1.9.2"),
]
self.main_pages: list[dict[str, Any]] = []
self.homes: list[dict[str, Any]] = []
self.write_store()
self.out = self.tmp / "K"
self.assertEqual(self.build(self.out, "2026-10-02T12:00:00Z"), 0)
def tearDown(self) -> None:
self._tmp.cleanup()
def write_store(self) -> None:
(self.work / "K-work" / "index.json").write_text(json.dumps(self.index), encoding="utf-8")
store: dict[str, Any] = {"fragments": self.records}
if self.main_pages or self.homes:
store.update(main_pages=self.main_pages, homes=self.homes)
(self.work / "K-work" / "accepted.json").write_text(json.dumps(store), encoding="utf-8")
def build(self, out: Path, at: str, *extra: str) -> int:
return run(kassemble, ["build", "--work", str(self.work), "--sources", str(self.root), "--out", str(out),
"--at", at, *extra])
def build_printed(self, out: Path, at: str, *extra: str) -> tuple[int, str]:
printed = io.StringIO()
with redirect_stdout(printed), redirect_stderr(printed):
code = kassemble.main(["build", "--work", str(self.work), "--sources", str(self.root), "--out", str(out),
"--at", at, *extra])
return code, printed.getvalue()
def page(self, name: str, out: Path | None = None) -> audit.Document:
return audit.read_document((out or self.out) / name, name)
def fm(self, name: str, out: Path | None = None) -> dict[str, Any]:
fm = self.page(name, out).frontmatter
assert fm is not None
return fm
def test_the_bundle_passes_the_auditor_and_every_sentence_has_its_quote(self) -> None:
self.assertEqual([f for f in audit.audit(self.out, self.root) if f.check != "link-rule"], [])
self.assertEqual(claims.criterion_1(claims.extract(self.out, self.root))["total"], (6, 6))
def test_the_quote_shown_is_the_whole_line_the_fragments_quote_stands_on(self) -> None:
# wave 4 order 22, correction A (order 20: 203 of 344 unsupported claims quoted a piece of a line and drew on
# the rest of it): the source entry quotes the whole line, trimmed, so the reader sees what the line says
soil = self.fm("soil.md")["sources"]
tomato = next(s for s in soil if s["resource"] == "/kilde/docs-en-tomatoes.md")
self.assertEqual((tomato["x-locator"], tomato["x-quote"]),
({"line": 8}, "Tomatoes need deep, loose soil with `compost` mixed in."))
found = claims.extract(self.out, self.root)
claim = next(c for c in found.claims if c.claim.startswith("Tomatoes need deep"))
self.assertEqual([e.text for e in claim.excerpts], ["Tomatoes need deep, loose soil with `compost` mixed in."])
self.assertEqual(claims.criterion_1(found)["total"], (6, 6))
kg = {s["x-locator"]["line"]: s["x-quote"] for s in self.fm("kitchen-garden.md")["sources"]
if s["resource"] == "/kilde/release-v1.2.3.md"}
self.assertEqual(kg, {1: "1.2.3", 3: "- Added the `compost` command to the Kitchen Garden planner."})
def test_a_context_quote_is_its_own_source_entry_cited_by_the_fragments_sentences(self) -> None:
# wave 4 order 22, correction O+L (order 20: 128 of 344 drew on a heading or a nearby line): the context kpack
# placed becomes a source entry of its own, cited after the fragment's quote, and the claim list shows it to
# the reader; the auditor and the claim list read the page unchanged (K8)
self.records[0]["context"] = [{"line": 6, "quote": "Soil", "section": "Growing tomatoes › Soil"}]
self.write_store()
out = self.tmp / "K2"
self.assertEqual(self.build(out, "2026-10-02T12:00:00Z"), 0)
entries = {(s["resource"], s["x-locator"]["line"]): s for s in self.fm("soil.md", out)["sources"]}
ctx = entries[("/kilde/docs-en-tomatoes.md", 6)]
self.assertEqual((ctx["x-quote"], ctx["title"], ctx["x-provenance"]),
("Soil", "Growing tomatoes › Soil", "documented"))
found = claims.extract(out, self.root)
claim = next(c for c in found.claims if c.page == "soil.md" and c.claim.startswith("Tomatoes need deep"))
self.assertEqual([(e.line, e.text) for e in claim.excerpts],
[(8, "Tomatoes need deep, loose soil with `compost` mixed in."), (6, "Soil")])
self.assertEqual(claims.criterion_1(found)["total"], (6, 6))
self.assertEqual([f for f in audit.audit(out, self.root) if f.check != "link-rule"], [])
def test_only_enriched_concepts_get_pages(self) -> None:
names = {p.name for p in self.out.glob("*.md")} - {"index.md", "log.md"}
self.assertEqual(names, {"soil.md", "kitchen-garden.md", "kitchen-garden-planner.md"})
self.assertEqual(self.fm("kitchen-garden-planner.md")["x-merge-candidate"], "kitchen-garden")
self.assertNotIn("x-merge-candidate", self.fm("soil.md"))
def test_history_in_version_order_without_version_numbers_in_the_text(self) -> None:
doc = self.page("kitchen-garden.md")
self.assertLess(doc.body.index("gained a compost command"), doc.body.index("shows compost levels"))
prose = " ".join(b.text for b in audit.prose_blocks(doc))
self.assertEqual(view.version_numbers(audit.FOOTNOTE_REF.sub("", prose)), [])
versions = [s for s in self.fm("kitchen-garden.md")["sources"] if view.is_version_heading(s)]
self.assertEqual(sorted(s["x-quote"] for s in versions), ["1.10.0", "1.2.3"])
self.assertEqual(sorted(s["id"] for s in versions), ["v1-10-0", "v1-2-3"])
self.assertIn("## History", doc.body)
def test_fragments_stand_in_the_order_of_their_sources_not_of_the_store(self) -> None:
body = self.page("soil.md").body
self.assertLess(body.index("Basil likes warm soil"), body.index("Tomatoes need deep")) # source 1 first
def test_provenance_becomes_x_provenance_on_the_source_entry(self) -> None:
soil = {(s["resource"], s["x-locator"]["line"]): s for s in self.fm("soil.md")["sources"]}
self.assertEqual(soil[("/kilde/docs-en-basil.md", 6)]["x-provenance"], "inferred")
self.assertEqual(soil[("/kilde/docs-en-tomatoes.md", 8)]["x-provenance"], "documented")
self.assertEqual(soil[("/kilde/docs-en-tomatoes.md", 8)]["x-span"], [8, 9])
kg = {s["x-quote"]: s for s in self.fm("kitchen-garden.md")["sources"]}
self.assertEqual(kg["The Kitchen Garden keeps tomatoes and basil together."]["x-provenance"], "merged")
self.assertEqual(kg["1.2.3"]["x-provenance"], "documented") # a version heading states its version
def test_code_adds_only_the_home_links_the_model_chose(self) -> None:
body = self.page("soil.md").body
self.assertIn("near the Kitchen Garden.", body) # the fragment's own link is reduced to its text
self.assertEqual(audit.body_links(self.page("soil.md")), [])
self.assertEqual(sum(len(audit.body_links(self.page(p.name))) for p in self.out.glob("*.md")
if p.name != "index.md"), 0) # no main page and no home: no link at all
self.main_pages = [main("docs-en-basil.md", "soil")]
self.homes = [home("release-v1.9.2.md", "kitchen-garden-planner", "soil"),
home("docs-en-tomatoes.md", "kitchen-garden", "kitchen-garden-planner")] # not a main page
self.write_store()
out = self.tmp / "K-homes"
self.assertEqual(self.build(out, "2026-10-02T12:00:00Z"), 0)
links = {p.name: [t for _, t in audit.body_links(self.page(p.name, out))] for p in out.glob("*.md")
if p.name not in ("index.md", "log.md")}
self.assertEqual(links, {"soil.md": ["kitchen-garden-planner.md"], "kitchen-garden.md": [],
"kitchen-garden-planner.md": []})
def test_links_come_from_a_links_file_and_pass_the_structure_check(self) -> None:
pages = klink.read_pages(self.out)
key = next(s.key for s in klink.body_sentences(pages["soil.md"].body) if "Kitchen Garden" in s.text)
links = self.tmp / "links.json"
result = klink.accept({"links": [{"page": "soil.md", "sentence": key, "anchor": "Kitchen Garden",
"target": "kitchen-garden"}]}, self.out, links, "test")
self.assertEqual(result["accepted"], 1)
linked = self.tmp / "K-linked"
self.assertEqual(self.build(linked, "2026-10-02T12:00:00Z", "--links", str(links)), 0)
self.assertEqual([t for _, t in audit.body_links(self.page("soil.md", linked))], ["kitchen-garden.md"])
found = audit.audit(linked, self.root)
self.assertEqual([f for f in found if f.check in ("link-misplaced", "broken-link", "body-link-bundle-absolute")],
[])
report = audit.link_rule_report(audit.load_bundle(linked, self.root))
self.assertEqual((report["pass"], report["misplaced"], report["broken"]), (1, 0, 0))
def test_a_link_record_whose_sentence_is_gone_is_stale_and_exits_1(self) -> None:
links = self.tmp / "links.json"
links.write_text(json.dumps({"links": [{"page": "soil.md", "sentence": "0" * 16 + "-0", "anchor": "soil",
"at": 0, "target": "kitchen-garden"}]}), encoding="utf-8")
self.assertEqual(self.build(self.out, "2026-10-03T12:00:00Z", "--replace", "--links", str(links)), 1)
self.assertEqual(audit.body_links(self.page("soil.md")), [])
def test_an_existing_output_is_refused_without_replace_and_swapped_with_it(self) -> None:
before = {p.name: p.read_bytes() for p in self.out.iterdir()}
self.assertEqual(self.build(self.out, "2026-10-03T12:00:00Z"), 2)
self.assertEqual({p.name: p.read_bytes() for p in self.out.iterdir()}, before)
self.records.pop(0)
self.write_store()
self.assertEqual(self.build(self.out, "2026-10-03T12:00:00Z", "--replace"), 0)
self.assertNotIn("Tomatoes need deep", (self.out / "soil.md").read_text(encoding="utf-8"))
self.assertEqual([p.name for p in self.tmp.iterdir() if p.name.startswith(".")], []) # no staging left
def test_replace_refuses_a_folder_that_holds_what_assembly_did_not_write(self) -> None:
(self.out / "notes.txt").write_text("mine\n", encoding="utf-8")
self.assertEqual(self.build(self.out, "2026-10-03T12:00:00Z", "--replace"), 2)
self.assertTrue((self.out / "notes.txt").is_file())
def test_a_pending_marker_in_the_work_folder_stops_the_build(self) -> None:
(self.work / "K-work" / "accept-2.pending").write_text("{}\n", encoding="utf-8")
self.assertEqual(self.build(self.tmp / "K2", "2026-10-03T12:00:00Z"), 2)
self.assertFalse((self.tmp / "K2").exists())
def test_inputs_that_cannot_build_exit_2(self) -> None:
self.assertEqual(self.build(self.tmp / "K2", "yesterday"), 2)
self.records.append(record("mulch", "docs-en-basil.md", 6, 6, "Basil likes mulch.", "Basil", 6, 1))
self.write_store()
self.assertEqual(self.build(self.tmp / "K2", "2026-10-03T12:00:00Z"), 2) # a concept not in the index
self.assertFalse((self.tmp / "K2").exists())
def test_format_choices_a_to_h_hold_on_every_page(self) -> None:
for p in sorted(self.out.glob("*.md")):
if p.name in ("index.md", "log.md"):
continue
fm = self.fm(p.name)
with self.subTest(page=p.name):
self.assertTrue(set(fm) <= FRONTMATTER_KEYS, set(fm) - FRONTMATTER_KEYS) # (e) no verified, (h)
ids = [s["id"] for s in fm["sources"]]
self.assertEqual(len(ids), len(set(ids))) # (f)
labels = set(audit.FOOTNOTE_REF.findall(self.page(p.name).body))
self.assertEqual(labels, set(ids)) # (f) every entry is cited and every label has an entry
for s in fm["sources"]:
self.assertTrue(set(s) <= ENTRY_KEYS, s)
self.assertTrue(s["resource"].startswith("/kilde/"), s) # (a)
self.assertEqual(set(s["x-locator"]), {"line"}) # (g)
self.assertIsInstance(s["x-quote"], str) # (c) and (g): a quote like 1.10.0 stays a string
self.assertEqual(fm["generated"], {"by": kassemble.GENERATOR, "at": "2026-10-02T12:00:00Z"}) # (c)(d)
text = kassemble.frontmatter({"type": "Concept", "sources": [{"id": "a", "x-quote": "no"},
{"id": "b", "x-quote": "1.10"}]})
self.assertEqual([s["x-quote"] for s in frontmatter(text)["sources"]], ["no", "1.10"]) # (c)
def test_a_footnote_label_is_keyed_by_its_fragment_not_by_its_place(self) -> None:
labels = {s["resource"]: s["id"] for s in self.fm("soil.md")["sources"]}
self.records.pop(3) # basil's fragment, first on the soil page
self.write_store()
self.assertEqual(self.build(self.tmp / "K2", "2026-10-02T12:00:00Z"), 0)
after = {s["resource"]: s["id"] for s in self.fm("soil.md", self.tmp / "K2")["sources"]}
self.assertEqual(after["/kilde/docs-en-tomatoes.md"], labels["/kilde/docs-en-tomatoes.md"])
def test_two_builds_of_the_same_store_are_byte_identical(self) -> None:
self.assertEqual(self.build(self.tmp / "K2", "2026-10-02T12:00:00Z"), 0)
self.assertEqual({p.name: p.read_bytes() for p in self.out.iterdir()},
{p.name: p.read_bytes() for p in (self.tmp / "K2").iterdir()})
def test_a_rebuild_without_change_keeps_every_page_and_adds_one_log_entry_under_its_day(self) -> None:
before = {p.name: p.read_bytes() for p in self.out.iterdir()}
self.assertEqual(self.build(self.out, "2026-10-02T15:00:00Z", "--replace"), 0)
after = {p.name: p.read_bytes() for p in self.out.iterdir()}
self.assertEqual({n: b for n, b in after.items() if n != "log.md"},
{n: b for n, b in before.items() if n != "log.md"})
log = after["log.md"].decode("utf-8").split("\n")
self.assertEqual([x for x in log if x.startswith("## ")], ["## 2026-10-02"])
entries = [x for x in log if x.startswith("* ")]
self.assertEqual(len(entries), 2)
self.assertIn("unchanged 3", entries[0]) # newest first
self.assertEqual([f for f in audit.audit(self.out, self.root) if f.check.startswith("spec11")], [])
# --- main pages and homes (wave 2, order 10) ------------------------------------------------------------------
def test_x_main_for_is_written_sorted_and_once_on_the_named_main_pages_only(self) -> None:
self.main_pages = [main("docs-en-tomatoes.md", "soil"), main("docs-en-basil.md", "soil"),
main("docs-en-basil.md", "soil", by="guard")]
self.write_store()
out = self.tmp / "K-main"
self.assertEqual(self.build(out, "2026-10-02T12:00:00Z"), 0)
self.assertEqual(self.fm("soil.md", out)["x-main-for"], ["/kilde/docs-en-basil.md", "/kilde/docs-en-tomatoes.md"])
self.assertNotIn("x-main-for", self.fm("kitchen-garden.md", out)) # not a main page: the key is left out
self.assertEqual([f for f in audit.audit(out, self.root) if f.check != "link-rule"], [])
def test_a_main_page_record_is_written_only_for_a_docs_source_the_page_cites(self) -> None:
self.main_pages = [main("docs-en-basil.md", "kitchen-garden"), # kitchen-garden does not cite basil
main("release-v1.2.3.md", "kitchen-garden")] # a release note has no main page
self.write_store()
out = self.tmp / "K-main"
self.assertEqual(self.build(out, "2026-10-02T12:00:00Z"), 0)
self.assertNotIn("x-main-for", self.fm("kitchen-garden.md", out))
def test_a_main_page_lists_its_homes_as_related_concepts_and_they_are_not_claims(self) -> None:
self.main_pages = [main("docs-en-basil.md", "soil")]
self.homes = [home("docs-en-tomatoes.md", "kitchen-garden", "soil"),
home("release-v1.9.2.md", "kitchen-garden-planner", "soil")]
self.write_store()
out = self.tmp / "K-home"
self.assertEqual(self.build(out, "2026-10-02T12:00:00Z"), 0)
body = self.page("soil.md", out).body
related = body.split("## Related concepts\n\n", 1)[1].split("\n\n", 1)[0]
self.assertEqual(related, "- [Kitchen Garden](kitchen-garden.md)\n- [Kitchen Garden planner](kitchen-garden-planner.md)")
self.assertLess(body.index("## Related concepts"), body.index("\n[^")) # before the footnote definitions
self.assertEqual([f for f in audit.audit(out, self.root) if f.check != "link-rule"], [])
self.assertEqual(claims.criterion_1(claims.extract(out, self.root))["total"], (6, 6)) # a link list is no claim
report = audit.link_rule_report(audit.load_bundle(out, self.root))
self.assertEqual((report["misplaced"], report["broken"]), (0, 0))
def test_a_home_on_a_page_that_is_no_main_page_or_on_itself_places_no_link(self) -> None:
self.homes = [home("docs-en-tomatoes.md", "kitchen-garden", "soil")] # soil is not a main page here
self.main_pages = [main("docs-en-tomatoes.md", "kitchen-garden")]
self.homes.append(home("docs-en-tomatoes.md", "kitchen-garden", "kitchen-garden"))
self.write_store()
out = self.tmp / "K-home"
self.assertEqual(self.build(out, "2026-10-02T12:00:00Z"), 0)
for name in ("soil.md", "kitchen-garden.md"):
self.assertEqual(audit.body_links(self.page(name, out)), [], name)
def test_a_store_with_a_bad_main_page_or_home_record_cannot_run(self) -> None:
for field in ("main_pages", "homes"):
with self.subTest(field=field):
self.main_pages = [{"source": "docs-en-basil.md"}] if field == "main_pages" else []
self.homes = [{"concept_id": "soil", "home": 3}] if field == "homes" else []
self.write_store()
self.assertEqual(self.build(self.tmp / f"K-{field}", "2026-10-02T12:00:00Z"), 2)
# --- found by the independent read of the branch ------------------------------------------------------------
def snapshot(self, out: Path | None = None) -> dict[str, bytes]:
return {p.name: p.read_bytes() for p in sorted((out or self.out).iterdir())}
def test_a_swap_that_fails_puts_the_old_output_back(self) -> None:
before = self.snapshot()
real = Path.rename
def rename(path: Path, target: Path) -> Path:
if path.name == "final":
raise OSError("the new output could not be moved in")
return real(path, target)
self.records.pop(0)
self.write_store()
with mock.patch.object(Path, "rename", autospec=True, side_effect=rename):
self.assertEqual(self.build(self.out, "2026-10-03T12:00:00Z", "--replace"), 2)
self.assertEqual(self.snapshot(), before)
self.assertEqual([p.name for p in self.tmp.iterdir() if p.name.startswith(".")], [])
def test_replace_refuses_a_markdown_file_assembly_did_not_write(self) -> None:
(self.out / "notes.md").write_text("# My notes\n\nKeep these.\n", encoding="utf-8")
self.assertEqual(self.build(self.out, "2026-10-03T12:00:00Z", "--replace"), 2)
self.assertTrue((self.out / "notes.md").is_file())
def test_a_finder_ds_store_file_does_not_block_replace(self) -> None:
(self.out / ".DS_Store").write_bytes(b"\x00\x01")
self.assertEqual(self.build(self.out, "2026-10-03T12:00:00Z", "--replace"), 0)
def test_a_link_to_a_page_that_is_gone_is_dropped_and_the_page_that_held_it_is_listed(self) -> None:
pages = klink.read_pages(self.out)
key = next(s.key for s in klink.body_sentences(pages["soil.md"].body) if "Kitchen Garden" in s.text)
links = self.tmp / "links.json"
klink.accept({"links": [{"page": "soil.md", "sentence": key, "anchor": "Kitchen Garden",
"target": "kitchen-garden-planner"}]}, self.out, links, "test")
self.assertEqual(self.build(self.out, "2026-10-03T12:00:00Z", "--replace", "--links", str(links)), 0)
self.assertEqual([t for _, t in audit.body_links(self.page("soil.md"))], ["kitchen-garden-planner.md"])
self.records.pop(5) # the planner's only fragment: its page goes
self.write_store()
code, printed = self.build_printed(self.out, "2026-10-04T12:00:00Z", "--replace", "--links", str(links))
self.assertEqual(code, 0, printed) # dropped by design (order 10), not stale
self.assertIn("dropped links to pages that are gone: 1 (soil.md)", printed)
self.assertIn("stale 0", printed)
self.assertEqual(audit.body_links(self.page("soil.md")), [])
self.assertEqual([f for f in audit.audit(self.out, self.root) if f.check == "broken-link"], [])
# the record into the gone page is taken out of the links file, so no later step places it again
self.assertEqual(json.loads(links.read_text(encoding="utf-8"))["links"], [])
self.assertEqual(json.loads(links.read_text(encoding="utf-8"))["accepted"], 0) # the count follows
self.assertIn("removed from the links file: 1", printed)
code, printed = self.build_printed(self.out, "2026-10-05T12:00:00Z", "--replace", "--links", str(links))
self.assertEqual(code, 0, printed)
self.assertNotIn("dropped links", printed)
self.assertIn("new 0, changed 0", printed)
def planner_link(self) -> Path:
"""A links file with one record on the planner's page, into soil; the planner's page goes when record 5 does."""
s = klink.body_sentences(klink.read_pages(self.out)["kitchen-garden-planner.md"].body)[0]
word = s.text.split()[0]
links = self.tmp / "links.json"
links.write_text(klink.dump({"schema": klink.SCHEMA, "links": [
{"page": "kitchen-garden-planner.md", "sentence": s.key, "anchor": word, "at": 0, "target": "soil.md"}],
"none": [], "none_count": 0, "accepted": 1, "rejected": {}}), encoding="utf-8")
self.assertEqual(self.build(self.out, "2026-10-03T12:00:00Z", "--replace", "--links", str(links)), 0)
return links
def test_a_link_record_on_a_page_that_is_gone_leaves_the_links_file_and_is_not_stale(self) -> None:
links = self.planner_link()
self.records.pop(5) # the planner's only fragment: the page that held the record goes
self.write_store()
code, printed = self.build_printed(self.out, "2026-10-04T12:00:00Z", "--replace", "--links", str(links))
self.assertEqual(code, 0, printed)
self.assertIn("stale 0", printed)
self.assertIn("removed from the links file: 1", printed)
self.assertEqual(json.loads(links.read_text(encoding="utf-8"))["links"], [])
def test_a_build_that_fails_keeps_every_record_of_the_links_file(self) -> None:
links = self.planner_link()
before = links.read_bytes()
self.records.pop(5)
self.write_store()
with mock.patch.object(kassemble, "swap_in", side_effect=OSError("disk full")):
self.assertEqual(self.build(self.out, "2026-10-04T12:00:00Z", "--replace", "--links", str(links)), 2)
self.assertEqual(links.read_bytes(), before)
def test_a_related_link_to_a_page_that_is_gone_is_dropped_and_its_main_page_is_listed(self) -> None:
self.main_pages = [main("docs-en-basil.md", "soil")]
self.homes = [home("release-v1.9.2.md", "kitchen-garden-planner", "soil")]
self.write_store()
self.assertEqual(self.build(self.out, "2026-10-03T12:00:00Z", "--replace"), 0)
self.records.pop(5) # the planner's only fragment: its page goes, and with it the related link on soil
self.write_store()
code, printed = self.build_printed(self.out, "2026-10-04T12:00:00Z", "--replace")
self.assertEqual(code, 0, printed)
self.assertIn("dropped links to pages that are gone: 1 (soil.md)", printed)
self.assertNotIn("## Related concepts", self.page("soil.md").body)
def test_a_links_file_with_a_bad_record_cannot_run(self) -> None:
links = self.tmp / "links.json"
links.write_text(json.dumps({"links": [{"page": "soil.md", "sentence": "x-0", "anchor": "soil", "at": "zero",
"target": "kitchen-garden.md"}]}), encoding="utf-8")
self.assertEqual(self.build(self.tmp / "K2", "2026-10-03T12:00:00Z", "--links", str(links)), 2)
self.assertFalse((self.tmp / "K2").exists())
def test_an_index_entry_without_a_title_cannot_run(self) -> None:
del self.index["entries"][0]["title"]
self.write_store()
self.assertEqual(self.build(self.tmp / "K2", "2026-10-03T12:00:00Z"), 2)
def test_an_external_link_in_a_fragment_is_reduced_to_its_text_too(self) -> None:
self.records[0]["text"] = "Tomatoes need deep, loose soil, as [the guide](https://example.org/guide) says."
self.write_store()
self.assertEqual(self.build(self.tmp / "K2", "2026-10-03T12:00:00Z"), 0)
body = self.page("soil.md", self.tmp / "K2").body
self.assertIn("as the guide says.", body)
self.assertNotIn("](", body)
def test_the_build_time_is_written_in_utc(self) -> None:
self.assertEqual(self.build(self.tmp / "K2", "2026-10-03T01:00:00+02:00"), 0)
self.assertEqual(self.fm("soil.md", self.tmp / "K2")["generated"]["at"], "2026-10-02T23:00:00Z")
self.assertIn("## 2026-10-02", (self.tmp / "K2" / "log.md").read_text(encoding="utf-8"))
def test_a_build_older_than_the_log_cannot_run(self) -> None:
self.assertEqual(self.build(self.out, "2026-10-01T12:00:00Z", "--replace"), 2)
class ComponentReleaseTest(unittest.TestCase):
"""Order 27 A6: the release notes of the copy of 08.10 are each one component, <Update label="X.Y.Z" ...>, with
no heading (416 of 416). A fragment from one goes under ## History with its version as the label, quoted where the
version stands: in the label on line 1."""
NOTE = '<Update label="1.2.3" description="May 2026">\n * Added the `compost` command to the planner.\n</Update>\n'
def setUp(self) -> None:
self._tmp = tempfile.TemporaryDirectory()
self.tmp = Path(self._tmp.name)
staging = self.tmp / "staging"
staging.mkdir()
(staging / "docs-en-tomatoes.md").write_text(DOC_TOMATO, encoding="utf-8")
(staging / "release-v1.2.3.md").write_text(self.NOTE, encoding="utf-8")
meta: dict[str, Any] = {"collection": "garden", "schema": "okf-wiki/source-meta/1", "sources": {
"docs-en-tomatoes.md": {"kind": "docs", "main_topic": True, "url": "https://example.org/t"},
"release-v1.2.3.md": {"kind": "release-notes", "main_topic": False, "url": "https://example.org/r",
"version": "1.2.3"}}}
(self.tmp / "meta.json").write_text(json.dumps(meta), encoding="utf-8")
self.root = self.tmp / "sources"
self.assertEqual(run(sources, ["freeze", str(staging), "--meta", str(self.tmp / "meta.json"), "--out",
str(self.root), "--frozen-at", "2026-10-08T06:00:00Z"]), 0)
self.work = self.tmp / "work"
(self.work / "K-work").mkdir(parents=True)
records = [
record("soil", "docs-en-tomatoes.md", 8, 9, "Tomatoes need deep, loose soil.", "deep, loose soil", 8, 1),
record("soil", "release-v1.2.3.md", 2, 2, "The planner has a compost command.", "the `compost` command", 2,
2, "1.2.3", pack=2),
]
(self.work / "K-work" / "index.json").write_text(json.dumps({"entries": [entry("soil", "Soil")]}),
encoding="utf-8")
store = {"fragments": records, "main_pages": [main("docs-en-tomatoes.md", "soil")]}
(self.work / "K-work" / "accepted.json").write_text(json.dumps(store), encoding="utf-8")
self.out = self.tmp / "K"
def tearDown(self) -> None:
self._tmp.cleanup()
def test_the_version_label_quotes_the_version_where_the_label_holds_it(self) -> None:
self.assertEqual(run(kassemble, ["build", "--work", str(self.work), "--sources", str(self.root), "--out",
str(self.out), "--at", "2026-10-02T12:00:00Z"]), 0)
doc = audit.read_document(self.out / "soil.md", "soil.md")
assert doc.frontmatter is not None
label = [s for s in doc.frontmatter["sources"] if s["id"] == "v1-2-3"]
self.assertEqual([(s["x-locator"], s["x-quote"], s["title"]) for s in label], [({"line": 1}, "1.2.3", "1.2.3")])
self.assertIn("compost command", doc.body.split("## History", 1)[1])
self.assertEqual(audit.audit(self.out, self.root), [])
class WeeklyHistoryTest(unittest.TestCase):
"""K1 marks the weekly What's New pages as history (rule 4, 08.10): their fragments go under ## History with the
week from the file name as their label, as a release note's go with their version."""
WEEKLY = "docs-en-whats-new-2026-w14.md"
def setUp(self) -> None:
self._tmp = tempfile.TemporaryDirectory()
self.tmp = Path(self._tmp.name)
staging = self.tmp / "staging"
staging.mkdir()
files = {"docs-en-tomatoes.md": DOC_TOMATO, self.WEEKLY: "# Week 14 · Garden notes\n\n- Tomatoes now get a "
"trellis.\n", "release-v1.2.3.md": GARDEN_RELEASES["release-v1.2.3.md"]}
meta: dict[str, Any] = {"collection": "garden", "schema": "okf-wiki/source-meta/1", "sources": {
"docs-en-tomatoes.md": {"kind": "docs", "main_topic": True, "url": "https://example.org/t"},
self.WEEKLY: {"kind": "docs", "main_topic": False, "url": "https://example.org/w14"},
"release-v1.2.3.md": {"kind": "release-notes", "main_topic": False, "url": "https://example.org/r",
"version": "1.2.3"}}}
for name, text in files.items():
(staging / name).write_text(text, encoding="utf-8")
(self.tmp / "meta.json").write_text(json.dumps(meta), encoding="utf-8")
self.root = self.tmp / "sources"
self.assertEqual(run(sources, ["freeze", str(staging), "--meta", str(self.tmp / "meta.json"), "--out",
str(self.root), "--frozen-at", "2026-10-08T06:00:00Z"]), 0)
self.work = self.tmp / "work"
(self.work / "K-work").mkdir(parents=True)
index = {"entries": [entry("soil", "Soil")]}
records = [
record("soil", "docs-en-tomatoes.md", 8, 9, "Tomatoes need deep, loose soil.", "deep, loose soil", 8, 1),
record("soil", self.WEEKLY, 3, 3, "Tomatoes get a trellis.", "Tomatoes now get a trellis", 3, 2, pack=2),
record("soil", "release-v1.2.3.md", 3, 3, "The planner has a compost command.", "the `compost` command", 3,
3, "1.2.3", pack=2),
]
(self.work / "K-work" / "index.json").write_text(json.dumps(index), encoding="utf-8")
# The root has K1, so the auditor checks the main-page rule (K2): the one main-topic source needs its main page.
store = {"fragments": records, "main_pages": [main("docs-en-tomatoes.md", "soil")]}
(self.work / "K-work" / "accepted.json").write_text(json.dumps(store), encoding="utf-8")
self.out = self.tmp / "K"
self.assertEqual(run(kassemble, ["build", "--work", str(self.work), "--sources", str(self.root), "--out",
str(self.out), "--at", "2026-10-02T12:00:00Z"]), 0)
def tearDown(self) -> None:
self._tmp.cleanup()
def test_a_weekly_page_goes_under_history_with_its_week_as_label(self) -> None:
doc = audit.read_document(self.out / "soil.md", "soil.md")
body, history = doc.body.split("## History", 1)
self.assertIn("Tomatoes need deep, loose soil.", body)
self.assertNotIn("trellis", body)
self.assertLess(history.index("compost command"), history.index("trellis")) # versions first, then weeks
assert doc.frontmatter is not None
week = [s for s in doc.frontmatter["sources"] if s["title"] == "2026-w14"]
self.assertEqual(len(week), 1)
self.assertEqual((week[0]["x-locator"], week[0]["x-quote"]), ({"line": 1}, "Week 14 · Garden notes"))
self.assertIn(f"[^{week[0]['id']}]", history)
self.assertEqual(audit.audit(self.out, self.root), [])
prose = " ".join(b.text for b in audit.prose_blocks(doc) if "trellis" in b.text)
self.assertNotIn("2026", audit.FOOTNOTE_REF.sub("", prose)) # the label is a footnote, not running text
class CleanTest(unittest.TestCase):
def test_a_bracket_in_code_survives_the_link_strip(self) -> None:
# A [ inside a code span opens no link (CommonMark 6.1).
self.assertEqual("Press `[` to mark a row, or see the shed.",
kassemble.clean("Press `[` to mark a row, or see [the shed](shed.md)."))
if __name__ == "__main__":
unittest.main()