Depurar autocomandos: listar, entender por qué no dispara y el orden

Los autocomandos fallan de la peor manera posible: en silencio. No hay excepción, no hay mensaje, simplemente el efecto que esperabas no aparece, y no existe un punto de interrupción donde detenerse porque el problema es que nadie te llamó. Depurar aquí no consiste en leer un error sino en interrogar a la tabla de suscripciones y reconstruir por qué el emparejamiento no ocurrió. Con las herramientas correctas es un proceso de cinco minutos; sin ellas, una tarde entera de conjeturas.

Listar: el comando autocmd y su versión programable

El comando :autocmd sin argumentos vuelca la tabla completa, lo cual es inútil por volumen. Su valor está en los filtros, que se aplican en el orden grupo, evento y patrón, cualquiera de ellos omitible.

:autocmd BufWritePre              " todo lo que escucha ese evento
:autocmd dios_formato             " todo lo del grupo, sea cual sea el evento
:autocmd dios_formato BufWritePre " la interseccion de ambos
:autocmd FileType lua             " el evento con ese patron concreto
:verbose autocmd BufWritePre      " ademas, desde que archivo se definio cada uno

:verbose autocmd es la herramienta decisiva y la más infrautilizada. Añade a cada entrada la línea que indica desde qué archivo y qué línea se registró, lo cual convierte “hay algo que formatea mi buffer y no sé qué” en una respuesta inmediata. Cuando el culpable es un plugin de terceros, esto es lo único que te dice cuál.

Para trabajo serio, sin embargo, la API devuelve datos estructurados en lugar de texto para leer con los ojos.

-- Inventario legible de todo lo que escucha un evento
local entradas = vim.api.nvim_get_autocmds({ event = "BufWritePre" })
for _, a in ipairs(entradas) do
  print(("[%s] %s -> %s"):format(a.group_name or "sin grupo", a.pattern, a.desc or "sin descripcion"))
end

-- Cuantos autocomandos ha registrado cada grupo
local por_grupo = {}
for _, a in ipairs(vim.api.nvim_get_autocmds({ event = "*" })) do
  local g = a.group_name or "ANONIMO"
  por_grupo[g] = (por_grupo[g] or 0) + 1
end
vim.print(por_grupo)

Ese segundo fragmento merece ejecutarse en cualquier configuración madura. El recuento bajo la clave de los anónimos es una métrica de deuda técnica: son exactamente los autocomandos que ya no puedes borrar ni identificar.

Por qué no dispara: el catálogo de causas

Cuando una reacción no ocurre, la causa está casi siempre en esta lista, y conviene recorrerla en orden porque está ordenada por frecuencia real.

Hay dos causas más que no caben en tarjetas y que producen los casos más desconcertantes. La primera: el buffer no tiene nombre. Muchos eventos comparan el patrón contra una ruta vacía, de modo que cualquier patrón distinto del asterisco falla en buffers recién creados, en los del terminal y en los de los plugins de interfaz. La segunda: el autocomando existe pero su callback aborta. Un error dentro de un callback se reporta, pero si envolviste el cuerpo en pcall o comprobaste una condición que resultó falsa, el efecto no ocurre y la tabla te dice que todo está correcto. Antes de dudar del emparejamiento, pon una notificación en la primera línea del callback.

-- Sonda universal: que llega realmente y con que valores
vim.api.nvim_create_autocmd(
  { "BufReadPost", "BufWritePre", "FileType", "LspAttach", "User" },
  {
    group = vim.api.nvim_create_augroup("dios_sonda", { clear = true }),
    desc = "Traza de diagnostico, borrar cuando termines",
    callback = function(args)
      vim.notify(("%s | match=%s | buf=%d"):format(args.event, args.match, args.buf))
    end,
  }
)

El orden de ejecución

Cuando varios autocomandos escuchan el mismo evento y todos casan, se ejecutan en orden de registro. No hay prioridades, no hay pesos, y los grupos no reordenan nada: un autocomando de un grupo creado después se ejecuta después, sin más.

flowchart TD
E[Se emite BufWritePre] --> T[Recorrido de la tabla en orden de registro]
T --> A1[Autocomando 1 registrado al arrancar]
A1 --> A2[Autocomando 2 de un plugin]
A2 --> A3[Autocomando 3 de tu configuracion]
A3 --> F[Se escribe el archivo]
A1 -.si aborta la escritura.-> X[Los siguientes no llegan a correr]
style T fill:#cba6f7,color:#11111b
style X fill:#f38ba8,color:#11111b

La consecuencia inmediata es que el orden depende del orden de carga de los plugins, que no controlas y que cambia cuando instalas o quitas cualquier cosa. Construir lógica sobre la suposición de que tu formateador corre antes que el de otro plugin es construir sobre arena.

Cuando el orden importa de verdad hay tres soluciones legítimas, en orden de preferencia. La primera y mejor: no depender del orden, haciendo cada autocomando independiente del efecto de los demás. La segunda: fusionar en uno solo, un único suscriptor que llama a las dos acciones en la secuencia que quieres, con lo que el orden pasa de ser emergente a ser código explícito. La tercera, para cuando no controlas al otro: reregistrar para ir al final, borrando tu grupo y volviéndolo a crear en un momento posterior, típicamente desde VeryLazy o desde un VimEnter diferido.

-- Orden explicito: un suscriptor que secuencia, en vez de dos que compiten
vim.api.nvim_create_autocmd("BufWritePre", {
  group = vim.api.nvim_create_augroup("dios_pipeline_guardado", { clear = true }),
  desc = "Saneado y formato en secuencia determinista",
  callback = function(args)
    require("dios.saneado").quitar_espacios(args.buf)
    require("dios.formato").aplicar(args.buf)
  end,
})

Instrumentar: medir y aislar

Cuando el problema no es que no dispare sino que dispara demasiado o cuesta demasiado, la técnica cambia: hay que medir. Los eventos de alta frecuencia —CursorMoved, TextChanged, BufEnter— son los sospechosos habituales de un editor perezoso.

-- Cuenta disparos por evento durante una sesion de trabajo
local cuentas = {}
vim.api.nvim_create_autocmd(
  { "CursorMoved", "CursorMovedI", "TextChanged", "BufEnter", "InsertLeave" },
  {
    group = vim.api.nvim_create_augroup("dios_metricas", { clear = true }),
    callback = function(args)
      cuentas[args.event] = (cuentas[args.event] or 0) + 1
    end,
  }
)
vim.api.nvim_create_user_command("Disparos", function() vim.print(cuentas) end, {})

Para aislar al culpable de una lentitud concreta, la bisección sobre grupos es infalible y rápida: borra la mitad de tus grupos con nvim_del_augroup_by_name, comprueba si el síntoma persiste y repite. Como los grupos son idempotentes, restaurarlos es volver a evaluar el archivo. Si el síntoma sobrevive a borrar todos tus grupos, el origen está en un plugin, y ahí :verbose autocmd te da el nombre del archivo en una línea.