1c_hbk_bsl

# 1C HBK BSL Tools for development on **1C Enterprise / BSL**: extension for VS Code / Cursor, CLI-linter, formatter, LSP-server and MCP-server for local integrations. [](https://github.com/mussolene/1c_hbk_bsl/actions/workflows/ci.yml) [](https://marketplace.visualstudio.com/items?itemName=mussolene.1c-hbk-bsl) [](https://marketplace.visualstudio.com/items?itemName=mussolene.1c-hbk-bsl) [](https://pypi.org/project/onec-hbk-bsl/) [](https://pypi.org/project/onec-hbk-bsl/) [](LICENSE) ## What Is It `onec-hbk-bsl` helps keep BSL code in order: - shows diagnostics in the editor and CLI; - includes 180 public diagnostic rules; - formats `.bsl` / `.os`; - provides navigation, hover, completion, rename, and inlay hints through LSP; - can output SARIF/JSON for CI; - offers MCP tools for local AI assistants. The project does not run the Java analyzer at runtime. The public contract of the product: `BSL###` rule codes, `onec-hbk-bsl.toml`, CLI/LSP/MCP, and VS Code extension. The current release requires Python 3.12+ when installed from PyPI. Platform-specific VSIX contains a ready-made binary and does not require a system Python. A historical, versioned snapshot of checks v0.8.38 and measurement methodology are provided in [Production notes](docs/Production-Notes.md#verification-snapshot-v0838); the current status is confirmed by the CI badge and artifacts of a specific release. ## Quick Start ### VS Code / Cursor 1. Install the `mussolene.1c-hbk-bsl` extension. 2. Open a directory with 1C source code. 3. Diagnostics will appear in Problems; formatting and navigation will work through LSP. Supported VS Code / Cursor with VS Code API 1.85+ and platform-specific builds for macOS Apple Silicon, macOS Intel, Linux x64, and Windows x64. Recommended workspace settings: ```json { "[bsl]": { "editor.defaultFormatter": "mussolene.1c-hbk-bsl", "editor.formatOnSave": true, "editor.tabSize": 4, "editor.insertSpaces": false } } ``` For more information: [vscode-extension/README.md](https://github.com/mussolene/1c_hbk_bsl/blob/main/vscode-extension/README.md). ### CLI ```bash uv tool install onec-hbk-bsl onec-hbk-bsl check . onec-hbk-bsl format . --check onec-hbk-bsl check . --format sarif > bsl-results.sarif ``` For a regular installation via pip: ```bash pip install onec-hbk-bsl ``` ## Configuration The main project file: `onec-hbk-bsl.toml`. ```toml ignore = ["BSL012"] exclude = ["vendor", "build", "*.gen.bsl"] format = "text" jobs = 0 insert-spaces = false indent-size = 4 index-mode = "full" # off | symbols | full index-max-bytes = 0 # 0 = unlimited [per-file-ignores] "legacy/*.bsl" = ["BSL002", "BSL011"] ``` Also supported is the `[tool."onec-hbk-bsl"]` section in `pyproject.toml`. CLI, Python API, LSP, and MCP use the same order of resolving values: explicit parameter → environment variable → project config → built-in default. Environment variables exist only for already public server/index settings: `BSL_SELECT`, `BSL_IGNORE`, `BSL_INDEX_MODE`, and `BSL_INDEX_MAX_BYTES`. Explicit values matching defaults (`--format text`, `--jobs 0`, `--no-exit-zero`, `--no-insert-spaces`), still override the project config. `jobs = 0` enables adaptive scheduling: several modules of size from 2 MiB on fork-capable OS are distributed among file-workers, and each worker receives a limited share of the total rule budget. `jobs = 1` always executes files sequentially. The Python API `check_files(...)` automatically searches for this config from the first passed path; if you pass `config=cfg`, it applies as a set of defaults entirely. CLI `format` reads `exclude`; the workspace index reads `index-exclude`, which by default inherits `exclude`, and also considers Git ignore. An empty `index-exclude` leaves excluded libraries from diagnostics available for hover/F12. After changing the index area, execute `index --force`. Formatter reads `insert-spaces` and `indent-size`; low-level `default_formatter.format(...)` remains a pure function from text and explicit parameters. ## Rules - `BSL###` — stable rule code for output, `--select`, `--ignore`, `onec-hbk-bsl.toml`, and `// noqa: BSL###`. - `Compatible key` — compatible alias for existing BSL projects, for example `LineLength` or `ConsecutiveEmptyLines`. - CLI and config accept both types, but output `BSL###`. Rule reference: [docs/diagnostic-rules.md](https://github.com/mussolene/1c_hbk_bsl/blob/main/docs/diagnostic-rules.md). Suppression: ```bsl Password = "dev_only"; // noqa: BSL012 // BSLLS:MethodSize-off ``` ## Commands ```bash # Diagnostics onec-hbk-bsl check . onec-hbk-bsl check . --select BSL001,BSL012 onec-hbk-bsl check . --ignore BSL014 # Reports and gradual implementation onec-hbk-bsl check . --format json onec-hbk-bsl check . --format sarif > bsl-results.sarif onec-hbk-bsl check . --update-baseline bsl-baseline.json onec-hbk-bsl check . --baseline bsl-baseline.json # Formatting onec-hbk-bsl format . onec-hbk-bsl format . --check # Servers onec-hbk-bsl lsp onec-hbk-bsl mcp --stdio --workspace /path/to/project onec-hbk-bsl index /path/to/project onec-hbk-bsl index /path/to/project --mode symbols onec-hbk-bsl index /path/to/project --status onec-hbk-bsl index /path/to/project --compact onec-hbk-bsl index /path/to/project --clean # stop LSP/MCP first ``` In a Git repository, tracked files and untracked files not excluded by Git (`.gitignore`, `.git/info/exclude`, global excludes) are indexed. Then, `index-exclude` patterns from `onec-hbk-bsl.toml` are applied; if the key is not set, it inherits `exclude`. The `symbols` mode does not store the call graph, `off` disables the permanent workspace index, and `full` preserves all cross-file capabilities. A damaged index is a cache and is deleted for rebuilding — `.corrupt.*` copies are not saved. Before `--clean`, stop LSP/MCP: the writer-lock cannot detect an inactive reader or an old version of the process with an open file. The public CLI/API surface is described in [docs/public-surface.md](https://github.com/mussolene/1c_hbk_bsl/blob/main/docs/public-surface.md). ## Python and Packages ```python from onec_hbk_bsl import check_files diagnostics = check_files(["src/Module.bsl"], jobs=1) for diagnostic in diagnostics: print(diagnostic.code, diagnostic.file, diagnostic.line) ``` Two PyPI distributions are published: | Package | Purpose | |---|---| | `onec-hbk-bsl-core` | CLI, formatter, diagnostics, Python API, and LSP without MCP dependencies | | `onec-hbk-bsl` | Full compatible package on top of `onec-hbk-bsl-core[mcp]` of the same version | ## Documentation Canonical fact owners and a complete index are fixed in the [Documentation Ownership](https://github.com/mussolene/1c_hbk_bsl/blob/main/docs/public-surface.md#documentation-ownership) section. | Document | Role | |---|---| | [VS Code extension guide](https://github.com/mussolene/1c_hbk_bsl/blob/main/vscode-extension/README.md) | Regulatory settings and behavior of the VS Code / Cursor extension | | [Diagnostic rules](https://github.com/mussolene/1c_hbk_bsl/blob/main/docs/diagnostic-rules.md) | Generated rule reference | | [Public surface](https://github.com/mussolene/1c_hbk_bsl/blob/main/docs/public-surface.md) | Regulatory public contract of CLI/Python/LSP/MCP/package | | [Architecture](https://github.com/mussolene/1c_hbk_bsl/blob/main/docs/architecture.md) | Descriptive architecture of the server and analyzer | | [Production notes](https://github.com/mussolene/1c_hbk_bsl/blob/main/docs/Production-Notes.md) | Runbook, release checks, and dated snapshots | | [Security policy](https://github.com/mussolene/1c_hbk_bsl/blob/main/SECURITY.md) | Supported versions and private channel for vulnerabilities | | [Third-party notices](https://github.com/mussolene/1c_hbk_bsl/blob/main/docs/THIRD_PARTY_NOTICES.md) | Dependencies, licenses, and data origin | ## Development ```bash git clone https://github.com/mussolene/1c_hbk_bsl cd 1c_hbk_bsl make install make lint make test ``` For local VSIX build, use `make vsix`. ## License MIT © 2024 1C HBK BSL Contributors