feat: integrate Gregorio Language Server Protocol (LSP) #9

lbssousa · 2025-10-17T20:03:11Z

Integrate Gregorio Language Server Protocol (LSP)

🎯 Overview

This PR adds comprehensive Language Server Protocol (LSP) integration to the VS Code GABC extension, enabling advanced language features for GABC/NABC files.

✨ Features Added

Core LSP Integration

✅ LSP client implementation (lsp-client.js)
✅ Automatic server discovery (development, package, global)
✅ Graceful degradation when server not found
✅ Status bar indicator for LSP connection
✅ Configuration change detection and auto-restart

Validation Features

✅ Real-time semantic validation of GABC/NABC files
✅ Header validation with error checking
✅ NABC-lines alternation validation for adiastematic neumes
✅ Quilisma validation with two types of diagnostics:
- Information: Glyph break suggestions (! before quilisma)
- Warning: Ascending motion validation
✅ Intelligent diagnostics (errors, warnings, information)

User Interface

✅ New command: "GABC: Restart Language Server"
✅ Status bar shows LSP connection state:
- ✓ Gregorio LSP (running)
- ⟳ Gregorio LSP (starting)
- ⚠ Gregorio LSP (stopped/error)

Configuration

Five new settings under "Gregorio LSP":

Setting	Type	Default	Description
`maxNumberOfProblems`	number	1000	Maximum diagnostics to report
`enableSemanticValidation`	boolean	true	Enable semantic validation
`enableNabcLinesValidation`	boolean	true	Enable NABC alternation checks
`strictAlternationChecking`	boolean	true	Treat alternation errors as errors (vs warnings)
`enableQuilismaValidation`	boolean	true	Enable quilisma validation

📁 Files Changed

New Files

lsp-client.js - LSP client implementation with auto-discovery
LSP_INTEGRATION.md - Complete setup and usage documentation

Modified Files

main.js - Integrated LSP activation/deactivation
package.json - Added configuration section, dependencies, and commands
package-lock.json - Updated with new dependencies
CHANGELOG.md - Documented v1.2.0 changes

🔧 Technical Details

Server Discovery

The client searches for gregorio-lsp in order:

../gregorio-lsp/out/server.js (development setup)
node_modules/gregorio-lsp/out/server.js (package)
../../gregorio-lsp/out/server.js (global)

Dependencies

Added: vscode-languageclient@^9.0.1

Activation

LSP client activates on onLanguage:gabc event
Integrates seamlessly with existing extension features
No impact on performance when server not found

📚 Documentation

LSP_INTEGRATION.md includes:

Overview of features
Setup instructions (development & NPM)
Configuration reference
Feature details with examples
Diagnostic codes reference
Troubleshooting guide
Development guide

Example Usage

Quilisma Validation

% Information: suggests glyph break
Text(gwh). (::)
% Suggested: Text(g!wh). (::)

% Warning: quilisma should ascend
Bad(gwf). (::)
% OK: h > g (ascending)
Good(gwh). (::)

NABC-lines Validation

nabc-lines: 1;
%%
Ky(f)ri(gh)e. (::)        % GABC - OK
vi1h pu2g Kyrie           % NABC - OK
Chri(g)ste. (::)          % GABC - OK

🧪 Testing

Manual Testing Checklist

Extension activates without LSP server
Extension activates with LSP server
Status bar shows correct LSP state
Diagnostics appear for invalid GABC
Quilisma suggestions work correctly
NABC-lines validation works
Configuration changes apply
Restart command works
No performance degradation

Test Files

Use existing test files:

