High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
refactor: settle one convention for the source-scanning census guards before a fourth is written (PIN-105)
Luigi Agosti82018519cb3b
diff --git a/cmd/pinchtab/cmd_server_test.go b/cmd/pinchtab/cmd_server_test.goindex a24b6e65..131fe481 100644--- a/cmd/pinchtab/cmd_server_test.go+++ b/cmd/pinchtab/cmd_server_test.go@@ -16,6 +16,7 @@ import ("github.com/pinchtab/pinchtab/internal/config""github.com/pinchtab/pinchtab/internal/safelog"+ "github.com/pinchtab/pinchtab/internal/srccensus")func TestApplyServerAddressFlagsPrecedence(t *testing.T) {@@ -314,91 +315,82 @@ func TestDaemonAndAutoStartLaunchWithoutLogLevelFlags(t *testing.T) {// on the helper cannot see a Run body that settles the level itself, and there are two// ways to do that: assigning cfg.LogLevel (which bypasses the precedence) or calling// safelog.SetLevel directly (which overrides the resolved threshold for the whole-// process). Both are banned everywhere in the package except the file that declares-// the resolver, and the census is over a glob so a new cmd_*.go is covered on arrival-// rather than when someone remembers to list it.+// process). Both are banned everywhere in the package except inside the+// resolveLogLevel/applyLogLevel pair that owns the decision.//-// KNOWN LIMIT, recorded so it is not rediscovered as new: the exemption is-// FILE-scoped. cmd_server.go carries safelog.SetLevel three times inside-// applyLogLevel, so a stray call added elsewhere in that same file is still permitted-// — the coarse-scope problem this guard narrows, surviving in the owning file. The-// honest fix is asserting the patterns occur only within the-// resolveLogLevel/applyLogLevel pair, which needs real function-body extraction; a-// hand-rolled brace matcher is the anti-pattern the AST-based shared guard is being-// introduced to remove, so this waits for it rather than growing one here.+// The scope is derived twice over, which is the property srccensus exists to make+// automatic: the package's non-test sources are enumerated rather than listed, so a new+// cmd_*.go is covered on arrival, and the exemption is the OWNING FUNCTIONS rather than+// the owning file. That closes the limit this guard used to record: cmd_server.go holds+// three legitimate safelog.SetLevel calls inside applyLogLevel, and a stray fourth+// anywhere else in that same file used to pass.func TestTheCommandPackageSettlesTheLogLevelInOnePlace(t *testing.T) {- files := commandSourceFiles(t)- if len(files) < 2 {- t.Fatalf("scanned %d command files; the census matched almost nothing and would pass vacuously", len(files))- }+ pkg := srccensus.Load(t, ".", 2)- sources := make(map[string]string, len(files))- for _, path := range files {- body, err := os.ReadFile(path) // #nosec G304 -- files listed from this package's own directory.- if err != nil {- t.Fatal(err)- }- sources[filepath.Base(path)] = string(body)- }-- // The declaring file is found rather than hardcoded, so moving the owner needs no- // test edit — the same staleness this census replaced.- const declaration = "func resolveLogLevel("- declarations := 0- owner := ""- for name, src := range sources {- if n := strings.Count(src, declaration); n > 0 {- declarations += n- owner = name+ owners := make([]srccensus.Func, 0, 2)+ for _, name := range []string{"resolveLogLevel", "applyLogLevel"} {+ fn, ok := pkg.Func(name)+ if !ok {+ t.Fatalf("no %s declaration in %s; the level owner was renamed or moved out of the package — re-point this census at whatever settles the level now rather than deleting it", name, pkg.Dir())}+ owners = append(owners, fn)}- if declarations != 1 {- t.Fatalf("found %d %s declarations in the command package, want exactly 1 — a second copy means the two commands no longer share one precedence", declarations, declaration)++ insideAnOwner := func(site srccensus.Site) bool {+ for _, owner := range owners {+ if pkg.Contains(owner, site) {+ return true+ }+ }+ return false}- // Each pattern is banned outside the owner and required at least once inside it:- // a census that finds the pattern nowhere would pass while the rule it states has- // silently stopped applying to anything.- for _, banned := range []struct {- pattern string- why string+ for _, rule := range []struct {+ what string+ sites []srccensus.Site+ why string}{- {".LogLevel = ", "the level is settled only inside resolveLogLevel, so a command that spawns or becomes a server must pass its flag there instead"},- {"safelog.SetLevel(", "a raw level set overrides the resolved threshold for the whole process, so a command that never resolves a level must not touch it"},+ {+ // Calls fails on zero by itself, so this rule's vacuity floor is structural.+ what: "safelog.SetLevel(",+ sites: pkg.Calls(t, "safelog.SetLevel"),+ why: "a raw level set overrides the resolved threshold for the whole process, so a command that never resolves a level must not touch it",+ },+ {+ // FieldAssignments has no such floor — an assignment is not a call — so the+ // floor for this rule is the explicit check below.+ what: ".LogLevel = ",+ sites: pkg.FieldAssignments("LogLevel"),+ why: "the level is settled only inside resolveLogLevel, so a command that spawns or becomes a server must pass its flag there instead",+ },} {- found := 0- for name, src := range sources {- n := strings.Count(src, banned.pattern)- found += n- if n > 0 && name != owner {- t.Errorf("%s contains %q %d time(s); %s", name, banned.pattern, n, banned.why)+ if len(rule.sites) == 0 {+ t.Errorf("no %s anywhere in the command package; the census has nothing to guard and would pass vacuously — re-point it rather than deleting it", rule.what)+ continue+ }+ inside := 0+ for _, site := range rule.sites {+ if insideAnOwner(site) {+ inside+++ continue}+ t.Errorf("%s uses %s outside resolveLogLevel/applyLogLevel; %s", site, rule.what, rule.why)}- if found == 0 {- t.Errorf("no command file contains %q; the census has nothing to guard and would pass vacuously", banned.pattern)+ if inside == 0 {+ t.Errorf("every %s in the package sits outside the owning functions; the rule has stopped applying where it is supposed to hold", rule.what)}}- // The one assignment must sit inside the resolver, not merely inside its file.- helper := sources[owner][strings.Index(sources[owner], declaration):]- if end := strings.Index(helper, "\nfunc "); end >= 0 {- helper = helper[:end]- }- if !strings.Contains(helper, ".LogLevel = ") {- t.Error("the one cfg.LogLevel assignment is outside resolveLogLevel; the flag can bypass the precedence again")- }-// The positive half: an absence-only census would pass happily if both commands// stopped resolving the level at all, which is the defect these guards were built// for. Matched on the call rather than an argument spelling, so a legitimate// signature change does not red this for no defect.+ callers := map[string]bool{}+ for _, site := range pkg.Calls(t, "resolveLogLevel") {+ callers[site.File] = true+ }for _, caller := range []string{"cmd_server.go", "cmd_bridge.go"} {- src, ok := sources[caller]- if !ok {- t.Errorf("%s is no longer in the command package; this guard names it as a resolveLogLevel caller", caller)- continue- }- if strings.Count(src, "resolveLogLevel(") <= strings.Count(src, declaration) {+ if !callers[caller] {t.Errorf("%s no longer calls resolveLogLevel, so its --log-level and server.logLevel are silently ignored", caller)}}diff --git a/internal/srccensus/srccensus.go b/internal/srccensus/srccensus.gonew file mode 100644index 00000000..925653c6--- /dev/null+++ b/internal/srccensus/srccensus.go@@ -0,0 +1,258 @@+// Package srccensus is the shared home for this repo's source-scanning census guards.+//+// A census guard pins something ordinary unit tests structurally cannot see: that+// production CALLS the guarded helper rather than reimplementing the rule inline. A unit+// test on the helper stays green while a caller bypasses it, which is the regression shape+// every one of these guards was written after.+//+// # The five properties+//+// Four rounds of these guards have now been written by hand, and the same two mistakes+// recur. Shared here, so they cannot be forgotten:+//+// 1. SCOPE IS DERIVED, NEVER HAND-LISTED. Load enumerates a package's non-test sources+// rather than naming files, and the finders return EVERY match rather than the first.+// Every silent narrowing found in this repo came from a hand-listed scope — a pair of+// filenames, the first match per file, a literal list of the very constants whose+// addition the guard policed. The rule was right in all three; the scope covered less+// than the message claimed, and no vacuity floor can see that.+// 2. NON-VACUITY IS STRUCTURAL. Load fails when the package yields too few files, and+// Calls fails when a pattern that must exist matches nothing. A guard whose scan+// matched nothing passes for the wrong reason, so this is not left to each author.+// Where zero matches is the PASS condition, CallsAllowingNone says so out loud and the+// floor has to sit on something else.+// 3. LOCATING A DECLARATION EITHER SUCCEEDS OR REPORTS. Func returns found=false as a+// value. The hand-rolled shape it replaces sliced from strings.Index and panicked with+// a bounds error when a helper moved to a sibling file — the one refactor most likely+// to cause it, answered with the least readable failure.+// 4. EXEMPTION TABLES STAY LOCAL, with the reason at the entry and checked in BOTH+// directions: a stale exemption naming something that no longer exists must fail too.+// They are deliberately not shared — the reason belongs beside the rule it excuses.+// 5. FAILURE MESSAGES STAY LOCAL AND SPECIFIC. Naming the file, the line and the fix is+// most of a census's value, and saying what to do when the guarded shape CHANGED —+// add the new entry point, or pin the property against whatever replaced it, but do+// not delete the test — is what stops the next reader deleting it.+//+// This package deliberately holds no rule tables, no exemptions and no messages. It reads+// source with go/ast so a site carries its enclosing function and a real FileSet line; it+// does not decide what is banned.+package srccensus++import (+ "fmt"+ "go/ast"+ "go/parser"+ "go/token"+ "path/filepath"+ "strings"+ "testing"+)++// Site is one match, positioned well enough to open and attributed to the function that+// contains it — the attribution a file-scoped scan cannot make.+type Site struct {+ File string+ Line int+ Func string+ Text string++ pos token.Pos+}++func (s Site) String() string {+ return fmt.Sprintf("%s:%d (in %s): %s", s.File, s.Line, s.Func, s.Text)+}++// Package is one Go package's non-test source, parsed.+type Package struct {+ fset *token.FileSet+ files map[string]*ast.File+ dir string+}++// Load parses every non-test .go file in dir. minFiles is the vacuity floor: pass the+// number of files the guard already knows about, not 1, so a scan that silently stops+// matching most of the package fails instead of passing.+func Load(t testing.TB, dir string, minFiles int) *Package {+ t.Helper()++ paths, err := filepath.Glob(filepath.Join(dir, "*.go"))+ if err != nil {+ t.Fatalf("cannot enumerate %s, so this census would check nothing: %v", dir, err)+ }++ pkg := &Package{fset: token.NewFileSet(), files: map[string]*ast.File{}, dir: dir}+ for _, path := range paths {+ if strings.HasSuffix(path, "_test.go") {+ continue+ }+ file, err := parser.ParseFile(pkg.fset, path, nil, 0)+ if err != nil {+ t.Fatalf("cannot parse %s, so this census would skip it silently: %v", path, err)+ }+ pkg.files[filepath.Base(path)] = file+ }+ if len(pkg.files) < minFiles {+ t.Fatalf("parsed %d non-test files in %s, want at least %d; the census matched almost nothing and would pass vacuously", len(pkg.files), dir, minFiles)+ }+ return pkg+}++// Files reports the base names parsed, for a guard that needs to name one.+func (p *Package) Files() []string {+ names := make([]string, 0, len(p.files))+ for name := range p.files {+ names = append(names, name)+ }+ return names+}++// Calls returns every call to want — either a bare "Fn" or a qualified "pkg.Fn" — and+// fails when there are none. Use it for a rule that says "this must happen HERE and+// nowhere else": a pattern that matches nothing means the rule has stopped applying to+// anything and the guard is guarding air.+func (p *Package) Calls(t testing.TB, want string) []Site {+ t.Helper()++ sites := p.CallsAllowingNone(want)+ if len(sites) == 0 {+ t.Fatalf("no call to %s anywhere in %s; the census has nothing to guard and would pass vacuously — re-point it at whatever replaced the call rather than deleting it", want, p.dir)+ }+ return sites+}++// CallsAllowingNone is Calls for a rule whose PASS condition is zero matches, such as a+// ban on a call that must not appear at all. The name is the point: a guard reading zero+// as success must say so, and must put its vacuity floor somewhere else.+func (p *Package) CallsAllowingNone(want string) []Site {+ var sites []Site+ p.each(func(name string, file *ast.File) {+ ast.Inspect(file, func(node ast.Node) bool {+ call, ok := node.(*ast.CallExpr)+ if !ok || calleeName(call.Fun) != want {+ return true+ }+ sites = append(sites, p.site(name, file, call, want))+ return true+ })+ })+ return sites+}++// FieldAssignments returns every assignment whose left-hand side is a selector ending in+// field — cfg.LogLevel = x, whatever the receiver is called. Receiver-name-blind, because+// a census keyed on one spelling is scoped to that spelling.+func (p *Package) FieldAssignments(field string) []Site {+ var sites []Site+ p.each(func(name string, file *ast.File) {+ ast.Inspect(file, func(node ast.Node) bool {+ assign, ok := node.(*ast.AssignStmt)+ if !ok {+ return true+ }+ for _, lhs := range assign.Lhs {+ sel, ok := lhs.(*ast.SelectorExpr)+ if !ok || sel.Sel.Name != field {+ continue+ }+ sites = append(sites, p.site(name, file, assign, "."+field+" ="))+ }+ return true+ })+ })+ return sites+}++// Func is a declaration found in the package, carrying the span a scope check needs.+type Func struct {+ Name string+ File string+ Line int++ start token.Pos+ end token.Pos+}++// Func looks a declaration up ANYWHERE in the package and returns found=false rather than+// panicking or guessing. A guard reporting not-found should name the declaration and the+// directory it searched, so a helper that moved to a sibling file — or was renamed —+// explains itself instead of producing a slice-bounds error.+func (p *Package) Func(name string) (Func, bool) {+ var found Func+ ok := false+ p.each(func(fileName string, file *ast.File) {+ for _, decl := range file.Decls {+ fn, isFunc := decl.(*ast.FuncDecl)+ if !isFunc || fn.Name.Name != name || ok {+ continue+ }+ position := p.fset.Position(fn.Pos())+ found = Func{Name: name, File: fileName, Line: position.Line, start: fn.Pos(), end: fn.End()}+ ok = true+ }+ })+ return found, ok+}++// Dir is the directory the census read, for a not-found message that says where it looked.+func (p *Package) Dir() string { return p.dir }++// Contains reports whether site lies inside this declaration's body. This is the check a+// file-scoped ban cannot make: a file that legitimately holds the guarded call inside the+// owning function also permitted a stray one anywhere else in the same file.+func (p *Package) Contains(fn Func, site Site) bool {+ // The site carries its exact position rather than being re-derived from its line: a+ // call sharing a line with the func declaration would otherwise read as outside it.+ return site.pos != token.NoPos && site.pos >= fn.start && site.pos < fn.end+}++func (p *Package) each(visit func(name string, file *ast.File)) {+ for _, name := range sortedKeys(p.files) {+ visit(name, p.files[name])+ }+}++func (p *Package) site(fileName string, file *ast.File, node ast.Node, text string) Site {+ position := p.fset.Position(node.Pos())+ return Site{File: fileName, Line: position.Line, Func: enclosingFunc(file, node.Pos()), Text: text, pos: node.Pos()}+}++func enclosingFunc(file *ast.File, pos token.Pos) string {+ name := "(file scope)"+ for _, decl := range file.Decls {+ fn, ok := decl.(*ast.FuncDecl)+ if !ok {+ continue+ }+ if pos >= fn.Pos() && pos < fn.End() {+ name = fn.Name.Name+ }+ }+ return name+}++func calleeName(fun ast.Expr) string {+ switch callee := fun.(type) {+ case *ast.Ident:+ return callee.Name+ case *ast.SelectorExpr:+ if pkg, ok := callee.X.(*ast.Ident); ok {+ return pkg.Name + "." + callee.Sel.Name+ }+ return callee.Sel.Name+ }+ return ""+}++func sortedKeys(files map[string]*ast.File) []string {+ names := make([]string, 0, len(files))+ for name := range files {+ names = append(names, name)+ }+ for i := 1; i < len(names); i++ {+ for j := i; j > 0 && names[j] < names[j-1]; j-- {+ names[j], names[j-1] = names[j-1], names[j]+ }+ }+ return names+}diff --git a/internal/srccensus/srccensus_test.go b/internal/srccensus/srccensus_test.gonew file mode 100644index 00000000..cb2e3d06--- /dev/null+++ b/internal/srccensus/srccensus_test.go@@ -0,0 +1,239 @@+package srccensus++import (+ "fmt"+ "os"+ "path/filepath"+ "strings"+ "testing"+)++func writePackage(t *testing.T, files map[string]string) string {+ t.Helper()++ dir := t.TempDir()+ for name, body := range files {+ if err := os.WriteFile(filepath.Join(dir, name), []byte(body), 0o600); err != nil {+ t.Fatal(err)+ }+ }+ return dir+}++// recorder stands in for *testing.T so a guard's own failures can be asserted. A census+// helper whose Fatal cannot be observed is a promise nobody checked.+type recorder struct {+ testing.TB+ fatals []string+}++func (r *recorder) Helper() {}+func (r *recorder) Fatalf(format string, args ...any) {+ r.fatals = append(r.fatals, sprintf(format, args...))+ panic(errStop{})+}++type errStop struct{}++func sprintf(format string, args ...any) string {+ return strings.TrimSpace(fmt.Sprintf(format, args...))+}++func mustFatal(t *testing.T, run func(tb testing.TB)) string {+ t.Helper()++ rec := &recorder{TB: t}+ func() {+ defer func() {+ if recovered := recover(); recovered != nil {+ if _, ok := recovered.(errStop); !ok {+ panic(recovered)+ }+ }+ }()+ run(rec)+ }()+ if len(rec.fatals) == 0 {+ t.Fatal("expected the census helper to fail, but it returned quietly — the non-vacuity promise is not kept")+ }+ return rec.fatals[0]+}++// Non-vacuity is the property whose absence silently voids a guard, so it is asserted on+// the shared helper rather than trusted to each author.+func TestLoadFailsWhenThePackageYieldsFewerFilesThanTheGuardKnowsAbout(t *testing.T) {+ dir := writePackage(t, map[string]string{+ "only.go": "package p\n",+ "only_test.go": "package p\n",+ })++ message := mustFatal(t, func(tb testing.TB) { Load(tb, dir, 2) })+ for _, needle := range []string{"parsed 1 non-test files", "want at least 2", "pass vacuously"} {+ if !strings.Contains(message, needle) {+ t.Errorf("failure %q does not carry %q", message, needle)+ }+ }+}++func TestLoadFailsOnSourceItCannotParse(t *testing.T) {+ dir := writePackage(t, map[string]string{"broken.go": "package p\nfunc f( {\n"})++ if message := mustFatal(t, func(tb testing.TB) { Load(tb, dir, 1) }); !strings.Contains(message, "would skip it silently") {+ t.Errorf("failure %q should say an unparseable file is not silently skipped", message)+ }+}++func TestCallsFailsWhenThePatternMatchesNothing(t *testing.T) {+ dir := writePackage(t, map[string]string{"a.go": "package p\n\nfunc f() {}\n"})+ pkg := Load(t, dir, 1)++ message := mustFatal(t, func(tb testing.TB) { pkg.Calls(tb, "safelog.SetLevel") })+ for _, needle := range []string{"no call to safelog.SetLevel", "pass vacuously", "rather than deleting it"} {+ if !strings.Contains(message, needle) {+ t.Errorf("failure %q does not carry %q", message, needle)+ }+ }+}++// CallsAllowingNone exists so a ban whose PASS condition is zero says so out loud instead+// of inheriting a floor it cannot satisfy.+func TestCallsAllowingNoneReturnsEmptyWithoutFailing(t *testing.T) {+ dir := writePackage(t, map[string]string{"a.go": "package p\n\nfunc f() {}\n"})+ pkg := Load(t, dir, 1)++ if sites := pkg.CallsAllowingNone("safelog.SetLevel"); len(sites) != 0 {+ t.Errorf("sites = %v, want none", sites)+ }+}++// Every match, not the first: finding one site per file is how a guard silently inspects+// less than its message claims.+func TestCallsFindsEveryMatchIncludingSeveralInOneFileAndFunction(t *testing.T) {+ dir := writePackage(t, map[string]string{+ "a.go": `package p++func first() {+ safelog.SetLevel(1)+ safelog.SetLevel(2)+}++func second() {+ safelog.SetLevel(3)+}+`,+ "b.go": `package p++func third() {+ safelog.SetLevel(4)+}+`,+ })+ pkg := Load(t, dir, 2)++ sites := pkg.Calls(t, "safelog.SetLevel")+ if len(sites) != 4 {+ t.Fatalf("found %d sites, want 4: %v", len(sites), sites)+ }+ wantFuncs := map[string]int{"first": 2, "second": 1, "third": 1}+ gotFuncs := map[string]int{}+ for _, site := range sites {+ gotFuncs[site.Func]+++ if site.Line == 0 || site.File == "" {+ t.Errorf("site %v carries no position; a census failure must name a place the reader can open", site)+ }+ }+ for name, want := range wantFuncs {+ if gotFuncs[name] != want {+ t.Errorf("%s holds %d sites, want %d — each site must be attributed to its enclosing function", name, gotFuncs[name], want)+ }+ }+}++// Contains is the check a file-scoped ban cannot make: the owning file legitimately holds+// the guarded call inside the owning function, and used to permit a stray one anywhere+// else in that same file.+func TestContainsScopesASiteToTheOwningFunctionNotTheFile(t *testing.T) {+ dir := writePackage(t, map[string]string{+ "a.go": `package p++func owner() {+ safelog.SetLevel(1)+}++func stray() {+ safelog.SetLevel(2)+}+`,+ })+ pkg := Load(t, dir, 1)+ fn, ok := pkg.Func("owner")+ if !ok {+ t.Fatal("owner not found")+ }++ inside, outside := 0, 0+ for _, site := range pkg.Calls(t, "safelog.SetLevel") {+ if pkg.Contains(fn, site) {+ inside+++ continue+ }+ outside+++ }+ if inside != 1 || outside != 1 {+ t.Errorf("inside = %d, outside = %d, want 1 and 1: a file-scoped check would report both as permitted", inside, outside)+ }+}++func TestFuncReportsNotFoundRatherThanPanicking(t *testing.T) {+ dir := writePackage(t, map[string]string{"a.go": "package p\n\nfunc f() {}\n"})+ pkg := Load(t, dir, 1)++ if _, ok := pkg.Func("missing"); ok {+ t.Error("Func reported a declaration that does not exist")+ }+ if fn, ok := pkg.Func("f"); !ok || fn.File != "a.go" || fn.Line == 0 {+ t.Errorf("Func(f) = %+v, %v; want it located with a real position", fn, ok)+ }+}++// A declaration is looked up across the package, so moving a helper to a sibling file is+// a refactor rather than a test failure — and the shape that used to panic on a -1 slice.+func TestFuncFindsADeclarationInAnySiblingFile(t *testing.T) {+ dir := writePackage(t, map[string]string{+ "a.go": "package p\n\nfunc caller() { owner() }\n",+ "b.go": "package p\n\nfunc owner() {}\n",+ })+ pkg := Load(t, dir, 2)++ fn, ok := pkg.Func("owner")+ if !ok {+ t.Fatal("owner not found in a sibling file; a census that reads one hardcoded file breaks on this refactor")+ }+ if fn.File != "b.go" {+ t.Errorf("owner located in %s, want b.go", fn.File)+ }+}++// Receiver-name-blind on purpose: a census keyed on one spelling is scoped to that+// spelling, which is how the identical assignment through a renamed variable survives.+func TestFieldAssignmentsIgnoresWhatTheReceiverIsCalled(t *testing.T) {+ dir := writePackage(t, map[string]string{+ "a.go": `package p++func f(cfg *C, other *C) {+ cfg.LogLevel = "warn"+ other.LogLevel = "error"+ cfg.Port = "1"+}+`,+ })+ pkg := Load(t, dir, 1)++ sites := pkg.FieldAssignments("LogLevel")+ if len(sites) != 2 {+ t.Fatalf("found %d LogLevel assignments, want 2 regardless of receiver name: %v", len(sites), sites)+ }+ if got := pkg.FieldAssignments("Port"); len(got) != 1 {+ t.Errorf("found %d Port assignments, want 1", len(got))+ }+}