FHIRPath Language Server Protocol

A comprehensive Language Server Protocol implementation for FHIRPath with VS Code extension support, providing intelligent features for FHIR healthcare data queries.

🚀 Features

✅ Core Language Support (Phase 1)

Syntax Highlighting - Comprehensive TextMate grammar for FHIRPath
Error Detection - Real-time syntax validation with precise error positioning
Language Configuration - Bracket matching, auto-closing, and folding support
Document Synchronization - Incremental text updates with caching

✅ Intelligence Features (Phase 2)

Auto-completion - Context-aware suggestions for functions, operators, and FHIR resources
Semantic Highlighting - Enhanced syntax highlighting with proper token classification
Hover Documentation - Rich tooltips with function documentation and live expression evaluation
FHIR Validation - Resource path validation against FHIR R4 specifications
Performance Optimization - Advanced LRU caching with performance metrics

🚀 Advanced Features

Multi-expression Support - Parse and validate semicolon-separated expressions
Live Expression Evaluation - Real-time evaluation in hover when context data is available
Rich Formatting - Markdown documentation with collapsible sections and visual badges
Context Analysis - Document-level context parsing and intelligent validation
Centralized Configuration - Unified configuration management with type safety and validation

📁 Project Structure

fhirpath-lsp/
├── client/                    # VS Code extension client
│   ├── src/extension.ts       # Extension entry point
│   └── package.json           # Extension manifest
├── server/                    # Language server implementation
│   ├── src/
│   │   ├── server.ts          # Main LSP server
│   │   ├── parser/
│   │   │   └── FHIRPathService.ts        # Parser integration
│   │   ├── providers/
│   │   │   ├── CompletionProvider.ts     # Auto-completion
│   │   │   ├── SemanticTokensProvider.ts # Semantic highlighting
│   │   │   ├── HoverProvider.ts          # Hover documentation
│   │   │   ├── DiagnosticProvider.ts     # Error detection
│   │   │   └── FHIRValidationProvider.ts # FHIR validation
│   │   └── services/
│   │       ├── FHIRPathFunctionRegistry.ts # Function definitions
│   │       ├── FHIRResourceService.ts      # FHIR resource schemas
│   │       ├── CacheService.ts             # Performance caching
│   │       ├── DocumentService.ts          # Document management
│   │       └── FHIRPathContextService.ts   # Context analysis
│   └── package.json
├── shared/                    # Shared types and utilities
│   ├── src/
│   │   ├── types.ts          # Common interfaces
│   │   └── index.ts          # Shared exports
│   └── package.json
├── syntaxes/
│   └── fhirpath.tmGrammar.json # TextMate grammar
├── test/                      # Test cases and examples
│   ├── *.fhirpath            # Test expressions
│   ├── patient-example.json  # Sample FHIR data
│   └── vital-signs-data.json # Sample context data
├── tasks/                     # Development task tracking
├── adr/                       # Architecture Decision Records
└── package.json              # Root workspace configuration

🛠️ Installation & Setup

Prerequisites

Bun runtime (recommended) or Node.js 18+
VS Code 1.84+

Build from Source

Clone the repository

git clone https://github.com/atomic-ehr/fhirpath-lsp.git
cd fhirpath-lsp

Install dependencies

bun install:all
# or individually:
# bun install && cd client && bun install && cd ../server && bun install && cd ../shared && bun install

Build the extension
```
bun run build
```
Run in development
```
bun run dev
```

⚙️ Configuration

The FHIRPath LSP server uses a centralized configuration system that supports multiple configuration sources with automatic validation and type safety.

Configuration Sources (in priority order)

Workspace Configuration - .fhirpath-lsp.json in your project root
User Configuration - ~/.fhirpath-lsp/config.json
Environment Variables - FHIRPATH_LSP_* prefixed variables
Runtime Configuration - Dynamic updates via LSP

Example Configuration

Create a .fhirpath-lsp.json file in your workspace root:

{
  "diagnostics": {
    "enabled": true,
    "performance": {
      "maxComplexity": 15,
      "maxNestingDepth": 6,
      "flagRedundantOperations": true
    },
    "codeQuality": {
      "maxLineLength": 120,
      "flagMagicValues": true
    },
    "fhirBestPractices": {
      "enforceTypeSafety": true,
      "checkCardinality": true
    }
  },
  "providers": {
    "completion": {
      "maxSuggestions": 75,
      "includeSnippets": true
    },
    "hover": {
      "includeExamples": true,
      "maxContentLength": 1200
    },
    "performance": {
      "requestThrottling": {
        "enabled": true,
        "configs": [
          {
            "requestType": "completion",
            "limit": 15,
            "windowMs": 1000
          }
        ]
      }
    }
  }
}

Environment Variables

You can also configure the server using environment variables:

# Diagnostic configuration
export FHIRPATH_LSP_DIAGNOSTICS_PERFORMANCE_MAX_COMPLEXITY=20
export FHIRPATH_LSP_DIAGNOSTICS_CODE_QUALITY_MAX_LINE_LENGTH=120

# Provider configuration
export FHIRPATH_LSP_PROVIDERS_COMPLETION_MAX_SUGGESTIONS=100
export FHIRPATH_LSP_PROVIDERS_HOVER_INCLUDE_EXAMPLES=true

Configuration Validation

The system automatically validates all configuration values and provides helpful error messages for invalid settings. Configuration changes are applied in real-time without requiring a server restart.

For complete configuration documentation, see server/src/config/README.md.

🐛 Local Development & Debugging

Development Environment Setup

Open in VS Code
```
code .
```
Install recommended extensions (when prompted)
- TypeScript and JavaScript Language Features
- ESLint
- Prettier

Debugging the Extension

Method 1: Using the Development Script

bun run dev

This builds the extension and opens a new VS Code window with the extension loaded.

Method 2: Using VS Code Debug Configuration

Open the project in VS Code
Go to Run and Debug (Ctrl+Shift+D)
Select "Launch Extension" from the dropdown
Press F5 or click the green play button

This will:

Build the extension automatically
Launch a new VS Code window (Extension Development Host)
Attach the debugger to both client and server processes

Method 3: Manual Debugging Steps

Build the project
```
bun run build
```
Open Command Palette (Ctrl+Shift+P)
Run "Developer: Reload Window" to reload the extension
Open a .fhirpath file to activate the extension

Testing Language Features

Create a test file with .fhirpath extension:

// Test basic syntax highlighting
Patient.name.where(use = 'official').given.first()

// Test auto-completion (type Patient. and see suggestions)
Patient.

// Test FHIR validation (this should show an error)
Patient.invalidProperty

// Test multi-expression support
Patient.name.given.first();
Patient.birthDate

Test features:
- Syntax Highlighting: Different colors for keywords, functions, strings
- Auto-completion: Type Patient. and press Ctrl+Space
- Hover: Hover over functions like where() or first()
- Error Detection: Invalid syntax should show red squiggles
- FHIR Validation: Invalid properties should show warnings

Debugging with Context Data

Add context declaration at the top of your .fhirpath file:

// @context Patient test/patient-example.json
Patient.name.given.first()

Features with context:
- Hover shows actual evaluation results
- More accurate FHIR validation
- Enhanced completion suggestions

Debugging Server Issues

Enable server tracing in VS Code settings:

{
  "fhirpath.trace.server": "verbose"
}

View server logs:
- Open Output panel (Ctrl+Shift+U)
- Select FHIRPath Language Server from dropdown
Common issues:
- Server not starting: Check the Output panel for errors
- Features not working: Verify the server is running and connected
- Performance issues: Check cache statistics in server logs

Development Commands

# Build all workspaces
bun run build

# Build with watch mode
bun run watch

# Type checking
bun run typecheck

# Run tests
bun run test

# Clean build outputs
bun run clean

# Lint code
bun run lint

# Format code
bun run format

# Package extension for distribution
bun run package

Debugging Configuration Files

The project includes VS Code debugging configurations in .vscode/:

launch.json: Debug configurations for client and server
tasks.json: Build tasks and shortcuts
settings.json: Workspace-specific settings

