Namespaces: agrupar marcas para poder borrarlas

Colocar extmarks es fácil; el problema real de un plugin es quitarlas. Si redibujas anotaciones en cada pulsación y no tienes forma de decir borra todo lo que puse yo y nada más, acabarás llevando a mano una lista de identificadores, se te escapará alguno y el buffer terminará lleno de fantasmas de marcas anteriores. El namespace existe justamente para eso: es la etiqueta que agrupa tus marcas y las convierte en desechables en bloque, sin tocar las de nadie más. Es una pieza aburrida y es, en la práctica, la que decide si tu plugin es limpio o es una fuga.

Un nombre que devuelve un número

Un namespace es un entero opaco que Neovim te entrega a cambio de una cadena. La función es vim.api.nvim_create_namespace y su propiedad más importante es que no crea nada nuevo si el nombre ya existe: llamarla mil veces con la misma cadena devuelve mil veces el mismo entero. Eso la vuelve segura de invocar en la carga del módulo, en cada llamada de una función o dentro de un autocomando, sin acumular basura ni necesitar memorizar el valor en una variable global.

-- Idempotente: la misma cadena siempre devuelve el mismo id
local ns = vim.api.nvim_create_namespace("miplugin.inline")

vim.api.nvim_buf_set_extmark(0, ns, 3, 0, { hl_group = "Comment" })
vim.api.nvim_buf_set_extmark(0, ns, 7, 0, { hl_group = "Comment" })

-- Y en cualquier otro archivo del proyecto:
local mismo = vim.api.nvim_create_namespace("miplugin.inline")
assert(mismo == ns)

Pasar 0 como namespace está permitido y significa ninguno: la marca se crea anónima, no se puede filtrar y no se puede limpiar en grupo. Sirve para experimentar en la línea de comandos y para casi nada más. En código de producción, una extmark sin namespace es una fuga de memoria visual que solo puedes cerrar cerrando el buffer.

Borrar en bloque

La contrapartida de agrupar es la limpieza. vim.api.nvim_buf_clear_namespace recibe el buffer, el namespace y un rango de líneas, y elimina de golpe todas las marcas de ese grupo que caigan dentro. Con 0 y -1 como límites, el rango es el buffer entero.

-- Todo el buffer
vim.api.nvim_buf_clear_namespace(0, ns, 0, -1)

-- Solo las lineas 10 a 19: redibujado parcial y barato
vim.api.nvim_buf_clear_namespace(0, ns, 10, 20)

El rango acotado no es un detalle menor: es la diferencia entre un plugin que recalcula el archivo entero en cada tecla y uno que solo rehace la ventana visible. Cuando un autocomando de cambio te dice qué líneas se tocaron, limpiar y repintar solo ese tramo mantiene el coste proporcional a la edición y no al tamaño del archivo.

Hay que subrayar qué es lo que no borra esta función: no toca las marcas de otros namespaces, ni siquiera las que estén en la misma línea o cubran el mismo carácter. Esa garantía de aislamiento es la razón de que decenas de plugins puedan anotar el mismo buffer simultáneamente sin coordinarse, y es también la razón de que el namespace sea obligatorio en la práctica aunque la API lo acepte a cero.

Para inspeccionar en vez de destruir está nvim_buf_get_extmarks, que acepta el mismo namespace como filtro, un rango, un límite de resultados y una opción details que devuelve además toda la configuración de cada marca. Es la herramienta de depuración imprescindible del nivel: si no ves lo que esperabas en pantalla, enumera tus marcas antes de suponer nada.

local marcas = vim.api.nvim_buf_get_extmarks(0, ns, 0, -1, { details = true })
for _, m in ipairs(marcas) do
  local id, fila, col, detalle = m[1], m[2], m[3], m[4]
  print(id, fila, col, vim.inspect(detalle))
end

flowchart LR
a[Evento de cambio en el buffer] --> b[clear_namespace en el rango tocado]
b --> c[Recalcula la informacion de esas lineas]
c --> d[set_extmark para cada anotacion nueva]
d --> a
style b fill:#f38ba8,color:#11111b
style d fill:#a6e3a1,color:#11111b

