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

179 lines
9 KiB
Python

"""The checks at writing on K's fragments (V1 Steps 2 and 5, brief SC1(b)(c), SC3).
The one hard check at writing is the quote (rule E, chosen in Step 4): every fragment carries a quote that stands
verbatim on a line inside its anchor span. P1 saw the compiler write numbers as words to slip past the trial's rule,
which asked for a quote only when the text held a digit or a backticked name (F1-F3). Every fragment also carries a
provenance mark from a fixed list (documented | inferred | merged), and the mark never exempts the quote (P1-P4).
Links are not checked at writing. The fixtures are synthetic text about gardening (CLAUDE.md rule 3).
VALIDATE and ACCEPT are the code under test, bound to the package (order 5 of wave 1, rev 4 Step 11). VALIDATE is
`okfwiki.kpack.validate`. ACCEPT runs `kpack accept` on a temporary work folder and returns the records it wrote to
`accepted.json`, because P3 must show that the mark is carried onward, not only kept by validate (PM plan check 05.10).
Run: python3 -m unittest discover -s tests -p 'test_fragment_rule.py'
"""
from __future__ import annotations
import io
import json
import sys
import tempfile
import unittest
from collections import Counter
from contextlib import redirect_stdout
from pathlib import Path
from typing import Any, Callable
ROOT = Path(__file__).resolve().parents[1]
sys.path.insert(0, str(ROOT))
from okfwiki import kpack # noqa: E402
Validate = Callable[[list[Any], list[str], dict[str, Any], Path], tuple[list[dict[str, Any]], Counter[str]]]
Accept = Callable[[list[Any], list[str], dict[str, Any], Path], list[dict[str, Any]]]
def _validate(fragments: list[Any], names: list[str], blocks_doc: dict[str, Any], kilde: Path
) -> tuple[list[dict[str, Any]], Counter[str]]:
return kpack.validate(fragments, names, blocks_doc, kilde)
def _accept(fragments: list[Any], names: list[str], blocks_doc: dict[str, Any], kilde: Path) -> list[dict[str, Any]]:
"""Pack 1 of `names`, accepted by the package's command into an empty work folder; returns accepted.json's records."""
with tempfile.TemporaryDirectory() as tmp:
work = Path(tmp)
(work / "K-fragments").mkdir()
(work / "K-work").mkdir()
(work / "blocks.json").write_text(json.dumps({**blocks_doc, "order": names}), encoding="utf-8")
(work / "K-fragments" / "pack-1.json").write_text(json.dumps({"fragments": fragments}), encoding="utf-8")
(work / "K-work" / "index.json").write_text(json.dumps({"entries": [INDEX_ENTRY]}), encoding="utf-8")
with redirect_stdout(io.StringIO()):
code = kpack.main(["accept", "1", "--blocks", str(work / "blocks.json"), "--sources", str(kilde.parent),
"--work", str(work)])
if code != 0:
raise RuntimeError(f"accept exited {code}")
records: list[dict[str, Any]] = json.loads((work / "K-work" / "accepted.json").read_text())["fragments"]
return records
VALIDATE: Validate = _validate
ACCEPT: Accept = _accept
SOURCE = "docs-en-basil.md"
MISSING_SOURCE = "docs-en-mint.md"
LINES = (
"# Growing basil",
"",
"Basil needs warm soil and six hours of sun.",
"Water basil twice a week, and pinch the top `leaf` pairs to keep it bushy.",
"",
)
BLOCKS: dict[str, Any] = {"blocks": [{"file": SOURCE, "start": 3, "end": 4, "section": "Growing basil",
"version": None}]}
INDEX_ENTRY: dict[str, Any] = {"id": "basil", "title": "Basil", "aliases": ["Basil"], "kind": "skeleton",
"merge_of": None, "origin": {"file": SOURCE, "line": 1}}
QUOTE = "Basil needs warm soil and six hours of sun."
PROVENANCE = ("documented", "inferred", "merged")
NO_MARK = object()
def fragment(text: str, quote: str | None = None, start: int = 3, end: int = 3, provenance: Any = "documented",
file: str = SOURCE) -> dict[str, Any]:
f: dict[str, Any] = {"concept": "Basil", "status": "existing", "id": "basil", "text": text,
"anchor": {"file": file, "start": start, "end": end}}
if quote is not None:
f["quote"] = quote
if provenance is not NO_MARK:
f["provenance"] = provenance
return f
class FragmentRuleTest(unittest.TestCase):
def setUp(self) -> None:
self._tmp = tempfile.TemporaryDirectory()
self.kilde = Path(self._tmp.name) / "kilde"
self.kilde.mkdir()
(self.kilde / SOURCE).write_text("\n".join(LINES), encoding="utf-8")
def tearDown(self) -> None:
self._tmp.cleanup()
def assert_rejected(self, case: str, f: dict[str, Any], reason: str) -> None:
accepted, rejected = VALIDATE([f], [SOURCE], BLOCKS, self.kilde)
self.assertEqual(accepted, [], f"{case}: the fragment was accepted ({f['text']!r}); it must be rejected "
f"for {reason}")
self.assertEqual(rejected, Counter({reason: 1}), case)
def assert_rejected_for_missing_quote(self, case: str, f: dict[str, Any]) -> None:
self.assert_rejected(case, f, "quote-missing")
# --- rule E: the quote --------------------------------------------------------------------------------------
def test_f1_a_number_written_as_a_word_needs_a_quote(self) -> None:
self.assert_rejected_for_missing_quote("F1 number as a word", fragment("Basil needs six hours of sun."))
def test_f2_a_digit_needs_a_quote(self) -> None:
self.assert_rejected_for_missing_quote("F2 digit", fragment("Basil needs 6 hours of sun."))
def test_f3_a_backticked_name_needs_a_quote(self) -> None:
self.assert_rejected_for_missing_quote(
"F3 backticked name", fragment("Pinch the top `leaf` pairs to keep basil bushy.", start=4, end=4))
def test_f4_plain_prose_needs_a_quote(self) -> None:
self.assert_rejected_for_missing_quote("F4 plain prose (rule E)", fragment("Basil likes warm soil."))
def test_f5_a_quote_that_is_not_verbatim_in_the_span_is_rejected(self) -> None:
self.assert_rejected("F5 quote not verbatim", fragment("Basil likes warm soil.", quote="Basil needs cold soil."),
"quote-not-in-span")
def test_f6_a_missing_anchor_file_is_rejected_not_a_crash(self) -> None:
blocks = {"blocks": BLOCKS["blocks"] + [{"file": MISSING_SOURCE, "start": 1, "end": 2, "section": "Mint",
"version": None}]}
f = fragment("Mint spreads fast.", quote="Mint spreads fast.", start=1, end=1, file=MISSING_SOURCE)
accepted, rejected = VALIDATE([f], [SOURCE, MISSING_SOURCE], blocks, self.kilde)
self.assertEqual(accepted, [])
self.assertEqual(sum(rejected.values()), 1, rejected)
def test_known_positive_a_quoted_fragment_is_accepted(self) -> None:
accepted, rejected = VALIDATE([fragment("Basil needs six hours of sun.", quote=QUOTE)],
[SOURCE], BLOCKS, self.kilde)
self.assertEqual(rejected, Counter())
self.assertEqual(len(accepted), 1)
self.assertEqual(accepted[0]["quote_line"], 3)
# --- the provenance mark ------------------------------------------------------------------------------------
def test_p1_a_fragment_without_a_provenance_mark_is_rejected(self) -> None:
self.assert_rejected("P1 no mark", fragment("Basil needs six hours of sun.", quote=QUOTE, provenance=NO_MARK),
"provenance-missing")
def test_p2_a_provenance_value_off_the_list_is_rejected(self) -> None:
for value in ("guessed", "", "Documented", ["documented"]):
with self.subTest(value=value):
self.assert_rejected(f"P2 {value!r}",
fragment("Basil needs six hours of sun.", quote=QUOTE, provenance=value),
"provenance-unknown")
def test_p3_each_listed_value_is_accepted_and_carried_onward(self) -> None:
for value in PROVENANCE:
with self.subTest(value=value):
records = ACCEPT([fragment("Basil needs six hours of sun.", quote=QUOTE, provenance=value)],
[SOURCE], BLOCKS, self.kilde)
self.assertEqual(len(records), 1)
self.assertEqual(records[0].get("provenance"), value)
def test_p4_the_mark_never_exempts_the_quote(self) -> None:
self.assert_rejected_for_missing_quote("P4 inferred without a quote",
fragment("Basil likes warm soil.", provenance="inferred"))
# --- links ---------------------------------------------------------------------------------------------------
def test_links_are_not_a_write_time_check(self) -> None:
f = fragment("Basil needs warm [soil](soil.md) and six hours of sun.", quote=QUOTE)
accepted, rejected = VALIDATE([f], [SOURCE], BLOCKS, self.kilde)
self.assertEqual(rejected, Counter(), "the hard check at writing is the quote check only")
self.assertEqual(len(accepted), 1)
if __name__ == "__main__":
unittest.main()