|
| 1 | +package guard |
| 2 | + |
| 3 | +import ( |
| 4 | + "fmt" |
| 5 | + "go/ast" |
| 6 | + "go/parser" |
| 7 | + "go/token" |
| 8 | + "os" |
| 9 | + "path/filepath" |
| 10 | + "sort" |
| 11 | + "strings" |
| 12 | + "testing" |
| 13 | +) |
| 14 | + |
| 15 | +// The second knob of the ratchet: how many things are CROWDING the ceiling. |
| 16 | +// |
| 17 | +// The ceiling in codeshape_test.go answers one question - is anything over the |
| 18 | +// line - and it is blind to the shape that actually happens: nothing over the |
| 19 | +// line, and everything creeping towards it. A tree where thirty functions sit |
| 20 | +// at seventy nine lines passes that guard and is exactly the tree the guard |
| 21 | +// exists to prevent. |
| 22 | +// |
| 23 | +// So the ratchet needs two knobs rather than one, which is the general form of |
| 24 | +// "the threshold only goes down" applied to any metric that decays slowly: |
| 25 | +// |
| 26 | +// a ceiling on the worst single case - catches one thing growing to a record |
| 27 | +// a count of things near the ceiling - catches everything drifting at once |
| 28 | +// |
| 29 | +// Measured on 2026-08-05 before the numbers below were chosen, because a |
| 30 | +// threshold picked out of the air is a guess, and a guess written into a gate |
| 31 | +// is a guess nobody can argue with later. |
| 32 | +const ( |
| 33 | + // What counts as crowding. Three quarters of the ceiling is far enough from |
| 34 | + // it that ordinary code does not trip the count, and close enough that |
| 35 | + // something arriving there is on its way. |
| 36 | + crowdingShare = 75 |
| 37 | + |
| 38 | + // Caps measured on the tree of 2026-08-05, then frozen - eleven functions and |
| 39 | + // two files were already crowding, against a first guess of four. That gap is |
| 40 | + // the whole argument for measuring rather than choosing: a cap of four would |
| 41 | + // have gone in red and been raised to make it pass, which is how a ratchet |
| 42 | + // becomes a rubber band. Like the ceilings |
| 43 | + // themselves these only go down. Raising one to turn a run green is the |
| 44 | + // same act as editing a golden value for the same reason. |
| 45 | + crowdedFunctions = 11 |
| 46 | + crowdedFiles = 2 |
| 47 | +) |
| 48 | + |
| 49 | +func TestNothingIsQuietlyCreepingTowardsTheCeiling(t *testing.T) { |
| 50 | + var functions, files []string |
| 51 | + |
| 52 | + for _, p := range packages(t) { |
| 53 | + for _, path := range p.files { |
| 54 | + body, err := os.ReadFile(path) |
| 55 | + if err != nil { |
| 56 | + t.Fatalf("reading %s: %v", path, err) |
| 57 | + } |
| 58 | + src := strings.Split(strings.ReplaceAll(string(body), "\r\n", "\n"), "\n") |
| 59 | + |
| 60 | + fset := token.NewFileSet() |
| 61 | + file, err := parser.ParseFile(fset, path, body, parser.ParseComments) |
| 62 | + if err != nil { |
| 63 | + t.Fatalf("parsing %s: %v", path, err) |
| 64 | + } |
| 65 | + comments := commentLines(fset, file) |
| 66 | + |
| 67 | + rel, err := filepath.Rel(repoRoot(t), path) |
| 68 | + if err != nil { |
| 69 | + rel = path |
| 70 | + } |
| 71 | + rel = filepath.ToSlash(rel) |
| 72 | + |
| 73 | + if n := codeLines(src, comments, 1, len(src)); crowding(n, longestFile) { |
| 74 | + files = append(files, fmt.Sprintf("%s %d/%d", rel, n, longestFile)) |
| 75 | + } |
| 76 | + |
| 77 | + for _, decl := range file.Decls { |
| 78 | + fn, ok := decl.(*ast.FuncDecl) |
| 79 | + if !ok || fn.Body == nil { |
| 80 | + continue |
| 81 | + } |
| 82 | + from := fset.Position(fn.Pos()).Line |
| 83 | + to := fset.Position(fn.End()).Line |
| 84 | + if n := codeLines(src, comments, from, to); crowding(n, longestFunction) { |
| 85 | + functions = append(functions, fmt.Sprintf("%s:%d %s %d/%d", |
| 86 | + rel, from, name(fn), n, longestFunction)) |
| 87 | + } |
| 88 | + } |
| 89 | + } |
| 90 | + } |
| 91 | + |
| 92 | + sort.Strings(functions) |
| 93 | + sort.Strings(files) |
| 94 | + |
| 95 | + if len(functions) > crowdedFunctions { |
| 96 | + t.Errorf("%d function(s) are within %d%% of the ceiling and the cap is %d:\n %s\n\n"+ |
| 97 | + "Nothing is over the line, which is the point - this is the drift the other guard "+ |
| 98 | + "cannot see. Split one of these rather than raising the cap.", |
| 99 | + len(functions), crowdingShare, crowdedFunctions, strings.Join(functions, "\n ")) |
| 100 | + } |
| 101 | + if len(files) > crowdedFiles { |
| 102 | + t.Errorf("%d file(s) are within %d%% of the ceiling and the cap is %d:\n %s", |
| 103 | + len(files), crowdingShare, crowdedFiles, strings.Join(files, "\n ")) |
| 104 | + } |
| 105 | + |
| 106 | + t.Logf("crowding the ceiling: %d function(s) of %d allowed, %d file(s) of %d allowed", |
| 107 | + len(functions), crowdedFunctions, len(files), crowdedFiles) |
| 108 | + for _, f := range functions { |
| 109 | + t.Logf(" function %s", f) |
| 110 | + } |
| 111 | + for _, f := range files { |
| 112 | + t.Logf(" file %s", f) |
| 113 | + } |
| 114 | +} |
| 115 | + |
| 116 | +// crowding reports whether a measurement has reached the share of the ceiling |
| 117 | +// at which it counts as on its way there. |
| 118 | +func crowding(n, ceiling int) bool { |
| 119 | + return n*100 >= ceiling*crowdingShare |
| 120 | +} |
0 commit comments