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>
972 lines
56 KiB
Python
972 lines
56 KiB
Python
"""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()
|