examples/*.gabc - Various GABC examples
Create test files with quilisma for validation testing

🔗 Related Work

Depends On

gregorio-lsp (v0.1.0+)
- Commits: c5a56f4, 610c547, c11ee79
- Features: NABC detection, quilisma validation, documentation

Integration Points

Works with existing syntax highlighting
Compatible with preview feature
Extends existing commands

📈 Version

Previous: v1.1.0
Current: v1.2.0

🎯 Next Steps

After this PR is merged:

Publish updated extension to VS Code Marketplace
Publish gregorio-lsp as NPM package
Update documentation with installation links
Add integration tests
Implement code actions for quick fixes
Add auto-completion and hover providers

🚧 Draft Status

This PR is in draft mode for:

Testing with real-world GABC files
Verifying LSP server discovery
Gathering feedback on configuration options
Performance validation
Documentation review

📝 Checklist

💬 Feedback Welcome

Please test the integration and provide feedback on:

LSP feature usability
Configuration options
Documentation clarity
Performance impact
Edge cases or bugs

Related Issues: N/A (new feature)
Related PRs: N/A
Dependencies: gregorio-lsp repository

Add comprehensive LSP integration for advanced GABC language features. Features Added: - Language Server Protocol client implementation (lsp-client.js) - Real-time semantic validation of GABC/NABC files - Quilisma validation with glyph break suggestions - NABC-lines alternation validation - Header validation with error checking - Status bar indicator for LSP connection status - Command to restart language server Configuration: - Add 5 new settings under 'Gregorio LSP' * maxNumberOfProblems: limit diagnostic count * enableSemanticValidation: toggle validation * enableNabcLinesValidation: toggle NABC checks * strictAlternationChecking: error vs warning mode * enableQuilismaValidation: toggle quilisma checks Implementation: - lsp-client.js: LSP client with auto-discovery of server - main.js: integrated LSP activation/deactivation - package.json: added configuration section and dependencies - LSP_INTEGRATION.md: complete setup and usage documentation Dependencies: - Added vscode-languageclient@9.0.1 Server Discovery: The client automatically searches for gregorio-lsp in: 1. Adjacent directory (development setup) 2. node_modules (package installation) 3. Global installation path Graceful Degradation: If LSP server is not found, extension continues with basic features and shows informational message about missing server. Version: 1.1.0 → 1.2.0

Major improvements to LSP integration: BUNDLED SERVER: - Add gregorio-lsp as Git submodule in server/ - Automatic compilation on npm install (postinstall script) - No external dependencies required - Update command: npm run update-server - Falls back gracefully if external server configured but not found CONFIGURATION OPTIONS: - gregorioLsp.enabled: Enable/disable LSP entirely - gregorioLsp.serverPath: 'bundled' (default) or 'external' - gregorioLsp.externalServerPath: Path to external server - gregorioLsp.trace.server: Debug communication (off/messages/verbose) SERVER DISCOVERY: Priority order: 1. Check if LSP is enabled in settings 2. If serverPath='external', try externalServerPath 3. Try bundled server (server/out/server.js) 4. Try fallback locations (development, node_modules, global) 5. Show error if none found NPM SCRIPTS: - npm run compile: Compile bundled server - npm run compile:server: Compile server only - npm run watch:server: Watch mode for server development - npm run update-server: Update submodule and recompile - npm run postinstall: Auto-compile on install DOCUMENTATION: - Updated LSP_INTEGRATION.md with submodule setup - Added SERVER_README.md for submodule management - Updated CHANGELOG.md with new features - Added configuration examples for all scenarios IMPROVEMENTS: - Better error messages with configuration hints - Graceful degradation when server not available - Output channels for debugging (LSP + Trace) - Configuration validation before activation - Proper cleanup on deactivation FILES: - .gitignore: Ignore server build artifacts - .gitmodules: Submodule configuration - lsp-client.js: Enhanced server discovery logic - package.json: New scripts and configuration options - PR_DESCRIPTION.md: Updated PR description - SERVER_README.md: Submodule documentation This makes the extension fully self-contained while still allowing developers to use external servers for testing.

…de intelligence - Add tree-sitter-gregorio as Git submodule in parser/ directory - Implement tree-sitter-provider.js with 4 providers: * Semantic tokens provider (context-aware syntax highlighting) * Document symbols provider (outline view) * Folding ranges provider (structural code folding) * Selection ranges provider (smart selection) - Add 3 new configuration options under gregorioTreeSitter: * enabled: Enable/disable tree-sitter features (default: true) * bundledPath: Path to bundled parser (default: 'parser') * externalPath: Path to external parser for development - Add 'GABC: Reload Tree-sitter Parser' command - Add NPM scripts: compile:parser, watch:parser, update-parser - Update .gitignore to exclude parser build artifacts - Create comprehensive documentation: * TREE_SITTER_INTEGRATION.md: Technical integration guide * TREE_SITTER_COMPARISON.md: Visual comparison TextMate vs Tree-sitter * TREE_SITTER_EXAMPLE.md: Implementation examples * PARSER_README.md: Submodule management guide - Update LSP_INTEGRATION.md with tree-sitter information - Update CHANGELOG.md for v1.3.0 - Implement hybrid architecture: TextMate + Tree-sitter working together - Add tree-sitter dependency (v0.21.0) - Intelligent server discovery with priority: external → bundled → node_modules - Graceful fallback to TextMate when tree-sitter unavailable

Adiciona suporte completo a macros LaTeX para todos os cabeçalhos documentados: ✨ Novos cabeçalhos com LaTeX (3 tipos): - mode-differentia: Diferenças modais com formatação LaTeX - mode-modifier: Modificadores de modo com LaTeX - def-m0 até def-m9: Definições de macros com numeração destacada 🎨 Destaques especiais: - Números em def-m# recebem escopo constant.numeric.integer (verde) - Padrão separado para capturar prefixo e número individualmente - Consistência com headers LaTeX existentes 📝 Total de headers LaTeX: 10 tipos (20 variações com def-m0..9) 🔧 Alterações técnicas: - syntaxes/gabc.tmLanguage.json: linhas 131-168 * Novo padrão meta.header.def-macro.gabc (26 linhas) * Expandido meta.header.with-latex.gabc (2 novos headers) - Todos os patterns incluem latex-verbatim e latex-inline-command ✅ Validação: - JSON sem erros de sintaxe - Arquivo de teste com 60+ casos - Documentação completa (1300+ linhas) 📚 Documentação criada: - EXTENSION_ALL_LATEX_HEADERS.md: Análise completa - test-all-latex-headers.gabc: Suite de testes abrangente Refs: #9 - Implementações de melhorias de sintaxe

Resolved conflicts in package.json and package-lock.json: - Updated package name to 'gregorio' (from 'gabc-gregorian-chant-notation') - Maintained version 1.2.0 - Preserved LSP dependencies (tree-sitter, vscode-languageclient) - Updated engines.vscode to ^1.96.0 Merged changes from main: - Documentation updates in docs/ directory - Syntax highlighting improvements - CHANGELOG and README updates - Command title updates (GABC → Gregorio)

…tallation - Remove server and parser submodules (.gitmodules, .git/modules) - Add install-deps.js script for automatic GitHub release-based installation - Add install-deps.sh as Bash alternative for CI/CD environments - Update package.json scripts (install-deps, postinstall, compile, update-*) - Modify .gitignore to ignore entire server/ and parser/ directories - Add comprehensive DEPENDENCY_MANAGEMENT.md documentation - Add MIGRATION_FROM_SUBMODULES.md migration guide - Add scripts/README.md for quick reference Features: - Installs latest tagged release from GitHub (with fallback to main) - Automatic compilation via postinstall hook - Version tracking and reproducible builds - Colored console output for better UX - Error handling and retry logic Breaking Change: - server/ and parser/ directories no longer tracked in Git - Run 'npm install' to download and compile dependencies Benefits: - Semantic versioning with release tags - Reproducible builds across environments - Simplified Git workflow - Reduced repository size - CI/CD friendly (no submodule complexity) - Clear version tracking Tested: - ✅ install-deps.js successfully installs and compiles both dependencies - ✅ Fallback to main branch works when no releases exist - ✅ Server compiles to TypeScript → JavaScript - ✅ Parser generates and compiles native bindings - ✅ Extension loads correctly with compiled dependencies

- Add NEXT_STEPS.md with recommended actions post-migration - Include guidance for creating first releases - Document CI/CD updates needed - Provide long-term improvement suggestions - Add testing and automation recommendations

- Update install-deps.js to check for tags when no releases exist - Update install-deps.sh with same fallback logic - Priority: releases → tags → main branch - Tested with v0.1.0 tags successfully This allows using Git tags (v0.1.0) without requiring formal GitHub releases, making the version management more flexible. Tested: ✓ Detects tags v0.1.0 correctly for both dependencies ✓ Clones correct version ✓ Compiles successfully ✓ Both server and parser at version 0.1.0

- Document v0.1.0 tag deployment for both dependencies - Explain tag detection fallback mechanism (releases → tags → main) - Provide guidelines for semantic versioning - Include troubleshooting and best practices - Document version history and verification methods - Outline migration path to GitHub Releases Current versions: - gregorio-lsp: v0.1.0 (commit 794b5b1) - tree-sitter-gregorio: v0.1.0 (commit 38aab61)

- Comprehensive checklist for verifying v0.1.0 tag deployment - Step-by-step verification procedures - Quick verification commands - Troubleshooting references - Status tracking template This ensures the tagging process was successful and all components are working correctly.

- Update launch.json with LSP server debugging configuration - Add vscode-gregorio.code-workspace with LSP tracing enabled - Create LSP_DEBUGGING.md with complete debugging guide - Add configuration for attaching to LSP server on port 6009 Debugging features: - Two debug configurations: Run Extension + Attach to LSP Server - Verbose logging enabled by default in workspace - Step-by-step debugging instructions - Troubleshooting checklist - Test cases for NABC-lines validation - Output channel monitoring guide This makes it easier to debug and verify LSP functionality, especially for NABC-lines alternation pattern validation.

lbssousa added 2 commits October 17, 2025 17:01

lbssousa added the enhancement New feature or request label Oct 17, 2025

lbssousa added 7 commits October 21, 2025 08:09

docs: add next steps guide after submodule migration

002c5d7

- Add NEXT_STEPS.md with recommended actions post-migration - Include guidance for creating first releases - Document CI/CD updates needed - Provide long-term improvement suggestions - Add testing and automation recommendations

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: integrate Gregorio Language Server Protocol (LSP) #9

feat: integrate Gregorio Language Server Protocol (LSP) #9

Uh oh!

lbssousa commented Oct 17, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

feat: integrate Gregorio Language Server Protocol (LSP) #9

Are you sure you want to change the base?

feat: integrate Gregorio Language Server Protocol (LSP) #9

Uh oh!

Conversation

lbssousa commented Oct 17, 2025

Integrate Gregorio Language Server Protocol (LSP)

🎯 Overview

✨ Features Added

Core LSP Integration

Validation Features

User Interface

Configuration

📁 Files Changed

New Files

Modified Files

🔧 Technical Details

Server Discovery

Dependencies

Activation

📚 Documentation

LSP_INTEGRATION.md includes:

Example Usage

Quilisma Validation

NABC-lines Validation

🧪 Testing

Manual Testing Checklist

Test Files

🔗 Related Work

Depends On

Integration Points

📈 Version

🎯 Next Steps

🚧 Draft Status

📝 Checklist

💬 Feedback Welcome

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants