Skip to content

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

docs: declare pkg/pinchtabaudit pre-1.0 with no compatibility promise, and pin its exported surface so a source-breaking change announces itself (PIN-161)

Luigi Agostia130e94ec4a0
diff --git a/docs/audit.md b/docs/audit.md
index fbf40973..d64e19eb 100644
--- a/docs/audit.md
+++ b/docs/audit.md
@@ -175,6 +175,11 @@ report, err := client.EnrichWithBrowser(ctx,
pinchtabaudit.AuditInput{SitemapURL: "https://example.com/sitemap.xml"}, nil)
```
+The module is pre-1.0. The exported Go types in `pkg/pinchtabaudit` may change name,
+shape or JSON tag in any release without notice, and no deprecation window is offered.
+Pin a module version if that matters to you. The HTTP API below is the stable contract:
+build against it if you need one.
+
## HTTP API
The CLI is a thin client over two endpoints:
diff --git a/pkg/pinchtabaudit/public_surface_test.go b/pkg/pinchtabaudit/public_surface_test.go
new file mode 100644
index 00000000..603c481e
--- /dev/null
+++ b/pkg/pinchtabaudit/public_surface_test.go
@@ -0,0 +1,216 @@
+package pinchtabaudit
+
+import (
+ "bytes"
+ "flag"
+ "fmt"
+ "go/ast"
+ "go/parser"
+ "go/printer"
+ "go/token"
+ "os"
+ "path/filepath"
+ "sort"
+ "strings"
+ "testing"
+)
+
+var updateSurface = flag.Bool("update", false, "rewrite the pinned public surface")
+
+const surfacePath = "testdata/public_surface.txt"
+
+// This package is the module's only public Go surface, so a change to an exported name,
+// field type or JSON tag is source-breaking for an external importer. The module is pre-1.0
+// and docs/audit.md says such changes may happen without notice — so the point of this pin is
+// not to prevent them. It is to make one ANNOUNCE ITSELF in the diff: the retype that
+// prompted it broke no in-repo build and was not obviously a public-surface change to anyone
+// reviewing it.
+//
+// It follows the acknowledge-on-change shape of the audit schema-version pin rather than
+// inventing a second convention: a committed expectation that fails the moment the surface
+// moves, updated deliberately in the same commit. It differs in HOW the expectation is
+// stored, and that is the reason to prefer a file: a schema version is one token that fits in
+// a literal, while this surface is every exported declaration in the package, and a reviewer
+// needs to read WHICH line moved. A hash would fail just as loudly and say nothing.
+//
+// Everything is derived from the package source, so a newly added exported type is covered
+// without anyone extending a list.
+func TestPublicSurfaceIsPinned(t *testing.T) {
+ got := renderPublicSurface(t)
+
+ if *updateSurface {
+ if err := os.MkdirAll(filepath.Dir(surfacePath), 0o755); err != nil {
+ t.Fatal(err)
+ }
+ if err := os.WriteFile(surfacePath, got, 0o644); err != nil {
+ t.Fatal(err)
+ }
+ }
+
+ want, err := os.ReadFile(surfacePath)
+ if err != nil {
+ t.Fatalf("read the pinned surface: %v\nRun `go test ./pkg/pinchtabaudit -update` and review the diff.", err)
+ }
+ if !bytes.Equal(got, want) {
+ t.Errorf("the exported surface of this package no longer matches %s.\n"+
+ "This package is the module's only public Go surface, so this diff is source-breaking for an external importer.\n"+
+ "If the change is intended: run `go test ./pkg/pinchtabaudit -update`, read the diff, and commit it alongside the change so the break is visible in review.\n"+
+ "If a field mirrors an internal type, internal/audit/types_test.go pins that pairing separately and may need the same edit.\n\n%s",
+ surfacePath, firstDifference(string(want), string(got)))
+ }
+}
+
+// A rename that keeps the same shape is the change most likely to slip through review, so it
+// is the control this pin is proved with: the guard must red on the NAME alone.
+func TestPublicSurfaceRenderIncludesNamesTypesAndTags(t *testing.T) {
+ rendered := string(renderPublicSurface(t))
+
+ for _, want := range []string{
+ "type AuditReport struct",
+ "SchemaVersion string `json:\"schemaVersion\"`",
+ "Input AuditReportInput `json:\"input\"`",
+ "func (*Client) EnrichPage",
+ } {
+ if !strings.Contains(rendered, want) {
+ t.Errorf("the rendered surface is missing %q, so a change to it could not red this pin:\n%s", want, rendered)
+ }
+ }
+ if strings.Contains(rendered, "func newRequest") || strings.Contains(rendered, "unexported") {
+ t.Error("the rendered surface carries unexported declarations, which are not part of the public contract")
+ }
+}
+
+func renderPublicSurface(t *testing.T) []byte {
+ t.Helper()
+
+ paths, err := filepath.Glob("*.go")
+ if err != nil {
+ t.Fatalf("enumerate the package: %v", err)
+ }
+
+ fset := token.NewFileSet()
+ var lines []string
+ files := 0
+ for _, path := range paths {
+ if strings.HasSuffix(path, "_test.go") {
+ continue
+ }
+ file, err := parser.ParseFile(fset, path, nil, 0)
+ if err != nil {
+ t.Fatalf("parse %s: %v", path, err)
+ }
+ if file.Name.Name != "pinchtabaudit" {
+ t.Fatalf("%s declares package %s, so this pin is scanning the wrong source", path, file.Name.Name)
+ }
+ files++
+ for _, decl := range file.Decls {
+ lines = append(lines, exportedDeclLines(fset, decl)...)
+ }
+ }
+ if files < 2 {
+ t.Fatalf("parsed %d non-test files; the package has more, so this pin has stopped seeing most of its source", files)
+ }
+ if len(lines) == 0 {
+ t.Fatal("no exported declarations were found; this pin would pass vacuously")
+ }
+ sort.Strings(lines)
+
+ return []byte(strings.Join(lines, "\n") + "\n")
+}
+
+func exportedDeclLines(fset *token.FileSet, decl ast.Decl) []string {
+ switch d := decl.(type) {
+ case *ast.FuncDecl:
+ if !d.Name.IsExported() {
+ return nil
+ }
+ receiver := ""
+ if d.Recv != nil {
+ if len(d.Recv.List) == 0 || !exportedReceiver(d.Recv.List[0].Type) {
+ return nil
+ }
+ receiver = "(" + typeString(fset, d.Recv.List[0].Type) + ") "
+ }
+ return []string{fmt.Sprintf("func %s%s%s", receiver, d.Name.Name, typeString(fset, d.Type)[len("func"):])}
+ case *ast.GenDecl:
+ var lines []string
+ for _, spec := range d.Specs {
+ switch s := spec.(type) {
+ case *ast.TypeSpec:
+ if !s.Name.IsExported() {
+ continue
+ }
+ lines = append(lines, typeSpecLines(fset, s)...)
+ case *ast.ValueSpec:
+ for _, name := range s.Names {
+ if name.IsExported() {
+ lines = append(lines, fmt.Sprintf("%s %s", d.Tok, name.Name))
+ }
+ }
+ }
+ }
+ return lines
+ }
+ return nil
+}
+
+func typeSpecLines(fset *token.FileSet, spec *ast.TypeSpec) []string {
+ structType, ok := spec.Type.(*ast.StructType)
+ if !ok {
+ return []string{fmt.Sprintf("type %s %s", spec.Name.Name, typeString(fset, spec.Type))}
+ }
+
+ lines := []string{fmt.Sprintf("type %s struct", spec.Name.Name)}
+ for _, field := range structType.Fields.List {
+ tag := ""
+ if field.Tag != nil {
+ tag = " " + field.Tag.Value
+ }
+ if len(field.Names) == 0 {
+ lines = append(lines, fmt.Sprintf("type %s struct: %s%s", spec.Name.Name, typeString(fset, field.Type), tag))
+ continue
+ }
+ for _, name := range field.Names {
+ if !name.IsExported() {
+ continue
+ }
+ lines = append(lines, fmt.Sprintf("type %s struct: %s %s%s", spec.Name.Name, name.Name, typeString(fset, field.Type), tag))
+ }
+ }
+ return lines
+}
+
+func exportedReceiver(expr ast.Expr) bool {
+ if star, ok := expr.(*ast.StarExpr); ok {
+ expr = star.X
+ }
+ ident, ok := expr.(*ast.Ident)
+ return ok && ident.IsExported()
+}
+
+func typeString(fset *token.FileSet, expr ast.Expr) string {
+ var buf bytes.Buffer
+ if err := printer.Fprint(&buf, fset, expr); err != nil {
+ return "<unprintable>"
+ }
+ return strings.Join(strings.Fields(buf.String()), " ")
+}
+
+// A whole-surface diff buries the one line that moved, which is what a reviewer needs.
+func firstDifference(want, got string) string {
+ wantLines := strings.Split(want, "\n")
+ gotLines := strings.Split(got, "\n")
+ for i := 0; i < len(wantLines) || i < len(gotLines); i++ {
+ w, g := "", ""
+ if i < len(wantLines) {
+ w = wantLines[i]
+ }
+ if i < len(gotLines) {
+ g = gotLines[i]
+ }
+ if w != g {
+ return fmt.Sprintf("first difference at line %d:\n pinned %q\n current %q", i+1, w, g)
+ }
+ }
+ return "the files differ only in trailing bytes"
+}
diff --git a/pkg/pinchtabaudit/testdata/public_surface.txt b/pkg/pinchtabaudit/testdata/public_surface.txt
new file mode 100644
index 00000000..10b525ef
--- /dev/null
+++ b/pkg/pinchtabaudit/testdata/public_surface.txt
@@ -0,0 +1,134 @@
+const DefaultTimeout
+func (*Client) EnrichPage(ctx context.Context, url string, opts *PageOptions) (*PageAudit, error)
+func (*Client) EnrichWithBrowser(ctx context.Context, input AuditInput, opts *RunOptions) (*AuditReport, error)
+func Bool(v bool) *bool
+func New(baseURL, token string) *Client
+type A11yFinding struct
+type A11yFinding struct: Count int `json:"count"`
+type A11yFinding struct: Rule string `json:"rule"`
+type A11yFinding struct: Samples []string `json:"samples"`
+type A11yFinding struct: Severity string `json:"severity"`
+type AuditInput struct
+type AuditInput struct: SeaportalResults []byte `json:"seaportalResults,omitempty"`
+type AuditInput struct: SitemapURL string `json:"sitemapUrl,omitempty"`
+type AuditInput struct: URLs []string `json:"urls,omitempty"`
+type AuditOptions struct
+type AuditOptions struct: Concurrency int `json:"concurrency,omitempty"`
+type AuditOptions struct: NetworkMonitor bool `json:"networkMonitor,omitempty"`
+type AuditOptions struct: OutputDir string `json:"outputDir,omitempty"`
+type AuditOptions struct: SampleSize int `json:"sampleSize,omitempty"`
+type AuditOptions struct: Screenshot bool `json:"screenshot,omitempty"`
+type AuditOptions struct: VisualDiff bool `json:"visualDiff,omitempty"`
+type AuditReport struct
+type AuditReport struct: GeneratedAt time.Time `json:"generatedAt"`
+type AuditReport struct: Input AuditReportInput `json:"input"`
+type AuditReport struct: Options AuditOptions `json:"options"`
+type AuditReport struct: Pages []PageResult `json:"pages"`
+type AuditReport struct: Recommendations []string `json:"recommendations,omitempty"`
+type AuditReport struct: SchemaVersion string `json:"schemaVersion"`
+type AuditReport struct: SecurityFindings []SecurityFinding `json:"securityFindings,omitempty"`
+type AuditReport struct: SummaryScore int `json:"summaryScore"`
+type AuditReportInput struct
+type AuditReportInput struct: SeaportalFile string `json:"seaportalFile,omitempty"`
+type AuditReportInput struct: SeaportalFormat string `json:"seaportalFormat,omitempty"`
+type AuditReportInput struct: SitemapURL string `json:"sitemapUrl,omitempty"`
+type AuditReportInput struct: URLs []string `json:"urls,omitempty"`
+type BrokenAsset struct
+type BrokenAsset struct: Error string `json:"error,omitempty"`
+type BrokenAsset struct: ResourceType string `json:"resourceType,omitempty"`
+type BrokenAsset struct: Status int `json:"status,omitempty"`
+type BrokenAsset struct: URL string `json:"url"`
+type BrowserPageData struct
+type BrowserPageData struct: AccessibilityScore int `json:"accessibilityScore,omitempty"`
+type BrowserPageData struct: BrokenAssets []BrokenAsset `json:"brokenAssets,omitempty"`
+type BrowserPageData struct: ConsoleLogs []ConsoleLogEntry `json:"consoleLogs,omitempty"`
+type BrowserPageData struct: FullPageScreenshot bool `json:"fullPageScreenshot,omitempty"`
+type BrowserPageData struct: InteractiveElements []InteractiveElement `json:"interactiveElements,omitempty"`
+type BrowserPageData struct: JSErrors []JSError `json:"jsErrors,omitempty"`
+type BrowserPageData struct: NetworkRequests []NetworkRequest `json:"networkRequests,omitempty"`
+type BrowserPageData struct: ScreenshotPath string `json:"screenshotPath,omitempty"`
+type BrowserPageData struct: TimingMetrics TimingMetrics `json:"timingMetrics"`
+type BrowserPageData struct: VisualDiff *VisualDiffResult `json:"visualDiff,omitempty"`
+type Client struct
+type Client struct: HTTPClient *http.Client
+type ConsoleLogEntry struct
+type ConsoleLogEntry struct: Level string `json:"level"`
+type ConsoleLogEntry struct: Message string `json:"message"`
+type ConsoleLogEntry struct: Source string `json:"source,omitempty"`
+type ConsoleLogEntry struct: Timestamp time.Time `json:"timestamp"`
+type InteractiveElement struct
+type InteractiveElement struct: Disabled bool `json:"disabled,omitempty"`
+type InteractiveElement struct: Label string `json:"label,omitempty"`
+type InteractiveElement struct: Name string `json:"name,omitempty"`
+type InteractiveElement struct: Ref string `json:"ref"`
+type InteractiveElement struct: Role string `json:"role"`
+type InteractiveElement struct: Tag string `json:"tag,omitempty"`
+type JSError struct
+type JSError struct: Column int64 `json:"column,omitempty"`
+type JSError struct: Line int64 `json:"line,omitempty"`
+type JSError struct: Message string `json:"message"`
+type JSError struct: Stack string `json:"stack,omitempty"`
+type JSError struct: Timestamp time.Time `json:"timestamp"`
+type JSError struct: Type string `json:"type,omitempty"`
+type JSError struct: URL string `json:"url,omitempty"`
+type NetworkRequest struct
+type NetworkRequest struct: Duration float64 `json:"duration,omitempty"`
+type NetworkRequest struct: Error string `json:"error,omitempty"`
+type NetworkRequest struct: Failed bool `json:"failed,omitempty"`
+type NetworkRequest struct: Method string `json:"method"`
+type NetworkRequest struct: MimeType string `json:"mimeType,omitempty"`
+type NetworkRequest struct: ResourceType string `json:"resourceType,omitempty"`
+type NetworkRequest struct: Size int64 `json:"size,omitempty"`
+type NetworkRequest struct: StartTime time.Time `json:"startTime"`
+type NetworkRequest struct: Status int `json:"status,omitempty"`
+type NetworkRequest struct: StatusText string `json:"statusText,omitempty"`
+type NetworkRequest struct: URL string `json:"url"`
+type PageAudit struct
+type PageAudit struct: A11yFindings []A11yFinding `json:"a11yFindings,omitempty"`
+type PageAudit struct: BrowserPageData
+type PageAudit struct: Error string `json:"error,omitempty"`
+type PageAudit struct: Screenshot string `json:"screenshot,omitempty"`
+type PageAudit struct: SecurityFindings []SecurityFinding `json:"securityFindings,omitempty"`
+type PageAudit struct: Title string `json:"title,omitempty"`
+type PageAudit struct: URL string `json:"url"`
+type PageOptions struct
+type PageOptions struct: A11y *bool `json:"a11y,omitempty"`
+type PageOptions struct: Console *bool `json:"console,omitempty"`
+type PageOptions struct: Elements *bool `json:"elements,omitempty"`
+type PageOptions struct: Network *bool `json:"network,omitempty"`
+type PageOptions struct: Screenshot *bool `json:"screenshot,omitempty"`
+type PageOptions struct: Security *bool `json:"security,omitempty"`
+type PageOptions struct: Timing *bool `json:"timing,omitempty"`
+type PageResult struct
+type PageResult struct: Browser BrowserPageData `json:"browser"`
+type PageResult struct: Error string `json:"error,omitempty"`
+type PageResult struct: Screenshot string `json:"screenshot,omitempty"`
+type PageResult struct: Seaportal map[string]any `json:"seaportal,omitempty"`
+type PageResult struct: SecurityFindings []SecurityFinding `json:"securityFindings,omitempty"`
+type PageResult struct: StatusCode int `json:"statusCode,omitempty"`
+type PageResult struct: Title string `json:"title,omitempty"`
+type PageResult struct: URL string `json:"url"`
+type RunOptions struct
+type RunOptions struct: Concurrency int
+type RunOptions struct: EnrichAll bool
+type RunOptions struct: Page *PageOptions
+type RunOptions struct: SampleSize int
+type SecurityFinding struct
+type SecurityFinding struct: Detail string `json:"detail"`
+type SecurityFinding struct: RuleID string `json:"ruleId"`
+type SecurityFinding struct: Severity string `json:"severity"`
+type SecurityFinding struct: URL string `json:"url,omitempty"`
+type TimingMetrics struct
+type TimingMetrics struct: CumulativeLayoutShift float64 `json:"cls,omitempty"`
+type TimingMetrics struct: DOMContentLoaded float64 `json:"domContentLoadedMs,omitempty"`
+type TimingMetrics struct: FirstContentfulPaint float64 `json:"fcpMs,omitempty"`
+type TimingMetrics struct: LargestContentfulPaint float64 `json:"lcpMs,omitempty"`
+type TimingMetrics struct: Load float64 `json:"loadMs,omitempty"`
+type TimingMetrics struct: TimeToFirstByte float64 `json:"ttfbMs,omitempty"`
+type VisualDiffResult struct
+type VisualDiffResult struct: BaselinePath string `json:"baselinePath"`
+type VisualDiffResult struct: Changed bool `json:"changed"`
+type VisualDiffResult struct: CurrentPath string `json:"currentPath"`
+type VisualDiffResult struct: DiffPath string `json:"diffPath,omitempty"`
+type VisualDiffResult struct: DiffPixels int `json:"diffPixels"`
+type VisualDiffResult struct: DiffRatio float64 `json:"diffRatio"`