slopstopper-cli 0.3.0__py3-none-any.whl

slopstopper/checks/csp_exceptions.py

@@ -0,0 +1,329 @@
+"""CSP-Exceptions Drift Detector.
+
+Ports .ss/scripts/check-csp-exceptions.py. Enforces that every per-path
+CSP relaxation in the configured header source is documented in
+`docs/security/CSP_EXCEPTIONS.md`, and vice versa.
+
+Configuration (.slopstopper.yml):
+
+    headers:
+      source: worker/headers.json   # path to header file (set to null to skip)
+      format: json                  # json | cloudflare-text | auto
+
+See .slopstopper.yml.example for the canonical schema and supported
+adapters.
+
+Exit codes mirror the bash:
+  0 — source and doc agree (or no source configured — graceful skip)
+  1 — drift detected (details in report)
+  2 — required input files missing OR unknown adapter format
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+from pathlib import Path
+
+from slopstopper import config, headers_adapters, output
+
+EXCEPTIONS_DOC = Path("docs/security/CSP_EXCEPTIONS.md")
+REPORT_DIR = Path(".ss/reports/csp")
+REPORT_JSON = REPORT_DIR / "csp-exceptions-report.json"
+REPORT_MD = REPORT_DIR / "csp-exceptions-report.md"
+
+# Consumed by `slopstopper emit hygiene:csp-exceptions --target pr-comment`.
+# The discriminator substring `🔐 CSP Exceptions` appears in both legacy
+# bot comments (pre-flip JS heading "🔐 CSP Exceptions Check") and the
+# post-flip body (report H1 "🔐 CSP Exceptions Report"), so a single bot
+# comment is reused across the migration. No issue keys: this check fails
+# the workflow on drift via its own exit code, no main-branch issue is
+# created.
+META = {
+    "report_path": str(REPORT_MD),
+    "comment_discriminator": "🔐 CSP Exceptions",
+}
+
+REQUIRED_FIELDS = {
+    "Origin allowed",
+    "Directives added",
+    "Loader SRI",
+    "Why",
+    "Approved by",
+    "Data leaving site",
+    "Refresh policy",
+}
+
+ORIGIN_RE = re.compile(r"https?://[^\s`'\"\)\],]+")
+HEADING_RE = re.compile(r"^###\s+`?(/[^\s`]+)`?\s*$")
+FIELD_RE = re.compile(r"^-\s*\*\*([^:*]+):\*\*\s*(.*)$")
+
+
+def _resolve_source() -> tuple[Path | None, str | None, str | None]:
+    """Return (path, format_name, skip_reason)."""
+    source_str = config.get("headers.source")
+    format_name = config.get("headers.format", "auto") or "auto"
+    if not source_str:
+        return None, None, "no headers.source configured in .slopstopper.yml"
+    source_path = Path(str(source_str))
+    if not source_path.exists():
+        return source_path, format_name, f"configured headers source {source_path} does not exist"
+    return source_path, format_name, None
+
+
+def _extract_csp_origins(csp: str) -> set[str]:
+    origins: set[str] = set()
+    for directive in csp.split(";"):
+        for token in directive.strip().split():
+            if token.startswith(("http://", "https://")):
+                origins.add(token.rstrip("/"))
+    return origins
+
+
+# ── CSP_EXCEPTIONS.md parser ────────────────────────────────────────
+
+
+def _new_entry() -> dict:
+    return {"origins": set(), "sri": None, "fields_seen": set()}
+
+
+def _apply_doc_field(entry: dict, field: str, value: str) -> None:
+    entry["fields_seen"].add(field)
+    if field in {"Origin allowed", "Directives added"}:
+        entry["origins"].update(o.rstrip("/") for o in ORIGIN_RE.findall(value))
+    elif field == "Loader SRI":
+        entry["sri"] = value.split()[0] if value else None
+
+
+def _flush_doc_entry(out: dict, state: dict) -> None:
+    if state["current"] is not None and state["path"] is not None:
+        out[state["path"]] = state["current"]
+        state["current"] = None
+        state["path"] = None
+
+
+def _handle_doc_line(out: dict, state: dict, line: str) -> None:
+    if line.startswith("## "):
+        _flush_doc_entry(out, state)
+        state["in_section"] = line.strip() == "## Exceptions"
+        return
+    if not state["in_section"]:
+        return
+    heading = HEADING_RE.match(line)
+    if heading:
+        _flush_doc_entry(out, state)
+        path = heading.group(1)
+        # /* is the site-wide CSP baseline, not a per-path exception. The
+        # headers side filters it out too — keep the doc parser symmetric.
+        if path == "/*":
+            state["path"] = None
+            state["current"] = None
+            return
+        state["path"] = path
+        state["current"] = _new_entry()
+        return
+    if state["current"] is None:
+        return
+    field = FIELD_RE.match(line)
+    if field:
+        _apply_doc_field(state["current"], field.group(1).strip(), field.group(2).strip())
+
+
+def _parse_exceptions_doc(doc_path: Path) -> dict[str, dict]:
+    if not doc_path.exists():
+        return {}
+    out: dict[str, dict] = {}
+    state: dict = {"in_section": False, "path": None, "current": None}
+    for raw_line in doc_path.read_text().splitlines():
+        _handle_doc_line(out, state, raw_line.rstrip())
+    _flush_doc_entry(out, state)
+    return out
+
+
+# ── Comparison ──────────────────────────────────────────────────────
+
+
+def _headers_exception_map(rules: list[dict]) -> dict[str, set[str]]:
+    out: dict[str, set[str]] = {}
+    for rule in rules:
+        path = rule["for"]
+        if path == "/*" or rule["csp"] is None:
+            continue
+        external = _extract_csp_origins(rule["csp"])
+        if external:
+            out[path] = external
+    return out
+
+
+def _sri_issues(path: str, sri: str) -> list[dict]:
+    if "TODO" in sri.upper():
+        return [{
+            "severity": "warn",
+            "path": path,
+            "message": f"`{path}` Loader SRI is a placeholder ({sri}) — refresh before this exception ships",
+        }]
+    if not sri:
+        return [{
+            "severity": "warn",
+            "path": path,
+            "message": f"`{path}` has no Loader SRI — acceptable if the third party does not support SRI; document why in the entry",
+        }]
+    return []
+
+
+def _issues_for_documented_path(path: str, required: set[str], entry: dict, source_label: str) -> list[dict]:
+    issues: list[dict] = []
+    missing_origins = required - entry["origins"]
+    if missing_origins:
+        issues.append({
+            "severity": "error",
+            "path": path,
+            "message": f"`{path}` allows {', '.join(sorted(missing_origins))} in {source_label} but those origins are not listed in CSP_EXCEPTIONS.md",
+        })
+    missing_fields = REQUIRED_FIELDS - entry["fields_seen"]
+    if missing_fields:
+        issues.append({
+            "severity": "error",
+            "path": path,
+            "message": f"`{path}` is missing required field(s) in CSP_EXCEPTIONS.md: {', '.join(sorted(missing_fields))}",
+        })
+    issues.extend(_sri_issues(path, entry["sri"] or ""))
+    return issues
+
+
+def _compare(rules: list[dict], doc_entries: dict[str, dict], source_label: str) -> list[dict]:
+    issues: list[dict] = []
+    headers_map = _headers_exception_map(rules)
+    for path, required in headers_map.items():
+        entry = doc_entries.get(path)
+        if entry is None:
+            issues.append({
+                "severity": "error",
+                "path": path,
+                "message": f"`{path}` in {source_label} allows external origins ({', '.join(sorted(required))}) but has no entry in CSP_EXCEPTIONS.md",
+            })
+            continue
+        issues.extend(_issues_for_documented_path(path, required, entry, source_label))
+    for path in doc_entries:
+        if path not in headers_map:
+            issues.append({
+                "severity": "error",
+                "path": path,
+                "message": f"`{path}` is documented in CSP_EXCEPTIONS.md but no matching CSP exception exists in {source_label}",
+            })
+    return issues
+
+
+# ── Report writers ─────────────────────────────────────────────────
+
+
+def _overall_status(issues: list[dict]) -> str:
+    if any(i["severity"] == "error" for i in issues):
+        return "❌ FAIL"
+    if any(i["severity"] == "warn" for i in issues):
+        return "⚠️ WARN"
+    return "✅ PASS"
+
+
+def _md_issue_section(title: str, severity: str, issues: list[dict]) -> list[str]:
+    bucket = [i for i in issues if i["severity"] == severity]
+    if not bucket:
+        return []
+    lines = [title, ""]
+    lines.extend(f"- **{i['path']}** — {i['message']}" for i in bucket)
+    lines.append("")
+    return lines
+
+
+def _md_fix_section(source_label: str) -> list[str]:
+    return [
+        "## How to Fix",
+        "",
+        "- **Missing doc entry** → add a `### \\`/path\\`` heading under `## Exceptions` in `docs/security/CSP_EXCEPTIONS.md` with all required fields.",
+        f"- **Mismatched origins** → make `Origin allowed` / `Directives added` in the doc list every external origin in the corresponding `{source_label}` entry.",
+        f"- **Stale doc entry** → remove the heading, or restore the matching entry in `{source_label}`.",
+        "- **Placeholder SRI** → recompute with the procedure documented in `CSP_EXCEPTIONS.md` and update both the doc and the page that loads the third-party script.",
+        "",
+    ]
+
+
+def _build_md_report(issues: list[dict], summary: dict) -> str:
+    source_label = summary.get("source", "headers source")
+    lines: list[str] = [
+        "# 🔐 CSP Exceptions Report",
+        "",
+        f"**Status:** {_overall_status(issues)}",
+        "",
+        f"- Headers source: `{source_label}` (format: `{summary.get('format', 'unknown')}`)",
+        f"- Documented exceptions in `docs/security/CSP_EXCEPTIONS.md`: {summary['doc_entries']}",
+        f"- CSP exceptions in source (non-`/*`): {summary['headers_exceptions']}",
+        "",
+    ]
+    if not issues:
+        lines.extend([f"No drift detected. `{source_label}` and `CSP_EXCEPTIONS.md` agree.", ""])
+    else:
+        lines.extend(_md_issue_section("## ❌ Errors", "error", issues))
+        lines.extend(_md_issue_section("## ⚠️ Warnings", "warn", issues))
+    lines.extend(_md_fix_section(source_label))
+    return "\n".join(lines) + "\n"
+
+
+def _write_reports(issues: list[dict], summary: dict) -> None:
+    REPORT_DIR.mkdir(parents=True, exist_ok=True)
+    REPORT_JSON.write_text(json.dumps({"summary": summary, "issues": issues}, indent=2) + "\n")
+    REPORT_MD.write_text(_build_md_report(issues, summary))
+
+
+def _print_results(headers_count: int, doc_count: int, issues: list[dict], source_label: str) -> None:
+    output.status("🔐", "CSP exceptions check")
+    output._emit(f"   source: {source_label}")
+    output._emit(f"   CSP exceptions in source: {headers_count}")
+    output._emit(f"   documented in CSP_EXCEPTIONS.md: {doc_count}")
+    output.separator()
+    if not issues:
+        output.success("No drift detected.")
+        return
+    for i in issues:
+        icon = "❌" if i["severity"] == "error" else "⚠️ "
+        output._emit(f"   {icon} {i['path']}: {i['message']}")
+    output.separator()
+
+
+def run(_args: list[str] | None = None) -> int:
+    source_path, format_name, skip_reason = _resolve_source()
+    if source_path is None:
+        output.info(f"CSP exceptions check: {skip_reason} — skipping.")
+        return 0
+    if skip_reason:
+        output.info(f"CSP exceptions check: {skip_reason} — skipping.")
+        return 0
+    if format_name not in {*headers_adapters.ADAPTERS.keys(), "auto"}:
+        output.error(
+            f"Unknown headers.format '{format_name}' in .slopstopper.yml. "
+            f"Known: {', '.join(sorted(headers_adapters.ADAPTERS.keys()))} or 'auto'."
+        )
+        return 2
+    if not EXCEPTIONS_DOC.exists():
+        output.error("docs/security/CSP_EXCEPTIONS.md not found")
+        return 2
+
+    rules = headers_adapters.parse(source_path, format_name)
+    doc_entries = _parse_exceptions_doc(EXCEPTIONS_DOC)
+    headers_count = len(_headers_exception_map(rules))
+    issues = _compare(rules, doc_entries, str(source_path))
+
+    _write_reports(issues, {
+        "doc_entries": len(doc_entries),
+        "headers_exceptions": headers_count,
+        "source": str(source_path),
+        "format": format_name,
+    })
+    _print_results(headers_count, len(doc_entries), issues, str(source_path))
+
+    if any(i["severity"] == "error" for i in issues):
+        output.error("Drift detected. See .ss/reports/csp/csp-exceptions-report.md for full details.")
+        return 1
+    if issues:
+        output.warn("Warnings only — passing.")
+    return 0

slopstopper/checks/cwv.py

@@ -0,0 +1,269 @@
+"""Core Web Vitals audit (Lighthouse CI wrapper).
+
+Implements the reliability:cwv flow:
+
+  slopstopper run reliability:cwv -- --url https://your-site.example.com
+
+  which is, under the covers:
+
+  npx lhci autorun --collect.url="$CWV_URL" --config=<resolved lhci config>
+
+Subprocess-invokes `npx lhci` — Lighthouse CI is Apache-2.0; the
+slopstopper-cli wheel ships zero Lighthouse code.
+
+After lhci finishes, cwv.py reads the latest `.lighthouseci/lhr-*.json`,
+extracts the four headline metrics (Performance, LCP, TBT, CLS) plus
+FCP, and writes `.ss/reports/cwv/cwv-report.md` with the threshold
+table. emit.py then handles PR-comment / issue from that report — same
+shape as every other check.
+
+Configuration: thresholds and the lhci config path live in the
+`.ss/lighthouserc.json` override (or the package-data fallback under
+`cli/slopstopper/data/lighthouserc.json`). cwv.py's threshold-table
+limits mirror that file so the rendered table matches what lhci
+actually enforced.
+
+Exit codes:
+  0 — lhci passed all thresholds
+  non-zero — lhci failed thresholds (report still written) or URL/config missing
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+from slopstopper import output, templates
+
+
+REPORT_DIR = Path(".ss/reports/cwv")
+REPORT_MD = REPORT_DIR / "cwv-report.md"
+LHCI_DIR = Path(".lighthouseci")
+
+# Threshold table — kept in lockstep with `.ss/lighthouserc.json`'s
+# `assertions` block so the rendered table reflects what lhci actually
+# enforced. If you tune the lhci config, mirror the change here.
+THRESHOLDS = {
+    "performance": ("Performance score", "≥ 70", 70, "min"),
+    "lcp":         ("LCP", "≤ 4 s",    4000, "max"),
+    "tbt":         ("TBT", "≤ 600 ms",  600, "max"),
+    "cls":         ("CLS", "≤ 0.25",  0.25, "max"),
+}
+
+# Consumed by `slopstopper emit reliability:cwv --target pr-comment|issue`.
+# Discriminator `🚦 Core Web Vitals` matches the pre-flip github-script
+# block's PR comment heading so the same bot comment is reused after
+# the workflow flip.
+META = {
+    "report_path": str(REPORT_MD),
+    "comment_discriminator": "🚦 Core Web Vitals",
+    "issue_title": "❌ Core Web Vitals Below Threshold",
+    "issue_labels": ["cwv-failure", "reliability"],
+    "issue_followup": "🔔 Core Web Vitals failure recurred in commit",
+}
+
+
+def _parse_args(args: list[str] | None) -> argparse.Namespace:
+    p = argparse.ArgumentParser(prog="slopstopper run reliability:cwv", add_help=False)
+    p.add_argument("--url", default=None, help="Site URL to audit (else $CWV_URL)")
+    p.add_argument(
+        "--prod",
+        action="store_true",
+        help="Use the stricter prod lighthouserc (default: dev). "
+        "Workflows pass this on deployment_status / schedule events.",
+    )
+    p.add_argument(
+        "--config",
+        default=None,
+        help="Explicit Lighthouse CI config path. Overrides --prod resolution. "
+        "Default resolution: .ss/lighthouserc[.prod].json override, else package data.",
+    )
+    p.add_argument("--help", "-h", action="help")
+    return p.parse_args(args or [])
+
+
+def _npx_available() -> bool:
+    return shutil.which("npx") is not None
+
+
+def _resolve_url(parsed_url: str | None) -> str | None:
+    return parsed_url or os.environ.get("CWV_URL")
+
+
+def _build_cmd(url: str, config_path: str) -> list[str]:
+    return [
+        "npx", "lhci", "autorun",
+        f"--collect.url={url}",
+        f"--config={config_path}",
+    ]
+
+
+def _run_lhci(cmd: list[str]) -> tuple[int, str]:
+    """Run lhci, tee its output to our stdout, and return (exit_code, captured_output)."""
+    proc = subprocess.Popen(
+        cmd, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True, bufsize=1
+    )
+    chunks: list[str] = []
+    assert proc.stdout is not None
+    for line in proc.stdout:
+        sys.stdout.write(line)
+        sys.stdout.flush()
+        chunks.append(line)
+    rc = proc.wait()
+    return rc, "".join(chunks)
+
+
+# ── lhci JSON parsing + report rendering ─────────────────────────
+
+
+def _latest_lhr_json() -> Path | None:
+    if not LHCI_DIR.exists():
+        return None
+    reports = sorted(LHCI_DIR.glob("lhr-*.json"))
+    return reports[-1] if reports else None
+
+
+def _extract_metrics(lhr: dict) -> dict[str, float | None]:
+    """Pull the four headline metrics + FCP from a Lighthouse result JSON."""
+    categories = lhr.get("categories") or {}
+    audits = lhr.get("audits") or {}
+    perf_cat = categories.get("performance") or {}
+
+    def _audit_value(key: str) -> float | None:
+        audit = audits.get(key) or {}
+        value = audit.get("numericValue")
+        return float(value) if isinstance(value, (int, float)) else None
+
+    perf_score = perf_cat.get("score")
+    return {
+        "performance": round(perf_score * 100) if isinstance(perf_score, (int, float)) else None,
+        "lcp": _audit_value("largest-contentful-paint"),
+        "tbt": _audit_value("total-blocking-time"),
+        "cls": _audit_value("cumulative-layout-shift"),
+        "fcp": _audit_value("first-contentful-paint"),
+    }
+
+
+def _format_value(metric: str, value: float | None) -> str:
+    if value is None:
+        return "N/A"
+    if metric == "performance":
+        return f"{int(value)}/100"
+    if metric == "cls":
+        return f"{value:.3f}"
+    return f"{int(round(value))} ms"
+
+
+def _passes(metric: str, value: float | None) -> bool | None:
+    if value is None:
+        return None
+    _, _, threshold, direction = THRESHOLDS[metric]
+    return value >= threshold if direction == "min" else value <= threshold
+
+
+def _icon(passed: bool | None) -> str:
+    if passed is None:
+        return "⚠️"
+    return "✅" if passed else "❌"
+
+
+def _extract_report_url(output: str) -> str | None:
+    """lhci prints the storage URL to stdout. Capture the first one."""
+    match = re.search(r"https://storage\.googleapis\.com/\S+", output)
+    return match.group(0) if match else None
+
+
+def _build_report_md(
+    url: str,
+    metrics: dict[str, float | None],
+    report_url: str | None,
+    overall_pass: bool,
+) -> str:
+    status = "✅ PASSED" if overall_pass else "❌ FAILED"
+    lines: list[str] = [
+        f"## 🚦 Core Web Vitals {status}",
+        "",
+        f"**URL audited:** {url}",
+        "",
+        "| Metric | Threshold | Status |",
+        "|--------|-----------|--------|",
+    ]
+    for key, (label, threshold_str, _, _) in THRESHOLDS.items():
+        value = metrics.get(key)
+        lines.append(
+            f"| {label} | {threshold_str} | {_icon(_passes(key, value))} {_format_value(key, value)} |"
+        )
+    lines.append("")
+    if report_url:
+        lines.append(f"[📊 Full Lighthouse Report]({report_url})")
+        lines.append("")
+    lines.append("### How to run locally")
+    lines.append("")
+    lines.append("```bash")
+    lines.append("slopstopper run reliability:cwv -- --url https://your-site.example.com")
+    lines.append("```")
+    lines.append("")
+    return "\n".join(lines)
+
+
+def _write_report(url: str, output: str, lhci_exit: int) -> None:
+    """Parse the latest lhr-*.json + lhci stdout, and write the markdown report."""
+    REPORT_DIR.mkdir(parents=True, exist_ok=True)
+    lhr_path = _latest_lhr_json()
+    if lhr_path is None:
+        REPORT_MD.write_text(
+            "## 🚦 Core Web Vitals ⚠️ NO REPORT\n\n"
+            "Lighthouse CI did not produce a report JSON under `.lighthouseci/`. "
+            "Check the lhci output above for the cause.\n"
+        )
+        return
+    try:
+        lhr = json.loads(lhr_path.read_text())
+    except (OSError, json.JSONDecodeError) as e:
+        REPORT_MD.write_text(
+            f"## 🚦 Core Web Vitals ⚠️ PARSE ERROR\n\nCould not parse {lhr_path}: {e}\n"
+        )
+        return
+    metrics = _extract_metrics(lhr)
+    report_url = _extract_report_url(output)
+    REPORT_MD.write_text(
+        _build_report_md(url, metrics, report_url, overall_pass=lhci_exit == 0)
+    )
+
+
+# ── CLI entrypoint ───────────────────────────────────────────────
+
+
+def run(args: list[str] | None = None) -> int:
+    if not _npx_available():
+        output.error("npx is not available — install Node.js to run Lighthouse CI")
+        return 1
+
+    parsed = _parse_args(args)
+    url = _resolve_url(parsed.url)
+    if not url:
+        output.error("CWV target URL is required")
+        output._emit("Usage:")
+        output._emit("  slopstopper run reliability:cwv -- --url https://your-site.example.com")
+        output._emit("  CWV_URL=https://your-site slopstopper run reliability:cwv")
+        return 1
+
+    config_path = (
+        Path(parsed.config) if parsed.config else templates.lighthouserc(prod=parsed.prod)
+    )
+    if not config_path.exists():
+        output.error(f"Lighthouse CI config not found at {config_path}")
+        return 1
+
+    output.status("🚦", f"Running Core Web Vitals audit against: {url}")
+    cmd = _build_cmd(url, str(config_path))
+    rc, captured = _run_lhci(cmd)
+    _write_report(url, captured, rc)
+    output.footer(REPORT_DIR, [REPORT_MD.name])
+    return rc