GitLabgitlab-org

cli

main
ply6 git calls199 ms99 KiB4 cachedprotocol v2
394 lines10 KiBRaw
1// Flag comments whose content is inferable from the code they sit next to.
2//
3// Usage:
4//
5// go run ./scripts/comment-overlap ./internal/...
6// go run ./scripts/comment-overlap -threshold 0.6 -sample 25 ./...
7// go run ./scripts/comment-overlap -json ./internal/commands/mr/...
8//
9// The signal is token coverage: a comment whose words are mostly already
10// present in the adjacent code restates that code, so it carries no
11// information a reader could not get from the line itself. This is a
12// mechanical proxy for "document only what is non-obvious from the code".
13//
14// Doc comments are skipped by position, using go/ast Doc fields rather than
15// text heuristics, so idiomatic godoc on an exported symbol is never flagged
16// for repeating its own symbol name. Only inline comments are considered.
17//
18// Comment tokens are matched against code tokens after camelCase and
19// snake_case splitting, so "clear env vars" is recognised as covered by
20// env.RemoveVar(...).
21package main
23import (
24 "encoding/json"
25 "flag"
26 "fmt"
27 "go/ast"
28 "go/parser"
29 "go/token"
30 "io/fs"
31 "os"
32 "path/filepath"
33 "regexp"
34 "sort"
35 "strings"
36 "unicode"
39var (
40 excludeRe = regexp.MustCompile(`(^|/)(vendor|docs|testdata|node_modules)/|\.pb\.go$|_generated\.go$|(^|/)mock_[^/]*\.go$`)
41 wordRe = regexp.MustCompile(`[A-Za-z][A-Za-z0-9]*`)
43 // A numbered step labels its position in a sequence, which is information
44 // the code does not carry even when the label itself restates the call.
45 // Removing some steps of a run would leave the remaining numbering broken.
46 stepRe = regexp.MustCompile(`^\d+\.\s`)
48 stop = map[string]struct{}{
49 "the": {}, "a": {}, "an": {}, "to": {}, "of": {}, "in": {},
50 "on": {}, "for": {}, "and": {}, "or": {}, "is": {}, "are": {},
51 "be": {}, "with": {}, "this": {}, "that": {}, "it": {},
52 "as": {}, "at": {}, "by": {}, "from": {}, "into": {}, "we": {},
53 "if": {}, "else": {}, "return": {}, "func": {}, "var": {},
54 "err": {}, "nil": {},
55 }
57 // Words that signal rationale rather than description. Exempting these is
58 // Orbit's precision tactic; -why-exempt makes it measurable rather than
59 // assumed, since the list is common enough to swallow real findings.
60 why = map[string]struct{}{
61 "because": {}, "so": {}, "since": {}, "otherwise": {},
62 "must": {}, "note": {}, "safety": {}, "gotcha": {},
63 "invariant": {}, "intentionally": {}, "deliberately": {},
64 "avoid": {}, "prevents": {}, "ensures": {}, "would": {},
65 "cannot": {}, "never": {}, "always": {}, "only": {},
66 "instead": {}, "rather": {}, "workaround": {}, "hack": {},
67 "race": {}, "deadlock": {}, "panic": {}, "assumes": {},
68 "requires": {}, "needs": {}, "guarantees": {},
69 }
72type finding struct {
73 File string `json:"file"`
74 Line int `json:"line"`
75 Coverage float64 `json:"coverage"`
76 Comment string `json:"comment"`
77 Code string `json:"code"`
80func main() {
81 threshold := flag.Float64("threshold", 0.6, "minimum token coverage to flag")
82 whyExempt := flag.Bool("why-exempt", false, "skip comments containing a rationale word")
83 sample := flag.Int("sample", 0, "print at most N findings, evenly spaced")
84 asJSON := flag.Bool("json", false, "emit JSON")
85 maxFindings := flag.Int("max-findings", -1, "exit 1 if findings exceed this; -1 disables the gate")
86 flag.Parse()
88 targets := flag.Args()
89 if len(targets) == 0 {
90 targets = []string{"./..."}
91 }
93 files, err := collect(targets)
94 if err != nil {
95 fmt.Fprintf(os.Stderr, "comment-overlap: %v\n", err)
96 os.Exit(2)
97 }
99 var found []finding
100 scanned := 0
101 for _, path := range files {
102 fs, err := analyze(path, *threshold, *whyExempt)
103 if err != nil {
104 continue
105 }
106 scanned++
107 found = append(found, fs...)
108 }
110 sort.Slice(found, func(i, j int) bool {
111 if found[i].Coverage != found[j].Coverage {
112 return found[i].Coverage > found[j].Coverage
113 }
114 return found[i].File < found[j].File
115 })
117 shown := found
118 if *sample > 0 && len(found) > *sample {
119 shown = nil
120 step := float64(len(found)) / float64(*sample)
121 for i := 0; i < *sample; i++ {
122 shown = append(shown, found[int(float64(i)*step)])
123 }
124 }
126 if *asJSON {
127 //nolint:forbidigo // dev script; IOStreams.PrintJSON is for CLI commands
128 enc := json.NewEncoder(os.Stdout)
129 enc.SetIndent("", " ")
130 _ = enc.Encode(map[string]any{
131 "files_scanned": scanned, "findings": len(found), "shown": shown,
132 })
133 } else {
134 for _, f := range shown {
135 fmt.Printf("%s:%d\t%.2f\t// %s\n\t\t-> %s\n", f.File, f.Line, f.Coverage, f.Comment, f.Code)
136 }
137 fmt.Fprintf(os.Stderr, "# %d findings across %d files\n", len(found), scanned)
138 }
140 if *maxFindings >= 0 && len(found) > *maxFindings {
141 fmt.Fprintf(os.Stderr,
142 "comment-overlap: %d findings exceed the allowed %d; these comments restate the code they sit next to\n",
143 len(found), *maxFindings)
144 os.Exit(1)
145 }
148func collect(targets []string) ([]string, error) {
149 seen := map[string]struct{}{}
150 var out []string
151 for _, t := range targets {
152 root := strings.TrimSuffix(strings.TrimSuffix(t, "..."), "/")
153 if root == "" || root == "." {
154 root = "."
155 }
156 err := filepath.WalkDir(root, func(path string, d fs.DirEntry, walkErr error) error {
157 // Surfaced rather than skipped: a file this gate cannot read is a
158 // file it cannot check, which must not look like a pass.
159 if walkErr != nil {
160 return walkErr
161 }
162 if d.IsDir() {
163 if strings.HasPrefix(d.Name(), ".") && d.Name() != "." {
164 return filepath.SkipDir
165 }
166 return nil
167 }
168 if !strings.HasSuffix(path, ".go") || excludeRe.MatchString(path) || has(seen, path) {
169 return nil
170 }
171 seen[path] = struct{}{}
172 out = append(out, path)
173 return nil
174 })
175 if err != nil {
176 return nil, err
177 }
178 }
179 sort.Strings(out)
180 return out, nil
183func analyze(path string, threshold float64, whyExempt bool) ([]finding, error) {
184 src, err := os.ReadFile(path)
185 if err != nil {
186 return nil, err
187 }
188 fset := token.NewFileSet()
189 f, err := parser.ParseFile(fset, path, src, parser.ParseComments)
190 if err != nil {
191 return nil, err
192 }
194 lineOf := func(p token.Pos) int { return fset.Position(p).Line }
195 colOf := func(p token.Pos) int { return fset.Position(p).Column }
197 docLines := map[int]struct{}{}
198 markDoc := func(g *ast.CommentGroup) {
199 if g == nil {
200 return
201 }
202 for i := lineOf(g.Pos()); i <= lineOf(g.End()); i++ {
203 docLines[i] = struct{}{}
204 }
205 }
206 markDoc(f.Doc)
207 ast.Inspect(f, func(n ast.Node) bool {
208 switch d := n.(type) {
209 case *ast.FuncDecl:
210 markDoc(d.Doc)
211 case *ast.GenDecl:
212 markDoc(d.Doc)
213 case *ast.TypeSpec:
214 markDoc(d.Doc)
215 case *ast.ValueSpec:
216 markDoc(d.Doc)
217 case *ast.Field:
218 markDoc(d.Doc)
219 }
220 return true
221 })
223 commentLines := map[int]struct{}{}
224 for _, g := range f.Comments {
225 for i := lineOf(g.Pos()); i <= lineOf(g.End()); i++ {
226 commentLines[i] = struct{}{}
227 }
228 }
230 raw := strings.Split(string(src), "\n")
231 isCode := func(n int) bool {
232 if n < 1 || n > len(raw) {
233 return false
234 }
235 return !has(commentLines, n) && strings.TrimSpace(raw[n-1]) != ""
236 }
238 var out []finding
239 for _, g := range f.Comments {
240 start, end := lineOf(g.Pos()), lineOf(g.End())
241 if has(docLines, start) {
242 continue
243 }
245 // A block comment with code on both sides annotates that code rather
246 // than describing a following statement, as in an unnamed return type.
247 if endLine, endCol := lineOf(g.End()), colOf(g.End()); endLine == start &&
248 endCol-1 <= len(raw[start-1]) &&
249 strings.TrimSpace(raw[start-1][endCol-1:]) != "" {
250 continue
251 }
253 // A trailing comment describes the line it sits on, not the next one.
254 var codeLine int
255 if colOf(g.Pos()) > 1 && strings.TrimSpace(strings.Split(raw[start-1], "//")[0]) != "" {
256 codeLine = start
257 } else {
258 for n := end + 1; n <= len(raw) && n <= end+3; n++ {
259 if isCode(n) {
260 codeLine = n
261 break
262 }
263 }
264 }
265 if codeLine == 0 {
266 continue
267 }
269 text := commentText(g)
270 if stepRe.MatchString(text) {
271 continue
272 }
273 ct := tokenize(text)
274 if len(ct) < 2 {
275 continue
276 }
277 if whyExempt && hasWhy(text) {
278 continue
279 }
281 codeSrc := raw[codeLine-1]
282 if codeLine == start {
283 codeSrc = strings.Split(codeSrc, "//")[0]
284 }
285 cov := coverage(ct, tokenize(codeSrc))
286 if cov >= threshold {
287 out = append(out, finding{
288 File: path, Line: start, Coverage: cov,
289 Comment: collapse(text), Code: collapse(codeSrc),
290 })
291 }
292 }
293 return out, nil
296func commentText(g *ast.CommentGroup) string {
297 var b strings.Builder
298 for _, c := range g.List {
299 t := c.Text
300 t = strings.TrimPrefix(t, "//")
301 t = strings.TrimPrefix(t, "/*")
302 t = strings.TrimSuffix(t, "*/")
303 b.WriteString(" ")
304 b.WriteString(t)
305 }
306 return strings.TrimSpace(b.String())
309func tokenize(s string) map[string]struct{} {
310 out := map[string]struct{}{}
311 for _, w := range wordRe.FindAllString(s, -1) {
312 for _, part := range splitIdent(w) {
313 p := strings.ToLower(part)
314 if p == "" || has(stop, p) {
315 continue
316 }
317 out[stem(p)] = struct{}{}
318 }
319 }
320 return out
323// splitIdent breaks Go identifiers into words so comment prose can be matched
324// against camelCase and snake_case code tokens.
325func splitIdent(s string) []string {
326 var parts []string
327 for chunk := range strings.SplitSeq(s, "_") {
328 start := 0
329 runes := []rune(chunk)
330 for i := 1; i < len(runes); i++ {
331 prev, cur := runes[i-1], runes[i]
332 boundary := unicode.IsLower(prev) && unicode.IsUpper(cur)
333 if boundary {
334 parts = append(parts, string(runes[start:i]))
335 start = i
336 }
337 }
338 if start < len(runes) {
339 parts = append(parts, string(runes[start:]))
340 }
341 }
342 return parts
345func stem(s string) string {
346 if len(s) > 3 && strings.HasSuffix(s, "s") && !strings.HasSuffix(s, "ss") {
347 return strings.TrimSuffix(s, "s")
348 }
349 return s
352func coverage(comment, code map[string]struct{}) float64 {
353 if len(comment) == 0 {
354 return 0
355 }
356 matched := 0
357 for t := range comment {
358 if has(code, t) {
359 matched++
360 continue
361 }
362 for c := range code {
363 // Both sides need length: a one-character code token such as a
364 // receiver name would otherwise substring-match any word.
365 if len(t) >= 4 && len(c) >= 4 && (strings.Contains(c, t) || strings.Contains(t, c)) {
366 matched++
367 break
368 }
369 }
370 }
371 return float64(matched) / float64(len(comment))
374func hasWhy(text string) bool {
375 for _, w := range wordRe.FindAllString(strings.ToLower(text), -1) {
376 if has(why, w) {
377 return true
378 }
379 }
380 return strings.Contains(text, "http://") || strings.Contains(text, "https://")
383func collapse(s string) string {
384 s = strings.Join(strings.Fields(s), " ")
385 if len(s) > 90 {
386 s = s[:90] + "…"
387 }
388 return s
391func has[K comparable](m map[K]struct{}, k K) bool {
392 _, ok := m[k]
393 return ok
Diagnostics6 git calls · 199 ms
CallStatusSizeTime0199 ms
discover200185 B3 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=3
git.response.bytes=185
git.server.agent=git/2.56.g1891de4-Linux
git.server.object_format=sha1
git.server.caps=agent ls-refs fetch server-option object-format
git.server.fetch=shallow wait-for-done filter
git.protocol.version=2
git.pkt.frames=9
git.pkt.data=7
git.pkt.flush=2
git.pkt.delim=0
git.pkt.bytes=185
git.pkt.payload.max=35
ls-refs20058 KiB · hit7 ms
git.upload-pack ls-refs
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=3
git.response.bytes=59849
git.response.cache=HIT
git.response.duration_ms=7
git.protocol.version=2
git.pkt.frames=731
git.pkt.data=730
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=59849
git.pkt.payload.max=143
git.ls_refs.count=730
git.ls_refs.head=refs/heads/main
fetchcombine:blob:none+tree:2 · deepen 12004.2 KiB · hit2 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=3
git.response.bytes=4273
git.response.cache=HIT
git.response.duration_ms=2
git.fetch.filter=combine:blob:none+tree:2
git.fetch.wants=0dd7574dce9e385c5c30540e6c15657adc6bdce9
git.fetch.haves.count=0
git.fetch.deepen=1
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=7
git.pkt.data=5
git.pkt.flush=1
git.pkt.delim=1
git.pkt.bytes=4273
git.pkt.payload.max=4173
git.sideband.band1.bytes=4173
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=11
git.pack.bytes=4173
git.fetch.wide.objects=11
git.fetch.wide.extra_bytes=3930
git.fetch.wide.blobs=0
fetchtree:0 · deepen 1020032 KiB · hit3 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=2
git.response.bytes=32926
git.response.cache=HIT
git.response.duration_ms=3
git.fetch.filter=tree:0
git.fetch.wants=0dd7574dce9e385c5c30540e6c15657adc6bdce9
git.fetch.haves.count=0
git.fetch.deepen=10
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=22
git.pkt.data=20
git.pkt.flush=1
git.pkt.delim=1
git.pkt.bytes=32926
git.pkt.payload.max=32046
git.sideband.band1.bytes=32046
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=80
git.pack.bytes=32046
git.pack.ofs_delta=36
git.pack.ref_delta=0
git.pack.chain.max=2
git.pack.trailer=cb0bad5d7ffc514895d8b21c4dd470327f90bc91
git.pack.full=44
Open pack map
fetchtree:0200105 B · hit2 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=2
git.response.bytes=105
git.response.cache=HIT
git.response.duration_ms=2
git.fetch.filter=tree:0
git.fetch.wants=ef89b03d1ab233731a39c150d867dd04491d2ded
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=4
git.pkt.data=3
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=105
git.pkt.payload.max=78
git.sideband.band1.bytes=78
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=1
git.pack.bytes=78
git.pack.trailer=9616c6e50c4c66af16b59e9ab7e3ce12ddbd3192
Open pack map
fetch2004.0 KiB188 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=188
git.response.bytes=4120
git.response.cache=MISS
git.response.duration_ms=188
git.fetch.wants=a9072abdc151850558f201ab95aa59d6043b5070
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=4
git.pkt.data=3
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=4120
git.pkt.payload.max=4093
git.sideband.band1.bytes=4093
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0

Each row is one HTTP round trip ply made to the git server for this page, on one timeline. discover asks what the server speaks, ls-refs lists branch tips, fetch brings objects by id. A hit was served by Workers Cache. Tap a row for its wire details.

Remote
https://gitlab.com/gitlab-org/cli
Ref
refs/heads/main
Commit
0dd7574dce9e385c5c30540e6c15657adc6bdce9
cf-ray
a5e16b4788de4b2a
Request
8e36b8e4…
Protocol
v2 · sha1
Agent
git/2.56.g1891de4-Linux
Filter
advertised
Fetch
shallow wait-for-done filter
Capabilities
agent ls-refs fetch server-option object-format