go-lint

Un kit de lint para repositorios Go: una config de golangci-lint generada, una comprobación de deriva para ella y siete analizadores para lo que los linters estándar no ven.

Goversatile.shcódigo abiertoLenguaje Go 1.27Licencia MITBinario vlintAnalizadores 7 (go/analysis)github.com/versatile-sh/go-lint

Visión general

go-lint es un módulo Go versionado con un único comando, vlint. Un repositorio lo fija en mise.toml (o lo ejecuta con go run en una versión fija), así que no se añade nada a su go.mod y cada máquina ejecuta las mismas reglas.

Existe para que las mismas reglas de lint, la misma config y las mismas comprobaciones se apliquen a todo repositorio Go que siga el estándar de ingeniería de Versatile. No reemplaza a golangci-lint: genera la config de esa herramienta y corre a su lado.

HaceNo hace
Escribir .golangci.yml, .golangci-fast.yml y .revive.toml a partir de una config compartida más un pequeño overlayDejar que un repositorio active linters extra o relaje ajustes compartidos
Ejecutar los linters en tres niveles (rápido sobre archivos staged, cambiados desde el merge base, completo)Aplicar autofixes riesgosos: solo errorlint y los formateadores
Ejecutar siete analizadores go/analysis: layout, clock, entorno, errores, tests, comentarios, referencias a registros de diseñoReemplazar a golangci-lint

Puesta en marcha

Requisitos: Go 1.27, golangci-lint 2.15 y revive 1.17. Desde la raíz de un 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

vlint imprime una línea por hallazgo como file:line:col: message y termina con 3 cuando hay alguno, y con 1 cuando un paquete falla al cargar o al comprobar tipos. Fija las herramientas y conecta los niveles en 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" }]

Con lefthook, pre-commit ejecuta mise run lint-fast {staged_files} y pre-push ejecuta mise run lint.

Flag o archivoEfecto
-layout, -errstring, ...Ejecutan solo los analizadores nombrados; -clockseam=false ejecuta todos menos uno
-tags integrationAnaliza archivos tras build tags (separados por comas, pasados a la carga de paquetes)
-baseline f [-write]Falla solo con hallazgos ausentes del archivo baseline; -write registra los hallazgos de hoy
lint/golangci.local.ymlEl overlay del repositorio; acepta solo exclusiones, depguard e issues.new-from-merge-base
vlint fix ./...golangci-lint --fix limitado a errorlint, y luego golangci-lint fmt

Arquitectura

overlayshared.ymlrepo Arepo B3 sheets per repo
Una plantilla compartida más un pequeño overlay se estampa en las mismas tres hojas de config en cada repositorio.

vlint es un único binario (cmd/vlint) sobre cuatro paquetes internos, el generador de golangci y un paquete por analizador bajo 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/: embebe shared.yml y revive.toml, fusiona el overlay del repositorio, escribe los tres archivos de config e informa ErrDrift cuando un archivo versionado difiere.
  • internal/driver: carga paquetes y ejecuta los analizadores seleccionados, produciendo valores Finding.
  • internal/baseline: lee y escribe el archivo baseline y lo resta de los hallazgos.
  • internal/changed: mapea archivos cambiados a paquetes y módulos para el nivel changed.
  • internal/module: encuentra raíces de módulos y sus archivos go.mod.

La compuerta

templatecommittedErrDrift
La comprobación de deriva regenera cada hoja y la mide contra la versionada; una diferencia falla con ErrDrift.

Las mismas reglas corren en tres profundidades, porque los linters pesados y una ejecución sobre todo el repositorio son demasiado lentos para cada commit.

NivelCuándoComandoEjecuta
fastpre-commitvlint fast [-fix] <files>goimports sobre archivos staged, luego revive (solo AST) sobre sus paquetes, informando solo las líneas cambiadas desde HEAD
changedpre-pushvlint changed [-base origin/main] [-tags t] [-baseline f]analizadores de vlint y golangci-lint -c .golangci-fast.yml --new-from-merge-base sobre los paquetes cambiados desde el merge base
fullbajo demandavlint ./... y golangci-lint run ./...Todo, con .golangci.yml
  1. 1Comprobar derivavlint golangci -check regenera las tres configs en memoria y falla cuando una difiere del archivo versionado.
  2. 2Ejecutar analizadoresvlint ./... ejecuta los analizadores sobre cada paquete, incluidos los archivos de test donde una regla los cubre.
  3. 3Ejecutar golangci-lintgolangci-lint run ./... ejecuta los linters estándar con la config generada.

vlint changed cuenta los archivos .go con commit, staged, unstaged y no rastreados (omitiendo testdata, vendor y carpetas que empiezan con punto o guion bajo), mapea cada uno a su paquete y al go.mod más cercano, y analiza todo el módulo cuando cambió go.mod, go.sum o una config de lint. -list imprime los paquetes y no ejecuta nada.

Analizadores

