Editor Support (LSP)

The Nic compiler includes a Language Server Protocol (LSP) implementation for IDE integration.

Features

Feature	Description
Diagnostics	Real-time parse and type errors
Hover	Type information and documentation on hover
Go to Definition	Jump to symbol definitions (cross-module)
Find References	Find all uses of a symbol
Document Outline	Symbols, structs, classes, enums, traits
Semantic Highlighting	Context-aware syntax highlighting
Auto-completion	Symbol and import suggestions

VS Code Setup

Install the Extension

1. Get the Nic extension from the VS Code marketplace, or install manually:

cd extensions/vscode
npm install
npm run package
code --install-extension nic-language-*.vsix

2. The extension automatically starts the LSP server when you open .nic files.

Extension Settings

Configure in VS Code settings (settings.json):

{
  "nic.compiler.path": "nicc",
  "nic.trace.server": "verbose"
}

Setting	Default	Description
nic.compiler.path	nicc	Path to nicc executable
nic.trace.server	off	LSP message tracing (off, messages, verbose)

Neovim Setup

Using nvim-lspconfig

Add to your Neovim configuration:

local lspconfig = require('lspconfig')
local configs = require('lspconfig.configs')

-- Define Nic language server
if not configs.nic then
  configs.nic = {
    default_config = {
      cmd = { 'nicc', 'lsp' },
      filetypes = { 'nic' },
      root_dir = lspconfig.util.root_pattern('nic.toml', '.git'),
      settings = {},
    },
  }
end

-- Enable the server
lspconfig.nic.setup({
  on_attach = function(client, bufnr)
    -- Your on_attach configuration
  end,
})

File Type Detection

Add to your init.lua:

vim.filetype.add({
  extension = {
    nic = 'nic',
  },
})

Other Editors

Any editor supporting LSP can use the Nic language server:

nicc lsp

The server communicates via stdin/stdout using the Language Server Protocol.

Helix

Add to ~/.config/helix/languages.toml:

[[language]]
name = "nic"
scope = "source.nic"
file-types = ["nic"]
roots = ["nic.toml"]
language-server = { command = "nicc", args = ["lsp"] }

Sublime Text

Install the LSP package, then add to settings:

{
  "clients": {
    "nic": {
      "command": ["nicc", "lsp"],
      "selector": "source.nic"
    }
  }
}

Debugging the LSP

Enable Debug Logging

NICC_LSP_DEBUG=1 nicc lsp

Or use a custom log file:

nicc lsp --log /tmp/nicc-lsp.log

Default log location: ~/.nicc/logs/lsp.log

Log Contents

Debug logs include:

• Requests/Responses: All LSP message exchanges
• File Changes: Document open, change, save events
• Diagnostics: Errors and warnings sent to editor
• Module Graph: Import resolution and dependencies
• Cache Operations: Hit/miss information
• Timing: Compilation duration for performance analysis

Example Debug Session

# Terminal 1: Start LSP with debugging
NICC_LSP_DEBUG=1 nicc lsp

# Terminal 2: Watch the log
tail -f ~/.nicc/logs/lsp.log

Troubleshooting

LSP Not Starting

1. Verify nicc is in PATH:

   which nicc
   nicc --version

2. Check extension logs (VS Code: Output > Nic Language Server)

3. Try running manually:

   echo '{"jsonrpc":"2.0","method":"initialize","params":{},"id":1}' | nicc lsp

No Diagnostics

1. Ensure standard library is installed:

   ls ~/.nicc/std/

2. Check for prelude errors:

   nicc --sast yourfile.nic

3. Enable debug logging to see what's happening

Slow Performance

1. Check file size (very large files may be slow)

2. Review debug log for timing:

   [DEBUG] Compilation took 150ms

3. Ensure incremental compilation is working (check for cache hits)

Go to Definition Not Working

1. Ensure the target module is compiled without errors

2. Check module imports are correct:

   import std.io;  // Must match actual module path

3. Cross-module navigation requires all files to type-check successfully

Hover Not Showing Types

1. File must compile without errors

2. Cursor must be on a valid identifier

3. Check debug log for hover requests

LSP Capabilities

The Nic LSP server advertises these capabilities:

{
  "textDocumentSync": "incremental",
  "completionProvider": { "triggerCharacters": ["."] },
  "hoverProvider": true,
  "definitionProvider": true,
  "referencesProvider": true,
  "documentSymbolProvider": true,
  "semanticTokensProvider": { "full": true }
}

Protocol Details

Initialization

The server sends standard LSP initialization responses. No special configuration is required.

Text Synchronization

The server uses incremental text synchronization for efficiency. On each change:

1. Parse the updated file
2. Re-type-check affected modules
3. Send updated diagnostics

Semantic Tokens

Token types supported:

• namespace - Module names
• type - Type names
• class - Class names
• enum - Enum names
• function - Function names
• parameter - Parameters
• variable - Variables
• property - Struct fields
• keyword - Language keywords
• string, number - Literals
• comment - Comments

See Also

• CLI Commands - nicc lsp command
• Debugging - LSP debug logging