Diseñar la API pública: la fachada y la superficie mínima

Hasta ahora escribías código para ti: si algo no encajaba, lo cambiabas y seguías. Publicar invierte esa relación de manera irreversible. En el instante en que otra persona escribe require con el nombre de tu plugin, cada nombre que devuelves deja de ser un detalle de implementación y se convierte en una promesa que alguien invocará desde su configuración a las once de la noche, en una versión de Neovim que tú no usas, para un caso que no habías imaginado. Esta lección trata de decidir por adelantado cuáles son esas promesas, y de aceptar la consecuencia incómoda: todo lo que no prometes es libertad que conservas, y todo lo que prometes es libertad que regalas para siempre.

La fachada

Un plugin de Neovim no tiene un punto de entrada impuesto por el lenguaje: tiene el que tú declares. El convenio establecido —y conviene seguirlo, porque los convenios son gratis y las excepciones se pagan en soporte— es que lua/mi-plugin/init.lua sea lo único que un usuario necesite cargar, y que ese archivo no contenga lógica sino delegación.

-- lua/mi-plugin/init.lua : la unica puerta de entrada
local M = {}

---@param opts table|nil
---@return nil
function M.setup(opts)
  require("mi-plugin.config").aplicar(opts or {})
end

---@return boolean activo
function M.toggle()
  return require("mi-plugin.core").toggle()
end

return M

El detalle que parece cosmético y no lo es: cada require vive dentro del cuerpo de la función, no en la cabecera del archivo. Así la fachada cuesta unos microsegundos al cargarse, y el usuario que la carga en el arranque para registrar un mapeo no paga el precio de tu módulo de interfaz gráfica hasta que lo usa. La estructura que se deriva de esto es siempre la misma, y es legible sin explicación:

lua/mi-plugin/
  init.lua      fachada publica, y nada mas
  config.lua    valores por defecto, validacion y fusion
  core.lua      la logica de verdad
  ui.lua        ventanas, extmarks, resaltados
plugin/mi-plugin.lua   solo lo que debe existir sin require explicito
doc/mi-plugin.txt      el contrato escrito en prosa

Accesible no es publicado

Lua no tiene visibilidad. Cualquier módulo bajo lua/ es alcanzable con require, cualquier campo de una tabla devuelta es invocable, y no existe ninguna palabra clave que impida a nadie llamar a mi-plugin.core.reconstruir_indice. La consecuencia es que la frontera entre lo público y lo privado no la impone el lenguaje: la declaras tú y la sostiene la documentación.

Esta distinción no es burocracia: es la única defensa que tendrás cuando alguien abra un issue quejándose de que le has roto algo. Si lo que usaba estaba documentado, tiene razón y el fallo es tuyo. Si estaba llamando a un módulo interno, la respuesta amable es explicarle por qué eso nunca fue una promesa y, si su necesidad es legítima, convertirla en una petición de API pública. Sin la frontera escrita, todas las discusiones se vuelven cuestión de opinión, y el proyecto acaba congelado por miedo a mover cualquier cosa.

Convenios que se fijan una sola vez

Hay cuatro decisiones que resulta barato tomar antes de la primera versión y carísimo cambiar después, porque afectan a todas las llamadas y no a una.

La primera es la configuración. El convenio dominante es una única función setup que recibe una tabla, la fusiona con los valores por defecto y valida el resultado. Fusionar en profundidad importa: el usuario que solo quiere cambiar un color no debería tener que reescribir el resto del árbol.

-- lua/mi-plugin/config.lua
local M = {}

M.defaults = {
  enabled = true,
  ventana = { border = "rounded", ancho = 60 },
  ignorar = { "gitcommit", "help" },
}

M.opts = vim.deepcopy(M.defaults)

function M.aplicar(opts)
  local nueva = vim.tbl_deep_extend("force", M.defaults, opts)
  vim.validate("enabled", nueva.enabled, "boolean")
  vim.validate("ventana.ancho", nueva.ventana.ancho, "number")
  M.opts = nueva
  return M.opts
end

return M

La segunda es qué hace require por sí solo. La respuesta correcta es nada observable: sin autocomandos, sin mapeos, sin comandos, sin grupos de resaltado. Cargar un módulo tiene que ser inocuo, porque el usuario puede cargarlo para leer una constante y no espera que su editor cambie de comportamiento. Los efectos empiezan en setup, o en plugin/ si de verdad deben existir sin que nadie los pida.

La tercera es cómo fallas. En Lua hay dos protocolos, y mezclarlos es una crueldad: error para lo que es culpa del programador —un tipo equivocado, una opción inexistente— y devolver nil más un mensaje para lo que es un resultado legítimo del mundo, como un archivo que no está. Elige uno para cada categoría, escríbelo en la documentación, y no vuelvas a pensarlo.

-- Culpa del programador: revienta pronto y con el nombre del campo
function M.abrir(id)
  vim.validate("id", id, "number")
  ...
end

-- Resultado legitimo del mundo: dos valores, nunca un error
---@return string|nil contenido
---@return string|nil error
function M.leer(ruta) ... end

La cuarta es qué devuelves. Una función que crea algo debe devolver una manija para destruirlo; una función que consulta debe devolver datos, no imprimirlos. Un plugin cuyas funciones solo tienen efectos secundarios y devuelven nil es un plugin imposible de componer, y la composición es exactamente lo que la gente hará con el tuyo en cuanto lo instale. El caso extremo y revelador es la función que abre una ventana: si no devuelve el identificador de esa ventana, acabas de obligar a todo el mundo a adivinarlo recorriendo la lista de ventanas abiertas, que es justo el tipo de acoplamiento frágil que después se rompe y aparece como un issue tuyo.

El coste de un símbolo

flowchart TB
u[Configuracion del usuario] --> f[Modulo raiz como fachada]
f --> s[setup y comandos publicos]
f --> t[Anotaciones de tipo y doc]
s --> c[config interno]
s --> k[core interno]
k --> i[ui interno]
c -.-> x[Nadie depende de esto]
k -.-> x
i -.-> x
style f fill:#cba6f7,color:#11111b
style x fill:#a6e3a1,color:#11111b

Las flechas discontinuas del diagrama son la parte importante y la que se olvida al dibujarlo: representan lo que nadie puede alcanzar legítimamente, y por tanto lo que puedes reescribir mañana sin publicar una versión mayor. Un plugin bien diseñado tiene muchas más flechas discontinuas que continuas, y esa proporción es la medida más honesta de tu libertad futura.

Cada nombre exportado tiene un coste que no se paga al escribirlo sino durante los años siguientes: hay que documentarlo, hay que probarlo, hay que mantener su comportamiento estable frente a los cambios internos y hay que seguir soportándolo cuando ya no encaja con el diseño. Una API de cuarenta funciones no es cuatro veces más trabajo que una de diez: es considerablemente más, porque las combinaciones entre ellas también son contrato. La regla operativa que mejor funciona es preguntarse, símbolo por símbolo, si estarías dispuesto a mantenerlo tres años. Si la respuesta es no, no lo exportes; deja que quien lo necesite lo pida, con un caso de uso concreto, y entonces exporta la mínima función que lo resuelva.