steppy-dev 0.3.0__py3-none-any.whl

steppy/report/coverage_source.py

@@ -0,0 +1,277 @@
+"""Where the report's coverage numbers come from, in order of trustworthiness.
+
+Named ``coverage_source`` rather than ``coverage`` so ``from . import coverage``
+inside this package cannot shadow :mod:`steppy.coverage`.
+
+The problem this module exists to solve. The coverage map is a sqlite store at
+``.steppy/coverage.db``, which lives **outside** ``output/`` on purpose — cleaning
+run artifacts must never wipe hand-made triage flags — and is therefore never
+inside a results bundle. The *declared* surface it is scored against comes from
+``coverage refresh``, which fetches an OpenAPI document over the network. So a
+bundle downloaded from someone else's CI carries the raw per-scenario records and
+nothing that says what they should be compared to.
+
+Four tiers, best first:
+
+===========  ==========================================  ===============================
+tier         source                                      when
+===========  ==========================================  ===============================
+``bundled``  ``output/coverage/gaps.json`` in the run    any input that carries one
+``store``    the project's live ``.steppy/coverage.db``  **live-tree input only**
+``records``  a throwaway store rebuilt from raw records  records, no gaps.json, no store
+``none``     no coverage section at all                  nothing was recorded
+===========  ==========================================  ===============================
+
+Two of those rows are guardrails against a plausible-looking lie, and both are the
+kind of bug that would never surface as a crash:
+
+**``store`` is live-tree only.** Reading this machine's map to describe a bundle
+that came from elsewhere would attribute *our* coverage to *their* run and print a
+confident percentage about it.
+
+**``records`` cannot report assert strength.** Rebuilding via ``merge_run`` calls
+``count_scenario_asserts``, which reads ``scenarios/*.md`` — and a bundle carries
+none, so it returns 0 for every scenario and ``gaps._strength`` marks every tested
+endpoint "weak". So that tier suppresses strength outright and says why, rather
+than publishing a number that looks like a finding.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Optional, Sequence
+
+from ..contracts.report import ReportBadge, ReportCoverage, ReportNonUi
+
+TIER_BUNDLED = "bundled"
+TIER_STORE = "store"
+TIER_RECORDS = "records"
+TIER_NONE = "none"
+
+#: Manifest kind of the gap report that travels with a run (``bundle/classify``).
+GAPS_KIND = "coverage_gaps"
+RECORD_KIND = "coverage_record"
+
+STRENGTH_UNKNOWN_WARNING = (
+    "assert strength is unavailable: this coverage was rebuilt from raw records, and a bundle "
+    "carries no scenarios/*.md to count assert steps in — every tested endpoint would otherwise "
+    "read as weakly covered"
+)
+
+
+def resolve_coverage(
+    source,
+    *,
+    project_root: Path,
+    non_ui: Sequence[str] = (),
+    surface: str = "all",
+    badge_label: Optional[str] = None,
+    href: Optional[str] = None,
+) -> ReportCoverage:
+    """Best available coverage for *source*. Never raises — degrades and says so."""
+    from ..coverage.report import DEFAULT_BADGE_LABEL
+
+    label = badge_label or DEFAULT_BADGE_LABEL
+    warnings: list[str] = []
+
+    gaps, tier = _from_bundle(source, warnings)
+    if gaps is None and source.is_live_tree:
+        gaps, tier = _from_store(project_root, non_ui, warnings)
+    if gaps is None:
+        gaps, tier = _from_records(source, project_root, non_ui, warnings)
+    if gaps is None:
+        return ReportCoverage(tier=TIER_NONE, warnings=warnings)
+
+    if tier == TIER_RECORDS:
+        warnings.append(STRENGTH_UNKNOWN_WARNING)
+
+    return _view(gaps, tier=tier, surface=surface, label=label, href=href, warnings=warnings)
+
+
+def _view(
+    gaps: dict,
+    *,
+    tier: str,
+    surface: str,
+    label: str,
+    href: Optional[str],
+    warnings: list[str],
+) -> ReportCoverage:
+    from ..coverage.report import badge_payload
+
+    ratio = (gaps.get("e2e_surface") or {}).get(surface) or {}
+    payload = badge_payload(gaps, surface=surface, label=label)
+    return ReportCoverage(
+        tier=tier,
+        counts=gaps.get("counts") or {},
+        e2e_surface=gaps.get("e2e_surface") or {},
+        buckets={kind: gaps[kind] for kind in ("endpoints", "routes", "modules") if isinstance(gaps.get(kind), dict)},
+        non_ui=_non_ui_summary(gaps),
+        badge=ReportBadge(
+            surface=surface,
+            label=label,
+            tested=ratio.get("tested", 0),
+            declared=ratio.get("declared", 0),
+            ratio=ratio.get("ratio"),
+            percent=ratio.get("percent"),
+            color=payload["color"],
+        ),
+        href=href,
+        warnings=warnings,
+    )
+
+
+def _non_ui_summary(gaps: dict) -> ReportNonUi:
+    """How much was discounted, and on whose authority.
+
+    ``by_source`` is what lets a reader see a percentage was raised by committed
+    config rather than by a flag somebody set locally and never shared.
+    """
+    counts = gaps.get("counts") or {}
+    declared = sum((counts.get(kind) or {}).get("declared_non_ui", 0) for kind in ("endpoints", "routes"))
+    tested = sum((counts.get(kind) or {}).get("tested_non_ui", 0) for kind in ("endpoints", "routes"))
+    by_source: dict[str, int] = {}
+    for kind in ("endpoints", "routes"):
+        section = gaps.get(kind) or {}
+        for bucket in ("tested", "declared_unreached"):
+            for entry in section.get(bucket) or []:
+                if entry.get("triage") == "non_ui":
+                    key = entry.get("triage_source") or "unspecified"
+                    by_source[key] = by_source.get(key, 0) + 1
+    return ReportNonUi(declared=declared, tested=tested, by_source=dict(sorted(by_source.items())))
+
+
+def _from_bundle(source, warnings: list[str]) -> tuple[Optional[dict], str]:
+    """The gap report that travelled with the run, if it did."""
+    entries = [f for f in source.manifest.files if f.kind == GAPS_KIND]
+    if not entries:
+        return None, TIER_NONE
+    try:
+        fetched, fetch_warnings = source.fetch(texts={entries[0].path})
+    except Exception as e:
+        warnings.append(f"coverage: could not read {entries[0].path} from the bundle ({e})")
+        return None, TIER_NONE
+    warnings.extend(fetch_warnings)
+    payload = fetched.get(entries[0].path)
+    if not payload:
+        return None, TIER_NONE
+    try:
+        gaps = json.loads(payload.decode("utf-8"))
+    except (UnicodeDecodeError, ValueError) as e:
+        warnings.append(f"coverage: {entries[0].path} is not readable JSON ({e})")
+        return None, TIER_NONE
+    if not isinstance(gaps, dict):
+        return None, TIER_NONE
+    return gaps, TIER_BUNDLED
+
+
+def _from_store(project_root: Path, non_ui: Sequence[str], warnings: list[str]) -> tuple[Optional[dict], str]:
+    """The project's own map. Only ever reached for a live ``output/`` tree."""
+    try:
+        from ..config import load_config
+        from ..coverage.gaps import compute_gaps
+        from ..coverage.merge import CoverageSettings
+        from ..coverage.store import open_store, read_map
+        from ..coverage.triage import apply_config_triage
+
+        settings = CoverageSettings.from_config(load_config(project_root / "config.yaml"), project_root)
+        store_path = Path(settings.store_path)
+        if not store_path.is_file():
+            return None, TIER_NONE
+        patterns = tuple(non_ui) or settings.non_ui
+        conn = open_store(store_path)
+        try:
+            gaps = compute_gaps(apply_config_triage(read_map(conn), patterns))
+        finally:
+            conn.close()
+        return gaps, TIER_STORE
+    except Exception as e:
+        warnings.append(f"coverage: the local map at .steppy/coverage.db could not be read ({e})")
+        return None, TIER_NONE
+
+
+def _from_records(source, project_root: Path, non_ui: Sequence[str], warnings: list[str]) -> tuple[Optional[dict], str]:
+    """Last resort: rebuild a throwaway map from the raw records in the bundle.
+
+    Observed nodes only. There is no declared surface here (that needs the network)
+    and no triage table, so the buckets are honest about what was *exercised* and
+    silent about what was missed.
+    """
+    entries = [f for f in source.manifest.files if f.kind == RECORD_KIND]
+    if not entries:
+        return None, TIER_NONE
+
+    import tempfile
+
+    try:
+        from ..config import ConfigError, load_config
+        from ..coverage.gaps import compute_gaps
+        from ..coverage.merge import CoverageSettings, merge_run
+        from ..coverage.store import open_store, read_map
+        from ..coverage.triage import apply_config_triage
+    except Exception as e:  # pragma: no cover - import failure is not a report failure
+        warnings.append(f"coverage: records present but the coverage modules could not be loaded ({e})")
+        return None, TIER_NONE
+
+    run_id = source.manifest.run.run_id
+    with tempfile.TemporaryDirectory(prefix="steppy-report-cov-") as tmp:
+        tmp_root = Path(tmp)
+        records_dir = tmp_root / "coverage"
+        wanted = {entry.path: records_dir / _record_rel(entry.path) for entry in entries}
+        try:
+            _, fetch_warnings = source.fetch(into=wanted)
+        except Exception as e:
+            warnings.append(f"coverage: raw records could not be read ({e})")
+            return None, TIER_NONE
+        warnings.extend(fetch_warnings)
+
+        try:
+            base = load_config(project_root / "config.yaml")
+        except (ConfigError, OSError):
+            base = None
+        settings = (
+            CoverageSettings.from_config(base, project_root)
+            if base is not None
+            else CoverageSettings(store_path=tmp_root / "map.db", records_dir=records_dir)
+        )
+        settings = _relocated(settings, store_path=tmp_root / "map.db", records_dir=records_dir)
+
+        try:
+            merge_run(settings, run_id)
+            conn = open_store(settings.store_path)
+            try:
+                patterns = tuple(non_ui) or settings.non_ui
+                gaps = compute_gaps(apply_config_triage(read_map(conn), patterns))
+            finally:
+                conn.close()
+        except Exception as e:
+            warnings.append(f"coverage: raw records could not be merged ({e})")
+            return None, TIER_NONE
+    return gaps, TIER_RECORDS
+
+
+def _relocated(settings, *, store_path: Path, records_dir: Path):
+    """A copy of *settings* pointed at a throwaway store.
+
+    ``dataclasses.replace`` rather than mutation: the caller's settings describe
+    the project, and quietly repointing them at a temp directory is the sort of
+    thing that works until something else reads them.
+    """
+    from dataclasses import replace
+
+    return replace(settings, store_path=store_path, records_dir=records_dir)
+
+
+def _record_rel(manifest_path: str) -> Path:
+    """``output/coverage/raw/<run>/<scenario>/<file>`` → ``raw/<run>/<scenario>/<file>``.
+
+    ``merge_run`` expects the ``raw/<run_id>/`` layout under its ``records_dir``,
+    so the tail from ``raw/`` onwards is what has to be reproduced. Falls back to
+    the basename if the path is not that shape, which keeps a malformed manifest
+    from escaping the temp directory.
+    """
+    parts = Path(manifest_path).parts
+    if "raw" in parts:
+        return Path(*parts[parts.index("raw") :])
+    return Path(Path(manifest_path).name)

steppy/report/model.py

@@ -0,0 +1,423 @@
+"""Bundle manifest + event timeline + coverage → :class:`ReportModel`.
+
+**This module must never import jinja2.** It is the half of the reporter a control
+plane can consume — ``from steppy.report.model import build_model`` — and dragging
+a renderer along would defeat the point of the model/render split. That is the
+concrete form of "one renderer, not two": the *model* is shared, the presentation
+is not. (It also may not import :mod:`steppy.guide`, which builds a module-level
+``MarkdownIt``; a guard test forbids ``markdown_it`` on the default import path.)
+
+The build is a pure function of its inputs, with no clock and no filesystem reads.
+Everything it needs has already been fetched: the manifest carries the file
+inventory *with* attribution (``bundle/classify.py`` did that work at create
+time, so nothing here parses a path), the timeline comes from the event JSONL, and
+coverage arrives resolved. Same input, same bytes out — which is what lets a test
+assert on the model and CI diff two reports.
+"""
+
+from __future__ import annotations
+
+import base64
+from typing import Iterable, Optional
+
+from ..contracts.bundle import BundleFile, BundleManifest, BundleTest
+from ..contracts.report import (
+    REPORT_SCHEMA_VERSION,
+    ReportArtifactGroup,
+    ReportArtifacts,
+    ReportCapabilities,
+    ReportCoverage,
+    ReportFailureCause,
+    ReportFailureOccurrence,
+    ReportModel,
+    ReportScenario,
+    ReportSourceInfo,
+    ReportStep,
+    ReportTotals,
+    ReportVariant,
+)
+
+#: Worst-first. A run's verdict, and a scenario's, is the worst thing that
+#: happened to it — a flow that fails only in Dutch on mobile is a failing flow.
+#: Unknown outcomes sort *after* ``failed`` and before ``passed``: something we
+#: cannot classify is not a pass, and claiming it is a failure would be a guess.
+_OUTCOME_RANK = {
+    "worker_died": 0,
+    "error": 1,
+    "failed": 2,
+    "interrupted": 3,
+    "unknown": 4,
+    "skipped": 5,
+    "passed": 6,
+}
+_UNRANKED = 4
+
+#: Outcomes that do not fail a gate. ``skipped`` is deliberate scope, and the
+#: coordinator already treats a pass-on-retry as non-fatal.
+_PASSING = frozenset({"passed", "skipped"})
+
+
+def worse(a: str, b: str) -> str:
+    """The worse of two outcomes, by :data:`_OUTCOME_RANK`."""
+    return a if _rank(a) <= _rank(b) else b
+
+
+def _rank(outcome: str) -> int:
+    return _OUTCOME_RANK.get(outcome, _UNRANKED)
+
+
+def _decode_tail(test: BundleTest) -> str:
+    if not test.fail_tail_b64:
+        return ""
+    try:
+        return base64.b64decode(test.fail_tail_b64).decode("utf-8", errors="replace")
+    except (ValueError, TypeError):
+        # A corrupt tail is not worth losing the row over — the outcome, the step
+        # and the screenshot all still say something useful.
+        return ""
+
+
+class _Row:
+    """Duck-type for ``_parallel.fingerprint.group_failures``.
+
+    That function needs only ``.slug`` and ``.fail_tails``, which is why the
+    parallel renderer's grouping works here unchanged rather than being
+    reimplemented — the console summary and the HTML report collapse identical
+    failures identically, by construction.
+    """
+
+    __slots__ = ("slug", "fail_tails")
+
+    def __init__(self, slug: str, fail_tails: list[tuple[str, str]]):
+        self.slug = slug
+        self.fail_tails = fail_tails
+
+
+def group_manifest_failures(tests: Iterable[BundleTest]) -> tuple[list[ReportFailureCause], dict[str, str]]:
+    """``(causes, {nodeid: fingerprint})`` for every failing test.
+
+    Returns the per-nodeid map as well so each variant can link to its cause
+    without the templates re-deriving anything.
+    """
+    from .._parallel.fingerprint import fingerprint, group_failures
+
+    by_slug: dict[str, list[tuple[str, str]]] = {}
+    context: dict[str, BundleTest] = {}
+    prints: dict[str, str] = {}
+    for test in tests:
+        if test.outcome in _PASSING:
+            continue
+        tail = _decode_tail(test)
+        by_slug.setdefault(test.scenario, []).append((test.nodeid, tail))
+        context[test.nodeid] = test
+        prints[test.nodeid] = fingerprint(tail)
+
+    rows = [_Row(slug, tails) for slug, tails in by_slug.items()]
+    causes = []
+    for group in group_failures(rows):
+        occurrences = []
+        exemplar = ""
+        for _slug, nodeid, tail in group.occurrences:
+            test = context.get(nodeid)
+            occurrences.append(
+                ReportFailureOccurrence(
+                    scenario=test.scenario if test else _slug,
+                    nodeid=nodeid,
+                    locale=test.locale if test else None,
+                    layout=test.layout if test else None,
+                )
+            )
+            if not exemplar:
+                exemplar = tail
+        causes.append(
+            ReportFailureCause(
+                fingerprint=group.fingerprint,
+                headline=group.headline,
+                count=group.count,
+                scenarios=group.slugs,
+                occurrences=occurrences,
+                exemplar_tail=exemplar,
+            )
+        )
+    return causes, prints
+
+
+def scenario_href(slug: str) -> str:
+    """Site-relative URL of a scenario page.
+
+    One definition, used for the link *and* for the filename the renderer writes —
+    two would drift, and they would drift silently into a 404. The slug is
+    sanitised for the same reason asset paths are: it may have arrived in a
+    downloaded manifest, and here it decides a path on disk.
+    """
+    from .assets import sanitise
+
+    return f"scenarios/{sanitise(slug)}.html"
+
+
+def build_model(
+    *,
+    manifest: BundleManifest,
+    source: ReportSourceInfo,
+    attempts: Optional[dict] = None,
+    coverage: Optional[ReportCoverage] = None,
+    assets: Optional[dict] = None,
+    screenshots_policy: str = "none",
+    steppy_version: str = "",
+    extra_warnings: Optional[list[str]] = None,
+) -> ReportModel:
+    """Assemble the report model.
+
+    ``attempts`` is ``{nodeid: [TestAttempt]}`` from
+    ``bundle.results.steps_from_records``; ``assets`` maps a manifest path to the
+    site-relative URL it was copied to (absent ⇒ not copied, which is a policy
+    outcome rather than an error).
+    """
+    attempts = attempts or {}
+    assets = assets or {}
+    coverage = coverage or ReportCoverage()
+
+    tests = list(manifest.tests)
+    causes, prints = group_manifest_failures(tests)
+
+    # Scenarios come from the tests AND the files, so a run made without
+    # --bundle — no test rows at all — still lists what it captured instead of
+    # rendering an empty page.
+    slugs: list[str] = []
+    seen: set[str] = set()
+    for name in [t.scenario for t in tests] + [f.scenario for f in manifest.files if f.scenario]:
+        if name and name not in seen:
+            seen.add(name)
+            slugs.append(name)
+    slugs.sort()
+
+    by_scenario: dict[str, list[BundleTest]] = {}
+    for test in tests:
+        by_scenario.setdefault(test.scenario, []).append(test)
+
+    failure_shots = _index_failure_screenshots(manifest, assets)
+    failure_logs = _index_by_scenario(manifest, "failure_log")
+    traces = _index_paths(manifest, "trace")
+    videos = _index_paths(manifest, "video")
+
+    scenarios: list[ReportScenario] = []
+    any_steps = False
+    any_attempts = False
+    outcomes: dict[str, int] = {}
+    duration_sum = 0
+    verdict = "passed"
+
+    for slug in slugs:
+        rows = by_scenario.get(slug, [])
+        variants: list[ReportVariant] = []
+        scenario_outcome = "passed" if rows else "unknown"
+        scenario_counts: dict[str, int] = {}
+        scenario_duration = 0
+
+        for test in sorted(rows, key=lambda t: (t.locale or "", t.layout or "", t.nodeid)):
+            runs = attempts.get(test.nodeid) or []
+            if len(runs) > 1:
+                any_attempts = True
+            last = runs[-1] if runs else None
+            steps = _steps_for(last, test, assets, manifest)
+            if steps:
+                any_steps = True
+
+            variants.append(
+                ReportVariant(
+                    nodeid=test.nodeid,
+                    locale=test.locale,
+                    layout=test.layout,
+                    outcome=test.outcome,
+                    duration_ms=test.duration_ms,
+                    attempts=max(len(runs), 1),
+                    attempt_outcomes=[a.outcome or "unknown" for a in runs],
+                    failed_step=test.failed_step,
+                    failed_step_title=_step_title(steps, test.failed_step),
+                    fingerprint=prints.get(test.nodeid),
+                    fail_tail=_decode_tail(test),
+                    steps=steps,
+                    failure_screenshot=failure_shots.get(test.nodeid),
+                    trace_path=traces.get(test.nodeid),
+                    video_path=videos.get(test.nodeid),
+                )
+            )
+            outcomes[test.outcome] = outcomes.get(test.outcome, 0) + 1
+            scenario_counts[test.outcome] = scenario_counts.get(test.outcome, 0) + 1
+            scenario_outcome = worse(scenario_outcome, test.outcome)
+            verdict = worse(verdict, test.outcome)
+            duration_sum += test.duration_ms or 0
+            scenario_duration += test.duration_ms or 0
+
+        scenarios.append(
+            ReportScenario(
+                slug=slug,
+                outcome=scenario_outcome,
+                outcomes=scenario_counts,
+                duration_ms_sum=scenario_duration,
+                href=scenario_href(slug),
+                variants=variants,
+                failure_log=failure_logs.get(slug),
+            )
+        )
+
+    not_passed = sum(1 for s in scenarios if s.outcome not in _PASSING)
+    if not tests:
+        # No outcomes were recorded at all — a run without ``--bundle``, or a
+        # capture-only guide run. "passed" would be a claim we have no evidence
+        # for, which is the exact failure mode this whole model tries to avoid.
+        # ``exit_code`` stays 0 because nothing *failed*: the run itself already
+        # reported its own verdict, and a report is not the gate.
+        verdict = "unknown"
+        exit_code = 0
+    else:
+        exit_code = 0 if verdict in _PASSING else 1
+    totals = ReportTotals(
+        tests=len(tests),
+        scenarios=len(scenarios),
+        scenarios_not_passed=not_passed,
+        outcomes=dict(sorted(outcomes.items())),
+        duration_ms_sum=duration_sum,
+        verdict=verdict,
+        exit_code=exit_code,
+    )
+
+    warnings = list(manifest.warnings) + list(extra_warnings or [])
+    return ReportModel(
+        steppy_report=REPORT_SCHEMA_VERSION,
+        generated_by=steppy_version,
+        source=source,
+        run=manifest.run,
+        totals=totals,
+        dimensions=_observed_dimensions(tests),
+        capabilities=ReportCapabilities(
+            step_timeline=any_steps,
+            attempts=any_attempts,
+            coverage=coverage.tier,
+            screenshots=screenshots_policy,
+            strength_reliable=coverage.tier != "records",
+        ),
+        scenarios=scenarios,
+        failure_causes=causes,
+        coverage=coverage,
+        artifacts=_artifacts(manifest, assets),
+        warnings=warnings,
+        truncated=manifest.truncated,
+    )
+
+
+def _observed_dimensions(tests: list[BundleTest]) -> dict[str, list[str]]:
+    """Locales and layouts that actually produced a row.
+
+    Not ``run.spec``: a scenario whose frontmatter ``layouts:`` is disjoint from
+    the run's is silently deselected, so a matrix built from the *requested* set
+    grows a column of empty cells that reads like a failure.
+    """
+    locales = sorted({t.locale for t in tests if t.locale})
+    layouts = sorted({t.layout for t in tests if t.layout})
+    return {"locales": locales, "layouts": layouts}
+
+
+def _steps_for(attempt, test: BundleTest, assets: dict, manifest: BundleManifest) -> list[ReportStep]:
+    """The timeline for one variant, with each step's captures attached."""
+    if attempt is None:
+        return []
+    shots = _index_step_screenshots(manifest, assets, test.scenario, test.locale, test.layout)
+    steps = []
+    for row in attempt.offsets():
+        steps.append(ReportStep(**row, screenshots=shots.get(row["step"], [])))
+    return steps
+
+
+def _step_title(steps: list[ReportStep], failed_step: Optional[int]) -> str:
+    if failed_step is None:
+        return ""
+    for step in steps:
+        if step.step == failed_step:
+            return step.title
+    return ""
+
+
+def _index_step_screenshots(
+    manifest: BundleManifest, assets: dict, scenario: Optional[str], locale, layout
+) -> dict[int, list[str]]:
+    """``{step: [url, …]}`` for one variant, in frame order.
+
+    Reads ``manifest.files[]`` attribution rather than parsing paths — that is what
+    ``bundle/classify.py`` recorded it for.
+    """
+    out: dict[int, list[tuple[str, str]]] = {}
+    for entry in manifest.files:
+        if entry.kind != "screenshot" or entry.step is None:
+            continue
+        if entry.scenario != scenario or entry.locale != locale or entry.layout != layout:
+            continue
+        url = assets.get(entry.path)
+        if url:
+            out.setdefault(entry.step, []).append((entry.frame or "", url))
+    return {step: [url for _frame, url in sorted(frames)] for step, frames in out.items()}
+
+
+def _index_failure_screenshots(manifest: BundleManifest, assets: dict) -> dict[str, str]:
+    """``{nodeid: url}``, joined through the manifest's own attribution.
+
+    ``sanitise_nodeid`` is lossy and must only ever be used forwards, so nothing
+    here tries to reverse a ``_failures/`` filename: ``classify`` already resolved
+    each one to a (scenario, locale, layout) at create time.
+    """
+    by_key: dict[tuple, str] = {}
+    for entry in manifest.files:
+        if entry.kind != "failure_screenshot":
+            continue
+        url = assets.get(entry.path)
+        if url:
+            by_key.setdefault((entry.scenario, entry.locale, entry.layout), url)
+    return {
+        test.nodeid: url
+        for test in manifest.tests
+        if (url := by_key.get((test.scenario, test.locale, test.layout))) is not None
+    }
+
+
+def _index_by_scenario(manifest: BundleManifest, kind: str) -> dict[str, str]:
+    out: dict[str, str] = {}
+    for entry in manifest.files:
+        if entry.kind == kind and entry.scenario:
+            out.setdefault(entry.scenario, entry.path)
+    return out
+
+
+def _index_paths(manifest: BundleManifest, kind: str) -> dict[str, str]:
+    """``{nodeid: in-bundle path}`` for artifacts that are named, not copied."""
+    by_key: dict[tuple, str] = {}
+    for entry in manifest.files:
+        if entry.kind == kind:
+            by_key.setdefault((entry.scenario, entry.locale, entry.layout), entry.path)
+    return {
+        test.nodeid: path
+        for test in manifest.tests
+        if (path := by_key.get((test.scenario, test.locale, test.layout))) is not None
+    }
+
+
+def _artifacts(manifest: BundleManifest, assets: dict) -> ReportArtifacts:
+    by_kind: dict[str, ReportArtifactGroup] = {}
+    total_bytes = 0
+    for entry in manifest.files:
+        group = by_kind.setdefault(entry.kind, ReportArtifactGroup())
+        group.count += 1
+        group.bytes += entry.size
+        total_bytes += entry.size
+    copied = {url for url in assets.values() if url}
+    return ReportArtifacts(
+        files=len(manifest.files),
+        bytes=total_bytes,
+        deduped=max(len(assets) - len(copied), 0),
+        by_kind=dict(sorted(by_kind.items())),
+    )
+
+
+def files_of_kind(manifest: BundleManifest, *kinds: str) -> list[BundleFile]:
+    """Manifest rows of any of *kinds*, in manifest order (sorted by path)."""
+    wanted = set(kinds)
+    return [f for f in manifest.files if f.kind in wanted]