slopstopper-cli 0.3.0__py3-none-any.whl

slopstopper/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.3.0"

slopstopper/__main__.py

@@ -0,0 +1,4 @@
+from slopstopper.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

slopstopper/checks/__init__.py

@@ -0,0 +1,41 @@
+"""Check registry. Maps `<category>:<name>` keys to check entrypoints."""
+
+from __future__ import annotations
+
+from typing import Callable, Optional
+
+from slopstopper.checks import (
+    accessibility,
+    broken_links,
+    complexity,
+    csp_exceptions,
+    cwv,
+    dast,
+    dependencies,
+    docs_accuracy,
+    docs_size,
+    docs_structure,
+    entry_files,
+    sast,
+    secrets,
+    seo,
+    smoke,
+)
+
+REGISTRY: dict[str, Callable[[Optional[list[str]]], int]] = {
+    "hygiene:complexity": complexity.run,
+    "hygiene:csp-exceptions": csp_exceptions.run,
+    "hygiene:docs-accuracy": docs_accuracy.run,
+    "hygiene:docs-size": docs_size.run,
+    "hygiene:docs-structure": docs_structure.run,
+    "hygiene:entry-files": entry_files.run,
+    "reliability:accessibility": accessibility.run,
+    "reliability:broken-links": broken_links.run,
+    "reliability:cwv": cwv.run,
+    "reliability:seo": seo.run,
+    "reliability:smoke": smoke.run,
+    "security:dast": dast.run,
+    "security:dependencies": dependencies.run,
+    "security:sast": sast.run,
+    "security:secrets": secrets.run,
+}

slopstopper/checks/accessibility.py

