Metadata-Version: 2.4
Name: synesis-lsp
Version: 0.21.0
Summary: Language Server Protocol para Synesis v1.1
Author-email: Synesis Project <noreply@synesis.org>
License-Expression: AGPL-3.0-only AND LicenseRef-Synesis-data-output-exception
Project-URL: Homepage, https://github.com/synesis-lang/synesis-lsp
Project-URL: Repository, https://github.com/synesis-lang/synesis-lsp
Project-URL: Issues, https://github.com/synesis-lang/synesis-lsp/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Text Editors :: Integrated Development Environments (IDE)
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: LICENSE.exception
Requires-Dist: synesis>=0.10.0
Requires-Dist: pygls<2.0.0,>=1.0.0
Requires-Dist: lsprotocol<2024.0.0,>=2023.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.20.0; extra == "dev"
Requires-Dist: jsonschema>=4.18; extra == "dev"
Requires-Dist: ruff==0.15.17; extra == "dev"
Requires-Dist: mypy==1.16.0; extra == "dev"
Provides-Extra: release
Requires-Dist: build>=1.2.0; extra == "release"
Requires-Dist: twine>=5.0.0; extra == "release"
Dynamic: license-file

# synesis-lsp

**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.

[![PyPI version](https://img.shields.io/pypi/v/synesis-lsp)](https://pypi.org/project/synesis-lsp/)
[![Python 3.10+](https://img.shields.io/pypi/pyversions/synesis-lsp)](https://pypi.org/project/synesis-lsp/)
[![License: AGPL v3](https://img.shields.io/badge/License-AGPL%20v3%20%2B%20exception-blue.svg)](https://github.com/synesis-lang/synesis-lsp/blob/main/LICENSE)

> **Copyright (c) 2011–2026 Christian Maciel de Britto**
> [`https://github.com/synesis-lang`](https://github.com/synesis-lang) · [`ORCID`](https://orcid.org/0000-0003-1431-3924)

---

## What is synesis-lsp?

`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.

---

## Features

- **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`, `ONTOLOGY` blocks
- **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`

---

## Requirements

- Python 3.10+
- `synesis` compiler ≥ 0.5.5

---

## Installation

```bash
pip install synesis
pip install synesis-lsp
```

**From source:**
```bash
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-lsp
```

---

## Usage

### Standalone server (STDIO)

```bash
python -m synesis_lsp
```

The server communicates via JSON-RPC over STDIO and is compatible with any LSP client.

### VS Code

The **Synesis Explorer** extension manages the LSP server automatically. No manual configuration required — install the extension, open a Synesis project, and the server starts.

### Workspace requirements

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.

---

## Architecture

```
┌─────────────┐
│   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](https://github.com/synesis-lang/synesis/issues).

---

## Custom LSP Commands

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 |

---

## Compatibility

| 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 |

---

## Troubleshooting

**`Error: Package 'synesis' not found`**
```bash
pip install synesis
```

**LSP does not validate after editing**

1. Check logs: *Output → Synesis LSP* in VS Code
2. Reload window: `Ctrl+Shift+P → Reload Window`
3. Ensure `.synp` references the correct template and bibliography
4. 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:
```bash
synesis check your_file.syn
```
If the CLI also reports it, the issue is in the compiler — report it in the [compiler repository](https://github.com/synesis-lang/synesis/issues). If the CLI passes but the LSP flags it, report in the [LSP repository](https://github.com/synesis-lang/synesis-lsp/issues).

---

## Development

```bash
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 LSP `Range` (0-based)
- If you change error/result contracts, update `INTERFACES.md` and `converters.py`
- Keep the server resilient: exceptions must become diagnostics, never crashes

---

## Project Structure

```
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
```

---

## Intellectual Genealogy

`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](https://github.com/synesis-lang/synesis#intellectual-genealogy) and the project's [NOTICE file](https://github.com/synesis-lang/synesis/blob/main/NOTICE) for the full intellectual genealogy and copyright notices for predecessor works.

---

## License

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](https://github.com/synesis-lang/synesis-lsp/blob/main/LICENSE) and
[LICENSE.exception](https://github.com/synesis-lang/synesis-lsp/blob/main/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.

---

## References

- [Synesis compiler](https://github.com/synesis-lang/synesis) — the core engine this server wraps
- [Synesis Explorer](https://github.com/synesis-lang/synesis-explorer) — VS Code extension
- [LSP Specification](https://microsoft.github.io/language-server-protocol/)
- [pygls Documentation](https://pygls.readthedocs.io/)
- [Interfaces and Contracts](https://github.com/synesis-lang/synesis-lsp/blob/main/INTERFACES.md)
- [Changelog](https://github.com/synesis-lang/synesis-lsp/blob/main/CHANGELOG.md)

---

## Author

**Dr. Christian Maciel de Britto**

[GitHub](https://github.com/synesis-lang) · [ORCID](https://orcid.org/0000-0003-1431-3924) · [Lattes](https://lattes.cnpq.br/2334832147379385)
