xbsllint 0.2.0__tar.gz

xbsllint-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xbsl-lint contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

xbsllint-0.2.0/NOTICE

@@ -0,0 +1,36 @@
+xbsl-lint
+=========
+
+(English below, русский ниже)
+
+--- English ---
+
+This project is not affiliated with 1C and is not an official 1C product.
+
+"1C", "1C:Enterprise", "1C:Element", "1C:Fresh" and related names are trademarks and service marks
+of their respective owners. They are used here only to indicate the tool's compatibility with the
+platform.
+
+The language and type data (xbsllint/data/element/...) is NOT included in this repository. It is
+extracted by the user from their OWN, legally obtained 1C:Element distribution using the scripts
+tools/extract_grammar.py and tools/extract_stdlib.py, and stays on the user's machine. The user is
+responsible for holding the rights to the distribution and for the admissibility of extracting data
+from it.
+
+The project's source code is distributed under the MIT License (see the LICENSE file).
+
+--- Русский ---
+
+Проект не аффилирован с фирмой «1С» и не является её официальным продуктом.
+
+«1С», «1С:Предприятие», «1С:Элемент», «1С:Фреш» и связанные названия – товарные знаки и знаки
+обслуживания их правообладателей. Здесь они используются исключительно для указания
+совместимости инструмента с платформой.
+
+Данные о языке и типах (xbsllint/data/element/...) в этот репозиторий НЕ включены. Они
+извлекаются пользователем из его СОБСТВЕННОГО, законно полученного дистрибутива 1С:Элемент
+скриптами tools/extract_grammar.py и tools/extract_stdlib.py и остаются на локальной машине.
+Ответственность за наличие прав на дистрибутив и за допустимость извлечения из него данных несёт
+пользователь.
+
+Исходный код проекта распространяется по лицензии MIT (см. файл LICENSE).

