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.gonew file mode 100644index 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.gonew file mode 100644index 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)+ }+}