coverage-flashlight 1.0.0__py3-none-any.whl

coverage_flashlight/__init__.py

@@ -0,0 +1 @@
+"""Coverage reports and opt-in ordered Python execution recording."""

coverage_flashlight/__main__.py

@@ -0,0 +1,3 @@
+from coverage_flashlight.cli import main
+
+raise SystemExit(main())

coverage_flashlight/bootstrap/sitecustomize.py

@@ -0,0 +1,20 @@
+"""Opt-in child-process bootstrap; used only by the execution flashlight runner."""
+
+import importlib.machinery
+import importlib.util
+import os
+import sys
+from pathlib import Path
+
+# Preserve the environment's own startup customization.
+_here = Path(__file__).parent.resolve()
+_existing = importlib.machinery.PathFinder.find_spec(
+    "sitecustomize", [path for path in sys.path if Path(path).resolve() != _here]
+)
+if _existing is not None and _existing.loader is not None:
+    _existing.loader.exec_module(importlib.util.module_from_spec(_existing))
+
+if os.environ.get("COVERAGE_FLASHLIGHT_DIR"):
+    from coverage_flashlight.trace import install
+
+    install()

coverage_flashlight/cli.py

@@ -0,0 +1,107 @@
+"""The flashlight command; target arguments are passed through after --."""
+
+import argparse
+import subprocess
+from importlib.metadata import version
+from pathlib import Path
+
+from coverage.exceptions import CoverageException
+
+from coverage_flashlight.config import project_sources
+from coverage_flashlight.runner import measure, render_coverage
+
+
+def main(argv=None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="flashlight",
+        description="Explore Python coverage or replay executed lines.",
+    )
+    parser.add_argument(
+        "--version", action="version", version=version("coverage-flashlight")
+    )
+    commands = parser.add_subparsers(dest="command", required=True)
+    for name, help_text in [
+        ("pytest", "Measure each selected pytest case"),
+        ("run", "Execute a Python script or module once"),
+    ]:
+        command = commands.add_parser(name, help=help_text)
+        command.add_argument(
+            "--trace",
+            action="store_true",
+            help="record ordered execution instead of line/branch coverage",
+        )
+        command.add_argument(
+            "--source",
+            action="append",
+            help="project-relative source file or directory; repeat for multiple paths",
+        )
+        command.add_argument(
+            "--output",
+            type=Path,
+            help="HTML report path (default: htmlcov/flashlight.html or execution.html)",
+        )
+        command.add_argument(
+            "--data-file",
+            type=Path,
+            default=Path(".coverage"),
+            help="coverage database to replace (coverage mode only)",
+        )
+        command.add_argument(
+            "--max-events",
+            type=int,
+            default=100_000,
+            help="maximum trace events per process",
+        )
+        if name == "run":
+            command.add_argument(
+                "-m",
+                "--module",
+                action="store_true",
+                help="run the target as a Python module",
+            )
+        command.add_argument(
+            "arguments", nargs=argparse.REMAINDER, help="target arguments, after --"
+        )
+    report = commands.add_parser(
+        "report", help="Render existing branch coverage without executing code"
+    )
+    report.add_argument("--data-file", type=Path, default=Path(".coverage"))
+    report.add_argument("--output", type=Path, default=Path("htmlcov/flashlight.html"))
+    args = parser.parse_args(argv)
+    try:
+        if args.command == "report":
+            if not args.data_file.is_file():
+                parser.error(f"Coverage database does not exist: {args.data_file}")
+            render_coverage(args.data_file, args.output, Path.cwd())
+            return 0
+        arguments = (
+            args.arguments[1:] if args.arguments[:1] == ["--"] else args.arguments
+        )
+        if args.command == "run" and not arguments:
+            parser.error("run requires a script path or module name")
+        if args.max_events <= 0:
+            parser.error("--max-events must be positive")
+        sources = project_sources(Path.cwd(), trace=args.trace, override=args.source)
+        return measure(
+            arguments,
+            args.output
+            or Path(
+                "htmlcov/execution.html" if args.trace else "htmlcov/flashlight.html"
+            ),
+            sources,
+            trace=args.trace,
+            pytest=args.command == "pytest",
+            module=getattr(args, "module", False),
+            max_events=args.max_events,
+            data_file=args.data_file,
+        )
+    except subprocess.CalledProcessError as error:
+        return error.returncode
+    except (ValueError, OSError, CoverageException) as error:
+        parser.error(str(error))
+    except KeyboardInterrupt:
+        return 130
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

coverage_flashlight/config.py

@@ -0,0 +1,98 @@
+"""Project-local source selection shared by both measurement modes."""
+
+from __future__ import annotations
+
+import fnmatch
+import os
+import tomllib
+from pathlib import Path
+
+EXCLUDED_DIRS = {
+    ".venv",
+    "venv",
+    "node_modules",
+    "build",
+    "dist",
+    "__pycache__",
+    "site-packages",
+}
+
+
+class Sources:
+    def __init__(self, root: Path, paths: list[str], omit: list[str] | None = None):
+        self.root = root.resolve()
+        self.paths = [(self.root / path).resolve() for path in paths]
+        self.omit = omit or []
+        if not self.paths:
+            raise ValueError(
+                "source must contain at least one project-relative file or directory"
+            )
+        for path in self.paths:
+            if not path.is_relative_to(self.root) or not path.exists():
+                raise ValueError(f"Source must exist inside the project root: {path}")
+
+    def name(self, filename: str) -> str | None:
+        # Use the real platform's concrete path type, even when tests mock os.name.
+        path = type(self.root)(filename)
+        if not path.is_absolute() or not filename.endswith(".py"):
+            return None
+        if not any(
+            path == source or path.is_relative_to(source) for source in self.paths
+        ):
+            return None
+        relative = path.relative_to(self.root)
+        if any(
+            part.startswith(".") or part in EXCLUDED_DIRS for part in relative.parts
+        ):
+            return None
+        name = relative.as_posix()
+        if any(
+            fnmatch.fnmatchcase(name, pattern)
+            or fnmatch.fnmatchcase(path.as_posix(), pattern)
+            for pattern in self.omit
+        ):
+            return None
+        return name
+
+    def snapshot(self) -> dict[str, list[str]]:
+        result = {}
+        for source in self.paths:
+            if source.is_file():
+                if name := self.name(str(source)):
+                    result[name] = source.read_text(encoding="utf-8").splitlines()
+                continue
+            for directory, subdirs, filenames in os.walk(source):
+                subdirs[:] = [
+                    name
+                    for name in subdirs
+                    if not name.startswith(".")
+                    and name not in EXCLUDED_DIRS
+                    and not (Path(directory) / name).is_symlink()
+                ]
+                for filename in filenames:
+                    path = Path(directory) / filename
+                    if path.is_symlink():
+                        continue
+                    if name := self.name(str(path)):
+                        result[name] = path.read_text(encoding="utf-8").splitlines()
+        return dict(sorted(result.items()))
+
+
+def project_sources(
+    root: Path, *, trace: bool = False, override: list[str] | None = None
+) -> Sources:
+    path = root / "pyproject.toml"
+    document = tomllib.loads(path.read_text(encoding="utf-8")) if path.is_file() else {}
+    settings = document.get("tool", {}).get("coverage-flashlight", {})
+    paths = override or settings.get(
+        "trace-source" if trace else "source", settings.get("source", ["."])
+    )
+    omit = settings.get("omit", [])
+    for name, value in [("source", paths), ("omit", omit)]:
+        if not isinstance(value, list) or not all(
+            isinstance(item, str) for item in value
+        ):
+            raise ValueError(
+                f"tool.coverage-flashlight.{name} must be a list of strings"
+            )
+    return Sources(root, paths, omit)

coverage_flashlight/coverage.py

@@ -0,0 +1,82 @@
+"""Render measured line/branch coverage as a self-contained scenario explorer."""
+
+from __future__ import annotations
+
+import json
+import re
+import tempfile
+from datetime import UTC, datetime
+from pathlib import Path
+
+from coverage import Coverage
+
+
+def build_payload(cov: Coverage, root: Path) -> dict:
+    """Use coverage.py's analysis rather than inferring executable code ourselves."""
+    root = root.resolve()
+    measured_files = [
+        name
+        for name in cov.get_data().measured_files()
+        if Path(name).resolve().is_relative_to(root)
+    ]
+    if not measured_files:
+        raise ValueError("No measured source files inside the project root")
+    labels = sorted(cov.get_data().measured_contexts())
+    scopes = [("All recorded runs", None)]
+    scopes.extend(
+        (label or "Unlabelled run", [f"^{re.escape(label)}$"]) for label in labels
+    )
+
+    payload = {
+        "created": datetime.now(UTC).isoformat(),
+        "files": {},
+        "scopes": [],
+        "contexts": labels,
+    }
+    with tempfile.TemporaryDirectory(prefix="flashlight-report-") as directory:
+        report_path = Path(directory) / "report.json"
+        for index, (label, contexts) in enumerate(scopes):
+            cov.json_report(
+                morfs=measured_files,
+                outfile=str(report_path),
+                contexts=contexts,
+                show_contexts=True,
+            )
+            report = json.loads(report_path.read_text(encoding="utf-8"))
+            scope = {"label": label, "totals": report["totals"], "files": {}}
+            for filename, measured in report["files"].items():
+                path = Path(filename)
+                if not path.is_absolute():
+                    path = root / path
+                name = path.relative_to(root).as_posix()
+                scope["files"][name] = {
+                    "summary": measured["summary"],
+                    "executed": measured["executed_lines"],
+                    "missing_branches": measured.get("missing_branches", []),
+                }
+                if index == 0:
+                    payload["files"][name] = {
+                        "source": path.read_text(encoding="utf-8").splitlines(),
+                        "statements": sorted(
+                            measured["executed_lines"] + measured["missing_lines"]
+                        ),
+                        "excluded": measured["excluded_lines"],
+                        "contexts": measured.get("contexts", {}),
+                    }
+            payload["scopes"].append(scope)
+    return payload
+
+
+def render(payload: dict) -> str:
+    template = (
+        Path(__file__).with_name("coverage_flashlight.html").read_text(encoding="utf-8")
+    )
+    template = template.replace(
+        "__FLASHLIGHT_STYLE__",
+        Path(__file__).with_name("flashlight.css").read_text(encoding="utf-8"),
+    )
+    # Source files can contain literal </script> tags (notably the dashboard).
+    encoded = json.dumps(payload, ensure_ascii=True, separators=(",", ":")).replace(
+        "<", "\\u003c"
+    )
+    return template.replace("__COVERAGE_DATA__", encoded)

coverage_flashlight/coverage_flashlight.html

@@ -0,0 +1,158 @@
+<!doctype html>
+<html lang="en">
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Coverage flashlight</title>
+<style>
+__FLASHLIGHT_STYLE__
+.legend { display:flex; gap:12px; flex-wrap:wrap; font-size:11px; margin-top:5px; color:var(--muted); }
+.legend span::before { content:""; display:inline-block; width:9px; height:9px; border:1px solid var(--border); margin-right:4px; }
+.legend .lit::before { background:var(--hit); }
+.legend .partial::before { background:var(--partial); }
+.legend .miss::before { background:var(--miss); }
+.legend .elsewhere::before { background:var(--elsewhere); }
+main { grid-template-columns:minmax(260px,310px) minmax(0,1fr); }
+aside { min-height:0; padding:6px 10px; border-right:1px solid var(--border); overflow:auto; overscroll-behavior:contain; }
+table { border-collapse:collapse; width:100%; }
+th { position:sticky; top:-6px; background:var(--bg); font-weight:500; color:var(--muted); text-align:right; font-size:11px; }
+th:first-child { text-align:left; }
+td { padding:2px 0; border-bottom:1px solid var(--border); font-variant-numeric:tabular-nums; }
+td button { width:100%; border:0; text-align:left; background:none; font-size:12px; padding:5px 3px; overflow-wrap:anywhere; }
+tr[aria-selected=true] { background:var(--elsewhere); }
+.percent { min-width:53px; font-size:11px; text-align:right; }
+.bar { height:3px; width:45px; margin:2px 0 2px auto; background:var(--border); }
+.bar i { display:block; height:100%; background:var(--accent); }
+#file-summary { margin:0; font-size:12px; }
+.line.hit { background:var(--hit); }
+.line.partial { background:var(--partial); }
+.line.miss { background:var(--miss); }
+.line.elsewhere { background:var(--elsewhere); }
+.line.selected { outline:2px solid var(--accent); outline-offset:-2px; }
+.line button { position:sticky; left:0; flex:0 0 56px; width:56px; border:0; border-radius:0; padding:0 8px; font:inherit; text-align:right; color:var(--muted); background:var(--panel); }
+#line-detail { flex-shrink:0; overflow:auto; max-height:32px; font-size:11px; overflow-wrap:anywhere; color:var(--muted); }
+#scope { flex:1; }
+@media(max-width:850px) { aside { border-right:0; border-bottom:1px solid var(--border); } #totals { font-size:11px; } }
+</style>
+<header>
+  <h1>Coverage flashlight</h1>
+  <div class="controls">
+    <label for="scope">Measured scope</label><select id="scope"></select>
+    <span class="metrics" id="totals" aria-live="polite"></span>
+  </div>
+  <div class="legend" aria-label="Line status legend">
+    <span class="lit" title="Executed in the selected scope">Executed</span><span class="partial" title="Executed line with an untested branch alternative">Branch gap</span>
+    <span class="elsewhere" title="Executed in another recorded scope">Other scope</span><span class="miss" title="Never executed in these runs">Unexecuted</span>
+  </div>
+</header>
+<main>
+  <aside aria-label="Modules">
+    <table><thead><tr><th>Module</th><th>Lines</th><th>Branches</th></tr></thead><tbody id="modules"></tbody></table>
+  </aside>
+  <section class="source-panel" aria-label="Source coverage">
+    <div class="source-heading"><h2 id="filename"></h2><button id="next-gap" type="button" aria-label="Next uncovered line or branch">Next gap</button></div>
+    <p id="file-summary" class="metrics"></p>
+    <div id="code" aria-label="Source lines"></div>
+    <div id="line-detail" aria-live="polite">Select a line number to inspect its recorded scenarios and missing branch destinations.</div>
+  </section>
+</main>
+<footer><span id="generated"></span>
+    <details><summary>About coverage</summary><div class="help-content">
+      <p>Coverage records execution, not correctness. Imports and function definitions count as executable lines. A test can execute code without asserting its result.</p>
+      <p>Scopes include setup, teardown, and Python subprocesses started during that run. Background worker activity is attributed to the scenario, not to individual concurrent requests. A pre-existing GUI process is not captured automatically.</p>
+      <p>This view contains no execution counts, durations, call ordering, variable history, or native-code coverage. Branch destinations are line numbers within this file; “exit” means leaving the function. The source is a snapshot taken when this report was generated.</p>
+    </div></details>
+</footer>
+<script id="coverage-data" type="application/json">__COVERAGE_DATA__</script>
+<script>
+"use strict";
+const data = JSON.parse(document.getElementById("coverage-data").textContent);
+const scopeSelect = document.getElementById("scope");
+const files = Object.keys(data.files).sort();
+let currentFile = files[0];
+let selectedLine = null;
+const percent = (hit, total) => total ? `${(100 * hit / total).toFixed(1)}%` : "—";
+const totalsText = s => `${percent(s.covered_lines, s.num_statements)} lines (${s.covered_lines}/${s.num_statements}) · ${percent(s.covered_branches, s.num_branches)} branches (${s.covered_branches}/${s.num_branches})`;
+const scope = () => data.scopes[Number(scopeSelect.value)];
+for (let index = 0; index < data.scopes.length; index++) {
+  const option = document.createElement("option");
+  option.value = index;
+  option.textContent = data.scopes[index].label;
+  scopeSelect.append(option);
+}
+function metricCell(hit, total) {
+  const td = document.createElement("td"); td.className = "percent";
+  td.textContent = percent(hit, total);
+  const bar = document.createElement("div"); bar.className = "bar";
+  const fill = document.createElement("i"); fill.style.width = `${total ? 100 * hit / total : 0}%`;
+  bar.append(fill); td.append(bar); return td;
+}
+function drawModules() {
+  const body = document.getElementById("modules"); body.replaceChildren();
+  for (const name of files) {
+    const row = document.createElement("tr"); row.setAttribute("aria-selected", String(name === currentFile));
+    const td = document.createElement("td");
+    const button = document.createElement("button"); button.type = "button";
+    button.textContent = name;
+    button.addEventListener("click", () => { currentFile = name; selectedLine = null; draw(); });
+    td.append(button); row.append(td);
+    const s = scope().files[name].summary;
+    row.append(metricCell(s.covered_lines, s.num_statements), metricCell(s.covered_branches, s.num_branches));
+    body.append(row);
+  }
+}
+function selectLine(line) {
+  selectedLine = line;
+  for (const row of document.querySelectorAll(".line.selected")) row.classList.remove("selected");
+  document.getElementById(`line-${line}`).classList.add("selected");
+  const labels = data.files[currentFile].contexts[String(line)] || [];
+  const missing = scope().files[currentFile].missing_branches.filter(([from]) => from === line).map(([,to]) => to < 0 ? "exit" : to);
+  const detail = document.getElementById("line-detail");
+  detail.textContent = `Line ${line} · ${labels.length ? "Recorded in: " + labels.join(", ") : "No recorded execution"}${missing.length ? " · Missing destinations in scope: " + missing.join(", ") : ""}`;
+}
+function drawSource() {
+  const measured = scope().files[currentFile];
+  const file = data.files[currentFile];
+  const statements = new Set(file.statements);
+  const hits = new Set(measured.executed);
+  const allHits = new Set(data.scopes[0].files[currentFile].executed);
+  const partial = new Set(measured.missing_branches.map(([from]) => from));
+  document.getElementById("filename").textContent = currentFile;
+  document.getElementById("filename").title = currentFile;
+  document.getElementById("file-summary").textContent = totalsText(measured.summary);
+  const code = document.getElementById("code"); code.replaceChildren();
+  const fragment = document.createDocumentFragment();
+  file.source.forEach((text, index) => {
+    const line = index + 1;
+    const row = document.createElement("div"); row.className = "line"; row.id = `line-${line}`;
+    if (statements.has(line)) row.classList.add(hits.has(line) ? partial.has(line) ? "partial" : "hit" : allHits.has(line) ? "elsewhere" : "miss");
+    const number = document.createElement("button"); number.type = "button"; number.textContent = line;
+    number.setAttribute("aria-label", `Inspect line ${line}`);
+    number.addEventListener("click", () => selectLine(line));
+    const content = document.createElement("code"); content.textContent = text || " ";
+    row.append(number, content); fragment.append(row);
+  });
+  code.append(fragment);
+  if (selectedLine !== null) selectLine(selectedLine);
+  else { code.scrollTop = 0; document.getElementById("line-detail").textContent = "Select a line number to inspect its recorded scenarios and missing branch destinations."; }
+}
+function draw() {
+  const s = scope().totals;
+  document.getElementById("totals").textContent = `${percent(s.covered_lines, s.num_statements)} lines · ${percent(s.covered_branches, s.num_branches)} branches`;
+  document.getElementById("totals").title = totalsText(s);
+  drawModules(); drawSource();
+}
+scopeSelect.addEventListener("change", draw);
+document.getElementById("next-gap").addEventListener("click", () => {
+  const measured = scope().files[currentFile];
+  const hits = new Set(measured.executed);
+  const partial = new Set(measured.missing_branches.map(([from]) => from));
+  const gaps = data.files[currentFile].statements.filter(line => !hits.has(line) || partial.has(line));
+  if (!gaps.length) { document.getElementById("line-detail").textContent = "No uncovered lines or branches in this module and scope."; return; }
+  const next = gaps.find(line => line > (selectedLine || 0)) || gaps[0];
+  selectLine(next);
+  document.getElementById(`line-${next}`).scrollIntoView({block:"center"});
+});
+document.getElementById("generated").textContent = `Measured Python execution · Report generated ${new Date(data.created).toLocaleString()} · ${files.length} modules · ${data.contexts.length} recorded scopes`;
+draw();
+</script>
+</html>