MODSIM III Language Server

A high-performance Language Server Protocol (LSP) implementation for the MODSIM III simulation language, providing intelligent code editing features for modern IDEs and editors.

Overview

The MODSIM III Language Server brings modern IDE features to the MODSIM III simulation language, including auto-completion, go-to-definition, find references, hover documentation, diagnostics, and more. Built from the ground up with a focus on correctness and performance, it has been validated against the 988-file RAMS production codebase with a 94% parse success rate.

What is MODSIM III?

MODSIM III is an object-oriented, discrete-event simulation language developed at CACI. It combines the power of object-oriented programming with simulation-specific constructs like WAIT, ASK, and TELL statements. The language is widely used in aerospace, defense, and logistics simulation applications.

Features

Core Language Support

• ✅ Complete Lexer - Tokenizes all MODSIM III constructs including keywords, operators, literals, and nestable comments
• ✅ Full Parser - Parses 98% of MODSIM III language features including:
  • Module structures (DEFINITION, IMPLEMENTATION, MAIN, PROGRAM)
  • Object-oriented features (objects, inheritance, methods, PROTO types)
  • All statement types (IF, WHILE, FOR, FOREACH, CASE, LOOP, REPEAT, WAIT)
  • Complex expressions with proper precedence
  • Import/export statements
• ✅ Semantic Analysis - Type checking, scope resolution, MODSIM-specific validation

LSP Features

• ✅ Auto-Completion - Context-aware completions for keywords, symbols, and code snippets
• ✅ Go-to-Definition - Navigate to symbol definitions across files
• ✅ Find References - Find all usages of a symbol workspace-wide
• ✅ Hover Information - Type info, signatures, and documentation on hover
• ✅ Diagnostics - Real-time error and warning detection with helpful messages
• ✅ Document Symbols - Outline view showing module structure
• ✅ Semantic Tokens - Accurate syntax highlighting based on semantic analysis
• ✅ Signature Help - Parameter hints for procedures and methods
• ✅ Code Actions - Quick fixes and refactorings
• ✅ Rename Refactoring - Safely rename symbols across workspace
• ✅ Document Highlight - Highlight all occurrences of symbol under cursor
• ✅ Folding Ranges - Code folding for modules, procedures, objects, and control structures

Performance

• ⚡ Fast Parsing - Average 5.75ms per file, 174 files/second throughput
• ⚡ Scalable - Tested on 988-file RAMS codebase without crashes
• ⚡ Efficient - Low memory footprint, suitable for large projects

Production Ready

• ✅ 94% Success Rate on RAMS production codebase (929/988 files)
• ✅ 370+ Unit Tests with 96.4% pass rate
• ✅ Comprehensive Error Detection - Identifies genuine syntax errors
• ✅ Root Cause Analysis - Detailed error reporting with context

Installation

Using npx (Recommended)

No installation required! The language server can be invoked directly:

npx modsim-language-server --stdio

Global Installation

npm install -g modsim-language-server
modsim-language-server --stdio

Local Installation

npm install modsim-language-server
npx modsim-language-server --stdio

Quick Start

VS Code

1. Install a generic LSP client extension (e.g., "vscode-languageclient")
2. Configure it to launch the MODSIM language server:

{
  "languageServerExample.server": {
    "command": "npx",
    "args": ["modsim-language-server", "--stdio"]
  },
  "files.associations": {
    "*.mod": "modsim"
  }
}

Neovim (nvim-lspconfig)

Add to your Neovim configuration:

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

-- Define MODSIM server
if not configs.modsim then
  configs.modsim = {
    default_config = {
      cmd = {'npx', 'modsim-language-server', '--stdio'},
      filetypes = {'modsim'},
      root_dir = lspconfig.util.root_pattern('.git'),
    },
  }
end

-- Set up MODSIM server
lspconfig.modsim.setup{}

-- Associate .mod files with modsim filetype
vim.filetype.add({
  extension = {
    mod = 'modsim',
  },
})

IntelliJ IDEA

1. Install the "LSP Support" plugin
2. Configure it to launch npx modsim-language-server --stdio
3. Map .mod files to the MODSIM language server

See docs/intellij-setup.md for detailed instructions.

Editor Setup Guides

Detailed setup instructions for specific editors:

• VS Code Setup - Step-by-step VS Code configuration
• IntelliJ IDEA Setup - IntelliJ IDEA and PyCharm
• Vim/Neovim Setup - Vim and Neovim with coc.nvim or native LSP

Usage

Command Line Options

modsim-language-server [options]

Options:
  --stdio          Use stdio for communication (default)
  --socket=<port>  Use socket on specified port
  --version        Show version number
  --help          Show help

Workspace Setup

The language server automatically indexes all .mod files in your workspace:

my-project/
├── source/
│   ├── Module1.mod
│   ├── Module2.mod
│   └── ...
└── .git/

Simply open the workspace folder in your editor and the language server will:

1. Index all .mod files
2. Build cross-file symbol tables
3. Resolve imports and dependencies
4. Provide intelligent features

Validation Results

RAMS Codebase Testing

The language server has been extensively tested on the RAMS production codebase:

• Total Files: 988 MODSIM III modules
• Parse Success: 929 files (94.0%)
• Performance: 5.68 seconds total (5.75ms average per file)
• Stability: Zero crashes during testing

