#!/usr/bin/env python3
"""
SEO Report — Professional HTML audit report generator.
Features:
- Single-file HTML with inline CSS (no external deps)
- SVG radar chart for score visualization
- Color-coded issue cards (Critical/High/Medium/Low)
- Quick Wins section
- Print-friendly (@media print)
- Responsive (mobile-readable)
Author: Laurent Rochetta
License: MIT
"""
import argparse
import html
import json
import math
import os
import sys
from datetime import datetime
def generate_radar_svg(scores: dict, size: int = 300) -> str:
"""Generate an SVG radar chart for the 7 score categories."""
categories = list(scores.keys())
values = list(scores.values())
n = len(categories)
if n == 0:
return ""
cx, cy = size // 2, size // 2
radius = size // 2 - 40
# Short labels for display
short_labels = {
"technical": "Tech",
"content_eeat": "E-E-A-T",
"on_page": "On-Page",
"schema": "Schema",
"performance": "Perf",
"ai_readiness": "AI/GEO",
"images": "Images",
}
def point(angle_deg, r):
angle_rad = math.radians(angle_deg - 90)
x = cx + r * math.cos(angle_rad)
y = cy + r * math.sin(angle_rad)
return x, y
svg_parts = [f'')
return "\n".join(svg_parts)
def severity_color(severity: str) -> str:
"""Get color for severity level."""
return {
"critical": "#ef4444",
"high": "#f97316",
"medium": "#f59e0b",
"low": "#22c55e",
}.get(severity, "#64748b")
def severity_icon(severity: str) -> str:
return {
"critical": "🔴",
"high": "🟠",
"medium": "🟡",
"low": "🟢",
}.get(severity, "⚪")
def score_color(score: int) -> str:
if score >= 90:
return "#22c55e"
elif score >= 70:
return "#84cc16"
elif score >= 50:
return "#f59e0b"
else:
return "#ef4444"
def generate_html_report(audit_data: dict) -> str:
"""Generate a complete HTML report from audit JSON data."""
domain = audit_data.get("domain", "Unknown")
timestamp = audit_data.get("timestamp", datetime.now().isoformat())
total_score = audit_data.get("score", {}).get("total", 0)
# Escaped copies of externally-sourced content for safe HTML interpolation
domain_esc = html.escape(str(domain))
timestamp_esc = html.escape(str(timestamp)[:10])
total_score_esc = html.escape(str(total_score))
categories = audit_data.get("score", {}).get("categories", {})
issues = audit_data.get("issues", [])
pages = audit_data.get("pages", [])
# Generate radar chart
radar_svg = generate_radar_svg(categories) if categories else ""
# Sort issues by severity
severity_order = {"critical": 0, "high": 1, "medium": 2, "low": 3}
sorted_issues = sorted(issues, key=lambda x: severity_order.get(x.get("severity", "low"), 4))
# Count by severity
counts = {"critical": 0, "high": 0, "medium": 0, "low": 0}
for issue in issues:
sev = issue.get("severity", "low")
counts[sev] = counts.get(sev, 0) + 1
# Quick wins
quick_wins = [i for i in issues if i.get("quick_win", False)][:5]
# Build issue cards HTML
issue_cards = ""
for issue in sorted_issues:
sev = issue.get("severity", "low")
fix_html = ""
if issue.get("fix"):
fix_html = f'Fix:{html.escape(str(issue["fix"]))}
'
issue_cards += f'''
{html.escape(str(issue.get("title", "")))}
{html.escape(str(issue.get("description", "")))}
{fix_html}
'''
# Quick wins HTML
qw_html = ""
if quick_wins:
qw_items = ""
for qw in quick_wins:
qw_items += f'{severity_icon(qw.get("severity", ""))} {html.escape(str(qw.get("title", "")))}'
qw_html = f''
# Category scores table
cat_rows = ""
for cat, score in categories.items():
cat_name = html.escape(str(cat).replace("_", " ").title())
score_esc = html.escape(str(score))
cat_rows += f'''
| {cat_name} |
|
{score_esc} |
'''
html_out = f'''
SEO Audit Report — {domain_esc}
{total_score_esc}
SEO Score
{radar_svg}
{counts["critical"]}
Critical
{counts["medium"]}
Medium
{qw_html}
🔍 Issues ({len(issues)})
{issue_cards}
'''
return html_out
# ── CLI ────────────────────────────────────────────────────────────
def main():
parser = argparse.ArgumentParser(
description="SEO Report — HTML audit report generator (BMAD+ SEO Engine)"
)
parser.add_argument("input", help="Audit JSON file")
parser.add_argument("--output", "-o", default="seo-report.html", help="Output HTML file")
args = parser.parse_args()
if not os.path.isfile(args.input):
print(f"Error: File not found: {args.input}", file=sys.stderr)
sys.exit(1)
with open(args.input, "r", encoding="utf-8") as f:
audit_data = json.load(f)
html = generate_html_report(audit_data)
with open(args.output, "w", encoding="utf-8") as f:
f.write(html)
print(f"✅ Report generated: {args.output}", file=sys.stderr)
print(f" Domain: {audit_data.get('domain', 'Unknown')}")
print(f" Score: {audit_data.get('score', {}).get('total', 0)}/100")
print(f" Issues: {len(audit_data.get('issues', []))}")
if __name__ == "__main__":
main()