steppy-dev 0.3.0__py3-none-any.whl

steppy/tours/actions.py

@@ -0,0 +1,402 @@
+"""How each scenario action becomes (or does not become) a tour step.
+
+``ACTION_TOUR_KIND`` classifies **every** action in ``models.VALID_ACTIONS``;
+``tests/test_tour_action_table.py`` fails when a new action is added without a
+row here — a missing row would silently drop that step from every tour.
+
+Kinds:
+
+``click`` / ``change`` / ``input``  the user acts on one target; the tour points
+                                    at it and advances on that kind of event
+``fill-form``                       one ``input`` sub-step per field
+``upload``                          a file input, usually hidden behind a trigger
+``check``                           an assertion / wait: a hidden gate, or an info
+                                    step when it carries text
+``cursor``                          ``custom`` / ``call``: only a ``guide-cursor``
+                                    says what the user does
+``unguided``                        the user must act but there is no test-id to
+                                    point at (confirm dialogs)
+``navigation``                      changes the page; never part of a tour
+``skip``                            setup, waits, hovers, key presses
+"""
+
+from __future__ import annotations
+
+import keyword
+import re
+from dataclasses import dataclass, field
+from typing import Literal, Optional
+
+from ..assertions import AssertionSyntaxError, parse_assertion
+from ..models import Step, expect_checks
+from ..testids import TargetExtraction, extract_test_id
+
+ACTION_TOUR_KIND: dict[str, str] = {
+    "click": "click",
+    "expand": "click",
+    "toggle": "change",
+    "select": "change",
+    "select-option": "change",
+    "pick-date": "change",
+    "pick-time": "change",
+    "fill": "input",
+    "fill-date": "input",
+    "fill-form": "fill-form",
+    "upload": "upload",
+    "assert": "check",
+    "wait-for": "check",
+    "custom": "cursor",
+    "call": "cursor",
+    "confirm": "unguided",
+    "navigate": "navigation",
+    "login": "navigation",
+    "hover": "skip",
+    "scroll": "skip",
+    "keyboard": "skip",
+    "wait": "skip",
+    "wait-for-text": "skip",
+    "capture": "skip",
+}
+
+#: Assertion forms that imply "this element is on screen" — the only ones that
+#: can gate a step. ``hidden``/``not-visible``/``stays-hidden``/``count 0`` say
+#: the opposite; ``toast``/``row-contains``/``url-contains`` have no target.
+POSITIVE_FORMS = frozenset({"visible", "text", "contains", "icontains", "not-empty"})
+
+#: ``custom`` code that acts on the page: skipping it inside a tour leaves the
+#: user with an action nobody told them to do.
+INTERACTIVE_CODE_RE = re.compile(
+    r"\.(?:click|dblclick|fill|type|press|press_sequentially|check|uncheck|select_option|set_input_files"
+    r"|dispatch_event)\(|dispatchEvent\("
+)
+
+#: Actions that leave the page as they found it. A gate (a hidden check) still
+#: holds after one of them runs unshown inside a tour; after any other — a
+#: skipped click or fill, a confirm, a key press, a navigate — the element it
+#: waited for may be gone. An action added later counts as page-changing until
+#: it is listed here, which is the safe side: a dropped gate only lets the next
+#: step show sooner, a stale one keeps it from ever showing.
+PAGE_NEUTRAL_ACTIONS = frozenset({"assert", "wait-for", "wait", "wait-for-text", "hover", "scroll", "capture"})
+
+#: Calls ``custom`` code can make and still leave the page alone. Code calling
+#: anything else — ``click``, ``goto``, ``evaluate``, a project helper — may
+#: change it. An allowlist on purpose: on the consumer corpora, a denylist
+#: (``INTERACTIVE_CODE_RE`` plus the navigations) missed form values set
+#: through ``evaluate`` and clicks inside helpers.
+_READ_ONLY_CALLS = frozenset(
+    (
+        # Playwright: locating, reading, waiting, asserting; the ``to_*`` / ``not_to_*`` matchers and the
+        # ``expect_*`` waiters (whose ``with`` block holds the call that acts) are matched by prefix
+        "locator get_by_role get_by_text get_by_label get_by_placeholder get_by_alt_text get_by_title "
+        "get_by_test_id frame_locator filter nth and_ or_ all count is_visible is_hidden is_enabled is_disabled "
+        "is_checked is_editable text_content inner_text inner_html input_value get_attribute all_text_contents "
+        "all_inner_texts bounding_box title wait_for wait_for_timeout wait_for_selector wait_for_load_state "
+        "wait_for_url wait_for_function expect "
+        # The page-neutral actions above, written as code
+        "hover scroll_into_view_if_needed "
+        # Python builtins, and the list / str / re / datetime / time calls code uses to compute values
+        "print len str int float bool list dict set tuple range sorted min max any abs round enumerate zip "
+        "isinstance globals insert append extend strip lower upper split join replace format startswith endswith "
+        "removeprefix removesuffix isdigit get keys items values compile sub search match fullmatch findall group "
+        "now today date datetime timedelta weekday strftime isoformat time monotonic sleep"
+    ).split()
+)
+_READ_ONLY_PREFIXES = ("to_", "not_to_", "expect_")
+
+_STRING_RE = re.compile(r"'''.*?'''|\"\"\".*?\"\"\"|'(?:[^'\\\n]|\\.)*'|\"(?:[^\"\\\n]|\\.)*\"", re.S)
+_COMMENT_RE = re.compile(r"#[^\n]*")
+_CALL_RE = re.compile(r"\b([A-Za-z_]\w*)\s*\(")
+
+#: Advance kinds the scenario's own action can satisfy in the replay. A
+#: ``tour-advance`` outside this set would make the replay wait forever.
+_REPLAYABLE = {
+    "click": frozenset({"click", "manual", "visible"}),
+    "input": frozenset({"input", "change", "manual"}),
+    "change": frozenset({"change", "click", "manual"}),
+    "upload": frozenset({"change", "manual"}),
+    "info": frozenset({"manual", "visible"}),
+}
+
+
+@dataclass
+class Sub:
+    """One target of a kept candidate (fill-form has several)."""
+
+    extraction: Optional[TargetExtraction]
+    selector: Optional[str]
+    field: Optional[str] = None
+
+
+@dataclass
+class Candidate:
+    kind: Literal["kept", "gate", "skip"]
+    reason: str = ""
+    advance: Optional[str] = None
+    subs: list[Sub] = field(default_factory=list)
+    #: A failed/absent target is acceptable (centred step) — info steps, text-only custom.
+    centred_ok: bool = False
+    gate: Optional[str] = None
+    #: Which replayable-advance family the step belongs to (see ``_REPLAYABLE``).
+    family: str = "info"
+    reloads_page: bool = False
+    #: Deferred notes: emitted only if the step is not explicitly ``tour: skip``-ped.
+    notes: list[tuple[str, str, Optional[str]]] = field(default_factory=list)
+    trailing_gates: list[str] = field(default_factory=list)
+
+
+def has_text(step: Step) -> bool:
+    for text in (step.tour_text, step.guide_text):
+        if text is None:
+            continue
+        values = [getattr(text, n) for n in ("fr", "en", "nl", "de")] + list((text.model_extra or {}).values())
+        if any(v is not None for v in values):
+            return True
+    return False
+
+
+def _extract(step: Step, selector: Optional[str], attr: str, *, scoped: bool = True) -> TargetExtraction:
+    if scoped:
+        return extract_test_id(selector, attr, within=step.within, match=step.match)
+    return extract_test_id(selector, attr)
+
+
+def _checks(step: Step, attr: str, *, scoped: bool) -> list[tuple[Optional[str], Optional[str], bool]]:
+    """``(test-id, selector, positive)`` per assertion of the step."""
+    out = []
+    for check in expect_checks(step.expect):
+        try:
+            parsed = parse_assertion(check)
+        except AssertionSyntaxError:
+            continue
+        selector = parsed.get("selector")
+        if selector is None:
+            continue
+        kind = parsed["type"]
+        positive = kind in POSITIVE_FORMS
+        if kind == "count":
+            positive = _int(parsed.get("count")) >= 1
+        elif kind == "count-cmp":
+            n, cmp = _int(parsed.get("count")), parsed.get("comparator")
+            positive = (cmp in (">=", "==") and n >= 1) or (cmp == ">" and n >= 0)
+        ext = _extract(step, selector, attr, scoped=scoped)
+        out.append((ext.test_id, selector, positive))
+    return out
+
+
+def _int(value) -> int:
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return 0
+
+
+def trailing_gates(step: Step, attr: str) -> list[str]:
+    """Positive, extractable ``expect:`` checks riding on a non-assert action.
+
+    Extracted **without** ``within``/``match``: the trailing expect uses a plain
+    locator in the generated test, whatever scopes the action itself.
+    """
+    if step.action in ("assert", "wait-for"):
+        return []
+    return [tid for tid, _sel, positive in _checks(step, attr, scoped=False) if positive and tid]
+
+
+def natural_target(step: Step, attr: str) -> tuple[Optional[TargetExtraction], Optional[str]]:
+    """The element a step is "about", for ``tour: keep`` on a skipped step."""
+    if step.selector:
+        return _extract(step, step.selector, attr), step.selector
+    if step.guide_cursor is not None:
+        return extract_test_id(step.guide_cursor.target, attr), step.guide_cursor.target
+    for tid, selector, _positive in _checks(step, attr, scoped=True):
+        return (extract_test_id(selector, attr, within=step.within, match=step.match), selector)
+    if step.fields:
+        key = next(iter(step.fields))
+        return extract_test_id(key, attr), key
+    return None, None
+
+
+def infer_candidate(step: Step, attr: str) -> Candidate:
+    """What inference alone makes of ``step`` (annotations are applied later)."""
+    action = step.action
+    kind = ACTION_TOUR_KIND[action]
+    gates = trailing_gates(step, attr)
+
+    if step.when or step.optional:
+        return Candidate("skip", reason="conditional", trailing_gates=gates)
+
+    if kind in ("click", "change", "input"):
+        cand = Candidate("kept", advance=kind, family=kind, trailing_gates=gates)
+        cand.subs.append(Sub(_extract(step, step.selector, attr), step.selector))
+        if action == "expand":
+            cand.notes.append(
+                (
+                    "may-not-change",
+                    "an `expand` step only clicks when the section is closed, so its click may never happen",
+                    "use `tour-advance: manual`, or `tour: skip`",
+                )
+            )
+        if action == "toggle" and step.state:
+            cand.notes.append(
+                (
+                    "may-not-change",
+                    "a `toggle` with `state:` does nothing when the switch is already in that state",
+                    "use `tour-advance: manual`, or `tour: skip`",
+                )
+            )
+        return cand
+
+    if kind == "fill-form":
+        if not step.fields:
+            return Candidate("skip", reason="fill-form-empty", trailing_gates=gates)
+        cand = Candidate("kept", advance="input", family="input", trailing_gates=gates)
+        for key in step.fields:
+            cand.subs.append(Sub(extract_test_id(key, attr), key, field=key))
+        return cand
+
+    if kind == "upload":
+        if step.guide_cursor is not None:
+            target = step.guide_cursor.target
+            cand = Candidate("kept", advance="manual", family="upload", trailing_gates=gates)
+            cand.subs.append(Sub(extract_test_id(target, attr), target))
+            return cand
+        ext = _extract(step, step.selector, attr)
+        cand = Candidate("kept", advance="change", family="upload", trailing_gates=gates)
+        cand.subs.append(Sub(ext, step.selector))
+        if ext.ok and ext.reduced_from is None:
+            cand.notes.append(
+                (
+                    "upload-target-may-be-hidden",
+                    "the tour points at the file input itself, which apps usually hide behind a styled button",
+                    "add `guide-cursor: {behavior: click, target: <the visible trigger>}`",
+                )
+            )
+        return cand
+
+    if kind == "check":
+        if action == "wait-for":
+            positive = step.state in (None, "visible")
+            ext = _extract(step, step.selector, attr)
+            checks = [(ext.test_id, step.selector, positive)]
+        else:
+            checks = _checks(step, attr, scoped=True)
+        if has_text(step):
+            cand = Candidate("kept", advance="manual", family="info", centred_ok=True)
+            first = next(((tid, sel) for tid, sel, pos in checks if pos and tid), None)
+            if first is not None:
+                cand.subs.append(Sub(TargetExtraction(test_id=first[0]), first[1]))
+                cand.gate = first[0]
+            else:
+                cand.subs.append(Sub(None, None))
+            return cand
+        usable = [tid for tid, _sel, pos in checks if pos and tid]
+        if usable:
+            return Candidate("gate", gate=usable[-1], reason="gate")
+        dropped = any(pos and not tid for tid, _sel, pos in checks)
+        return Candidate("skip", reason="gate-dropped" if dropped else "check")
+
+    if kind == "cursor":
+        cursor = step.guide_cursor
+        if cursor is not None and cursor.behavior in ("click", "type"):
+            advance = "click" if cursor.behavior == "click" else "input"
+            cand = Candidate("kept", advance=advance, family=advance, trailing_gates=gates)
+            cand.subs.append(Sub(extract_test_id(cursor.target, attr), cursor.target))
+            return cand
+        if cursor is not None:
+            return Candidate("skip", reason="hover-cursor", trailing_gates=gates)
+        if has_text(step):
+            cand = Candidate("kept", advance="manual", family="info", centred_ok=True, trailing_gates=gates)
+            cand.subs.append(Sub(None, None))
+            cand.notes.append(
+                (
+                    "unguided-action",
+                    "this step has text but no target, so the tour shows it as a centred note while the user "
+                    "must still do whatever the code does",
+                    "add `guide-cursor: {behavior: click, target: <test-id selector>}`",
+                )
+            )
+            return cand
+        cand = Candidate("skip", reason=action, trailing_gates=gates)
+        if action == "custom" and step.code and INTERACTIVE_CODE_RE.search(step.code):
+            cand.notes.append(
+                (
+                    "unguided-action",
+                    "this custom code acts on the page, but the tour has nothing to show for it; "
+                    "the next step's target may never appear",
+                    "migrate it to `action: click` (with `synthetic: true` if needed) or add `guide-cursor`",
+                )
+            )
+        return cand
+
+    if kind == "unguided":
+        cand = Candidate("skip", reason=action, trailing_gates=gates)
+        cand.notes.append(
+            (
+                "unguided-action",
+                "confirm dialogs have no test-id to point at, so the tour cannot guide this click",
+                "say what to do in the previous step's `tour-text`, or give the dialog buttons test-ids "
+                "and click them by test-id",
+            )
+        )
+        return cand
+
+    if kind == "navigation":
+        cand = Candidate("skip", reason=action, reloads_page=True, trailing_gates=gates)
+        if action == "navigate" and not step.reload:
+            from .routes import ID_LIKE_RE
+
+            target = step.target or ""
+            id_like = any(ID_LIKE_RE.fullmatch(seg) for seg in target.split("?")[0].split("/") if seg)
+            cand.notes.append(
+                (
+                    "navigate-in-tour",
+                    f"the tour cannot take the user to {target!r}"
+                    + (" — it contains fixture ids no real user has" if id_like else ""),
+                    "start the tour later (tour.entry), or let the user get there by clicking",
+                )
+            )
+        else:
+            cand.notes.append(
+                (
+                    "reloads-page",
+                    "this step reloads the page or logs in again inside the tour",
+                    "the tour resumes from sessionStorage, but move it before the tour starts if you can",
+                )
+            )
+        return cand
+
+    # plain skips
+    cand = Candidate("skip", reason=action, trailing_gates=gates)
+    if action == "keyboard" and "escape" in (step.value or "").lower():
+        cand.notes.append(
+            (
+                "escape-in-tour",
+                "an Escape key press inside the tour may dismiss it",
+                "the player ignores Escape inside dialogs and open dropdowns; check the replay",
+            )
+        )
+    return cand
+
+
+def page_change(step: Step) -> Optional[str]:
+    """Why ``step`` may change the page when it runs unshown, or ``None`` if it cannot.
+
+    Phrased as the start of the ``gate-stale`` message. String literals and
+    comments are blanked before ``custom`` code is scanned, so a selector such
+    as ``':has-text("Save")'`` is not read as a call.
+    """
+    action = step.action
+    if action in PAGE_NEUTRAL_ACTIONS:
+        return None
+    if action == "call":
+        return None if step.page is False else f"the helper `{step.fn}` gets the page and may change it"
+    if action == "custom":
+        code = _COMMENT_RE.sub("", _STRING_RE.sub("''", step.code or ""))
+        for name in _CALL_RE.findall(code):
+            if not (keyword.iskeyword(name) or name in _READ_ONLY_CALLS or name.startswith(_READ_ONLY_PREFIXES)):
+                return f"this code calls `{name}()`, which may change the page"
+        return None
+    return f"this `{action}` may change the page"
+
+
+def replayable(candidate: Candidate, advance: str) -> bool:
+    return advance in _REPLAYABLE.get(candidate.family, _REPLAYABLE["info"])

steppy/tours/compiler.py

@@ -0,0 +1,144 @@
+"""All opted-in scenarios → compiled tours, replay plans and diagnostics."""
+
+from __future__ import annotations
+
+from ..models import Scenario
+from .diagnostics import Diagnostic, DiagSink, sort_diagnostics
+from .inference import infer_scenario
+from .model import CompiledTour, ReplayPlan, ScenarioInference, TourCompileResult
+from .settings import ToursSettings
+from .text import check_texts, content_for, emitted_locales, guide_url, resolve_texts, tour_title
+
+
+def opted_in(scenarios: list[Scenario], settings: ToursSettings) -> list[Scenario]:
+    return [s for s in scenarios if s.tour_opted_in(settings.default_opt_in)]
+
+
+def compile_tours(scenarios: list[Scenario], settings: ToursSettings) -> TourCompileResult:
+    """Compile every opted-in scenario (the caller passes the whole directory)."""
+    diagnostics: list[Diagnostic] = []
+    tours: list[CompiledTour] = []
+    plans: dict[str, ReplayPlan] = {}
+    ids: dict[str, str] = {}
+    untitled: list[str] = []  # multi-locale tours whose title is the (one-language) scenario title
+
+    for scenario in opted_in(scenarios, settings):
+        slug = scenario.slug or (scenario.file_path.stem if scenario.file_path else "scenario")
+        tour_id = scenario.tour.id if scenario.tour and scenario.tour.id else slug
+        sink = DiagSink(slug, tour_id, replay=settings.replay)
+        from ..tour_spec import is_tour_id
+
+        if not is_tour_id(tour_id):
+            sink.add(
+                "tour-id-invalid",
+                f"{tour_id!r} cannot be a tour id (1-64 characters [A-Za-z0-9_-], no device names)",
+                hint="set `tour: {id: <id>}`",
+            )
+            diagnostics.extend(sink.items)
+            continue
+        key = tour_id.casefold()
+        if key in ids:
+            sink.add("tour-id-duplicate", f"tour id {tour_id!r} is also used by {ids[key]}", hint="set `tour.id`")
+            diagnostics.extend(sink.items)
+            continue
+        ids[key] = slug
+
+        inference = infer_scenario(scenario, settings, sink)
+        if inference is None:
+            diagnostics.extend(sink.items)
+            continue
+        tour = _compile_one(scenario, slug, tour_id, inference, settings, sink)
+        diagnostics.extend(sink.items)
+        if sink.has_errors:
+            continue
+        tours.append(tour)
+        if (scenario.tour is None or scenario.tour.title is None) and len(tour.locales) > 1:
+            untitled.append(tour_id)
+        plans[slug] = ReplayPlan(
+            scenario_slug=slug,
+            tour_id=tour_id,
+            role=inference.role,
+            auth=scenario.auth,
+            default_locale=settings.default_locale,
+            locales=tour.locales,
+            entry_route=inference.entry_route,
+            entry_params=inference.entry_params,
+            entry_step_number=(
+                scenario.steps[inference.entry_step_index].step_number
+                if inference.entry_step_index is not None
+                else None
+            ),
+            start_index=inference.start_index,
+            entries=tuple(inference.entries),
+            tour_step_count=len(inference.steps),
+            layouts=tuple(
+                (name, query)
+                for name, query in settings.layouts
+                if any(p.layouts and name in p.layouts for p in inference.steps)
+            ),
+            test_id_attribute=settings.test_id_attribute,
+        )
+
+    if untitled:
+        shown = ", ".join(sorted(untitled)[:5]) + (", …" if len(untitled) > 5 else "")
+        diagnostics.append(
+            Diagnostic(
+                "warning",
+                "title-fallback",
+                f"{len(untitled)} multi-language tour(s) have no `tour.title` ({shown}); every language shows "
+                "the scenario title, which apps listing tours display as is",
+                hint="set `tour: {title: {en: …, fr: …}}`",
+            )
+        )
+    tours.sort(key=lambda t: t.id)
+    return TourCompileResult(tours=tours, replay_plans=plans, diagnostics=sort_diagnostics(diagnostics))
+
+
+def _compile_one(
+    scenario: Scenario,
+    slug: str,
+    tour_id: str,
+    inference: ScenarioInference,
+    settings: ToursSettings,
+    sink: DiagSink,
+) -> CompiledTour:
+    locales = emitted_locales(scenario, inference.steps, settings)
+    dropped = [loc for loc in settings.locales if loc not in locales]
+    if dropped:
+        sink.add(
+            "locale-not-emitted",
+            f"no kept step has text in {', '.join(dropped)}, so no file is written for it; those users get "
+            f"the tour in their base language if it has a file, else in {settings.default_locale}",
+            hint="add `tour-text` or `guide-text` in that language",
+        )
+    if not any(content_for(scenario.steps[p.step_index], settings.default_locale) for p in inference.steps):
+        sink.add(
+            "no-authored-text",
+            f"no step has text in the default locale {settings.default_locale!r}; every step shows a generic instruction",
+        )
+    titles = {}
+    fell_back = []
+    for locale in locales:
+        titles[locale], fb = tour_title(scenario, locale, settings.default_locale)
+        if fb:
+            fell_back.append(locale)
+    if fell_back:
+        sink.add(
+            "title-fallback",
+            f"tour.title has no entry for {', '.join(fell_back)}; the {settings.default_locale} title "
+            "(else the scenario title) is used there",
+        )
+    texts = resolve_texts(scenario, inference.steps, locales)
+    check_texts(scenario, inference.steps, texts, settings, sink)
+    urls = {loc: u for loc in locales if (u := guide_url(scenario, settings, loc))}
+    return CompiledTour(
+        id=tour_id,
+        scenario_slug=slug,
+        role=inference.role,
+        entry_route=inference.entry_route,
+        steps=inference.steps,
+        locales=locales,
+        titles=titles,
+        step_texts=texts,
+        guide_urls=urls,
+    )

steppy/tours/diagnostics.py

@@ -0,0 +1,137 @@
+"""Compile diagnostics: stable kebab-case codes, one rendered line each.
+
+Errors stop emission (``steppy validate`` exits 1); warnings never change
+an exit code; infos only print with ``steppy tours --explain``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal, Optional
+
+Severity = Literal["error", "warning", "info"]
+
+#: Every code the compiler emits, with its severity. Tests pin that the compiler
+#: never emits a code missing here, that every code here is emitted somewhere
+#: (``tests/test_tours_diagnostics.py``), and that ``docs/tours.md`` lists each
+#: one with this severity (``tests/test_tours_docs_sync.py``).
+CODES: dict[str, Severity] = {
+    # errors
+    "scenario-unreadable": "error",
+    "tour-role-required": "error",
+    "tour-role-unknown": "error",
+    "tour-no-role": "error",
+    "tour-id-invalid": "error",
+    "tour-id-duplicate": "error",
+    "entry-invalid": "error",
+    "entry-no-match": "error",
+    "no-entry": "error",  # downgraded to a warning when tours.replay is off
+    "target-not-test-id": "error",
+    "no-kept-steps": "error",
+    "layouts-unmapped": "error",
+    "annotation-outside-tour": "error",
+    "annotation-on-skipped-step": "error",
+    "skip-and-annotations": "error",
+    "keep-not-allowed": "error",
+    "advance-needs-target": "error",
+    "advance-not-replayable": "error",  # downgraded to a warning when tours.replay is off
+    "limit-exceeded": "error",
+    "layout-media-mismatch": "error",
+    "build-id": "error",
+    "target-path": "error",
+    # warnings
+    "unguided-action": "warning",
+    "navigate-in-tour": "warning",
+    "reloads-page": "warning",
+    "escape-in-tour": "warning",
+    "may-not-change": "warning",
+    "upload-target-may-be-hidden": "warning",
+    "entry-query-dropped": "warning",
+    "entry-id-segment": "warning",
+    "app-url-unresolved": "warning",
+    "fixture-leak": "warning",
+    "generic-text": "warning",
+    "no-authored-text": "warning",
+    "title-fallback": "warning",
+    "placement-ignored": "warning",
+    "tour-text-locale-untargeted": "warning",
+    "locale-not-emitted": "warning",
+    "chrome-strings-missing": "warning",
+    "text-link-dropped": "warning",
+    "layout-media-overlap": "warning",
+    "app-assets-skipped": "warning",
+    "no-tours": "warning",
+    # infos
+    "step-skipped": "info",
+    "gate-dropped": "info",
+    "gate-stale": "info",
+    "reduced-to-host": "info",
+    "conditional-skipped": "info",
+    "layout-media-unchecked": "info",
+}
+
+
+@dataclass(frozen=True)
+class Diagnostic:
+    severity: Severity
+    code: str
+    message: str
+    scenario: Optional[str] = None
+    tour: Optional[str] = None
+    step_number: Optional[int] = None
+    step_title: Optional[str] = None
+    hint: Optional[str] = None
+
+    def render(self) -> str:
+        where = ""
+        if self.tour and self.scenario and self.tour != self.scenario:
+            where = f"tour '{self.tour}' ({self.scenario})"
+        elif self.tour or self.scenario:
+            where = f"tour '{self.tour or self.scenario}'"
+        if self.step_number is not None:
+            where += f", step {self.step_number}"
+            if self.step_title:
+                where += f" '{self.step_title}'"
+        text = f"{where}: {self.message}" if where else self.message
+        if self.hint:
+            text += f" — {self.hint}"
+        return f"[{self.code}] {text}"
+
+    def sort_key(self):
+        return (self.scenario or "", self.step_number or 0, self.code, self.message)
+
+
+class DiagSink:
+    """Collects diagnostics for one scenario (or the whole run when ``scenario`` is None)."""
+
+    def __init__(self, scenario: Optional[str] = None, tour: Optional[str] = None, *, replay: bool = True):
+        self.scenario = scenario
+        self.tour = tour
+        self.replay = replay
+        self.items: list[Diagnostic] = []
+
+    def add(self, code: str, message: str, *, step=None, hint: Optional[str] = None) -> None:
+        severity = CODES[code]
+        if code in ("no-entry", "advance-not-replayable") and not self.replay:
+            severity = "warning"
+        self.items.append(
+            Diagnostic(
+                severity=severity,
+                code=code,
+                message=message,
+                scenario=self.scenario,
+                tour=self.tour,
+                step_number=getattr(step, "step_number", None),
+                step_title=getattr(step, "step_title", None),
+                hint=hint,
+            )
+        )
+
+    @property
+    def has_errors(self) -> bool:
+        return any(d.severity == "error" for d in self.items)
+
+
+def sort_diagnostics(items: list[Diagnostic]) -> list[Diagnostic]:
+    order = {"error": 0, "warning": 1, "info": 2}
+    return sorted(items, key=lambda d: (order[d.severity], *d.sort_key()))