Parse Error Analysis

The 59 files (6%) that don't parse contain genuine source code errors:

• 5 critical typos causing ~30 cascade failures (documented in test reports)
• Additional syntax errors requiring fixes in source code

Key Finding: Parser correctly identifies errors. With 5 simple fixes to RAMS source, parse rate would reach ~97%.

See test-results/rams-validation-report.md for detailed analysis.

Troubleshooting

Language server not starting

1. Check that Node.js is installed: node --version
2. Try running directly: npx modsim-language-server --stdio
3. Check editor LSP client logs for error messages

No completions or features working

1. Verify .mod file extension is recognized
2. Check that the language server process is running
3. Ensure workspace contains .mod files
4. Check LSP client configuration in your editor

Slow performance or high memory usage

1. The language server is optimized for large codebases
2. If issues persist, try:
   • Closing other applications
   • Limiting workspace to specific directories
   • Reporting performance metrics via GitHub Issues

False error reports

1. Verify your MODSIM code is valid (check with MODSIM compiler)
2. Known limitations:
   • Some edge cases may not be supported
   • Report issues with code samples via GitHub
3. See LANGUAGE_GAP_ANALYSIS.md for known gaps

Architecture

Component Overview

┌─────────────────────────────────────────┐
│         LSP Client (Editor)             │
└────────────────┬────────────────────────┘
                 │ JSON-RPC over stdio
┌────────────────▼────────────────────────┐
│         LSP Server (server.ts)          │
│  - Connection Management                │
│  - Document Lifecycle                   │
│  - Request Routing                      │
└────────────────┬────────────────────────┘
                 │
    ┌────────────┼────────────┐
    │            │            │
┌───▼────┐  ┌───▼─────┐  ┌──▼──────┐
│ Lexer  │  │ Parser  │  │Analyzer │
└───┬────┘  └───┬─────┘  └──┬──────┘
    │           │            │
┌───▼───────────▼────────────▼───────┐
│      Workspace Manager              │
│  - Multi-file Indexing              │
│  - Symbol Table                     │
│  - Dependency Resolution            │
└─────────────────────────────────────┘

Key Design Decisions

1. No AST Caching - Parsing is fast enough (5.75ms avg) that caching isn't needed
2. Workspace-Wide Symbols - All files indexed for cross-file navigation
3. Error Recovery - Parser continues after errors for better diagnostics
4. MODSIM-Specific Validation - Enforces language rules (ASK/TELL, WAIT, parameter modes)

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Development Setup

# Clone repository
git clone https://github.com/yourusername/modsim-language-server.git
cd modsim-language-server

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Run specific test file
npm test -- lexer.test.ts

# Lint
npm run lint

# Format
npm run format

Project Structure

lsp/
├── src/
│   ├── language/        # Core language implementation
│   │   ├── lexer.ts     # Tokenizer
│   │   ├── parser.ts    # AST generator
│   │   ├── analyzer.ts  # Semantic analysis
│   │   ├── symbols.ts   # Symbol table
│   │   └── ast.ts       # AST definitions
│   ├── features/        # LSP feature providers
│   ├── utils/           # Utilities (logging, workspace)
│   ├── server.ts        # LSP server
│   └── cli.ts           # CLI entry point
├── test/
│   └── fixtures/        # Test MODSIM files
├── scripts/             # Build and test scripts
└── docs/                # Documentation

FAQ

What MODSIM III features are supported?

The language server supports ~98% of MODSIM III language features. See LANGUAGE_GAP_ANALYSIS.md for details on missing features.

Does it work with MODSIM II?

Not currently. The parser is designed specifically for MODSIM III syntax. MODSIM II support may be added in the future.

Can I use this with my proprietary MODSIM code?

Yes! The language server processes files locally and doesn't send any code externally. It's safe for proprietary and classified codebases.

What's the difference between parse errors and diagnostics?

• Parse errors - Syntax errors that prevent building an AST (missing END keywords, malformed expressions)
• Diagnostics - Semantic errors in valid syntax (type mismatches, undefined symbols, unused variables)

How do I report issues?

Please open an issue on GitHub with:

1. MODSIM code sample that reproduces the issue
2. Expected behavior
3. Actual behavior (error message, incorrect feature)
4. Editor and language server version

Roadmap

Version 1.0 (Current)

• ✅ Complete lexer and parser
• ✅ All LSP features
• ✅ 94% RAMS compatibility
• ✅ Production-ready performance

Version 1.1 (Planned)

• [ ] VS Code extension on marketplace
• [ ] Improved error recovery
• [ ] More code actions (extract method, etc.)
• [ ] Configuration file support

Version 2.0 (Future)

• [ ] Incremental parsing for live editing
• [ ] AST/symbol caching
• [ ] Workspace-wide refactorings
• [ ] Call hierarchy provider
• [ ] Type hierarchy provider

Resources

MODSIM III Documentation

• MODSIM III Language Guide
• MODSIM III Reference Manual

Language Server Protocol

• LSP Specification
• LSP Implementations

License

MIT License - see LICENSE file for details.

Acknowledgments

• CACI for the MODSIM III language
• Microsoft for the Language Server Protocol specification
• The RAMS project team for providing validation data and feedback

Developed with ❤️ for the MODSIM simulation community

For support, questions, or feedback, please open an issue on GitHub.