CI: matriz de versiones, linter y formateador

Una suite que solo corre en tu máquina prueba una cosa: que tu máquina funciona. El valor real aparece cuando se ejecuta en un entorno que no controlas, sobre varias versiones del editor y ante cada propuesta de cambio, porque entonces deja de ser una comprobación y pasa a ser un contrato: esto es lo que mi plugin promete, en estas versiones, y aquí está la prueba automática de que lo cumple. A eso se le añade una segunda capa que atrapa una clase de defectos distinta y más barata todavía —variables globales sin declarar, argumentos que sobran, funciones inexistentes— y una tercera que elimina de raíz una categoría entera de discusiones: el formato.

La matriz: una promesa, no una lista

Elegir versiones parece administrativo y es la decisión de producto más importante del capítulo, porque cada entrada de la matriz es una promesa que tendrás que sostener durante años. Tres columnas cubren casi todos los casos con proporciones muy distintas de coste y beneficio.

La versión estable es innegociable: es la que usa la mayoría y un fallo ahí es un fallo real. La versión mínima soportada es la que declaras en tu documentación, y si no la pruebas no la soportas, solo lo esperas; el error más frecuente de todo el ecosistema es usar en el código una función incorporada en una versión posterior a la que se anuncia como mínima. La versión de desarrollo es distinta en naturaleza: sirve como aviso temprano de que una API va a cambiar, y por eso no debe bloquear la fusión de nada.

strategy:
  fail-fast: false          # que un fallo no cancele las demas: quieres el cuadro completo
  matrix:
    neovim: [v0.9.5, stable, nightly]
    include:
      - neovim: nightly
        experimental: true

El flujo de trabajo

La estructura mínima que funciona tiene cuatro pasos: obtener el código, instalar el editor en la versión de la matriz, colocar las dependencias de prueba, y ejecutar la suite en modo headless propagando el código de salida.

name: tests
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    timeout-minutes: 10                    # sin esto, un proceso colgado consume la cuota
    strategy:
      fail-fast: false
      matrix:
        neovim: [v0.9.5, stable, nightly]
    steps:
      - uses: actions/checkout@v4
      - uses: rhysd/action-setup-vim@v1
        with: { neovim: true, version: "${{ matrix.neovim }}" }

      - uses: actions/cache@v4
        with:
          path: .tests/site
          key: deps-${{ runner.os }}-${{ hashFiles('tests/minimal_init.lua') }}

      - name: Instalar plenary
        run: |
          mkdir -p .tests/site/pack/deps/start
          test -d .tests/site/pack/deps/start/plenary.nvim || git clone --depth 1 \
            https://github.com/nvim-lua/plenary.nvim .tests/site/pack/deps/start/plenary.nvim

      - name: Ejecutar la suite
        env:
          XDG_DATA_HOME: ${{ github.workspace }}/.tests/data
          XDG_STATE_HOME: ${{ github.workspace }}/.tests/state
        run: |
          nvim --headless -u tests/minimal_init.lua \
            -c "PlenaryBustedDirectory tests/ { minimal_init = 'tests/minimal_init.lua' }"

Dos detalles deciden si esto es fiable o si te dará disgustos. El primero es el tiempo máximo del trabajo: sin él, un proceso sin interfaz que no termina consume la cuota de la organización durante horas antes de rendirse. El segundo es el código de salida: el ejecutor de plenary sale con un valor distinto de cero cuando algún caso falla, y ese valor es lo único que el sistema mira; si envuelves la invocación en una tubería o en un guion que no lo propaga, tendrás una suite que informa fallos en verde, que es peor que no tener suite.

flowchart TD
A[Propuesta de cambio] --> B[Formato con stylua en modo comprobacion]
B --> C[Analisis estatico con selene o luacheck]
C --> D[Suite sobre la matriz de versiones]
D --> E[Version minima soportada]
D --> F[Version estable]
D --> G[Version de desarrollo tolerante a fallo]
E --> H[Fusion permitida]
F --> H
style B fill:#89b4fa,color:#11111b
style G fill:#f9e2af,color:#11111b
style H fill:#a6e3a1,color:#11111b

Análisis estático y formato

El análisis estático de Lua tiene una particularidad en este dominio: la tabla vim es una global que ninguna herramienta conoce de antemano, así que sin configurarla obtendrás cientos de avisos inútiles sobre una variable no definida y acabarás desactivando la herramienta entera.

Hay dos linters vigentes. luacheck es el veterano, escrito en Lua, exhaustivo y algo lento. selene está escrito en Rust, es mucho más rápido y describe las bibliotecas estándar en archivos declarativos, entre ellos uno específico para Neovim.

# selene.toml
std = "luajit+neovim"

[rules]
mixed_table = "warn"
unused_variable = "warn"

-- .luacheckrc: la alternativa clasica, con la tabla vim declarada a mano
std = "luajit"
globals = { "vim" }
ignore = { "212/self", "631" }        -- argumento self sin usar, linea demasiado larga

El formateador es una decisión distinta y más tajante. stylua reformatea el código según una configuración corta y en integración continua se ejecuta en modo comprobación, de modo que falla si algún archivo no está exactamente como el formateador lo escribiría. Eso convierte el estilo en algo que nadie discute nunca más, porque deja de ser una opinión y pasa a ser una propiedad verificable.

  lint:                                     # trabajo aparte: no se repite por cada version
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: JohnnyMorganz/stylua-action@v4
        with: { version: latest, args: "--check lua/ tests/" }
      - run: |
          curl -sL https://github.com/Kampfkarren/selene/releases/latest/download/selene-linux.zip \
            -o selene.zip && unzip -q selene.zip && chmod +x selene && ./selene lua/

Queda una tercera capa que poca gente añade y que atrapa los errores más caros: el servidor de lenguaje de Lua puede ejecutarse como comprobador en lote y, alimentado con las anotaciones de tipo de la API de Neovim, detecta llamadas con el número de argumentos equivocado, campos inexistentes en tablas y valores de retorno mal usados. Es análisis de tipos sobre un lenguaje dinámico, y encuentra en segundos lo que una suite descubriría solo si ese camino concreto tuviera un caso escrito.

Ordenar para fallar pronto

El orden de las etapas no es cosmético: determina cuánto tarda alguien en enterarse de que se equivocó. Lo barato y universal va primero —formato y análisis estático tardan segundos y cubren todo el código—, y lo caro y parcial va después. Además, separar el análisis en un trabajo propio evita repetirlo una vez por cada entrada de la matriz, que es un desperdicio silencioso muy común.

Tres refinamientos elevan un flujo correcto a uno agradable de usar. Ejecutar el formateador y el linter también antes de confirmar, mediante ganchos locales, para que el rojo remoto sea excepcional en lugar de rutinario. Publicar la salida de los fallos como un resumen legible en la propia propuesta de cambio, en vez de obligar a desplegar registros. Y cancelar automáticamente las ejecuciones anteriores de la misma rama cuando llega un cambio nuevo, porque nadie necesita el resultado de un estado que ya fue reemplazado.

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true