steppy-dev 0.3.0__py3-none-any.whl

steppy/coverage/report.py

@@ -0,0 +1,178 @@
+"""Render the gap report: deterministic JSON, a shields badge, a human summary."""
+
+from __future__ import annotations
+
+import json
+
+_MAX_ROWS = 50
+
+#: shields.io endpoint colours, coarsest-first. Deliberately the palette a
+#: README already uses for test/coverage badges, so a Steppy badge sits in a row
+#: of them without looking foreign.
+_BADGE_COLORS = ((50, "red"), (70, "orange"), (85, "yellow"), (95, "green"))
+_BADGE_COLOR_BEST = "brightgreen"
+_BADGE_COLOR_UNKNOWN = "lightgrey"
+
+DEFAULT_BADGE_LABEL = "e2e surface"
+
+
+def gaps_to_json(gaps: dict) -> str:
+    """Machine-readable report: sorted keys, no wall clock — diffable."""
+    return json.dumps(gaps, indent=2, sort_keys=True)
+
+
+def badge_color(percent: int) -> str:
+    """Shields colour for a percentage."""
+    for ceiling, color in _BADGE_COLORS:
+        if percent < ceiling:
+            return color
+    return _BADGE_COLOR_BEST
+
+
+def badge_payload(gaps: dict, *, surface: str = "all", label: str = DEFAULT_BADGE_LABEL) -> dict:
+    """A shields.io **endpoint** object for the e2e surface ratio.
+
+    An endpoint JSON rather than a generated SVG: it inherits whatever style the
+    rest of the README's badge row uses, it is cacheable by shields, and no image
+    rendering lands in this repo. Consumed as
+    ``https://img.shields.io/endpoint?url=<raw-url-to-this-file>``.
+
+    Nothing declared ⇒ ``"n/a"`` in grey. A badge reading ``0%`` when the truth is
+    "no OpenAPI surface is configured" is worse than one admitting it does not
+    know, because the first invites someone to go fix a number that is not broken.
+    """
+    ratio = (gaps.get("e2e_surface") or {}).get(surface) or {}
+    percent = ratio.get("percent")
+    if percent is None:
+        return {"schemaVersion": 1, "label": label, "message": "n/a", "color": _BADGE_COLOR_UNKNOWN}
+    return {
+        "schemaVersion": 1,
+        "label": label,
+        "message": f"{percent}%",
+        "color": badge_color(percent),
+    }
+
+
+def badge_to_json(gaps: dict, *, surface: str = "all", label: str = DEFAULT_BADGE_LABEL) -> str:
+    """:func:`badge_payload` as deterministic JSON text."""
+    return json.dumps(badge_payload(gaps, surface=surface, label=label), indent=2, sort_keys=True) + "\n"
+
+
+def _print_bucket_table(console, title: str, rows: list[dict], columns: list[str]) -> None:
+    from rich.table import Table
+
+    table = Table(title=f"{title} ({len(rows)})", title_justify="left")
+    for col in columns:
+        table.add_column(col)
+    for row in rows[:_MAX_ROWS]:
+        table.add_row(*(str(row.get(col, "")) for col in columns))
+    console.print(table)
+    if len(rows) > _MAX_ROWS:
+        console.print(f"[dim]… and {len(rows) - _MAX_ROWS} more (see --json output)[/dim]")
+
+
+def _count_sources(entries: list[dict]) -> list[tuple[str, int]]:
+    """``[(source, count)]`` sorted for stable output."""
+    tally: dict[str, int] = {}
+    for entry in entries:
+        source = entry.get("triage_source", "")
+        tally[source] = tally.get(source, 0) + 1
+    return sorted(tally.items())
+
+
+def _print_surface(gaps: dict, console) -> None:
+    """The one line the badge is derived from, so the two can never disagree."""
+    ratio = (gaps.get("e2e_surface") or {}).get("all") or {}
+    percent = ratio.get("percent")
+    if percent is None:
+        console.print(
+            "[bold]E2E surface[/bold]: not measured — nothing declared. "
+            "Configure [bold]coverage.apis[/bold] (and optionally [bold]coverage.sitemap[/bold]), "
+            "then run [bold]steppy coverage refresh[/bold].\n"
+        )
+        return
+    console.print(
+        f"[bold]E2E surface[/bold]: {percent}% "
+        f"({ratio['tested']}/{ratio['declared']} declared endpoints + routes a UI test could reach)\n"
+    )
+
+
+def print_summary(gaps: dict, console) -> None:
+    """Short human summary: counts first, then the bucket lists."""
+    counts = gaps["counts"]
+    ep = counts["endpoints"]
+    console.print(
+        f"[bold]Endpoints[/bold]: {ep['declared']} declared | "
+        f"{ep['tested']} tested ({ep['tested_strong']} strong) | "
+        f"[red]{ep['declared_unreached']} declared-unreached[/red] "
+        f"({ep['declared_unreached_actionable']} actionable, rest non_ui) | "
+        f"{ep['discovered_uncovered']} discovered-uncovered | "
+        f"{ep['unclassified']} unclassified"
+    )
+    rt = counts["routes"]
+    console.print(
+        f"[bold]Routes[/bold]:    {rt['declared']} declared | {rt['tested']} tested | "
+        f"[red]{rt['declared_unreached']} declared-unreached[/red] | "
+        f"{rt['discovered_uncovered']} discovered-uncovered"
+    )
+    console.print(
+        f"[bold]Modules[/bold]:   {counts['modules']['covered']} covered | scenarios in map: {counts['scenarios']}"
+    )
+    _print_surface(gaps, console)
+
+    unreached = gaps["endpoints"]["declared_unreached"]
+    actionable = [e for e in unreached if e["triage"] != "non_ui"]
+    if actionable:
+        _print_bucket_table(
+            console,
+            "Declared but unreached (actionable)",
+            actionable,
+            ["api", "method", "key", "triage", "note"],
+        )
+    non_ui = [e for e in unreached if e["triage"] == "non_ui"]
+    if non_ui:
+        by_source = _count_sources(non_ui)
+        detail = ", ".join(f"{n} from {src or 'unspecified'}" for src, n in by_source)
+        console.print(f"[dim]{len(non_ui)} declared-unreached triaged non_ui, hidden ({detail})[/dim]")
+
+    if gaps["endpoints"]["discovered_uncovered"]:
+        _print_bucket_table(
+            console,
+            "Discovered but weakly covered (endpoints)",
+            gaps["endpoints"]["discovered_uncovered"],
+            ["api", "method", "key", "scenarios"],
+        )
+    if gaps["routes"]["declared_unreached"]:
+        _print_bucket_table(
+            console,
+            "Declared but unreached (routes)",
+            gaps["routes"]["declared_unreached"],
+            ["key", "triage", "note"],
+        )
+    if gaps["routes"]["discovered_uncovered"]:
+        _print_bucket_table(
+            console,
+            "Discovered but weakly covered (routes)",
+            gaps["routes"]["discovered_uncovered"],
+            ["key", "scenarios"],
+        )
+    if gaps["endpoints"]["unclassified"]:
+        console.print(
+            f"[yellow]{len(gaps['endpoints']['unclassified'])} unclassified API request "
+            "pattern(s)[/yellow] — requests matching no configured coverage.apis base_urls; "
+            "check base_urls (include internal_url origins for parallel runs)."
+        )
+    if gaps["endpoints"]["discovered_tested"]:
+        console.print(
+            f"[yellow]{len(gaps['endpoints']['discovered_tested'])} tested endpoint(s) missing "
+            "from the manifest[/yellow] — stale spec or base-URL prefix mismatch; "
+            "run `steppy coverage refresh`."
+        )
+
+    declared_total = ep["declared"]
+    if declared_total and ep["tested"] == 0:
+        console.print(
+            "[yellow]No declared endpoint was ever matched by an observed request — "
+            "if scenarios did run, coverage.apis base_urls probably don't mirror the "
+            "OpenAPI servers[].url prefix.[/yellow]"
+        )

steppy/coverage/sourcemap.py

@@ -0,0 +1,219 @@
+"""Source-map decoding: executed V8 offsets -> source modules. Pure Python.
+
+The recorder (generated conftest) persists, per script: the executed function
+start offsets (V8 character offsets), a ``line_starts`` newline-offset table
+computed from the script source, and a reference to the source map (inline
+``data:`` maps are decoded + stored at record time; external maps are looked
+up on local disk at merge time via ``coverage.sourcemap_dir``).
+
+This module turns those into source-module sets:
+
+  offset --(bisect over line_starts)--> (generated line, col)
+         --(floor lookup in the decoded mappings line index)--> sources[idx]
+         --(webpack:// / sourceRoot / dot-segment normalization, ignore
+            filter)--> module key
+
+Degradation ladder (per script, never an error): usable map -> module keys;
+unusable/missing map or missing line_starts -> a single ``bundle:<url-path>``
+node so the signal survives at bundle granularity.
+"""
+
+from __future__ import annotations
+
+import gzip
+import json
+import posixpath
+import re
+from bisect import bisect_right
+from pathlib import Path
+from urllib.parse import urlsplit
+
+_B64 = {c: i for i, c in enumerate("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/")}
+_SCHEME_RE = re.compile(r"^[a-zA-Z][\w+.\-]*://")
+
+
+class SourceMapUnusable(Exception):
+    """Structural problem with a map — caller degrades to bundle granularity."""
+
+
+def _decode_vlq_segment(segment: str) -> list[int]:
+    values: list[int] = []
+    result = shift = 0
+    for ch in segment:
+        try:
+            digit = _B64[ch]
+        except KeyError:
+            raise SourceMapUnusable(f"invalid VLQ character {ch!r}") from None
+        result |= (digit & 31) << shift
+        if digit & 32:
+            shift += 5
+        else:
+            values.append(-(result >> 1) if result & 1 else result >> 1)
+            result = shift = 0
+    if shift:
+        raise SourceMapUnusable("truncated VLQ segment")
+    return values
+
+
+def build_line_index(mappings: str) -> list[tuple[list[int], list[int]]]:
+    """Decode ``mappings`` into per-generated-line ``(gen_cols, src_idxs)``.
+
+    ``gen_col`` resets per line; ``src_idx`` accumulates across lines (spec
+    behaviour). Segments without a source field get ``src_idx = -1``.
+    """
+    lines: list[tuple[list[int], list[int]]] = []
+    src_idx = 0
+    for line_str in mappings.split(";"):
+        cols: list[int] = []
+        idxs: list[int] = []
+        gen_col = 0
+        for seg in line_str.split(","):
+            if not seg:
+                continue
+            fields = _decode_vlq_segment(seg)
+            gen_col += fields[0]
+            if len(fields) >= 4:
+                src_idx += fields[1]
+                cols.append(gen_col)
+                idxs.append(src_idx)
+            else:
+                cols.append(gen_col)
+                idxs.append(-1)
+        lines.append((cols, idxs))
+    return lines
+
+
+def normalize_source_path(source: str, source_root: str = "") -> str:
+    """Normalize a source-map ``sources`` entry to a stable module key.
+
+    Resolves against ``sourceRoot``, strips scheme prefixes (``webpack://``,
+    ``ng://`` …) and leading slashes, and collapses dot segments. Webpack
+    namespace components (``webpack://my-app/src/…``) are kept — they are
+    stable across runs and can be ignored via ``coverage.module_ignore``.
+    """
+    s = source
+    if source_root:
+        root = source_root if source_root.endswith("/") else source_root + "/"
+        if not _SCHEME_RE.match(s) and not s.startswith("/"):
+            s = root + s
+    m = _SCHEME_RE.match(s)
+    if m:
+        s = s[m.end() :]
+    s = s.lstrip("/")
+    if s:
+        s = posixpath.normpath(s)
+        if s == ".":
+            s = ""
+    return s
+
+
+def is_ignored(module: str, ignore: tuple[str, ...]) -> bool:
+    """True when ``module`` falls under any ignore entry (prefix or any path level)."""
+    for entry in ignore:
+        clean = entry.rstrip("/")
+        if not clean:
+            continue
+        if module == clean or module.startswith(clean + "/"):
+            return True
+        if f"/{clean}/" in f"/{module}":
+            return True
+    return False
+
+
+def modules_for_script(
+    executed_offsets: list[int],
+    line_starts: list[int],
+    map_obj: dict,
+    ignore: tuple[str, ...] = (),
+) -> set[str]:
+    """Map executed character offsets to the set of executed source modules.
+
+    Raises :class:`SourceMapUnusable` on structural problems (index maps,
+    missing sources, malformed VLQ) so the caller can fall back to bundle
+    granularity. Offsets that hit no mapping segment are silently skipped.
+    """
+    if not isinstance(map_obj, dict):
+        raise SourceMapUnusable("map is not a JSON object")
+    if "sections" in map_obj:
+        raise SourceMapUnusable("index maps (sections) not supported")
+    sources = map_obj.get("sources") or []
+    if not sources:
+        raise SourceMapUnusable("map has no sources")
+    if not line_starts:
+        raise SourceMapUnusable("missing line_starts")
+    source_root = map_obj.get("sourceRoot") or ""
+    normalized = [normalize_source_path(s or "", source_root) for s in sources]
+    line_index = build_line_index(map_obj.get("mappings") or "")
+
+    modules: set[str] = set()
+    for offset in executed_offsets:
+        line = bisect_right(line_starts, offset) - 1
+        if line < 0 or line >= len(line_index):
+            continue
+        col = offset - line_starts[line]
+        cols, idxs = line_index[line]
+        i = bisect_right(cols, col) - 1
+        if i < 0:
+            continue
+        idx = idxs[i]
+        if 0 <= idx < len(normalized):
+            module = normalized[idx]
+            if module and not is_ignored(module, ignore):
+                modules.add(module)
+    return modules
+
+
+def bundle_key(script_url: str) -> str:
+    """Fallback module key when no usable map exists for a script."""
+    path = urlsplit(script_url).path
+    return f"bundle:{path or script_url}"
+
+
+def load_map_for_entry(
+    entry: dict,
+    maps_dir: Path | None,
+    sourcemap_dir: Path | None,
+) -> dict | None:
+    """Resolve the source map for one recorded script entry.
+
+    Order: inline blob persisted by the recorder (``_maps/<sha256>.json.gz``)
+    -> local-disk lookup under ``sourcemap_dir`` (by sourceMappingURL
+    basename, then ``<script-basename>.map``; recursive, lexicographically
+    first match) -> ``None`` (bundle fallback).
+    """
+    map_info = entry.get("map") or {}
+    if map_info.get("kind") == "inline" and map_info.get("hash") and maps_dir is not None:
+        blob = Path(maps_dir) / f"{map_info['hash']}.json.gz"
+        if blob.is_file():
+            try:
+                return json.loads(gzip.decompress(blob.read_bytes()).decode("utf-8"))
+            except (OSError, ValueError):
+                return None
+
+    if sourcemap_dir is None:
+        return None
+    sourcemap_dir = Path(sourcemap_dir)
+    if not sourcemap_dir.is_dir():
+        return None
+
+    candidates: list[str] = []
+    if map_info.get("kind") == "external" and map_info.get("url"):
+        name = posixpath.basename(urlsplit(map_info["url"]).path)
+        if name:
+            candidates.append(name)
+    script_name = posixpath.basename(urlsplit(entry.get("url") or "").path)
+    if script_name:
+        candidates.append(script_name + ".map")
+
+    seen: set[str] = set()
+    for name in candidates:
+        if name in seen:
+            continue
+        seen.add(name)
+        matches = sorted(sourcemap_dir.rglob(name), key=lambda p: p.as_posix())
+        for match in matches:
+            try:
+                return json.loads(match.read_text(encoding="utf-8"))
+            except (OSError, ValueError):
+                continue
+    return None