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.mdindex 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 APIThe CLI is a thin client over two endpoints:diff --git a/pkg/pinchtabaudit/public_surface_test.go b/pkg/pinchtabaudit/public_surface_test.gonew file mode 100644index 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.txtnew file mode 100644index 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"`