okf-wiki/tests/test_kblocks.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

374 lines
16 KiB
Python
Raw Permalink 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/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
<Note>
Mulch keeps the soil moist in summer.
</Note>
<Tip>
Spread it after rain.
</Tip>
Use <b>straw</b> or bark.
<Steps>
<Step>
Rake the bed.
</Step>
</Steps>
<https://example.org/mulch>
"""
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 <style>{`
.shed { color: green; }
`}</style>;
};
## 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, <Update label="X.Y.Z" ...>, 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")]
# <Note> (3), <Tip> (7), </Tip> (11), <Steps> and <Step> (15, 16) start nothing; a tag inside a paragraph
# that has started stays in it (5, 18, 19); a paragraph holding <b> 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 ("<Note>", "</Note>", " <Step>", '<Frame caption="x">', "<br/>", "<img src='a.png' />"):
self.assertIsNotNone(common.HTML_TAG_ONLY.match(line), line)
for line in ("Use <b>straw</b> or bark.", "<b>bold</b>", "a < b > c", "<Note>Keep it moist.", "",
"<https://example.org/mulch>", "<mailto:beds@example.org>"):
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 = ('<Update label="1.4.0" description="May 2026">\n * Added a frost warning to the planner.\n'
' * Seed trays can be named,\n and moved.\n</Update>\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()