steppy-dev 0.3.0__py3-none-any.whl

steppy/report_cli.py

@@ -0,0 +1,173 @@
+"""``steppy report`` — render one run to a static site (leaf CLI module).
+
+Module scope stays typer + stdlib + ``_cli_common``. Every ``steppy.report`` (and
+``steppy.bundle``) import lives inside the command body, because ``cli.py`` imports
+*this* module eagerly to register the command — so a lazy import here is the only
+thing keeping the site renderer, the tar reader and the ``output/`` walker off the
+path a plain ``steppy run`` takes. Guard:
+``tests/test_no_report_import_on_default_path.py``.
+
+Naming note, since "report" is crowded: ``config.yaml``'s ``report:`` block is
+about pytest artifacts (JUnit, HTML, traces, videos, reruns), the
+``steppy-dev[report]`` extra is pytest-html, and ``steppy coverage report`` prints gap
+buckets. This command is the *run report site* — the thing you publish.
+"""
+
+from pathlib import Path
+from typing import Optional
+
+import typer
+from rich.markup import escape
+
+from ._cli_common import console, _cli_errors, _error
+
+
+def register_report(app: typer.Typer) -> None:
+    """Attach the ``report`` command to the root Typer app."""
+
+    @app.command("report")
+    def report(
+        bundle: Optional[Path] = typer.Argument(
+            None,
+            help="A .tar.zst/.tar.gz bundle, or an unpacked bundle directory. Omit to report on ./output/.",
+        ),
+        output: Optional[Path] = typer.Option(
+            None,
+            "--output",
+            "-o",
+            help="Where to write the site (default: output/report).",
+        ),
+        project_root: Path = typer.Option(Path("."), "--project-root", help="Project root (default: .)."),
+        output_dir: Optional[Path] = typer.Option(
+            None, "--output-dir", help="The run's output/ tree to read (default: <project-root>/output)."
+        ),
+        run_id: Optional[str] = typer.Option(
+            None, "--run-id", help="Which run to report on when output/ holds more than one."
+        ),
+        screenshots: str = typer.Option(
+            "failed",
+            "--screenshots",
+            help="Which captures to copy into the site: failed (default), all, or none.",
+        ),
+        badge_surface: str = typer.Option(
+            "all",
+            "--badge-surface",
+            help="Surface the coverage badge measures: all (endpoints + routes), endpoints, or routes.",
+        ),
+        badge_label: Optional[str] = typer.Option(
+            None, "--badge-label", help="Left-hand text on the badge (default: 'e2e surface')."
+        ),
+        title: Optional[str] = typer.Option(None, "--title", help="Heading for the report pages."),
+        templates_dir: Optional[Path] = typer.Option(
+            None, "--templates-dir", help="Override the template search root."
+        ),
+        force: bool = typer.Option(
+            False, "--force", "-f", help="Replace the contents of a non-empty output directory."
+        ),
+        dry_run: bool = typer.Option(False, "--dry-run", help="Report what would be written, write nothing."),
+        as_json: bool = typer.Option(False, "--json", help="Print report.json to stdout instead of a summary."),
+        open_browser: bool = typer.Option(False, "--open", help="Open the rendered report in a browser."),
+    ) -> None:
+        """Render one run's results to a self-contained static site.
+
+        Reads a results bundle — or the live ``output/`` tree of a run that used
+        ``steppy run --bundle`` — and writes ``index.html``, a page per scenario,
+        the coverage gap report, a machine-readable ``report.json`` and a
+        shields.io ``badge.json``. Everything is relative and self-contained, so it
+        works from a file:// path, a CI artifact, or GitHub/GitLab Pages.
+
+        **The exit code describes rendering, not the run.** A report of a failing
+        run still exits 0 — it rendered fine. Gate your build on ``steppy run``
+        itself (or read ``totals.exit_code`` out of ``report.json``); a report step
+        that goes red for a red run is a step people delete.
+        """
+        with _cli_errors():
+            from .report.build import ReportError, build_report
+
+            try:
+                result = build_report(
+                    project_root=project_root,
+                    bundle=bundle,
+                    site_dir=output,
+                    output_dir=output_dir,
+                    run_id=run_id,
+                    screenshots=screenshots,
+                    badge_surface=badge_surface,
+                    badge_label=badge_label,
+                    title=title,
+                    templates_dir=templates_dir,
+                    force=force,
+                    dry_run=dry_run,
+                )
+            except ReportError as e:
+                _error(str(e))
+                raise typer.Exit(1)
+            except ValueError as e:
+                # The policy/surface validators, which are worth a clean message
+                # rather than a traceback.
+                _error(str(e))
+                raise typer.Exit(1)
+
+            if as_json:
+                from .contracts.report import report_bytes
+
+                print(report_bytes(result.model).decode("utf-8"), end="")
+                raise typer.Exit(0)
+
+            _print_summary(result, dry_run=dry_run)
+
+            if open_browser and not dry_run:
+                import webbrowser
+
+                webbrowser.open((result.site_dir / "index.html").resolve().as_uri())
+
+
+def _print_summary(result, *, dry_run: bool) -> None:
+    """The post-render summary. Mirrors ``steppy build``'s counts vocabulary."""
+    totals = result.model.totals
+    verb = "Would render" if dry_run else "Rendered"
+    colour = "green" if totals.verdict in ("passed", "skipped") else "red"
+    console.print(
+        f"[{colour}]{totals.verdict.upper()}[/{colour}] {totals.scenarios} scenario(s), {totals.tests} test(s)"
+    )
+    if totals.outcomes:
+        console.print("[dim]" + "  ".join(f"{count} {name}" for name, count in totals.outcomes.items()) + "[/dim]")
+
+    causes = result.model.failure_causes
+    if causes:
+        console.print(f"\n[bold]Failure causes[/bold] ({len(causes)} distinct)")
+        for cause in causes[:5]:
+            # escape(), because a headline routinely contains a CSS selector and
+            # Rich would read `[data-testid="x"]` as markup and swallow it.
+            console.print(f"  [red]×{cause.count}[/red] {escape(cause.headline)} [dim]({cause.fingerprint})[/dim]")
+        if len(causes) > 5:
+            console.print(f"  [dim]… and {len(causes) - 5} more[/dim]")
+
+    coverage = result.model.coverage
+    if coverage.tier != "none":
+        pct = coverage.badge.percent
+        measured = f"{pct}%" if pct is not None else "n/a"
+        console.print(
+            f"\n[bold]E2E surface[/bold] {measured} "
+            f"[dim]({coverage.badge.tested}/{coverage.badge.declared}, source: {coverage.tier})[/dim]"
+        )
+
+    console.print(f"\n{verb} {len(result.files)} file(s) → {result.site_dir}")
+    if result.copied:
+        console.print(f"[dim]{result.copied} screenshot(s) copied, {_human(result.copied_bytes)}[/dim]")
+    if not dry_run:
+        console.print(f"[dim]Open {result.site_dir / 'index.html'}[/dim]")
+
+    for warning in result.warnings:
+        console.print(f"[yellow]WARNING[/yellow] {escape(warning)}")
+    for warning in result.model.coverage.warnings:
+        console.print(f"[yellow]WARNING[/yellow] {escape(warning)}")
+
+
+def _human(size: int) -> str:
+    value = float(size)
+    for unit in ("B", "KiB", "MiB", "GiB"):
+        if value < 1024 or unit == "GiB":
+            return f"{value:.0f} {unit}" if unit == "B" else f"{value:.1f} {unit}"
+        value /= 1024
+    return f"{value:.1f} GiB"  # pragma: no cover - the loop returns first

