steppy-dev 0.3.0__py3-none-any.whl

steppy/tours/model.py

@@ -0,0 +1,120 @@
+"""The compiled intermediate representation and the replay hand-off.
+
+Pure data: frozen dataclasses with no behaviour beyond small lookups, so the
+inference, text, emission and replay layers can be tested in isolation.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Literal, Optional
+
+Disposition = Literal["setup", "tour", "run", "drop"]
+
+
+@dataclass
+class TourStepPlan:
+    """One step of a tour, before text resolution. ``step_id`` is set by ``ids``."""
+
+    step_index: int  # index into scenario.steps
+    step_number: int
+    step_title: str
+    action: str
+    target: Optional[str]  # test-id value, or None for a centred step
+    source_selector: Optional[str]  # authored selector CI acts on (None when centred)
+    advance: str
+    wait_for: Optional[str] = None
+    placement: Optional[str] = None
+    layouts: Optional[tuple[str, ...]] = None
+    field: Optional[str] = None  # fill-form: the `fields` key this sub-step fills
+    step_id: str = ""
+
+
+@dataclass(frozen=True)
+class ReplayTourStep:
+    """A tour step as the replay test sees it."""
+
+    step_id: str
+    index: int  # 0-based position in the tour (identical in every locale)
+    target: Optional[str]
+    wait_for: Optional[str]
+    advance: str
+    layouts: Optional[tuple[str, ...]]
+    field: Optional[str] = None
+    source_selector: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class ReplayEntry:
+    """What the replay does with one scenario step (aligned 1:1 with scenario.steps)."""
+
+    step_number: int
+    disposition: Disposition
+    reason: str
+    tour_steps: tuple[ReplayTourStep, ...] = ()
+    reloads_page: bool = False
+
+
+@dataclass(frozen=True)
+class ReplayPlan:
+    """Everything the replay renderer needs; produced by the compiler."""
+
+    scenario_slug: str
+    tour_id: str
+    role: str
+    auth: bool
+    default_locale: str
+    locales: tuple[str, ...]
+    entry_route: Optional[str]
+    entry_params: tuple[tuple[str, str], ...]  # (param, _interp template) in route order
+    entry_step_number: Optional[int]
+    start_index: int
+    entries: tuple[ReplayEntry, ...]
+    tour_step_count: int
+    layouts: tuple[tuple[str, str], ...] = ()  # (layout, media query) for layouts kept steps use
+    test_id_attribute: str = "data-testid"
+
+    def entry_for(self, step_number: int) -> ReplayEntry:
+        for entry in self.entries:
+            if entry.step_number == step_number:
+                return entry
+        raise KeyError(step_number)
+
+
+@dataclass
+class ScenarioInference:
+    """The locale-independent result of inferring one scenario."""
+
+    role: str
+    entry_route: Optional[str]
+    entry_params: tuple[tuple[str, str], ...]
+    entry_step_index: Optional[int]
+    start_index: int
+    steps: list[TourStepPlan]
+    entries: list[ReplayEntry] = field(default_factory=list)
+
+
+@dataclass
+class CompiledTour:
+    """One tour, ready to serialize: inference + per-locale text."""
+
+    id: str
+    scenario_slug: str
+    role: str
+    entry_route: Optional[str]
+    steps: list[TourStepPlan]
+    locales: tuple[str, ...]  # emitted locales, in config order
+    titles: dict[str, str]  # locale -> tour title
+    step_texts: dict[str, list[tuple[Optional[str], Optional[str]]]]  # locale -> [(title, text)] per step
+    guide_urls: dict[str, str]  # locale -> guideUrl (absent when no guide link)
+
+
+@dataclass
+class TourCompileResult:
+    tours: list[CompiledTour]
+    replay_plans: dict[str, ReplayPlan]
+    diagnostics: list  # list[Diagnostic]
+
+    @property
+    def has_errors(self) -> bool:
+        return any(d.severity == "error" for d in self.diagnostics)

steppy/tours/paths.py

@@ -0,0 +1,126 @@
+"""Filesystem guards for tour output: where we may write, and what we may delete.
+
+Tour files land in two kinds of place: the canonical tree under
+``output.tours_dir`` and app-assets directories inside *someone else's*
+repository. Pruning stale files there is only safe when the directory is
+provably ours, so the rules are strict:
+
+* a directory is ours only when its ``tours.manifest.json`` carries our
+  ``kind`` marker — a foreign or unreadable manifest stops everything;
+* only files that previous manifest *listed* (and that look like tour file
+  names) are ever deleted — never a glob — and an existing file is only ever
+  overwritten or deleted when it is itself a tour file (its JSON ``kind``);
+* no target may be, contain, or sit inside the project root, the scenarios,
+  the generated tests, the captures, or another target.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import tempfile
+from pathlib import Path
+from typing import Iterable, Optional
+
+from ..naming import TOUR_FILE_KIND, TOURS_MANIFEST_FILENAME, TOURS_MANIFEST_KIND
+from ..tour_spec import TOUR_FILE_NAME_PATTERN
+
+#: Names that betray a project or package root — never write into a directory holding one.
+GUARDED_NAMES = ("config.yaml", "pyproject.toml", ".git", "scenarios", "src", "package.json", "angular.json")
+
+
+class TourPathError(ValueError):
+    """A tour target or prune would touch a path it must not."""
+
+
+def _resolved(path: Path) -> Path:
+    return Path(os.path.abspath(path))
+
+
+def overlaps(a: Path, b: Path) -> bool:
+    """True when ``a`` and ``b`` are the same path or one contains the other."""
+    a, b = _resolved(a), _resolved(b)
+    return a == b or a in b.parents or b in a.parents
+
+
+def check_emit_dir(path: Path, *, project_root: Path, owned_roots: Iterable[Path], label: str) -> None:
+    """Refuse a write target that could clobber something that is not ours."""
+    target = _resolved(path)
+    root = _resolved(project_root)
+    if target == Path(target.anchor):
+        raise TourPathError(f"{label} {path} is a filesystem root")
+    if target == root or target in root.parents:
+        raise TourPathError(f"{label} {path} is the project root or one of its parents")
+    for owned in owned_roots:
+        if overlaps(target, owned):
+            raise TourPathError(f"{label} {path} overlaps {owned}, which Steppy owns for something else")
+    if target.is_dir():
+        clash = [name for name in GUARDED_NAMES if (target / name).exists()]
+        if clash:
+            raise TourPathError(
+                f"{label} {path} contains {', '.join(clash)} — it looks like a project directory, not a tours folder"
+            )
+
+
+def read_marker(directory: Path) -> Optional[dict]:
+    """The previous manifest if ``directory`` is ours, None if it has none; raise if foreign."""
+    manifest = directory / TOURS_MANIFEST_FILENAME
+    if not manifest.exists():
+        return None
+    try:
+        data = json.loads(manifest.read_bytes().decode("utf-8"))
+    except (ValueError, UnicodeDecodeError, OSError) as exc:
+        raise TourPathError(f"{manifest} is not readable JSON ({exc}); refusing to touch {directory}") from exc
+    if not isinstance(data, dict) or data.get("kind") != TOURS_MANIFEST_KIND:
+        raise TourPathError(
+            f"{manifest} is not a Steppy tours manifest; refusing to touch {directory} — delete it manually"
+        )
+    return data
+
+
+def listed_files(manifest: Optional[dict]) -> set[str]:
+    """Tour file names a (marker-checked) manifest lists; anything path-like is ignored."""
+    if not manifest:
+        return set()
+    names: set[str] = set()
+    for tour in manifest.get("tours") or []:
+        if not isinstance(tour, dict):
+            continue
+        for name in (tour.get("files") or {}).values():
+            if isinstance(name, str) and re.fullmatch(TOUR_FILE_NAME_PATTERN, name):
+                names.add(name)
+    return names
+
+
+def is_tour_file(path: Path) -> bool:
+    """True when ``path`` is a JSON file carrying the tour-file ``kind`` marker."""
+    try:
+        data = json.loads(path.read_bytes().decode("utf-8"))
+    except (ValueError, UnicodeDecodeError, OSError):
+        return False
+    return isinstance(data, dict) and data.get("kind") == TOUR_FILE_KIND
+
+
+def check_tour_file(path: Path, verb: str) -> None:
+    """Refuse to ``verb`` (overwrite/delete) a file that is not a Steppy tour file."""
+    if not is_tour_file(path):
+        raise TourPathError(
+            f"{path} is not a Steppy tour file; refusing to {verb} it — move it away or delete it manually"
+        )
+
+
+def atomic_write_bytes(path: Path, data: bytes) -> None:
+    """Write ``data`` to ``path`` via a sibling temp file + ``os.replace``."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp = tempfile.mkstemp(dir=path.parent, prefix=f".{path.name}.", suffix=".tmp")
+    try:
+        with os.fdopen(fd, "wb") as handle:
+            handle.write(data)
+        os.replace(tmp, path)
+    except BaseException:
+        try:
+            os.unlink(tmp)
+        except OSError:
+            pass
+        raise

steppy/tours/pipeline.py

@@ -0,0 +1,277 @@
+"""The entry point ``steppy generate`` and ``steppy tours`` share.
+
+:func:`prepare_tours` does everything that can fail — parsing, compiling,
+resolving the build id, serializing, self-checking, guarding every target and
+reading every marker — **before** anything is written, so a refusal never
+leaves half an output behind. :meth:`TourPipeline.emit` then writes.
+
+Tours are always compiled from **every** scenario in the directory, even when
+``generate`` was asked for one file or a tag: a manifest must never depend on
+CLI arguments.
+
+``mode="check"`` (``steppy tours --check``) plans only the app-assets
+targets — the copies an app commits — and compares their *content* for the
+build id each one records: the canonical tree is a gitignored build output, and
+committed files always carry an older id under ``git-sha`` or a CI-stamped id.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Literal, Optional
+
+from ..buildid import BuildIdError, is_build_id, resolve_build_id
+from ..captures import DEFAULT_GUIDES_DIR, DEFAULT_SCREENSHOTS_DIR, resolve_output_dir
+from ..contracts.tours import TourDataInvalid
+from ..models import SteppyConfig, Scenario
+from ..naming import TOURS_MANIFEST_FILENAME
+from ..parser import ParseError, parse_scenario_file, validate_scenario_layouts, validate_scenario_roles
+from .compiler import compile_tours, opted_in
+from .diagnostics import Diagnostic, sort_diagnostics
+from .emit import (
+    DirPlan,
+    FileStatus,
+    TourArtifacts,
+    apply_dir,
+    plan_dir,
+    remove_build_dir,
+    render_artifacts,
+    sibling_build_dirs,
+)
+from .model import ReplayPlan, TourCompileResult
+from .paths import TourPathError, check_emit_dir, read_marker
+from .settings import ToursSettings, settings_diagnostics
+
+Mode = Literal["generate", "tours", "validate", "check"]
+
+
+@dataclass
+class TourPipeline:
+    settings: ToursSettings
+    diagnostics: list[Diagnostic] = field(default_factory=list)
+    result: Optional[TourCompileResult] = None
+    build_id: Optional[str] = None
+    artifacts: Optional[TourArtifacts] = None
+    plans: list[DirPlan] = field(default_factory=list)
+    stale_builds: list[Path] = field(default_factory=list)
+    replay_plans: dict[str, ReplayPlan] = field(default_factory=dict)
+    #: ``check`` mode: app-assets dir → the build id its manifest records (None: no tour files there).
+    checked: dict[Path, Optional[str]] = field(default_factory=dict)
+    #: ``check`` mode: why the configured build id could not be resolved here, if it could not.
+    build_id_error: Optional[str] = None
+
+    @property
+    def has_errors(self) -> bool:
+        return any(d.severity == "error" for d in self.diagnostics)
+
+    def statuses(self) -> dict[str, str]:
+        out: dict[str, str] = {}
+        for plan in self.plans:
+            for status in plan.statuses:
+                out[str(status.path)] = status.status
+        for directory in self.stale_builds:
+            out[str(directory)] = "removed"
+        return out
+
+    def emit(self, dry_run: bool = False) -> dict[str, str]:
+        """Write every planned file (unless ``dry_run``); return path → status."""
+        statuses = self.statuses()
+        if dry_run or self.has_errors:
+            return statuses
+        for plan in self.plans:
+            apply_dir(plan)
+        for directory in self.stale_builds:
+            remove_build_dir(directory)
+        return statuses
+
+
+def _err(code: str, message: str, scenario: Optional[str] = None) -> Diagnostic:
+    return Diagnostic("error", code, message, scenario=scenario)
+
+
+def _read_dir(scenarios_dir: Path, diagnostics: list[Diagnostic]) -> list[Scenario]:
+    out = []
+    for path in sorted(scenarios_dir.glob("*.md")):
+        try:
+            out.append(parse_scenario_file(path))
+        except ParseError as exc:
+            first = str(exc).splitlines()[0] if str(exc) else repr(exc)
+            diagnostics.append(
+                _err(
+                    "scenario-unreadable",
+                    f"{path.name} does not parse ({first}); in-app tours are compiled from every scenario, "
+                    "so the tour set would be incomplete",
+                )
+            )
+    return out
+
+
+def prepare_tours(
+    config: SteppyConfig,
+    *,
+    project_root: Path,
+    scenarios_dir: Path,
+    selected: Optional[list[Scenario]] = None,
+    all_scenarios: Optional[list[Scenario]] = None,
+    build_id_override: Optional[str] = None,
+    mode: Mode = "generate",
+) -> TourPipeline:
+    root = Path(project_root).resolve()
+    settings = ToursSettings.from_config(config, root)
+    pipeline = TourPipeline(settings=settings)
+    diags = pipeline.diagnostics
+    diags.extend(settings_diagnostics(config, settings))
+
+    scenarios = all_scenarios if all_scenarios is not None else _read_dir(scenarios_dir, diags)
+    by_slug = {s.slug: s for s in scenarios}
+
+    resolved_dir = scenarios_dir.resolve()
+    selected_slugs = None
+    if selected is not None:
+        selected_slugs = {s.slug for s in selected}
+        for s in opted_in(selected, settings):
+            path = Path(s.file_path).resolve() if s.file_path else None
+            if path is None or path.parent != resolved_dir:
+                diags.append(
+                    _err(
+                        "scenario-unreadable",
+                        f"{s.slug} opts into tours but is not in {scenarios_dir}; tours are compiled from that "
+                        "directory, so run the command with --scenarios-dir pointing at it",
+                        scenario=s.slug,
+                    )
+                )
+            by_slug.setdefault(s.slug, s)
+
+    roles, layouts = set(config.apps), set(config.screenshot.layouts)
+    for s in opted_in(list(by_slug.values()), settings):
+        if selected_slugs is not None and s.slug in selected_slugs:
+            continue  # the caller already validated the selection
+        for problem in validate_scenario_roles(s, roles) + validate_scenario_layouts(s, layouts):
+            diags.append(_err("scenario-unreadable", f"{problem}", scenario=s.slug))
+
+    result = compile_tours(list(by_slug.values()), settings)
+    pipeline.result = result
+    diags.extend(result.diagnostics)
+    if not result.tours and not result.has_errors:
+        diags.append(
+            Diagnostic(
+                "warning",
+                "no-tours",
+                "tours are enabled but no scenario opts in (`tour: true`); an empty manifest is written",
+            )
+        )
+    if settings.replay:
+        pipeline.replay_plans = {
+            slug: plan for slug, plan in result.replay_plans.items() if selected_slugs is None or slug in selected_slugs
+        }
+    if pipeline.has_errors or mode == "validate":
+        pipeline.diagnostics[:] = sort_diagnostics(diags)
+        return pipeline
+
+    owned = [
+        resolve_output_dir(root, config.output.screenshots_dir, DEFAULT_SCREENSHOTS_DIR),
+        resolve_output_dir(root, config.output.guides_dir, DEFAULT_GUIDES_DIR),
+        resolved_dir,
+        root / "tests",
+        root / ".steppy",
+        root / ".auth",
+        root / ".git",
+    ]
+
+    try:
+        pipeline.build_id = resolve_build_id(settings.build_id_raw, root, override=build_id_override)
+    except BuildIdError as exc:
+        if mode == "check":
+            pipeline.build_id_error = str(exc)  # only shown in a note: check compares recorded ids
+        else:
+            diags.append(_err("build-id", str(exc)))
+            pipeline.diagnostics[:] = sort_diagnostics(diags)
+            return pipeline
+
+    if mode == "check":
+        _prepare_check(pipeline, result, root, owned)
+        pipeline.diagnostics[:] = sort_diagnostics(diags)
+        return pipeline
+
+    try:
+        pipeline.artifacts = render_artifacts(result, settings, pipeline.build_id)
+    except TourDataInvalid as exc:
+        diags.append(_err("limit-exceeded", str(exc)))
+        pipeline.diagnostics[:] = sort_diagnostics(diags)
+        return pipeline
+
+    try:
+        check_emit_dir(
+            settings.tours_root,
+            project_root=root,
+            owned_roots=[*owned, *settings.app_assets_dirs],
+            label="output.tours_dir",
+        )
+        canonical = settings.tours_root / pipeline.build_id
+        pipeline.plans.append(plan_dir(canonical, pipeline.artifacts))
+        pipeline.stale_builds = sibling_build_dirs(settings.tours_root, pipeline.build_id)
+        for directory in settings.app_assets_dirs:
+            others = [d for d in settings.app_assets_dirs if d != directory]
+            check_emit_dir(
+                directory,
+                project_root=root,
+                owned_roots=[*owned, settings.tours_root, *others],
+                label="tours app-assets target",
+            )
+            if not directory.parent.is_dir():
+                message = f"the app-assets target {directory} has no parent directory (is the app checked out?)"
+                if mode == "generate":
+                    diags.append(Diagnostic("warning", "app-assets-skipped", message + "; skipped"))
+                    continue
+                diags.append(_err("target-path", message))
+                continue
+            pipeline.plans.append(plan_dir(directory, pipeline.artifacts))
+    except TourPathError as exc:
+        diags.append(_err("target-path", str(exc)))
+    pipeline.diagnostics[:] = sort_diagnostics(diags)
+    return pipeline
+
+
+def _prepare_check(pipeline: TourPipeline, result: TourCompileResult, root: Path, owned: list[Path]) -> None:
+    """Plan the app-assets targets only, each against the build id its own manifest records."""
+    settings = pipeline.settings
+    diags = pipeline.diagnostics
+    rendered: dict[str, TourArtifacts] = {}
+    for directory in settings.app_assets_dirs:
+        manifest_path = directory / TOURS_MANIFEST_FILENAME
+        try:
+            others = [d for d in settings.app_assets_dirs if d != directory]
+            check_emit_dir(
+                directory,
+                project_root=root,
+                owned_roots=[*owned, settings.tours_root, *others],
+                label="tours app-assets target",
+            )
+            if not directory.parent.is_dir():
+                diags.append(
+                    _err(
+                        "target-path",
+                        f"the app-assets target {directory} has no parent directory (is the app checked out?)",
+                    )
+                )
+                continue
+            previous = read_marker(directory) if directory.is_dir() else None
+            if previous is None:
+                pipeline.checked[directory] = None
+                pipeline.plans.append(DirPlan(directory=directory, statuses=[FileStatus(manifest_path, "missing")]))
+                continue
+            recorded = previous.get("buildId")
+            if not is_build_id(recorded):
+                diags.append(
+                    _err("build-id", f"{manifest_path} records the build id {recorded!r}, which is not a valid one")
+                )
+                continue
+            pipeline.checked[directory] = recorded
+            if recorded not in rendered:
+                rendered[recorded] = render_artifacts(result, settings, recorded)
+            pipeline.plans.append(plan_dir(directory, rendered[recorded]))
+        except TourDataInvalid as exc:
+            diags.append(_err("limit-exceeded", str(exc)))
+        except TourPathError as exc:
+            diags.append(_err("target-path", str(exc)))

steppy/tours/publish.py

@@ -0,0 +1,124 @@
+"""The ``steppy build`` side of in-app tours: the ``guide`` target.
+
+``steppy generate`` / ``steppy tours`` write the canonical tree
+(``output/tours/<build-id>/``); a static guide build republishes it byte for
+byte at ``<site>/tours/<build-id>/``, where an app in remote mode fetches it.
+``build`` never compiles tours itself — it needs no scenario parsing for this,
+and a guide site must serve exactly the bytes whose hashes the apps bundle.
+
+Everything here runs **before** the build wipes its output directory: a tree
+that is missing, stale (a file whose SRI no longer matches) or edited fails the
+build while the previous site is still intact.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterable, Optional
+
+from ..buildid import BuildIdError, resolve_build_id
+from ..contracts.tours import TourDataInvalid, TourSchemaUnsupported, check_consistency, parse_tours_manifest
+from ..naming import GUIDE_SITE_TOURS_DIR, TOURS_MANIFEST_FILENAME
+from .paths import TourPathError, overlaps, read_marker
+from .settings import ToursSettings
+
+
+class TourPublishError(ValueError):
+    """The guide target cannot be published as configured; the build must not wipe anything."""
+
+
+@dataclass(frozen=True)
+class GuidePublishPlan:
+    build_id: str
+    #: (file name, bytes): tour files first, the manifest last.
+    files: tuple[tuple[str, bytes], ...]
+    tour_ids: tuple[str, ...]
+    warnings: tuple[str, ...] = ()
+
+    @property
+    def site_dir(self) -> str:
+        """The site-relative directory the tree is published under."""
+        return f"{GUIDE_SITE_TOURS_DIR}/{self.build_id}"
+
+
+def check_build_overlaps(settings: ToursSettings, output_dir: Path, assets_dir: Path) -> None:
+    """The build rmtrees ``output_dir`` and ``assets_dir``: no tour directory may live there."""
+    tour_dirs = [("output.tours_dir", settings.tours_root)]
+    tour_dirs += [("an app-assets target", d) for d in settings.app_assets_dirs]
+    for label, tour_dir in tour_dirs:
+        for build_label, build_dir in (("outputDir", output_dir), ("assetsDir", assets_dir)):
+            if overlaps(tour_dir, build_dir):
+                raise TourPublishError(
+                    f"tours: {label} ({tour_dir}) overlaps the build's {build_label} ({build_dir}), which "
+                    "`steppy build` deletes before writing — move one of them"
+                )
+
+
+def plan_guide_publish(
+    settings: ToursSettings,
+    *,
+    guide_slugs: Iterable[str],
+    build_locales: Iterable[str],
+) -> GuidePublishPlan:
+    """Read and verify the canonical tree for the configured build id."""
+    try:
+        build_id = resolve_build_id(settings.build_id_raw, settings.project_root)
+    except BuildIdError as exc:
+        raise TourPublishError(f"tours: {exc}") from exc
+    tree = settings.tours_root / build_id
+    manifest_path = tree / TOURS_MANIFEST_FILENAME
+    if not manifest_path.is_file():
+        raise TourPublishError(
+            f"In-app tours for build {build_id} not found at {tree}. Run `steppy generate` or "
+            "`steppy tours` first (with the same tours.build_id)."
+        )
+    try:
+        read_marker(tree)
+        raw = manifest_path.read_bytes()
+        manifest = parse_tours_manifest(json.loads(raw.decode("utf-8")))
+    except (TourPathError, TourDataInvalid, TourSchemaUnsupported, ValueError) as exc:
+        raise TourPublishError(f"tours: {manifest_path} is not a valid tours manifest: {exc}") from exc
+    if manifest.buildId != build_id:
+        raise TourPublishError(f"tours: {manifest_path} is for build {manifest.buildId!r}, expected {build_id!r}")
+
+    names = sorted({name for tour in manifest.tours for name in tour.files.values()})
+    files = {name: (tree / name).read_bytes() for name in names if (tree / name).is_file()}
+    problems = check_consistency(manifest, files)
+    if problems:
+        raise TourPublishError(
+            f"tours: the tree at {tree} is stale or was edited ({problems[0]}); re-run `steppy tours`"
+        )
+
+    warnings = list(_guide_link_warnings(settings, manifest, files, set(guide_slugs), set(build_locales)))
+    return GuidePublishPlan(
+        build_id=build_id,
+        files=(*((name, files[name]) for name in names), (TOURS_MANIFEST_FILENAME, raw)),
+        tour_ids=tuple(tour.id for tour in manifest.tours),
+        warnings=tuple(warnings),
+    )
+
+
+def _guide_link_warnings(
+    settings: ToursSettings,
+    manifest,
+    files: dict[str, bytes],
+    guide_slugs: set[str],
+    build_locales: set[str],
+) -> Iterable[str]:
+    """A tour's "open the full guide" link that this build will not satisfy."""
+    base = (settings.guide_base_url or "").rstrip("/") + "/"
+    seen: set[str] = set()
+    for tour in manifest.tours:
+        for name in tour.files.values():
+            url: Optional[str] = json.loads(files[name].decode("utf-8")).get("guideUrl")
+            if not url or not url.startswith(base) or url in seen:
+                continue
+            seen.add(url)
+            slug, _, page = url[len(base) :].partition("/")
+            locale = page.removesuffix(".html")
+            if slug not in guide_slugs:
+                yield f"tours: tour {tour.id!r} links to guide {slug!r}, which this build does not publish ({url})"
+            elif locale not in build_locales:
+                yield f"tours: tour {tour.id!r} links to the {locale!r} page of {slug!r}, which this build has no locale for"