Miranda Language Server Protocol para VS Code

Qué es Miranda

Miranda es un lenguaje de programación funcional desarrollado por David Turner en los años 80. Fue uno de los primeros lenguajes funcionales con evaluación lazy e influyó directamente en el diseño de Haskell. Los archivos Miranda usan la extensión .m o .miranda. Como el lenguaje no tiene soporte en editores modernos, este servidor LSP fue construido desde cero.

Visual Studio Code es un editor de código que, por defecto, no entiende qué es Miranda. No sabe colorear el código, detectar errores ni ofrecer herramientas de navegación.

Esta extensión soluciona eso implementando un servidor LSP (Language Server Protocol). El LSP es un protocolo estándar que define cómo se comunican un editor y un servidor que entiende un lenguaje de programación. Gracias a eso, el servidor puede funcionar no solo en VS Code, sino también en cualquier otro editor compatible con LSP. Antes de existir LSP, si querías soporte para un lenguaje en distintos editores, había que implementar toda la lógica por separado para cada uno. Con LSP, el editor y el servidor hablan un "idioma común". El editor se encarga de la interfaz y el servidor se encarga de analizar el código.

Cuando se abre un archivo .m, VS Code inicia el servidor en segundo plano y comienza a intercambiar mensajes con él usando JSON-RPC, un formato estándar para comunicación entre procesos. Por ejemplo, si el usuario mueve el cursor sobre una función, VS Code envía un mensaje indicando la posición exacta del cursor. El servidor analiza el código, encuentra la definición correspondiente y responde con el archivo y la línea donde está declarada. VS Code usa esa respuesta para permitir navegación inmediata dentro del código. Todo esto ocurre en tiempo real mientras se escribe.

Caso de uso principal

El actor principal es el programador que escribe código Miranda en VS Code. El caso de uso central es que pueda abrir un archivo .m o .miranda y recibir soporte de editor en tiempo real sin necesidad de configurar nada manualmente.

Antes de esta extensión, VS Code trataba los archivos Miranda como texto plano sin ningún tipo de asistencia. El programador tenía que recordar la sintaxis y los tipos de memoria, navegar el código manualmente y detectar errores solo al correr el intérprete. Esta extensión elimina esa fricción, permitiendo trabajar con Miranda con las mismas herramientas que se tienen para cualquier lenguaje moderno.

Arquitectura

La arquitectura está dividida en dos partes:

• client/src/extension.ts: Corresponde a la extensión de Visual Studio Code. Su responsabilidad es iniciar el servidor cuando se abre un archivo Miranda y actuar como intermediario entre VS Code y el servidor.
• server/src/server.ts: Es un proceso separado que corre en segundo plano y contiene toda la lógica que entiende el lenguaje Miranda.

Cuando el servidor inicia, declara sus capacidades mediante una función llamada onInitialize. Esto le indica a VS Code qué funcionalidades soporta. Por ejemplo, si declara hoverProvider: true, VS Code sabe que puede consultarle qué mostrar cuando el usuario pasa el mouse sobre un símbolo. Si no lo declara, VS Code simplemente no realiza ese pedido. De esta forma, cada servidor implementa únicamente las capacidades que soporta.

Las librerías utilizadas son vscode-languageclient del lado del cliente y vscode-languageserver del lado del servidor. Son los módulos oficiales publicados por Microsoft para implementar LSP en Node.js y se encargan de manejar la conexión, parsear los mensajes JSON-RPC y exponer APIs para registrar cada tipo de request.

Decisiones técnicas

Para mantener sincronizado el contenido entre el editor y el servidor, LSP ofrece dos estrategias: Incremental, donde el editor envía únicamente el fragmento modificado, y Full, donde se envía el documento completo en cada cambio. Se eligió Full porque el servidor necesita analizar el archivo completo de todas formas. Ante cada modificación debe volver a escanear las funciones definidas para actualizar el autocompletado, recalcular los errores del archivo y reconstruir el outline con los símbolos detectados. No existe ninguna operación que pueda resolverse únicamente con el fragmento modificado, por lo que recibir el documento completo simplifica la implementación. Además, los archivos Miranda suelen tener solo varias líneas, por lo que el costo de enviar el texto completo en cada edición es insignificante.

Para analizar el código Miranda, el servidor utiliza expresiones regulares en lugar de un parser formal. La solución tradicional sería construir un AST (Abstract Syntax Tree), una representación estructurada del programa en forma de árbol donde cada nodo representa elementos sintácticos del lenguaje, como funciones, expresiones o tipos. A partir de ese árbol, el servidor podría responder preguntas como "¿dónde está definida esta función?". El problema es que no existe un parser de Miranda para Node.js y desarrollar uno desde cero hubiera implicado un proyecto mucho más grande que el propio servidor LSP. Como alternativa, decidí por trabajar directamente sobre el texto mediante expresiones regulares. Por ejemplo, para detectar definiciones de funciones se busca que la línea comience en la columna 0, empiece con una letra minúscula y contenga un =. Aunque no cubre todos los casos posibles del lenguaje, funciona correctamente para la gran mayoría de los casos reales.

Features implementadas

1. Syntax Highlighting

VS Code no conoce Miranda, así que el código aparecía todo del mismo color. Se definió una gramática (syntaxes/miranda.tmLanguage.json) que le dice al editor cómo colorear cada parte del lenguaje. Los colores dependen del tema que tenga instalado cada uno, pero cada categoría siempre tiene un color distinto.

2. Hover

Cuando se pasa el mouse sobre cualquier keyword o función del prelude, aparece un tooltip con su descripción y type signature.

3. Autocompletado

Al escribir las primeras letras de una función o keyword, aparecen sugerencias. El autocompletado incluye:

• Keywords de Miranda (where, if, otherwise, abstype)
• Funciones del prelude (map, filter, foldr, foldl, reverse)
• Las funciones propias del archivo, el servidor lo escanea y agrega al autocompletado todas las funciones que están definidas ahí.

4. Signature Help

Al escribir el ( para llamar a una función, aparece un tooltip con su type signature. Así se sabe qué parámetros recibe sin tener que buscar dónde está definida.

5. Detección de errores

El servidor analiza el código en tiempo real y subraya los errores:

6. Go to Definition

Posicionando el cursor sobre el nombre de una función el editor salta directo a donde está definida. Funciona tanto para funciones del mismo archivo como para funciones definidas en otros archivos.

https://github.com/user-attachments/assets/16a0a92d-0038-4220-84b8-e063b0964913

7. Find All References

Haciendo clic derecho en Find All References sobre cualquier función, se abre un panel con todas las líneas del archivo donde aparece ese nombre.

8. Rename Symbol

Haciendo clic derecho en Rename Symbol sobre el nombre de una función, se escribe el nombre nuevo y Enter. El servidor actualiza todas las apariciones a la vez, la definición, la type signature y cada lugar donde se llama.

https://github.com/user-attachments/assets/6f4bf590-dd2a-4dd7-9bfb-cc3cc46560a7

9. Code Lens

Encima de cada función aparece una línea gris con cuántas veces se llama en el archivo.

10. Document Symbols

El panel Outline del sidebar de VS Code lista todas las funciones definidas en el archivo. Haciendo clic en cualquiera se salta a esa línea.

11. Format Document

Haciendo clic derecho en Format Document. El servidor limpia el archivo, elimina espacios al final de cada línea y normaliza las líneas en blanco de más.

12. Code Actions

Cuando hay un error o warning subrayado, aparece una 💡 al costado. Al hacer clic se despliega un menú con una acción para corregirlo automáticamente.

13. Workspace Symbols

Presionando Cmd+T se abre un buscador de símbolos en todos los archivos del proyecto.

Cómo correrlo

git clone <url-del-repo>
cd plugin-individual-florjasinski
npm install
npm run compile

Para compilar en modo watch (recompila automáticamente al guardar):

npm run watch

Una vez compilado, hay que abrir el panel Run and Debug y seleccionar Run Miranda Extension y hacer clic en el botón verde de play. Esto abre una nueva ventana de VS Code donde la extensión ya está activa. Hay que abrir cualquier archivo .m o .miranda en esa ventana y la extensión va a funcionar.

Publicación en el Marketplace

La extensión está publicada en el Visual Studio Code Marketplace y se puede instalar directamente desde VS Code buscando Miranda LSP.

Uso de herramientas de IA

Durante el desarrollo de este trabajo utilicé Claude Code (claude-sonnet-4-5) como herramienta de apoyo, principalmente para implementar la lógica del servidor LSP. El código generado fue revisado, ajustado y extendido por mí para adaptarlo a las necesidades específicas del lenguaje Miranda. En todos los casos las decisiones, el diseño de la extensión y el contenido final fueron responsabilidad mía.