steppy/runmeta.py

@@ -0,0 +1,114 @@
+"""Run identity and the ``--bundle`` artifact layout.
+
+A **leaf**: stdlib plus ``steppy.__version__`` only. Three modules need to agree
+on what is written here and where — ``cli`` (single-worker runs),
+``coordinator`` (parallel runs) and ``bundle`` (the reader) — and two of those
+are lazy-imported from the third, so a shared home avoids an import cycle as
+well as three copies of the same path strings.
+
+Two things live here:
+
+**Run identity.** :func:`new_run_id` is the project's single id generator.
+Sortability is load-bearing rather than cosmetic: both
+``coverage.merge.latest_run_id`` and ``steppy bundle create`` resolve "the
+newest recorded run" by taking the lexicographically last directory name, so a
+random id would make them pick arbitrarily. Historically the parallel
+coordinator minted a bare ``uuid4().hex[:8]`` for exactly this variable, which
+is why that resolution was only ever correct on the single-worker path.
+
+**The sidecar.** ``steppy bundle create`` runs as a separate process, minutes
+or a CI step after the run itself, and cannot otherwise know what the run was
+asked to do. Re-deriving the spec from flags the user retypes is guaranteed to
+drift, and drift here means a results bundle that misreports its own
+dimensions. So a ``--bundle`` run records them.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+import uuid
+from pathlib import Path
+from typing import Any, Optional
+
+from . import __version__
+
+#: Per-run directories under ``output/``, mirroring
+#: ``output/coverage/raw/<run_id>/``. Keying on the run means a previous run's
+#: files can never be mistaken for this one's, so nothing has to be reset
+#: between runs — the failure mode that would otherwise ship yesterday's
+#: results inside today's bundle.
+EVENTS_SUBDIR = "events"
+JUNIT_SUBDIR = "junit"
+
+#: Where ``steppy report`` writes its static site by default. Lives here rather
+#: than in ``report/`` because the *bundler* needs it too: without skipping this
+#: directory, ``steppy bundle create`` would archive the whole rendered site —
+#: every screenshot it copied included — and roughly double the bundle's payload.
+#: (``classify`` maps ``output/reports``, plural, to a pytest-report kind; this
+#: singular directory would otherwise fall through to ``other`` and ship.)
+REPORT_SUBDIR = "report"
+
+#: Leading dot so it can never collide with a scenario slug. Under ``output/``
+#: because that is the only writable mount inside a worker container.
+RUN_SIDECAR_NAME = ".steppy-run.json"
+
+#: Schema version of the sidecar. Additive fields are always allowed and
+#: readers default what is absent — the same forward-compat rule the screenshot
+#: sidecars follow.
+RUN_SIDECAR_VERSION = 1
+
+
+def new_run_id() -> str:
+    """Sortable unique id for one run: ``20260806T101500Z-a1b2c3``."""
+    return time.strftime("%Y%m%dT%H%M%SZ", time.gmtime()) + "-" + uuid.uuid4().hex[:6]
+
+
+def bundle_dirs(project_root: Path, run_id: str) -> tuple[Path, Path]:
+    """``(events_dir, junit_dir)`` for a ``--bundle`` run."""
+    output = Path(project_root) / "output"
+    return output / EVENTS_SUBDIR / run_id, output / JUNIT_SUBDIR / run_id
+
+
+def sidecar_path(project_root: Path) -> Path:
+    return Path(project_root) / "output" / RUN_SIDECAR_NAME
+
+
+def write_run_sidecar(
+    project_root: Path,
+    *,
+    run_id: str,
+    spec: dict,
+    executor: str = "local",
+    slugs: Optional[list[str]] = None,
+) -> Optional[Path]:
+    """Write ``output/.steppy-run.json``. Best-effort — returns ``None`` and
+    never raises, because failing a whole test run over a metadata file would
+    be a poor trade. ``steppy bundle create`` says so loudly when it is absent.
+    """
+    payload: dict[str, Any] = {
+        "steppy_run": RUN_SIDECAR_VERSION,
+        "run_id": run_id,
+        "created_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+        "steppy_version": __version__,
+        "executor": executor,
+        "spec": spec,
+    }
+    if slugs is not None:
+        payload["slugs"] = list(slugs)
+    try:
+        path = sidecar_path(project_root)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(json.dumps(payload, indent=2, sort_keys=True) + "\n", encoding="utf-8", newline="\n")
+        return path
+    except OSError:
+        return None
+
+
+def read_run_sidecar(project_root: Path) -> Optional[dict]:
+    """Load ``output/.steppy-run.json``. ``None`` when absent or unreadable."""
+    try:
+        raw = json.loads(sidecar_path(project_root).read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return None
+    return raw if isinstance(raw, dict) else None

steppy/selection.py

@@ -0,0 +1,183 @@
+"""Shared scenario / locale / layout selection logic (FLAWS §8.3).
+
+The single-worker ``steppy run`` path (``cli.run``) and the parallel path
+(``coordinator.run_parallel``) both have to answer the same three questions from
+the same flags: *which scenarios* does ``--scenario`` / ``--tag`` / ``--guide`` /
+``--no-guide`` select, and *which locales / layouts* does ``--locales`` /
+``--layouts`` / ``--guide`` parametrize over. Historically each path re-implemented
+that decision, kept equivalent only by the parallel integration tests — a drift here
+would make ``--workers N`` silently run a **different scenario set** than
+``--workers 1``. This module is the one home for the decision; each caller keeps its
+own *projection* (cli builds ``test_<slug>.py`` paths, coordinator enqueues bare
+slugs) and its own console messaging.
+
+Kept deliberately pure — depends only on ``.parser``, ``.models`` and stdlib, no
+``typer``/``rich`` — so ``cli.py`` can import it **eagerly** without tripping the
+no-parallel-import guard (which blocks ``coordinator``/``worker``/``_parallel``, not
+this leaf). User errors surface as :class:`SelectionError`; each caller translates it
+to its own exit idiom (``typer.Exit`` / ``coordinator._SelectionExit``).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+from .locales import LocaleSyntaxError, normalize_locale
+from .models import SteppyConfig
+from .parser import ParseError, parse_scenarios_from_directory
+
+
+class SelectionError(Exception):
+    """A user-facing selection error (bad flag value, missing file/dir, parse
+    failure). Carries the primary ``message``, the intended process ``exit_code``
+    (always 1 today), and an optional ``hint`` line (may contain rich markup — only
+    printed by callers that render markup, i.e. never through cli's markup-escaping
+    ``_error``)."""
+
+    def __init__(self, message: str, *, exit_code: int = 1, hint: Optional[str] = None):
+        super().__init__(message)
+        self.message = message
+        self.exit_code = exit_code
+        self.hint = hint
+
+
+def _split_csv(value: str, flag: str, what: str) -> list[str]:
+    """Split a comma-separated flag value, stripping blanks. Raises
+    ``SelectionError`` when nothing survives (mirrors the historical
+    ``--<flag> did not contain any <what>`` message in both callers)."""
+    out = [item.strip() for item in value.split(",") if item.strip()]
+    if not out:
+        raise SelectionError(f"--{flag} did not contain any {what}")
+    return out
+
+
+def apply_guide_defaults(guide: bool, screenshots: bool, no_asserts: bool) -> tuple[bool, bool]:
+    """Resolve the flags ``--guide`` implies. Returns ``(screenshots, no_asserts)``.
+
+    Guide mode captures screenshots by definition, and forces ``--no-asserts``
+    because text assertions (toasts, row-contains) are language-specific and
+    would fail every non-default locale during multilingual capture.
+
+    Lives here, beside :func:`resolve_locales` / :func:`resolve_layouts` — the
+    other two things ``--guide`` implies — so the whole "what does guide mode
+    mean" contract is in one module. It is shared by ``cli.run``, ``cli.rerun``
+    and ``coordinator.run_parallel``, which previously each spelled the rule
+    out; a fourth implication added to only some of them would silently make
+    the parallel path diverge from the single-worker path.
+    """
+    if guide:
+        return True, True
+    return screenshots, no_asserts
+
+
+def resolve_locales(explicit: Optional[str], guide: bool, config: Optional[SteppyConfig]) -> list[str]:
+    """Resolve the locale parametrization list.
+
+    Explicit ``--locales`` wins (CSV split; error if it yields nothing); else
+    ``--guide`` pulls ``config.locales``; else empty (no parametrization).
+    ``config=None`` in guide mode yields ``[]`` — that is how cli models its
+    "config failed to load, degrade to empty" path.
+    """
+    if explicit:
+        codes = _split_csv(explicit, "locales", "locale codes")
+        # Each code becomes a screenshot directory segment that ``steppy build``
+        # reads back, and the build side rejects a malformed tag — so accepting
+        # one here only defers the failure to a place that cannot explain it.
+        for code in codes:
+            try:
+                normalize_locale(code)
+            except LocaleSyntaxError as exc:
+                raise SelectionError(f"--locales: {exc}") from exc
+        return codes
+    if guide and config is not None:
+        return list(config.locales or [])
+    return []
+
+
+def resolve_layouts(explicit: Optional[str], guide: bool, config: Optional[SteppyConfig]) -> list[str]:
+    """Resolve the layout parametrization list — mirror of :func:`resolve_locales`
+    over ``config.screenshot.layouts``."""
+    if explicit:
+        return _split_csv(explicit, "layouts", "layout names")
+    if guide and config is not None:
+        return list(config.screenshot.layouts.keys())
+    return []
+
+
+def select_scenario_slugs(
+    *,
+    scenarios_dir: Path,
+    tests_dir: Path,
+    scenario: Optional[str],
+    tag: Optional[list[str]],
+    guide: bool,
+    no_guide: bool,
+) -> list[str]:
+    """Return the selected scenario slugs for ``(scenario, tag, guide, no_guide)``.
+
+    Order: a single ``scenario`` (verifying its generated test file exists) wins;
+    otherwise parse ``scenarios_dir`` filtered by ``tag`` (``None`` = all), then keep
+    guide-enabled (``guide``) or non-guide (``no_guide``) scenarios. Returns slugs in
+    parse order. Raises :class:`SelectionError` on a missing test file / missing
+    scenarios dir / parse error instead of printing — the caller renders it.
+    """
+    if scenario:
+        test_file = tests_dir / f"test_{scenario}.py"
+        if not test_file.exists():
+            raise SelectionError(
+                f"Test file not found: {test_file}",
+                hint="Run [bold]steppy generate[/bold] first",
+            )
+        return [scenario]
+
+    if not scenarios_dir.exists():
+        raise SelectionError(f"Scenarios directory not found: {scenarios_dir}")
+
+    try:
+        all_scenarios = parse_scenarios_from_directory(scenarios_dir, tag_filter=tag)
+    except ParseError as e:
+        raise SelectionError(f"Parse error: {e}")
+
+    if guide:
+        all_scenarios = [s for s in all_scenarios if s.guide.enabled]
+    elif no_guide:
+        all_scenarios = [s for s in all_scenarios if not s.guide.enabled]
+
+    return [s.slug for s in all_scenarios]
+
+
+def exclusive_groups_for(scenarios_dir: Path, slugs: list[str]) -> dict[str, Optional[str]]:
+    """Map each selected slug to its ``exclusive:`` group, or None.
+
+    Only slugs carrying a group appear in the result; the caller reads it with
+    ``.get(slug)``. Returns ``{}`` when fewer than two scenarios are selected —
+    exclusivity is vacuous then, and it keeps the ``--scenario X`` path from newly
+    parsing the whole directory (where a broken *sibling* file would start failing
+    a run that works today).
+
+    **Fails closed.** A parse failure raises :class:`SelectionError` rather than
+    degrading to ``{}``, unlike its neighbours in ``coordinator`` (which return an
+    empty set on ``ParseError`` and swallow ordering failures wholesale). Those are
+    optimisations; this is a correctness constraint, and silently losing it runs the
+    mutually-exclusive scenarios concurrently with nothing printed — precisely the
+    bug the field exists to prevent. Being strict is cheap: for any selection this
+    matters for, ``select_scenario_slugs`` parsed the same directory successfully
+    moments earlier.
+    """
+    if len(slugs) < 2:
+        return {}
+    if not scenarios_dir.exists():
+        raise SelectionError(f"Scenarios directory not found: {scenarios_dir}")
+
+    try:
+        parsed = parse_scenarios_from_directory(scenarios_dir)
+    except ParseError as e:
+        raise SelectionError(
+            f"Parse error while reading exclusion groups: {e}",
+            hint="Exclusion groups cannot be resolved, and running without them "
+            "would execute mutually-exclusive scenarios concurrently.",
+        )
+
+    selected = set(slugs)
+    return {s.slug: s.exclusive for s in parsed if s.slug in selected and s.exclusive}

