Metadata-Version: 2.5
Name: pseudocode-i18n-languageserver
Version: 0.9.9
Summary: Language Server Protocol implementation for multilingual pseudocode-i18n
Project-URL: Documentation, https://rod2ik.gitlab.io/pseudocode-i18n-languageserver/
Project-URL: Repository, https://gitlab.com/rod2ik/pseudocode-i18n-languageserver
Project-URL: Issues, https://gitlab.com/rod2ik/pseudocode-i18n-languageserver/-/issues
Author: Rod2ik
License: GPL-3.0-or-later
License-File: LICENSE
Keywords: education,i18n,language-server,lsp,pseudocode
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Education
Classifier: Topic :: Software Development :: Compilers
Requires-Python: >=3.11
Requires-Dist: lsprotocol==2025.0.0
Requires-Dist: pseudocode-i18n<0.10,>=0.9.9
Requires-Dist: pygls<2.2,>=2.1.1
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: mkdocs-material>=9.6; extra == 'dev'
Requires-Dist: mkdocs<2,>=1.6; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.12; extra == 'dev'
Description-Content-Type: text/markdown

# pseudocode-i18n-languageserver

| Resource | Link | Purpose |
| --- | --- | --- |
| **pseudocode-i18n-languageserver — repository** | [gitlab.com/rod2ik/pseudocode-i18n-languageserver](https://gitlab.com/rod2ik/pseudocode-i18n-languageserver) | Shared Language Server Protocol implementation for Pseudocode editors and IDEs |
| **pseudocode-i18n-languageserver — documentation** | [rod2ik.gitlab.io/pseudocode-i18n-languageserver](https://rod2ik.gitlab.io/pseudocode-i18n-languageserver/) | Installation, features and editor integration |
| **pseudocode-i18n** | [gitlab.com/rod2ik/pseudocode-i18n](https://gitlab.com/rod2ik/pseudocode-i18n) | Parser, formatter, semantic analysis, i18n registry and editor-neutral semantic index |
| **pygments-lexer-pseudocode-i18n** | [gitlab.com/rod2ik/pygments-lexer-pseudocode-i18n](https://gitlab.com/rod2ik/pygments-lexer-pseudocode-i18n) | Pygments highlighting generated from the same language vocabulary |
| **mkdocs-pseudocode-i18n** | [gitlab.com/rod2ik/mkdocs-pseudocode-i18n](https://gitlab.com/rod2ik/mkdocs-pseudocode-i18n) | MkDocs rendering, MathJax and flowcharts |
| **vscode-pseudocode-i18n** | [gitlab.com/rod2ik/vscode-pseudocode-i18n](https://gitlab.com/rod2ik/vscode-pseudocode-i18n) | VS Code integration, execution and live visualization |

**Current version: 0.9.9.**
**Release history:** [pseudocode-i18n-languageserver changelog](https://rod2ik.gitlab.io/pseudocode-i18n-languageserver/reference/changelog/).
`pseudocode-i18n-languageserver` gives `.pseudo` and `.algo` files one reusable intelligence layer for open-source editors and educational IDEs. The server speaks the standard **Language Server Protocol (LSP)** over stdin/stdout and delegates the language itself to `pseudocode-i18n`.

Install it once:

```bash
python -m pip install 'pseudocode-i18n-languageserver>=0.9.9,<0.10'
```

On an externally managed Python installation, when you deliberately install into user/system packages:

```bash
python -m pip install --break-system-packages 'pseudocode-i18n-languageserver>=0.9.9,<0.10'
```

Check the command used by editors:

```bash
pseudo-lsp --version
```

You normally **do not launch `pseudo-lsp` yourself**. Kate, Neovim, Spyder or another LSP client starts it as a child process and communicates with it through stdin/stdout.

## Shared editor intelligence

`pseudo-lsp` exposes the coordinated editor contract while keeping the language itself in `pseudocode-i18n`:

- multiple localized diagnostics from the recovering core linter, with exact source ranges; parser-recovery fallback details are localized too, so backend English text never leaks into a diagnostic in another Pseudocode language;
- completion **plus retained frontend snippets** (including localized XOR expressions, `Do/Faire/...` loop forms and distinct range/stepped-range/collection-loop snippets), signature help, document symbols, definitions, references, rename and formatting; every structural snippet is linked to its exact shared documentation card instead of being matched only by its first word;
- hover documentation generated by the core for ordinary keywords **and structural grammar fragments** such as `Alors`, `fois`, `Jusqu'à` and every word of localized multi-word import aliases such as `en tant que`; complete recognized structures take priority over ambiguous fragments, so French range-loop `de`, `à`, `pas` and `Faire` show the correct range/stepped-range syntax rather than import help;
- import operands remain symbols rather than documentation keywords, preventing false hover/help on names such as an imported `sqrt`;
- all 14 source languages receive the same behavior without maintaining language-specific tables in the server;
- project-aware standard/local module resolution and strict type/operation diagnostics are preserved;
- `pseudocode/tutor` exposes the shared **`pseudocode-tutor/v2`** step-by-step execution model, including static flowchart snapshots with stable node/edge IDs, compact incremental output deltas and source-language human labels/values while canonical machine fields remain stable. The response also carries the cached `executable` state and the exact LSP diagnostic set: error-level diagnostics return a blocked Tutor model without constructing an execution session, while warnings/information accompany a normal executable model; no second lint or parse is performed;
- `pseudocode/flowchart` exposes the same shared flowchart model for static previews/export and keeps the Mermaid compatibility representation; semantic diagnostics do not block a graph when the original AST is structurally available. Symbol scopes carry localized `display_label` text beside canonical `name` / `kind`, and rich Tutor clients can render once and toggle stable IDs locally rather than requesting a new graph per step;
- each open-document model retains its parsed AST and caches Tutor sessions, symbol/scope lists and flowchart snapshots by document version, so diagnostics and custom requests reuse work already performed for the current source;
- custom Pseudocode requests share one document-parameter normalizer, accepting standard `textDocument.uri` plus compatibility fallbacks without duplicating parsing in editor plugins.

The server remains a thin LSP layer: source-language knowledge belongs to `pseudocode-i18n`, so VS Code, Thonny and other clients see the same diagnostics and help.

## Language-server capabilities

The server exposes the same language intelligence for all 14 supported natural languages:

- diagnostics from the native `pseudocode-i18n` parser and semantic linter, including multiple independent errors in one document, explicit type-contract mismatches and incompatible typed operations;
- project-aware module diagnostics: `math` and `random` are standard, while existing local `.pseudo` / `.algo` modules are resolved from the document/project path;
- i18n code completion **and the existing structural snippets**, using the normal language-resolution priority;
- completion for document symbols, localized built-ins, constants and types;
- pedagogical hover information for symbols, keywords, types and built-ins, with localized section labels and every accepted syntax synonym exposed;
- signature help;
- document symbols;
- go to definition;
- find references;
- prepare rename and rename;
- whole-document formatting; French repeat-until formatting canonically emits `Jusqu'à ...` while the longer accepted synonym remains valid;
- `.pseudo` and `.algo` as equivalent source extensions.

The server does **not** maintain a second grammar. `pseudocode-i18n` remains the source of truth for parsing, language detection, configuration, formatting, diagnostics, snippets and semantic indexing.

## Language and snippet resolution

A document uses the same precedence as the core:

1. explicit `# language: xx` / `# lang: xx` directive;
2. `language:` / `lang:` in `pseudocode.config.yml`;
3. automatic language detection;
4. `fallback_language`;
5. French as the final default.

This means typing a condition snippet in a French file proposes `Si … Alors`, while an English file proposes `If … Then`, without editor-specific copies of the snippet catalog.

## Editor targets

| Editor / IDE | Integration path |
| --- | --- |
| **Kate** | Native generic LSP client; ready to configure. A generated KSyntaxHighlighting definition is included. |
| **Neovim (`nvim`)** | Native LSP client; ready to configure. A Lua configuration is included. |
| **Spyder** | Supports LSP servers for “Other languages”; configuration guide included. |
| **Thonny 5** | `thonny-pseudocode-i18n` connects completion/snippets, hover, signature help, diagnostics, Ctrl+click navigation, rename and formatting to this server. |
| **Mu Editor** | Requires a Mu mode/editor adapter; the server side is ready. Mu remains an explicit project target. |
| **Pyzo** | Requires an editor adapter unless/until Pyzo exposes a generic LSP client; the server side is ready. |
| **VS Code / Code - OSS** | `vscode-pseudocode-i18n` now uses this server for completion/snippets, hover, navigation, rename, signatures, document symbols, formatting and diagnostics while keeping its richer execution/preview UX. |

See the **Editors** section of the documentation for exact configuration and current limitations.

## Development

```bash
yarn setup
yarn bfc
```

`yarn setup` installs the current project and uses a sibling `../pseudocode-i18n` checkout when present. `yarn bfc` is an alias for `yarn build:full:check` and performs version synchronization, generated integrations, linting, tests, a CLI smoke test, strict MkDocs documentation build and Python package build.

Useful commands:

```bash
yarn dev
yarn dev:lan
yarn test
yarn lint
yarn smoke
yarn zip
```

## License

GNU General Public License version 3 or later (**GPL-3.0-or-later**).
