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>
226 lines
9.8 KiB
Python
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()
|