@@ -0,0 +1,133 @@
+"""Accessibility audit (Playwright + axe-core wrapper).
+
+Ports the bash reliability:accessibility flow:
+
+  task ss:reliability:accessibility -- https://your-site.example.com
+
+  which is, under the covers:
+
+  ACCESSIBILITY_PAGES=$(python3 .ss/scripts/discover-pages.py
+                                accessibility --event=local)
+  ACCESSIBILITY_TEST_URL=...
+  npx playwright test --config=.ss/playwright.config.js
+                      .ss/tests/accessibility.spec.ts
+                      --reporter=list[,html]
+
+Subprocess-invokes `npx playwright`. Playwright is Apache-2.0, axe-core
+is MPL-2.0; the slopstopper-cli wheel ships zero code from either —
+both bind in via the adopter's node_modules. Page discovery uses the
+in-CLI slopstopper.discovery module.
+
+Falls back to SMOKE_TEST_URL when ACCESSIBILITY_TEST_URL is unset,
+matching the bash flow exactly.
+
+Configuration (.slopstopper.yml — all optional):
+
+    pages:
+      accessibility: /,/blog,/about
+    reliability:
+      coverage:
+        pr: changed     # see slopstopper.discovery for the resolution order
+        main: sitemap
+
+See .slopstopper.yml.example for the canonical schema and coverage
+modes.
+
+Exit codes:
+  0 — playwright tests passed
+  non-zero — playwright tests failed, or URL/spec missing
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import shutil
+import subprocess
+
+from slopstopper import discovery, output, templates
+
+SPEC_NAME = "accessibility"
+
+
+def _parse_args(args: list[str] | None) -> argparse.Namespace:
+    p = argparse.ArgumentParser(
+        prog="slopstopper run reliability:accessibility", add_help=False
+    )
+    p.add_argument("--url", default=None, help="Site URL to audit")
+    p.add_argument("--ci", action="store_true", help="CI mode: html reporter, CI=true")
+    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("ACCESSIBILITY_TEST_URL")
+        or os.environ.get("SMOKE_TEST_URL")
+    )
+
+
+def _discover_pages() -> str | None:
+    """Resolve pages.accessibility from .slopstopper.yml via the in-CLI
+    discovery module. Returns None on internal failure so the spec falls
+    back to its built-in default.
+    """
+    try:
+        paths = discovery.discover("accessibility", "local")
+    except Exception:
+        return None
+    return ",".join(paths) if paths else None
+
+
+def _build_env(url: str, ci_mode: bool) -> dict[str, str]:
+    env = dict(os.environ)
+    env["ACCESSIBILITY_TEST_URL"] = url
+    if "ACCESSIBILITY_PAGES" not in env:
+        pages = _discover_pages()
+        if pages is not None:
+            env["ACCESSIBILITY_PAGES"] = pages
+    if ci_mode:
+        env["CI"] = "true"
+    return env
+
+
+def _build_cmd(ci_mode: bool) -> list[str]:
+    reporter = "list,html" if ci_mode else "list"
+    return [
+        "npx", "playwright", "test",
+        f"--config={templates.playwright_config()}",
+        str(templates.playwright_spec(SPEC_NAME)),
+        f"--reporter={reporter}",
+    ]
+
+
+def run(args: list[str] | None = None) -> int:
+    if not _npx_available():
+        output.error("npx is not available — install Node.js to run Playwright tests")
+        return 1
+
+    parsed = _parse_args(args)
+    url = _resolve_url(parsed.url)
+    if not url:
+        output.error("accessibility target URL is required")
+        output._emit("Usage:")
+        output._emit("  slopstopper run reliability:accessibility -- --url https://your-site.example.com")
+        output._emit("  ACCESSIBILITY_TEST_URL=https://your-site slopstopper run reliability:accessibility")
+        return 1
+
+    spec = templates.playwright_spec(SPEC_NAME)
+    if not spec.exists():
+        output.error(f"Accessibility spec not found at {spec}")
+        output._emit("   The spec is bundled inside slopstopper-cli; reinstall to repair.")
+        return 1
+
+    output.status("♿", f"Running accessibility audit against: {url}")
+    env = _build_env(url, parsed.ci)
+    cmd = _build_cmd(parsed.ci)
+    result = subprocess.run(cmd, env=env, check=False)
+    return result.returncode

slopstopper/checks/broken_links.py

@@ -0,0 +1,128 @@
+"""Broken-link checks (Playwright wrapper).
+
+Ports the bash reliability:links flow:
+
+  task ss:reliability:links -- https://your-site.example.com
+
+  which is, under the covers:
+
+  BROKEN_LINKS_PAGES=$(python3 .ss/scripts/discover-pages.py
+                              broken_links --event=local)
+  BROKEN_LINKS_TEST_URL=...
+  npx playwright test --config=.ss/playwright.config.js
+                      .ss/tests/broken-links.spec.ts
+                      --reporter=list[,html]
+
+Subprocess-invokes `npx playwright`. Playwright is Apache-2.0; the
+slopstopper-cli wheel ships zero Playwright code. Page discovery uses
+the in-CLI slopstopper.discovery module.
+
+Falls back to SMOKE_TEST_URL when BROKEN_LINKS_TEST_URL is unset,
+matching the bash flow exactly.
+
+Configuration (.slopstopper.yml — all optional):
+
+    pages:
+      broken_links: /,/blog,/about
+    reliability:
+      coverage:
+        pr: changed     # see slopstopper.discovery for the resolution order
+        main: sitemap
+
+See .slopstopper.yml.example for the canonical schema and coverage
+modes.
+
+Exit codes:
+  0 — playwright tests passed
+  non-zero — playwright tests failed, or URL/spec missing
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import shutil
+import subprocess
+
+from slopstopper import discovery, output, templates
+
+SPEC_NAME = "broken-links"
+
+
+def _parse_args(args: list[str] | None) -> argparse.Namespace:
+    p = argparse.ArgumentParser(
+        prog="slopstopper run reliability:broken-links", add_help=False
+    )
+    p.add_argument("--url", default=None, help="Site URL to scan")
+    p.add_argument("--ci", action="store_true", help="CI mode: html reporter, CI=true")
+    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("BROKEN_LINKS_TEST_URL")
+        or os.environ.get("SMOKE_TEST_URL")
+    )
+
+
+def _discover_pages() -> str | None:
+    """Resolve pages.broken_links via the in-CLI discovery module."""
+    try:
+        paths = discovery.discover("broken_links", "local")
+    except Exception:
+        return None
+    return ",".join(paths) if paths else None
+
+
+def _build_env(url: str, ci_mode: bool) -> dict[str, str]:
+    env = dict(os.environ)
+    env["BROKEN_LINKS_TEST_URL"] = url
+    if "BROKEN_LINKS_PAGES" not in env:
+        pages = _discover_pages()
+        if pages is not None:
+            env["BROKEN_LINKS_PAGES"] = pages
+    if ci_mode:
+        env["CI"] = "true"
+    return env
+
+
+def _build_cmd(ci_mode: bool) -> list[str]:
+    reporter = "list,html" if ci_mode else "list"
+    return [
+        "npx", "playwright", "test",
+        f"--config={templates.playwright_config()}",
+        str(templates.playwright_spec(SPEC_NAME)),
+        f"--reporter={reporter}",
+    ]
+
+
+def run(args: list[str] | None = None) -> int:
+    if not _npx_available():
+        output.error("npx is not available — install Node.js to run Playwright tests")
+        return 1
+
+    parsed = _parse_args(args)
+    url = _resolve_url(parsed.url)
+    if not url:
+        output.error("broken-links target URL is required")
+        output._emit("Usage:")
+        output._emit("  slopstopper run reliability:broken-links -- --url https://your-site.example.com")
+        output._emit("  BROKEN_LINKS_TEST_URL=https://your-site slopstopper run reliability:broken-links")
+        return 1
+
+    spec = templates.playwright_spec(SPEC_NAME)
+    if not spec.exists():
+        output.error(f"Broken-links spec not found at {spec}")
+        return 1
+
+    output.status("🔗", f"Running broken-link checks against: {url}")
+    env = _build_env(url, parsed.ci)
+    cmd = _build_cmd(parsed.ci)
+    result = subprocess.run(cmd, env=env, check=False)
+    return result.returncode

