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