Overview

Relevant source files

BSL Language Server is an implementation of the Language Server Protocol for the BSL language family, which includes 1C:Enterprise 8 configuration language and OneScript. It provides IDE-independent language intelligence features including diagnostics, code formatting, navigation, symbol information, and refactoring capabilities.

This document provides a high-level overview of the BSL Language Server system, its capabilities, operating modes, and architecture. For detailed information about specific subsystems, see:

Architecture and core components: Architecture
Diagnostic system: Diagnostic System
Command-line interface: Command Line Interface
Build and deployment: Build and Development

Sources: docs/index.md1-32 docs/en/index.md1-32 README.md1-32 build.gradle.kts1-50

What is BSL Language Server?

BSL Language Server is a Java-based implementation of the Language Server Protocol for the BSL (Built-in Scripting Language) family, which includes:

1C:Enterprise 8 configuration language (.bsl files)
OneScript scripting language (.os files)

The server provides IDE-independent language intelligence by analyzing BSL source code and offering diagnostics, formatting, navigation, and refactoring capabilities. It operates as a standalone console application (com.github._1c_syntax.bsl.languageserver.BSLLSPLauncher) that can run in multiple modes:

Mode	Entry Point	Transport	Primary Use Case
LSP Server	`BSLLanguageServer`	stdio or WebSocket	IDE/editor integration via LSP
Analyzer	`AnalyzeCommand`	CLI batch	CI/CD pipeline integration, batch code analysis
Formatter	`FormatCommand`	CLI batch	Automated code formatting in build scripts

The server integrates with VS Code, Sublime Text, 1C:EDT, Phoenix BSL, and SonarQube through standard LSP protocol or dedicated plugins.

Sources: docs/index.md15-53 docs/en/index.md15-53 build.gradle.kts166-178 src/test/java/com/github/_1c_syntax/bsl/languageserver/BSLLSPLauncherTest.java42-272

Core Capabilities

The following table summarizes the main features provided by BSL Language Server:

Feature Category	Capabilities	Configuration
Diagnostics	100+ diagnostic rules covering code smells, errors, vulnerabilities, security hotspots	Per-diagnostic parameters, modes (ON/OFF/EXCEPT/ONLY/ALL)
Formatting	Document formatting, range formatting	Configurable via settings
Navigation	Go to definition, find references, document symbols, workspace symbols, call hierarchy	Built-in
Code Intelligence	Hover documentation, code lenses (complexity metrics), inlay hints (parameter names)	Toggle via configuration
Refactoring	Symbol renaming, code actions, quick fixes	Based on diagnostic context
Analysis	Cognitive complexity, cyclomatic complexity, method metrics, code folding	Threshold configuration

All features can be enabled or disabled through the configuration file (.bsl-language-server.json). See Configuration System for details.

Sources: docs/index.md35-116 docs/en/index.md35-116 docs/diagnostics/index.md1-9 docs/en/diagnostics/index.md1-9

Operating Modes and Entry Points

Command Line Interface Architecture

BSL Language Server uses Picocli for command-line parsing and Spring Boot for dependency injection. All modes are accessed through BSLLSPLauncher.main():

Command Parameters

Command	Primary Options	Configuration File	Output
`lsp` (default)	`-c, --configuration`	`.bsl-language-server.json`	LSP messages via stdio
`websocket`	`--server.port=8025` `--app.websocket.lsp-path=/lsp`	`.bsl-language-server.json`	LSP messages via WebSocket
`analyze`	`-s, --srcDir` `-r, --reporter` (console\|json\|junit\|sarif\|tslint) `-o, --outputDir`	`.bsl-language-server.json`	Analysis reports
`format`	`-s, --src` (file or directory)	`.bsl-language-server.json`	Modified source files
`version`	None	N/A	Version string to stdout

Sources: docs/index.md118-243 docs/en/index.md118-243 src/test/java/com/github/_1c_syntax/bsl/languageserver/BSLLSPLauncherTest.java42-272 build.gradle.kts18-27 build.gradle.kts70-82

Core Architecture: From Source File to Diagnostics

