steppy-dev 0.3.0__py3-none-any.whl

steppy/bundle_cli.py

@@ -0,0 +1,455 @@
+"""``steppy bundle`` — package a run's results into a portable archive.
+
+Leaf CLI module, registered by ``cli.py`` like ``coverage_cli`` /
+``video_cli``. Only ``typer`` + ``_cli_common`` + stdlib at module scope; every
+``steppy.bundle`` import happens inside a command body so ``import steppy.cli``
+never pulls in the walker or the optional ``zstandard``. Guard:
+``tests/test_no_bundle_import_on_default_path.py``.
+"""
+
+from __future__ import annotations
+
+import json as _json
+from pathlib import Path
+from typing import Optional
+
+import typer
+
+from ._cli_common import _cli_errors, _error, console
+
+bundle_app = typer.Typer(
+    help="Package a run's output/ tree into a portable results bundle.",
+    no_args_is_help=True,
+)
+
+
+def register_bundle(app: typer.Typer) -> None:
+    """Attach the ``bundle`` command group to the root Typer app."""
+    app.add_typer(bundle_app, name="bundle")
+
+
+def _parse_size(value: str) -> int:
+    """``2GiB`` / ``500MB`` / ``0`` → bytes. ``0`` disables the budget."""
+    text = value.strip().lower().replace(" ", "")
+    if not text:
+        return 0
+    units = (("gib", 1024**3), ("mib", 1024**2), ("kib", 1024), ("gb", 10**9), ("mb", 10**6), ("kb", 10**3), ("b", 1))
+    for suffix, factor in units:
+        if text.endswith(suffix):
+            number = text[: -len(suffix)]
+            try:
+                return int(float(number) * factor)
+            except ValueError:
+                break
+    try:
+        return int(text)
+    except ValueError:
+        raise typer.BadParameter(f"could not parse a size from {value!r} (try 2GiB, 500MB or 0)")
+
+
+def _human(size: int) -> str:
+    for unit in ("B", "KiB", "MiB", "GiB"):
+        if size < 1024 or unit == "GiB":
+            return f"{size:.0f} {unit}" if unit == "B" else f"{size:.1f} {unit}"
+        size /= 1024.0
+    return f"{size:.1f} GiB"
+
+
+def _print_summary(manifest, *, run_id_source: str) -> None:
+    from collections import Counter
+
+    run = manifest.run
+    console.print(f"\n[bold]Bundle[/bold] {run.run_id} [dim]({run_id_source})[/dim]")
+    console.print(f"[dim]steppy {run.steppy_version} · executor {run.executor} · created {run.created_at}[/dim]")
+    if run.git.sha:
+        branch = f" on {run.git.branch}" if run.git.branch else ""
+        pr = f" (PR #{run.git.pr})" if run.git.pr else ""
+        console.print(f"[dim]git {run.git.sha[:12]}{branch}{pr}[/dim]")
+
+    spec = run.spec
+    dimensions = []
+    if spec.locales:
+        dimensions.append(f"locales {', '.join(spec.locales)}")
+    if spec.layouts:
+        dimensions.append(f"layouts {', '.join(spec.layouts)}")
+    if spec.guide:
+        dimensions.append("guide mode")
+    if spec.coverage:
+        dimensions.append("coverage")
+    if dimensions:
+        console.print(f"[dim]{' · '.join(dimensions)}[/dim]")
+
+    if manifest.tests:
+        outcomes = Counter(t.outcome for t in manifest.tests)
+        parts = [f"{count} {name}" for name, count in sorted(outcomes.items())]
+        console.print(f"\n[bold]Tests[/bold] ({len(manifest.tests)}): {', '.join(parts)}")
+    else:
+        console.print("\n[bold]Tests[/bold]: none recorded")
+
+    kinds = Counter(f.kind for f in manifest.files)
+    total = sum(f.size for f in manifest.files)
+    console.print(f"[bold]Files[/bold] ({len(manifest.files)}, {_human(total)}):")
+    for kind, count in sorted(kinds.items()):
+        kind_size = sum(f.size for f in manifest.files if f.kind == kind)
+        console.print(f"  [dim]{kind:<22}[/dim] {count:>5}  {_human(kind_size)}")
+
+    if manifest.coverage and manifest.coverage.records:
+        console.print(f"[bold]Coverage[/bold]: {manifest.coverage.records} raw record(s)")
+    if manifest.truncated:
+        console.print("[yellow]TRUNCATED[/yellow] — some artifacts were dropped to fit the size budget")
+    for warning in manifest.warnings:
+        console.print(f"[yellow]WARNING[/yellow] {warning}")
+
+
+@bundle_app.command("create")
+def create(
+    output: Optional[Path] = typer.Option(
+        None,
+        "--output",
+        "-o",
+        help="Where to write the bundle. A directory gets a generated filename; "
+        "a path with an extension is used verbatim. "
+        "Default: output/bundles/steppy-bundle-<run-id>.tar.zst",
+    ),
+    run_id: Optional[str] = typer.Option(
+        None,
+        "--run-id",
+        help="Run identity for manifest.run.run_id. Defaults to the run recorded "
+        "in output/.steppy-run.json, else the newest recorded run on disk.",
+    ),
+    fmt: str = typer.Option(
+        "auto",
+        "--format",
+        help="Compression: auto (zstd when the steppy-dev[bundle] extra is installed, else gzip), zst, or gz.",
+    ),
+    project_root: Path = typer.Option(Path("."), "--project-root", help="Project root."),
+    output_dir: Optional[Path] = typer.Option(
+        None, "--output-dir", help="The tree to archive. Default: <project-root>/output"
+    ),
+    executor: str = typer.Option("local", "--executor", help="What ran the tests: local, github-actions, agent, ..."),
+    git_sha: Optional[str] = typer.Option(None, "--git-sha", help="Override the detected commit sha."),
+    git_branch: Optional[str] = typer.Option(None, "--git-branch", help="Override the detected branch."),
+    pr: Optional[int] = typer.Option(None, "--pr", help="Pull-request number this run belongs to."),
+    guides: bool = typer.Option(True, "--guides/--no-guides", help="Include output/guides/."),
+    traces: bool = typer.Option(True, "--traces/--no-traces", help="Include output/traces/."),
+    videos: bool = typer.Option(True, "--videos/--no-videos", help="Include output/videos/."),
+    coverage: bool = typer.Option(True, "--coverage/--no-coverage", help="Include output/coverage/."),
+    max_size: str = typer.Option(
+        "0",
+        "--max-size",
+        help="Uncompressed payload budget, e.g. 2GiB. Over budget, the cheapest-to-lose "
+        "artifacts are dropped (videos, then traces, then guides) and the manifest is "
+        "marked truncated. 0 disables the budget.",
+    ),
+    dry_run: bool = typer.Option(False, "--dry-run", help="Show what would be archived; write nothing."),
+    as_json: bool = typer.Option(False, "--json", help="Print the manifest as JSON instead of a summary."),
+) -> None:
+    """Package a run's output/ tree into a results bundle.
+
+    The archive holds output/ exactly as steppy wrote it — no path rewriting —
+    so unpacking it gives a tree `steppy guide` and `steppy build` consume
+    unchanged. Alongside it sit a manifest.json describing every file, a merged
+    junit.xml, and the run's per-test event records.
+
+    Run your scenarios with `steppy run --bundle` first: that captures the event
+    records and JUnit XML a plain run does not produce. Without them the bundle
+    is still valid, but manifest.tests[] will be empty.
+    """
+    with _cli_errors():
+        from .bundle import BundleError, create_bundle
+        from .bundle.create import manifest_bytes
+
+        try:
+            result = create_bundle(
+                project_root=project_root,
+                output_dir=output_dir,
+                target=output,
+                run_id=run_id,
+                fmt=fmt,
+                executor=executor,
+                git_sha=git_sha,
+                git_branch=git_branch,
+                pr=pr,
+                guides=guides,
+                traces=traces,
+                videos=videos,
+                coverage=coverage,
+                max_size=_parse_size(max_size),
+                dry_run=dry_run,
+            )
+        except BundleError as e:
+            _error(str(e))
+            raise typer.Exit(1)
+
+        if as_json:
+            typer.echo(manifest_bytes(result.manifest).decode("utf-8"), nl=False)
+            raise typer.Exit(0)
+
+        _print_summary(result.manifest, run_id_source=result.run_id_source)
+        if dry_run:
+            console.print(f"\n[dim]Dry run — nothing written. Format would be: {result.fmt}[/dim]")
+        else:
+            ratio = f" ({100 * result.compressed_size / result.payload_size:.0f}%)" if result.payload_size else ""
+            console.print(
+                f"\n[green]OK[/green] {result.path} [dim]{_human(result.compressed_size)}{ratio}, {result.fmt}[/dim]"
+            )
+
+
+def _config_cloud_url(project_root: Path) -> Optional[str]:
+    """``cloud.url`` from the project's config, or None.
+
+    A config that does not load is not an error here — the flag and the
+    environment variable both still work, and refusing to upload a finished run
+    because ``config.yaml`` no longer parses would be the same poor trade
+    ``resolve_roots`` already declines to make.
+    """
+    try:
+        from .config import load_config
+
+        config = load_config(project_root / "config.yaml")
+    except Exception:
+        return None
+    return config.cloud.url if config.cloud else None
+
+
+@bundle_app.command("upload")
+def upload(
+    bundle_path: Optional[Path] = typer.Argument(
+        None,
+        help="An existing .tar.zst/.tar.gz bundle to upload. Omit to upload straight "
+        "from output/ without writing an archive (the usual case).",
+    ),
+    url: Optional[str] = typer.Option(
+        None, "--url", help="Control plane base URL. Else $STEPPY_CLOUD_URL, else cloud.url."
+    ),
+    token: Optional[str] = typer.Option(
+        None, "--token", help="Project token. Else $STEPPY_CLOUD_TOKEN. There is no config key for it on purpose."
+    ),
+    attach: Optional[str] = typer.Option(
+        None,
+        "--attach",
+        help="Id of an existing run on the plane to upload into, instead of creating one. "
+        "What `steppy ci run` will use, where the plane created the run first.",
+    ),
+    run_id: Optional[str] = typer.Option(
+        None,
+        "--run-id",
+        help="Run identity for manifest.run.run_id, as in `bundle create`. Doubles as the "
+        "idempotency key, so re-uploading attaches to the same run rather than making a second.",
+    ),
+    project_root: Path = typer.Option(Path("."), "--project-root", help="Project root."),
+    output_dir: Optional[Path] = typer.Option(
+        None, "--output-dir", help="The tree to upload. Default: <project-root>/output"
+    ),
+    executor: str = typer.Option("local", "--executor", help="What ran the tests, recorded on a created run."),
+    exit_code: Optional[int] = typer.Option(
+        None, "--exit-code", help="The run's verdict. Default: derived from the manifest's test outcomes."
+    ),
+    git_sha: Optional[str] = typer.Option(None, "--git-sha", help="Override the detected commit sha."),
+    git_branch: Optional[str] = typer.Option(None, "--git-branch", help="Override the detected branch."),
+    pr: Optional[int] = typer.Option(None, "--pr", help="Pull-request number this run belongs to."),
+    guides: bool = typer.Option(True, "--guides/--no-guides", help="Include output/guides/."),
+    traces: bool = typer.Option(True, "--traces/--no-traces", help="Include output/traces/."),
+    videos: bool = typer.Option(True, "--videos/--no-videos", help="Include output/videos/."),
+    coverage: bool = typer.Option(True, "--coverage/--no-coverage", help="Include output/coverage/."),
+    max_size: str = typer.Option("0", "--max-size", help="Uncompressed payload budget, e.g. 2GiB. 0 disables it."),
+    concurrency: int = typer.Option(4, "--concurrency", min=1, help="Parallel uploads (ignored for an archive)."),
+    timeout: float = typer.Option(60.0, "--timeout", help="Per-request timeout, seconds."),
+    dry_run: bool = typer.Option(False, "--dry-run", help="Show what would be uploaded; contact nothing."),
+    as_json: bool = typer.Option(False, "--json", help="Print the outcome as JSON."),
+) -> None:
+    """Push a run's results to a Steppy control plane.
+
+    Uploads are content-addressed: the server is offered the manifest and hands
+    back URLs only for the files it does not already hold, so a re-run that
+    changed two screenshots uploads two screenshots. Interrupted? Run it again —
+    it attaches to the same run and sends only what is missing.
+
+    Run your scenarios with `steppy run --bundle` first. Two things depend on
+    it: the per-test event records, without which the plane gets an empty
+    tests[] and no failure detail; and the run identity in
+    output/.steppy-run.json, which is the idempotency key that makes a retried
+    upload attach rather than create a second run. Without a recorded identity
+    a fresh one is minted per invocation — pass --run-id to pin it, or --attach
+    to upload into a run that already exists.
+    """
+    with _cli_errors():
+        from .bundle import BundleError, plan_bundle
+        from .cloud import ArchiveSource, CloudError, TreeSource, cloud_client, derive_exit_code, upload_bundle
+
+        try:
+            if bundle_path is not None:
+                source = ArchiveSource(bundle_path)
+            else:
+                source = TreeSource(
+                    plan_bundle(
+                        project_root=project_root,
+                        output_dir=output_dir,
+                        run_id=run_id,
+                        git_sha=git_sha,
+                        git_branch=git_branch,
+                        pr=pr,
+                        guides=guides,
+                        traces=traces,
+                        videos=videos,
+                        coverage=coverage,
+                        max_size=_parse_size(max_size),
+                        executor=executor,
+                    )
+                )
+        except BundleError as e:
+            _error(str(e))
+            raise typer.Exit(1)
+
+        manifest = source.manifest
+        if dry_run:
+            _print_summary(manifest, run_id_source="planned")
+            console.print(
+                f"\n[dim]Dry run — nothing uploaded. {len(manifest.files)} file(s), "
+                f"{_human(sum(f.size for f in manifest.files))} before dedup; "
+                f"verdict would be exit {derive_exit_code(manifest) if exit_code is None else exit_code}.[/dim]"
+            )
+            raise typer.Exit(0)
+
+        try:
+            client = cloud_client(url=url, token=token, config_url=_config_cloud_url(project_root), timeout=timeout)
+        except CloudError as e:
+            _error(str(e))
+            raise typer.Exit(1)
+
+        with client:
+            try:
+                outcome = _run_upload(
+                    upload_bundle,
+                    client,
+                    source,
+                    run_id=attach,
+                    executor=executor,
+                    exit_code=exit_code,
+                    concurrency=concurrency,
+                )
+            except CloudError as e:
+                _error(str(e))
+                raise typer.Exit(1)
+
+        if as_json:
+            typer.echo(_json.dumps(outcome.as_dict(), indent=2))
+            raise typer.Exit(0)
+
+        _print_upload_summary(outcome, client.endpoint.url)
+
+
+def _run_upload(upload_bundle, client, source, *, run_id, executor, exit_code, concurrency):
+    """Drive the upload behind a byte-oriented progress bar.
+
+    Progress is measured in bytes rather than files: a bundle is a handful of
+    megabyte screenshots among hundreds of tiny sidecars, so a file counter
+    would sit at 90% for most of the wall clock.
+    """
+    from rich.progress import BarColumn, Progress, TextColumn, TimeElapsedColumn
+
+    total = sum(f.size for f in source.manifest.files)
+    with Progress(
+        TextColumn("[progress.description]{task.description}"),
+        BarColumn(),
+        TextColumn("{task.fields[sent]}"),
+        TimeElapsedColumn(),
+        console=console,
+        transient=True,
+    ) as progress:
+        bar = progress.add_task("uploading", total=total or 1, sent="")
+        sent = 0
+
+        def advance(blob) -> None:
+            nonlocal sent
+            sent += blob.size
+            progress.update(bar, completed=sent, sent=_human(sent))
+
+        return upload_bundle(
+            client,
+            source,
+            run_id=run_id,
+            executor=executor,
+            exit_code=exit_code,
+            concurrency=concurrency,
+            on_progress=advance,
+        )
+
+
+def _print_upload_summary(outcome, base_url: str) -> None:
+    verb = "Created run" if outcome.created_run else "Uploaded to run"
+    console.print(f"\n[bold]{verb}[/bold] #{outcome.run_number} [dim]{outcome.run_id}[/dim]")
+
+    # Blobs, not files: uploads are content-addressed, so a screenshot that is
+    # byte-identical across two locales is one upload serving two manifest
+    # entries. Reporting "3 of 4 files" for that would be a lie in both numbers.
+    if outcome.uploaded:
+        console.print(
+            f"[bold]Uploaded[/bold] {outcome.uploaded} of {outcome.total_blobs} blob(s), "
+            f"{_human(outcome.uploaded_bytes)} [dim]({outcome.total_files} file(s))[/dim]"
+        )
+    else:
+        console.print("[bold]Uploaded[/bold] nothing — the server already held every blob in this run")
+    if outcome.skipped_bytes:
+        console.print(f"[dim]{_human(outcome.skipped_bytes)} not sent — already held (content-addressed dedup)[/dim]")
+
+    for warning in outcome.warnings:
+        console.print(f"[yellow]WARNING[/yellow] {warning}")
+
+    colour = {"completed": "green", "failed": "red", "error": "red", "expired": "red", "canceled": "yellow"}.get(
+        outcome.run_status, "yellow"
+    )
+    console.print(f"[bold]Status[/bold] [{colour}]{outcome.run_status}[/{colour}]")
+    console.print(f"[dim]{base_url}/runs/{outcome.run_id}[/dim]")
+
+
+@bundle_app.command("inspect")
+def inspect(
+    bundle_path: Path = typer.Argument(..., help="Path to a .tar.zst or .tar.gz bundle."),
+    as_json: bool = typer.Option(False, "--json", help="Print the raw manifest JSON."),
+) -> None:
+    """Print a bundle's manifest without extracting it."""
+    with _cli_errors():
+        from .bundle import BundleError, inspect_bundle
+        from .bundle.create import manifest_bytes
+
+        try:
+            manifest = inspect_bundle(bundle_path)
+        except BundleError as e:
+            _error(str(e))
+            raise typer.Exit(1)
+
+        if as_json:
+            typer.echo(manifest_bytes(manifest).decode("utf-8"), nl=False)
+            raise typer.Exit(0)
+        _print_summary(manifest, run_id_source="archived")
+
+
+@bundle_app.command("verify")
+def verify(
+    bundle_path: Path = typer.Argument(..., help="Path to a .tar.zst or .tar.gz bundle."),
+    as_json: bool = typer.Option(False, "--json", help="Print the problem list as JSON."),
+) -> None:
+    """Re-hash every archived file against the manifest.
+
+    Exits non-zero if anything is missing, extra, or corrupted.
+    """
+    with _cli_errors():
+        from .bundle import BundleError, verify_bundle
+
+        try:
+            manifest, problems = verify_bundle(bundle_path)
+        except BundleError as e:
+            _error(str(e))
+            raise typer.Exit(1)
+
+        if as_json:
+            typer.echo(_json.dumps({"ok": not problems, "problems": problems}, indent=2))
+            raise typer.Exit(1 if problems else 0)
+
+        if problems:
+            _error(f"{len(problems)} problem(s) in {bundle_path.name}:")
+            for problem in problems:
+                console.print(f"  [red]·[/red] {problem}")
+            raise typer.Exit(1)
+        console.print(f"[green]OK[/green] {bundle_path.name}: {len(manifest.files)} file(s) match the manifest")

steppy/captures.py

@@ -0,0 +1,207 @@
+"""Capture-path grammar — the filename and directory shape of ``output/screenshots``.
+
+The *write* side of this grammar lives in the generated conftest
+(``_screenshot_folder`` / ``take_screenshot`` in ``templates/conftest.py.j2``):
+a capture lands at
+
+    <screenshots_dir>/<slug>/[<locale>/][<layout>/]step-NN[-<frame>].(png|json)
+
+with the locale segment appended before the layout segment, and either omitted
+when that dimension is not parametrized.
+
+Three consumers have to agree on that shape, and historically each answered it
+independently (see :meth:`steppy.guide.GuideAssembler.resolve_capture_segments`
+for what that cost): the guide read side, the build's copy/URL side, and — since
+the results bundle — the *inverse* direction, turning a path found on disk back
+into ``(scenario, locale, layout, step, frame)``.
+
+This module is the one home for the grammar — including its *root*, which
+:func:`resolve_output_dir` derives from ``config.output`` for every consumer
+that used to hardcode ``output/screenshots`` of its own (FLAWS §4.6).
+
+It is a **leaf**: stdlib only, no ``jinja2``/``markdown_it``/``pydantic``, so
+the bundler can import it without dragging ``guide.py``'s rendering stack onto
+the default CLI path. ``guide.py`` re-exports :func:`step_stem` and
+:func:`_has_captures` so its own callers are unaffected.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+
+#: ``step-07.png``, ``step-07.json``, ``step-07-b.png``. The step number is
+#: written zero-padded to two digits but matched more loosely — a scenario with
+#: 100+ steps must not silently stop being recognised.
+STEP_FILE_RE = re.compile(r"^step-(\d{2,})(?:-([a-z]+))?\.(png|json)$")
+
+#: Directory holding full-page screenshots of failed tests, keyed by a sanitised
+#: pytest nodeid rather than by scenario/step. Written by the generated
+#: conftest's ``pytest_runtest_makereport`` hook.
+FAILURES_DIRNAME = "_failures"
+
+#: Fallbacks for ``config.output.*``. The grammar above hangs off a *root*, and
+#: that root is the last piece of it that used to be re-derived per consumer —
+#: four independent copies of the same literal (FLAWS §4.6). These are the only
+#: two left, and the generated conftest carries a third by necessity (it is
+#: standalone rendered code and cannot import this module).
+DEFAULT_SCREENSHOTS_DIR = "output/screenshots"
+DEFAULT_GUIDES_DIR = "output/guides"
+#: Canonical in-app tour tree (``<tours_dir>/<build-id>/``); see ``steppy.tours``.
+DEFAULT_TOURS_DIR = "output/tours"
+
+
+def resolve_output_dir(project_root: Path, configured: Optional[str], default: str) -> Path:
+    """Resolve a ``config.output.*`` value against the project root.
+
+    A relative value (``./output/screenshots``) lands under the project; an
+    absolute one wins outright. Both are plain ``Path.__truediv__`` semantics,
+    deliberately — the same rule the conftest applies to
+    ``coverage.records_dir``, so writer and readers cannot disagree.
+
+    An empty/absent value falls back to *default*, because ``CONFIG`` is raw
+    YAML on the writer side: an absent ``output:`` block yields ``None`` there
+    and pydantic's ``default_factory`` never runs.
+    """
+    return (Path(project_root) / (configured or default)).resolve()
+
+
+def step_stem(step_index: int, frame: Optional[str] = None) -> str:
+    """Filename stem for a captured step: ``step-07`` or ``step-07-b``.
+
+    One definition shared by the read side (guide.py) and the build's URL
+    builders, so a change to the capture naming scheme can't half-land.
+    """
+    return f"step-{step_index:02d}" + (f"-{frame}" if frame else "")
+
+
+def _has_captures(directory: Path) -> bool:
+    """True when *directory* actually holds screenshots.
+
+    The single definition of "this is a capture directory". Existence alone is
+    not enough: the generated conftest's ``_screenshot_folder`` mkdirs before
+    calling ``page.screenshot``, so an interrupted run leaves empty directories
+    behind, and a per-locale directory that only holds per-layout subdirs holds
+    no captures of its own.
+    """
+    return directory.is_dir() and any(directory.glob("step-*.png"))
+
+
+@dataclass(frozen=True)
+class StepFile:
+    """A parsed capture filename. The inverse of :func:`step_stem`."""
+
+    step: int
+    frame: Optional[str]
+    ext: str  # "png" | "json"
+
+
+def parse_step_stem(filename: str) -> Optional[StepFile]:
+    """Parse ``step-NN[-<frame>].(png|json)``. ``None`` when it isn't one.
+
+    Round-trips with :func:`step_stem`::
+
+        parse_step_stem(step_stem(7, "b") + ".png") == StepFile(7, "b", "png")
+    """
+    match = STEP_FILE_RE.match(filename)
+    if match is None:
+        return None
+    number, frame, ext = match.groups()
+    return StepFile(step=int(number), frame=frame, ext=ext)
+
+
+@dataclass(frozen=True)
+class CaptureRef:
+    """A capture file located in the screenshots tree."""
+
+    scenario: str
+    locale: Optional[str]
+    layout: Optional[str]
+    step: int
+    frame: Optional[str]
+    ext: str
+
+
+def classify_capture_path(
+    rel_parts: tuple[str, ...] | list[str],
+    *,
+    locales: frozenset[str] | set[str] = frozenset(),
+    layouts: frozenset[str] | set[str] = frozenset(),
+) -> Optional[CaptureRef]:
+    """Invert the capture path shape. ``rel_parts`` is relative to the
+    screenshots dir, e.g. ``("order-lifecycle", "fr", "mobile", "step-01.png")``.
+
+    Returns ``None`` for anything that is not a step capture — including the
+    ``_failures/`` tree, whose filenames are sanitised pytest nodeids rather
+    than steps.
+
+    The middle segments are what need deciding, and only one case is genuinely
+    ambiguous:
+
+      * **0 segments** — flat/legacy capture, ``(None, None)``.
+      * **2 segments** — unambiguous. The writer appends locale then layout, in
+        that order, and never any other pair.
+      * **1 segment** — ``<slug>/fr/`` and ``<slug>/desktop/`` are structurally
+        identical, so the name is the only signal. Resolved by membership in the
+        configured sets; when it matches neither (a locale or layout removed
+        from ``config.yaml`` after the capture), it is read as a **locale**,
+        mirroring the "locale beats layout" precedence
+        :meth:`~steppy.guide.GuideAssembler.resolve_capture_segments` documents
+        — the locale determines the language actually visible in the image, and
+        mislabelling that is worse than mislabelling a viewport.
+    """
+    parts = tuple(rel_parts)
+    if len(parts) < 2 or parts[0] == FAILURES_DIRNAME:
+        return None
+
+    parsed = parse_step_stem(parts[-1])
+    if parsed is None:
+        return None
+
+    scenario = parts[0]
+    middle = parts[1:-1]
+
+    if len(middle) == 0:
+        locale, layout = None, None
+    elif len(middle) == 1:
+        segment = middle[0]
+        if segment in locales:
+            locale, layout = segment, None
+        elif segment in layouts:
+            locale, layout = None, segment
+        else:
+            locale, layout = segment, None
+    elif len(middle) == 2:
+        locale, layout = middle[0], middle[1]
+    else:
+        # Deeper than the writer can produce — not ours to interpret.
+        return None
+
+    return CaptureRef(
+        scenario=scenario,
+        locale=locale,
+        layout=layout,
+        step=parsed.step,
+        frame=parsed.frame,
+        ext=parsed.ext,
+    )
+
+
+def sanitise_nodeid(nodeid: str) -> str:
+    """Make a pytest nodeid filesystem-safe. Mirror of ``_sanitise_nodeid``.
+
+    **Byte-mirrored** from ``_sanitise_nodeid`` in ``templates/conftest.py.j2``,
+    which names the failure screenshots, traces and videos. Guard:
+    ``tests/test_nodeid_sanitiser_mirror.py`` — same arrangement as
+    ``totp._totp_now`` (CLAUDE.md). Apply any change to both.
+
+    The mapping is **lossy and not invertible**: a slug containing ``_`` is
+    indistinguishable from a separator, and ``(fr-mobile)`` cannot be told from
+    a literal parenthesis in a test name. So consumers must build the *forward*
+    map — sanitise every nodeid they know about and look filenames up in it —
+    never attempt to reverse a filename.
+    """
+    return nodeid.replace("/", "_").replace("\\", "_").replace("::", "__").replace("[", "(").replace("]", ")")