xbsl

# XBSL **English** · [Русский](https://github.com/keyfire/xbsl/blob/main/README.ru.md) **Documentation: [docs.keyfire.ru/xbsl](https://docs.keyfire.ru/xbsl/)**  The XBSL (1C:Element) toolkit: a linter with autofixes, an LSP server, a project index, platform documentation search, metadata scaffolding and an MCP server for AI agents. 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](https://github.com/keyfire/xbsl/blob/main/NOTICE). Development notes and updates (in Russian): the [1C × AI: engineering workshop](https://t.me/ceh_1c_ai) 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. ## 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.** ```sh 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: ```sh 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](https://github.com/keyfire/xbsl/blob/main/docs/GUIDE.md#language-data). **Step 3 – run.** ```sh xbsl path/to/sources # or: python -m xbsl path/to/sources xbsl data-diff # what changed in the platform between two data versions 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](https://github.com/keyfire/xbsl/blob/main/docs/GUIDE.md#cli-flags). ## What it does **Rules.** 99 rules 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](https://github.com/keyfire/xbsl/blob/main/docs/RULES.md); at runtime – `xbsl --list-rules`; what tier D verifies in depth – [the guide](https://github.com/keyfire/xbsl/blob/main/docs/GUIDE.md#rules-in-depth). **Autofixes.** `--fix` repairs the mechanical findings in place – trailing whitespace, typography characters, mixed newlines – and only them: anything needing judgment is never touched. **Baseline.** Adopt a rule on a legacy codebase without drowning: freeze the current findings once, hold only new code to the rule; the same file records point exclusions with reasons. [Details](https://github.com/keyfire/xbsl/blob/main/docs/GUIDE.md#baseline-adopt-a-rule-on-a-legacy-codebase). **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: ```sh 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](https://github.com/keyfire/xbsl/blob/main/docs/GUIDE.md#metadata-scaffolding). **Editors.** The [VS Code extension](https://github.com/keyfire/xbsl/blob/main/editors/vscode/README.md) ([Marketplace](https://marketplace.visualstudio.com/items?itemName=keyfire.xbsl), [Open VSX](https://open-vsx.org/extension/keyfire/xbsl)): syntax highlighting, live and project-wide diagnostics, go-to-definition and completion, the form designer, a metadata tree and a deploy button. Under the hood is `xbsl-lsp` – a Language Server any LSP-capable editor can spawn ([details](https://github.com/keyfire/xbsl/blob/main/docs/GUIDE.md#lsp-server)). **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](https://github.com/keyfire/xbsl/blob/main/docs/GUIDE.md#code-templates). **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](https://github.com/keyfire/xbsl/blob/main/docs/GUIDE.md#documentation-search). **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](https://github.com/keyfire/xbsl/blob/main/docs/GUIDE.md#mcp-server). **Web interface.** `xbsl-web` – a local page over the same engine: rule toggles, filters, themes. [Details](https://github.com/keyfire/xbsl/blob/main/docs/GUIDE.md#web-interface). **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](https://github.com/keyfire/xbsl/blob/main/docs/GUIDE.md#use-in-ci). **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](https://github.com/keyfire/xbsl/blob/main/docs/GUIDE.md#extending-your-own-rules-data-and-severities). Output language (RU/EN), Element data versions and the data root resolution order are also covered in the [guide](https://github.com/keyfire/xbsl/blob/main/docs/GUIDE.md#output-language). ## Tests ```sh pip install -e ".[dev]" pytest ``` Data-dependent tests are skipped automatically when the data has not been generated. ## License MIT – see [LICENSE](https://github.com/keyfire/xbsl/blob/main/LICENSE). Trademarks and data provenance – [NOTICE](https://github.com/keyfire/xbsl/blob/main/NOTICE). How to add a rule – [CONTRIBUTING.md](https://github.com/keyfire/xbsl/blob/main/CONTRIBUTING.md). Release history – [CHANGELOG.md](https://github.com/keyfire/xbsl/blob/main/CHANGELOG.md).