📊 Performance Metrics

Current performance targets (all met):

Auto-completion response: < 200ms
Semantic token generation: < 100ms
Hover information: < 150ms
FHIR validation: < 300ms
Memory usage: < 35MB for server process
Cache hit rate: > 80% for repeated operations

🧪 Testing

Test Files Available

test/basic-test.fhirpath - Basic syntax and functions
test/context-test.fhirpath - Context-aware evaluation
test/diagnostic-test.fhirpath - Error detection
test/multi-expression-test.fhirpath - Multiple expressions
test/patient-example.json - Sample FHIR Patient resource
test/vital-signs-data.json - Sample observation data

Running Tests

bun run test

📈 Implementation Status

✅ Phase 1: Foundation (Complete)

LSP server structure
Parser integration (@atomic-ehr/fhirpath)
TextMate grammar for syntax highlighting
Diagnostic provider for syntax errors
VS Code extension client
Document synchronization

✅ Phase 2: Intelligence (Complete)

Auto-completion provider with function registry
Semantic token provider for enhanced highlighting
Hover provider with comprehensive documentation
FHIR resource path validation
Performance optimization with caching
Multi-expression support
Live expression evaluation

🔄 Phase 3: Advanced Features (Planned)

Code formatting and refactoring
Go-to-definition and find references
Workspace symbol search
Integration with FHIR servers
Advanced diagnostics and quick fixes

🏗️ Architecture

The project follows a clean architecture with clear separation of concerns:

Client: VS Code extension handling UI interactions
Server: Language server implementing LSP protocol
Shared: Common types and utilities
Parser: Integration with @atomic-ehr/fhirpath library
Providers: Feature-specific implementations (completion, hover, etc.)
Services: Core business logic and data management

See ADR-001 for detailed architecture decisions.

🤝 Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes following the existing code style
Add tests for new functionality
Ensure all tests pass (bun run test)
Run type checking (bun run typecheck)
Format code (bun run format)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Related Projects

@atomic-ehr/fhirpath - Core FHIRPath parser
FHIR R4 Specification
FHIRPath Specification

📞 Support

Create an issue for bug reports
Start a discussion for questions
Check existing issues before creating new ones

Built with ❤️ by the Atomic EHR Team

Name		Name	Last commit message	Last commit date
Latest commit History 20 Commits
.cursor/rules		.cursor/rules
.vscode		.vscode
adr		adr
client		client
data		data
docs		docs
examples		examples
schemas		schemas
server		server
shared		shared
spec		spec
syntaxes		syntaxes
test		test
.fhirpath-lsp.json		.fhirpath-lsp.json
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
FHIRPATH_LIBRARY_REQUIREMENTS.md		FHIRPATH_LIBRARY_REQUIREMENTS.md
MODEL_PROVIDER_ENHANCEMENTS.md		MODEL_PROVIDER_ENHANCEMENTS.md
README.md		README.md
build.js		build.js
bun.lock		bun.lock
language-configuration.json		language-configuration.json
package.json		package.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

FHIRPath Language Server Protocol

🚀 Features

✅ Core Language Support (Phase 1)

✅ Intelligence Features (Phase 2)

🚀 Advanced Features

📁 Project Structure

🛠️ Installation & Setup

Prerequisites

Build from Source

⚙️ Configuration

Configuration Sources (in priority order)

Example Configuration

Environment Variables

Configuration Validation

🐛 Local Development & Debugging

Development Environment Setup

Debugging the Extension

Method 1: Using the Development Script

Method 2: Using VS Code Debug Configuration

Method 3: Manual Debugging Steps

Testing Language Features

Debugging with Context Data

Debugging Server Issues

Development Commands

Debugging Configuration Files

📊 Performance Metrics

🧪 Testing

Test Files Available

Running Tests

📈 Implementation Status

✅ Phase 1: Foundation (Complete)

✅ Phase 2: Intelligence (Complete)

🔄 Phase 3: Advanced Features (Planned)

🏗️ Architecture

🤝 Contributing

📝 License

🔗 Related Projects

📞 Support

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages