Miranda Language Server Protocol for VS Code

What is Miranda

Miranda is a functional programming language developed by David Turner in the 1980s. It was one of the first functional languages with lazy evaluation and directly influenced the design of Haskell. Miranda files use the .m or .miranda extension. Since the language has no support in modern editors, this LSP server was built from scratch.

Visual Studio Code is a code editor that, by default, does not understand Miranda. It cannot colorize the code, detect errors, or provide navigation tools.

This extension solves that by implementing an LSP (Language Server Protocol) server. LSP is a standard protocol that defines how an editor and a server that understands a programming language communicate. This allows the server to work not only in VS Code but also in any other editor compatible with LSP. Before LSP existed, if you wanted language support across multiple editors, you had to implement all the logic separately for each one. With LSP, the editor and the server speak a "common language." The editor handles the interface and the server handles code analysis.

When a .m file is opened, VS Code starts the server in the background and begins exchanging messages with it using JSON-RPC, a standard format for inter-process communication. For example, if the user hovers over a function, VS Code sends a message with the exact cursor position. The server analyzes the code, finds the corresponding definition, and responds with the file and line where it is declared. VS Code uses that response to enable immediate code navigation. All of this happens in real time while typing.

Main Use Case

The main actor is the programmer writing Miranda code in VS Code. The central use case is being able to open a .m or .miranda file and receive real-time editor support without any manual configuration.

Before this extension, VS Code treated Miranda files as plain text with no assistance. The programmer had to memorize the syntax and types, navigate the code manually, and only detect errors by running the interpreter. This extension eliminates that friction, allowing Miranda to be worked on with the same tools available for any modern language.

Architecture

The architecture is split into two parts:

• client/src/extension.ts: The VS Code extension entry point. Its responsibility is to start the server when a Miranda file is opened and act as an intermediary between VS Code and the server.
• server/src/server.ts: A separate process running in the background that contains all the logic for understanding the Miranda language.

When the server starts, it declares its capabilities through a function called onInitialize. This tells VS Code which features it supports. For example, if it declares hoverProvider: true, VS Code knows it can query what to show when the user hovers over a symbol. If not declared, VS Code simply does not make that request. This way, each server implements only the capabilities it supports.

The libraries used are vscode-languageclient on the client side and vscode-languageserver on the server side. These are the official modules published by Microsoft for implementing LSP in Node.js. They handle the connection, parse JSON-RPC messages, and expose APIs for registering each type of request.

Technical Decisions

To keep content synchronized between the editor and the server, LSP offers two strategies: Incremental, where the editor sends only the modified fragment, and Full, where the entire document is sent on every change. Full was chosen because the server needs to analyze the complete file anyway. On every modification it must re-scan the defined functions to update autocompletion, recalculate file errors, and rebuild the outline with the detected symbols. No operation can be resolved using only the modified fragment, so receiving the full document simplifies the implementation. Also, Miranda files tend to be only a few hundred lines, so the cost of sending the full text on each edit is negligible.

To analyze Miranda code, the server uses regular expressions instead of a formal parser. The traditional solution would be to build an AST (Abstract Syntax Tree), a structured tree representation of the program where each node represents syntactic elements of the language, such as functions, expressions, or types. From that tree, the server could answer questions like "where is this function defined?". The problem is that no Miranda parser exists for Node.js and developing one from scratch would have implied a much larger project than the LSP server itself. As an alternative, I decided to work directly on the text using regular expressions. For example, to detect function definitions the server checks that a line starts at column 0, begins with a lowercase letter, and contains an =. While this does not cover every possible case in the language, it works correctly for the vast majority of real-world cases.

Implemented Features

1. Syntax Highlighting

VS Code does not know Miranda, so code appeared all in the same color. A grammar (syntaxes/miranda.tmLanguage.json) was defined to tell the editor how to colorize each part of the language. Colors depend on the installed theme, but each category always has a distinct color.

2. Hover

Hovering over any keyword or prelude function shows a tooltip with its description and type signature.

3. Autocompletion

Typing the first letters of a function or keyword shows suggestions. Autocompletion includes:

• Miranda keywords (where, if, otherwise, abstype)
• Prelude functions (map, filter, foldr, foldl, reverse)
• User-defined functions from the file — the server scans it and adds all defined functions to autocompletion.

4. Signature Help

Typing ( to call a function shows a tooltip with its type signature, so you know what parameters it takes without having to look up where it is defined.

5. Error Detection

The server analyzes code in real time and underlines errors with red or yellow squiggles depending on severity.

6. Go to Definition

Placing the cursor over a function name jumps directly to where it is defined. Works for functions in the same file as well as functions defined in other files.

7. Find All References

Right-clicking and selecting Find All References on any function opens a panel with all the lines in the file where that name appears.

8. Rename Symbol

Right-clicking and selecting Rename Symbol on a function name, typing the new name, and pressing Enter. The server updates all occurrences at once: the definition, the type signature, and every call site.

9. Code Lens

Above each function a gray line shows how many times it is called in the file.

10. Document Symbols

The Outline panel in the VS Code sidebar lists all functions defined in the file. Clicking any one of them jumps to that line.

11. Format Document

Right-clicking and selecting Format Document. The server cleans up the file, removes trailing spaces from each line, and normalizes extra blank lines.

12. Code Actions

When an error or warning is underlined, a lightbulb icon appears alongside it. Clicking it opens a menu with an action to fix it automatically.

13. Workspace Symbols

Pressing Cmd+T opens a symbol search across all files in the project.

How to Run It

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

To compile in watch mode (recompiles automatically on save):

npm run watch

Once compiled, open the Run and Debug panel, select Run Miranda Extension, and click the green play button. This opens a new VS Code window where the extension is already active. Open any .m or .miranda file in that window and the extension will work.

Marketplace

The extension is published on the Visual Studio Code Marketplace and can be installed directly from VS Code by searching for Miranda LSP.

View on the Marketplace

Examples

See EXAMPLES.md for visual examples of each feature.

Contributing

See CONTRIBUTING.md for setup instructions, how to add new LSP features, diagnostics, keywords, and code conventions.

AI Tool Usage

During the development of this project I used Claude Code (claude-sonnet-4-5) as a support tool, mainly to implement the LSP server logic. The generated code was reviewed, adjusted, and extended by me to fit the specific needs of the Miranda language. In all cases the decisions, the extension design, and the final content were my responsibility.