.go7 analyzers
Cada paquete pasa por los siete analizadores; los hallazgos caen en la bandeja de rechazo.
AnalizadorInformaCorrección
layoutUna carpeta fuera del layout, o un import contra las capasMover el paquete; invertir la dependencia mediante un port
clockseamtime.Now, time.Since, time.Until fuera de la raíz de composiciónInyectar un port de reloj
envrootos.Getenv, os.LookupEnv, os.Environ fuera de la raíz de composiciónLeer la configuración una vez en app/ y pasar los valores
errstringerr.Error() comparado con ==, !=, switch o un matcher de strings, fuera de testsUn sentinel con errors.Is, o un error tipado con errors.As
noskipenvUn test que se omite en silenciot.Fatal cuando falta el entorno; omitir solo bajo testing.Short(), una variable de exclusión con token SKIP, o runtime.GOOS/GOARCH
doccommentSímbolo exportado sin doc comment, doc de más de dos líneas, doc en un símbolo no exportado, cualquier otro comentarioNombrar las cosas para que el código se lea sin comentarios; dos líneas en símbolos exportados
adrrefUn id de registro de diseño (ADR-12) o ruta de carpeta de registros en un comentario o string literal de Go, o un comentario de .protoDescribir el comportamiento; mantener los registros fuera del repositorio

Exenciones: clockseam y envroot omiten paquetes main, app/, cmd/, archivos _test.go y paquetes test-kit cuyo nombre termina en test. doccomment permite directivas (//go:, //nolint:, build tags), bloques Output de ejemplos, archivos generados, comentarios sobre la cláusula package y docs de dos líneas en campos de struct y métodos de interfaz. noskipenv exime el idioma de re-exec, un test llamado *HelperProcess. adrref omite archivos Go generados y lee todos los archivos .proto de cada módulo analizado, omitiendo testdata, vendor, node_modules, carpetas con punto o guion bajo y módulos anidados.

Cada analizador tiene casos analysistest en passes/<analyzer>/testdata: cada regla tiene un caso que debe informarse y un caso que no.

Estructura de carpetas

El analizador layout hace cumplir una estructura en capas. Las rutas son relativas a la raíz del módulo Go.

CarpetaFunciónPuede importar del módulo
app/Raíz de composición: configuración, cableado, el reloj realCualquier cosa; solo cmd/ y los paquetes main la importan
cmd/<binary>/Mains finos y generadoresCualquier cosa; nada lo importa
port/Interfaces, tipos simples, errores sentinel, el tipo de error con códigoport/, schema/, api/
core/Reglas de dominio puras, sin I/Ocore/, port/, schema/
service/Operaciones sobre core y ports; no conoce ningún transporteCualquier cosa salvo app/ y cmd/
schema/, api/Datos de contrato y tipos generadosSu propio subárbol (api/ puede usar schema/)
store/, server/, internal/<helper>/Adaptadores (una carpeta por driver) y helpers privadosCualquier cosa salvo app/ y cmd/

Los archivos de test pueden importar cualquier cosa excepto cmd/. Nombres de carpeta que se informan en la raíz o bajo internal/: domain, ports, application, adapters, adapter, bootstrap, infrastructure, infra, usecase, usecases, pkg, util, utils, common, helpers, shared, lib. Las carpetas de capa van en la raíz del módulo, no bajo internal/.

Compuerta baseline

Un repositorio que no puede llegar a cero hallazgos en un solo cambio versiona un baseline y falla solo con hallazgos nuevos.

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

Cada línea del baseline es el archivo relativo al módulo, el analizador, un hash de la línea de código informada (espacios colapsados) y el mensaje. No hay número de línea, así que editar otra parte de un archivo no lo altera; editar la línea informada hace nuevo su hallazgo. Las líneas idénticas repetidas cuentan un hallazgo cada una. La comprobación imprime N new findings y termina con 3 cuando N > 0; las entradas que ya no ocurren se listan como fixed: sin fallar. Usa los mismos flags al escribir y al comprobar. Un paquete que falla al cargar hace fallar la ejecución.

Para golangci-lint el equivalente es issues.new-from-merge-base en el overlay. Se basa en diff: necesita el historial de git y la ref en local (haz fetch de origin/main en un clon superficial de CI) y no comprueba nada en la propia rama base.

Decisiones

DecisiónElegidoDescartadoPor qué
Cómo obtiene las reglas un repositorioBinario vlint fijado mediante mise.toml o go runUna dependencia en cada go.modNo se añade nada a go.mod; cada máquina ejecuta las mismas reglas
Propiedad de la configGenerada desde shared.yml más un overlay limitado a tres clavesConfig libre por repositorioLos repositorios no pueden activar linters extra ni relajar ajustes compartidos
Conflictos del overlayCualquier otra clave se rechaza; una regla depguard no puede reutilizar el nombre de una regla compartidaReemplazo silenciosoMantiene autoritativas las reglas compartidas
AutofixSolo errorlint y formateadores--fix amplioLas correcciones riesgosas quedan manuales; ejecuta los tests tras %v a %w
Clave del baselineArchivo, analizador, hash de línea, mensajeNúmeros de líneaEditar otras partes de un archivo no lo altera
VelocidadTres niveles con un preset más ligeroUna ejecución completa en cada commitEl preset rápido omite gosec, contextcheck, sloglint, testifylint, que corren solo en el nivel completo

Límites conocidos: los archivos tras un build tag se analizan solo cuando el tag está definido; una ejecución parcial no puede listar entradas arregladas del baseline en vlint changed; la compuerta de golangci basada en diff no comprueba nada en la rama base; la tabla de dependencias del propio repositorio gobierna los bordes más finos entre adaptadores.

Archivos clave