steppy-dev 0.3.0__py3-none-any.whl

steppy/report/__init__.py

@@ -0,0 +1,37 @@
+"""``steppy report``: one results bundle rendered to a self-contained static site.
+
+**Lazy-imported only.** Nothing here may be reached by ``import steppy.cli`` —
+this package walks and hashes an ``output/`` tree, opens tar archives and builds a
+Jinja environment, none of which belongs on the path a plain ``steppy run`` (or
+``steppy --help``) takes. Every ``steppy.report`` import lives inside a
+``report_cli`` command body. Guard:
+``tests/test_no_report_import_on_default_path.py``.
+
+**A note on the name**, because "report" already means four things here and a
+fifth would be one too many. ``config.yaml``'s ``report:`` block
+(:class:`steppy.models.ReportConfig`) is about *pytest* artifacts — JUnit XML, an
+HTML report, traces, videos, reruns. The ``steppy-dev[report]`` extra is pytest-html.
+``bundle``'s file-kind ``report`` labels those artifacts inside an archive. And
+``steppy coverage report`` prints the gap buckets. This package is none of them:
+it is the *run report site* — the thing you publish to GitHub or GitLab Pages.
+
+What it is, and just as importantly what it is not. The report **transforms one
+bundle**. That is a structural property, not a restriction: with a single run's
+artifacts there is nothing to diff against, no history to rank flakes by, and no
+baseline anyone accepted. Those need memory, and memory lives in a control plane.
+
+Module map:
+
+- ``source``   — three inputs (live tree / archive / unpacked dir), one protocol.
+- ``model``    — the pure view-model builder. **No jinja2**, deliberately: this is
+  the module a control plane imports, and it must not drag a renderer along.
+- ``assets``   — which captures travel, where they land, and how they dedupe.
+- ``coverage_source`` — the four-tier coverage resolution and the badge number.
+- ``render``   — jinja2 → HTML, CSS, ``report.json``, ``badge.json``, robots.
+- ``build``    — orchestration, :class:`ReportError`, :class:`ReportResult`.
+
+This file re-exports **nothing**, on purpose. ``from steppy.report import
+build_report`` would make importing ``steppy.report.model`` pull in the renderer
+and therefore jinja2 — which is exactly what the model/render split exists to
+prevent. Import the submodule you need (the same shape ``steppy.coverage`` uses).
+"""

steppy/report/assets.py

