"""Tests for okfwiki/kblocks.py: the fixed order of the sources and their blocks with line spans. No model call. Ported from the trial's tests (evals/tests/test_p1_build.py, OrderTest, BlocksTest, DocsHeadingsTest, CliTest), plus the rule for lines that are only an HTML or MDX tag (brief rev 2.2 SC6(i)): such a line never starts a block, so a block is never only a tag. The fixtures are synthetic text about gardening (CLAUDE.md rule 3). Run: python3 -m unittest discover -s tests -p 'test_kblocks.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 ROOT = Path(__file__).resolve().parents[1] sys.path.insert(0, str(ROOT)) from okfwiki import common, kblocks # noqa: E402 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. ```bash # not a heading mix compost ``` | Month | Task | |---|---| | May | plant | ## Overview The Kitchen Garden keeps tomatoes and basil together. ### Pruning Remove side shoots once a week. """ DOC_BASIL = """# Growing basil Source: https://example.org/garden/basil ## Soil Basil likes warm soil and the Kitchen Garden. Plant Sweet Genovese early. ## Watering Water basil with `compost` tea when the leaves droop. """ DOC_MULCH = """# Mulch Mulch keeps the soil moist in summer. Spread it after rain. Use straw or bark. Rake the bed. """ REL_1 = """## 1.2.3 - Added the `compost` command to the Kitchen Garden planner. - Fixed watering reminders. """ REL_2 = """## 1.10.0 - The Kitchen Garden planner now shows `compost` levels. """ REL_3 = """## 1.9.2 - Basil seedlings get their own tray. """ DOC_SHED = """# Garden shed export const ShedPlan = () => { const parts = [ { name: 'Bed notes', example: `# Bed notes ## Planting - Sow \\`peas\\` in March ## Harvest - Pick beans daily`, }, { name: 'Tool list', example: `--- name: tools --- # Tools to keep`, }, ]; return ; }; ## Shelves Keep seed packets on the top shelf. * **Windows**: open `C:\\beds\\` in the planner. ### Hooks Hang the rake on the left hook. """ FILES = {"docs-en-tomatoes.md": DOC_TOMATO, "docs-en-basil.md": DOC_BASIL, "docs-en-mulch.md": DOC_MULCH, "release-v1.2.3.md": REL_1, "release-v1.10.0.md": REL_2, "release-v1.9.2.md": REL_3} class Fixture(unittest.TestCase): def setUp(self) -> None: self._tmp = tempfile.TemporaryDirectory() self.tmp = Path(self._tmp.name) self.root = self.tmp / "sources" self.kilde = self.root / "kilde" self.kilde.mkdir(parents=True) for name, text in FILES.items(): (self.kilde / name).write_text(text, encoding="utf-8") def tearDown(self) -> None: self._tmp.cleanup() def cli(self, args: list[str]) -> int: with redirect_stdout(io.StringIO()), redirect_stderr(io.StringIO()): return kblocks.main(args) class OrderTest(unittest.TestCase): def test_docs_first_then_release_notes_by_version_tuple(self) -> None: names = ["release-v0.2.34.md", "docs-en-b.md", "release-v0.2.9.md", "docs-en-a.md", "release-v1.0.0.md"] self.assertEqual(kblocks.order(names), ["docs-en-a.md", "docs-en-b.md", "release-v0.2.9.md", "release-v0.2.34.md", "release-v1.0.0.md"]) def test_any_other_name_is_a_page_in_name_order_before_the_release_notes(self) -> None: # motor step 2 (A5): a folder's own file names; only release-vX.Y.Z.md is a release note by name names = ["release-v1.0.0.md", "notat.txt", "moetereferat.md", "docs-en-a.md", "release-notes.md"] self.assertEqual(kblocks.order(names), ["docs-en-a.md", "moetereferat.md", "notat.txt", "release-notes.md", "release-v1.0.0.md"]) def test_a_page_named_release_without_a_version_has_no_version(self) -> None: with tempfile.TemporaryDirectory() as tmp: path = Path(tmp) / "release-plan.md" path.write_text("# Plan\n\n1.2.3 is a number here.\n", encoding="utf-8") self.assertEqual({b.version for b in kblocks.blocks(path)}, {None}) class BlocksTest(Fixture): def test_fence_aware_blocks_with_spans(self) -> None: got = kblocks.blocks(self.kilde / "docs-en-tomatoes.md") kinds = [(b.kind, b.start, b.end) for b in got] # line 2 "Source:" and line 4 are paragraphs; headings are not blocks self.assertIn(("paragraph", 2, 2), kinds) self.assertIn(("paragraph", 8, 9), kinds) self.assertIn(("item", 11, 11), kinds) self.assertIn(("item", 12, 13), kinds) # a continuation line belongs to its item self.assertIn(("code", 15, 18), kinds) # the "#" inside the fence is not a heading self.assertIn(("table", 20, 22), kinds) heads = {b.section for b in got} self.assertIn("Growing tomatoes › Soil", heads) self.assertIn("Growing tomatoes › Overview › Pruning", heads) self.assertNotIn("not a heading", " ".join(heads)) def test_every_non_blank_non_heading_line_is_in_exactly_one_block(self) -> None: path = self.kilde / "docs-en-tomatoes.md" lines = path.read_text(encoding="utf-8").split("\n") covered: dict[int, int] = {} for b in kblocks.blocks(path): for n in range(b.start, b.end + 1): covered[n] = covered.get(n, 0) + 1 for n, raw in enumerate(lines, 1): heading = raw.startswith("#") and not (15 <= n <= 18) if raw.strip() and not heading: self.assertEqual(covered.get(n), 1, (n, raw)) if heading: self.assertNotIn(n, covered, (n, raw)) def test_release_note_blocks_carry_the_version(self) -> None: self.assertEqual({b.version for b in kblocks.blocks(self.kilde / "release-v1.10.0.md")}, {"1.10.0"}) self.assertIsNone(kblocks.blocks(self.kilde / "docs-en-basil.md")[0].version) def test_a_release_note_in_component_form_carries_the_version_of_its_label(self) -> None: # order 27 A6: every release note of the copy of 08.10 is one component, , with no # heading; measured 416 of 416, each with its version in the label on line 1 path = self.kilde / "release-v1.4.0.md" path.write_text(COMPONENT_NOTE, encoding="utf-8") found = kblocks.blocks(path) self.assertEqual([(b.start, b.end, b.version) for b in found], [(2, 2, "1.4.0"), (3, 5, "1.4.0")]) self.assertEqual(kblocks.version_line(COMPONENT_NOTE.split("\n"), "1.4.0"), 1) self.assertIsNone(kblocks.version_line(COMPONENT_NOTE.split("\n"), "1.5.0")) def test_a_release_note_in_bold_form_carries_the_version_of_its_bold_line(self) -> None: # the release-note page changed shape after 20.10: each release is a line that is only the bold version, # a blank line and the date (measured 437 of 437 on 07.11), no component and no heading path = self.kilde / "release-v1.4.0.md" path.write_text(BOLD_NOTE, encoding="utf-8") self.assertEqual({b.version for b in kblocks.blocks(path)}, {"1.4.0"}) self.assertEqual(kblocks.version_line(BOLD_NOTE.split("\n"), "1.4.0"), 1) self.assertIsNone(kblocks.version_line(BOLD_NOTE.split("\n"), "1.5.0")) self.assertIsNone(kblocks.version_line(["**Added**", "**1.4.0 notes**"], "1.4.0")) class NestedFenceTest(Fixture): """The auditor's fence rule (CommonMark 4.5): a fence closes only on a run of its own character at least as long, with nothing after it, so a ```bash block inside a ````markdown block stays code (review finding #29).""" NESTED = "# Setup\n\n````markdown\n```bash\n# Install the tools\nnpm install\n```\n````\n\nAfter the block.\n" def path(self) -> Path: p = self.kilde / "docs-en-setup.md" p.write_text(self.NESTED, encoding="utf-8") return p def test_a_comment_in_a_nested_block_is_no_heading(self) -> None: self.assertEqual([(1, 1, "Setup")], kblocks.headings_of(self.NESTED.split("\n"))) self.assertNotIn("Install the tools", [h.text for h in kblocks.docs_headings(self.path().parent)]) def test_the_outer_block_is_one_code_block_and_the_section_is_kept(self) -> None: got = kblocks.blocks(self.path()) self.assertEqual([("code", 3, 8, "Setup"), ("paragraph", 10, 10, "Setup")], [(b.kind, b.start, b.end, b.section) for b in got]) def test_a_tilde_fence_is_not_closed_by_backticks(self) -> None: lines = ["~~~", "```", "# not a heading", "~~~", "# Real"] self.assertEqual([(5, 1, "Real")], kblocks.headings_of(lines)) class TagOnlyTest(Fixture): def test_a_line_that_is_only_a_tag_never_starts_a_block(self) -> None: got = [(b.kind, b.start, b.end) for b in kblocks.blocks(self.kilde / "docs-en-mulch.md")] # (3), (7), (11), and (15, 16) start nothing; a tag inside a paragraph # that has started stays in it (5, 18, 19); a paragraph holding is a block (13), and so is a line that is # only a link in angle brackets (21): content, not a tag self.assertEqual(got, [("paragraph", 4, 5), ("paragraph", 9, 9), ("paragraph", 13, 13), ("paragraph", 17, 19), ("paragraph", 21, 21)]) def test_no_block_is_only_tags(self) -> None: for path in sorted(self.kilde.glob("*.md")): lines = path.read_text(encoding="utf-8").split("\n") for b in kblocks.blocks(path): span = lines[b.start - 1:b.end] self.assertFalse(all(common.HTML_TAG_ONLY.match(x) for x in span), (path.name, b)) def test_the_tag_pattern(self) -> None: for line in ("", "", " ", '', "
", ""): self.assertIsNotNone(common.HTML_TAG_ONLY.match(line), line) for line in ("Use straw or bark.", "bold", "a < b > c", "Keep it moist.", "", "", ""): self.assertIsNone(common.HTML_TAG_ONLY.match(line), line) class DocsHeadingsTest(Fixture): def test_titles_and_second_and_third_level_headings_of_docs_pages_only(self) -> None: texts = [(h.file, h.level, h.text) for h in kblocks.docs_headings(self.kilde)] self.assertIn(("docs-en-tomatoes.md", 1, "Growing tomatoes"), texts) self.assertIn(("docs-en-tomatoes.md", 3, "Pruning"), texts) self.assertFalse(any(f.startswith("release-") for f, _, _ in texts)) self.assertFalse(any(t == "not a heading" for _, _, t in texts)) def test_lines_in_an_example_string_of_a_component_are_not_headings(self) -> None: # wave 4 order 22 (the skeleton; order 14 findings C and D): a component property whose value is a backtick # string that does not close on its line holds example text up to the line with the closing backtick; a "#" # line in it is no heading, neither for the skeleton nor for a block's section. A backtick escaped with a # backslash does not close it; inline code that ends in a backslash and a style block are no such string. path = self.tmp / "docs-en-shed.md" path.write_text(DOC_SHED, encoding="utf-8") lines = DOC_SHED.split("\n") got = [(level, text) for _, level, text in kblocks.headings_of(lines)] self.assertEqual(got, [(1, "Garden shed"), (2, "Shelves"), (3, "Hooks")]) sections = {b.section for b in kblocks.blocks(path)} self.assertEqual(sections, {"Garden shed", "Garden shed › Shelves", "Garden shed › Shelves › Hooks"}) self.assertFalse(any("Planting" in s or "Tools to keep" in s for s in sections)) def test_headings_of_a_page_with_any_name_are_read(self) -> None: (self.kilde / "notat.txt").write_text("# Kompost\n\nLag i lag.\n", encoding="utf-8") texts = [(h.file, h.text) for h in kblocks.docs_headings(self.kilde)] self.assertIn(("notat.txt", "Kompost"), texts) self.assertFalse(any(f.startswith("release-v") for f, _ in texts)) def test_meta_headings_fail_concept_test_2(self) -> None: self.assertTrue(kblocks.is_meta(" Overview ")) self.assertFalse(kblocks.is_meta("Pruning")) class CliTest(Fixture): def test_order_blocks_and_total(self) -> None: order = self.tmp / "order.txt" self.assertEqual(self.cli(["order", str(self.root), "--out", str(order)]), 0) names = order.read_text(encoding="utf-8").split() self.assertEqual(names, ["docs-en-basil.md", "docs-en-mulch.md", "docs-en-tomatoes.md", "release-v1.2.3.md", "release-v1.9.2.md", "release-v1.10.0.md"]) self.assertEqual(self.cli(["order", str(self.root), "--out", str(order)]), 2) # never overwritten out = self.tmp / "blocks.json" self.assertEqual(self.cli(["blocks", str(self.root), "--order", str(order), "--out", str(out)]), 0) doc = json.loads(out.read_text(encoding="utf-8")) self.assertEqual(doc["schema"], "okf-wiki/blocks/1") self.assertEqual(doc["order"], names) self.assertEqual(len(doc["blocks"]), sum(len(kblocks.blocks(self.kilde / n)) for n in names)) self.assertEqual(set(doc["blocks"][0]), {"file", "start", "end", "kind", "section", "version", "chars"}) for b in doc["blocks"]: # the characters of the block's lines, each with its newline (motor B17) lines = kblocks.read_lines(self.kilde / b["file"])[b["start"] - 1:b["end"]] self.assertEqual(b["chars"], sum(len(line) + 1 for line in lines)) self.assertEqual(self.cli(["blocks", str(self.root), "--order", str(order), "--out", str(out)]), 2) with redirect_stdout(io.StringIO()) as printed: self.assertEqual(kblocks.main(["total", str(self.root)]), 0) self.assertIn(f"{len(doc['blocks'])} blocks in 6 files", printed.getvalue()) def test_a_text_file_is_ordered_split_and_counted(self) -> None: # motor step 2 (B7): .txt is a source like .md, never dropped (self.kilde / "notat.txt").write_text("Kompost i lag.\n\nVann ukentlig.\n", encoding="utf-8") order = self.tmp / "order.txt" self.assertEqual(self.cli(["order", str(self.root), "--out", str(order)]), 0) self.assertIn("notat.txt", order.read_text(encoding="utf-8").split()) with redirect_stdout(io.StringIO()) as printed: self.assertEqual(kblocks.main(["total", str(self.root)]), 0) self.assertIn("in 7 files", printed.getvalue()) def test_commands_that_cannot_run_exit_2_and_write_nothing(self) -> None: empty = self.tmp / "empty" empty.mkdir() out = self.tmp / "o.txt" self.assertEqual(self.cli(["order", str(empty), "--out", str(out)]), 2) # no kilde/ folder order = self.tmp / "order.txt" order.write_text("docs-en-basil.md\ndocs-en-gone.md\n", encoding="utf-8") self.assertEqual(self.cli(["blocks", str(self.root), "--order", str(order), "--out", str(out)]), 2) self.assertFalse(out.exists()) COMPONENT_NOTE = ('\n * Added a frost warning to the planner.\n' ' * Seed trays can be named,\n and moved.\n\n') BOLD_NOTE = '**1.4.0**\n\nMay 2, 2026\n\n**Added**\n\n* Added a frost warning to the planner.\n\n' if __name__ == "__main__": unittest.main()