xbsllint-0.2.0/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: xbsllint
+Version: 0.2.0
+Summary: Линтер исходников 1С:Элемент (пары .yaml/.xbsl)
+Author: xbsl-lint contributors
+License: MIT
+Project-URL: Homepage, https://github.com/keyfire/xbsl-lint
+Project-URL: Repository, https://github.com/keyfire/xbsl-lint
+Keywords: 1c,1c-element,xbsl,linter,static-analysis
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: Russian
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: PyYAML>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.2; extra == "mcp"
+Dynamic: license-file
+
+# xbsl-lint
+
+**English** · [Русский](README.ru.md)
+
+![CI](https://github.com/keyfire/xbsl-lint/actions/workflows/ci.yml/badge.svg)
+
+A linter for 1C:Element sources — it checks `Name.yaml` (element description) and `Name.xbsl`
+(code module) pairs before the server-side compilation that happens on deploy.
+
+> 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](NOTICE).
+
+## Why
+
+1C:Element has no external linter: the only code check is the server-side compilation on deploy —
+it is slow and knows nothing about project conventions. xbsl-lint gives fast local feedback and
+catches what the compiler does not check at all.
+
+## Step 1: generate the language data
+
+The linter relies on language tables (bilingual keywords, operators), an stdlib type catalog, and
+the configuration metamodel (element properties). XBSL is built on Eclipse Xtext + ANTLR; these are
+extracted from **your** 1C:Element distribution (the `InternalBsl.g` grammar, the documentation, and
+the `.xcore` metamodel) and are NOT bundled in this repository. Generate them locally:
+
+```sh
+python tools/extract_grammar.py   --dist "<path to the 1C:Element distribution>"
+python tools/extract_stdlib.py    --dist "<path to the 1C:Element distribution>"
+python tools/extract_metamodel.py --dist "<path to the 1C:Element distribution>"
+```
+
+The scripts auto-detect the platform version and place the data under
+`xbsllint/data/element/<version>/` (this folder is gitignored). Without the data, the linter and
+the tests will tell you to generate it.
+
+## Step 2: install and run
+
+```sh
+pip install -e .
+xbsllint path/to/sources        # or: python -m xbsllint path/to/sources
+```
+
+Flags: `--list-rules`, `--select`/`--ignore` (by rule id, rule group — the part of the id before
+`/` — or tier letter), `--element-version`.
+
+## Rule tiers
+
+- **A. Structure and YAML** — `.xbsl`/`.yaml` pairing, schema validity, `Ид` as a UUID,
+  `Ид` uniqueness, `Имя` matching the file name.
+- **B. Text and conventions** — typography (en dash, straight quotes),
+  encoding/BOM/newlines/trailing whitespace, indentation and line length.
+- **C. Code structure** — balance of blocks and `;`, brackets, unused local and loop variables,
+  plus the platform's code style conventions (the `style/` group, see below).
+- **D. Semantics** — against platform data: type existence (in `новый`, `как` casts, annotations,
+  method signatures), form handlers (a yaml handler exists as a method in the paired module), and
+  top-level object properties against the configuration metamodel.
+
+## Code style conventions (the `style/` rules)
+
+Twenty-one rules that follow the platform documentation ("Code style conventions" and "Language
+idioms"): layout and expression wrapping, naming, type descriptions and signatures, collection
+literals, string interpolation, and checks of boolean values and `Неопределено`.
+
+Rules that clean code already satisfies are enabled by default (`warning`) — they guard against
+regressions. Rules that typically fire on accumulated legacy debt are `info` and disabled; enable
+them to measure the debt and pay it down:
+
+```sh
+xbsllint path/to/sources --select style     # all conventions, including the disabled ones
+xbsllint path/to/sources --ignore style     # none of them
+```
+
+`Запрос{ ... }` blocks (the query DSL) and string literals (HTML/CSS/SVG in web views) are
+excluded from these checks. Not covered, and left to the author and review: indentation being a
+multiple of four, collection idioms, `Строки.Соединить()` for bulk concatenation, the `?.` / `??`
+idioms, and `выбор` instead of an `иначе если` chain.
+
+## MCP server
+
+A thin adapter over the same core: an agent (e.g. Claude Code) can call the checks as tools and
+receive structured diagnostics.
+
+```sh
+pip install -e ".[mcp]"
+claude mcp add xbsllint -- xbsllint-mcp
+```
+
+Tools: `lint_paths(paths)`, `lint_source(filename, content)`, `list_rules()`. The core and the CLI
+do not require `mcp` — it lives only in the `[mcp]` extra.
+
+## Web interface
+
+A local page: point it at a project folder and see the diagnostics. Standard library only (no
+external dependencies), binds to `127.0.0.1` only.
+
+```sh
+xbsllint-web            # then open http://127.0.0.1:8771/
+```
+
+Per-tier rule toggles, a data-version selector, severity/text filters, dark/light theme; clicking
+a diagnostic opens the file in VS Code (`vscode://`).
+
+## Element versions
+
+The data is versioned by platform version:
+
+```
+xbsllint/data/element/
+    index.json            # { available: [...], default: "<version>" }
+    <version>/{language.json, stdlib.json, metamodel.json}
+```
+
+Pick a version with `--element-version` / the `XBSLLINT_ELEMENT_VERSION` env var / the index
+`default`; `--version` shows what is available. Add a new version by re-running the extractors with
+a new `--dist`.
+
+## Tests
+
+```sh
+pip install -e ".[dev]"
+pytest
+```
+
+Data-dependent tests are skipped automatically when the data has not been generated.
+
+## License
+
+MIT — see [LICENSE](LICENSE). Trademarks and data provenance — [NOTICE](NOTICE).
+How to add a rule — [CONTRIBUTING.md](CONTRIBUTING.md).

xbsllint-0.2.0/README.md

@@ -0,0 +1,129 @@
+# xbsl-lint
+
+**English** · [Русский](README.ru.md)
+
+![CI](https://github.com/keyfire/xbsl-lint/actions/workflows/ci.yml/badge.svg)
+
+A linter for 1C:Element sources — it checks `Name.yaml` (element description) and `Name.xbsl`
+(code module) pairs before the server-side compilation that happens on deploy.
+
+> 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](NOTICE).
+
+## Why
+
+1C:Element has no external linter: the only code check is the server-side compilation on deploy —
+it is slow and knows nothing about project conventions. xbsl-lint gives fast local feedback and
+catches what the compiler does not check at all.
+
+## Step 1: generate the language data
+
+The linter relies on language tables (bilingual keywords, operators), an stdlib type catalog, and
+the configuration metamodel (element properties). XBSL is built on Eclipse Xtext + ANTLR; these are
+extracted from **your** 1C:Element distribution (the `InternalBsl.g` grammar, the documentation, and
+the `.xcore` metamodel) and are NOT bundled in this repository. Generate them locally:
+
+```sh
+python tools/extract_grammar.py   --dist "<path to the 1C:Element distribution>"
+python tools/extract_stdlib.py    --dist "<path to the 1C:Element distribution>"
+python tools/extract_metamodel.py --dist "<path to the 1C:Element distribution>"
+```
+
+The scripts auto-detect the platform version and place the data under
+`xbsllint/data/element/<version>/` (this folder is gitignored). Without the data, the linter and
+the tests will tell you to generate it.
+
+## Step 2: install and run
+
+```sh
+pip install -e .
+xbsllint path/to/sources        # or: python -m xbsllint path/to/sources
+```
+
+Flags: `--list-rules`, `--select`/`--ignore` (by rule id, rule group — the part of the id before
+`/` — or tier letter), `--element-version`.
+
+## Rule tiers
+
+- **A. Structure and YAML** — `.xbsl`/`.yaml` pairing, schema validity, `Ид` as a UUID,
+  `Ид` uniqueness, `Имя` matching the file name.
+- **B. Text and conventions** — typography (en dash, straight quotes),
+  encoding/BOM/newlines/trailing whitespace, indentation and line length.
+- **C. Code structure** — balance of blocks and `;`, brackets, unused local and loop variables,
+  plus the platform's code style conventions (the `style/` group, see below).
+- **D. Semantics** — against platform data: type existence (in `новый`, `как` casts, annotations,
+  method signatures), form handlers (a yaml handler exists as a method in the paired module), and
+  top-level object properties against the configuration metamodel.
+
+## Code style conventions (the `style/` rules)
+
+Twenty-one rules that follow the platform documentation ("Code style conventions" and "Language
+idioms"): layout and expression wrapping, naming, type descriptions and signatures, collection
+literals, string interpolation, and checks of boolean values and `Неопределено`.
+
+Rules that clean code already satisfies are enabled by default (`warning`) — they guard against
+regressions. Rules that typically fire on accumulated legacy debt are `info` and disabled; enable
+them to measure the debt and pay it down:
+
+```sh
+xbsllint path/to/sources --select style     # all conventions, including the disabled ones
+xbsllint path/to/sources --ignore style     # none of them
+```
+
+`Запрос{ ... }` blocks (the query DSL) and string literals (HTML/CSS/SVG in web views) are
+excluded from these checks. Not covered, and left to the author and review: indentation being a
+multiple of four, collection idioms, `Строки.Соединить()` for bulk concatenation, the `?.` / `??`
+idioms, and `выбор` instead of an `иначе если` chain.
+
+## MCP server
+
+A thin adapter over the same core: an agent (e.g. Claude Code) can call the checks as tools and
+receive structured diagnostics.
+
+```sh
+pip install -e ".[mcp]"
+claude mcp add xbsllint -- xbsllint-mcp
+```
+
+Tools: `lint_paths(paths)`, `lint_source(filename, content)`, `list_rules()`. The core and the CLI
+do not require `mcp` — it lives only in the `[mcp]` extra.
+
+## Web interface
+
+A local page: point it at a project folder and see the diagnostics. Standard library only (no
+external dependencies), binds to `127.0.0.1` only.
+
+```sh
+xbsllint-web            # then open http://127.0.0.1:8771/
+```
+
+Per-tier rule toggles, a data-version selector, severity/text filters, dark/light theme; clicking
+a diagnostic opens the file in VS Code (`vscode://`).
+
+## Element versions
+
+The data is versioned by platform version:
+
+```
+xbsllint/data/element/
+    index.json            # { available: [...], default: "<version>" }
+    <version>/{language.json, stdlib.json, metamodel.json}
+```
+
+Pick a version with `--element-version` / the `XBSLLINT_ELEMENT_VERSION` env var / the index
+`default`; `--version` shows what is available. Add a new version by re-running the extractors with
+a new `--dist`.
+
+## Tests
+
+```sh
+pip install -e ".[dev]"
+pytest
+```
+
+Data-dependent tests are skipped automatically when the data has not been generated.
+
+## License
+
+MIT — see [LICENSE](LICENSE). Trademarks and data provenance — [NOTICE](NOTICE).
+How to add a rule — [CONTRIBUTING.md](CONTRIBUTING.md).

xbsllint-0.2.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "xbsllint"
+version = "0.2.0"
+description = "Линтер исходников 1С:Элемент (пары .yaml/.xbsl)"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "xbsl-lint contributors" }]
+keywords = ["1c", "1c-element", "xbsl", "linter", "static-analysis"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "License :: OSI Approved :: MIT License",
+    "Natural Language :: Russian",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Quality Assurance",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "PyYAML>=6.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/keyfire/xbsl-lint"
+Repository = "https://github.com/keyfire/xbsl-lint"
+
+[project.optional-dependencies]
+dev = ["pytest>=7"]
+mcp = ["mcp>=1.2"]
+
+[project.scripts]
+xbsllint = "xbsllint.cli:main"
+xbsllint-mcp = "xbsllint.mcp_server:main"
+xbsllint-web = "xbsllint.web:main"
+
+[tool.setuptools]
+packages = ["xbsllint", "xbsllint.rules"]
+
+[tool.setuptools.package-data]
+xbsllint = ["data/element/index.json", "data/element/*/*.json"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

xbsllint-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

xbsllint-0.2.0/tests/test_corpus.py

@@ -0,0 +1,27 @@
+"""Инвариант: реальный корпус проходит линтер без замечаний по умолчанию.
+
+Тест пропускается, если корпус недоступен (переносимость).
+Путь задаётся переменной окружения XBSLLINT_CORPUS.
+"""
+
+import os
+from pathlib import Path
+
+import pytest
+
+from xbsllint import engine
+from xbsllint.cli import discover
+
+_CORPUS = os.environ.get("XBSLLINT_CORPUS")
+
+
+@pytest.mark.skipif(not (_CORPUS and Path(_CORPUS).exists()), reason="корпус недоступен (задайте XBSLLINT_CORPUS)")
+def test_corpus_no_errors_and_only_known_warnings():
+    # Корпус – валидный задеплоенный код: ошибок линтера быть не должно. Допустимы только
+    # известные находки code/unused-loop-var (их же выдаёт серверная компиляция); любое
+    # другое срабатывание на корпусе – признак ложного и должно ловиться тестом.
+    diags = engine.run(discover([str(_CORPUS)]))
+    errors = [d for d in diags if d.severity.value == "error"]
+    assert not errors, f"неожиданные ошибки: {[d.format() for d in errors[:5]]}"
+    unexpected = [d for d in diags if d.rule_id != "code/unused-loop-var"]
+    assert not unexpected, f"неожиданные замечания: {[d.format() for d in unexpected[:5]]}"

xbsllint-0.2.0/tests/test_dataset.py

@@ -0,0 +1,27 @@
+"""Проверки версионированного доступа к данным (самодостаточность, выбор версии)."""
+
+import pytest
+
+from xbsllint import dataset
+
+
+def test_default_is_available():
+    assert dataset.available_versions()
+    assert dataset.default_version() in dataset.available_versions()
+
+
+def test_load_language_and_stdlib():
+    lang = dataset.load_json("language.json")
+    assert lang["keywords"]["METHOD"]["forms"]
+    std = dataset.load_json("stdlib.json")
+    assert "Массив" in std["names"]
+
+
+def test_data_stamped_with_element_version():
+    lang = dataset.load_json("language.json")
+    assert lang["meta"]["element_version"] == dataset.default_version()
+
+
+def test_invalid_version_raises():
+    with pytest.raises(dataset.DatasetError):
+        dataset.resolve_version("0.0.0-нет-такой")

xbsllint-0.2.0/tests/test_language.py

@@ -0,0 +1,20 @@
+"""Проверки сгенерированных языковых данных (language.json)."""
+
+from xbsllint.lexer import _keyword_forms, _language, _operators
+
+
+def test_language_has_bilingual_keywords():
+    lang = _language()
+    assert lang["keywords"]["METHOD"]["forms"], "у METHOD должны быть формы"
+    kf = _keyword_forms()
+    assert kf.get("метод") == "METHOD"
+    assert kf.get("method") == "METHOD"
+    assert kf.get("возврат") == "RETURN"
+
+
+def test_operators_have_multichar_and_sorted_longest_first():
+    ops = _operators()
+    for op in ("??", "?.", "::", "->", "==", "!="):
+        assert op in ops, f"оператор {op} отсутствует"
+    # по убыванию длины (для максимального откуса в лексере)
+    assert len(ops[0]) >= len(ops[-1])

xbsllint-0.2.0/tests/test_lexer.py

@@ -0,0 +1,42 @@
+"""Проверки лексера XBSL."""
+
+from xbsllint.lexer import tokenize
+
+
+def _kinds(text):
+    return [t.kind for t in tokenize(text)]
+
+
+def test_keywords_bilingual_with_canonical():
+    toks = tokenize("метод Ф(): Строка\n    возврат 1\n;\n")
+    canon = {t.canonical for t in toks if t.kind == "KEYWORD"}
+    assert "METHOD" in canon
+    assert "RETURN" in canon
+
+
+def test_string_and_comment_recognized():
+    kinds = _kinds('// коммент\nзнч s = "привет"\n')
+    assert "COMMENT" in kinds
+    assert "STRING" in kinds
+
+
+def test_number_with_dot_is_single_token():
+    nums = [t for t in tokenize("знч x = 1.5\n") if t.kind == "NUMBER"]
+    assert len(nums) == 1
+    assert nums[0].value == "1.5"
+
+
+def test_positions_are_1_indexed():
+    first = tokenize("метод Ф()\n;\n")[0]
+    assert (first.line, first.col) == (1, 1)
+
+
+def test_operators_do_not_produce_unknown():
+    toks = tokenize("знч x = a ?? b?.c\nзнч f = (п) -> п\n")
+    assert not any(t.kind == "UNKNOWN" for t in toks)
+
+
+def test_capitalized_form_still_keyword_token():
+    # 'Выбор' лексически — форма ключевого слова CASE (различение по контексту — на уровне правил)
+    toks = [t for t in tokenize("знч Выбор = 1\n") if t.kind == "KEYWORD"]
+    assert any(t.canonical == "CASE" for t in toks)

xbsllint-0.2.0/tests/test_mcp.py

@@ -0,0 +1,41 @@
+"""Проверка MCP-адаптера через подставной FastMCP (не требует установленного mcp)."""
+
+import importlib
+import sys
+import types
+
+
+class _FakeMCP:
+    def __init__(self, name):
+        self.name = name
+        self.tools = {}
+
+    def tool(self):
+        def deco(fn):
+            self.tools[fn.__name__] = fn
+            return fn
+
+        return deco
+
+    def run(self):  # pragma: no cover
+        pass
+
+
+def test_mcp_adapter_registers_tools_and_lints(monkeypatch):
+    fast = types.ModuleType("mcp.server.fastmcp")
+    fast.FastMCP = _FakeMCP
+    monkeypatch.setitem(sys.modules, "mcp", types.ModuleType("mcp"))
+    monkeypatch.setitem(sys.modules, "mcp.server", types.ModuleType("mcp.server"))
+    monkeypatch.setitem(sys.modules, "mcp.server.fastmcp", fast)
+    sys.modules.pop("xbsllint.mcp_server", None)
+
+    m = importlib.import_module("xbsllint.mcp_server")
+    assert {"lint_paths", "lint_source", "list_rules"}.issubset(m.mcp.tools)
+
+    rules = m.list_rules()
+    assert any(r["id"] == "code/blocks" for r in rules)
+
+    res = m.lint_source("М.xbsl", "метод Ф()  \n;\n", select=["whitespace/trailing"])
+    assert res["summary"]["diagnostics"] >= 1
+
+    sys.modules.pop("xbsllint.mcp_server", None)