@@ -0,0 +1,197 @@
+"""Which captures travel into the report site, and where they land.
+
+Two jobs, and both are load-bearing for different reasons.
+
+**The policy.** ``all`` on a real corpus is scenarios × locales × layouts ×
+frames — hundreds of megabytes pushed to Pages on every run — so the default is
+``failed``: the captures of the variants that did not pass, plus every failure
+screenshot. A run report's job is diagnosis; the guide site is where every capture
+already lives. ``all`` is one flag away for a showcase repo that wants the full
+"look what CI verified" strip.
+
+**The naming.** Destinations are computed from *validated components*, never from
+a manifest path. That is a security boundary, not tidiness: a downloaded bundle's
+``BundleFile.path`` is attacker-controlled, and streaming tar members
+one-by-one skips Python's extraction filters — so ``../../evil.png`` must not be
+able to decide where anything is written. Every component is reduced to
+``[A-Za-z0-9._-]`` and the shape is fixed:
+
+    assets/<scenario>/<locale>-<layout>/step-NN[-frame].png
+    assets/_failures/<scenario>/<locale>-<layout>.png
+
+Captures are also deduped by ``sha256``, so a screenshot that is byte-identical
+across two layouts is copied once and both URLs point at it. On a guide corpus
+where only a handful of steps differ per layout, that is most of the payload.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+from ..contracts.bundle import BundleFile, BundleManifest
+
+#: Copy every step capture, only the ones belonging to a variant that did not
+#: pass, or none at all.
+POLICIES = ("failed", "all", "none")
+DEFAULT_POLICY = "failed"
+
+ASSETS_DIRNAME = "assets"
+FAILURES_DIRNAME = "_failures"
+
+#: Above this, a Pages deploy is heading for trouble — GitHub caps a published
+#: site at 1 GB and warns from 1 GB, so half of that is where saying something is
+#: still useful rather than merely alarming.
+WARN_BYTES = 500 * 1024 * 1024
+
+_SAFE = re.compile(r"[^A-Za-z0-9._-]+")
+_UNSET = "_"
+
+
+def sanitise(component: str) -> str:
+    """One path component, reduced to characters that cannot mean anything else.
+
+    Collapses runs of unsafe characters to ``-`` and strips leading/trailing dots
+    and dashes, so ``..``, ``/``, a drive letter or a NUL cannot survive into a
+    destination. Stripping the *trailing* dot matters too: Windows rejects a
+    filename that ends in one, and a report that renders on Linux and fails to
+    unzip on Windows is a bug someone else has to diagnose.
+    """
+    cleaned = _SAFE.sub("-", component or "").strip(".-")
+    return cleaned or _UNSET
+
+
+def variant_dirname(locale: Optional[str], layout: Optional[str]) -> str:
+    """``fr-mobile``, ``fr-_``, ``_-_`` — one directory per (locale, layout).
+
+    The ``_`` placeholder for an unset dimension mirrors the ``default`` sentinel
+    the capture path grammar and the event filenames already use: three writers,
+    one idea, so a missing dimension never silently merges two variants.
+    """
+    return f"{sanitise(locale or _UNSET)}-{sanitise(layout or _UNSET)}"
+
+
+@dataclass
+class AssetPlan:
+    """What to copy where, and the URL each manifest path resolves to."""
+
+    #: manifest path → destination file (absolute).
+    into: dict[str, Path] = field(default_factory=dict)
+    #: manifest path → site-relative URL. Includes deduped paths, whose URL points
+    #: at the one copy that was actually made.
+    urls: dict[str, str] = field(default_factory=dict)
+    #: Bytes the copies will occupy, after dedupe.
+    bytes: int = 0
+    warnings: list[str] = field(default_factory=list)
+
+    @property
+    def copies(self) -> int:
+        return len(self.into)
+
+
+def plan_assets(
+    manifest: BundleManifest,
+    *,
+    site_dir: Path,
+    policy: str = DEFAULT_POLICY,
+) -> AssetPlan:
+    """Decide which captures travel, under *policy*.
+
+    Failure screenshots always travel when the policy is not ``none``: they are the
+    single most useful artifact in a red run, and there are at most one per failing
+    variant.
+    """
+    if policy not in POLICIES:
+        raise ValueError(f"screenshot policy must be one of {', '.join(POLICIES)} (got {policy!r})")
+
+    plan = AssetPlan()
+    if policy == "none":
+        return plan
+
+    wanted_variants = _variants_to_include(manifest, policy)
+    by_digest: dict[str, str] = {}
+
+    for entry in _sorted_captures(manifest):
+        if entry.kind == "screenshot":
+            if (entry.scenario, entry.locale, entry.layout) not in wanted_variants:
+                continue
+            rel = _step_rel(entry)
+        else:  # failure_screenshot
+            rel = _failure_rel(entry)
+        if rel is None:
+            continue
+
+        existing = by_digest.get(entry.sha256)
+        if existing is not None:
+            # Byte-identical capture already copied — point at the one copy.
+            plan.urls[entry.path] = existing
+            continue
+        by_digest[entry.sha256] = rel
+        plan.urls[entry.path] = rel
+        plan.into[entry.path] = site_dir / Path(rel)
+        plan.bytes += entry.size
+
+    if plan.bytes > WARN_BYTES:
+        plan.warnings.append(
+            f"the report will copy {plan.bytes / (1024 * 1024):.0f} MiB of screenshots; "
+            "GitHub Pages caps a published site at 1 GB — consider --screenshots failed"
+        )
+    return plan
+
+
+def _sorted_captures(manifest: BundleManifest) -> list[BundleFile]:
+    """Captures in a stable order, so dedupe picks the same winner every run.
+
+    Which copy survives has to be deterministic or two renders of one bundle
+    produce different URLs, and the report stops being diffable.
+    """
+    captures = [f for f in manifest.files if f.kind in ("screenshot", "failure_screenshot")]
+    return sorted(captures, key=lambda f: f.path)
+
+
+def _variants_to_include(manifest: BundleManifest, policy: str) -> set[tuple]:
+    """The (scenario, locale, layout) keys whose step captures travel.
+
+    Under ``failed`` this is every variant that did not pass — and, when there are
+    no test rows at all (a run made without ``--bundle``), nothing: an empty set is
+    the honest answer, and the report says so rather than shipping the whole
+    corpus by accident.
+    """
+    if policy == "all":
+        return {(f.scenario, f.locale, f.layout) for f in manifest.files if f.kind == "screenshot"}
+    return {(t.scenario, t.locale, t.layout) for t in manifest.tests if t.outcome not in ("passed", "skipped")}
+
+
+def _step_rel(entry: BundleFile) -> Optional[str]:
+    if entry.step is None:
+        return None
+    stem = f"step-{entry.step:02d}" + (f"-{sanitise(entry.frame)}" if entry.frame else "")
+    return "/".join(
+        (
+            ASSETS_DIRNAME,
+            sanitise(entry.scenario or _UNSET),
+            variant_dirname(entry.locale, entry.layout),
+            f"{stem}{_suffix(entry.path)}",
+        )
+    )
+
+
+def _failure_rel(entry: BundleFile) -> str:
+    # One failure capture per (scenario, variant, fixture); the fixture name is
+    # already gone from the manifest, so a second one would collide. Including the
+    # digest prefix keeps both rather than silently dropping one.
+    return "/".join(
+        (
+            ASSETS_DIRNAME,
+            FAILURES_DIRNAME,
+            sanitise(entry.scenario or _UNSET),
+            f"{variant_dirname(entry.locale, entry.layout)}-{entry.sha256[:8]}{_suffix(entry.path)}",
+        )
+    )
+
+
+def _suffix(path: str) -> str:
+    suffix = Path(path).suffix.lower()
+    return suffix if re.fullmatch(r"\.[a-z0-9]{1,8}", suffix) else ".png"

steppy/report/build.py

@@ -0,0 +1,261 @@
+"""Orchestration: a run in, a static site out.
+
+The order matters in one place and is otherwise unremarkable. Assets are planned
+and copied **before** the model is built, because the model needs the URL each
+capture ended up at; and the target directory is validated **before** anything is
+removed, because ``-o`` is a path off the command line and one typo away from
+somewhere that matters.
+"""
+
+from __future__ import annotations
+
+import shutil
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional, Sequence
+
+from ..contracts.report import ReportModel, ReportSourceInfo
+
+#: Default site location. Deliberately *not* a ``config.output.*`` key: this root
+#: has one writer and no automated reader (a CI job names the path in its own
+#: upload step), and ``OutputConfig`` already carries a deprecated-and-inert
+#: ``reports_dir`` — a live ``report_dir`` one letter away would be a permanent
+#: trap in every future review of that file.
+DEFAULT_SITE_SUBDIR = "report"
+
+#: Files whose presence means "this is a directory that matters, not a stale site".
+#: A second lock on rmtree: even ``--force`` will not delete a project.
+GUARDED_NAMES = ("config.yaml", "pyproject.toml", ".git", "scenarios", "src")
+
+#: The site's own marker. ``report.json`` is already written at the root and
+#: self-identifies via ``steppy_report``, so there is no extra file to keep in sync.
+MARKER_NAME = "report.json"
+
+
+class ReportError(Exception):
+    """The report could not be produced. Always actionable."""
+
+
+@dataclass
+class ReportResult:
+    site_dir: Path
+    model: ReportModel
+    files: dict[str, str] = field(default_factory=dict)
+    copied: int = 0
+    copied_bytes: int = 0
+    warnings: list[str] = field(default_factory=list)
+
+    @property
+    def verdict(self) -> str:
+        return self.model.totals.verdict
+
+    def count(self, status: str) -> int:
+        return sum(1 for value in self.files.values() if value == status)
+
+
+def build_report(
+    *,
+    project_root: Path,
+    bundle: Optional[Path] = None,
+    site_dir: Optional[Path] = None,
+    output_dir: Optional[Path] = None,
+    run_id: Optional[str] = None,
+    screenshots: str = "failed",
+    badge_surface: str = "all",
+    badge_label: Optional[str] = None,
+    title: Optional[str] = None,
+    templates_dir: Optional[Path] = None,
+    non_ui: Sequence[str] = (),
+    force: bool = False,
+    dry_run: bool = False,
+) -> ReportResult:
+    """Render one run to a self-contained static site."""
+    from .. import __version__
+    from ..coverage.gaps import SURFACES
+    from .assets import POLICIES, plan_assets
+    from .coverage_source import resolve_coverage
+    from .model import build_model
+    from .render import render_site
+    from .source import ReportSourceError, open_source
+
+    # Validated before anything is read or removed: an unusable flag should cost
+    # the caller a message, not a half-written site. Both are checked here rather
+    # than only in Typer so a programmatic caller gets the same guarantee — and
+    # an unknown surface would otherwise render a silently empty badge, which is
+    # the worst of the three outcomes.
+    if screenshots not in POLICIES:
+        raise ReportError(f"--screenshots must be one of {', '.join(POLICIES)} (got {screenshots!r})")
+    if badge_surface not in SURFACES:
+        raise ReportError(f"--badge-surface must be one of {', '.join(SURFACES)} (got {badge_surface!r})")
+
+    try:
+        source = open_source(bundle, project_root=project_root, output_dir=output_dir, run_id=run_id)
+    except ReportSourceError as e:
+        raise ReportError(str(e)) from e
+
+    target = Path(site_dir) if site_dir else project_root / "output" / DEFAULT_SITE_SUBDIR
+    target = target.resolve()
+    _check_target(target, force=force, dry_run=dry_run)
+
+    warnings: list[str] = list(source.warnings)
+    warnings.extend(_placement_warnings(target, project_root))
+
+    plan = plan_assets(source.manifest, site_dir=target, policy=screenshots)
+    warnings.extend(plan.warnings)
+
+    if not dry_run:
+        _reset(target)
+        _, fetch_warnings = source.fetch(into=plan.into)
+        warnings.extend(fetch_warnings)
+
+    coverage = resolve_coverage(
+        source,
+        project_root=project_root,
+        non_ui=non_ui,
+        surface=badge_surface,
+        badge_label=badge_label,
+        href="coverage.html",
+    )
+
+    attempts = _timeline(source)
+    model = build_model(
+        manifest=source.manifest,
+        source=ReportSourceInfo(kind=source.kind, label=source.label),
+        attempts=attempts,
+        coverage=coverage,
+        assets=plan.urls,
+        screenshots_policy=screenshots,
+        steppy_version=__version__,
+        extra_warnings=warnings,
+    )
+
+    rendered = render_site(
+        model,
+        site_dir=target,
+        title=title or _default_title(model),
+        templates_dir=templates_dir,
+        project_root=project_root,
+        dry_run=dry_run,
+    )
+    return ReportResult(
+        site_dir=target,
+        model=model,
+        files=rendered.files,
+        copied=plan.copies,
+        copied_bytes=plan.bytes,
+        warnings=warnings,
+    )
+
+
+def _timeline(source) -> dict:
+    """``{nodeid: [TestAttempt]}`` from the run's event JSONL, or ``{}``.
+
+    Absent step events are a *capability*, not a failure: they exist only when the
+    run set ``STEPPY_STEP_EVENTS=1`` (which ``steppy run --bundle`` does), and a
+    tree generated before the markers existed emits none either. The model records
+    which, and the page says so.
+    """
+    from ..bundle.results import parse_event_lines, steps_from_records
+
+    wanted = {f.path for f in source.manifest.files if f.kind == "events"}
+    if not wanted:
+        return {}
+    fetched, _warnings = source.fetch(texts=wanted)
+    texts = [(name, payload.decode("utf-8", errors="replace")) for name, payload in sorted(fetched.items())]
+    records, _parse_warnings = parse_event_lines(texts)
+    return steps_from_records(records)
+
+
+def _default_title(model: ReportModel) -> str:
+    branch = model.run.git.branch
+    return f"Steppy run report — {branch}" if branch else "Steppy run report"
+
+
+def _check_target(target: Path, *, force: bool, dry_run: bool) -> None:
+    """Refuse to write where a mistake would be expensive.
+
+    ``steppy report -o <dir>`` takes its path from the command line, so ``-o .`` in
+    a project root is one keystroke away. Three checks, and the **order matters**:
+
+    1. Our own marker wins first. A directory holding ``report.json`` with a
+       ``steppy_report`` key is a previous render of this report, and re-rendering
+       into it is the normal case. This has to come first because the site itself
+       writes a ``scenarios/`` directory — which is also one of the signals below
+       that a directory is a *project*. Checking that first would refuse every
+       second render, permanently.
+    2. A directory that looks like a project (``config.yaml`` / ``pyproject.toml``
+       / ``.git`` / ``scenarios`` / ``src``) is refused **even with ``--force``**.
+       Nothing about rendering a report justifies deleting one of those. A
+       directory cannot become both, because step 2 refuses the first render into
+       a project before step 1 could ever have written a marker there.
+    3. Otherwise a non-empty directory needs ``--force``.
+    """
+    if not target.exists():
+        return
+    if not target.is_dir():
+        raise ReportError(f"{target} exists and is not a directory")
+
+    if _looks_like_a_report(target):
+        return
+
+    guarded = [name for name in GUARDED_NAMES if (target / name).exists()]
+    if guarded:
+        raise ReportError(
+            f"refusing to write a report into {target} — it contains {', '.join(sorted(guarded))}, "
+            "which makes it look like a project rather than a report directory. "
+            "Point -o at a dedicated directory (the default is output/report)."
+        )
+
+    if dry_run or not any(target.iterdir()) or force:
+        return
+    raise ReportError(
+        f"{target} is not empty and does not look like a Steppy report "
+        f"(no {MARKER_NAME} with a 'steppy_report' key). Pass --force to replace its contents, "
+        "or point -o somewhere else."
+    )
+
+
+def _looks_like_a_report(target: Path) -> bool:
+    import json
+
+    marker = target / MARKER_NAME
+    if not marker.is_file():
+        return False
+    try:
+        return "steppy_report" in json.loads(marker.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return False
+
+
+def _reset(target: Path) -> None:
+    """Clear the site so a removed scenario's page does not linger.
+
+    Only ever reached after :func:`_check_target` approved the path.
+    """
+    if target.exists():
+        shutil.rmtree(target)
+    target.mkdir(parents=True, exist_ok=True)
+
+
+def _placement_warnings(target: Path, project_root: Path) -> list[str]:
+    """Warn when the site lands somewhere ``bundle create`` will archive.
+
+    ``output/report/`` is skipped by the bundler by name. Anywhere else under
+    ``output/`` is not, so a later ``steppy bundle create`` would archive the whole
+    site — including every screenshot it copied — and roughly double the bundle.
+    """
+    output = (project_root / "output").resolve()
+    default = (output / DEFAULT_SITE_SUBDIR).resolve()
+    if target == default:
+        return []
+    try:
+        inside = target.is_relative_to(output)
+    except (OSError, ValueError):  # pragma: no cover - defensive
+        return []
+    if not inside:
+        return []
+    return [
+        f"the report is being written to {target}, which is inside output/ but is not "
+        f"output/{DEFAULT_SITE_SUBDIR} — a later `steppy bundle create` will archive it as run "
+        "artifacts, roughly doubling the bundle's screenshot payload"
+    ]