Skip to content

High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.

5.5 KB
Raw Blame
// Package report renders audit results into human-readable Markdown and
// self-contained HTML. Sections without data are omitted entirely (the
// documented empty-section policy); the JSON report remains the complete
// machine interface. Rendering is deterministic: stable section and item
// ordering, sorted map keys, and no wall-clock reads — the only timestamp
// is the report's own GeneratedAt.
package report

import (
	"fmt"
	"sort"
	"strings"

	"github.com/pinchtab/pinchtab/internal/audit"
)

// Formats accepted by Render.
const (
	FormatJSON     = "json"
	FormatMarkdown = "md"
	FormatHTML     = "html"
)

// Render renders an AuditReport as Markdown or HTML. FormatJSON is the
// caller's business (the report already is JSON) and is rejected here.
func Render(r audit.AuditReport, format string) ([]byte, error) {
	switch format {
	case FormatMarkdown:
		return renderMarkdown(r), nil
	case FormatHTML:
		return renderHTML(r)
	default:
		return nil, fmt.Errorf("unsupported render format %q (md|html)", format)
	}
}

// RenderComparison renders a ComparisonReport as Markdown or HTML.
func RenderComparison(r audit.ComparisonReport, format string) ([]byte, error) {
	switch format {
	case FormatMarkdown:
		return renderComparisonMarkdown(r), nil
	case FormatHTML:
		return renderComparisonHTML(r)
	default:
		return nil, fmt.Errorf("unsupported render format %q (md|html)", format)
	}
}

func pageLabel(p audit.PageResult) string {
	if p.Title != "" {
		return p.Title
	}
	return p.URL
}

func hasSeaportal(r audit.AuditReport) bool {
	for _, p := range r.Pages {
		if len(p.Seaportal) > 0 {
			return true
		}
	}
	return false
}

func hasVisualDiff(r audit.AuditReport) bool {
	for _, p := range r.Pages {
		if p.Browser.VisualDiff != nil {
			return true
		}
	}
	return false
}

func hasTiming(r audit.AuditReport) bool {
	for _, p := range r.Pages {
		if p.Browser.TimingMetrics != (audit.BrowserTimingMetrics{}) {
			return true
		}
	}
	return false
}

func hasElements(r audit.AuditReport) bool {
	for _, p := range r.Pages {
		if len(p.Browser.InteractiveElements) > 0 {
			return true
		}
	}
	return false
}

// consoleProblems returns the error and warning console entries of a page.
func consoleProblems(p audit.PageResult) []audit.ConsoleLogEntry {
	var out []audit.ConsoleLogEntry
	for _, l := range p.Browser.ConsoleLogs {
		if l.Level == "error" || l.Level == "warning" || l.Level == "warn" {
			out = append(out, l)
		}
	}
	return out
}

func hasConsoleProblems(r audit.AuditReport) bool {
	for _, p := range r.Pages {
		if len(consoleProblems(p)) > 0 {
			return true
		}
	}
	return false
}

func hasJSErrors(r audit.AuditReport) bool {
	for _, p := range r.Pages {
		if len(p.Browser.JSErrors) > 0 {
			return true
		}
	}
	return false
}

// firstLine trims an exception message down to its first line, so a stack trace
// never breaks the list or table cell it is rendered into.
func firstLine(s string) string {
	if i := strings.IndexByte(s, '\n'); i >= 0 {
		return strings.TrimSpace(s[:i])
	}
	return strings.TrimSpace(s)
}

func hasBrokenAssets(r audit.AuditReport) bool {
	for _, p := range r.Pages {
		if len(p.Browser.BrokenAssets) > 0 {
			return true
		}
	}
	return false
}

// usabilityPages are the pages with a below-perfect accessibility score.
func usabilityPages(r audit.AuditReport) []audit.PageResult {
	var out []audit.PageResult
	for _, p := range r.Pages {
		if p.Error == "" && p.Browser.AccessibilityScore < 100 {
			out = append(out, p)
		}
	}
	return out
}

func totalBrokenAssets(r audit.AuditReport) int {
	n := 0
	for _, p := range r.Pages {
		n += len(p.Browser.BrokenAssets)
	}
	return n
}

func totalJSErrors(r audit.AuditReport) int {
	n := 0
	for _, p := range r.Pages {
		n += len(p.Browser.JSErrors)
	}
	return n
}

func totalConsoleErrors(r audit.AuditReport) int {
	n := 0
	for _, p := range r.Pages {
		for _, l := range p.Browser.ConsoleLogs {
			if l.Level == "error" {
				n++
			}
		}
	}
	return n
}

// recommendations merges the report's explicit recommendations with
// rule-derived ones, in a stable order.
func recommendations(r audit.AuditReport) []string {
	recs := append([]string(nil), r.Recommendations...)
	if n := totalBrokenAssets(r); n > 0 {
		recs = append(recs, fmt.Sprintf("Fix %d broken asset reference(s) — see Broken Assets.", n))
	}
	if n := totalJSErrors(r); n > 0 {
		recs = append(recs, fmt.Sprintf("Fix %d uncaught JS error(s) — each halts the script that raised it; see Console & JS Errors.", n))
	}
	if n := totalConsoleErrors(r); n > 0 {
		recs = append(recs, fmt.Sprintf("Investigate %d console error(s) — see Console & JS Errors.", n))
	}
	if pages := usabilityPages(r); len(pages) > 0 {
		recs = append(recs, fmt.Sprintf("Improve accessibility on %d page(s) scoring below 100 — see Usability Issues.", len(pages)))
	}
	if n := len(r.SecurityFindings); n > 0 {
		recs = append(recs, fmt.Sprintf("Address %d security finding(s) — see Security Findings.", n))
	}
	failed := 0
	for _, p := range r.Pages {
		if p.Error != "" {
			failed++
		}
	}
	if failed > 0 {
		recs = append(recs, fmt.Sprintf("Re-check %d page(s) that failed to audit.", failed))
	}
	return recs
}

// sortedKeys returns a map's keys in stable sorted order.
func sortedKeys(m map[string]any) []string {
	keys := make([]string, 0, len(m))
	for k := range m {
		keys = append(keys, k)
	}
	sort.Strings(keys)
	return keys
}

func formatMs(v float64) string {
	if v == 0 {
		return "-"
	}
	return fmt.Sprintf("%.0f ms", v)
}

func formatCLS(v float64) string {
	if v == 0 {
		return "0"
	}
	return strings.TrimRight(strings.TrimRight(fmt.Sprintf("%.3f", v), "0"), ".")
}