okf-wiki/tests/test_kassemble.py
Kjell Tore Guttormsen 0fd86a23a3
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>
2026-11-14 21:03:20 +01:00

972 lines
56 KiB
Python
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

"""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()