iru-go-code-quality
Run a Go module's wired static-analysis and style checks — golangci-lint v2 (`golangci-lint run --output.json.path …`, a `version: "2"` config with `linters` and `formatters` sections; issues bucketed
SKILL.md.claude/skills/iru-go-code-quality/SKILL.md
GitHubGo Code Quality
Run every static-analysis and style check this Go project actually has wired — golangci-lint (linters and
formatters), go vet, and govulncheck — and report every issue, grouped by tool and by rule id. This skill only runs
checks and reports results — it never fixes issues, applies formatting, adds //nolint, tidies modules, or modifies
tool configuration unless asked to as a follow-up.
Step 0 — Resolve inputs
- Scope (optional, comma-separated):
.gofiles or directories (internal/greet/run.go,internal/cli). Drop paths that don't exist and say so. golangci-lint andgo vetwork on packages (a file is type-checked with the rest of its package), so map each scoped file to its directory (./internal/greet) for the run and filter the findings back down to the scope in Step 3. No scope →./...(or one./<dir>/...per module of ago.workworkspace whose root isn't a module —go list -m -f '{{.Dir}}';./...fails there, as iniru-go-testStep 1). baseline: <prior report>(optional) — per-tool/per-rule-id counts, or an itemizedtool rule file:linelist, from an earlier run of this skill; kept for Step 4.
Read the project's real invocation before choosing flags: .github/workflows/*.yml (a golangci/golangci-lint-action
step pins a version: and may pass args:), Makefile/Taskfile.yml/magefile.go lint targets, and
.pre-commit-config.yaml. Mirror its --build-tags/--config/--timeout, and note a version mismatch between the
installed golangci-lint version and the CI pin — different versions report different issues.
Step 1 — Verify which tools are wired
| Tool | Wired when | Notes |
|---|---|---|
| golangci-lint | command -v golangci-lint and a config (.golangci.yml/.yaml/.toml/.json, found by walking up from the module) or a CI/Makefile golangci-lint run |
Config must declare version: "2". A v1 config (no version) makes v2 exit 3 with can't load config: unsupported version of the configuration: "" (verified) — report it as a tooling failure with the fix (golangci-lint migrate), never as "0 issues". Note linters.default (standard = errcheck, govet, ineffassign, staticcheck, unused; all; none; fast), linters.enable/disable, linters.exclusions.presets (the comments preset hides revive's exported/package-comments findings — say so, iru-go-godoc checks those with its own config), exclusions.generated, and formatters.enable (gofmt, goimports, gofumpt, gci, golines). Installed but no config → it runs with the standard defaults: run it and say "golangci-lint defaults (no project config)". |
| go vet | always (part of the toolchain; go test runs a subset anyway) |
Runs separately from golangci-lint's govet (whose analyzer set the config controls) — both are reported, in separate buckets. |
| gofmt | always, but only as a standalone check when golangci-lint isn't wired or its config enables no formatter | With golangci-lint formatters enabled, formatting issues come back in its report as rule gofmt/goimports/…; running gofmt -l too would double-count. |
| govulncheck | command -v govulncheck (or a CI step / go tool govulncheck from a tool directive in go.mod) |
Needs network access to vuln.go.dev (or -db file://…). Unreachable → "govulncheck: vulnerability database unreachable, skipped", never "0 vulnerabilities". |
A tool that isn't wired is skipped and named in the report ("govulncheck: not installed, skipped") — never omitted
silently, never reported as "0 issues". Recommend (don't fail on) missing expected tools: golangci-lint v2 with
revive, gosec, errorlint and the gofmt/goimports formatters, and govulncheck — the set iru-setup-go-cli
scaffolds.
Step 2 — Run each wired tool
Write every machine-readable report under build/, prefixed iru-go-cq-, and delete them afterwards (rm -f build/iru-go-cq-*; remove build/ only if this run created it). Exit codes are information, not failures — always
read the report; only a "tool broke" exit (listed per tool) means the report can't be trusted.
golangci-lint:
golangci-lint run --output.json.path="$PWD/build/iru-go-cq-golangci.json" --output.text.path=stderr \ --show-stats=false --max-issues-per-linter=0 --max-same-issues=0 --uniq-by-line=false --path-mode=abs \ [--build-tags …] <packages> 2>/dev/null- v2 output flags are
--output.<format>.path(v1's--out-formatis gone). Relative output paths and issue paths are resolved against the config file's directory in v2 (verified: with-c ../cfg.ymlthe report landed beside the config) — hence the absolute$PWD/…output path and--path-mode=abs(the parser makes paths project-relative again).--max-issues-per-linter=0 --max-same-issues=0lift the default caps (50 / 3) and--uniq-by-line=falsethe default one-issue-per-line dedup (verified: with it on, agodotfinding on the same line as arevive:exportedone was dropped) — all three would otherwise hide issues. - Exit
0= clean,1= issues found,3= failure (bad config, a linter that can't load);--issues-exit-codeonly changes the1. A compile error comes back as exit1with lintertypecheckissues (verified) — report those first: they stop the other linters for that package. - Shape:
{"Issues": [{"FromLinter": "gosec", "Text": "G204: Subprocess launched with variable", "Severity": "medium", "Pos": {"Filename": "…/run.go", "Line": 13, "Column": 9}, "SourceLines": […]}], "Report": {"Linters": [{"Name": "errcheck", "Enabled": true}, …]}}—Report.Linterslists what actually ran.
- v2 output flags are
go vet:
go vet -json [-tags …] <packages> > build/iru-go-cq-vet.json 2>&1-jsonexits0even with findings and writes a stream of JSON objects ({"<pkg>": {"<analyzer>": [{"posn": "/abs/file.go:6:41", "message": "…"}]}},{}for clean packages) — to stdout in Go 1.27 (older releases used stderr, hence2>&1). Text mode (go vet ./…) exits1withfile:line:col: messagebut no analyzer name.- A package that doesn't compile shows its compiler error instead — report it as a tooling failure.
gofmt (only per Step 1):
gofmt -l $(git ls-files '*.go') > build/iru-go-cq-gofmt.txt(or the scope's files).gofmt -lexits0even when it lists files (verified) — the list is the result. Same forgoimports -lwhen the project uses goimports without golangci-lint. Never-w.govulncheck:
govulncheck -format json [-tags …] ./... > build/iru-go-cq-vuln.json-format jsonexits0with findings (verified); text mode exits3when the code calls a vulnerable symbol. Any other non-zero exit, or an empty file → tooling failure (network, a package that doesn't build).- The stream holds
config,SBOM,progress,osv(database entries) andfindingobjects. Each finding'strace[0]says how deep it reaches: withfunction→ the code calls the vulnerable symbol; with onlypackage→ the package is imported but the vulnerable symbol isn't called; with onlymodule→ the module is merely required. The same OSV id appears at several levels; the parser keeps the deepest. - Always module-wide (it needs the whole call graph), even for a scoped run.
Step 3 — Parse every report into tool → rule id → issues
Pass scope=<comma-separated paths> (omit for an unscoped run) and one tool=report pair per tool that ran
(golangci, govet, gofmt, goimports, govulncheck):
python3 - scope=internal/greet,internal/cli golangci=build/iru-go-cq-golangci.json govet=build/iru-go-cq-vet.json govulncheck=build/iru-go-cq-vuln.json <<'PY'
import json
import os
import re
import sys
from collections import Counter, defaultdict
cwd = os.path.realpath(os.getcwd())
CODED = {"revive", "gosec", "staticcheck", "govet", "gocritic"} # Text starts with "<rule>: "
def rel(path):
p = os.path.realpath(path) if os.path.isabs(path) else path
return os.path.relpath(p, cwd) if os.path.isabs(p) else p
def objects(text): # concatenated / pretty-printed JSON values, noise lines skipped
dec, i = json.JSONDecoder(), 0
while i < len(text):
j = text.find("{", i)
if j < 0:
return
try:
obj, i = dec.raw_decode(text, j)
except ValueError:
i = j + 1
continue
yield obj
def golangci(text): # golangci-lint v2 --output.json.path
for d in (json.loads(text or "{}").get("Issues") or []):
linter, msg = d["FromLinter"], d["Text"]
m = re.match(r"^([A-Za-z][\w-]*): (.*)$", msg, re.S)
rule = f"{linter}:{m[1]}" if linter in CODED and m else linter
lines = [ln for ln in (m[2] if linter in CODED and m else msg).splitlines() if ln.strip()] or [msg]
yield rel(d["Pos"]["Filename"]), d["Pos"]["Line"], rule, lines[-1] if linter == "typecheck" else lines[0]
def govet(text): # go vet -json: {"<pkg>": {"<analyzer>": [{"posn": "file:l:c", "message"}]}}
for obj in objects(text):
for analyzers in obj.values():
for analyzer, diags in analyzers.items():
for d in diags if isinstance(diags, list) else []:
f, line = d["posn"].rsplit(":", 2)[:2]
yield rel(f), int(line), f"govet:{analyzer}", d["message"]
def gofmt(text): # gofmt -l / goimports -l: one path per line
for line in text.splitlines():
if line.strip().endswith(".go"):
yield rel(line.strip()), 0, "gofmt", "File is not gofmt-formatted"
def goimports(text):
for f, line, _, _ in gofmt(text):
yield f, line, "goimports", "Imports are not goimports-formatted"
def govulncheck(text): # govulncheck -format json: one finding per trace level; keep the deepest
best = {}
for obj in objects(text):
f = obj.get("finding")
if not f:
continue
top = f["trace"][0]
level = 2 if top.get("function") else 1 if top.get("package") else 0
pos = top.get("position") or {}
cur = best.get(f["osv"])
if cur is None or level > cur[0]:
where = top.get("module", "") + "@" + top.get("version", "")
caller = next(((fr.get("position") or {}) for fr in reversed(f["trace"])
if (fr.get("position") or {}).get("filename")), pos)
best[f["osv"]] = (level, where, f.get("fixed_version") or "none", caller)
for osv, (level, where, fixed, caller) in sorted(best.items()):
kind = ("called", "imported only", "required only")[2 - level]
yield (rel(caller.get("filename", "go.mod")) if level == 2 else "go.mod", caller.get("line", 0) if level == 2 else 0,
f"govulncheck:{osv}", f"{where} ({kind}; fixed in {fixed})")
PARSERS = {"golangci": golangci, "govet": govet, "gofmt": gofmt, "goimports": goimports, "govulncheck": govulncheck}
args = dict(a.split("=", 1) for a in sys.argv[1:])
scope = [s.rstrip("/") for s in args.pop("scope", "").split(",") if s]
for tool, path in args.items():
issues = [i for i in PARSERS[tool](open(path, encoding="utf-8", errors="replace").read())
if not scope or tool == "govulncheck" or any(i[0] == s or i[0].startswith(s + "/") for s in scope)]
by_rule = Counter(i[2] for i in issues)
print(f"{tool}: {len(issues)} issue(s)")
files = defaultdict(list)
for f, line, rule, msg in issues:
files[rule].append(f"{f}:{line} — {msg}")
for rule, n in by_rule.most_common():
print(f" {rule}: {n}")
for item in files[rule][:20]:
print(f" {item}")
if n > 20:
print(f" (+{n - 20} more)")
PY
Rule ids: linters whose messages carry their own rule code get <linter>:<rule> — revive (revive:exported,
revive:package-comments, revive:var-naming), gosec (gosec:G204, gosec:G304), staticcheck (which in v2 also
holds the former gosimple/stylecheck checks: staticcheck:SA1019, staticcheck:S1000, staticcheck:ST1003,
staticcheck:QF1001), govet (govet:printf, govet:inline), gocritic (gocritic:ifElseChain). Every other linter is
its own rule id (errcheck, unused, ineffassign, errorlint, godot, typecheck) and so is every formatter
(gofmt, goimports, gofumpt, gci, golines — one issue per file). Standalone go vet findings are
govet:<analyzer> in the separate govet tool bucket; govulncheck's are govulncheck:<GO-ID>. Paths come out
project-relative; the per-rule list is capped at 20 entries with "(+N more)".
Step 4 — Classify, diff against a baseline if given, and report
Bucket every issue by tool, then rule id. Never merge buckets across tools even when they describe the same
finding (golangci-lint's govet:printf and standalone go vet's govet:printf stay separate). Call out families a
caller hands off elsewhere: typecheck first (code doesn't compile — everything else on that package is
incomplete), gosec:* and govulncheck:* called (security — list early; imported/required-only
vulnerabilities are informational: "upgrade <module> to <fixed> when convenient"), revive:exported/
revive:package-comments/godot (doc comments — fixed by iru-go-godoc), and the formatters (fixed by running
the formatter, a follow-up the user drives).
Report: an overall total across all tools first, then per tool: whether it ran or was skipped (and why), the
config and version in force (e.g. "golangci-lint 2.15.0, .golangci.yml v2, default standard + revive, gosec,
errorlint, godot; formatters gofmt, goimports; exclusion presets std-error-handling", "govulncheck 1.9.0, db
vuln.go.dev"), its total, and one line per rule-id bucket with its count — plus the file:line — message list when the
scope is smaller than the whole module, or on request. Tool failures (golangci-lint exit 3, a v1 config, go vet on a
package that doesn't build, govulncheck without network) get their own line with the first error line, never
"0 issues". Never paste the raw JSON reports.
Baseline diff — when the prompt supplies a baseline: (the contract iru-go-code-one-task-group uses for this
skill): report only issues that are new since the baseline — a rule id whose count increased, a rule id that didn't
exist before, or a new file + rule entry when the baseline was itemized (match on tool + rule id + file, not on line
numbers or message text, which shift). A rule id whose count fell or stayed the same is not a regression and is
omitted from the diff (it still appears in the plain counts). A tool that wasn't run in the baseline (unwired then,
newly wired since) → treat all its current issues as new and say so. govulncheck findings can appear without any code
change (a new advisory) — flag a new govulncheck:* id as "new advisory or new dependency", not as a code
regression. This is separate from the project's own suppressions (//nolint:<linter> // reason, exclusions.rules),
which golangci-lint already applied.
Do not fix any issue, add //nolint, extend exclusions, run a formatter in write mode, upgrade a dependency, or
modify any configuration — those are follow-ups the user (or a coding skill) drives explicitly.
Verification notes
Verified with Go 1.27.2, golangci-lint 2.15.0 (built with go1.27.0), govulncheck 1.9.0, in
$TMPDIR/iru-verify/cli/go-gates/demo (a throwaway Cobra CLI module outside this repository) against deliberately bad
code (unchecked cmd.Run(), exec.Command with a variable, strings.Title, a mis-grouped import block, an
undocumented exported function, a missing package comment, an unused function, a wrong printf verb, a comment without
a final period, golang.org/x/text@v0.3.5 with language.Parse called):
- A
version: "2"config (linters.default: standard, enable revive/gosec/godot/errorlint, formatters gofmt/goimports) passedgolangci-lint config verify.golangci-lint run --output.json.path=… --show-stats=false --max-issues-per-linter=0 --max-same-issues=0 ./...exited1; the parser bucketederrcheck,errorlint,godot,gofmt,goimports,gosec:G204,govet:printf,revive:exported,revive:package-comments,staticcheck:SA1019,unused;--uniq-by-line=falseraised the count from 11 to 12. Withexclusions.presets: [comments, …]the two revive findings disappeared. - A v1 config → exit
3,can't load config: unsupported version of the configuration: "". An undefined identifier → exit1with onetypecheckissue.--issues-exit-code=0→ exit0.-c ../cfg.ymlwith a relative--output.json.pathwrote the report next to the config and issue paths relative to it;$PWD/…+--path-mode=absfixed both. go vet -json ./...exited0and printed{}per clean package plus{"…/internal/greet": {"printf": [{"posn": "…/vet.go:6:41", …}]}}on stdout;go vet ./...exited1.gofmt -llisted the mis-formatted file and exited0;golangci-lint fmt --diffexited1with a diff.govulncheck -format json ./...exited0with 7findingobjects for 4 OSV ids; the parser reportedGO-2021-0113as called atinternal/lang/lang.go:8(fixed in v0.3.7),GO-2022-1059imported only, two required only; text mode exited3.- Still unverified:
gofumpt/gci/golinesformatter ids end to end, golangci-lint's--new-from-revmode (not used here — the baseline diff covers it), govulncheck with-db file://offline, and Windows paths.
Sources
- golangci-lint docs (golangci-lint.run): configuration file v2 (
version: "2",linters.default,exclusions.presets,formatters),runcommand flags (--output.json.path,--path-mode,--max-issues-per-linter), migration guide (v1 → v2,golangci-lint migrate), linters reference (revive rules, gosec G-codes, staticcheck SA/S/ST/QF codes) - go.dev:
go doc cmd/vet(-json),go doc cmd/gofmt; go.dev/doc/security/vuln and pkg.go.dev/golang.org/x/vuln/cmd/govulncheck (-format json, exit codes, call-graph precision) - irurueta docs: ai/cli-for-agents/security.adoc (dependency auditing, never build shell strings — what gosec G204 flags)