High-Level Component Structure

Data Flow: .bsl File to Diagnostic Output

Architectural Patterns

Pattern	Implementation	Benefit
Lazy Initialization	`DocumentContext` uses `Lazy<T>` for tokenizer, symbol tree, diagnostics	Expensive operations only run on demand; memory efficient
Two-Level State	`ServerContext` (workspace) + `DocumentContext` (per-file)	Separation of concerns; supports incremental updates
Spring DI	`@Component` scan for diagnostics, providers injected via constructor	Extensible plugin architecture; testable
Provider Pattern	`HoverProvider`, `DefinitionProvider`, etc. implement feature-specific logic	LSP operations cleanly separated; reusable
Immutable Configuration	`LanguageServerConfiguration` reloaded on `workspace/didChangeConfiguration`	Thread-safe; predictable behavior

Sources: build.gradle.kts18-95 build.gradle.kts66-150 Diagrams 1, 2, 3, and 6 from high-level architecture, src/test/java/com/github/_1c_syntax/bsl/languageserver/BSLLanguageServerTest.java49-100

Technology Stack

BSL Language Server is built on the following core technologies:

Runtime & Framework

Technology	Version	Purpose
Java	17+	Runtime platform (tested on 17, 21, 23)
Spring Boot	3.5.6	Application framework, dependency injection
picocli	4.7.7	Command-line interface framework

Language Server Protocol

Technology	Version	Purpose
LSP4J	0.24.0	LSP protocol implementation
LSP4J WebSocket	0.24.0	WebSocket transport for LSP

BSL Language Processing

Technology	Version	Purpose
bsl-parser	0.26.1	ANTLR-based BSL grammar and parser
bsl-parser-core	0.3.1	Core parsing utilities
mdclasses	0.15.1	1C metadata parsing
bsl-common-library	0.8.1	BSL language utilities
supportconf	0.14.3	Support configuration handling

Analysis & Quality

Technology	Version	Purpose
JLanguageTool	6.5	Spell checking (English, Russian)
JGraphT	1.5.2	Graph algorithms for call hierarchies
AspectJ	1.9.22.1	AOP for cross-cutting concerns

Build & Testing

Technology	Version	Purpose
Gradle	8.14.3	Build automation
JUnit 5	(via Spring Boot)	Testing framework
JMockit	1.49	Mocking framework
Jacoco	(via plugin)	Code coverage
SonarQube	(via plugin)	Code quality analysis

Sources: build.gradle.kts6-149 gradle/wrapper/gradle-wrapper.properties1-8 docs/systemRequirements.md1-20 docs/en/systemRequirements.md1-20

Configuration System

BSL Language Server uses a JSON-based configuration file (.bsl-language-server.json) validated against JSON schemas. Configuration controls:

Language: Message locale (Russian/English)
Diagnostics: Enable/disable rules, set parameters, choose modes
Features: Code lenses, inlay hints, diagnostic links, code actions
Formatting: Code style parameters
Trace Logging: Debug output configuration

The configuration system supports:

Schema validation: src/main/resources/com/github/_1c_syntax/bsl/languageserver/configuration/schema.json1-10
Per-diagnostic parameters: src/main/resources/com/github/_1c_syntax/bsl/languageserver/configuration/parameters-schema.json1-100
Runtime updates via workspace/didChangeConfiguration LSP event

For detailed configuration options, see Configuration System.

Sources: src/main/resources/com/github/_1c_syntax/bsl/languageserver/configuration/schema.json1-50 src/main/resources/com/github/_1c_syntax/bsl/languageserver/configuration/parameters-schema.json1-100 docs/index.md245-249

Diagnostic System Overview

150+ Code Quality Rules

The diagnostic system implements over 150 configurable rules covering code smells, errors, vulnerabilities, and security issues. Each diagnostic is a Spring-managed @Component implementing the BSLDiagnostic interface.

Diagnostic Execution Flow

Diagnostic Distribution by Category

Type	Count	Severity Range	Example Diagnostic Keys
`CODE_SMELL`	~100	Info, Minor, Major	`CognitiveComplexity`, `EmptyCodeBlock`, `MissingSpace`
`ERROR`	~30	Critical, Blocker	`ParseError`, `MissedRequiredParameter`, `FunctionShouldHaveReturn`
`VULNERABILITY`	~15	Critical, Blocker	`ExecuteExternalCode`, `DisableSafeMode`, `FileSystemAccess`
`SECURITY_HOTSPOT`	~6	Major	`IsInRoleMethod`, `PrivilegedModuleMethodCall`

Diagnostic Metadata and Localization

Each diagnostic class is annotated with @DiagnosticMetadata and has corresponding resource files:

src/main/java/.../diagnostics/MissingTempStorageDeletionDiagnostic.java src/main/resources/.../diagnostics/MissingTempStorageDeletionDiagnostic_en.properties src/main/resources/.../diagnostics/MissingTempStorageDeletionDiagnostic_ru.properties docs/diagnostics/MissingTempStorageDeletion.md (Russian) docs/en/diagnostics/MissingTempStorageDeletion.md (English)

The DiagnosticInfo class aggregates metadata, localized messages, and parameter schemas for each diagnostic. Configuration parameters are defined in src/main/resources/com/github/_1c_syntax/bsl/languageserver/configuration/parameters-schema.json1-100

For detailed diagnostic system architecture, see Diagnostic System.

Sources: docs/diagnostics/index.md1-9 docs/en/diagnostics/index.md1-9 src/main/java/com/github/_1c_syntax/bsl/languageserver/diagnostics/MissingTempStorageDeletionDiagnostic.java44-78 src/test/java/com/github/_1c_syntax/bsl/languageserver/diagnostics/SmokyTest.java56-155 src/main/resources/com/github/_1c_syntax/bsl/languageserver/diagnostics/MissingTempStorageDeletionDiagnostic_en.properties1-3 Diagram 4 from high-level architecture

Build and Distribution

Build System Overview

BSL Language Server uses Gradle 8.14.3 with multiple plugins for compilation, testing, quality assurance, and packaging. The main entry point for the build is build.gradle.kts1-416

Gradle Plugin Stack

Plugin	Purpose	Key Configuration
`java-library`	Core Java compilation	Java 17 source/target compatibility
`org.springframework.boot` (3.5.6)	Executable JAR packaging	`bootJar` task creates self-contained JAR
`io.freefair.lombok`	Annotation processing	Reduces boilerplate code
`io.freefair.aspectj.post-compile-weaving`	AOP support	Cross-cutting concerns (logging, tracing)
`jacoco`	Code coverage	XML reports for SonarCloud
`org.jreleaser`	Maven Central publishing	Automatic deployment
`me.qoomon.git-versioning`	Version from Git tags	`v0.22.0` → `0.22.0`, develop → `0.23.0.x-SNAPSHOT`
`io.github.1c-syntax.bslls-dev-tools`	Diagnostic doc generation	Auto-generates Markdown from `@DiagnosticMetadata`

Artifact Distribution

Artifact Type	Task	Output Location	Distribution Channel
Standard JAR	`jar`	`build/libs/bsl-language-server-{version}.jar`	Maven Central
Executable JAR	`bootJar`	`build/libs/bsl-language-server-{version}-exec.jar`	Maven Central, GitHub Releases
Sources JAR	`sourcesJar`	`build/libs/bsl-language-server-{version}-sources.jar`	Maven Central
Javadoc JAR	`javadocJar`	`build/libs/bsl-language-server-{version}-javadoc.jar`	Maven Central
Platform packages	`jpackage` (via GitHub Actions)	Native installers (Windows .zip, Linux .tar.gz, macOS .app)	GitHub Releases

Version Management

The build.gradle.kts36-58 configures automatic versioning:

Tagged releases: git tag v0.22.0 → version 0.22.0
Develop branch: 0.{minor+1}.0.{distance}-SNAPSHOT (e.g., 0.23.0.47-SNAPSHOT)
Feature branches: {branch}-{shortCommit} (e.g., feature-123-a1b2c3d)

Continuous Integration

GitHub Actions workflows (.github/workflows/) handle:

Multi-platform testing (Ubuntu, Windows, macOS)
Multi-JDK testing (Java 17, 21, 23)
SonarCloud quality gate
CodeQL security analysis
Performance benchmarking
Automatic dependency updates via Dependabot

For detailed build configuration, see Build and Development.

Sources: build.gradle.kts1-58 build.gradle.kts151-178 build.gradle.kts298-406 gradle/wrapper/gradle-wrapper.properties1-8 .github/dependabot.yml1-23 Diagram 5 from high-level architecture

LSP Protocol Support

BSL Language Server implements a comprehensive subset of the LSP specification:

LSP Operation	Status	Notes
Lifecycle
`initialize`	✓	Capability negotiation
`shutdown` / `exit`	✓	Clean shutdown
Text Synchronization
`didOpen` / `didChange` / `didClose` / `didSave`	✓	Full sync mode
Language Features
`publishDiagnostics`	✓	100+ diagnostics, tag support
`hover`	✓	Method documentation
`definition`	✓	Go to definition
`references`	✓	Find all references
`documentSymbol`	✓	Outline view
`codeAction`	✓	Quick fixes
`codeLens`	✓	Complexity metrics
`formatting` / `rangeFormatting`	✓	Code formatting
`rename` / `prepareRename`	✓	Symbol renaming
`foldingRange`	✓	Code folding
`callHierarchy`	✓	Call graph
`inlayHint`	✓	Parameter names
`documentLink`	✓	Diagnostic documentation links
`documentColor` / `colorPresentation`	✓	Color preview and conversion
Workspace
`symbol`	✓	Workspace-wide symbol search
`executeCommand`	✓	Custom commands
`didChangeConfiguration`	✓	Runtime configuration updates

Unsupported operations include: completion, signatureHelp, semanticTokens, onTypeFormatting.

Sources: docs/index.md54-116 docs/en/index.md54-116 src/test/java/com/github/_1c_syntax/bsl/languageserver/BSLLanguageServerTest.java1-100

Integration Points

BSL Language Server integrates with various development tools:

IDE/Editor Integrations (via LSP)

VS Code: vsc-language-1c-bsl extension
Sublime Text: LSP plugin
Phoenix BSL: 1C Designer plugin
1C:EDT: Direct integration (non-LSP)

Quality Platforms

SonarQube: sonar-bsl-plugin-community

Communication Protocols

stdio: Default LSP transport for local processes
WebSocket: ws://localhost:8025/lsp for remote/browser clients

Sources: docs/index.md1-32 docs/en/index.md1-32 docs/faq.md24-38 docs/en/faq.md24-38

System Requirements

Runtime Environment

Component	Requirement	Notes
JVM	Java 17+	Tested on OpenJDK 17, 21, 23; built with JDK 23 for releases
OS	Windows 7+, Linux (Ubuntu/CentOS 6+), macOS	Platform-specific installers provided
Memory	512MB minimum, 4GB+ recommended for large projects	Use `-Xmx4g` flag for batch analysis
Disk Space	~100MB for application, additional space for project cache	Temporary storage in system temp directory

Client Requirements (for LSP mode)

LSP-compatible editor or IDE
Support for stdio or WebSocket transport
UTF-8 text encoding support

Sources: docs/systemRequirements.md1-20 docs/en/systemRequirements.md1-20 build.gradle.kts152-157 docs/index.md181-185 docs/en/index.md181-185

Documentation Resources

Additional documentation is available at:

User Documentation: https://1c-syntax.github.io/bsl-language-server
Development Documentation: https://1c-syntax.github.io/bsl-language-server/dev
Javadoc: Published alongside user documentation
Diagnostic Reference: Detailed pages for each diagnostic rule
Configuration Guide: See Configuration System
FAQ: Common questions and answers

For contributing guidelines, see the Contributing section in the main documentation.

Sources: README.md1-32 docs/index.md17-28 docs/en/index.md17-29 docs/faq.md1-38 docs/en/faq.md1-38