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

226 lines
9.8 KiB
Python

"""Tests for tools/x_fields_check.py and docs/x-fields.md: every x- field has a row with a measured reason (format
choice g, PLAN.md criterion 5; wave 2 order 7).
The check reads the table in docs/x-fields.md and every concept page of a bundle. It fails when a page carries an x-
field (top level or on a sources entry) that has no row, or has it at another place than its row says, or carries a
field whose row says "not in v1"; and when a row has no reason or a reason without a measured number. The fixtures are
synthetic text about bread (CLAUDE.md rule 3).
Run: python3 -m unittest discover -s tests -p 'test_x_fields.py'
"""
from __future__ import annotations
import contextlib
import importlib.util
import io
import re
import sys
import tempfile
import unittest
from pathlib import Path
from typing import Any
ROOT = Path(__file__).resolve().parents[1]
TABLE = ROOT / "docs" / "x-fields.md"
# Loaded from its file, as tests/test_fetch_docs.py loads its tool; mypy checks the tool when it is named.
_SPEC = importlib.util.spec_from_file_location("x_fields_check", ROOT / "tools" / "x_fields_check.py")
assert _SPEC is not None and _SPEC.loader is not None
xf: Any = importlib.util.module_from_spec(_SPEC)
sys.modules["x_fields_check"] = xf
_SPEC.loader.exec_module(xf)
FIELD = re.compile(r"\bx-[a-z][a-z0-9-]*")
HEADER = ("| Field | Where | Status | Written by | Read by | Meaning | Measured reason | Standard field if Google adopts one |\n"
"|---|---|---|---|---|---|---|---|\n")
ROWS = {
"x-quote": "| `x-quote` | sources[] | v1 | a | b | The quote. | SPEC names 0 quote keys; 4 of 4 entries carry one. | none |\n",
"x-locator": "| `x-locator` | sources[] | v1 | a | b | The line. | SPEC names 0 locator keys; 4 of 4 entries. | none |\n",
"x-main-for": "| `x-main-for` | page | v1 | a | b | Main page. | 0 hits for main page in SPEC; 1 source. | none |\n",
"x-outdated": "| `x-outdated` | page | not in v1 | a | b | Pairs. | 0 hits in SPEC; 6 pairs on 4 pages. | supersedes |\n",
}
PAGE = """---
type: Concept
title: Sourdough
sources:
- id: b-2
resource: /kilde/bread.md
x-locator: { line: 2 }
x-quote: 'Sourdough needs a starter'
x-main-for:
- /kilde/bread.md
---
# Sourdough
Sourdough needs a starter.[^b-2]
[^b-2]: Bread notes, line 2
"""
INDEX = "# Bread\n\n* [Sourdough](sourdough.md) - A bread.\n"
class Fixture(unittest.TestCase):
def setUp(self) -> None:
self._tmp = tempfile.TemporaryDirectory(prefix="x-fields-test-")
self.root = Path(self._tmp.name)
self.bundle = self.root / "bundle"
self.bundle.mkdir()
(self.bundle / "index.md").write_text(INDEX, encoding="utf-8")
(self.bundle / "log.md").write_text("# Directory Update Log\n\n## 2026-10-09\n* Added.\n", encoding="utf-8")
self.table = self.root / "x-fields.md"
self.write_table()
self.page(PAGE)
def tearDown(self) -> None:
self._tmp.cleanup()
def write_table(self, rows: dict[str, str] | None = None) -> None:
body = "".join((ROWS if rows is None else rows).values())
self.table.write_text("# x- fields\n\nIntro.\n\n" + HEADER + body + "\nAfter the table.\n", encoding="utf-8")
def page(self, text: str, name: str = "sourdough.md") -> None:
(self.bundle / name).write_text(text, encoding="utf-8")
def run_check(self) -> tuple[int, str]:
out = io.StringIO()
with contextlib.redirect_stdout(out), contextlib.redirect_stderr(out):
code = xf.main([str(self.bundle), "--table", str(self.table)])
return code, out.getvalue()
class CheckTest(Fixture):
def test_a_bundle_with_only_table_fields_passes(self) -> None:
code, out = self.run_check()
self.assertEqual(0, code, out)
self.assertIn("PASS", out)
def test_a_page_field_without_a_row_fails_and_is_named(self) -> None:
self.page(PAGE.replace("x-main-for:", "x-aliases: [levain]\nx-main-for:"))
code, out = self.run_check()
self.assertEqual(1, code, out)
self.assertIn("x-aliases", out)
def test_a_source_entry_field_without_a_row_fails(self) -> None:
self.page(PAGE.replace(" x-quote:", " x-quote-by: code\n x-quote:"))
code, out = self.run_check()
self.assertEqual(1, code, out)
self.assertIn("x-quote-by", out)
def test_a_field_at_another_place_than_its_row_fails(self) -> None:
self.page(PAGE.replace("x-main-for:", "x-quote: 'Sourdough'\nx-main-for:"))
code, out = self.run_check()
self.assertEqual(1, code, out)
self.assertIn("x-quote", out)
def test_a_field_whose_row_says_not_in_v1_fails_on_a_page(self) -> None:
self.page(PAGE.replace("x-main-for:", "x-outdated: [{ old: b-1, new: b-2 }]\nx-main-for:"))
code, out = self.run_check()
self.assertEqual(1, code, out)
self.assertIn("x-outdated", out)
def test_a_row_without_a_reason_fails(self) -> None:
rows = dict(ROWS, **{"x-quote": "| `x-quote` | sources[] | v1 | a | b | The quote. | | none |\n"})
self.write_table(rows)
code, out = self.run_check()
self.assertEqual(1, code, out)
self.assertIn("x-quote", out)
def test_a_reason_without_a_measured_number_fails(self) -> None:
rows = dict(ROWS, **{"x-quote": "| `x-quote` | sources[] | v1 | a | b | The quote. | The standard lacks it. | none |\n"})
self.write_table(rows)
code, out = self.run_check()
self.assertEqual(1, code, out)
self.assertIn("x-quote", out)
def test_a_reason_whose_only_numbers_are_references_fails(self) -> None:
for reason in ("SPEC § 4.1 allows it.", "See #22 and K2 point 8, criterion 5.", "Chosen 06.10.2026 at ad30107.",
"Decided on 2026-10-08 in step 11 of wave 2, order 7."):
with self.subTest(reason=reason):
self.write_table(dict(ROWS, **{"x-quote": f"| `x-quote` | sources[] | v1 | a | b | Q. | {reason} | none |\n"}))
code, out = self.run_check()
self.assertEqual(1, code, out)
self.assertIn("x-quote", out)
def test_a_row_with_an_unknown_place_or_status_fails(self) -> None:
for bad in ("| `x-quote` | body | v1 | a | b | Q. | 0 keys in SPEC. | none |\n",
"| `x-quote` | sources[] | maybe | a | b | Q. | 0 keys in SPEC. | none |\n"):
with self.subTest(row=bad):
self.write_table(dict(ROWS, **{"x-quote": bad}))
self.assertEqual(1, self.run_check()[0])
def test_a_field_given_two_rows_fails(self) -> None:
self.write_table(dict(ROWS, again=ROWS["x-quote"]))
self.assertEqual(1, self.run_check()[0])
def test_a_page_whose_frontmatter_does_not_parse_fails(self) -> None:
self.page("---\ntype: [Concept\n---\n\n# Rye\n", "rye.md")
code, out = self.run_check()
self.assertEqual(1, code, out)
self.assertIn("rye.md", out)
def test_a_bundle_without_concept_pages_fails(self) -> None:
(self.bundle / "sourdough.md").unlink()
self.assertEqual(1, self.run_check()[0])
def test_index_and_log_are_not_read_as_pages(self) -> None:
(self.bundle / "log.md").write_text("---\nx-anything: 1\n---\n# Log\n", encoding="utf-8")
self.assertEqual(0, self.run_check()[0])
def test_a_missing_table_or_bundle_cannot_run(self) -> None:
self.table.unlink()
self.assertEqual(2, self.run_check()[0])
self.write_table()
self.assertEqual(2, xf.main([str(self.root / "nope"), "--table", str(self.table)]))
def test_a_table_file_without_the_table_cannot_run(self) -> None:
self.table.write_text("# x- fields\n\nNo table here.\n", encoding="utf-8")
self.assertEqual(2, self.run_check()[0])
class RepoTableTest(unittest.TestCase):
"""docs/x-fields.md itself: one row per x- field the code names, measured (grep over okfwiki/ and skills/)."""
def rows(self) -> dict[str, Any]:
rows, problems = xf.read_table(TABLE)
self.assertEqual([], problems)
return rows # type: ignore[no-any-return]
def test_every_row_has_a_measured_reason(self) -> None:
self.assertGreater(len(self.rows()), 0)
def test_the_table_has_one_row_per_x_field_the_code_and_the_skill_name(self) -> None:
named: set[str] = set()
for top in ("okfwiki", "skills"):
for path in sorted((ROOT / top).rglob("*")):
if path.is_file() and path.suffix in (".py", ".md"):
named |= set(FIELD.findall(path.read_text(encoding="utf-8")))
self.assertGreater(len(named), 0, "a grep that finds nothing cannot pass")
self.assertEqual(sorted(named), sorted(self.rows()))
def test_x_main_for_and_x_outdated_stand_as_the_contracts_say(self) -> None:
rows = self.rows()
self.assertEqual("page", rows["x-main-for"].where)
self.assertIn("K2 point 8", rows["x-main-for"].standard)
self.assertEqual("not in v1", rows["x-outdated"].status) # CLAUDE.md: Outdated-marking is not in v1
def test_every_writer_a_row_names_writes_its_field(self) -> None:
# review finding 7 (order 39): the x-outdated row named the skill as its writer, and the skill has 0 hits
for field, row in self.rows().items():
files = re.findall(r"[\w./-]+\.(?:py|md)\b", row.written)
with self.subTest(field=field):
if row.written.startswith("none"):
self.assertEqual([], files)
continue
self.assertNotEqual([], files, "a writer names a file, or the row says none")
for rel in files:
path = ROOT / rel
self.assertTrue(path.is_file(), rel)
self.assertIn(field, path.read_text(encoding="utf-8"), rel)
if __name__ == "__main__":
unittest.main()