GitLabgitlab-org
cli
main
1// Measure how much of a change is comment rather than code.
2//
3// Usage:
4//
5// go run ./scripts/comment-ratio -base origin/main
6// go run ./scripts/comment-ratio -base <sha> -head <sha> -per-file
7// go run ./scripts/comment-ratio -base origin/main -max-inline-ratio 0.25
8//
9// Unlike a per-comment classifier, this makes no judgement about any
10// individual comment, so rewording cannot move the number: only writing
11// fewer comment lines can. That makes it a volume signal rather than a
12// quality one.
13//
14// Added lines are classified against the full parsed file, so doc comments
15// are attributed through go/ast Doc fields rather than guessed from the
16// diff hunk. Lines are reported in three classes:
17//
18// doc comment lines attached to a declaration as its godoc
19// inline every other comment line
20// code non-blank, non-comment
21//
22// inline_ratio (inline/code) is the actionable signal. Doc comments are
23// counted separately because documenting an exported symbol is required by
24// convention and should not read as noise.
25package main
27import (
28 "encoding/json"
29 "flag"
30 "fmt"
31 "go/ast"
32 "go/parser"
33 "go/token"
34 "os"
35 "os/exec"
36 "regexp"
37 "sort"
38 "strconv"
39 "strings"
40)
42var (
43 excludeRe = regexp.MustCompile(`(^|/)(vendor|docs|testdata)/|\.pb\.go$|_generated\.go$|(^|/)mock_[^/]*\.go$`)
44 hunkRe = regexp.MustCompile(`^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@`)
45)
47type counts struct {
48 Code int `json:"code"`
49 Inline int `json:"inline"`
50 Doc int `json:"doc"`
51}
53type fileResult struct {
54 Path string `json:"path"`
55 counts
56}
58func main() {
59 base := flag.String("base", "", "revision to diff against (required)")
60 head := flag.String("head", "", "revision to diff to; defaults to the working tree")
61 asJSON := flag.Bool("json", false, "emit JSON")
62 perFile := flag.Bool("per-file", false, "include per-file rows")
63 maxRatio := flag.Float64("max-inline-ratio", -1, "exit 1 if inline/code exceeds this")
64 flag.Parse()
66 if *base == "" {
67 fmt.Fprintln(os.Stderr, "comment-ratio: -base is required")
68 os.Exit(2)
69 }
71 added, err := addedLines(*base, *head)
72 if err != nil {
73 fmt.Fprintf(os.Stderr, "comment-ratio: %v\n", err)
74 os.Exit(2)
75 }
77 var total counts
78 var rows []fileResult
79 paths := make([]string, 0, len(added))
80 for p := range added {
81 paths = append(paths, p)
82 }
83 sort.Strings(paths)
85 for _, path := range paths {
86 src, err := fileSource(*head, path)
87 if err != nil {
88 continue
89 }
90 kinds, err := classify(path, src)
91 if err != nil {
92 continue
93 }
94 var c counts
95 for line := range added[path] {
96 if line < 1 || line > len(kinds) {
97 continue
98 }
99 switch kinds[line-1] {
100 case "code":
101 c.Code++
102 case "inline":
103 c.Inline++
104 case "doc":
105 c.Doc++
106 }
107 }
108 total.Code += c.Code
109 total.Inline += c.Inline
110 total.Doc += c.Doc
111 if *perFile && (c.Inline > 0 || c.Code > 0) {
112 rows = append(rows, fileResult{Path: path, counts: c})
113 }
114 }
116 ratio := -1.0
117 if total.Code > 0 {
118 ratio = float64(total.Inline) / float64(total.Code)
119 }
121 if *asJSON {
122 out := map[string]any{
123 "code": total.Code, "inline": total.Inline, "doc": total.Doc,
124 "inline_ratio": round(ratio), "files": rows,
125 }
126 //nolint:forbidigo // dev script; IOStreams.PrintJSON is for CLI commands
127 enc := json.NewEncoder(os.Stdout)
128 enc.SetIndent("", " ")
129 _ = enc.Encode(out)
130 } else {
131 for _, r := range rows {
132 fmt.Printf("%s\tcode=%d inline=%d doc=%d\n", r.Path, r.Code, r.Inline, r.Doc)
133 }
134 fmt.Printf("# code=%d inline=%d doc=%d inline_ratio=%s\n",
135 total.Code, total.Inline, total.Doc, fmtRatio(ratio))
136 }
138 if *maxRatio >= 0 && ratio > *maxRatio {
139 fmt.Fprintf(os.Stderr, "comment-ratio: inline ratio %s exceeds %.2f\n",
140 fmtRatio(ratio), *maxRatio)
141 os.Exit(1)
142 }
143}
145func addedLines(base, head string) (map[string]map[int]struct{}, error) {
146 spec := base
147 if head != "" {
148 spec = base + "..." + head
149 }
150 out, err := exec.Command("git", "diff", "--unified=0", "--diff-filter=ACMR", spec, "--", "*.go").Output()
151 if err != nil {
152 return nil, fmt.Errorf("git diff %s: %w", spec, err)
153 }
155 result := map[string]map[int]struct{}{}
156 var current string
157 for line := range strings.SplitSeq(string(out), "\n") {
158 switch {
159 case strings.HasPrefix(line, "+++ b/"):
160 current = strings.TrimPrefix(line, "+++ b/")
161 if !strings.HasSuffix(current, ".go") || excludeRe.MatchString(current) {
162 current = ""
163 continue
164 }
165 if result[current] == nil {
166 result[current] = map[int]struct{}{}
167 }
168 case current != "" && strings.HasPrefix(line, "@@"):
169 m := hunkRe.FindStringSubmatch(line)
170 if m == nil {
171 continue
172 }
173 start, _ := strconv.Atoi(m[1])
174 count := 1
175 if m[2] != "" {
176 count, _ = strconv.Atoi(m[2])
177 }
178 for i := start; i < start+count; i++ {
179 result[current][i] = struct{}{}
180 }
181 }
182 }
183 for p, lines := range result {
184 if len(lines) == 0 {
185 delete(result, p)
186 }
187 }
188 return result, nil
189}
191func fileSource(head, path string) ([]byte, error) {
192 if head == "" {
193 return os.ReadFile(path)
194 }
195 return exec.Command("git", "show", head+":"+path).Output()
196}
198func classify(path string, src []byte) ([]string, error) {
199 fset := token.NewFileSet()
200 f, err := parser.ParseFile(fset, path, src, parser.ParseComments)
201 if err != nil {
202 return nil, err
203 }
205 lineOf := func(p token.Pos) int { return fset.Position(p).Line }
207 docLines := map[int]struct{}{}
208 markDoc := func(g *ast.CommentGroup) {
209 if g == nil {
210 return
211 }
212 for i := lineOf(g.Pos()); i <= lineOf(g.End()); i++ {
213 docLines[i] = struct{}{}
214 }
215 }
216 markDoc(f.Doc)
217 ast.Inspect(f, func(n ast.Node) bool {
218 switch d := n.(type) {
219 case *ast.FuncDecl:
220 markDoc(d.Doc)
221 case *ast.GenDecl:
222 markDoc(d.Doc)
223 case *ast.TypeSpec:
224 markDoc(d.Doc)
225 case *ast.ValueSpec:
226 markDoc(d.Doc)
227 case *ast.Field:
228 markDoc(d.Doc)
229 }
230 return true
231 })
233 commentLines := map[int]struct{}{}
234 for _, g := range f.Comments {
235 for i := lineOf(g.Pos()); i <= lineOf(g.End()); i++ {
236 commentLines[i] = struct{}{}
237 }
238 }
240 raw := strings.Split(string(src), "\n")
241 kinds := make([]string, len(raw))
242 for i, line := range raw {
243 n := i + 1
244 switch {
245 case has(docLines, n):
246 kinds[i] = "doc"
247 case has(commentLines, n):
248 kinds[i] = "inline"
249 case strings.TrimSpace(line) == "":
250 kinds[i] = "blank"
251 default:
252 kinds[i] = "code"
253 }
254 }
255 return kinds, nil
256}
258func round(v float64) float64 {
259 if v < 0 {
260 return -1
261 }
262 return float64(int(v*1000+0.5)) / 1000
263}
265func fmtRatio(v float64) string {
266 if v < 0 {
267 return "n/a"
268 }
269 return strconv.FormatFloat(round(v), 'f', 3, 64)
270}
272func has[K comparable](m map[K]struct{}, k K) bool {
273 _, ok := m[k]
274 return ok
275}
Diagnostics6 git calls · 51 ms
CallStatusSizeTime051 ms
discover200185 B2 ms
git.upload-pack discover http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=ls-refs git.upstream.dur_ms=2 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 · hit2 ms
git.upload-pack ls-refs http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=ls-refs git.upstream.dur_ms=2 git.response.bytes=59849 git.response.cache=HIT git.response.duration_ms=2 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 · hit3 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=4 git.response.bytes=4273 git.response.cache=HIT git.response.duration_ms=3 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 · hit4 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=32926 git.response.cache=HIT git.response.duration_ms=4 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=44Open pack map
fetchtree:0200105 B · hit3 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=105 git.response.cache=HIT git.response.duration_ms=3 git.fetch.filter=tree:0 git.fetch.wants=696be8fd02ce9fe47287a54fb2691edf02903f4d 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=d44fabcf6fe6b3f0ed9896f18c9570adf89d658cOpen pack map
fetch2002.7 KiB · hit43 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=43 git.response.bytes=2720 git.response.cache=HIT git.response.duration_ms=43 git.fetch.wants=1dbb3415cd7cff77fd24e439c8f46de0caf9dca7 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=2720 git.pkt.payload.max=2693 git.sideband.band1.bytes=2693 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
- a5e1396f38ab18aa
- Request
- 371cbaa0…
- 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