Inspeccionar: el visor del árbol y tu propio código

Todo lo anterior —el parser, el árbol, los campos, la gramática— sería teoría inaplicable sin una forma de mirar la estructura que Neovim construye sobre tu buffer. Esa forma existe y viene de serie: un visor que muestra el árbol en vivo, sincronizado con el cursor, y un comando que te dice exactamente qué está pintando cada byte de la pantalla. A partir de aquí dejas de suponer cómo se llama un nodo y pasas a leerlo, que es el requisito para escribir consultas en el nivel siguiente.

El visor del árbol

El comando es :InspectTree, y equivale a llamar a vim.treesitter.inspect_tree. Abre una ventana lateral con el árbol del buffer actual en notación de expresiones simbólicas, y mantiene los dos lados sincronizados: al mover el cursor por el código se resalta el nodo correspondiente, y al moverte por el árbol se resalta el rango del buffer que ocupa ese nodo.

-- Abrir el visor para el buffer actual: sin opciones deduce el lenguaje del filetype
vim.keymap.set("n", "<leader>ti", function()
  vim.treesitter.inspect_tree()
end, { desc = "Inspeccionar el arbol" })

-- Abrir el editor de consultas, equivalente al comando :EditQuery
vim.keymap.set("n", "<leader>tq", function()
  vim.treesitter.query.edit()
end, { desc = "Editar una query" })

Dentro de la ventana del visor hay cuatro teclas que cambian por completo lo que ves:

Empieza siempre con los nodos anónimos ocultos: el árbol se lee como un esquema del programa. Actívalos solo cuando necesites un token concreto —una llave, un operador, una palabra reservada— porque casi siempre es lo que hay que capturar para colorearlo aparte.

Qué pinta cada byte

El árbol responde a la pregunta estructural. La otra pregunta cotidiana —por qué este identificador sale de este color— la responde :Inspect, que informa de todo lo que afecta a la posición del cursor: capturas de Treesitter con su prioridad, grupos de sintaxis clásica si sigue activa, extmarks que aportan resaltado y tokens semánticos del servidor de lenguaje.

-- Volcar en bruto todo lo que afecta a la posicion del cursor
vim.print(vim.inspect_pos())

-- Comprobar si hay arbol y de que lenguaje es.
-- get_parser devuelve nil (y un mensaje) cuando no puede crear el parser:
-- no lanza excepcion, asi que se comprueba con un if, no con pcall.
local parser, err = vim.treesitter.get_parser(0)
print(parser and parser:lang() or err)

Leer esa salida enseña el orden real de mando. Sobre el mismo byte pueden competir una captura de Treesitter, un extmark de un plugin y un token semántico del LSP; gana el de mayor prioridad, y por eso un color puede cambiar segundos después de abrir el archivo, cuando el servidor de lenguaje responde y sus tokens se superponen a los del árbol. Sin esta herramienta, ese comportamiento parece un fallo aleatorio; con ella, es una lista ordenada.

flowchart TD
D[Duda sobre el codigo] --> I[InspectTree con anonimos ocultos]
I --> N[Identificar el tipo de nodo y su campo]
N --> Q[Editor de consultas con o]
Q --> V[Ver las capturas resaltadas en vivo]
V --> OK[La consulta captura lo que querias]
V --> NO[Captura de mas o de menos]
NO --> I
OK --> U[Usarla en highlights o textobjects]
C[Color inesperado] --> P[Inspect sobre la posicion]
P --> L[Lista de capturas extmarks y tokens por prioridad]
style I fill:#89b4fa,color:#11111b
style OK fill:#a6e3a1,color:#11111b
style NO fill:#f38ba8,color:#11111b
style P fill:#cba6f7,color:#11111b

Diagnosticar el árbol de tu propio código

Con el visor abierto, tres situaciones se vuelven legibles de inmediato.

Un nodo ERROR significa que el parser no supo encajar ese fragmento en ninguna regla. Casi siempre es código a medio escribir y desaparece solo; si persiste en código válido, tienes un desfase entre la versión de la gramática y la del lenguaje. Un nodo MISSING es más interesante: el analizador dedujo que falta un token concreto —una llave, un end, un paréntesis— e insertó un marcador vacío para poder continuar. Es tolerancia a errores en acción, y te señala el punto exacto donde el código está incompleto, a menudo mejor que cualquier mensaje del compilador.

La tercera situación son las inyecciones. Un bloque de código dentro de Markdown, una consulta SQL dentro de una cadena, HTML dentro de una plantilla: cada región se parsea con su propio lenguaje y el conjunto se organiza como un árbol de árboles. En el visor pulsa I y verás el lenguaje de cada rama; si un fragmento no se colorea, lo primero es comprobar ahí si la inyección se está reconociendo y si el parser de ese lenguaje está instalado.

Construir tu propia inspección

El visor es una ventana aparte, y hay preguntas que quieres tener contestadas todo el rato, sin abrir nada. Con lo que ya sabes del árbol puedes fabricarlas en unas pocas líneas.

Una migaja de pan con la cadena de nodos que te contiene, lista para colgar de la winbar o de la línea de estado:

local function ruta_sintactica()
  local nodo = vim.treesitter.get_node()
  local partes = {}
  while nodo do
    if nodo:named() then
      table.insert(partes, 1, nodo:type())
    end
    nodo = nodo:parent()
  end
  return table.concat(partes, " > ")
end

vim.api.nvim_create_autocmd({ "CursorMoved", "BufEnter" }, {
  callback = function()
    local ok, ruta = pcall(ruta_sintactica)
    vim.wo.winbar = ok and ruta or ""
  end,
})

Y un comando que te diga si el buffer tiene errores de análisis y dónde está el primero, útil para distinguir un problema de tu código de un problema de la gramática:

vim.api.nvim_create_user_command("TSErrores", function()
  local parser = vim.treesitter.get_parser(0)
  if not parser then
    return vim.notify("este buffer no tiene parser")
  end
  local raiz = parser:parse()[1]:root()
  if not raiz:has_error() then
    return vim.notify("arbol limpio")
  end
  for nodo in raiz:iter_children() do
    if nodo:has_error() then
      vim.notify("rama con error en la linea " .. (nodo:start() + 1))
    end
  end
end, {})

Los propios nodos de error son consultables, cosa que casi nadie sabe. (ERROR) empareja el nodo que el analizador no supo encajar y (MISSING) el marcador de anchura cero que insertó para poder continuar; puedes incluso pedir un token concreto con (MISSING ";"). Con eso, localizar el punto exacto donde el buffer se rompe deja de ser un paseo visual por el visor y pasa a ser una consulta.

Ninguna de estas dos piezas es un plugin ni pretende serlo. Son la demostración de que, una vez el editor tiene un modelo estructural del buffer, la instrumentación deja de ser un privilegio de los autores de plugins y pasa a estar a tu alcance en veinte líneas de Lua.