Conviene enunciar el ciclo como un invariante y no como una receta: en todo momento, el conjunto de marcas de tu namespace en un rango debe ser función únicamente del contenido actual de ese rango. Si tu código cumple esa propiedad, da igual cuántas veces se dispare el redibujado, en qué orden lleguen los eventos o si dos autocomandos se solapan: el resultado converge siempre al mismo estado. Si no la cumple, tendrás fallos que solo aparecen al escribir rápido y que no sabrás reproducir.

Ese ciclo de cuatro pasos —limpiar, recalcular, repintar, esperar— es el esqueleto de prácticamente todo plugin de anotación que existe. La disciplina consiste en que la limpieza y el pintado usen siempre el mismo namespace y el mismo rango, porque en cuanto ambos se desalinean aparecen anotaciones duplicadas o huecos sin repintar.

Hay una asimetría que conviene tener presente. nvim_buf_clear_namespace borra las marcas que empiezan dentro del rango que le das; una marca de rango que arranca antes del límite inferior y lo cruza sobrevive a la limpieza. Cuando tus anotaciones son puntuales eso no importa nunca, pero si trabajas con rangos largos —un bloque resaltado de treinta líneas— limpiar solo la ventana visible puede dejarte marcas viejas colgando desde arriba. La solución es ampliar el rango de limpieza hasta el inicio de la anotación más larga posible, o llevar rangos que nunca crucen la frontera que uses para repintar.

-- Cuidado: una marca que empieza en la linea 3 y acaba en la 40
-- NO se borra con esta llamada, porque su inicio queda fuera.
vim.api.nvim_buf_clear_namespace(0, ns, 10, 20)

Tampoco existe una operación para renombrar, fusionar ni enumerar namespaces por buffer. Sí puedes listar los existentes en la sesión con nvim_get_namespaces, que devuelve una tabla de nombre a identificador; es útil para depurar quién está pintando en un buffer cuando sospechas de un conflicto entre plugins, pero no es una API de gestión: los namespaces se crean y ya está, no se destruyen.

Cuántos namespaces necesitas

La respuesta corta es: uno por cada cosa que quieras poder apagar por separado. Si tu plugin muestra pistas de tipo al final de la línea y además resalta la variable bajo el cursor, y el usuario puede desactivar solo lo primero, esos son dos grupos. Si todo se enciende y se apaga junto, uno basta.

La pregunta de control para decidirlo es una sola: si el usuario desactiva esta funcionalidad, ¿qué marcas deben desaparecer? Si la respuesta agrupa limpiamente un subconjunto, ese subconjunto merece su propio grupo. Si la respuesta es todas, no dividas.

Lo que casi nunca conviene es un namespace por buffer o por línea. El identificador es global al proceso y no se recicla, así que fabricar nombres dinámicos como miplugin.buf.42 hace crecer la tabla interna sin límite durante toda la sesión, además de dejarte sin la ventaja principal: la limpieza en una sola llamada. La ubicación ya la aporta el par buffer más rango que pasas a las funciones; el namespace es para la procedencia, no para la posición.

Un caso intermedio aparece cuando el plugin ofrece varios modos que el usuario alterna. Si tienes anotaciones permanentes y otras que solo se muestran mientras el cursor está en la línea, esas dos familias tienen ciclos de vida radicalmente distintos: las primeras se rehacen al cambiar el texto, las segundas al mover el cursor, que es un evento muchísimo más frecuente. Meterlas en el mismo grupo obliga a recalcular lo caro cada vez que ocurre lo barato, y ese es exactamente el síntoma que percibe el usuario como el editor va lento desde que instalé esto.

local ns_fijo = vim.api.nvim_create_namespace("miplugin.persistente")
local ns_cursor = vim.api.nvim_create_namespace("miplugin.bajo_cursor")

vim.api.nvim_create_autocmd("CursorMoved", {
  callback = function()
    -- Solo se rehace lo barato: lo persistente ni se toca
    vim.api.nvim_buf_clear_namespace(0, ns_cursor, 0, -1)
    -- ... y se vuelve a pintar la anotacion de la linea actual
  end,
})

Hay un segundo uso que conviene tener en el radar. Un namespace también puede llevar asociada una tabla de resaltado propia mediante nvim_set_hl_ns y nvim_win_set_hl_ns, lo que permite que un mismo grupo de resaltado se vea distinto en una ventana concreta. Es la maquinaria que hay detrás de las ventanas flotantes con tema propio, y aunque no la necesitarás para anotar texto, explica por qué el namespace no es solo una etiqueta de borrado sino una unidad de contexto visual completa.