merls

merls is a powerful Language Server for Merlin32-style 6502 assembly. It provides a rich set of intelligent IDE features and includes a fully-fledged Visual Studio Code extension as well as a standalone server published to npm (e.g., for coc.nvim).

Status

The LSP feature set for Merlin32-style 6502 assembly is comprehensive and fully implemented. The repository now includes:

1. A standalone Language Server (@razdolbai/merls) published to npm for use with Neovim/Vim.
2. A bundled VS Code Extension (in the vscode/ directory) for a plug-and-play graphical editor experience.

Goals

• Provide a standalone LSP server over stdio
• Provide a seamless out-of-the-box experience in VS Code via the native extension
• Work cleanly with coc.nvim through standard language-server configuration
• Support Merlin32-style 6502 source structure, symbols, directives, and expressions
• Deliver useful editing features before deeper assembler integration

Scope

In Scope

• 6502-only Merlin32-style assembly
• Parser-based diagnostics
• Cross-file symbol resolution via USE, PUT, and ASM
• Extensive LSP features including:
  • diagnostics
  • hover
  • completion
  • go to definition
  • find references
  • document symbols
  • workspace symbols
  • semantic tokens (syntax highlighting)
  • rename
  • formatting (document, range, on-type)
  • folding ranges
  • document highlights
  • inlay hints
  • signature help
  • call hierarchy
  • code actions
  • code lens
  • document links
  • selection ranges

Out of Scope

• 65816 support

Implementation

• runtime: Node.js
• language: TypeScript
• LSP library: vscode-languageserver
• process model: standalone stdio server
• development style: TDD from the start

Installation

VS Code (Primary)

The VS Code extension lives in the vscode/ folder. It bundles the Language Server automatically. To package and install it locally:

cd vscode
npm install
npm run compile
npx vsce package
code --install-extension pearls-1.0.0.vsix

Standalone Server (coc.nvim / Neovim)

If you are using Vim/Neovim or another LSP client, you can install the standalone server globally via npm:

npm install -g @razdolbai/merls

Development Workflow

• npm install: install project dependencies
• npm run build: compile the TypeScript sources into dist/
• npm test: build the project and run the current test suite
• npm run dev: run the TypeScript compiler in watch mode during bootstrap work
• pwsh test/smoke/run-smoke.ps1: run the headless Vim + coc.nvim smoke test (requires Vim with coc.nvim installed via vim-plug)

The packaged CLI entry point now lives at dist/src/cli.js. For VS Code specific development, refer to vscode/DEVELOPMENT.md.

CLI Contract

The supported stdio launch contract is merls --stdio.

coc.nvim Target

The intended integration model is a standard languageserver entry in coc-settings.json that launches merls over stdio.

If you installed merls globally via npm, the languageserver shape is:

{
  "semanticTokens.enable": true,
  "languageserver": {
    "merls": {
      "command": "merls",
      "args": [
        "--stdio"
      ],
      "rootPatterns": [
        ".git"
      ],
      "filetypes": [
        "6502"
      ]
    }
  }
}

To enable semantic tokens for syntax highlighting, ensure "semanticTokens.enable": true is set in your coc-settings.json and that your Vim buffer is set to the matching filetype (e.g. set filetype=6502).

An example configuration lives in examples/coc-settings.json.

Development Notes

• TDD is mandatory for implementation work in this repository.
• Core syntax, parsing, and document model logic are located in src/asm/.
• LSP handlers (hover, completion, diagnostics, etc.) are located in src/lsp/.
• The CLI entry point lives in src/cli.ts and compiles to dist/src/cli.js.
• The test/fixtures/valid/ directory contains supported 6502 Merlin32-style syntax samples.
• The test/fixtures/invalid/ directory contains unsupported 65816-only syntax samples for negative testing.
• The integration test suite covers stdio initialize, the CLI contract, and core LSP features.