go-lint

Um kit de lint para repositórios Go: uma config do golangci-lint gerada, uma checagem de drift para ela e sete analisadores para o que os linters padrão não enxergam.

Goversatile.shcódigo abertoLinguagem Go 1.27Licença MITBinário vlintAnalisadores 7 (go/analysis)github.com/versatile-sh/go-lint

Visão geral

O go-lint é um módulo Go versionado com um único comando, vlint. Um repositório o fixa no mise.toml (ou o roda com go run numa versão fixa), então nada é adicionado ao seu go.mod e toda máquina roda as mesmas regras.

Ele existe para que as mesmas regras de lint, a mesma config e as mesmas checagens valham para todo repositório Go que segue o padrão de engenharia da Versatile. Não substitui o golangci-lint: gera a config dessa ferramenta e roda ao lado dela.

FazNão faz
Escrever .golangci.yml, .golangci-fast.yml e .revive.toml a partir de uma config compartilhada mais um pequeno overlayDeixar um repositório ativar linters extras ou afrouxar configurações compartilhadas
Rodar os linters em três níveis (rápido em arquivos staged, alterados desde o merge base, completo)Aplicar autofixes arriscados: só errorlint e os formatadores
Rodar sete analisadores go/analysis: layout, clock, ambiente, erros, testes, comentários, referências a registros de designSubstituir o golangci-lint

Primeiros passos

Pré-requisitos: Go 1.27, golangci-lint 2.15 e revive 1.17. A partir da raiz de um módulo Go:

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

O vlint imprime uma linha por achado como file:line:col: message e sai com 3 quando há algum, e com 1 quando um pacote falha ao carregar ou ao checar tipos. Fixe as ferramentas e ligue os níveis no 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" }]

Com o lefthook, o pre-commit roda mise run lint-fast {staged_files} e o pre-push roda mise run lint.

Flag ou arquivoEfeito
-layout, -errstring, ...Rodam só os analisadores nomeados; -clockseam=false roda todos menos um
-tags integrationAnalisa arquivos atrás de build tags (separadas por vírgula, passadas ao carregamento de pacotes)
-baseline f [-write]Falha só com achados ausentes do arquivo baseline; -write registra os achados de hoje
lint/golangci.local.ymlO overlay do repositório; aceita só exclusões, depguard e issues.new-from-merge-base
vlint fix ./...golangci-lint --fix limitado ao errorlint, e depois golangci-lint fmt

Arquitetura

overlayshared.ymlrepo Arepo B3 sheets per repo
Um template compartilhado mais um pequeno overlay é carimbado nas mesmas três folhas de config em todo repositório.

O vlint é um único binário (cmd/vlint) sobre quatro pacotes internos, o gerador do golangci e um pacote por analisador em 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/: embute shared.yml e revive.toml, mescla o overlay do repositório, escreve os três arquivos de config e reporta ErrDrift quando um arquivo commitado difere.
  • internal/driver: carrega pacotes e roda os analisadores selecionados, produzindo valores Finding.
  • internal/baseline: lê e escreve o arquivo baseline e o subtrai dos achados.
  • internal/changed: mapeia arquivos alterados para pacotes e módulos para o nível changed.
  • internal/module: encontra raízes de módulo e seus arquivos go.mod.

O gate

templatecommittedErrDrift
A checagem de drift regenera cada folha e a compara com a commitada; uma diferença falha com ErrDrift.

As mesmas regras rodam em três profundidades, porque os linters pesados e uma execução no repositório inteiro são lentos demais para cada commit.

NívelQuandoComandoRoda
fastpre-commitvlint fast [-fix] <files>goimports nos arquivos staged, depois revive (só AST) nos pacotes deles, reportando só linhas alteradas desde o HEAD
changedpre-pushvlint changed [-base origin/main] [-tags t] [-baseline f]analisadores do vlint e golangci-lint -c .golangci-fast.yml --new-from-merge-base nos pacotes alterados desde o merge base
fullsob demandavlint ./... e golangci-lint run ./...Tudo, com .golangci.yml
  1. 1Checar driftvlint golangci -check regenera as três configs em memória e falha quando uma difere do arquivo commitado.
  2. 2Rodar analisadoresvlint ./... roda os analisadores em todo pacote, incluindo arquivos de teste onde uma regra os cobre.
  3. 3Rodar o golangci-lintgolangci-lint run ./... roda os linters padrão com a config gerada.

vlint changed conta arquivos .go commitados, staged, unstaged e não rastreados (ignorando testdata, vendor e pastas iniciadas por ponto ou sublinhado), mapeia cada um para seu pacote e o go.mod mais próximo, e analisa o módulo inteiro quando go.mod, go.sum ou uma config de lint mudou. -list imprime os pacotes e não roda nada.

Analisadores

