"""The reference section: /reference/settings and the three contract pages, in the 1c Logbook layout. The other site suites are about slices — a heading renamed in AGENTS.md stops the build. This one is about the promise a *settings* page makes, which is stronger and easier to break quietly: the page is not written, it is read out of `manager/core/.env.example`, so a key added there appears here with nobody editing site/, and a key documented nowhere fails the build rather than reaching the site bare. The rest is the layout: the pinned console carries the page's own entries and nothing it invented, and a reference page keeps every piece of furniture an article has — the sidebar, the folded menus, prev/next and "Edit this page". python3 -m unittest discover -s tests """ import json import re import shutil import tempfile import unittest from pathlib import Path from tests.test_site_build import (BUILDER, HAS_MARKDOWN_IT, REPO, SITE, ScratchCase, needs_renderer, run_build) ENV_EXAMPLE = "manager/core/.env.example" CONSOLE_LINE = re.compile( r'(.*?)', re.S) CONSOLE_KEY = re.compile(r'([^<]*)') CONSOLE_VALUE = re.compile(r'([^<]*)') HEADING_ID = re.compile(r'

(.*?)

', re.S) SIDE_HERE = re.compile(r'class="side-link side-here" href="([^"]+)"') NAV = re.compile(r'
(.*?)
', re.S) CONTENTS = re.compile( r'
(.*?)
', re.S) def settings(text: str) -> dict: """{name: value} for every NAME=value line in an env file, read the naive way on purpose — the point of comparing against it is that it shares no code with the builder's own parser.""" found = {} for line in text.splitlines(): if line.startswith("#") or "=" not in line.strip(): continue name, _, value = line.partition("=") if name.strip() and name.strip() == name: found[name] = value return found class BuiltSite(unittest.TestCase): """The real manifest, built once into a scratch directory.""" @classmethod def setUpClass(cls): if not HAS_MARKDOWN_IT: raise unittest.SkipTest("markdown-it-py is not installed") cls.out = Path(tempfile.mkdtemp(prefix="bench-reference-")).resolve() result = run_build(REPO, cls.out) if result.returncode != 0: # not assert: must survive python -O raise RuntimeError( f"site/build.py failed:\n{result.stdout}{result.stderr}") cls.manifest = json.loads( (SITE / "pages.json").read_text(encoding="utf-8")) cls.env = (REPO / ENV_EXAMPLE).read_text(encoding="utf-8") @classmethod def tearDownClass(cls): if hasattr(cls, "out"): shutil.rmtree(cls.out, ignore_errors=True) def page(self, route: str) -> str: return BUILDER.target_for(self.out, route).read_text("utf-8") def entries(self) -> list: return [page for page in self.manifest["pages"] if page["layout"] == "reference"] class TheSectionJoinsTheSite(BuiltSite): """Reference is a section beside Guides and Concepts — in the nav, in the sidebar and on the reading order the arrows walk.""" def test_the_four_routes_are_all_there(self): """Named one by one rather than counted: a route quietly dropped from the manifest is exactly the failure this catches.""" routes = {page["path"] for page in self.entries()} for route in ("/reference/settings/", "/reference/adapters/", "/reference/driver/", "/reference/commands/"): self.assertIn(route, routes) self.assertTrue(BUILDER.target_for(self.out, route).is_file(), f"{route} produced no page") def test_reference_is_a_section_of_its_own(self): names = [group["name"] for group in BUILDER.sections(self.manifest)] self.assertEqual(["Guides", "Concepts", "Reference"], names) def test_the_nav_reaches_it_from_a_concept_page(self): html = self.page("/concepts/stages/") self.assertIn('href="/reference/settings/">Reference', html) def test_a_reference_page_marks_itself_in_the_sidebar(self): for entry in self.entries(): here = SIDE_HERE.findall(self.page(entry["path"])) self.assertTrue(here, f'{entry["path"]} does not mark itself') self.assertEqual({entry["path"]}, set(here), entry["path"]) def test_it_is_on_the_flow_the_arrows_walk(self): order = [page["path"] for page in BUILDER.flow(self.manifest)] for entry in self.entries(): self.assertIn(entry["path"], order) self.assertEqual("/reference/commands/", order[-1], "the reference section is not the end of the flow") class TheSettingsPageIsTheEnvFile(BuiltSite): """Acceptance: every setting in .env.example, exactly once, with the default the file actually gives it.""" def setUp(self): self.html = self.page("/reference/settings/") self.expected = settings(self.env) def test_it_reads_as_a_settings_file_rather_than_a_short_list(self): """Guards every test below from passing on an empty page.""" self.assertGreater(len(self.expected), 15, "the env example has almost no settings in it") self.assertIn("BOARD_PORT", self.expected) self.assertIn("BENCH_SOURCE", self.expected) def test_every_setting_appears_exactly_once_in_the_console(self): listed = [CONSOLE_KEY.search(line).group(1) for _, line in CONSOLE_LINE.findall(self.html)] self.assertEqual(sorted(self.expected), sorted(listed), "the console and the env file disagree about " "which settings exist") self.assertEqual(len(listed), len(set(listed)), "a setting is listed twice") def test_each_one_carries_the_default_the_file_gives_it(self): shown = {} for _, line in CONSOLE_LINE.findall(self.html): value = CONSOLE_VALUE.search(line) shown[CONSOLE_KEY.search(line).group(1)] = \ value.group(1) if value else None for name, value in self.expected.items(): self.assertEqual(value, shown[name], f"{name}'s default on the page is not the " f"one in {ENV_EXAMPLE}") def test_an_empty_default_is_shown_as_empty_rather_than_dropped(self): """BOARD_TITLE= is a default: the board falls back to the repo directory's name. A page that skipped the line would read as a setting with no default at all.""" self.assertEqual("", self.expected["BOARD_TITLE"]) self.assertIn('BOARD_TITLE' '=' '', self.html) def test_every_console_line_points_at_a_heading_on_the_page(self): anchors = {slug for slug, _ in HEADING_ID.findall(self.html)} targets = {slug for slug, _ in CONSOLE_LINE.findall(self.html)} self.assertTrue(targets) self.assertEqual(set(), targets - anchors, "a console line links to an anchor that is not " "on the page") def test_the_keys_are_grouped_the_way_the_file_groups_them(self): """The four model keys sit under one comment in the file, so they are one entry on the page — and the three headings below are the shape "grouped as that file groups them" takes.""" headings = [text for _, text in HEADING_ID.findall(self.html)] self.assertIn("BOARD_PORT", headings) self.assertIn("BOARD_CLAUDE_BIN, BOARD_OPENCODE_BIN", headings) self.assertIn("BOARD_AGENT_MODEL, BOARD_AGENT_MODEL_WORK, " "BOARD_AGENT_MODEL_ACT_PR, BOARD_AGENT_MODEL_REVIEW", headings) def test_a_default_is_the_files_own_line_and_says_it_is_one(self): """The flag under each heading is the line copied out of the file, not a retyping of the value — and it is fenced as `env` so the stylesheet can draw a value you set differently from a terminal that printed something.""" self.assertIn('
BOARD_AGENT_COMMANDS='
                      "python3 -m unittest\n
