Miranda Navigator Function

Extensión individual para Visual Studio Code orientada a mejorar la navegación, lectura y comprensión de archivos escritos en Miranda.

Descripción

Miranda Navigator Function es una extensión para VS Code que analiza archivos Miranda y ayuda al desarrollador a identificar rápidamente las funciones definidas, sus firmas de tipo y la cantidad de ecuaciones o patrones asociados a cada función.

La extensión no busca implementar un compilador completo, un type checker ni un Language Server Protocol completo. Su objetivo principal es mejorar la experiencia de lectura y navegación dentro del editor, ofreciendo información contextual útil sobre el módulo abierto.

Objetivo

El objetivo del plugin es facilitar el trabajo con archivos Miranda, especialmente cuando el archivo contiene muchas funciones o definiciones con múltiples patrones.

La extensión permite:

• Entender rápidamente qué funciones existen en un archivo.
• Identificar qué funciones tienen firma de tipo declarada.
• Detectar funciones sin firma de tipo.
• Ver cuántas ecuaciones o patrones tiene cada función.
• Generar un resumen del módulo en formato Markdown.
• Navegar de forma más cómoda dentro del archivo Miranda.

Alcance

Esta extensión se enfoca en funcionalidades de navegación, análisis liviano y documentación automática del módulo.

Quedan fuera del alcance inicial:

• Inferencia de tipos.
• Validación semántica completa.
• Ejecución de código Miranda.
• Implementación completa de un Language Server Protocol.
• Análisis exhaustivo de pattern matching.
• Correcciones automáticas complejas.
• Análisis de dependencias entre módulos.

Funcionalidades implementadas

Detección de funciones

La extensión analiza el documento abierto y detecta funciones Miranda a partir de sus definiciones.

Ejemplo:

factorial 0 = 1
factorial n = n * factorial (n - 1)

En este caso, la extensión identifica la función factorial y reconoce que tiene más de una ecuación o patrón.

Detección de firmas de tipo

La extensión reconoce firmas de tipo declaradas con ::.

Ejemplo:

factorial :: num -> num
factorial 0 = 1
factorial n = n * factorial (n - 1)

La función factorial queda registrada como una función con firma declarada.

CodeLens

Sobre cada función detectada, la extensión muestra información contextual mediante CodeLens.

Ejemplo de información mostrada:

2 patrones · con firma

o:

1 patrón · sin firma

Esto permite ver rápidamente si una función está documentada con firma de tipo y cuántas ecuaciones tiene.

Diagnósticos informativos

La extensión muestra un diagnóstico informativo cuando una función no tiene firma de tipo declarada.

Esto no representa un error de compilación, sino una advertencia de calidad y documentación del código.

Resumen de funciones

La extensión incluye el comando:

Miranda Navigator: Show Function Summary

Este comando muestra un resumen de las funciones detectadas en el archivo actual.

Generación de mapa del módulo

La extensión incluye el comando:

Miranda Navigator: Generate Module Map

Este comando genera un documento Markdown con una tabla resumen de las funciones del archivo.

El mapa incluye:

• Nombre de la función.
• Firma de tipo, si existe.
• Cantidad de ecuaciones o patrones.
• Línea donde aparece la función.

Información de función

La extensión incluye el comando:

Miranda Navigator: Show Function Info

Este comando permite visualizar información específica sobre una función detectada.

Syntax highlighting básico

La extensión registra soporte básico de sintaxis para archivos Miranda.

Extensiones reconocidas por defecto:

.mir
.mira

No se registra .m por defecto para evitar conflictos con otros lenguajes o extensiones, ya que esa extensión puede ser utilizada por otros ecosistemas.

Snippets básicos

La extensión incluye snippets simples para facilitar la escritura de estructuras comunes en Miranda.

Archivo de prueba incluido

El repositorio incluye un archivo de prueba llamado:

archivoParaProbarPlugin.mir

Este archivo permite validar rápidamente las funcionalidades principales del plugin.

Con este archivo se puede probar:

• Detección de funciones.
• Detección de firmas de tipo.
• Conteo de ecuaciones o patrones.
• CodeLens sobre funciones.
• Diagnóstico informativo para funciones sin firma.
• Generación del mapa Markdown del módulo.
• Comandos disponibles desde la Command Palette.

Uso de la extensión

1. Abrir un archivo .mir o .mira en VS Code.
2. Verificar que VS Code reconozca el lenguaje como Miranda.
3. Ejecutar alguno de los comandos desde la Command Palette.

Para abrir la Command Palette:

Ctrl + Shift + P

Luego buscar:

Miranda Navigator

Comandos disponibles:

Miranda Navigator: Show Function Summary
Miranda Navigator: Generate Module Map
Miranda Navigator: Show Function Info

Ejemplo de código Miranda

|| Example Miranda file

factorial :: num -> num
factorial 0 = 1
factorial n = n * factorial (n - 1)

sumList :: [num] -> num
sumList [] = 0
sumList (x:xs) = x + sumList xs

withoutType x = x + 1

Para este archivo, la extensión detecta:

Función	Firma	Ecuaciones / patrones
factorial	factorial :: num -> num	2
sumList	sumList :: [num] -> num	2
withoutType	Sin firma declarada	1

Además, la función withoutType genera un diagnóstico informativo porque no tiene firma de tipo declarada.

Configuración

La extensión incluye opciones configurables desde la configuración de VS Code.

Ejemplo:

{
  "mirandaNavigator.warnMissingSignatures": true,
  "mirandaNavigator.maxFunctionEquations": 8
}

mirandaNavigator.warnMissingSignatures

Permite activar o desactivar los diagnósticos informativos para funciones sin firma de tipo.

Valor por defecto:

true

mirandaNavigator.maxFunctionEquations

Define una cantidad máxima sugerida de ecuaciones o patrones por función.

Valor por defecto:

8

Desarrollo

Requisitos

Para ejecutar el proyecto en modo desarrollo se necesita tener instalado:

• Node.js
• npm
• Visual Studio Code

Instalación de dependencias

npm install

Compilación

npm run compile

Ejecución de tests

npm test

Ejecución en modo desarrollo

Para probar la extensión:

1. Abrir este proyecto en VS Code.
2. Ejecutar:

npm install
npm run compile

3. Presionar F5.

Esto abre una nueva ventana de VS Code llamada Extension Development Host.

4. En esa segunda ventana, abrir el archivo:

archivoParaProbarPlugin.mir

5. Ejecutar los comandos de la extensión desde la Command Palette.

Estructura del proyecto

plugin-individual-Giovanelli18/
├── .vscode/
│   └── launch.json
├── src/
│   ├── extension.ts
│   ├── mirandaParser.ts
│   └── test/
│       └── mirandaParser.test.ts
├── snippets/
│   └── miranda.json
├── syntaxes/
│   └── miranda.tmLanguage.json
├── archivoParaProbarPlugin.mir
├── example.mir
├── language-configuration.json
├── package.json
├── package-lock.json
├── tsconfig.json
├── CHANGELOG.md
└── README.md

Archivos principales

src/extension.ts

Contiene la integración principal con la API de VS Code.

Desde este archivo se registran:

• Comandos.
• CodeLens.
• Diagnósticos.
• Proveedores de símbolos.
• Funcionalidades principales de la extensión.

src/mirandaParser.ts

Contiene la lógica de análisis liviano del código Miranda.

Este archivo se encarga de detectar:

• Firmas de tipo.
• Definiciones de funciones.
• Cantidad de ecuaciones o patrones.
• Líneas donde aparecen las funciones.

src/test/mirandaParser.test.ts

Contiene pruebas unitarias para validar el comportamiento principal del parser.

syntaxes/miranda.tmLanguage.json

Define reglas básicas de syntax highlighting para archivos Miranda.

snippets/miranda.json

Incluye snippets básicos para facilitar la escritura de código Miranda.

archivoParaProbarPlugin.mir

Archivo de ejemplo utilizado para probar las funcionalidades de la extensión.

Decisiones de diseño

No implementar un LSP completo

Se decidió no implementar un Language Server Protocol completo en esta primera versión porque el objetivo del plugin es más acotado: mejorar la navegación y comprensión de archivos Miranda dentro de VS Code.

Un LSP permitiría agregar funcionalidades más avanzadas, como autocompletado complejo, type checking, navegación entre módulos o refactorings. Sin embargo, también aumentaría considerablemente la complejidad técnica del proyecto.

Análisis liviano del código

La extensión realiza un análisis simple basado en el texto del archivo. Esto permite detectar funciones, firmas y patrones sin depender de un compilador completo de Miranda.

Esta decisión permite que el plugin sea más simple, rápido y fácil de mantener.

Evitar conflictos con otras extensiones

La extensión registra por defecto archivos .mir y .mira.

No se registra .m por defecto para evitar posibles conflictos con otros lenguajes o extensiones que utilizan esa misma extensión de archivo.

Los comandos también se registran bajo el prefijo Miranda Navigator para reducir la posibilidad de conflicto con otras extensiones desarrolladas en el curso.

Limitaciones actuales

La versión actual tiene algunas limitaciones:

• No valida si una expresión Miranda es semánticamente correcta.
• No infiere tipos.
• No detecta todos los errores posibles de pattern matching.
• No analiza dependencias entre módulos.
• No ejecuta código Miranda.
• El parser es intencionalmente simple y puede no cubrir todos los casos avanzados del lenguaje.

Estas limitaciones son aceptadas dentro del alcance del plugin, ya que el foco está en navegación, lectura y documentación automática.

Posibles mejoras futuras

Algunas mejoras posibles para futuras versiones son:

• Agregar hover con información de funciones detectadas.
• Agregar autocompletado básico de funciones del archivo.
• Agregar integración con funciones del Preludio.
• Mejorar el parser para soportar más casos del lenguaje Miranda.
• Agregar detección de patrones redundantes o no alcanzables.
• Agregar navegación entre módulos.
• Agregar soporte opcional para archivos .m.
• Agregar una vista lateral con el resumen del módulo.
• Permitir exportar el mapa del módulo a un archivo Markdown.

Validación manual

Para validar manualmente la extensión se puede utilizar el archivo:

archivoParaProbarPlugin.mir

Pasos sugeridos:

1. Ejecutar la extensión con F5.
2. Abrir archivoParaProbarPlugin.mir en la ventana de desarrollo.
3. Verificar que aparezcan los CodeLens sobre las funciones.
4. Ejecutar Miranda Navigator: Show Function Summary.
5. Ejecutar Miranda Navigator: Generate Module Map.
6. Confirmar que el mapa generado coincida con las funciones del archivo.
7. Verificar que las funciones sin firma generen un diagnóstico informativo.

Validación por pares

Como parte del proceso académico, la extensión debe ser validada por un compañero.

La validación esperada consiste en:

• Probar la extensión en VS Code.
• Usar el archivo archivoParaProbarPlugin.mir o un archivo Miranda propio.
• Verificar las funcionalidades principales.
• Reportar observaciones mediante issues.
• Registrar evidencia tanto en este repositorio como en el repositorio de la extensión validada, cuando corresponda.

La validación de una extensión externa también debe quedar documentada mediante issues, indicando:

• Qué extensión fue validada.
• Qué funcionalidades se probaron.
• Qué resultado se obtuvo.
• Qué problemas o limitaciones se encontraron.
• Qué mejoras se sugieren desde el punto de vista de Ingeniería de Software.

Publicación en Marketplace

La extensión fue publicada en el Visual Studio Marketplace bajo el publisher:

giovanelli18

Datos de publicación:

Nombre publicado: Miranda Navigator Function
Identificador: giovanelli18.miranda-navigator-function
Versión publicada: 0.0.1
Publisher: giovanelli18
Disponibilidad: pública

URL pública de la extensión:

https://marketplace.visualstudio.com/items?itemName=giovanelli18.miranda-navigator-function

La publicación se realizó mediante carga manual del archivo .vsix desde el panel de administración del publisher en Visual Studio Marketplace.

Inicialmente se intentó publicar mediante vsce login giovanelli18 utilizando un Personal Access Token de Azure DevOps. Sin embargo, el token generó errores de autorización sobre el publisher. Por ese motivo, se utilizó el método alternativo de publicación manual permitido por Marketplace: empaquetar la extensión con vsce package y subir el archivo .vsix desde el panel del publisher.

Comandos utilizados para validar, compilar y empaquetar:

npm run compile
npm test
vsce package

El archivo .vsix generado no se incluye en el repositorio porque es un artefacto de publicación. El repositorio mantiene el código fuente, la configuración de la extensión y los archivos necesarios para reconstruir el paquete.

Estado actual

El plugin cuenta con una primera versión funcional aceptada como propuesta académica.

Actualmente permite probar las funcionalidades principales dentro de VS Code mediante F5 y también se encuentra publicado en Visual Studio Marketplace.

Checklist de entrega

Estado de los puntos principales de la entrega:

• Implementación funcional de la extensión.
• Código fuente disponible en el repositorio.
• README documentado.
• Archivo de prueba incluido.
• Tests del parser incluidos.
• Extensión empaquetada como .vsix.
• Extensión publicada en Visual Studio Marketplace.
• Pendiente o a documentar: validación por parte de un compañero.
• Pendiente o a documentar: validación de una extensión externa de un compañero.

Autor

Plugin individual desarrollado para el curso de Ingeniería de Software Colaborativa.

Repositorio:

https://github.com/IngSoft-IOS-2026-1/plugin-individual-Giovanelli18