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>
374 lines
16 KiB
Python
374 lines
16 KiB
Python
"""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()
|