feat(cli): add HTML leaderboard generator with --html flag (#57)

Self-contained static HTML page from Arbiter scores with dark theme,
HUMMBL branding (#166534 forest green), responsive layout, color-coded
score badges, and XSS-safe escaping. 12 new tests.

Co-authored-by: Claude (agent) <claude@agents.hummbl.io>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: 3 people

src/arbiter/__main__.py

@@ -7,6 +7,7 @@
     python -m arbiter explain /path/to/repo        Plain-English score explanation
     python -m arbiter contribute [--lang python]  Scan repos for fixable findings
     python -m arbiter leaderboard [--db FILE]    Markdown quality leaderboard from DB
+    python -m arbiter leaderboard --html -o out.html  HTML leaderboard
     python -m arbiter agents                     Agent leaderboard
     python -m arbiter trend [--days 30]          Quality trend over time
     python -m arbiter worst [--limit 20]         Worst files by quality
@@ -1516,7 +1517,7 @@ def format_leaderboard_markdown(
 
 
 def cmd_leaderboard(args: argparse.Namespace) -> None:
-    """Read from an existing DB and output a markdown quality leaderboard."""
+    """Read from an existing DB and output a quality leaderboard."""
     db_path = Path(args.db) if args.db else Path("arbiter_github_top.db")
     if not db_path.exists():
         print(f"Database not found: {db_path}. Run 'arbiter github-top' first.", file=sys.stderr)
@@ -1528,14 +1529,19 @@ def cmd_leaderboard(args: argparse.Namespace) -> None:
         print("No data in database. Run 'arbiter github-top' first.", file=sys.stderr)
         sys.exit(1)
 
-    md = format_leaderboard_markdown(report, language=args.lang)
+    if getattr(args, "html", False):
+        from arbiter.leaderboard_html import generate_leaderboard_html
+        content = generate_leaderboard_html(report, language=args.lang)
+    else:
+        content = format_leaderboard_markdown(report, language=args.lang)
 
     if args.output:
         out = Path(args.output)
-        out.write_text(md)
-        print(f"Leaderboard written to {out}", file=sys.stderr)
+        out.write_text(content)
+        fmt = "HTML" if getattr(args, "html", False) else "Markdown"
+        print(f"{fmt} leaderboard written to {out}", file=sys.stderr)
     else:
-        print(md)
+        print(content)
 
 
 def cmd_github_top(args: argparse.Namespace) -> None:
@@ -2214,7 +2220,8 @@ def main() -> None:
     p_leaderboard = subparsers.add_parser("leaderboard",
         help="Output quality leaderboard as markdown from an existing DB")
     p_leaderboard.add_argument("--lang", default="Python", help="Language label for the header (default: Python)")
-    p_leaderboard.add_argument("--output", "-o", help="Write markdown to file instead of stdout")
+    p_leaderboard.add_argument("--html", action="store_true", help="Output as self-contained HTML instead of markdown")
+    p_leaderboard.add_argument("--output", "-o", help="Write output to file instead of stdout")
 
     # contributions (OSS contribution tracker)
     p_contrib = subparsers.add_parser("contributions",

src/arbiter/leaderboard_html.py

@@ -0,0 +1,221 @@
+"""Generate a self-contained HTML leaderboard page from Arbiter scores."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from html import escape
+
+
+def _grade_score(score: float, total_loc: int = 1) -> str:
+    """Convert a numeric score to a letter grade."""
+    if total_loc <= 0:
+        return "N/A"
+    if score >= 90:
+        return "A"
+    if score >= 80:
+        return "B"
+    if score >= 70:
+        return "C"
+    if score >= 60:
+        return "D"
+    return "F"
+
+
+_GRADE_COLORS = {
+    "A": "#22c55e",
+    "B": "#84cc16",
+    "C": "#eab308",
+    "D": "#f97316",
+    "F": "#ef4444",
+    "N/A": "#6b7280",
+}
+
+
+def _score_color(score: float) -> str:
+    """Return a CSS color for a numeric score."""
+    if score >= 90:
+        return "#22c55e"
+    if score >= 80:
+        return "#84cc16"
+    if score >= 70:
+        return "#eab308"
+    if score >= 60:
+        return "#f97316"
+    return "#ef4444"
+
+
+def generate_leaderboard_html(
+    report: list[dict],
+    *,
+    title: str = "Arbiter Quality Index",
+    language: str = "Python",
+) -> str:
+    """Generate a self-contained HTML page with the leaderboard.
+
+    The page uses inline CSS only -- no external stylesheets or scripts.
+    It is responsive and uses a dark theme with HUMMBL forest green (#166534)
+    as the accent color.
+    """
+    timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M UTC")
+
+    rows: list[str] = []
+    for rank, r in enumerate(report, 1):
+        repo_name = escape(r.get("repo_name") or "?")
+        score = r.get("overall_score", 0) or 0
+        loc = r.get("total_loc", 0) or 0
+        findings = r.get("total_findings", 0) or 0
+        grade = _grade_score(score, loc)
+        grade_color = _GRADE_COLORS.get(grade, "#6b7280")
+        sc = _score_color(score)
+
+        if "/" in repo_name:
+            repo_cell = (
+                f'<a href="https://github.com/{repo_name}">{repo_name}</a>'
+            )
+        else:
+            repo_cell = repo_name
+
+        score_display = f"{score:.1f}" if grade != "N/A" else "n/a"
+
+        rows.append(f"""        <tr>
+          <td class="rank">{rank}</td>
+          <td class="repo">{repo_cell}</td>
+          <td class="score"><span class="badge" style="background:{sc}">{score_display}</span></td>
+          <td class="grade"><span class="badge" style="background:{grade_color}">{grade}</span></td>
+          <td class="findings">{findings:,}</td>
+          <td class="loc">{loc:,}</td>
+        </tr>""")
+
+    rows_html = "\n".join(rows)
+    esc_title = escape(title)
+    esc_lang = escape(language)
+
+    return f"""<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>{esc_title}</title>
+  <style>
+    *, *::before, *::after {{ box-sizing: border-box; }}
+    body {{
+      margin: 0;
+      padding: 0;
+      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+      background: #0f172a;
+      color: #e2e8f0;
+      min-height: 100vh;
+    }}
+    .container {{
+      max-width: 960px;
+      margin: 0 auto;
+      padding: 2rem 1rem;
+    }}
+    h1 {{
+      text-align: center;
+      font-size: 1.75rem;
+      margin: 0 0 0.25rem;
+      color: #f8fafc;
+    }}
+    .subtitle {{
+      text-align: center;
+      color: #94a3b8;
+      font-size: 0.875rem;
+      margin-bottom: 1.5rem;
+    }}
+    .table-wrap {{
+      overflow-x: auto;
+      -webkit-overflow-scrolling: touch;
+    }}
+    table {{
+      width: 100%;
+      border-collapse: collapse;
+      font-size: 0.9rem;
+    }}
+    th {{
+      background: #166534;
+      color: #f0fdf4;
+      padding: 0.6rem 0.75rem;
+      text-align: left;
+      font-weight: 600;
+      position: sticky;
+      top: 0;
+      white-space: nowrap;
+    }}
+    td {{
+      padding: 0.5rem 0.75rem;
+      border-bottom: 1px solid #1e293b;
+    }}
+    tr:hover td {{
+      background: #1e293b;
+    }}
+    .rank {{ text-align: center; color: #94a3b8; }}
+    .repo a {{
+      color: #86efac;
+      text-decoration: none;
+    }}
+    .repo a:hover {{
+      text-decoration: underline;
+    }}
+    .score, .grade {{ text-align: center; }}
+    .findings, .loc {{ text-align: right; font-variant-numeric: tabular-nums; }}
+    .badge {{
+      display: inline-block;
+      padding: 0.15rem 0.5rem;
+      border-radius: 4px;
+      color: #fff;
+      font-weight: 600;
+      font-size: 0.8rem;
+    }}
+    footer {{
+      text-align: center;
+      margin-top: 2rem;
+      padding-top: 1rem;
+      border-top: 1px solid #1e293b;
+      color: #64748b;
+      font-size: 0.8rem;
+    }}
+    footer a {{
+      color: #166534;
+      text-decoration: none;
+      font-weight: 600;
+    }}
+    footer a:hover {{
+      text-decoration: underline;
+    }}
+    @media (max-width: 600px) {{
+      .container {{ padding: 1rem 0.5rem; }}
+      h1 {{ font-size: 1.25rem; }}
+      table {{ font-size: 0.8rem; }}
+      th, td {{ padding: 0.4rem 0.5rem; }}
+    }}
+  </style>
+</head>
+<body>
+  <div class="container">
+    <h1>{esc_title}</h1>
+    <p class="subtitle">Language: {esc_lang} | Top {len(report)} by quality score | Generated: {timestamp}</p>
+    <div class="table-wrap">
+      <table>
+        <thead>
+          <tr>
+            <th>Rank</th>
+            <th>Repository</th>
+            <th>Score</th>
+            <th>Grade</th>
+            <th>Findings</th>
+            <th>LOC</th>
+          </tr>
+        </thead>
+        <tbody>
+{rows_html}
+        </tbody>
+      </table>
+    </div>
+    <footer>
+      Powered by <a href="https://github.com/hummbl-research/arbiter">HUMMBL Arbiter</a> | {timestamp}
+    </footer>
+  </div>
+</body>
+</html>
+"""

tests/test_leaderboard_html.py

@@ -0,0 +1,121 @@
+"""Tests for the HTML leaderboard generator."""
+
+from __future__ import annotations
+
+from arbiter.leaderboard_html import generate_leaderboard_html
+
+SAMPLE_REPORT = [
+    {
+        "repo_name": "pallets/flask",
+        "overall_score": 92.5,
+        "total_findings": 12,
+        "total_loc": 15000,
+    },
+    {
+        "repo_name": "psf/requests",
+        "overall_score": 85.3,
+        "total_findings": 28,
+        "total_loc": 8500,
+    },
+    {
+        "repo_name": "django/django",
+        "overall_score": 71.0,
+        "total_findings": 145,
+        "total_loc": 250000,
+    },
+]
+
+
+def test_generates_valid_html():
+    html = generate_leaderboard_html(SAMPLE_REPORT)
+    assert html.strip().startswith("<!DOCTYPE html>")
+    assert "</html>" in html
+
+
+def test_contains_repo_names():
+    html = generate_leaderboard_html(SAMPLE_REPORT)
+    assert "pallets/flask" in html
+    assert "psf/requests" in html
+    assert "django/django" in html
+
+
+def test_contains_scores():
+    html = generate_leaderboard_html(SAMPLE_REPORT)
+    assert "92.5" in html
+    assert "85.3" in html
+    assert "71.0" in html
+
+
+def test_self_contained():
+    """No external CSS or JS references."""
+    html = generate_leaderboard_html(SAMPLE_REPORT)
+    # Should not link to external stylesheets or scripts
+    assert 'rel="stylesheet"' not in html
+    assert "<link" not in html.lower().replace("blinkmacsystemfont", "")
+    assert "<script src=" not in html
+    # Style should be inline
+    assert "<style>" in html
+
+
+def test_responsive_meta_tag():
+    html = generate_leaderboard_html(SAMPLE_REPORT)
+    assert 'name="viewport"' in html
+    assert "width=device-width" in html
+
+
+def test_hummbl_branding():
+    html = generate_leaderboard_html(SAMPLE_REPORT)
+    # Forest green accent
+    assert "#166534" in html
+    # Footer branding
+    assert "HUMMBL Arbiter" in html
+    assert "hummbl-research/arbiter" in html
+
+
+def test_repos_are_linked():
+    html = generate_leaderboard_html(SAMPLE_REPORT)
+    assert 'href="https://github.com/pallets/flask"' in html
+    assert 'href="https://github.com/psf/requests"' in html
+
+
+def test_custom_title_and_language():
+    html = generate_leaderboard_html(
+        SAMPLE_REPORT, title="My Index", language="Rust"
+    )
+    assert "My Index" in html
+    assert "Rust" in html
+
+
+def test_empty_report():
+    html = generate_leaderboard_html([])
+    assert html.strip().startswith("<!DOCTYPE html>")
+    assert "Top 0" in html
+
+
+def test_grade_badges():
+    html = generate_leaderboard_html(SAMPLE_REPORT)
+    # Flask (92.5) should get A, Requests (85.3) B, Django (71.0) C
+    assert ">A<" in html
+    assert ">B<" in html
+    assert ">C<" in html
+
+
+def test_html_escaping():
+    """Repo names with special characters should be escaped."""
+    report = [
+        {
+            "repo_name": 'test/<script>alert("xss")</script>',
+            "overall_score": 50.0,
+            "total_findings": 1,
+            "total_loc": 100,
+        },
+    ]
+    html = generate_leaderboard_html(report)
+    assert "<script>" not in html
+    assert "&lt;script&gt;" in html
+
+
+def test_timestamp_present():
+    html = generate_leaderboard_html(SAMPLE_REPORT)
+    assert "Generated:" in html
+    assert "UTC" in html