XBSL

English · Русский

Documentation: docs.keyfire.ru/xbsl

The XBSL (1C:Element) toolkit: 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 Name.yaml (element description) and Name.xbsl (code module) pairs – before the server-side compilation that happens on deploy.

Before 0.16 the project was named xbsl-lint (the xbsllint package); the old commands, imports, env vars 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 external tooling: the only code check is the server-side compilation on deploy – it is slow and knows nothing about project conventions. xbsl gives fast local feedback, catches what the compiler does not check at all, 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 + <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 the same core, so every surface sees 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 relies on tables extracted from your 1C:Element distribution (keywords, the stdlib type catalog, the configuration metamodel, terms, the documentation index, the component schema); they are NOT bundled in this repository:

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

The command runs every extractor in one go (python tools/extract.py from a clone is the same entry point; --only picks a subset), auto-detects the platform version and places the data under xbsl/data/element/ (gitignored). Details – data location, private data packages – 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, native mypyc wheels and the self-update mechanics – in the guide.

What it does

Rules. 190 rules in the base set, in four tiers: A – structure and yaml schema, B – text and typography conventions, C – code structure (blocks, brackets, unused locals, the style/ code conventions), D – 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 – docs/RULES.md; at runtime – xbsl --list-rules; what tier D verifies in depth – the guide.

Autofixes. --fix repairs the mechanical findings in place – trailing whitespace, typography characters, mixed newlines – and only them: anything needing judgment is never touched.

Baseline. A rule can be adopted on an old codebase without cleaning all of it first: the current findings are frozen once, and only new code answers to the rule. The same file records point exclusions with reasons. Details.

Metadata scaffolding. Creating objects, attributes, routes and forms without hand-writing yaml: 33 element kinds, forms generated with real content, context-aware rename-object, access-control editing. The same operations 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 (the kinds are resolved through the term dictionary extracted from your distribution). Section names of add-field still go in the project's own language; 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): 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 – get the whole construct with edit points. 51 builtin templates (each one parsed by the linter's own parser, so it cannot insert broken code), your own in .xbsl-templates.json, a management panel in VS Code; the mechanism and 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: linting, documentation search, type_members and every scaffolding operation as meta_* tools – an 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-is; --format codeclimate feeds the GitLab Code Quality widget. Ready-made GitHub Actions and GitLab CI jobs – the guide.

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

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

Tests

pip install -e ".[dev]"
pytest

Data-dependent tests are skipped automatically 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.