steppy/sitemap.py

@@ -0,0 +1,205 @@
+"""``sitemap.xml`` serialisation — the one place the XML is built.
+
+Why this is a module and not a Jinja template, stated honestly, because the
+obvious reason is the weak one:
+
+  * **Escaping** buys less than it looks like it does. Jinja's ``| e`` and
+    ``ElementTree`` behave identically on ``&``, ``<``, ``>`` and ``]]>``, and
+    *both* pass control characters and NUL straight through into a document no
+    parser will accept. The one real bug ET closes is an **attribute** that was
+    interpolated with no filter at all: ``hreflang="{{ alt.hreflang }}"`` in the
+    template this replaces, under an ``autoescape=False`` environment. Here
+    escaping is unconditional rather than dependent on someone remembering a
+    filter, and the characters neither engine can escape are **rejected** (see
+    ``_XML_ILLEGAL``) instead of silently emitted.
+  * The real reasons: a schema-bearing machine format should have a generator
+    rather than a string template that any edit can push out of
+    well-formedness; ``<lastmod>`` and future per-URL extensions become
+    structural instead of textual; and the whole thing becomes a pure function
+    testable with no build, no ``tmp_path`` and no Jinja environment.
+
+A project that wants more than this emits — ``<image:image>`` over a guide's
+screenshots, ``<video:video>``, a ``<sitemapindex>`` split — still overrides
+``templates/static/sitemap.xml.j2`` and wins; see ``_write_static_sitemap``.
+
+Stdlib-only leaf: imports nothing from ``steppy``.
+"""
+
+from __future__ import annotations
+
+import re
+import xml.etree.ElementTree as ET
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Iterable, Optional, Sequence
+
+# ── Errors ───────────────────────────────────────────────────────────────────
+
+
+class SitemapError(ValueError):
+    """Raised when a sitemap cannot be serialised as well-formed XML."""
+
+
+# ── Constants ────────────────────────────────────────────────────────────────
+
+SITEMAP_NS = "http://www.sitemaps.org/schemas/sitemap/0.9"
+XHTML_NS = "http://www.w3.org/1999/xhtml"
+
+# ElementTree cannot produce this line. `encoding="utf-8"` emits single quotes
+# and a lowercase name; `encoding="UTF-8"` suppresses the declaration entirely,
+# because `ElementTree.write` only writes one when the encoding is *not*
+# utf-8/us-ascii/unicode and "UTF-8".lower() is "utf-8". So it is prepended.
+XML_DECLARATION = '<?xml version="1.0" encoding="UTF-8"?>'
+
+# sitemaps.org protocol limits. Exceeding either makes a search engine reject the
+# *whole* file rather than the excess, and nothing about that is visible locally.
+MAX_SITEMAP_URLS = 50_000
+MAX_SITEMAP_BYTES = 50 * 1024 * 1024
+
+# XML 1.0 section 2.2 Char production. Anything outside it has no escaped
+# spelling -- a character reference to it is itself illegal -- so it can only be
+# rejected. Lone surrogates land here too (D800-DFFF is excluded), which is what
+# keeps them from reaching `Path.write_text` as a UnicodeEncodeError far from the
+# value that caused it.
+_XML_ILLEGAL = re.compile(r"[^\x09\x0A\x0D\x20-퟿-�\U00010000-\U0010FFFF]")
+
+# W3C Datetime, as the sitemap protocol cites it, narrowed to the two shapes
+# anyone means. A timezone is mandatory whenever a time is present -- an
+# offset-less "2026-09-14T12:00:00" is not a valid W3C datetime, and it is the
+# trap `datetime.fromisoformat` accepts without complaint. Bare `YYYY` and
+# `YYYY-MM` are deliberately dropped: nobody means them and crawlers handle them
+# poorly.
+_LASTMOD_RE = re.compile(r"^\d{4}-\d{2}-\d{2}(?:T\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:\d{2}))?$")
+
+_LASTMOD_HELP = (
+    "must be a W3C datetime: 'YYYY-MM-DD', or 'YYYY-MM-DDThh:mm:ssZ' / "
+    "'YYYY-MM-DDThh:mm:ss+hh:mm' (a timezone is required when a time is given)"
+)
+
+
+# ── Value types ──────────────────────────────────────────────────────────────
+
+
+@dataclass(frozen=True)
+class Alternate:
+    """One ``<xhtml:link rel="alternate">`` row: a language and its URL."""
+
+    hreflang: str
+    href: str
+
+
+@dataclass(frozen=True)
+class SitemapUrl:
+    """One ``<url>`` entry.
+
+    ``lastmod`` is per-URL from day one even though the config sets a single
+    site-wide value today: the version that earns its keep is a guide stamped
+    with its own scenario's commit date, and leaving the field off would mean
+    rewriting every call site to add it later.
+    """
+
+    loc: str
+    alternates: tuple[Alternate, ...] = ()
+    lastmod: Optional[str] = None
+
+
+# ── Validation ───────────────────────────────────────────────────────────────
+
+
+def _check_xml_text(value: str, field: str) -> str:
+    """Reject text no XML document can carry, naming the field that carried it.
+
+    Rejecting rather than stripping is the point: a control character in a
+    ``loc`` means the URL was built from a bad slug, locale or path, and a
+    silently-stripped one yields a URL that 404s from a sitemap that looks fine.
+    """
+    if not isinstance(value, str):
+        raise SitemapError(f"sitemap {field} must be a string, got {type(value).__name__}")
+    bad = _XML_ILLEGAL.search(value)
+    if bad is not None:
+        raise SitemapError(
+            f"sitemap {field} contains a character XML cannot represent "
+            f"(U+{ord(bad.group()):04X}) and therefore cannot be escaped: {value!r}"
+        )
+    return value
+
+
+def normalize_lastmod(value: object) -> str:
+    """Validate a ``<lastmod>`` value and return it unchanged.
+
+    Shape is checked by regex and *then* by ``datetime.fromisoformat``, because
+    neither is sufficient alone: the regex cannot tell that ``2026-02-31`` is
+    not a day, and ``fromisoformat`` happily accepts ``20260914``,
+    ``2026-W12-1``, a space separator, and a time with no timezone -- none of
+    which are valid W3C datetimes.
+    """
+    if not isinstance(value, str):
+        raise SitemapError(f"lastmod {_LASTMOD_HELP}, got {type(value).__name__}")
+    text = value.strip()
+    if not _LASTMOD_RE.match(text):
+        raise SitemapError(f"lastmod {_LASTMOD_HELP}, got {value!r}")
+    try:
+        datetime.fromisoformat(text.replace("Z", "+00:00"))
+    except ValueError as exc:
+        raise SitemapError(f"lastmod {_LASTMOD_HELP}, got {value!r} ({exc})") from exc
+    return text
+
+
+def limit_warnings(url_count: int, byte_size: int) -> list[str]:
+    """Protocol-limit warnings for a rendered sitemap, most severe first.
+
+    Pure, so the leaf owns the thresholds and the wording while ``build.py``
+    owns the console. Empty when the document is within both limits.
+    """
+    warnings: list[str] = []
+    if url_count > MAX_SITEMAP_URLS:
+        warnings.append(
+            f"sitemap.xml lists {url_count:,} URLs, over the {MAX_SITEMAP_URLS:,}-URL sitemaps.org "
+            "limit — search engines reject the whole file, not the excess. Reduce the built "
+            "surface, or override templates/static/sitemap.xml.j2 to emit a <sitemapindex>."
+        )
+    if byte_size > MAX_SITEMAP_BYTES:
+        warnings.append(
+            f"sitemap.xml is {byte_size / 1024 / 1024:.1f} MB, over the "
+            f"{MAX_SITEMAP_BYTES // 1024 // 1024} MB uncompressed sitemaps.org limit — search "
+            "engines reject the whole file."
+        )
+    return warnings
+
+
+# ── Serialisation ────────────────────────────────────────────────────────────
+
+
+def render_sitemap(urls: Sequence[SitemapUrl] | Iterable[SitemapUrl], *, default_lastmod: Optional[str] = None) -> str:
+    """Serialise ``urls`` as a sitemaps.org 0.9 document.
+
+    Element order inside ``<url>`` is ``<loc>``, the ``xhtml:link`` alternates,
+    then ``<lastmod>`` — the shape Google's own hreflang example uses, and the
+    layout the Jinja template this replaces produced.
+    """
+    # Namespaces go in as ordinary attributes and the tags carry literal
+    # prefixes, rather than building a namespace-aware tree. Two reasons, both
+    # dead ends otherwise: `tostring(default_namespace=...)` raises outright
+    # ("cannot use non-qualified names with default_namespace option") because
+    # rel/hreflang/href are un-namespaced attributes; and `register_namespace`
+    # mutates `ET._namespace_map` process-wide and permanently, which would make
+    # any later XML-serialising test in the same pytest session order-dependent.
+    # The output is byte-identical to the registered form. The tree is therefore
+    # not namespace-aware, but it never leaves this function.
+    root = ET.Element("urlset", {"xmlns": SITEMAP_NS, "xmlns:xhtml": XHTML_NS})
+    count = 0
+    for entry in urls:
+        count += 1
+        url_el = ET.SubElement(root, "url")
+        ET.SubElement(url_el, "loc").text = _check_xml_text(entry.loc, "loc")
+        for alt in entry.alternates:
+            link = ET.SubElement(url_el, "xhtml:link")
+            link.set("rel", "alternate")
+            link.set("hreflang", _check_xml_text(alt.hreflang, "hreflang"))
+            link.set("href", _check_xml_text(alt.href, "href"))
+        lastmod = entry.lastmod if entry.lastmod is not None else default_lastmod
+        if lastmod is not None:
+            ET.SubElement(url_el, "lastmod").text = _check_xml_text(lastmod, "lastmod")
+
+    ET.indent(root, space="  ")
+    return f"{XML_DECLARATION}\n{ET.tostring(root, encoding='unicode')}\n"