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.
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.
| Hace | No hace |
|---|---|
| Escribir .golangci.yml, .golangci-fast.yml y .revive.toml a partir de una config compartida más un pequeño overlay | Dejar 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ño | Reemplazar 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:
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 lintersvlint 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:
[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 archivo | Efecto |
|---|---|
| -layout, -errstring, ... | Ejecutan solo los analizadores nombrados; -clockseam=false ejecuta todos menos uno |
| -tags integration | Analiza 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.yml | El 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
vlint es un único binario (cmd/vlint) sobre cuatro paquetes internos, el generador de golangci y un paquete por analizador bajo 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/: 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
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.
| Nivel | Cuándo | Comando | Ejecuta |
|---|---|---|---|
| fast | pre-commit | vlint fast [-fix] <files> | goimports sobre archivos staged, luego revive (solo AST) sobre sus paquetes, informando solo las líneas cambiadas desde HEAD |
| changed | pre-push | vlint 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 |
| full | bajo demanda | vlint ./... y golangci-lint run ./... | Todo, con .golangci.yml |
- 1Comprobar derivavlint golangci -check regenera las tres configs en memoria y falla cuando una difiere del archivo versionado.
- 2Ejecutar analizadoresvlint ./... ejecuta los analizadores sobre cada paquete, incluidos los archivos de test donde una regla los cubre.
- 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
| Analizador | Informa | Corrección |
|---|---|---|
| layout | Una carpeta fuera del layout, o un import contra las capas | Mover el paquete; invertir la dependencia mediante un port |
| clockseam | time.Now, time.Since, time.Until fuera de la raíz de composición | Inyectar un port de reloj |
| envroot | os.Getenv, os.LookupEnv, os.Environ fuera de la raíz de composición | Leer la configuración una vez en app/ y pasar los valores |
| errstring | err.Error() comparado con ==, !=, switch o un matcher de strings, fuera de tests | Un sentinel con errors.Is, o un error tipado con errors.As |
| noskipenv | Un test que se omite en silencio | t.Fatal cuando falta el entorno; omitir solo bajo testing.Short(), una variable de exclusión con token SKIP, o runtime.GOOS/GOARCH |
| doccomment | Símbolo exportado sin doc comment, doc de más de dos líneas, doc en un símbolo no exportado, cualquier otro comentario | Nombrar las cosas para que el código se lea sin comentarios; dos líneas en símbolos exportados |
| adrref | Un 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 .proto | Describir 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.
| Carpeta | Función | Puede importar del módulo |
|---|---|---|
| app/ | Raíz de composición: configuración, cableado, el reloj real | Cualquier cosa; solo cmd/ y los paquetes main la importan |
| cmd/<binary>/ | Mains finos y generadores | Cualquier cosa; nada lo importa |
| port/ | Interfaces, tipos simples, errores sentinel, el tipo de error con código | port/, schema/, api/ |
| core/ | Reglas de dominio puras, sin I/O | core/, port/, schema/ |
| service/ | Operaciones sobre core y ports; no conoce ningún transporte | Cualquier cosa salvo app/ y cmd/ |
| schema/, api/ | Datos de contrato y tipos generados | Su propio subárbol (api/ puede usar schema/) |
| store/, server/, internal/<helper>/ | Adaptadores (una carpeta por driver) y helpers privados | Cualquier 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.
vlint -baseline lint/vlint-baseline.txt -write ./... # record today's findings
vlint -baseline lint/vlint-baseline.txt ./... # in mise run checkCada 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ón | Elegido | Descartado | Por qué |
|---|---|---|---|
| Cómo obtiene las reglas un repositorio | Binario vlint fijado mediante mise.toml o go run | Una dependencia en cada go.mod | No se añade nada a go.mod; cada máquina ejecuta las mismas reglas |
| Propiedad de la config | Generada desde shared.yml más un overlay limitado a tres claves | Config libre por repositorio | Los repositorios no pueden activar linters extra ni relajar ajustes compartidos |
| Conflictos del overlay | Cualquier otra clave se rechaza; una regla depguard no puede reutilizar el nombre de una regla compartida | Reemplazo silencioso | Mantiene autoritativas las reglas compartidas |
| Autofix | Solo errorlint y formateadores | --fix amplio | Las correcciones riesgosas quedan manuales; ejecuta los tests tras %v a %w |
| Clave del baseline | Archivo, analizador, hash de línea, mensaje | Números de línea | Editar otras partes de un archivo no lo altera |
| Velocidad | Tres niveles con un preset más ligero | Una ejecución completa en cada commit | El 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
- README.mdReglas, niveles, layout, configuración y notas de seguridad
- cmd/vlint/main.goPunto de entrada: ejecución de analizadores, subcomandos golangci y fix
- cmd/vlint/changed.goEl nivel changed
- cmd/vlint/fast.goEl nivel fast: goimports y revive
- golangci/golangci.goGeneración de config, overlay, comprobación de deriva
- golangci/shared.ymlLa config compartida de golangci-lint
- golangci/revive.tomlLa config compartida de revive
- internal/driver/driver.goCarga de paquetes y ejecución de analizadores
- internal/baseline/baseline.goLectura, escritura y filtrado del baseline
- internal/changed/changed.goDe archivos cambiados a paquetes y módulos
- passes/layoutEl analizador layout y su testdata
- mise.tomlTareas: lint-fast, lint, lint-full, test, check, semgrep
- lefthook.ymlCableado de pre-commit y pre-push