Skip to content

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

feat: define audit data model and report schema in internal/audit

Luigi Agostiab761bd33795
diff --git a/internal/audit/types.go b/internal/audit/types.go
new file mode 100644
index 00000000..54cb3fc9
--- /dev/null
+++ b/internal/audit/types.go
@@ -0,0 +1,222 @@
+// Package audit defines the shared data model and versioned report schema
+// for the PinchTab scraping & audit pipeline (docs/pinchtab-scrape-audit-spec.md).
+// Types here are audit-local with camelCase JSON tags; they map from bridge
+// and observe shapes without importing handler types, so downstream consumers
+// (LLM pipelines, CI diffs) can rely on a stable contract.
+package audit
+
+import "time"
+
+// SchemaVersion is the current audit report schema version, embedded in
+// every AuditReport so consumers can detect incompatible changes.
+const SchemaVersion = "1.0"
+
+// ConsoleLogEntry is a single console message captured during page load.
+// It mirrors the bridge console log shape.
+type ConsoleLogEntry struct {
+ // Timestamp is when the message was emitted.
+ Timestamp time.Time `json:"timestamp"`
+ // Level is the console level (log, info, warn, error).
+ Level string `json:"level"`
+ // Message is the console message text.
+ Message string `json:"message"`
+ // Source identifies where the message originated (URL or subsystem).
+ Source string `json:"source,omitempty"`
+}
+
+// NetworkRequest is a single resource request observed while loading a page.
+// It mirrors the observe network entry shape, trimmed to audit-relevant fields.
+type NetworkRequest struct {
+ // URL is the requested resource URL.
+ URL string `json:"url"`
+ // Method is the HTTP method.
+ Method string `json:"method"`
+ // Status is the HTTP response status code, zero if the request never completed.
+ Status int `json:"status,omitempty"`
+ // StatusText is the HTTP status text.
+ StatusText string `json:"statusText,omitempty"`
+ // ResourceType classifies the resource (Document, Image, Script, ...).
+ ResourceType string `json:"resourceType,omitempty"`
+ // MimeType is the response MIME type.
+ MimeType string `json:"mimeType,omitempty"`
+ // StartTime is when the request started.
+ StartTime time.Time `json:"startTime"`
+ // Duration is the request duration in milliseconds.
+ Duration float64 `json:"duration,omitempty"`
+ // Size is the response body size in bytes.
+ Size int64 `json:"size,omitempty"`
+ // Failed reports whether the request failed (network error or HTTP >= 400).
+ Failed bool `json:"failed,omitempty"`
+ // Error is the network error text when the request failed before a response.
+ Error string `json:"error,omitempty"`
+}
+
+// BrokenAsset is a page resource that failed to load (404 images, missing
+// scripts or stylesheets, failed API calls).
+type BrokenAsset struct {
+ // URL is the asset URL that failed.
+ URL string `json:"url"`
+ // ResourceType classifies the asset (Image, Script, Stylesheet, XHR, ...).
+ ResourceType string `json:"resourceType,omitempty"`
+ // Status is the HTTP status code, zero when the failure was a network error.
+ Status int `json:"status,omitempty"`
+ // Error describes the failure when no HTTP status is available.
+ Error string `json:"error,omitempty"`
+}
+
+// InteractiveElement is an actionable element discovered on the page,
+// derived from the accessibility snapshot.
+type InteractiveElement struct {
+ // Ref is the stable snapshot reference (e.g. "e5").
+ Ref string `json:"ref"`
+ // Role is the accessibility role (button, link, textbox, ...).
+ Role string `json:"role"`
+ // Name is the accessible name.
+ Name string `json:"name,omitempty"`
+ // Tag is the underlying HTML tag.
+ Tag string `json:"tag,omitempty"`
+ // Label is the associated form label, when present.
+ Label string `json:"label,omitempty"`
+ // Disabled reports whether the element is disabled.
+ Disabled bool `json:"disabled,omitempty"`
+ // Visible reports whether the element is visible in the layout.
+ Visible bool `json:"visible,omitempty"`
+}
+
+// BrowserTimingMetrics holds browser-level performance timings for a page,
+// in milliseconds unless noted otherwise.
+type BrowserTimingMetrics struct {
+ // TimeToFirstByte is the navigation time-to-first-byte.
+ TimeToFirstByte float64 `json:"timeToFirstByte,omitempty"`
+ // DOMContentLoaded is the DOMContentLoaded event time.
+ DOMContentLoaded float64 `json:"domContentLoaded,omitempty"`
+ // Load is the load event time.
+ Load float64 `json:"load,omitempty"`
+ // FirstContentfulPaint is the FCP Core Web Vital.
+ FirstContentfulPaint float64 `json:"firstContentfulPaint,omitempty"`
+ // LargestContentfulPaint is the LCP Core Web Vital.
+ LargestContentfulPaint float64 `json:"largestContentfulPaint,omitempty"`
+ // CumulativeLayoutShift is the CLS Core Web Vital (unitless score).
+ CumulativeLayoutShift float64 `json:"cumulativeLayoutShift,omitempty"`
+}
+
+// VisualDiffResult is the outcome of comparing a page screenshot against a
+// baseline in compare mode.
+type VisualDiffResult struct {
+ // BaselinePath is the baseline screenshot file path.
+ BaselinePath string `json:"baselinePath"`
+ // CurrentPath is the current screenshot file path.
+ CurrentPath string `json:"currentPath"`
+ // DiffPath is the annotated diff image path, when a diff was rendered.
+ DiffPath string `json:"diffPath,omitempty"`
+ // DiffPixels is the number of pixels that differ.
+ DiffPixels int `json:"diffPixels"`
+ // DiffRatio is the fraction of pixels that differ, in [0,1].
+ DiffRatio float64 `json:"diffRatio"`
+ // Changed reports whether the diff exceeds the change threshold.
+ Changed bool `json:"changed"`
+}
+
+// SecurityFinding is a single security-surface issue detected during an audit
+// (mixed content, exposed endpoint, scanner rule hit).
+type SecurityFinding struct {
+ // RuleID identifies the rule that produced the finding.
+ RuleID string `json:"ruleId"`
+ // Severity is the finding severity (info, low, medium, high, critical).
+ Severity string `json:"severity"`
+ // Detail is a human-readable description of the finding.
+ Detail string `json:"detail"`
+ // URL is the page or resource the finding applies to.
+ URL string `json:"url,omitempty"`
+}
+
+// BrowserPageData is the browser-enriched data captured for a single page.
+type BrowserPageData struct {
+ // ScreenshotPath is the saved screenshot file path.
+ ScreenshotPath string `json:"screenshotPath,omitempty"`
+ // FullPageScreenshot reports whether the screenshot covers the full page.
+ FullPageScreenshot bool `json:"fullPageScreenshot,omitempty"`
+ // ConsoleLogs are the console messages captured during load.
+ ConsoleLogs []ConsoleLogEntry `json:"consoleLogs,omitempty"`
+ // NetworkRequests are the resource requests observed during load.
+ NetworkRequests []NetworkRequest `json:"networkRequests,omitempty"`
+ // BrokenAssets are resources that failed to load, especially 404 images.
+ BrokenAssets []BrokenAsset `json:"brokenAssets,omitempty"`
+ // InteractiveElements are the actionable elements found on the page.
+ InteractiveElements []InteractiveElement `json:"interactiveElements,omitempty"`
+ // AccessibilityScore is the basic a11y score for the page, in [0,100].
+ AccessibilityScore int `json:"accessibilityScore,omitempty"`
+ // VisualDiff is the visual regression result; set only in compare mode.
+ VisualDiff *VisualDiffResult `json:"visualDiff,omitempty"`
+ // TimingMetrics are the browser-level performance timings.
+ TimingMetrics BrowserTimingMetrics `json:"timingMetrics"`
+}
+
+// PageResult is the audit outcome for a single page: its URL, any SeaPortal
+// summary carried over from the input, and the browser-enriched data.
+type PageResult struct {
+ // URL is the audited page URL.
+ URL string `json:"url"`
+ // Title is the page title, when known.
+ Title string `json:"title,omitempty"`
+ // StatusCode is the HTTP status of the page navigation, when known.
+ StatusCode int `json:"statusCode,omitempty"`
+ // Seaportal holds SeaPortal per-page summary fields passed through
+ // verbatim when the input was a SeaPortal results file.
+ Seaportal map[string]any `json:"seaportal,omitempty"`
+ // Browser is the browser-enriched data for the page.
+ Browser BrowserPageData `json:"browser"`
+}
+
+// AuditInput describes where the audited pages came from. Exactly one source
+// is expected to be set.
+type AuditInput struct {
+ // URLs is a direct list of page URLs to audit.
+ URLs []string `json:"urls,omitempty"`
+ // SitemapURL is a sitemap to discover pages from.
+ SitemapURL string `json:"sitemapUrl,omitempty"`
+ // SeaportalFile is the path to a SeaPortal results JSON file.
+ SeaportalFile string `json:"seaportalFile,omitempty"`
+}
+
+// AuditOptions are the run options an audit was executed with.
+type AuditOptions struct {
+ // SampleSize caps how many pages are audited per page group.
+ SampleSize int `json:"sampleSize,omitempty"`
+ // Screenshot enables screenshot capture.
+ Screenshot bool `json:"screenshot,omitempty"`
+ // NetworkMonitor enables network request capture.
+ NetworkMonitor bool `json:"networkMonitor,omitempty"`
+ // VisualDiff enables visual regression against a baseline.
+ VisualDiff bool `json:"visualDiff,omitempty"`
+ // Concurrency is the number of pages audited in parallel.
+ Concurrency int `json:"concurrency,omitempty"`
+ // OutputDir is where screenshots and report artifacts are written.
+ OutputDir string `json:"outputDir,omitempty"`
+}
+
+// AuditReport is the site-level audit result: the versioned top-level schema
+// every audit, compare, and report consumer builds on.
+type AuditReport struct {
+ // SchemaVersion is the report schema version; always SchemaVersion.
+ SchemaVersion string `json:"schemaVersion"`
+ // GeneratedAt is when the report was produced.
+ GeneratedAt time.Time `json:"generatedAt"`
+ // Input describes where the audited pages came from.
+ Input AuditInput `json:"input"`
+ // Options are the run options the audit was executed with.
+ Options AuditOptions `json:"options"`
+ // Pages are the per-page audit results.
+ Pages []PageResult `json:"pages"`
+ // SummaryScore is the overall site score, in [0,100].
+ SummaryScore int `json:"summaryScore"`
+ // SecurityFindings are site-wide security-surface findings.
+ SecurityFindings []SecurityFinding `json:"securityFindings,omitempty"`
+ // Recommendations are human-readable follow-up suggestions.
+ Recommendations []string `json:"recommendations,omitempty"`
+}
+
+// NewAuditReport returns an AuditReport stamped with the current SchemaVersion.
+func NewAuditReport() AuditReport {
+ return AuditReport{SchemaVersion: SchemaVersion}
+}
diff --git a/internal/audit/types_test.go b/internal/audit/types_test.go
new file mode 100644
index 00000000..5d1143bc
--- /dev/null
+++ b/internal/audit/types_test.go
@@ -0,0 +1,138 @@
+package audit
+
+import (
+ "encoding/json"
+ "reflect"
+ "testing"
+ "time"
+)
+
+func roundTrip[T any](t *testing.T, name string, in T) {
+ t.Helper()
+ data, err := json.Marshal(in)
+ if err != nil {
+ t.Fatalf("%s: marshal: %v", name, err)
+ }
+ var out T
+ if err := json.Unmarshal(data, &out); err != nil {
+ t.Fatalf("%s: unmarshal: %v", name, err)
+ }
+ if !reflect.DeepEqual(in, out) {
+ t.Errorf("%s: round-trip mismatch\n in: %#v\nout: %#v", name, in, out)
+ }
+}
+
+var ts = time.Date(2026, 7, 4, 12, 30, 0, 0, time.UTC)
+
+func sampleConsoleLogEntry() ConsoleLogEntry {
+ return ConsoleLogEntry{Timestamp: ts, Level: "error", Message: "boom", Source: "https://example.com/app.js"}
+}
+
+func sampleNetworkRequest() NetworkRequest {
+ return NetworkRequest{
+ URL: "https://example.com/api", Method: "GET", Status: 500, StatusText: "Internal Server Error",
+ ResourceType: "XHR", MimeType: "application/json", StartTime: ts,
+ Duration: 12.5, Size: 2048, Failed: true, Error: "net::ERR_FAILED",
+ }
+}
+
+func sampleBrokenAsset() BrokenAsset {
+ return BrokenAsset{URL: "https://example.com/logo.png", ResourceType: "Image", Status: 404, Error: "not found"}
+}
+
+func sampleInteractiveElement() InteractiveElement {
+ return InteractiveElement{Ref: "e5", Role: "button", Name: "Submit", Tag: "button", Label: "Submit form", Disabled: true, Visible: true}
+}
+
+func sampleTimingMetrics() BrowserTimingMetrics {
+ return BrowserTimingMetrics{
+ TimeToFirstByte: 80, DOMContentLoaded: 350, Load: 900,
+ FirstContentfulPaint: 400, LargestContentfulPaint: 850, CumulativeLayoutShift: 0.05,
+ }
+}
+
+func sampleVisualDiff() VisualDiffResult {
+ return VisualDiffResult{
+ BaselinePath: "base.png", CurrentPath: "cur.png", DiffPath: "diff.png",
+ DiffPixels: 120, DiffRatio: 0.02, Changed: true,
+ }
+}
+
+func sampleSecurityFinding() SecurityFinding {
+ return SecurityFinding{RuleID: "mixed-content", Severity: "medium", Detail: "http resource on https page", URL: "https://example.com"}
+}
+
+func sampleBrowserPageData() BrowserPageData {
+ diff := sampleVisualDiff()
+ return BrowserPageData{
+ ScreenshotPath: "page.png", FullPageScreenshot: true,
+ ConsoleLogs: []ConsoleLogEntry{sampleConsoleLogEntry()},
+ NetworkRequests: []NetworkRequest{sampleNetworkRequest()},
+ BrokenAssets: []BrokenAsset{sampleBrokenAsset()},
+ InteractiveElements: []InteractiveElement{sampleInteractiveElement()},
+ AccessibilityScore: 87,
+ VisualDiff: &diff,
+ TimingMetrics: sampleTimingMetrics(),
+ }
+}
+
+func samplePageResult() PageResult {
+ return PageResult{
+ URL: "https://example.com", Title: "Example", StatusCode: 200,
+ Seaportal: map[string]any{"group": "home", "wordCount": float64(1200)},
+ Browser: sampleBrowserPageData(),
+ }
+}
+
+func sampleAuditInput() AuditInput {
+ return AuditInput{URLs: []string{"https://example.com"}, SitemapURL: "https://example.com/sitemap.xml", SeaportalFile: "report.json"}
+}
+
+func sampleAuditOptions() AuditOptions {
+ return AuditOptions{SampleSize: 5, Screenshot: true, NetworkMonitor: true, VisualDiff: true, Concurrency: 4, OutputDir: "out"}
+}
+
+func sampleAuditReport() AuditReport {
+ r := NewAuditReport()
+ r.GeneratedAt = ts
+ r.Input = sampleAuditInput()
+ r.Options = sampleAuditOptions()
+ r.Pages = []PageResult{samplePageResult()}
+ r.SummaryScore = 91
+ r.SecurityFindings = []SecurityFinding{sampleSecurityFinding()}
+ r.Recommendations = []string{"fix broken logo image"}
+ return r
+}
+
+func TestJSONRoundTrip(t *testing.T) {
+ roundTrip(t, "ConsoleLogEntry", sampleConsoleLogEntry())
+ roundTrip(t, "NetworkRequest", sampleNetworkRequest())
+ roundTrip(t, "BrokenAsset", sampleBrokenAsset())
+ roundTrip(t, "InteractiveElement", sampleInteractiveElement())
+ roundTrip(t, "BrowserTimingMetrics", sampleTimingMetrics())
+ roundTrip(t, "VisualDiffResult", sampleVisualDiff())
+ roundTrip(t, "SecurityFinding", sampleSecurityFinding())
+ roundTrip(t, "BrowserPageData", sampleBrowserPageData())
+ roundTrip(t, "PageResult", samplePageResult())
+ roundTrip(t, "AuditInput", sampleAuditInput())
+ roundTrip(t, "AuditOptions", sampleAuditOptions())
+ roundTrip(t, "AuditReport", sampleAuditReport())
+}
+
+func TestNewAuditReportSchemaVersion(t *testing.T) {
+ r := NewAuditReport()
+ if r.SchemaVersion != SchemaVersion {
+ t.Fatalf("SchemaVersion = %q, want %q", r.SchemaVersion, SchemaVersion)
+ }
+ data, err := json.Marshal(r)
+ if err != nil {
+ t.Fatalf("marshal: %v", err)
+ }
+ var raw map[string]any
+ if err := json.Unmarshal(data, &raw); err != nil {
+ t.Fatalf("unmarshal: %v", err)
+ }
+ if got := raw["schemaVersion"]; got != SchemaVersion {
+ t.Fatalf("schemaVersion JSON field = %v, want %q", got, SchemaVersion)
+ }
+}