go-lint

One lint kit for Go repositories: a generated golangci-lint config, a drift check for it, and seven analyzers for what stock linters cannot see.

Goversatile.shopen sourceLanguage Go 1.27License MITBinary vlintAnalyzers 7 (go/analysis)github.com/versatile-sh/go-lint

Overview

go-lint is a versioned Go module with one command, vlint. A repository pins it in mise.toml (or runs it with go run at a pinned version), so nothing is added to its go.mod and every machine runs the same rules.

It exists so that the same lint rules, the same config and the same checks apply to every Go repository that follows the Versatile engineering standard. It does not replace golangci-lint: it generates that tool's config and runs beside it.

It doesIt does not
Write .golangci.yml, .golangci-fast.yml and .revive.toml from one shared config plus a small overlayLet a repository enable extra linters or loosen shared settings
Run the linters in three tiers (fast on staged files, changed since the merge base, full)Apply risky autofixes: only errorlint and the formatters
Run seven go/analysis analyzers: layout, clock, environment, errors, tests, comments, design-record referencesReplace golangci-lint

Bootstrap

Prerequisites: Go 1.27, golangci-lint 2.15 and revive 1.17. From the root of a Go module:

sh
vlint golangci          # writes .golangci.yml, .golangci-fast.yml and .revive.toml
vlint ./...             # full tier: the analyzers on every package
golangci-lint run ./... # full tier: the stock linters

vlint prints one line per finding as file:line:col: message and exits 3 when there is any, 1 when a package fails to load or type-check. Pin the tools and wire the tiers in mise.toml:

toml
[tools]
go = "1.27.3"
"go:github.com/versatile-sh/go-lint/cmd/vlint" = "0.3.0"
"go:github.com/golangci/golangci-lint/v2/cmd/golangci-lint" = "2.15.0"
"go:github.com/mgechev/revive" = "1.17.1"

[tasks.lint-fast]
run = "vlint fast -fix"

[tasks.lint]
run = ["vlint golangci -check", "vlint changed"]

[tasks.lint-full]
run = ["vlint golangci -check", "vlint ./...", "golangci-lint run ./..."]

[tasks.check]
run = [{ task = "lint-full" }, { task = "test" }]

With lefthook, pre-commit runs mise run lint-fast {staged_files} and pre-push runs mise run lint.

Flag or fileEffect
-layout, -errstring, ...Run only the named analyzers; -clockseam=false runs all but one
-tags integrationAnalyze files behind build tags (comma-separated, passed to package loading)
-baseline f [-write]Fail only on findings absent from the baseline file; -write records today's findings
lint/golangci.local.ymlThe repository overlay; accepts exclusions, depguard and issues.new-from-merge-base only
vlint fix ./...golangci-lint --fix limited to errorlint, then golangci-lint fmt

Architecture

overlayshared.ymlrepo Arepo B3 sheets per repo
One shared template plus a small overlay is stamped into the same three config sheets in every repository.

vlint is a single binary (cmd/vlint) over four internal packages, the golangci generator and one package per analyzer under passes/.

text
mise run check
   |
   v
 vlint golangci -check --> golangci/ (shared.yml + revive.toml + overlay) --> drift?
   |
   v
 vlint ./...  --> internal/driver --> passes/{layout,clockseam,envroot,
   |                                         errstring,noskipenv,doccomment,adrref}
   |            \-> internal/baseline (optional "don't get worse" filter)
   v
 golangci-lint run ./...  (with the generated .golangci.yml)
  • golangci/: embeds shared.yml and revive.toml, merges the repository overlay, writes the three config files and reports ErrDrift when a committed file differs.
  • internal/driver: loads packages and runs the selected analyzers, producing Finding values.
  • internal/baseline: reads and writes the baseline file and subtracts it from the findings.
  • internal/changed: maps changed files to packages and modules for the changed tier.
  • internal/module: finds module roots and their go.mod files.

The gate

templatecommittedErrDrift
The drift check regenerates each sheet and measures it against the committed one; a mismatch fails with ErrDrift.

The same rules run at three depths, because the heavy linters and a whole-repository run are too slow for every commit.

TierWhenCommandRuns
fastpre-commitvlint fast [-fix] <files>goimports on staged files, then revive (AST only) on their packages, reporting only lines changed since HEAD
changedpre-pushvlint changed [-base origin/main] [-tags t] [-baseline f]vlint analyzers and golangci-lint -c .golangci-fast.yml --new-from-merge-base on packages changed since the merge base
fullon demandvlint ./... and golangci-lint run ./...Everything, with .golangci.yml
  1. 1Check driftvlint golangci -check regenerates the three configs in memory and fails when one differs from the committed file.
  2. 2Run analyzersvlint ./... runs the analyzers over every package, test files included where a rule covers them.
  3. 3Run golangci-lintgolangci-lint run ./... runs the stock linters with the generated config.

