@aexol/spectral 0.9.126 → 0.9.127

package/dist/extensions/seo/tools/report.js

@@ -1,27 +1,28 @@
-/**
- * seo_report tool — generate formatted reports from audit results.
- */
 import { mkdirSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { resolve, relative, isAbsolute } from "node:path";
 import { errorResult, textResult } from "./helpers.js";
 export function registerReportTools(ext, config) {
     const reportTool = {
         name: "seo_report",
         label: "SEO Report Generator",
         description: "Generate a formatted SEO report from audit results. " +
-            "Accepts a FullAuditResult object (from seo_audit) and produces a Markdown, JSON, or HTML report. " +
+            "Accepts a FullAuditResult object (from seo_audit) OR an array of FullAuditResult objects for batch reporting. " +
+            "Produces a Markdown, JSON, SARIF, or HTML report. " +
             "Optionally writes the report to a file in the SEO output directory (default: ~/.spectral/seo-reports/).",
-        promptSnippet: "`seo_report { auditResult, format?, outputPath? }` — generate formatted SEO report",
+        promptSnippet: "`seo_report { auditResult, format?, outputPath? }` — generate formatted SEO report (single or batch)",
         parameters: {
             type: "object",
             properties: {
                 auditResult: {
-                    type: "object",
-                    description: "The FullAuditResult object from seo_audit.",
+                    oneOf: [
+                        { type: "object", description: "A single FullAuditResult object from seo_audit." },
+                        { type: "array", items: { type: "object" }, description: "An array of FullAuditResult objects for batch reporting." },
+                    ],
+                    description: "The FullAuditResult object (or array of them) from seo_audit.",
                 },
                 format: {
                     type: "string",
-                    enum: ["markdown", "json", "html"],
+                    enum: ["markdown", "json", "sarif", "html"],
                     description: "Output format. Default: 'markdown'.",
                 },
                 outputPath: {
@@ -36,26 +37,57 @@ export function registerReportTools(ext, config) {
             try {
                 const fmt = format ?? "markdown";
                 let content;
-                switch (fmt) {
-                    case "json":
-                        content = JSON.stringify(auditResult, null, 2);
-                        break;
-                    case "html":
-                        content = generateHtmlReport(auditResult);
-                        break;
-                    case "markdown":
-                    default:
-                        content = generateMarkdownReport(auditResult);
-                        break;
+                if (Array.isArray(auditResult)) {
+                    switch (fmt) {
+                        case "json":
+                            content = JSON.stringify(auditResult, null, 2);
+                            break;
+                        case "sarif":
+                            const allResults = Array.isArray(auditResult) ? auditResult : [auditResult];
+                            content = JSON.stringify(generateSarifBatchReport(allResults, config), null, 2);
+                            break;
+                        case "html":
+                            content = auditResult.map((r) => generateHtmlReport(r, config)).join("\n<hr>\n");
+                            break;
+                        case "markdown":
+                        default:
+                            content = generateMarkdownReport(auditResult, config);
+                            break;
+                    }
+                }
+                else {
+                    // Cast to extended type for Phase 3B fields
+                    const result = auditResult;
+                    switch (fmt) {
+                        case "json":
+                            content = JSON.stringify(result, null, 2);
+                            break;
+                        case "sarif":
+                            content = JSON.stringify(generateSarifReport(result), null, 2);
+                            break;
+                        case "html":
+                            content = generateHtmlReport(result, config);
+                            break;
+                        case "markdown":
+                        default:
+                            content = generateMarkdownReport(result, config);
+                            break;
+                    }
                 }
                 let savedPath;
                 if (outputPath) {
-                    const fullPath = outputPath.startsWith("/")
-                        ? outputPath
-                        : join(config.outputDir, outputPath);
-                    mkdirSync(join(fullPath, ".."), { recursive: true });
-                    writeFileSync(fullPath, content, "utf-8");
-                    savedPath = fullPath;
+                    const resolvedOutputDir = resolve(config.outputDir);
+                    const resolvedPath = isAbsolute(outputPath)
+                        ? resolve(outputPath)
+                        : resolve(config.outputDir, outputPath);
+                    // Path traversal guard: resolved path must stay within outputDir
+                    const rel = relative(resolvedOutputDir, resolvedPath);
+                    if (rel.startsWith("..") || isAbsolute(rel)) {
+                        throw new Error(`SECURITY: Output path must be within the configured output directory (${resolvedOutputDir})`);
+                    }
+                    mkdirSync(resolve(resolvedPath, ".."), { recursive: true });
+                    writeFileSync(resolvedPath, content, "utf-8");
+                    savedPath = resolvedPath;
                 }
                 const summary = `✓ Report generated (${fmt})\n` +
                     (savedPath ? `Saved to: ${savedPath}\n` : "") +
@@ -73,20 +105,89 @@ export function registerReportTools(ext, config) {
     };
     ext.registerTool(reportTool);
 }
-function generateMarkdownReport(audit) {
+// ---------------------------------------------------------------------------
+// Report generators
+// ---------------------------------------------------------------------------
+function generateMarkdownReport(audit, config) {
+    if (Array.isArray(audit)) {
+        return generateBatchMarkdownReport(audit, config);
+    }
+    const esc = escapeMarkdown;
     const lines = [
         `# SEO Audit Report`,
         ``,
-        `**URL:** ${audit.url}`,
-        `**Date:** ${audit.auditedAt}`,
+        `**URL:** ${esc(audit.url)}`,
+        `**Date:** ${esc(audit.auditedAt)}`,
         `**Overall Score:** ${audit.overallScore}/100`,
         ``,
     ];
+    // --- Severity Summary ---
+    lines.push(...buildSeveritySummary(audit.allIssues));
+    lines.push(``);
+    // Unified score breakdown table
+    lines.push(`## Category Scores`);
+    lines.push(`| Category | Score | Status |`);
+    lines.push(`|----------|-------|--------|`);
+    if (audit.technical) {
+        lines.push(`| Technical SEO | ${audit.technical.score}/100 | ✅ |`);
+    }
+    if (audit.content) {
+        lines.push(`| Content Quality | ${audit.content.overallQuality}/100 | ✅ |`);
+    }
+    if (audit.schema) {
+        lines.push(`| Schema | ${audit.schema.score}/100 | ✅ |`);
+    }
+    if (audit.images) {
+        lines.push(`| Images | ${audit.images.score}/100 | ✅ |`);
+    }
+    if (audit.preload) {
+        lines.push(`| Preload | ${audit.preload.score}/100 | ✅ |`);
+    }
+    if (audit.agentUx) {
+        lines.push(`| Agent UX | ${audit.agentUx.agentUxScore}/100 | ✅ |`);
+    }
+    else if (audit.skippedCategories.includes("agentUx") || !audit.rendererAvailable) {
+        lines.push(`| Agent UX | — | ⏭️ Skipped |`);
+    }
+    if (audit.performance) {
+        const perfSource = audit.performance.source ? ` (${audit.performance.source})` : "";
+        lines.push(`| Performance | ${audit.performance.score}/100 | ✅${perfSource} |`);
+    }
+    lines.push(``);
+    // --- Reproducibility ---
+    lines.push(`## Reproducibility`, ``);
+    lines.push(`- **User Agent:** \`${esc(config.userAgent)}\``);
+    lines.push(`- **Viewport:** ${esc(config.defaultViewport)}`);
+    lines.push(`- **Timeout:** ${config.timeout}ms`);
+    lines.push(`- **Timestamp:** ${esc(audit.auditedAt)}`);
+    lines.push(`- **Renderer:** ${audit.rendererAvailable ? "Available (Playwright/Chromium)" : "Unavailable"}`);
+    lines.push(`- **Audit Version:** ${audit.version ?? 1}`);
+    lines.push(``);
+    // Skipped / Failed Categories
+    if (audit.skippedCategories.length > 0) {
+        lines.push(`## Skipped / Failed Categories`);
+        lines.push(``);
+        for (const cat of audit.skippedCategories) {
+            lines.push(`- **${esc(cat)}** — not analyzed in this audit`);
+        }
+        if (!audit.rendererAvailable) {
+            lines.push(``);
+            lines.push(`_Browser rendering was not available. Agent UX and measured performance data are unavailable._`);
+        }
+        lines.push(``);
+    }
+    else if (!audit.rendererAvailable) {
+        lines.push(`## Skipped / Failed Categories`);
+        lines.push(``);
+        lines.push(`_Browser rendering was not available. Agent UX and measured performance data are unavailable._`);
+        lines.push(``);
+    }
+    // --- Technical SEO ---
     if (audit.technical) {
         lines.push(`## Technical SEO`, `**Score:** ${audit.technical.score}/100`, ``);
         lines.push(`| Category | Score |`, `|----------|-------|`);
         for (const [cat, score] of Object.entries(audit.technical.categoryScores)) {
-            lines.push(`| ${cat} | ${score}/100 |`);
+            lines.push(`| ${esc(cat)} | ${score}/100 |`);
         }
         lines.push(``);
         lines.push(`**HTTPS:** ${audit.technical.isHttps ? "✓" : "✗"}`);
@@ -94,49 +195,225 @@ function generateMarkdownReport(audit) {
         lines.push(`**robots.txt:** ${audit.technical.robotsTxt.exists ? "✓" : "✗"}`);
         lines.push(``);
     }
+    // --- Content Quality ---
     if (audit.content) {
-        lines.push(`## Content Quality`, `**Overall Quality:** ${audit.content.overallQuality}/100`, ``, `- Word count: ${audit.content.wordCount}`, `- Filler score: ${audit.content.fillerScore}/100`, `- AI pattern score: ${audit.content.aiPatternScore}/100`, `- Information density: ${audit.content.informationDensity}/100`, `- Repetition score: ${audit.content.repetitionScore}/100`, `- Flags: ${audit.content.flags.join(", ") || "none"}`, ``);
+        lines.push(`## Content Quality`, `**Overall Quality:** ${audit.content.overallQuality}/100`, ``, `- Word count: ${audit.content.wordCount}`, `- Filler score: ${audit.content.fillerScore}/100`, `- AI pattern score: ${audit.content.aiPatternScore}/100`, `- Information density: ${audit.content.informationDensity}/100`, `- Repetition score: ${audit.content.repetitionScore}/100`, `- Flags: ${audit.content.flags.map((f) => esc(f)).join(", ") || "none"}`, ``);
     }
+    // --- Schema Markup ---
     if (audit.schema) {
-        lines.push(`## Schema Markup`, `**Detected schemas:** ${audit.schema.detectedSchemas.length}`, `**Deprecated types:** ${audit.schema.deprecatedTypes.join(", ") || "none"}`, ``);
+        lines.push(`## Schema Markup`, `**Detected schemas:** ${audit.schema.detectedSchemas.length}`, `**Deprecated types:** ${audit.schema.deprecatedTypes.map((t) => esc(t)).join(", ") || "none"}`, ``);
         if (audit.schema.recommendations.length > 0) {
             lines.push(`**Recommendations:**`);
             for (const rec of audit.schema.recommendations) {
-                lines.push(`- ${rec}`);
+                lines.push(`- ${esc(rec)}`);
             }
             lines.push(``);
         }
     }
+    // --- Images ---
     if (audit.images) {
         lines.push(`## Images`, `**Total:** ${audit.images.totalImages}`, `**Missing alt:** ${audit.images.missingAlt}`, `**Missing dimensions:** ${audit.images.missingDimensions}`, `**Modern formats:** ${audit.images.modernFormats}`, ``);
     }
+    // --- Preload & bfcache ---
     if (audit.preload) {
         lines.push(`## Preload & bfcache`, `**Score:** ${audit.preload.score}/100`, `**Speculation rules:** ${audit.preload.speculationRules.inlineBlocks} inline blocks`, `**Preload hints:** ${audit.preload.preloadHints}`, ``);
     }
+    // --- Agent UX ---
     if (audit.agentUx) {
         lines.push(`## Agent UX`, `**Score:** ${audit.agentUx.agentUxScore}/100`, `**Real buttons:** ${audit.agentUx.html.realButtons}`, `**Real anchors:** ${audit.agentUx.html.realAnchors}`, `**div onclick widgets:** ${audit.agentUx.html.divOnclickWidgets}`, ``);
     }
+    // --- Performance ---
+    if (audit.performance) {
+        const perf = audit.performance;
+        lines.push(`## Performance`, `**Score:** ${perf.score}/100`, ``);
+        lines.push(`- **LCP:** ${perf.lcp.value.toFixed(1)}ms (${perf.lcp.rating})` +
+            (perf.lcp.element
+                ? typeof perf.lcp.element === "string"
+                    ? ` — element: \`${esc(perf.lcp.element)}\``
+                    : ` — element: \`<${perf.lcp.element.tagName}>\`${perf.lcp.element.id ? ` #${perf.lcp.element.id}` : ""}${perf.lcp.element.src ? ` src=${perf.lcp.element.src}` : ""}${perf.lcp.element.size ? ` ${perf.lcp.element.size}` : ""}`
+                : ""));
+        lines.push(`- **CLS:** ${perf.cls.value.toFixed(3)} (${perf.cls.rating})`);
+        lines.push(`- **TBT:** ${perf.tbt.value.toFixed(1)}ms (${perf.tbt.rating})`);
+        lines.push(`- **FCP:** ${perf.fcp.value.toFixed(1)}ms (${perf.fcp.rating})`);
+        lines.push(`- **TTFB:** ${perf.ttfb.value.toFixed(1)}ms (${perf.ttfb.rating})`);
+        if (perf.source) {
+            lines.push(`- **Source:** ${perf.source}`);
+        }
+        lines.push(``);
+        if (perf.desktop) {
+            const d = perf.desktop;
+            lines.push(`### Desktop vs Mobile Comparison`, ``);
+            lines.push(`| Metric | Mobile | Desktop | Difference |`);
+            lines.push(`|--------|--------|---------|------------|`);
+            lines.push(`| LCP | ${perf.lcp.value.toFixed(1)}ms (${perf.lcp.rating}) | ${d.lcp.value.toFixed(1)}ms (${d.lcp.rating}) | ${diffMs(perf.lcp.value, d.lcp.value)} |`);
+            lines.push(`| CLS | ${perf.cls.value.toFixed(3)} (${perf.cls.rating}) | ${d.cls.value.toFixed(3)} (${d.cls.rating}) | ${diffMs(perf.cls.value, d.cls.value)} |`);
+            lines.push(`| TBT | ${perf.tbt.value.toFixed(1)}ms (${perf.tbt.rating}) | ${d.tbt.value.toFixed(1)}ms (${d.tbt.rating}) | ${diffMs(perf.tbt.value, d.tbt.value)} |`);
+            lines.push(``);
+        }
+    }
+    // --- Page Weight ---
+    if (audit.pageWeight) {
+        const pw = audit.pageWeight;
+        lines.push(`## Page Weight`, `**Total:** ${pw.totalKb.toFixed(1)} KB`, `**Resources:** ${pw.resourceCount}`, ``, `| Type | Size (KB) |`, `|------|-----------|`, `| HTML | ${pw.htmlKb.toFixed(1)} |`, `| CSS | ${pw.cssKb.toFixed(1)} |`, `| JS | ${pw.jsKb.toFixed(1)} |`, `| Images | ${pw.imageKb.toFixed(1)} |`, `| Fonts | ${pw.fontKb.toFixed(1)} |`, `| Other | ${pw.otherKb.toFixed(1)} |`, ``);
+        if (pw.topHeavyResources.length > 0) {
+            lines.push(`**Heaviest resources:**`);
+            for (const r of pw.topHeavyResources) {
+                lines.push(`- \`${esc(r.url)}\` — ${r.sizeKb.toFixed(1)} KB (${esc(r.type)})`);
+            }
+            lines.push(``);
+        }
+    }
+    // --- Render Blocking ---
+    if (audit.renderBlocking) {
+        const rb = audit.renderBlocking;
+        lines.push(`## Render Blocking`, `**Total blocking URLs:** ${rb.totalBlockingUrls}`, ``);
+        if (rb.blockingCss.length > 0) {
+            lines.push(`**Blocking CSS:**`);
+            for (const css of rb.blockingCss) {
+                lines.push(`- \`${esc(css.href)}\` (est. ${css.sizeEstimate} bytes)`);
+            }
+            lines.push(``);
+        }
+        if (rb.blockingJs.length > 0) {
+            lines.push(`**Blocking JS:**`);
+            for (const js of rb.blockingJs) {
+                lines.push(`- \`${esc(js.src)}\` (est. ${js.sizeEstimate} bytes)`);
+            }
+            lines.push(``);
+        }
+        if (rb.recommendations.length > 0) {
+            lines.push(`**Recommendations:**`);
+            for (const rec of rb.recommendations) {
+                lines.push(`- ${esc(rec)}`);
+            }
+            lines.push(``);
+        }
+    }
+    // --- Font Audit ---
+    if (audit.fontAudit) {
+        const fa = audit.fontAudit;
+        lines.push(`## Font Audit`, `**Score:** ${fa.score}/100`, `**Has font-display:** ${fa.hasFontDisplay ? "✓" : "✗"}`, `**Fonts found:** ${fa.fontsFound.length}`, ``);
+        if (fa.fontsFound.length > 0) {
+            lines.push(`| Family | Source | Format | font-display | Subset |`);
+            lines.push(`|--------|--------|--------|--------------|--------|`);
+            for (const f of fa.fontsFound) {
+                lines.push(`| ${esc(f.family)} | ${esc(f.source)} | ${esc(f.format)} | ${f.hasDisplay ? "✓" : "✗"} | ${f.isSubset ? "✓" : "✗"} |`);
+            }
+            lines.push(``);
+        }
+        if (fa.recommendations.length > 0) {
+            lines.push(`**Recommendations:**`);
+            for (const rec of fa.recommendations) {
+                lines.push(`- ${esc(rec)}`);
+            }
+            lines.push(``);
+        }
+    }
+    // --- Sitemap ---
+    if (audit.sitemap) {
+        const sm = audit.sitemap;
+        lines.push(`## Sitemap`, `**URL:** ${esc(sm.url)}`, `**URL count:** ${sm.urlCount}`, `**Size:** ${(sm.sizeBytes / 1024).toFixed(1)} KB`, `**Lastmod coverage:** ${(sm.lastmodCoverage * 100).toFixed(0)}%`, `**Invalid entries:** ${sm.invalidEntries}`, `**Is sitemap index:** ${sm.isSitemapIndex ? "Yes" : "No"}`, ``);
+        if (sm.warnings.length > 0) {
+            lines.push(`**Warnings:**`);
+            for (const w of sm.warnings) {
+                lines.push(`- ${esc(w)}`);
+            }
+            lines.push(``);
+        }
+        if (sm.childSitemaps.length > 0) {
+            lines.push(`**Child sitemaps:**`);
+            for (const cs of sm.childSitemaps) {
+                lines.push(`- ${esc(cs)}`);
+            }
+            lines.push(``);
+        }
+    }
+    // --- Issues ---
     if (audit.allIssues.length > 0) {
         lines.push(`## Issues (${audit.allIssues.length})`, ``);
         const sorted = audit.allIssues.sort((a, b) => severityRank(a.severity) - severityRank(b.severity));
         for (const issue of sorted) {
-            lines.push(`### [${issue.severity.toUpperCase()}] ${issue.title}`);
-            lines.push(`**Category:** ${issue.category}`);
-            lines.push(`**Description:** ${issue.description}`);
-            lines.push(`**Recommendation:** ${issue.recommendation}`);
+            lines.push(`### [${issue.severity.toUpperCase()}] ${esc(issue.title)}`);
+            lines.push(`**Category:** ${esc(issue.category)}`);
+            lines.push(`**Description:** ${esc(issue.description)}`);
+            lines.push(`**Recommendation:** ${esc(issue.recommendation)}`);
             lines.push(``);
         }
     }
     return lines.join("\n");
 }
-function generateHtmlReport(audit) {
-    const md = generateMarkdownReport(audit);
-    // Simple HTML wrapper around markdown content.
+function generateBatchMarkdownReport(audits, config) {
+    const esc = escapeMarkdown;
+    if (audits.length === 0)
+        return "# Batch SEO Report\n\nNo results provided.";
+    const lines = [
+        `# Batch SEO Report`,
+        ``,
+        `**Pages audited:** ${audits.length}`,
+        `**Generated:** ${new Date().toISOString()}`,
+        ``,
+    ];
+    const scores = audits.map((a) => a.overallScore);
+    const avgScore = Math.round(scores.reduce((a, b) => a + b, 0) / scores.length);
+    const minScore = Math.min(...scores);
+    const maxScore = Math.max(...scores);
+    lines.push(`## Summary`, ``, `- **Average score:** ${avgScore}/100`, `- **Range:** ${minScore} — ${maxScore}`, `- **Worst page:** ${esc(audits.find((a) => a.overallScore === minScore)?.url ?? "-")}`, `- **Best page:** ${esc(audits.find((a) => a.overallScore === maxScore)?.url ?? "-")}`, ``);
+    const allIssues = audits.flatMap((a) => a.allIssues);
+    const severityCounts = { critical: 0, high: 0, medium: 0, low: 0 };
+    for (const issue of allIssues) {
+        severityCounts[issue.severity] = (severityCounts[issue.severity] ?? 0) + 1;
+    }
+    lines.push(`## Aggregate Severity`, ``, `| Severity | Count |`, `|----------|-------|`, `| Critical | ${severityCounts.critical} |`, `| High     | ${severityCounts.high} |`, `| Medium   | ${severityCounts.medium} |`, `| Low      | ${severityCounts.low} |`, `| **Total** | **${allIssues.length}** |`, ``);
+    // Skipped categories summary in batch
+    const pagesWithSkipped = audits.filter((a) => a.skippedCategories.length > 0);
+    if (pagesWithSkipped.length > 0) {
+        lines.push(`## Skipped / Failed Categories`, ``, `**${pagesWithSkipped.length}** of **${audits.length}** pages had skipped categories (e.g. renderer unavailable, fetch failed).`, ``);
+    }
+    lines.push(`## Per-Page Scores`, ``, `| URL | Score | Issues |`, `|-----|-------|--------|`);
+    const sorted = [...audits].sort((a, b) => b.overallScore - a.overallScore);
+    for (const a of sorted) {
+        lines.push(`| ${esc(a.url)} | ${a.overallScore}/100 | ${a.allIssues.length} |`);
+    }
+    lines.push(``);
+    const issueFreq = new Map();
+    for (const issue of allIssues) {
+        const key = issue.title.toLowerCase();
+        if (issueFreq.has(key)) {
+            issueFreq.get(key).count++;
+        }
+        else {
+            issueFreq.set(key, { title: issue.title, count: 1, severity: issue.severity });
+        }
+    }
+    const topIssues = [...issueFreq.values()]
+        .sort((a, b) => b.count - a.count)
+        .slice(0, 10);
+    if (topIssues.length > 0) {
+        lines.push(`## Top 10 Issues Across All Pages`, ``, `| Issue | Severity | Pages Affected |`, `|-------|----------|----------------|`);
+        for (const ti of topIssues) {
+            lines.push(`| ${esc(ti.title)} | ${ti.severity} | ${ti.count} |`);
+        }
+        lines.push(``);
+    }
+    return lines.join("\n");
+}
+function diffMs(a, b) {
+    const delta = a - b;
+    const sign = delta > 0 ? "+" : "";
+    const absDelta = Math.abs(delta);
+    if (absDelta < 1)
+        return `${sign}${delta.toFixed(3)}`;
+    if (absDelta < 10)
+        return `${sign}${delta.toFixed(1)}ms`;
+    return `${sign}${Math.round(delta)}ms`;
+}
+function generateHtmlReport(audit, config) {
+    const md = generateMarkdownReport(audit, config);
     return `<!DOCTYPE html>
 <html>
 <head>
 <meta charset="utf-8">
-<title>SEO Audit Report — ${audit.url}</title>
+<title>SEO Audit Report — ${escapeHtml(audit.url)}</title>
 <style>
 body { font-family: system-ui, sans-serif; max-width: 900px; margin: 2rem auto; padding: 0 1rem; line-height: 1.6; }
 h1 { border-bottom: 2px solid #333; }
@@ -150,18 +427,207 @@ td, th { border: 1px solid #ddd; padding: 0.5rem; }
 </body>
 </html>`;
 }
+function generateSarifReport(audit) {
+    return generateSarifSingleReport(audit, audit.allIssues ?? []);
+}
+function generateSarifSingleReport(audit, issues) {
+    // Build unique rules
+    const rules = [];
+    const seenRuleIds = new Set();
+    for (const issue of issues) {
+        const categorySlug = issue.category.toLowerCase().replace(/\s+/g, "-");
+        const ruleId = issue.issueId ?? `seo-${categorySlug}-${issue.severity}`;
+        if (!seenRuleIds.has(ruleId)) {
+            seenRuleIds.add(ruleId);
+            rules.push({
+                id: ruleId,
+                name: ruleId,
+                shortDescription: { text: `${issue.category}: ${issue.title}` },
+            });
+        }
+    }
+    // Build results with ruleIndex, properties, partialFingerprints
+    const results = issues.map((issue, i) => {
+        const categorySlug = issue.category.toLowerCase().replace(/\s+/g, "-");
+        const ruleId = issue.issueId ?? `seo-${categorySlug}-${issue.severity}`;
+        const ruleIndex = rules.findIndex((r) => r.id === ruleId);
+        return {
+            ruleId,
+            ruleIndex,
+            level: severityToSarifLevel(issue.severity),
+            message: { text: `${issue.title}: ${issue.description} \u2014 ${issue.recommendation}` },
+            locations: [{
+                    physicalLocation: { artifactLocation: { uri: audit.url } },
+                }],
+            properties: {
+                category: issue.category,
+                severity: issue.severity,
+                score: audit.overallScore,
+            },
+            partialFingerprints: {
+                issueHash: `${ruleId}-${i}`,
+            },
+        };
+    });
+    return {
+        $schema: "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json",
+        version: "2.1.0",
+        runs: [
+            {
+                tool: {
+                    driver: {
+                        name: "Spectral SEO Auditor",
+                        version: "1.0.0",
+                        semanticVersion: "1.0.0",
+                        informationUri: "https://aexol.com",
+                        rules,
+                    },
+                },
+                invocation: {
+                    executionSuccessful: true,
+                    startTimeUtc: audit.auditedAt,
+                    endTimeUtc: new Date().toISOString(),
+                    arguments: [
+                        `url=${audit.url}`,
+                    ],
+                },
+                results,
+            },
+        ],
+    };
+}
+function generateSarifBatchReport(results, _config) {
+    const allIssues = results.flatMap((r) => r.allIssues ?? []);
+    // Build unique rules across all audits
+    const rules = [];
+    const seenRuleIds = new Set();
+    for (const issue of allIssues) {
+        const categorySlug = issue.category.toLowerCase().replace(/\s+/g, "-");
+        const ruleId = issue.issueId ?? `seo-${categorySlug}-${issue.severity}`;
+        if (!seenRuleIds.has(ruleId)) {
+            seenRuleIds.add(ruleId);
+            rules.push({
+                id: ruleId,
+                name: ruleId,
+                shortDescription: { text: `${issue.category}: ${issue.title}` },
+            });
+        }
+    }
+    const sarifResults = allIssues.map((issue, i) => {
+        const categorySlug = issue.category.toLowerCase().replace(/\s+/g, "-");
+        const ruleId = issue.issueId ?? `seo-${categorySlug}-${issue.severity}`;
+        const ruleIndex = rules.findIndex((r) => r.id === ruleId);
+        return {
+            ruleId,
+            ruleIndex,
+            level: severityToSarifLevel(issue.severity),
+            message: { text: `${issue.title}: ${issue.description} \u2014 ${issue.recommendation}` },
+            locations: [{
+                    physicalLocation: { artifactLocation: { uri: results[0]?.url ?? "unknown" } },
+                }],
+            properties: {
+                category: issue.category,
+                severity: issue.severity,
+            },
+            partialFingerprints: {
+                issueHash: `${ruleId}-${i}`,
+            },
+        };
+    });
+    return {
+        $schema: "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json",
+        version: "2.1.0",
+        runs: [
+            {
+                tool: {
+                    driver: {
+                        name: "Spectral SEO Auditor",
+                        version: "1.0.0",
+                        semanticVersion: "1.0.0",
+                        informationUri: "https://aexol.com",
+                        rules,
+                    },
+                },
+                invocation: {
+                    executionSuccessful: true,
+                    startTimeUtc: results.reduce((earliest, r) => r.auditedAt < earliest ? r.auditedAt : earliest, results[0]?.auditedAt ?? new Date().toISOString()),
+                    endTimeUtc: new Date().toISOString(),
+                    arguments: results.map((r) => `url=${r.url}`),
+                },
+                results: sarifResults,
+            },
+        ],
+    };
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function buildSeveritySummary(issues) {
+    const counts = { critical: 0, high: 0, medium: 0, low: 0 };
+    for (const issue of issues) {
+        counts[issue.severity] = (counts[issue.severity] ?? 0) + 1;
+    }
+    const total = issues.length;
+    return [
+        `## Severity Summary`,
+        ``,
+        `| Severity | Count |`,
+        `|----------|-------|`,
+        `| Critical | ${counts.critical} |`,
+        `| High     | ${counts.high} |`,
+        `| Medium   | ${counts.medium} |`,
+        `| Low      | ${counts.low} |`,
+        `| **Total** | **${total}** |`,
+    ];
+}
+// toSarifResult removed — logic inlined in generateSarifSingleReport and generateSarifBatchReport
+function severityToSarifLevel(s) {
+    switch (s) {
+        case "critical":
+        case "high":
+            return "error";
+        case "medium":
+            return "warning";
+        case "low":
+            return "note";
+        default:
+            return "none";
+    }
+}
+/** HTML-escape user-supplied text to prevent injection and Markdown breakage. */
 function escapeHtml(text) {
     return text
         .replace(/&/g, "&amp;")
         .replace(/</g, "&lt;")
-        .replace(/>/g, "&gt;");
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&#39;")
+        .replace(/=/g, "&#x3D;");
+}
+/** Escape user-supplied values for safe embedding in Markdown content. */
+function escapeMarkdown(text) {
+    return escapeHtml(text)
+        .replace(/\|/g, "\\|")
+        .replace(/`/g, "\\`")
+        .replace(/\*/g, "\\*")
+        .replace(/_/g, "\\_")
+        .replace(/\[/g, "\\[")
+        .replace(/\]/g, "\\]")
+        .replace(/#/g, "\\#")
+        .replace(/!/g, "\\!")
+        .replace(/~/g, "\\~");
 }
 function severityRank(s) {
     switch (s) {
-        case "critical": return 0;
-        case "high": return 1;
-        case "medium": return 2;
-        case "low": return 3;
-        default: return 4;
+        case "critical":
+            return 0;
+        case "high":
+            return 1;
+        case "medium":
+            return 2;
+        case "low":
+            return 3;
+        default:
+            return 4;
     }
 }