.go7 analyzers
Todo pacote passa pelos sete analisadores; os achados caem na bandeja de rejeitados.
AnalisadorReportaCorreção
layoutUma pasta fora do layout, ou um import contra as camadasMover o pacote; inverter a dependência por um port
clockseamtime.Now, time.Since, time.Until fora da raiz de composiçãoInjetar um port de relógio
envrootos.Getenv, os.LookupEnv, os.Environ fora da raiz de composiçãoLer a configuração uma vez em app/ e passar os valores
errstringerr.Error() comparado com ==, !=, switch ou um matcher de strings, fora de testesUm sentinel com errors.Is, ou um erro tipado com errors.As
noskipenvUm teste que pula em silênciot.Fatal quando falta o ambiente; pular só sob testing.Short(), uma variável de opt-out com token SKIP, ou runtime.GOOS/GOARCH
doccommentSímbolo exportado sem doc comment, doc com mais de duas linhas, doc em símbolo não exportado, qualquer outro comentárioNomear as coisas para o código ser lido sem comentários; duas linhas em símbolos exportados
adrrefUm id de registro de design (ADR-12) ou caminho de pasta de registros num comentário ou string literal Go, ou num comentário de .protoDescrever o comportamento; manter os registros fora do repositório

Isenções: clockseam e envroot ignoram pacotes main, app/, cmd/, arquivos _test.go e pacotes test-kit cujo nome termina em test. doccomment permite diretivas (//go:, //nolint:, build tags), blocos Output de exemplos, arquivos gerados, comentários acima da cláusula package e docs de duas linhas em campos de struct e métodos de interface. noskipenv isenta o idioma de re-exec, um teste chamado *HelperProcess. adrref ignora arquivos Go gerados e lê todo arquivo .proto de cada módulo analisado, ignorando testdata, vendor, node_modules, pastas iniciadas por ponto ou sublinhado e módulos aninhados.

Cada analisador tem casos analysistest em passes/<analyzer>/testdata: cada regra tem um caso que precisa ser reportado e um caso que não pode.

Estrutura de pastas

O analisador layout impõe uma estrutura em camadas. Os caminhos são relativos à raiz do módulo Go.

PastaPapelPode importar do módulo
app/Raiz de composição: configuração, wiring, o relógio realQualquer coisa; só cmd/ e pacotes main a importam
cmd/<binary>/Mains finos e geradoresQualquer coisa; nada o importa
port/Interfaces, tipos simples, erros sentinel, o tipo de erro com códigoport/, schema/, api/
core/Regras de domínio puras, sem I/Ocore/, port/, schema/
service/Operações sobre core e ports; não conhece transporteQualquer coisa exceto app/ e cmd/
schema/, api/Dados de contrato e tipos geradosSua própria subárvore (api/ pode usar schema/)
store/, server/, internal/<helper>/Adaptadores (uma pasta por driver) e helpers privadosQualquer coisa exceto app/ e cmd/

Arquivos de teste podem importar qualquer coisa exceto cmd/. Nomes de pasta reportados na raiz ou sob internal/: domain, ports, application, adapters, adapter, bootstrap, infrastructure, infra, usecase, usecases, pkg, util, utils, common, helpers, shared, lib. As pastas de camada ficam na raiz do módulo, não sob internal/.

Gate de baseline

Um repositório que não consegue chegar a zero achados numa só mudança commita um baseline e falha apenas com achados novos.

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

Cada linha do baseline é o arquivo relativo ao módulo, o analisador, um hash da linha de código reportada (espaços colapsados) e a mensagem. Não há número de linha, então edições em outras partes do arquivo não o perturbam; editar a linha reportada torna o achado novo. Linhas idênticas repetidas contam um achado cada. A checagem imprime N new findings e sai com 3 quando N > 0; entradas que não ocorrem mais são listadas como fixed: sem falhar. Use as mesmas flags ao escrever e ao checar. Um pacote que falha ao carregar faz a execução falhar.

Para o golangci-lint o equivalente é issues.new-from-merge-base no overlay. Ele é baseado em diff: precisa do histórico do git e da ref localmente (faça fetch de origin/main num clone raso de CI) e não checa nada na própria branch base.

Decisões

DecisãoEscolhidoRejeitadoPor quê
Como um repositório recebe as regrasBinário vlint fixado via mise.toml ou go runUma dependência em cada go.modNada é adicionado ao go.mod; toda máquina roda as mesmas regras
Propriedade da configGerada de shared.yml mais um overlay limitado a três chavesConfig livre por repositórioRepositórios não podem ativar linters extras nem afrouxar configurações compartilhadas
Conflitos do overlayQualquer outra chave é recusada; uma regra depguard não pode reusar o nome de uma regra compartilhadaSobrescrita silenciosaMantém as regras compartilhadas como autoridade
AutofixSó errorlint e formatadores--fix amploCorreções arriscadas continuam manuais; rode os testes após %v para %w
Chave do baselineArquivo, analisador, hash da linha, mensagemNúmeros de linhaEdições em outras partes do arquivo não o perturbam
VelocidadeTrês níveis com um preset mais leveUma execução completa a cada commitO preset rápido tira gosec, contextcheck, sloglint, testifylint, que rodam só no nível completo

Limites conhecidos: arquivos atrás de uma build tag só são analisados quando a tag está definida; uma execução parcial não consegue listar entradas corrigidas do baseline em vlint changed; o gate do golangci baseado em diff não checa nada na branch base; a tabela de dependências do próprio repositório governa as bordas mais finas entre adaptadores.

Arquivos principais