nextflow-io/language-server

1. What this repo is

- This is a Java 17+ Language Server Protocol implementation for Nextflow.

- It runs as a stdio-based server jar and serves Nextflow script files and Nextflow config files.

2. Top-level runtime boundary

- The entrypoint is nextflow.lsp.NextflowLanguageServer.

- It sits between the editor/client and the internal language features, receiving LSP requests and publishing responses, diagnostics, and notifications over standard input/output.

3. Core dispatch layer

- nextflow.lsp.services.LanguageService is the main routing layer.

- It selects the appropriate subsystem for the file type: script services for .nf-style workflow scripts and config services for Nextflow config files.

- LanguageServerConfiguration and ErrorReportingMode control behavior from workspace configuration changes.

4. Two main analysis pipelines

- The repo has a clear split between:

- services/script/* for workflow scripts

- services/config/* for config files

- Each side has its own AST cache, visitors, completion/hover/definition/reference providers, formatting, semantic tokens, and symbol support.

5. Script subsystem

- ScriptService is the orchestrator for script files.

- It relies on ScriptAstCache, ScriptAstParentVisitor, and several specialized visitors/providers to answer editor features.

- This subsystem also handles workflow-specific concerns like process conversion, plugin include resolution, and workspace preview generation.

6. Config subsystem

- ConfigService plays the same role for configuration files.

- It uses ConfigAstCache, ConfigAstParentVisitor, and config-specific providers for completion, hover, links, formatting, and semantic highlighting.

- Config analysis also resolves includes via CachingResolveIncludeVisitor.

7. Parsing, compilation, and diagnostics

- nextflow.lsp.compiler.LanguageServerCompiler and LanguageServerErrorCollector form the diagnostics pipeline.

- Source files are parsed/compiled, errors are collected, and surfaced back to the client as diagnostics.

- This is the main path for “diagnostics” support in the language server.

8. State and caching

- nextflow.lsp.file.FileCache tracks workspace file contents/state.

- AST and domain-specific caches reduce repeated parsing and enable cross-request reuse.

- The design assumes many LSP requests are read-heavy and benefit from cached semantic models.

9. Language feature providers

- Standard LSP features are implemented as separate provider classes: completion, definition, references, rename, hover, formatting, symbols, links, code lens, call hierarchy, and semantic tokens.

- There is a shared abstraction layer in nextflow.lsp.services.*, with script/config specializations beneath it.

- This makes the architecture provider-oriented: each feature is implemented as a focused service over the cached AST/model.

10. Nextflow-specific semantic model

- nextflow.lsp.spec.* defines project-specific specs such as ScriptSpecFactory, ConfigSpecFactory, and plugin metadata caches.

- These classes encode knowledge of Nextflow syntax, plugins, and runtime conventions so the LSP can offer accurate completions and navigation.

- src/main/java/nextflow/script/* contains deeper language/type infrastructure, including type checking helpers and shim types that model Nextflow/Groovy semantics.

11. Workflow DAG preview path

- Script analysis includes a dedicated DAG preview subsystem under services/script/dag.

- DataflowVisitor builds graph data, Graph holds the intermediate representation, and MermaidRenderer turns it into a previewable diagram format.

- WorkspacePreviewProvider connects this analysis to the language server feature surface.

12. Utilities and support code

- Shared helpers in nextflow.lsp.util handle logging, JSON, positions/ranges, debouncing, and progress notifications.

- DebouncingExecutor suggests some requests are rate-limited or coalesced to avoid expensive repeated analysis while the user is typing.

13. Build and test structure

- The project uses Gradle with a wrapper, plus a Makefile for local build/test convenience.

- Tests are in Groovy under src/test/groovy, with coverage for caches, type checking, script/config features, DAG preview, and utility code.

- GitHub Actions workflows build the project and generate dependency updates.

14. Repository dependency boundary

- The README notes that this server is built alongside the Nextflow repository and the nf-lang module.

- Architecturally, that means this repo depends on Nextflow’s language/runtime semantics for correctness, while exposing them through an LSP-compatible server for editors.