XBSL

English · Русский

Documentation: docs.keyfire.ru/xbsl

The XBSL toolkit for 1C:Element: a linter with autofixes, an LSP server, a project index, platform documentation search, metadata scaffolding, translation of sources into English spellings and an MCP server for AI agents. Plus a VS Code extension on the same engine. It works on pairs of files: Name.yaml describes an element, Name.xbsl holds its code. And it answers long before the server-side compilation that runs on deploy.

Before 0.16 the project was named xbsl-lint, package xbsllint. The old commands, imports, environment variables and entry-point groups keep working as aliases.

Not affiliated with 1C. "1C:Element", "1C:Fresh" and related names are trademarks of their respective owners. Language data is generated from your own distribution. See NOTICE.

Development notes and updates (in Russian): the 1C × AI: engineering workshop Telegram channel.

Why

1C:Element has no tooling outside the platform. The only check on the code is the server-side compilation on deploy, which is slow and knows nothing about a project's conventions. xbsl answers right away on your own machine, catches what the compiler never looks at, and takes over the metadata mechanics: creating objects, attributes and forms.

Related MCP server: 1C MCP Server

How it works

One engine, four surfaces. The core reads the <element>.yaml and <element>.xbsl pairs, and the scaffolding writes them back. The CLI, the LSP server, the MCP server and the web UI are thin adapters over that core, so all four see the same rules, data and templates:

Quick start

Step 1 – install.

pip install xbsl              # or from a clone of the repository: pip install -e .

Step 2 – generate the language data. The linter judges by tables taken from your 1C:Element distribution: keywords, the stdlib type catalog, the configuration metamodel, terms, the documentation index, the component schema. None of that is bundled in this repository:

xbsl extract --dist "<path to the 1C:Element distribution>"

The command runs every extractor in one go. From a clone the same entry point is python tools/extract.py, and --only picks a subset of the steps. It detects the platform version itself and places the data under xbsl/data/element/, a folder listed in .gitignore. Where the data lives and how a private package can ship it is covered in the guide.

Step 3 – run.

xbsl path/to/sources        # or: python -m xbsl path/to/sources
xbsl data-diff              # what changed in the platform between two data versions
xbsl translate SOURCES      # rewrite a project into English spellings (a project dictionary)
xbsl self-update            # upgrade to the latest PyPI version, safe with busy exe stubs

The main flags: --list-rules, --fix, --select/--enable/--ignore, --baseline/--write-baseline, --format text|json|codeclimate, --lang ru|en. The full flag reference, the --stdin/--index editor modes, the native mypyc wheels and how self-update works are all in the guide.

What it does

Rules. 194 rules in the base set, in four tiers. A covers structure and the yaml schema. B covers text and typography conventions. C covers code structure: blocks, brackets, unused locals, the style/ conventions. D covers semantics against the platform data and the project itself: every type position in code and yaml, enumeration values, Query{...} block tables, cross-file consistency, the types of attached .xlib libraries. The full list with severities and documentation links is in docs/RULES.md, and xbsl --list-rules prints it on the spot. What tier D verifies in depth is in the guide.

Autofixes. --fix repairs the mechanical findings in place: trailing whitespace, typography characters, mixed newlines. Anything that needs judgment it leaves alone.

Baseline. You can adopt a rule on an old codebase without cleaning all of it first. Freeze the current findings once, and only new code answers to the rule. The same file records point exclusions with reasons. Details.

Metadata scaffolding. Objects, attributes, routes and forms are created without hand-written yaml: 33 element kinds, forms generated with real content, a context-aware rename-object, access-control editing. The same operations are available through the CLI, MCP and LSP:

xbsl new-object vendor/App/Main Catalog Goods            # the kind in either language
xbsl add-field vendor/App/Main/Goods.yaml <section> Color --type <type>
xbsl add-form . --name Goods                            # object + list forms, registered
xbsl rename-object . Goods Products                     # rename files + update references

The platform is bilingual: an element kind has an English name and a Russian one for the same thing, and the tool takes either spelling. It resolves the kinds through the term dictionary extracted from your distribution. Section names of add-field still go in the project's own language, and xbsl new-object --help lists the kinds it can create.

All subcommands with their options – the guide.

Editors. The VS Code extension (Marketplace, Open VSX) gives you syntax highlighting, live and project-wide diagnostics, go-to-definition and completion, the form designer, a metadata tree and a deploy button. It runs on xbsl-lsp, a Language Server any LSP-capable editor can spawn (details).

Code templates. Type the first letters of a construct, press Ctrl+Space, and the whole construct arrives with its edit points. There are 51 builtin templates, each one parsed by the linter's own parser, so none of them can insert broken code. Your own live in .xbsl-templates.json, with a management panel in VS Code. The mechanism and the file format mirror 1C:EDT. Details.

Documentation search. tools/extract_docs.py turns the distribution's Element reference into a local full-text docs.sqlite; the xbsl.docs API and the MCP tools search it. Details.

MCP server. claude mcp add xbsl -- xbsl-mcp gives an agent linting, documentation search, type_members and every scaffolding operation as meta_* tools. The agent creates an object and gets the lint of the written files in one round trip. Details.

Web interface. xbsl-web – a local page over the same engine: rule toggles, filters, themes. Details.

CI. The exit code is non-zero only on error-severity findings, so xbsl gates a pipeline as it is. --format codeclimate feeds the GitLab Code Quality widget. Ready-made GitHub Actions and GitLab CI jobs are in the guide.

Extending. Entry points let a private package add rules, ship language data and override severities without forking the linter. XBSL_NO_PLUGINS=1 turns every plugin off. Details.

Output language (RU/EN), Element data versions and the order the data root is resolved in are covered in the same guide.

Tests

pip install -e ".[dev]"
pytest

Tests that need the data skip themselves when the data has not been generated.

License

MIT – see LICENSE. Trademarks and data provenance – NOTICE. How to add a rule – CONTRIBUTING.md. Release history – CHANGELOG.md.