", self.html) css = (SITE / "static" / "site.css").read_text("utf-8") self.assertIn("code.language-env", css, "nothing in the stylesheet tells a default from a " "code block") def test_the_documentation_is_the_files_own_comment(self): """Not a paraphrase written into site/: sentences out of the comment blocks, arriving as the markdown they were written as.""" self.assertIn("Pinned by default so the URL is bookmarkable", self.html) self.assertIn("a test runner missing from this list", self.html) self.assertIn("board: <number> → <stage> " "(<name>)", self.html) def test_a_placeholder_in_a_comment_survives_as_text(self): """`` is a placeholder, and a markdown parser that honoured HTML would post it into the page as a tag and show nothing. Generated bodies are rendered with HTML off.""" self.assertIn("<git user.name>", self.html) self.assertNotIn("", self.html) def test_a_comment_documenting_no_key_is_kept_as_a_remark(self): """The note about the `checks` file sits between two settings and belongs to neither. It stays on the page — it is documentation — as a blockquote rather than as the next key's description.""" self.assertIn("
", self.html) note = self.html.split("
") self.assertTrue( any("definition-of-done check" in part for part in note), "the note about the checks file is not on the page") def test_edit_this_page_opens_the_file_itself(self): """There is no `from` heading to anchor at: the page is the whole file.""" blob = self.manifest["site"]["blob_base"].rstrip("/") + "/" self.assertIn(f'href="{blob}{ENV_EXAMPLE}"', self.html) class TheContractPagesAreSlices(BuiltSite): """Acceptance: slices of the contract files, not paraphrases.""" def test_the_adapter_contract_is_the_adapters_readme(self): html = self.page("/reference/adapters/") self.assertIn("stdout is captured by the board as the job log", html) self.assertIn("work", html) # The normalized event schema, indented in the README, arrives as # the code block it is. self.assertIn("
", html)
        self.assertIn(""v": 1", html)

    def test_the_driver_contract_is_agents_md(self):
        html = self.page("/reference/driver/")
        self.assertIn("refuse fast with a printed reason", html)
        self.assertIn("DRIVE URL", html)

    def test_the_command_contract_is_agents_md(self):
        html = self.page("/reference/commands/")
        self.assertIn("CMD_WORKTREE", html)
        self.assertIn("Commands arm on first click and run on the second",
                      html)

    def test_each_one_edits_at_the_section_it_was_cut_from(self):
        blob = self.manifest["site"]["blob_base"].rstrip("/") + "/"
        for entry in self.entries():
            if not entry.get("from"):
                continue
            wanted = (blob + entry["source"] + "#"
                      + BUILDER.github_anchor(entry["from"]))
            self.assertIn(f'href="{wanted}"', self.page(entry["path"]),
                          f'{entry["path"]}: "Edit this page" does not open '
                          f'{entry["source"]} at {entry["from"]}')

    def test_a_pages_console_is_its_own_headings(self):
        """The adapter page's entries are the contract's `###` headings,
        promoted — so the console is generated for a sliced page too,
        with no per-page authoring anywhere."""
        html = self.page("/reference/adapters/")
        anchors = dict(HEADING_ID.findall(html))
        lines = CONSOLE_LINE.findall(html)
        self.assertEqual(sorted(anchors), sorted(slug for slug, _ in lines))
        self.assertIn("run — execute one headless job to completion",
                      [CONSOLE_KEY.search(line).group(1) for _, line in lines],
                      "the console shows the heading's markdown backticks")


class TheLayoutKeepsEveryArticlesFurniture(BuiltSite):
    """A reader must not lose the nav, the contents or the arrows by
    walking into the reference section."""

    def test_the_three_columns_are_there(self):
        for entry in self.entries():
            html = self.page(entry["path"])
            for furniture in ('class="page-reference"', 'class="side"',
                              'class="prose"', 'class="gutter"',
                              'class="crumbs"', 'class="prose-lede"'):
                self.assertIn(furniture, html,
                              f'{entry["path"]} is missing {furniture}')

    def test_the_section_nav_is_folded_in_as_well(self):
        listed = [page for page in self.manifest["pages"]
                  if page.get("section")]
        for entry in self.entries():
            menu = NAV.search(self.page(entry["path"]))
            self.assertIsNotNone(menu, f'{entry["path"]} has no folded nav')
            for page in listed:
                self.assertIn(f'href="{page["path"]}"', menu.group(1),
                              f'{entry["path"]}\'s menu cannot reach '
                              f'{page["path"]}')

    def test_the_folded_contents_carries_the_anchors_the_console_does(self):
        """Below 1080px the whole gutter goes, console and all. The strip
        that replaces it has to reach everything the console did, or a
        phone loses the index entirely."""
        for entry in self.entries():
            html = self.page(entry["path"])
            strip = CONTENTS.search(html)
            self.assertIsNotNone(strip,
                                 f'{entry["path"]} has no contents strip')
            for slug, _ in CONSOLE_LINE.findall(html):
                self.assertIn(f'href="#{slug}"', strip.group(1),
                              f'{entry["path"]}\'s contents strip drops '
                              f"#{slug}")

    def test_the_arrows_are_rendered(self):
        for entry in self.entries():
            self.assertIn('