slopstopper/checks/complexity.py

@@ -0,0 +1,237 @@
+"""Code complexity analyzer (Lizard wrapper).
+
+Ports the bash hygiene:complexity flow:
+
+  .ss/scripts/check-tool   (in Taskfile.ss.yml — installs lizard)
+  + python3 -m lizard . ... --csv > complexity-report.csv
+  + .ss/scripts/generate-complexity-md.py
+
+into one self-contained check. Subprocess-invokes `python -m lizard`
+(using sys.executable so the same Python running the CLI provides
+lizard), captures the CSV, parses it, writes both the CSV and the
+markdown report.
+
+This is the CLI's first external-tool integration. Subprocess-invoke
+boundary is the load-bearing licensing rule (see plan doc): we call
+lizard's CLI, never `import lizard`. Adopter installs lizard
+themselves (or via the test extra in cli/pyproject.toml's [test]
+group, which is what CI does).
+
+Exit codes:
+  0 — analysis completed (independent of whether high-complexity items
+      exist — gating happens at the workflow level, mirroring bash)
+  1 — lizard is not installed
+"""
+
+from __future__ import annotations
+
+import csv
+import io
+import subprocess
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+from slopstopper import output
+
+REPORT_DIR = Path(".ss/reports/complexity")
+REPORT_CSV = REPORT_DIR / "complexity-report.csv"
+REPORT_MD = REPORT_DIR / "complexity-report.md"
+
+# Consumed by `slopstopper emit hygiene:complexity --target {pr-comment,issue}`.
+# The comment_discriminator is the H1 of the generated report — pre-flip the
+# JS prepended its own "## 📊 Code Complexity Analysis" heading, but the
+# report itself starts with "# Code Complexity Analysis Report", so the
+# substring "Code Complexity Analysis" matches the same comment after the
+# flip. Issue strings are byte-for-byte identical to the legacy block.
+META = {
+    "report_path": str(REPORT_MD),
+    "comment_discriminator": "Code Complexity Analysis",
+    "issue_title": "⚠️ Code Complexity Issues in Main Branch",
+    "issue_labels": ["code-complexity", "technical-debt"],
+    "issue_followup": "🔔 Code complexity issues detected again in commit",
+}
+
+# Exclude tests, generated files, vendored deps from the scan. Same list
+# as Taskfile.ss.yml's hygiene:complexity:analyze.
+LIZARD_EXCLUDES = (
+    "tests/*",
+    ".ss/tests/*",
+    ".github/*",
+    "node_modules/*",
+    ".git/*",
+)
+
+CCN_THRESHOLD = 10
+
+_LIZARD_INSTALL_HELP = (
+    "lizard is not installed.\n"
+    "Install with:\n"
+    "  pip3 install --user lizard\n"
+    "  python3 -m pip install --user lizard\n"
+    "Note: do NOT install via 'brew install lizard' — that's lz4's lizard,\n"
+    "a completely different tool that will shadow the Python package."
+)
+
+
+def _lizard_available() -> bool:
+    try:
+        result = subprocess.run(
+            [sys.executable, "-m", "lizard", "--version"],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        return result.returncode == 0
+    except OSError:
+        return False
+
+
+def _run_lizard(target_dir: str = ".") -> str:
+    """Invoke `python -m lizard <target> --csv ...` and return stdout."""
+    cmd = [sys.executable, "-m", "lizard", target_dir]
+    for ex in LIZARD_EXCLUDES:
+        cmd += ["-x", ex]
+    cmd += ["--csv"]
+    result = subprocess.run(cmd, capture_output=True, text=True, check=False)
+    return result.stdout
+
+
+def _parse_csv_rows(csv_text: str) -> list[tuple]:
+    """Parse lizard's CSV output.
+
+    Columns (0-indexed):
+      0 nloc, 1 ccn, 2 tokens, 3 params, 4 length,
+      5 location ("function@start-end@./path"),
+      6 file path, 7 function name, 8 long name, ...
+
+    Returns [(nloc, ccn, tokens, params, length, location, file), ...].
+    Rows with non-numeric leading columns (header rows from fixtures) are
+    silently skipped.
+    """
+    rows: list[tuple] = []
+    reader = csv.reader(io.StringIO(csv_text))
+    for row in reader:
+        if len(row) < 6:
+            continue
+        try:
+            nloc = int(row[0])
+            ccn = int(row[1])
+            tokens = int(row[2])
+            params = int(row[3])
+            length = int(row[4])
+        except ValueError:
+            continue
+        location = row[5].strip('"')
+        if len(row) > 6 and row[6]:
+            file_path = row[6].strip('"')
+        elif "@" in location:
+            file_path = location.split("@")[-1]
+        else:
+            file_path = location.split(":")[0]
+        rows.append((nloc, ccn, tokens, params, length, location, file_path))
+    return rows
+
+
+def _compute_summary_lines(rows: list[tuple]) -> list[str]:
+    if not rows:
+        return [
+            "Total NLOC   Avg.NLOC  Avg.CCN  Avg.Tokens  Fun Cnt  Warning Cnt",
+            "----------------------------------------------------------------",
+            "         0        0.0      0.0         0.0        0            0",
+            "",
+            "No functions analyzed.",
+        ]
+
+    fun_cnt = len(rows)
+    total_nloc = sum(r[0] for r in rows)
+    avg_nloc = total_nloc / fun_cnt
+    avg_ccn = sum(r[1] for r in rows) / fun_cnt
+    avg_tokens = sum(r[2] for r in rows) / fun_cnt
+    warning_cnt = sum(1 for r in rows if r[1] > CCN_THRESHOLD)
+
+    files = {r[6] for r in rows}
+    file_count = len(files)
+    file_word = "file" if file_count == 1 else "files"
+
+    return [
+        "Total NLOC   Avg.NLOC  Avg.CCN  Avg.Tokens  Fun Cnt  Warning Cnt",
+        "----------------------------------------------------------------",
+        f"{total_nloc:>10}  {avg_nloc:>9.1f}  {avg_ccn:>7.1f}  {avg_tokens:>10.1f}  {fun_cnt:>7}  {warning_cnt:>11}",
+        "",
+        f"{file_count} {file_word} analyzed.",
+    ]
+
+
+def _format_summary_section(summary_lines: list[str]) -> str:
+    if not summary_lines:
+        return ""
+    return "```\n" + "\n".join(summary_lines) + "\n```\n\n"
+
+
+def _format_high_complexity_section(rows: list[tuple]) -> str:
+    high = [r for r in rows if r[1] > CCN_THRESHOLD]
+    if not high:
+        return "## ✅ Complexity Status\n\nNo high-complexity items found (all CCN ≤ 10)\n\n"
+
+    out = "## ⚠️ High Complexity Items (CCN > 10)\n\n"
+    out += "| NLOC | CCN | Tokens | Params | Length | Location |\n"
+    out += "|------|-----|--------|--------|--------|----------|\n"
+    for nloc, ccn, tokens, params, length, location, _file in high:
+        out += f"| {nloc} | {ccn} | {tokens} | {params} | {length} | `{location}` |\n"
+    return out
+
+
+def _generated_at() -> str:
+    # Bash uses `datetime.now().strftime(...)` (naive local time). The
+    # parity test strips this line so format is irrelevant, but using
+    # timezone.utc here matches what the docs-size port chose.
+    return datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M:%S")
+
+
+def _build_md_report(rows: list[tuple]) -> str:
+    summary = _compute_summary_lines(rows)
+    md = "# Code Complexity Analysis Report\n\n"
+    md += f"**Generated**: {_generated_at()}\n\n"
+    md += "## Summary\n\n"
+    md += _format_summary_section(summary)
+    md += _format_high_complexity_section(rows)
+    md += "## Guidelines\n\n"
+    md += "- **Cyclomatic Complexity (CCN)**: Measure of code complexity based on decision points\n"
+    md += "  - **Good**: CCN ≤ 10\n"
+    md += "  - **Warning**: 10 < CCN ≤ 15\n"
+    md += "  - **Critical**: CCN > 15\n\n"
+    md += "- **Function Length (NLOC)**: Number of lines of code\n"
+    md += "  - Target: Keep functions under 50 lines\n"
+    md += "  - For this static template, code should be minimal\n\n"
+    md += "- **Threshold**: Any function with CCN > 10 should be reviewed and simplified\n\n"
+    md += "## More Information\n\n"
+    md += "- Generated by [Lizard](http://www.lizard.ws/)\n"
+    md += "- Reports location: `.ss/reports/complexity/`\n"
+    md += "  - `complexity-report.md` (this file)\n"
+    md += "  - `complexity-report.csv` (machine-readable)\n"
+    return md
+
+
+def run(_args: list[str] | None = None) -> int:
+    if not _lizard_available():
+        output.error(_LIZARD_INSTALL_HELP)
+        return 1
+
+    output.running("Analyzing code complexity…")
+    REPORT_DIR.mkdir(parents=True, exist_ok=True)
+
+    csv_text = _run_lizard()
+    REPORT_CSV.write_text(csv_text)
+
+    rows = _parse_csv_rows(csv_text)
+    REPORT_MD.write_text(_build_md_report(rows))
+
+    high_count = sum(1 for r in rows if r[1] > CCN_THRESHOLD)
+    if high_count:
+        output.warn(f"Found {high_count} item(s) with cyclomatic complexity > 10")
+    else:
+        output.success("No high-complexity items found (all CCN ≤ 10)")
+
+    output.footer(REPORT_DIR, [REPORT_MD.name, REPORT_CSV.name])
+    return 0