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.
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.
| Faz | Não faz |
|---|---|
| Escrever .golangci.yml, .golangci-fast.yml e .revive.toml a partir de uma config compartilhada mais um pequeno overlay | Deixar 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 design | Substituir 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:
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 lintersO 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:
[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 arquivo | Efeito |
|---|---|
| -layout, -errstring, ... | Rodam só os analisadores nomeados; -clockseam=false roda todos menos um |
| -tags integration | Analisa 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.yml | O 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
O vlint é um único binário (cmd/vlint) sobre quatro pacotes internos, o gerador do golangci e um pacote por analisador em passes/.
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
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ível | Quando | Comando | Roda |
|---|---|---|---|
| fast | pre-commit | vlint fast [-fix] <files> | goimports nos arquivos staged, depois revive (só AST) nos pacotes deles, reportando só linhas alteradas desde o HEAD |
| changed | pre-push | vlint 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 |
| full | sob demanda | vlint ./... e golangci-lint run ./... | Tudo, com .golangci.yml |
- 1Checar driftvlint golangci -check regenera as três configs em memória e falha quando uma difere do arquivo commitado.
- 2Rodar analisadoresvlint ./... roda os analisadores em todo pacote, incluindo arquivos de teste onde uma regra os cobre.
- 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
| Analisador | Reporta | Correção |
|---|---|---|
| layout | Uma pasta fora do layout, ou um import contra as camadas | Mover o pacote; inverter a dependência por um port |
| clockseam | time.Now, time.Since, time.Until fora da raiz de composição | Injetar um port de relógio |
| envroot | os.Getenv, os.LookupEnv, os.Environ fora da raiz de composição | Ler a configuração uma vez em app/ e passar os valores |
| errstring | err.Error() comparado com ==, !=, switch ou um matcher de strings, fora de testes | Um sentinel com errors.Is, ou um erro tipado com errors.As |
| noskipenv | Um teste que pula em silêncio | t.Fatal quando falta o ambiente; pular só sob testing.Short(), uma variável de opt-out com token SKIP, ou runtime.GOOS/GOARCH |
| doccomment | Símbolo exportado sem doc comment, doc com mais de duas linhas, doc em símbolo não exportado, qualquer outro comentário | Nomear as coisas para o código ser lido sem comentários; duas linhas em símbolos exportados |
| adrref | Um 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 .proto | Descrever 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.
| Pasta | Papel | Pode importar do módulo |
|---|---|---|
| app/ | Raiz de composição: configuração, wiring, o relógio real | Qualquer coisa; só cmd/ e pacotes main a importam |
| cmd/<binary>/ | Mains finos e geradores | Qualquer coisa; nada o importa |
| port/ | Interfaces, tipos simples, erros sentinel, o tipo de erro com código | port/, schema/, api/ |
| core/ | Regras de domínio puras, sem I/O | core/, port/, schema/ |
| service/ | Operações sobre core e ports; não conhece transporte | Qualquer coisa exceto app/ e cmd/ |
| schema/, api/ | Dados de contrato e tipos gerados | Sua própria subárvore (api/ pode usar schema/) |
| store/, server/, internal/<helper>/ | Adaptadores (uma pasta por driver) e helpers privados | Qualquer 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.
vlint -baseline lint/vlint-baseline.txt -write ./... # record today's findings
vlint -baseline lint/vlint-baseline.txt ./... # in mise run checkCada 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ão | Escolhido | Rejeitado | Por quê |
|---|---|---|---|
| Como um repositório recebe as regras | Binário vlint fixado via mise.toml ou go run | Uma dependência em cada go.mod | Nada é adicionado ao go.mod; toda máquina roda as mesmas regras |
| Propriedade da config | Gerada de shared.yml mais um overlay limitado a três chaves | Config livre por repositório | Repositórios não podem ativar linters extras nem afrouxar configurações compartilhadas |
| Conflitos do overlay | Qualquer outra chave é recusada; uma regra depguard não pode reusar o nome de uma regra compartilhada | Sobrescrita silenciosa | Mantém as regras compartilhadas como autoridade |
| Autofix | Só errorlint e formatadores | --fix amplo | Correções arriscadas continuam manuais; rode os testes após %v para %w |
| Chave do baseline | Arquivo, analisador, hash da linha, mensagem | Números de linha | Edições em outras partes do arquivo não o perturbam |
| Velocidade | Três níveis com um preset mais leve | Uma execução completa a cada commit | O 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
- README.mdRegras, níveis, layout, configuração e notas de segurança
- cmd/vlint/main.goPonto de entrada: execução de analisadores, subcomandos golangci e fix
- cmd/vlint/changed.goO nível changed
- cmd/vlint/fast.goO nível fast: goimports e revive
- golangci/golangci.goGeração de config, overlay, checagem de drift
- golangci/shared.ymlA config compartilhada do golangci-lint
- golangci/revive.tomlA config compartilhada do revive
- internal/driver/driver.goCarregamento de pacotes e execução de analisadores
- internal/baseline/baseline.goLeitura, escrita e filtro do baseline
- internal/changed/changed.goDe arquivos alterados para pacotes e módulos
- passes/layoutO analisador layout e seu testdata
- mise.tomlTarefas: lint-fast, lint, lint-full, test, check, semgrep
- lefthook.ymlWiring de pre-commit e pre-push