Real-time validation and language intelligence for Synesis projects.
A Language Server Protocol (LSP) implementation that brings the full power of the Synesis compiler into VS Code and any LSP-compatible editor — diagnostics, hover, completion, semantic tokens, relation graphs, and more.
Copyright (c) 2011–2026 Christian Maciel de Britto
https://github.com/synesis-lang·ORCID
synesis-lsp is a protocol adapter, not a second parser. All validation is delegated entirely to the Synesis compiler — the server translates compiler output into LSP diagnostics and editor features. This means the language server and the CLI always agree: if synesis check passes, the editor shows no errors.
The result is a live editorial environment where ontological constraints, required fields, and relational rules are enforced as you type — with pedagogical error messages that explain why a construct is invalid, not just that it is.
- Real-time validation — syntax and semantic errors as you type, delegated to the Synesis compiler
- Pedagogical diagnostics — clear explanations of template rules,
REQUIRED/OPTIONAL,BUNDLE,ARITY - Semantic tokens — AST-driven syntax highlighting (not regex)
- Document symbols — structured outline of
SOURCE,ITEM,ONTOLOGYblocks - Hover documentation — field definitions, ontology entries, and template rules on hover
- Completion — context-aware suggestions for codes, bibrefs, relation types, and field names
- Inlay hints — inline field type annotations
- Go-to-definition & Rename — for bibrefs and ontology codes, across files
- Relation graph — Mermaid diagram of the current project's relational structure
- Fuzzy matching — suggestions for mistyped bibrefs and codes
- Full file type support —
.syn,.synp,.synt,.syno
- Python 3.10+
synesiscompiler ≥ 0.5.5
pip install synesis
pip install synesis-lspFrom source:
git clone https://github.com/synesis-lang/synesis.git
git clone https://github.com/synesis-lang/synesis-lsp.git
pip install -e synesis
pip install -e synesis-lsppython -m synesis_lspThe server communicates via JSON-RPC over STDIO and is compatible with any LSP client.
The Synesis Explorer extension manages the LSP server automatically. No manual configuration required — install the extension, open a Synesis project, and the server starts.
For full semantic validation, the workspace should contain:
| File | Role |
|---|---|
*.synp |
Project file — required for full validation |
*.synt |
Template referenced by .synp |
*.bib |
BibTeX bibliography |
*.syn |
Annotation files |
*.syno |
Ontology files |
Without a
.synp, the LSP provides syntax validation and grammar keywords only — no template or ontology enforcement.
┌─────────────┐
│ VS Code │ (or any LSP client)
└──────┬──────┘
│ JSON-RPC / STDIO
▼
┌──────────────────────────────────┐
│ synesis_lsp.server │
│ │
│ Handlers: did_open, did_change │
│ Providers: tokens · symbols │
│ hover · completion │
│ definition · inlay │
│ signature · rename │
│ Commands: loadProject · stats │
│ explorer · graph │
└──────┬───────────────────────────┘
│ delegates all validation to
▼
┌──────────────────────────────────┐
│ synesis.lsp_adapter │
│ validate_single_file() │
│ Context discovery │
└──────┬───────────────────────────┘
│
▼
┌──────────────────────────────────┐
│ synesis.compiler │
│ Lark LALR(1) parser │
│ Semantic validator │
│ ValidationResult │
└──────────────────────────────────┘
Design principle: this layer never re-implements parsing or semantics. If a diagnostic is incorrect, the issue is in the compiler — reproduce it with synesis check file.syn and report in the compiler issue tracker.
Cross-file features (hover, definition, completion, rename, graph) depend on the workspace cache loaded via synesis/loadProject.
| Command | Description |
|---|---|
synesis/loadProject |
Load and cache the full project |
synesis/getProjectStats |
Compilation statistics |
synesis/getReferences |
All source references in scope |
synesis/getCodes |
All ontology codes in scope |
synesis/getRelations |
All declared relation types |
synesis/getRelationGraph |
Mermaid diagram of project relations |
| Package | Latest | Requires synesis | Python |
|---|---|---|---|
| synesis | 0.6.0 | — | ≥ 3.10 |
| synesis-lsp | 0.16.0 | ≥ 0.5.5 | ≥ 3.10 |
| synesis-coder | 0.4.1 | ≥ 0.5.5 | ≥ 3.10 |
| synesis-graph | 0.2.0 | ≥ 0.5.5 | ≥ 3.10 |
Error: Package 'synesis' not found
pip install synesisLSP does not validate after editing
- Check logs: Output → Synesis LSP in VS Code
- Reload window:
Ctrl+Shift+P → Reload Window - Ensure
.synpreferences the correct template and bibliography - Look for log messages:
Projeto Synesis carregado,Template carregado,Bibliografia carregada
Incorrect diagnostics
The LSP delegates all validation to the compiler. To isolate the issue:
synesis check your_file.synIf the CLI also reports it, the issue is in the compiler — report it in the compiler repository. If the CLI passes but the LSP flags it, report in the LSP repository.
pip install -e ".[dev]"
pytest tests/
pytest --cov=synesis_lsp tests/Contributing guidelines:
- This server is a protocol adapter — do not implement parsing or semantics here
- All validation must use
synesis.lsp_adapter.validate_single_file - Always convert
SourceLocation(1-based) to LSPRange(0-based) - If you change error/result contracts, update
INTERFACES.mdandconverters.py - Keep the server resilient: exceptions must become diagnostics, never crashes
synesis-lsp/
├── synesis_lsp/
│ ├── server.py # LSP server (pygls)
│ ├── converters.py # ValidationError → LSP Diagnostic
│ ├── cache.py # Workspace cache
│ ├── semantic_tokens.py # Semantic tokens
│ ├── symbols.py # Document symbols
│ ├── hover.py # Hover provider
│ ├── definition.py # Go-to-definition
│ ├── completion.py # Autocomplete
│ ├── inlay_hints.py # Inlay hints
│ ├── graph.py # Relation graph (Mermaid)
│ ├── rename.py # Rename provider
│ └── explorer_requests.py # Custom explorer commands
├── tests/
├── INTERFACES.md # Compiler ↔ LSP contracts
├── CHANGELOG.md
├── LICENSE
└── README.md
synesis-lsp is part of the Synesis ecosystem. The compiler and language it serves are the formal culmination of a research and development trajectory spanning more than a decade. See the compiler README and the project's NOTICE file for the full intellectual genealogy and copyright notices for predecessor works.
This program is distributed under the GNU Affero General Public License, version 3 only (AGPL-3.0-only), with the Synesis Data-Output Exception — see LICENSE and LICENSE.exception.
SPDX identifier: AGPL-3.0-only AND LicenseRef-Synesis-data-output-exception
Your research data and outputs are yours. Files you author and the
artifacts Synesis produces from them are not covered by the AGPL and carry
no copyleft obligation toward Synesis. See LICENSE.exception for the terms.
The AGPL applies to synesis-lsp itself: if you modify it and distribute it, or run it as a network service, you must share your changes under the AGPL.
Releases published before this change remain available under the MIT license they were issued under.
This license grants no rights to the "Synesis" name or logo.
- Synesis compiler — the core engine this server wraps
- Synesis Explorer — VS Code extension
- LSP Specification
- pygls Documentation
- Interfaces and Contracts
- Changelog
Dr. Christian Maciel de Britto