steppy-dev 0.3.0__py3-none-any.whl

steppy/coverage_cli.py

@@ -0,0 +1,265 @@
+"""Coverage-map CLI commands (`steppy coverage ...`).
+
+Extracted from cli.py (FLAWS §4.2) — these ~200 lines are a self-contained
+sub-app that the god module no longer needs to carry.
+
+Everything under `steppy coverage` lazy-imports steppy.coverage.* — plain
+runs never load it (tests/test_no_coverage_import_on_default_path.py). Keep
+all ``from .coverage.* import`` statements *inside* the command bodies so
+importing this module (which `import steppy.cli` does) stays coverage-free.
+"""
+
+from pathlib import Path
+from typing import Optional
+
+import typer
+from rich.markup import escape
+from rich.table import Table
+
+from ._cli_common import console, _cli_errors, _error
+from .config import load_config
+
+coverage_app = typer.Typer(
+    name="coverage",
+    help="Coverage map: record with `steppy run --coverage`, refresh the declared "
+    "surface from OpenAPI/sitemap manifests, report what is NOT yet tested.",
+    add_completion=False,
+)
+
+triage_app = typer.Typer(
+    name="triage",
+    help="Persisted per-node triage flags (ui_testable | non_ui | unknown). "
+    "Survive merges and manifest refreshes — flag webhooks/cron callbacks "
+    "non_ui once and the gap report discounts them forever. These live in "
+    ".steppy/coverage.db, which is gitignored: for CI (and the badge), declare "
+    "coverage.non_ui patterns in config.yaml instead, and use these commands for "
+    "the one-off a pattern should not cover.",
+    add_completion=False,
+)
+coverage_app.add_typer(triage_app, name="triage")
+
+
+def _coverage_settings():
+    from .coverage.merge import CoverageSettings
+
+    return CoverageSettings.from_config(load_config(), Path.cwd())
+
+
+def _utc_now() -> str:
+    import time as _time
+
+    return _time.strftime("%Y-%m-%dT%H:%M:%SZ", _time.gmtime())
+
+
+@coverage_app.command("refresh")
+def coverage_refresh(
+    api: Optional[str] = typer.Option(
+        None, "--api", help="Refresh only this configured API (default: all APIs + sitemap)."
+    ),
+):
+    """Fetch the configured OpenAPI manifest(s) (and optional sitemap) into the
+    declared surface, then re-link previously observed endpoints onto newly
+    declared templates. Never touches triage flags; nodes are never deleted."""
+    with _cli_errors():
+        settings = _coverage_settings()
+        if not settings.apis and not settings.sitemap:
+            console.print(
+                "[red]ERROR[/red] No coverage.apis (or coverage.sitemap) configured — "
+                "add a `coverage:` block to config.yaml"
+            )
+            raise typer.Exit(1)
+        apis = settings.apis
+        if api is not None:
+            apis = [a for a in settings.apis if a["name"] == api]
+            if not apis:
+                names = [a["name"] for a in settings.apis]
+                console.print(f"[red]ERROR[/red] Unknown API {api!r}; configured: {names}")
+                raise typer.Exit(1)
+
+        from .coverage.manifest import refresh_declared
+        from .coverage.store import open_store
+
+        conn = open_store(settings.store_path)
+        try:
+            summary = refresh_declared(
+                conn,
+                apis,
+                settings.sitemap if api is None else None,
+                settings.route_param_patterns,
+                updated_at=_utc_now(),
+            )
+        finally:
+            conn.close()
+        for entry in summary["apis"]:
+            console.print(
+                f"[green]OK[/green] {entry['source']}: {entry['declared']} declared "
+                f"endpoint(s), {entry['removed']} removed"
+            )
+        if summary["sitemap"]:
+            console.print(
+                f"[green]OK[/green] sitemap: {summary['sitemap']['declared']} declared "
+                f"route(s), {summary['sitemap']['removed']} removed"
+            )
+        if summary["relinked"]:
+            console.print(
+                f"[dim]{summary['relinked']} observed contribution(s) re-linked onto declared endpoints[/dim]"
+            )
+
+
+@coverage_app.command("report")
+def coverage_report(
+    json_path: Optional[Path] = typer.Option(
+        None, "--json", help="Also write the machine-readable report (deterministic JSON) here."
+    ),
+    badge_path: Optional[Path] = typer.Option(
+        None,
+        "--badge",
+        help="Also write a shields.io endpoint JSON for the e2e-surface percentage here.",
+    ),
+    badge_surface: str = typer.Option(
+        "all",
+        "--badge-surface",
+        help="Surface the badge measures: all (endpoints + routes), endpoints, or routes.",
+    ),
+    badge_label: Optional[str] = typer.Option(
+        None, "--badge-label", help="Left-hand text on the badge (default: 'e2e surface')."
+    ),
+):
+    """Compute and print the gap report: tested, declared-unreached (the key
+    bucket), discovered-uncovered, plus unclassified requests and the covered
+    module inventory."""
+    with _cli_errors():
+        settings = _coverage_settings()
+        if not Path(settings.store_path).exists():
+            console.print(
+                f"[red]ERROR[/red] No coverage store at {settings.store_path} — "
+                "record a run first: steppy run --coverage"
+            )
+            raise typer.Exit(1)
+
+        from .coverage.gaps import SURFACES, compute_gaps
+        from .coverage.report import DEFAULT_BADGE_LABEL, badge_to_json, gaps_to_json, print_summary
+        from .coverage.store import open_store, read_map
+        from .coverage.triage import apply_config_triage, unmatched_patterns
+
+        if badge_surface not in SURFACES:
+            _error(f"--badge-surface must be one of {', '.join(SURFACES)} (got {badge_surface!r})")
+            raise typer.Exit(1)
+
+        conn = open_store(settings.store_path)
+        try:
+            raw_map = read_map(conn)
+        finally:
+            conn.close()
+
+        # The committed ``coverage.non_ui`` declarations are a read-time overlay:
+        # applied here, never written to the store, so merge/refresh stay free of
+        # triage and a pattern edit takes effect without re-recording anything.
+        map_view = apply_config_triage(raw_map, settings.non_ui)
+        gaps = compute_gaps(map_view)
+
+        # A pattern that matches nothing silently inflates the percentage — the
+        # exact failure this feature exists to prevent — so it is worth a line.
+        stale = unmatched_patterns(map_view, settings.non_ui)
+        if stale:
+            console.print(
+                f"[yellow]WARNING[/yellow] {len(stale)} coverage.non_ui pattern(s) matched nothing: "
+                f"{escape(', '.join(stale))}"
+            )
+            console.print("[dim]A renamed or retired endpoint leaves a stale rule that inflates the percentage.[/dim]")
+
+        print_summary(gaps, console)
+        if json_path is not None:
+            json_path.parent.mkdir(parents=True, exist_ok=True)
+            json_path.write_text(gaps_to_json(gaps), encoding="utf-8")
+            console.print(f"[dim]JSON report written to {json_path}[/dim]")
+        if badge_path is not None:
+            badge_path.parent.mkdir(parents=True, exist_ok=True)
+            badge_path.write_text(
+                badge_to_json(gaps, surface=badge_surface, label=badge_label or DEFAULT_BADGE_LABEL),
+                encoding="utf-8",
+            )
+            console.print(f"[dim]Badge endpoint written to {badge_path}[/dim]")
+
+
+@coverage_app.command("merge")
+def coverage_merge(
+    run_id: Optional[str] = typer.Option(
+        None, "--run-id", help="Run directory to merge (default: latest under <records_dir>/raw)."
+    ),
+):
+    """Merge raw run records into the map. Rescue path — `steppy run --coverage`
+    merges automatically; use this after a crashed/interrupted run. Idempotent:
+    re-merging a run replaces each scenario's contribution, it never doubles."""
+    with _cli_errors():
+        settings = _coverage_settings()
+        from .coverage.merge import merge_run
+
+        summary = merge_run(settings, run_id)
+        console.print(
+            f"[green]OK[/green] Merged run {summary['run_id']}: "
+            f"{summary['totals']['scenarios']} scenario(s), "
+            f"{summary['totals']['nodes']} map node(s) → {settings.store_path}"
+        )
+        for warning in summary.get("warnings", []):
+            console.print(f"[yellow]WARNING[/yellow] {warning}")
+
+
+@triage_app.command("set")
+def coverage_triage_set(
+    path: str = typer.Argument(
+        ..., help="Node key: endpoint path template (e.g. '/webhooks/stripe') or route pattern."
+    ),
+    flag: str = typer.Option(..., "--flag", help="ui_testable | non_ui | unknown"),
+    method: str = typer.Option("", "--method", help="HTTP method (endpoints only)."),
+    api: str = typer.Option("", "--api", help="API name from coverage.apis (endpoints only)."),
+    kind: str = typer.Option("endpoint", "--kind", help="endpoint | route | module"),
+    note: str = typer.Option("", "--note", help="Why, e.g. 'Payment provider callback — not UI-reachable'."),
+):
+    """Persist a triage flag on a node (created if not yet in the map). The
+    flag survives every merge and refresh and is never reset."""
+    with _cli_errors():
+        settings = _coverage_settings()
+        from .coverage.store import open_store, set_triage
+
+        conn = open_store(settings.store_path)
+        try:
+            set_triage(
+                conn,
+                kind=kind,
+                key=path,
+                api=api,
+                method=method.upper(),
+                flag=flag,
+                note=note,
+                updated_at=_utc_now(),
+            )
+        finally:
+            conn.close()
+        console.print(f"[green]OK[/green] {kind} {method.upper()} {path} → {flag}")
+
+
+@triage_app.command("list")
+def coverage_triage_list(
+    flag: Optional[str] = typer.Option(None, "--flag", help="Filter by flag value."),
+):
+    """List persisted triage flags."""
+    with _cli_errors():
+        settings = _coverage_settings()
+        from .coverage.store import list_triage, open_store
+
+        if not Path(settings.store_path).exists():
+            console.print("[dim]No coverage store yet — nothing triaged[/dim]")
+            return
+        conn = open_store(settings.store_path)
+        try:
+            rows = list_triage(conn, flag)
+        finally:
+            conn.close()
+        if not rows:
+            console.print("[dim]No triage flags set[/dim]")
+            return
+        table = Table("kind", "api", "method", "key", "flag", "note")
+        for row in rows:
+            table.add_row(row["kind"], row["api"], row["method"], row["key"], row["flag"], row["note"])
+        console.print(table)

steppy/durations.py

@@ -0,0 +1,48 @@
+"""Duration parsing, shared by the model validator and codegen.
+
+``timeout:`` is written by a scenario author and consumed by the generator, so
+the grammar has to be the same in both places or ``steppy validate`` accepts a
+value the generator then mangles — the shape of bug ``steppy.assertions`` was
+extracted to close. Stdlib only: ``models.py`` is on the eager CLI path.
+
+The grammar matches the ``wait`` action's ``duration:`` exactly, including its
+bare-number-means-milliseconds rule, so an author never has to remember two.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Union
+
+__all__ = ["DurationSyntaxError", "parse_ms"]
+
+
+class DurationSyntaxError(ValueError):
+    """Raised when a duration string is not ``<number>[ms|s]``."""
+
+
+_DURATION = re.compile(r"^\s*(\d+(?:\.\d+)?)\s*(ms|s)?\s*$")
+
+
+def parse_ms(value: Union[str, int, float]) -> int:
+    """Return ``value`` in whole milliseconds.
+
+    ``"25s"`` -> 25000, ``"500ms"`` -> 500, ``25000`` -> 25000. A bare number is
+    milliseconds — the same rule ``generator._format_wait_duration`` applies to
+    ``wait``'s ``duration:``.
+    """
+    if isinstance(value, bool):  # bool is an int subclass; a timeout of True is a typo
+        raise DurationSyntaxError(f"duration must be a number or a string, got {value!r}")
+    if isinstance(value, (int, float)):
+        ms = float(value)
+    else:
+        match = _DURATION.match(str(value))
+        if not match:
+            raise DurationSyntaxError(
+                f'duration {value!r} is not understood. Use e.g. "25s", "500ms", or a bare number of milliseconds'
+            )
+        number, unit = float(match.group(1)), match.group(2)
+        ms = number * 1000 if unit == "s" else number
+    if ms <= 0:
+        raise DurationSyntaxError(f"duration must be positive, got {value!r}")
+    return int(round(ms))

steppy/exclusive.py

@@ -0,0 +1,178 @@
+"""Exclusion groups — scenarios that must never run concurrently.
+
+A scenario opts in with a frontmatter ``exclusive: <name>``. Two scenarios naming
+the same group never run at the same time under ``steppy run --workers N``, while
+different groups still run concurrently and ungrouped scenarios are untouched.
+
+This module is the one home for two things:
+
+  * the **group-name grammar**, because the name becomes a filename component
+    (``claims/<task_id>.claim`` is built by string concatenation), and
+  * the **partition**, which collapses each group into a single queue task.
+
+Mutual exclusion is therefore a property of how the queue was *seeded* — decided
+once, single-threaded, on the host, before any container exists — rather than a
+run-time protocol. There is no lock, so nothing leaks when a worker is killed, no
+lease to renew, no timeout to tune, and no worker ever waits on another. The only
+run-time primitive involved is the O_EXCL claim the queue already performs.
+
+Stdlib-only leaf: it imports nothing from ``steppy``, so ``models.py`` can import
+it on the eager CLI path (like ``assertions`` and ``durations``) without tripping
+the no-parallel-import guard, while ``_parallel/queue.py`` and ``coordinator.py``
+import the same module lazily.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Optional
+
+
+class ExclusiveGroupSyntaxError(ValueError):
+    """Raised when a scenario's ``exclusive:`` value is not a usable group name."""
+
+
+# The group name becomes a path component under the run's coordination directory,
+# so this pattern is a security control and not a style rule: it rejects ``..``,
+# both separators, leading dots, and anything else that could escape the run's
+# tmp dir with the CI runner's privileges. Lowercase-only is equally load-bearing
+# — the coordination directory is created on the HOST, and NTFS and APFS are
+# case-insensitive by default, so `Payments` and `payments` would collapse into
+# one claim file and one of the two batches would silently never run.
+GROUP_NAME_RE = re.compile(r"^[a-z0-9][a-z0-9._+-]{0,63}$")
+MAX_GROUP_NAME_LEN = 64
+
+# Reserved on Windows for the basename *before* the extension, so `con.claim` is
+# un-creatable just as `con` is. Cheap to reject here; baffling to diagnose when
+# it surfaces as a Docker error on one developer's machine and nowhere in CI.
+_WINDOWS_RESERVED = frozenset(
+    {"con", "prn", "aux", "nul"} | {f"com{i}" for i in range(1, 10)} | {f"lpt{i}" for i in range(1, 10)}
+)
+
+# Naming the combination of two resources does NOT exclude a scenario against one
+# named after a single resource: 'stripe-and-mailbox' and 'stripe' are two group
+# names, so they are two tasks and they run concurrently. The only safe reading of
+# a one-name-per-scenario model is transitive, so say so rather than suggesting a
+# fusion that produces exactly the bug the field exists to prevent.
+_CLOSURE_RULE = (
+    "a scenario belongs to at most one exclusion group. If a flow contends on two "
+    "shared resources, every scenario touching EITHER resource must use the SAME "
+    "group name — naming the combination (e.g. 'stripe-and-mailbox') does not "
+    "exclude it against a scenario named 'stripe', so the two would still run "
+    "concurrently"
+)
+
+
+def normalize_group_name(value: object) -> str:
+    """Validate one ``exclusive:`` frontmatter value and return the group name.
+
+    Raises :class:`ExclusiveGroupSyntaxError` with an actionable message for every
+    rejection. A list or dict is refused outright rather than being fused, because
+    the fusion an author would reach for is unsound — see ``_CLOSURE_RULE``.
+    """
+    if isinstance(value, (list, tuple, set, dict)):
+        raise ExclusiveGroupSyntaxError(f"'exclusive' takes a single group name, not a list: {_CLOSURE_RULE}")
+    if not isinstance(value, str):
+        raise ExclusiveGroupSyntaxError(f"'exclusive' must be a string group name, got {type(value).__name__}")
+
+    name = value.strip()
+    if not name:
+        raise ExclusiveGroupSyntaxError("'exclusive' must be a non-empty group name (or omitted)")
+    if len(name) > MAX_GROUP_NAME_LEN:
+        raise ExclusiveGroupSyntaxError(
+            f"exclusion group name is too long ({len(name)} > {MAX_GROUP_NAME_LEN}): {name!r}"
+        )
+    if not GROUP_NAME_RE.match(name):
+        raise ExclusiveGroupSyntaxError(
+            f"invalid exclusion group name {name!r}. Use lowercase letters, digits, "
+            "'.', '_', '+' or '-', starting with a letter or digit. The name becomes "
+            "a filename in the run's coordination directory, and uppercase is rejected "
+            "because Windows and macOS filesystems would silently merge it with a "
+            "lowercase twin."
+        )
+    if name in _WINDOWS_RESERVED:
+        raise ExclusiveGroupSyntaxError(
+            f"exclusion group name {name!r} is a reserved device name on Windows and "
+            "cannot be used as a filename there. Pick another name."
+        )
+    return name
+
+
+@dataclass(frozen=True)
+class Task:
+    """One unit of work in the queue.
+
+    ``task_id`` is the key used for ``queue/NNNN-<task_id>.task`` and
+    ``claims/<task_id>.claim``: the bare slug for an ungrouped scenario, the group
+    name for a batch. ``slugs`` is the execution order — always exactly one entry
+    when ``group`` is None, which is what makes an ungrouped run byte-identical to
+    the pre-feature queue.
+    """
+
+    task_id: str
+    slugs: tuple[str, ...]
+    group: Optional[str] = None
+
+    @property
+    def is_batch(self) -> bool:
+        return self.group is not None
+
+
+def partition(ordered_slugs: list[str], group_of: dict[str, Optional[str]]) -> list[Task]:
+    """Collapse each exclusion group into one :class:`Task`, preserving order.
+
+    An ungrouped slug becomes its own task; a grouped slug is appended to its
+    group's task, which occupies the position of the group's **first** member.
+    Members keep selection order inside the batch — deterministic and debuggable;
+    ordering them by duration would buy nothing, since a batch's total is fixed.
+
+    With no groups this returns one singleton task per slug in the same order,
+    which is what keeps the seeded queue directory byte-identical.
+
+    Grouped and ungrouped entries are keyed separately, so a group named after an
+    *ungrouped* scenario produces two tasks that share an id rather than one task
+    that quietly swallows the loose scenario. That distinction is load-bearing:
+    merging them would leave a task whose ``group`` is None but whose ``slugs``
+    holds two entries, which ``seed`` writes with no payload — and the second
+    scenario would then never run, and be reported nowhere.
+    :func:`duplicate_task_ids` is what turns the collision into an error.
+    """
+    order: list[tuple[bool, str]] = []
+    members: dict[tuple[bool, str], list[str]] = {}
+
+    for slug in ordered_slugs:
+        group = group_of.get(slug)
+        key = (True, group) if group else (False, slug)
+        if key not in members:
+            members[key] = []
+            order.append(key)
+        members[key].append(slug)
+
+    return [
+        Task(task_id=name, slugs=tuple(members[(grouped, name)]), group=name if grouped else None)
+        for grouped, name in order
+    ]
+
+
+def duplicate_task_ids(tasks: list[Task]) -> list[tuple[str, str]]:
+    """Task ids that collide once case is folded, as ``(first, duplicate)`` pairs.
+
+    Exact-string uniqueness is not enough: the coordination directory lives on the
+    host, and on a case-insensitive filesystem two ids differing only in case share
+    one claim file — the second worker's O_EXCL fails, it concludes the queue is
+    drained, and a whole task silently never runs while the run still exits 0.
+
+    Checking the resulting *id set* rather than "group name versus slug" is also
+    what keeps ``exclusive: checkout`` legal on a scenario slugged ``checkout``,
+    which is the most natural name there is.
+    """
+    seen: dict[str, str] = {}
+    dupes: list[tuple[str, str]] = []
+    for task in tasks:
+        key = task.task_id.casefold()
+        if key in seen:
+            dupes.append((seen[key], task.task_id))
+        else:
+            seen[key] = task.task_id
+    return dupes

steppy/flaky_cli.py

@@ -0,0 +1,169 @@
+"""``steppy flaky`` — rank scenarios by how often they cost you attention.
+
+Reads the append-only history that parallel runs leave at
+``.steppy/history.jsonl`` (see :mod:`steppy.history`) and answers the question a
+single run's summary cannot: *which* of my three hundred scenarios are the
+unreliable ones? That ranking is the whole point — a list of five slugs is
+actionable in a way that twenty separate red runs never were.
+
+A leaf module, like ``coverage_cli``: it imports ``_cli_common`` and
+``history`` (stdlib-only) and nothing from ``cli`` / ``coordinator`` /
+``_parallel``, so ``import steppy.cli`` stays free of parallel-mode code
+(``tests/test_no_parallel_import_on_default_path.py``).
+"""
+
+from __future__ import annotations
+
+import json as _json
+from pathlib import Path
+from typing import Optional
+
+import typer
+from rich.table import Table
+
+from ._cli_common import _cli_errors, console
+
+
+DEFAULT_WINDOW = 20
+
+
+def _rate_style(rate: float) -> str:
+    if rate >= 0.5:
+        return "bold red"
+    if rate >= 0.2:
+        return "yellow"
+    return "dim"
+
+
+def register_flaky(app: typer.Typer) -> None:
+    """Attach the ``flaky`` command to the root Typer app."""
+
+    @app.command("flaky")
+    def flaky(
+        last: int = typer.Option(
+            DEFAULT_WINDOW,
+            "--last",
+            "-n",
+            min=1,
+            help=f"Consider only the N most recent runs (default: {DEFAULT_WINDOW}).",
+        ),
+        min_rate: float = typer.Option(
+            0.0,
+            "--min-rate",
+            min=0.0,
+            max=1.0,
+            help="Only show scenarios whose flake rate is at least this (0.0-1.0). "
+            "e.g. --min-rate 0.2 hides anything that misbehaved in under a fifth of runs.",
+        ),
+        limit: int = typer.Option(20, "--limit", min=1, help="Maximum rows to print."),
+        as_json: bool = typer.Option(False, "--json", help="Emit machine-readable JSON instead of a table."),
+        prune_to: Optional[int] = typer.Option(
+            None,
+            "--prune",
+            min=1,
+            help="Rewrite the history file keeping only the newest N runs, then exit.",
+        ),
+    ):
+        """Rank scenarios by flakiness across recent runs.
+
+        History is recorded by parallel runs (`steppy run --workers N`); the
+        single-worker path produces no per-scenario records, so runs made with
+        `--workers 1` do not appear here.
+
+        The flake rate counts every run where a scenario did not pass first
+        try — outright failures included. A scenario failing 7 of 10 runs is not
+        healthier than one flaking 7 of 10; both cost the same attention.
+        """
+        with _cli_errors():
+            from .history import flake_stats, history_path, load, prune
+
+            project_root = Path.cwd()
+
+            if prune_to is not None:
+                dropped = prune(project_root, keep_runs=prune_to)
+                console.print(f"[green]OK[/green] Pruned {dropped} record(s); kept the newest {prune_to} run(s).")
+                raise typer.Exit(0)
+
+            path = history_path(project_root)
+            records = load(project_root, last_runs=last)
+            if not records:
+                if as_json:
+                    console.print_json(data={"runs": 0, "scenarios": []})
+                    raise typer.Exit(0)
+                console.print(f"[yellow]No run history yet[/yellow] [dim]({path})[/dim]")
+                console.print(
+                    "\nHistory is written by parallel runs. Record some with:\n  [bold]steppy run --workers 4[/bold]"
+                )
+                raise typer.Exit(0)
+
+            run_count = len({r["run_id"] for r in records})
+            stats = [s for s in flake_stats(records) if s.flake_rate >= min_rate]
+
+            if as_json:
+                console.print_json(
+                    _json.dumps(
+                        {
+                            "runs": run_count,
+                            "window": last,
+                            "scenarios": [
+                                {
+                                    "slug": s.slug,
+                                    "runs": s.runs,
+                                    "failures": s.failures,
+                                    "flakes": s.flakes,
+                                    "flake_rate": round(s.flake_rate, 4),
+                                    "median_s": s.median_s,
+                                    "p95_s": s.p95_s,
+                                    "last_outcome": s.last_outcome,
+                                    "fingerprints": s.fingerprints,
+                                }
+                                for s in stats[:limit]
+                            ],
+                        }
+                    )
+                )
+                raise typer.Exit(0)
+
+            if not stats:
+                console.print(
+                    f"[green]✓[/green] No scenario exceeded a {min_rate:.0%} flake rate "
+                    f"across the last {run_count} run(s)."
+                )
+                raise typer.Exit(0)
+
+            table = Table(title=f"Flakiest scenarios — last {run_count} run(s)", title_justify="left")
+            table.add_column("scenario", overflow="fold")
+            table.add_column("runs", justify="right")
+            table.add_column("fail", justify="right")
+            table.add_column("flaky", justify="right")
+            table.add_column("rate", justify="right")
+            table.add_column("median", justify="right")
+            table.add_column("p95", justify="right")
+            table.add_column("last")
+
+            for s in stats[:limit]:
+                table.add_row(
+                    s.slug,
+                    str(s.runs),
+                    f"[red]{s.failures}[/red]" if s.failures else "0",
+                    f"[yellow]{s.flakes}[/yellow]" if s.flakes else "0",
+                    f"[{_rate_style(s.flake_rate)}]{s.flake_rate:.0%}[/{_rate_style(s.flake_rate)}]",
+                    f"{s.median_s:.0f}s" if s.median_s is not None else "—",
+                    f"{s.p95_s:.0f}s" if s.p95_s is not None else "—",
+                    s.last_outcome,
+                )
+            console.print(table)
+
+            hidden = len(stats) - min(limit, len(stats))
+            if hidden > 0:
+                console.print(f"[dim]… and {hidden} more (raise --limit to see them)[/dim]")
+
+            # A scenario that always fails the same way is a bug, not a flake —
+            # worth saying out loud, because the two need opposite responses.
+            consistent = [s for s in stats[:limit] if len(s.fingerprints) == 1 and s.failures]
+            if consistent:
+                console.print(
+                    f"\n[dim]{len(consistent)} scenario(s) always fail the same way "
+                    f"(single fingerprint) — likely a real bug, not contention.[/dim]"
+                )
+            console.print(f"[dim]source: {path}[/dim]")