vlint changed counts committed, staged, unstaged and untracked .go files (skipping testdata, vendor and dot or underscore folders), maps each to its package and nearest go.mod, and lints the whole module when go.mod, go.sum or a lint config changed. -list prints the packages and runs nothing.

Analyzers

.go7 analyzers
Every package passes through the seven analyzers; findings drop into the reject tray.
AnalyzerReportsFix
layoutA folder outside the layout, or an import against the layersMove the package; invert the dependency through a port
clockseamtime.Now, time.Since, time.Until outside the composition rootInject a clock port
envrootos.Getenv, os.LookupEnv, os.Environ outside the composition rootRead configuration once in app/ and pass values in
errstringerr.Error() compared with ==, !=, switch or a strings matcher, outside testsA sentinel with errors.Is, or a typed error with errors.As
noskipenvA test that skips silentlyt.Fatal when the environment is missing; skip only under testing.Short(), a SKIP-token opt-out variable, or runtime.GOOS/GOARCH
doccommentExported symbol without a doc comment, doc over two lines, doc on an unexported symbol, any other commentName things so the code reads without comments; two lines on exported symbols
adrrefA design-record id (ADR-12) or record folder path in a Go comment or string literal, or a .proto commentState the behaviour; keep records outside the repository

Exemptions: clockseam and envroot skip main packages, app/, cmd/, _test.go files and test-kit packages whose name ends in test. doccomment allows directives (//go:, //nolint:, build tags), example Output blocks, generated files, comments above the package clause, and two-line docs on struct fields and interface methods. noskipenv exempts the re-exec idiom, a test named *HelperProcess. adrref skips generated Go files and reads every .proto file of each analyzed module instead, skipping testdata, vendor, node_modules, dot and underscore folders and nested modules.

Each analyzer has analysistest cases in passes/<analyzer>/testdata: every rule has a case that must be reported and a case that must not.

Folder layout

The layout analyzer enforces one layered structure. Paths are relative to the Go module root.

FolderRoleMay import from the module
app/Composition root: configuration, wiring, the real clockAnything; only cmd/ and main packages import it
cmd/<binary>/Thin mains and generatorsAnything; nothing imports it
port/Interfaces, plain types, sentinel errors, the coded error typeport/, schema/, api/
core/Pure domain rules, no I/Ocore/, port/, schema/
service/Operations over core and ports; knows no transportAnything but app/ and cmd/
schema/, api/Contract data and generated typesTheir own subtree (api/ may use schema/)
store/, server/, internal/<helper>/Adapters (one folder per driver) and private helpersAnything but app/ and cmd/

Test files may import anything except cmd/. Reported folder names at the root or under internal/: domain, ports, application, adapters, adapter, bootstrap, infrastructure, infra, usecase, usecases, pkg, util, utils, common, helpers, shared, lib. Layer folders sit at the module root, not under internal/.

Baseline gate

A repository that cannot reach zero findings in one change commits a baseline and fails only on new findings.

sh
vlint -baseline lint/vlint-baseline.txt -write ./...   # record today's findings
vlint -baseline lint/vlint-baseline.txt ./...          # in mise run check

Each baseline line is the module-relative file, the analyzer, a hash of the reported source line (whitespace collapsed) and the message. There is no line number, so edits elsewhere in a file do not disturb it; editing the reported line makes its finding new. Repeated identical lines count one finding each. The check prints N new findings and exits 3 when N > 0; entries that no longer occur are listed as fixed: without failing. Use the same flags when writing and checking. A package that fails to load fails the run.

For golangci-lint the equivalent is issues.new-from-merge-base in the overlay. It is diff-based: it needs the git history and the ref locally (fetch origin/main in a shallow CI clone) and checks nothing on the base branch itself.

Decisions

DecisionChosenRejectedWhy
How a repository gets the rulesPinned vlint binary via mise.toml or go runA dependency in each go.modNothing added to go.mod; every machine runs the same rules
Config ownershipGenerated from shared.yml plus an overlay limited to three keysPer-repository free-form configRepositories cannot enable extra linters or loosen shared settings
Overlay conflictsAny other key refused; a depguard rule may not reuse a shared rule's nameSilent overrideKeeps the shared rules authoritative
Autofixerrorlint and formatters onlyBroad --fixRisky fixes stay manual; run tests after %v to %w
Baseline keyFile, analyzer, line hash, messageLine numbersEdits elsewhere in a file do not disturb it
SpeedThree tiers with a lighter presetOne full run on every commitFast preset drops gosec, contextcheck, sloglint, testifylint, which run in the full tier only

Known limits: files behind a build tag are analyzed only when the tag is set; a partial run cannot list fixed baseline entries for vlint changed; the diff-based golangci gate checks nothing on the base branch; the repository's own dependency table governs finer edges between adapters.

Key files