Un caso real: un plugin que anota mientras escribes

Todo lo anterior se junta aquí. Vamos a escribir un plugin pequeño y honesto: marca las líneas que superan el ancho recomendado, pone un símbolo en el margen y anuncia al final de la línea cuántas columnas sobran, y se mantiene al día mientras el usuario escribe. Es deliberadamente modesto en funcionalidad y exigente en ingeniería, porque los problemas difíciles de un plugin de anotación no están en el cálculo: están en cuándo recalcular, cuánto repintar y cómo apagarse sin dejar rastro. Quien resuelve esos tres, ha resuelto la categoría entera.

El dibujado: limpiar, calcular, marcar

La función de dibujado es el corazón y debe cumplir una regla: llamarla dos veces seguidas tiene que dejar exactamente el mismo resultado que llamarla una vez. Se consigue limpiando el namespace en el rango antes de repintarlo, nunca añadiendo sobre lo que ya había.

local M = {}
local ns = vim.api.nvim_create_namespace("anchoaviso.inline")
local LIMITE = 80

local function pintar(bufnr, desde, hasta)
  vim.api.nvim_buf_clear_namespace(bufnr, ns, desde, hasta)
  local lineas = vim.api.nvim_buf_get_lines(bufnr, desde, hasta, false)

  for i, linea in ipairs(lineas) do
    local ancho = vim.fn.strdisplaywidth(linea)
    if ancho > LIMITE then
      vim.api.nvim_buf_set_extmark(bufnr, ns, desde + i - 1, 0, {
        sign_text = "▸",
        sign_hl_group = "DiagnosticSignWarn",
        virt_text = { { "  +" .. (ancho - LIMITE) .. " col", "DiagnosticVirtualTextWarn" } },
        virt_text_pos = "eol",
        priority = 120,
      })
    end
  end
end

Tres decisiones merecen defensa. Medimos con strdisplaywidth y no con el tamaño en bytes, porque lo que le importa al usuario son celdas de pantalla y un ideograma ocupa dos. Elegimos prioridad 120, por debajo de los diagnósticos: si hay un error en la línea, que gane el error. Y usamos eol en lugar de inline, porque nuestra información es un comentario marginal y no merece desplazar el código.

Solo lo visible, y no en cada tecla

Recorrer un archivo de veinte mil líneas en cada pulsación es inviable, y además es innecesario: el usuario solo ve una ventana. Calculamos el rango visible con nvim_win_get_cursor y las funciones de línea de la ventana, ampliamos un poco por arriba y por abajo para cubrir el desplazamiento inmediato, y pintamos solo eso.

La segunda mitad del problema es la frecuencia. TextChangedI se dispara en cada carácter que escribes, así que engancharle trabajo directamente convierte el tecleo en una sucesión de pequeños atascos. La solución estándar es amortiguar: cada evento reinicia un temporizador corto y el dibujado real ocurre solo cuando el usuario deja de escribir unos milisegundos.

local temporizador = nil

local function programar(bufnr)
  if temporizador then
    temporizador:stop()
    temporizador:close()
  end
  temporizador = vim.uv.new_timer()
  temporizador:start(80, 0, vim.schedule_wrap(function()
    if vim.api.nvim_buf_is_valid(bufnr) then
      local win = vim.fn.bufwinid(bufnr)
      if win ~= -1 then
        local alto = vim.api.nvim_win_get_height(win)
        local arriba = math.max(0, vim.fn.line("w0", win) - 1 - alto)
        local abajo = vim.fn.line("w$", win) + alto
        pintar(bufnr, arriba, abajo)
      end
    end
  end))
end

El vim.schedule_wrap no es decorativo: el temporizador de vim.uv se ejecuta en el bucle de eventos, fuera del hilo principal del editor, y llamar a la API de Neovim desde ahí es un error. schedule_wrap difiere la función al momento seguro siguiente. Es el error más frecuente de quien escribe su primer plugin asíncrono, y se manifiesta como un fallo intermitente e imposible de reproducir.

flowchart LR
e[TextChanged o TextChangedI] --> t[Reinicia el temporizador de 80 ms]
t --> q{Sigue escribiendo}
q -->|si| t
q -->|no| s[schedule_wrap al hilo principal]
s --> r[Calcula rango visible]
r --> p[clear_namespace y repinta]
style t fill:#89b4fa,color:#11111b
style p fill:#a6e3a1,color:#11111b

Encender, apagar y no filtrar

Lo último es el ciclo de vida. Los autocomandos se crean en un grupo local al buffer, de modo que apagar el plugin en un archivo no afecta a los demás; y al apagar hay que hacer las dos cosas, borrar los autocomandos y limpiar el namespace, porque olvidar la segunda deja anotaciones congeladas que ya nadie actualizará.

local grupos = {}

function M.activar(bufnr)
  bufnr = bufnr or vim.api.nvim_get_current_buf()
  if grupos[bufnr] then return end

  local grupo = vim.api.nvim_create_augroup("anchoaviso." .. bufnr, { clear = true })
  grupos[bufnr] = grupo

  vim.api.nvim_create_autocmd(
    { "TextChanged", "TextChangedI", "WinScrolled", "BufEnter" },
    { group = grupo, buffer = bufnr, callback = function() programar(bufnr) end }
  )
  vim.api.nvim_create_autocmd("BufWipeout", {
    group = grupo, buffer = bufnr, callback = function() M.desactivar(bufnr) end,
  })

  programar(bufnr)
end

function M.desactivar(bufnr)
  bufnr = bufnr or vim.api.nvim_get_current_buf()
  if grupos[bufnr] then
    vim.api.nvim_del_augroup_by_id(grupos[bufnr])
    grupos[bufnr] = nil
  end
  if vim.api.nvim_buf_is_valid(bufnr) then
    vim.api.nvim_buf_clear_namespace(bufnr, ns, 0, -1)
  end
end

vim.api.nvim_create_user_command("AnchoAviso", function()
  local b = vim.api.nvim_get_current_buf()
  if grupos[b] then M.desactivar(b) else M.activar(b) end
end, { desc = "Alterna el aviso de lineas largas" })

return M

El autocomando BufWipeout es la pieza que la mayoría olvida: sin él, la tabla grupos conserva entradas de buffers que ya no existen y el plugin va acumulando estado muerto durante toda la sesión. Y WinScrolled está en la lista porque, al pintar solo el rango visible, desplazarse es tan generador de trabajo como escribir.