Diseñar tu vocabulario: prefijos, colisiones y documentación

Llegado este punto sabes crear mapeos, comandos y operadores. El problema deja de ser técnico y pasa a ser de diseño de lenguaje: cincuenta atajos sin sistema son peores que quince con gramática, porque los primeros hay que recordarlos uno a uno y los segundos se deducen. Esta lección trata la parte que ninguna documentación de plugin te va a enseñar.

Prefijos: construir un espacio de nombres

Un prefijo convierte una tecla en un dominio. La convención que mejor escala usa dos niveles y una regla fija: el primer carácter tras <leader> nombra el dominio, el segundo nombra la acción dentro de ese dominio.

Junto a <leader> conviven tres espacios de nombres nativos que deberías respetar en lugar de reinventar. Los corchetes [ y ] significan anterior y siguiente dentro de una secuencia, y Neovim ya trae de serie [q y ]q para la lista de correcciones, [b y ]b para buffers, [d y ]d para diagnósticos, [c y ]c para trozos de diferencia. La tecla g es el cajón de acciones extendidas, y z gobierna pliegues, desplazamiento y ortografía. Un mapeo tuyo que respete estas convenciones se aprende solo; uno que las contradiga te costará una fricción diaria.

Qué teclas están libres de verdad

Neovim instala mapeos por defecto que crecen con cada versión, y la lista sigue en :h default-mappings. El espacio gr está ocupado por las acciones de LSP: grn renombra, gra ejecuta una acción de código, grr lista referencias, gri va a la implementación y grt al tipo. Además K muestra documentación flotante y gO lista los símbolos del documento. Antes de reclamar cualquier tecla, la pregunta correcta no es “me parece que está libre” sino esta:

:verbose nmap gs        → dónde se fijó por última vez ese mapeo
:map <leader>f          → todo lo que cuelga de ese prefijo
:h default-mappings     → qué reclama Neovim de fábrica

:verbose te dice el archivo y la línea exactos donde se fijó el mapeo por última vez, y resuelve en segundos el misterio de qué plugin te ha robado una tecla. La versión programática es más potente, porque puedes ejecutarla al arrancar y convertir una colisión en un aviso.

local function ocupada(modo, lhs)
  local objetivo = vim.fn.keytrans(vim.keycode(lhs))
  for _, m in ipairs(vim.api.nvim_get_keymap(modo)) do
    if vim.fn.keytrans(m.lhs) == objetivo then
      return m.desc or m.rhs or 'mapeo sin descripción'
    end
  end
end

print(ocupada('n', 'grn'))

La opción unique = true hace lo mismo de forma declarativa: si el mapeo ya existe, el arranque falla con E227 en lugar de sobrescribir en silencio. Mientras diseñas tu vocabulario es la red de seguridad más barata que existe. Y si decides quedarte con una tecla nativa, la forma limpia de liberarla es vim.keymap.del, no sobrescribirla y olvidarlo.

El retardo por prefijo compartido

Cuando un mapeo es prefijo estricto de otro, Neovim no puede saber si has terminado de teclear y espera timeoutlen milisegundos antes de decidir. Si mapeas a la vez <leader>b y <leader>bd, cada pulsación del primero arrastra medio segundo de parálisis. La regla de diseño es sencilla y no admite excepciones cómodas: los prefijos son ramas y los mapeos son hojas; ninguna rama puede ser también una hoja.

flowchart TB
R[Tecla lider] --> B[Rama b de buffers]
R --> G[Rama g de git]
B --> B1[Hoja bd cerrar buffer]
B --> B2[Hoja bn siguiente buffer]
G --> G1[Hoja gs estado]
G --> G2[Hoja gd diferencia]
R --> MAL[Hoja b directa provoca espera]
style MAL fill:#f38ba8,color:#11111b
style B1 fill:#a6e3a1,color:#11111b
style G1 fill:#a6e3a1,color:#11111b

El mismo fenómeno tiene una variante que muerde en modo insertar. Si mapeas jk para salir a normal, cada j que teclees quedará retenido hasta que expire el temporizador o llegue otra tecla; en texto en castellano, donde j aparece con frecuencia, la latencia es perceptible. Y no confundas timeoutlen, que gobierna la ambigüedad entre mapeos, con ttimeoutlen, que gobierna la espera de las secuencias de escape del terminal y debe ser muy pequeña para que <Esc> responda al instante.

vim.o.timeout = true
vim.o.timeoutlen = 400    -- ambigüedad entre mapeos tuyos
vim.o.ttimeoutlen = 10    -- códigos del terminal: cuanto más bajo, mejor

Para mapeos locales de buffer que compiten con un prefijo global, nowait = true corta la espera de raíz y resuelve el caso de las ventanas efímeras, donde q debe cerrar de inmediato aunque exista algún q seguido de más teclas en el ámbito global.

Documentar lo que has construido

Un vocabulario sin documentación se erosiona: los atajos que usas a diario sobreviven, y los quincenales se olvidan y se vuelven espacio muerto. La disciplina mínima es desc en absolutamente todos los mapeos, porque convierte tu tabla en una base de datos legible por which-key, por la ayuda y por tus propios scripts.

vim.api.nvim_create_user_command('Chuleta', function()
  local filas = { '| Modo | Tecla | Acción |', '|---|---|---|' }
  for _, modo in ipairs({ 'n', 'x', 'o', 'i', 't' }) do
    for _, m in ipairs(vim.api.nvim_get_keymap(modo)) do
      if m.desc and m.desc ~= '' then
        filas[#filas + 1] = ('| %s | %s | %s |'):format(modo, vim.fn.keytrans(m.lhs), m.desc)
      end
    end
  end
  vim.cmd('enew')
  vim.bo.filetype = 'markdown'
  vim.bo.buftype = 'nofile'
  vim.api.nvim_buf_set_lines(0, 0, -1, false, filas)
end, { desc = 'Volcar todos los atajos documentados a un buffer' })

Ese comando de veinte líneas produce una chuleta que nunca se desactualiza, porque no describe lo que creías haber configurado sino lo que hay cargado ahora mismo. Invierte el sentido habitual de la documentación: en lugar de escribir un archivo que envejece, interrogas al sistema.