Skip to content

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

feat: add deterministic template-group sampling to audit runs

Luigi Agostif0704b27ffb2
diff --git a/cmd/pinchtab/cmd_cli_register.go b/cmd/pinchtab/cmd_cli_register.go
index c2bff8ef..a519bdfc 100644
--- a/cmd/pinchtab/cmd_cli_register.go
+++ b/cmd/pinchtab/cmd_cli_register.go
@@ -356,7 +356,7 @@ func configureBrowserFlags() {
errorsCmd.Flags().String("limit", "", "Maximum entries to return")
auditCmd.Flags().Bool("sitemap", false, "Treat the URL as a sitemap.xml and audit the discovered pages")
- auditCmd.Flags().Int("sample-size", 0, "Cap the number of audited pages (0 = no cap)")
+ auditCmd.Flags().Int("sample-size", 0, "Pages audited per template group, e.g. /products/p1..pN (0 = all pages; deterministic picks)")
auditCmd.Flags().Bool("screenshot", true, "Capture page screenshots")
auditCmd.Flags().Bool("network-monitor", true, "Collect network requests and broken assets")
auditCmd.Flags().String("output-dir", "", "Write report.json and screenshots/ to this directory")
diff --git a/internal/audit/run.go b/internal/audit/run.go
index 2029a4af..ea8cb971 100644
--- a/internal/audit/run.go
+++ b/internal/audit/run.go
@@ -18,8 +18,8 @@ const (
// RunOptions configures a multi-page audit run.
type RunOptions struct {
- // SampleSize caps the number of audited pages, 0 = no cap. (Per-group
- // sampling lands with page grouping; this is a plain truncation.)
+ // SampleSize caps how many pages each template group contributes
+ // (see SamplePages), 0 = no cap.
SampleSize int
// Concurrency is the number of pages audited in parallel, clamped to
// [1, MaxConcurrency].
@@ -102,10 +102,7 @@ func RunAudit(input AuditInput, opts RunOptions, discover SitemapFetcher, auditP
urls = discovered
}
- plan := PlanURLs(urls)
- if opts.SampleSize > 0 && len(plan) > opts.SampleSize {
- plan = plan[:opts.SampleSize]
- }
+ plan := SamplePages(PlanURLs(urls), opts.SampleSize, nil)
if len(plan) == 0 {
return AuditReport{}, errors.New("no URLs to audit")
}
diff --git a/internal/audit/run_test.go b/internal/audit/run_test.go
index a346a646..9d0ca463 100644
--- a/internal/audit/run_test.go
+++ b/internal/audit/run_test.go
@@ -176,7 +176,7 @@ func TestRunAuditSitemapMode(t *testing.T) {
func TestRunAuditSampleSizeAndEmpty(t *testing.T) {
auditor, _, _ := fakeAuditor()
report, err := RunAudit(
- AuditInput{URLs: []string{"http://x/1", "http://x/2", "http://x/3"}},
+ AuditInput{URLs: []string{"http://x/p1.html", "http://x/p2.html", "http://x/p3.html"}},
RunOptions{SampleSize: 2},
nil, auditor,
)
@@ -184,7 +184,7 @@ func TestRunAuditSampleSizeAndEmpty(t *testing.T) {
t.Fatalf("RunAudit: %v", err)
}
if len(report.Pages) != 2 {
- t.Errorf("pages = %d, want 2 (sample size)", len(report.Pages))
+ t.Errorf("pages = %d, want 2 (template group sampled)", len(report.Pages))
}
if _, err := RunAudit(AuditInput{}, RunOptions{}, nil, auditor); err == nil {
diff --git a/internal/audit/sample.go b/internal/audit/sample.go
new file mode 100644
index 00000000..b8afcf58
--- /dev/null
+++ b/internal/audit/sample.go
@@ -0,0 +1,117 @@
+package audit
+
+import (
+ "net/url"
+ "regexp"
+ "sort"
+)
+
+// PageGroup is a set of URLs sharing a path template. Groups with a single
+// member are ordinary pages; only groups of two or more are treated as
+// template groups by SamplePages.
+type PageGroup struct {
+ // Template is the digit-normalized URL template shared by the members.
+ Template string
+ // URLs are the member URLs in first-occurrence order.
+ URLs []string
+}
+
+var digitRuns = regexp.MustCompile(`\d+`)
+
+// templateKey normalizes a URL to its path template: scheme, host, and path
+// with digit runs collapsed to '#'. Query and fragment are ignored, so
+// /products/p1.html and /products/p2.html share one template.
+func templateKey(raw string) string {
+ u, err := url.Parse(raw)
+ if err != nil || u.Host == "" {
+ return digitRuns.ReplaceAllString(raw, "#")
+ }
+ return u.Scheme + "://" + u.Host + digitRuns.ReplaceAllString(u.Path, "#")
+}
+
+// GroupURLs groups URLs by path template, deterministically: groups appear
+// in first-occurrence order and members keep input order.
+func GroupURLs(urls []string) []PageGroup {
+ index := map[string]int{}
+ var groups []PageGroup
+ for _, u := range urls {
+ key := templateKey(u)
+ i, ok := index[key]
+ if !ok {
+ i = len(groups)
+ index[key] = i
+ groups = append(groups, PageGroup{Template: key})
+ }
+ groups[i].URLs = append(groups[i].URLs, u)
+ }
+ return groups
+}
+
+// SamplePages reduces urls to a bounded, prioritized audit plan:
+//
+// - the entry URL (urls[0]) is always first
+// - ungrouped pages (unique templates) are all kept, in input order
+// - each template group (>= 2 members) contributes at most sampleSize
+// pages, picked in lexical order for stability; an entry URL belonging
+// to a group counts toward its quota
+// - template-group pages come after ungrouped pages (homepage and nav
+// pages ahead of deep template pages)
+//
+// sampleSize <= 0 keeps every page (prioritized ordering still applies).
+// groups may be supplied externally (e.g. from a SeaPortal SiteReport); nil
+// computes them locally from URL structure. Fully deterministic: identical
+// inputs always yield the identical plan.
+func SamplePages(urls []string, sampleSize int, groups []PageGroup) []string {
+ if len(urls) == 0 {
+ return nil
+ }
+ if groups == nil {
+ groups = GroupURLs(urls)
+ }
+
+ groupOf := map[string]string{}
+ for _, g := range groups {
+ if len(g.URLs) < 2 {
+ continue
+ }
+ for _, u := range g.URLs {
+ groupOf[u] = g.Template
+ }
+ }
+
+ entry := urls[0]
+ plan := []string{entry}
+ seen := map[string]bool{entry: true}
+ picked := map[string]int{}
+ if t, ok := groupOf[entry]; ok {
+ picked[t] = 1
+ }
+
+ for _, u := range urls {
+ if seen[u] || groupOf[u] != "" {
+ continue
+ }
+ seen[u] = true
+ plan = append(plan, u)
+ }
+
+ for _, g := range groups {
+ if len(g.URLs) < 2 {
+ continue
+ }
+ members := append([]string(nil), g.URLs...)
+ sort.Strings(members)
+ for _, u := range members {
+ if sampleSize > 0 && picked[g.Template] >= sampleSize {
+ break
+ }
+ if seen[u] {
+ continue
+ }
+ seen[u] = true
+ plan = append(plan, u)
+ picked[g.Template]++
+ }
+ }
+ return plan
+}
diff --git a/internal/audit/sample_test.go b/internal/audit/sample_test.go
new file mode 100644
index 00000000..2dfcd445
--- /dev/null
+++ b/internal/audit/sample_test.go
@@ -0,0 +1,133 @@
+package audit
+
+import (
+ "reflect"
+ "testing"
+)
+
+var fixtureSiteURLs = []string{
+ "http://fixtures/audit-site/index.html",
+ "http://fixtures/audit-site/broken-assets.html",
+ "http://fixtures/audit-site/console-errors.html",
+ "http://fixtures/audit-site/a11y-issues.html",
+ "http://fixtures/audit-site/clean.html",
+ "http://fixtures/audit-site/forms.html",
+ "http://fixtures/audit-site/cookie-echo.html",
+ "http://fixtures/audit-site/products/p1.html",
+ "http://fixtures/audit-site/products/p2.html",
+ "http://fixtures/audit-site/products/p3.html",
+ "http://fixtures/audit-site/products/p4.html",
+ "http://fixtures/audit-site/products/p5.html",
+}
+
+func TestGroupURLsCollapsesProductTemplates(t *testing.T) {
+ groups := GroupURLs(fixtureSiteURLs)
+
+ var products *PageGroup
+ multi := 0
+ for i := range groups {
+ if len(groups[i].URLs) >= 2 {
+ multi++
+ products = &groups[i]
+ }
+ }
+ if multi != 1 {
+ t.Fatalf("template groups = %d, want 1 (products only)", multi)
+ }
+ if len(products.URLs) != 5 {
+ t.Errorf("products group size = %d, want 5", len(products.URLs))
+ }
+ if products.Template != "http://fixtures/audit-site/products/p#.html" {
+ t.Errorf("products template = %q", products.Template)
+ }
+}
+
+func TestGroupURLsKeepsDistinctPagesApart(t *testing.T) {
+ groups := GroupURLs([]string{
+ "http://x/index.html",
+ "http://x/clean.html",
+ "http://x/forms.html",
+ })
+ if len(groups) != 3 {
+ t.Errorf("groups = %d, want 3 distinct (letters differ, not digits)", len(groups))
+ }
+}
+
+func TestSamplePagesDeterministicPicks(t *testing.T) {
+ first := SamplePages(fixtureSiteURLs, 2, nil)
+ for range 10 {
+ if again := SamplePages(fixtureSiteURLs, 2, nil); !reflect.DeepEqual(first, again) {
+ t.Fatalf("sampling not deterministic:\n%v\n%v", first, again)
+ }
+ }
+
+ products := 0
+ for _, u := range first {
+ if u == "http://fixtures/audit-site/products/p1.html" || u == "http://fixtures/audit-site/products/p2.html" {
+ products++
+ }
+ }
+ if products != 2 {
+ t.Errorf("expected the 2 lexically-first product pages, got plan %v", first)
+ }
+ if len(first) != 9 {
+ t.Errorf("plan size = %d, want 9 (7 non-group + 2 sampled)", len(first))
+ }
+}
+
+func TestSamplePagesHomepageFirst(t *testing.T) {
+ plan := SamplePages(fixtureSiteURLs, 2, nil)
+ if plan[0] != "http://fixtures/audit-site/index.html" {
+ t.Errorf("plan[0] = %q, want homepage", plan[0])
+ }
+
+ shuffled := []string{
+ "http://fixtures/audit-site/products/p3.html",
+ "http://fixtures/audit-site/index.html",
+ "http://fixtures/audit-site/products/p1.html",
+ }
+ plan = SamplePages(shuffled, 1, nil)
+ if plan[0] != "http://fixtures/audit-site/products/p3.html" {
+ t.Errorf("entry URL must stay first even when grouped, got %v", plan)
+ }
+ if len(plan) != 2 {
+ t.Errorf("plan = %v, want entry + index (entry fills the group quota)", plan)
+ }
+}
+
+func TestSamplePagesTemplatePagesLast(t *testing.T) {
+ plan := SamplePages(fixtureSiteURLs, 2, nil)
+ sawProduct := false
+ for _, u := range plan[1:] {
+ isProduct := templateKey(u) == "http://fixtures/audit-site/products/p#.html"
+ if sawProduct && !isProduct {
+ t.Errorf("ungrouped page %q after template pages: %v", u, plan)
+ }
+ if isProduct {
+ sawProduct = true
+ }
+ }
+}
+
+func TestSamplePagesNoCapKeepsAll(t *testing.T) {
+ plan := SamplePages(fixtureSiteURLs, 0, nil)
+ if len(plan) != len(fixtureSiteURLs) {
+ t.Errorf("plan size = %d, want %d (no cap)", len(plan), len(fixtureSiteURLs))
+ }
+}
+
+func TestSamplePagesExternalGroups(t *testing.T) {
+ urls := []string{"http://x/home", "http://x/shoes", "http://x/hats"}
+ external := []PageGroup{{Template: "catalog", URLs: []string{"http://x/shoes", "http://x/hats"}}}
+ plan := SamplePages(urls, 1, external)
+ want := []string{"http://x/home", "http://x/hats"}
+ if !reflect.DeepEqual(plan, want) {
+ t.Errorf("plan = %v, want %v (external group sampled)", plan, want)
+ }
+}
+
+func TestSamplePagesEmpty(t *testing.T) {
+ if plan := SamplePages(nil, 2, nil); plan != nil {
+ t.Errorf("SamplePages(nil) = %v", plan)
+ }
+}
diff --git a/tests/e2e/scenarios/api/audit-sampling-extended.sh b/tests/e2e/scenarios/api/audit-sampling-extended.sh
new file mode 100755
index 00000000..faf93484
--- /dev/null
+++ b/tests/e2e/scenarios/api/audit-sampling-extended.sh
@@ -0,0 +1,51 @@
+#!/bin/bash
+# audit-sampling-extended.sh — POST /audit template-group sampling.
+
+GROUP_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "${GROUP_DIR}/../../helpers/api.sh"
+
+SAMPLING_BODY="{\"sitemapUrl\":\"${FIXTURES_URL}/audit-site/sitemap.xml\",\"sampleSize\":2,\"options\":{\"screenshot\":false}}"
+
+# ─────────────────────────────────────────────────────────────────
+start_test "sampleSize=2 keeps all non-group pages plus 2 products"
+
+pt_post /audit -d "$SAMPLING_BODY"
+assert_ok "sampled sitemap audit"
+
+assert_json_length "$RESULT" '.pages' 9 "9 pages (7 non-group + 2 sampled products)"
+
+PRODUCT_COUNT=$(echo "$RESULT" | jq '[.pages[].url | select(contains("products/"))] | length')
+if [ "$PRODUCT_COUNT" -eq 2 ]; then
+ pass_assert "exactly 2 products/* pages"
+else
+ fail_assert "exactly 2 products/* pages (got: $PRODUCT_COUNT)"
+fi
+
+for page in index.html broken-assets.html console-errors.html a11y-issues.html clean.html forms.html cookie-echo.html; do
+ if echo "$RESULT" | jq -e --arg page "$page" '.pages[] | select(.url | endswith($page))' >/dev/null 2>&1; then
+ pass_assert "non-group page $page present"
+ else
+ fail_assert "non-group page $page present"
+ fi
+done
+
+assert_json_contains "$RESULT" '.pages[0].url' "index.html" "homepage first in page order"
+
+end_test
+
+# ─────────────────────────────────────────────────────────────────
+start_test "sampling is reproducible across runs"
+
+FIRST_SET=$(echo "$RESULT" | jq -S '[.pages[].url] | sort')
+
+pt_post /audit -d "$SAMPLING_BODY"
+assert_ok "second sampled audit"
+SECOND_SET=$(echo "$RESULT" | jq -S '[.pages[].url] | sort')
+
+if [ "$FIRST_SET" = "$SECOND_SET" ]; then
+ pass_assert "identical page URL set across runs"
+else
+ fail_assert "URL sets differ: $FIRST_SET vs $SECOND_SET"
+fi
+
+end_test