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