xbsllint 0.2.0__py3-none-any.whl

xbsllint/__init__.py

@@ -0,0 +1,3 @@
+"""xbsl-lint – линтер исходников 1С:Элемент (пары .yaml/.xbsl)."""
+
+__version__ = "0.2.0"

xbsllint/__main__.py

@@ -0,0 +1,4 @@
+from xbsllint.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

xbsllint/cli.py

@@ -0,0 +1,126 @@
+"""Точка входа командной строки: xbsllint / python -m xbsllint."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from xbsllint import __version__, dataset
+
+
+def discover(paths: list[str]) -> list[Path]:
+    """Собрать файлы исходников (.xbsl и .yaml) по указанным путям."""
+    out: list[Path] = []
+    for raw in paths:
+        p = Path(raw)
+        if p.is_file():
+            if p.suffix in (".xbsl", ".yaml"):
+                out.append(p)
+        elif p.is_dir():
+            out.extend(sorted(p.rglob("*.xbsl")))
+            out.extend(sorted(p.rglob("*.yaml")))
+    # Уникализируем, сохраняя порядок
+    seen: set[Path] = set()
+    uniq: list[Path] = []
+    for f in out:
+        rp = f.resolve()
+        if rp not in seen:
+            seen.add(rp)
+            uniq.append(f)
+    return uniq
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="xbsllint",
+        description="Линтер исходников 1С:Элемент (пары .yaml/.xbsl).",
+    )
+    parser.add_argument("paths", nargs="*", default=["."], help="файлы или каталоги для проверки")
+    parser.add_argument(
+        "--select",
+        metavar="ID/ГРУППА/ТИР",
+        help="проверять только эти правила (через запятую: id, группа – часть id до '/' "
+             "(напр. style) – или буква тира A/B/C/D)",
+    )
+    parser.add_argument(
+        "--ignore",
+        metavar="ID/ГРУППА/ТИР",
+        help="исключить эти правила (через запятую: id, группа или буква тира)",
+    )
+    parser.add_argument(
+        "--list-rules", action="store_true", help="вывести список правил и выйти"
+    )
+    parser.add_argument(
+        "--element-version",
+        metavar="ВЕРСИЯ",
+        help="версия данных Элемента (по умолчанию – последняя из бандла)",
+    )
+    data_note = ""
+    try:
+        data_note = (
+            f" (данные Элемента: {dataset.default_version()}; "
+            f"доступно: {', '.join(dataset.available_versions())})"
+        )
+    except dataset.DatasetError:
+        pass
+    parser.add_argument("--version", action="version", version=f"xbsllint {__version__}{data_note}")
+    return parser
+
+
+def _parse_set(value: str | None) -> set[str] | None:
+    if not value:
+        return None
+    return {part.strip() for part in value.split(",") if part.strip()}
+
+
+def main(argv: list[str] | None = None) -> int:
+    # Вывод линтера всегда в UTF-8, независимо от кодировки консоли (важно для кириллицы
+    # и для перенаправления в файл/редактор).
+    for stream in (sys.stdout, sys.stderr):
+        reconfigure = getattr(stream, "reconfigure", None)
+        if reconfigure is not None:
+            try:
+                reconfigure(encoding="utf-8")
+            except (ValueError, OSError):
+                pass
+
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.element_version:
+        dataset.set_version(args.element_version)
+    try:
+        dataset.resolve_version()  # проверить доступность выбранной версии данных
+    except dataset.DatasetError as exc:
+        print(f"Ошибка данных Элемента: {exc}", file=sys.stderr)
+        return 2
+
+    from xbsllint.engine import RULES, run
+
+    if args.list_rules:
+        for r in sorted(RULES, key=lambda x: (x.tier, x.id)):
+            mark = "   " if r.enabled_by_default else "off"
+            print(f"{r.tier} {mark} {r.id:30} {r.severity.value:7} {r.title}")
+        if not RULES:
+            print("(правила ещё не зарегистрированы)")
+        return 0
+
+    files = discover(args.paths or ["."])
+    diagnostics = run(files, select=_parse_set(args.select), ignore=_parse_set(args.ignore))
+    for d in sorted(diagnostics, key=lambda x: x.sort_key()):
+        print(d.format())
+
+    n_xbsl = sum(1 for f in files if f.suffix == ".xbsl")
+    n_yaml = sum(1 for f in files if f.suffix == ".yaml")
+    n_err = sum(1 for d in diagnostics if d.severity.value == "error")
+    print(
+        f"\nПроверено файлов: {len(files)} ({n_xbsl} .xbsl, {n_yaml} .yaml); "
+        f"замечаний: {len(diagnostics)} (ошибок: {n_err})",
+        file=sys.stderr,
+    )
+    return 1 if n_err else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

xbsllint/dataset.py

@@ -0,0 +1,70 @@
+"""Версионированный доступ к данным о языке и типах (самодостаточно, без дистрибутива).
+
+Данные лежат в xbsllint/data/element/<версия>/{language.json, stdlib.json}, а
+xbsllint/data/element/index.json хранит список доступных версий и версию по умолчанию.
+Версия выбирается так: явный аргумент/set_version > env XBSLLINT_ELEMENT_VERSION > default из индекса.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from functools import lru_cache
+from pathlib import Path
+
+DATA_ROOT = Path(__file__).parent / "data" / "element"
+_ENV_VERSION = "XBSLLINT_ELEMENT_VERSION"
+_selected: str | None = None
+
+
+class DatasetError(RuntimeError):
+    pass
+
+
+def _read_index() -> dict:
+    idx = DATA_ROOT / "index.json"
+    if not idx.exists():
+        raise DatasetError(
+            f"Нет индекса версий данных: {idx}. Сгенерируйте данные через tools/extract_*.py."
+        )
+    return json.loads(idx.read_text(encoding="utf-8"))
+
+
+def available_versions() -> list[str]:
+    try:
+        return list(_read_index().get("available", []))
+    except DatasetError:
+        return []
+
+
+def default_version() -> str:
+    version = _read_index().get("default")
+    if not version:
+        raise DatasetError("В индексе версий не задан default")
+    return version
+
+
+def set_version(version: str | None) -> None:
+    """Зафиксировать версию данных для процесса (CLI --element-version). Сбрасывает кэш."""
+    global _selected
+    _selected = version
+    load_json.cache_clear()
+
+
+def resolve_version(override: str | None = None) -> str:
+    version = override or _selected or os.environ.get(_ENV_VERSION) or default_version()
+    avail = available_versions()
+    if version not in avail:
+        raise DatasetError(
+            f"Версия данных '{version}' недоступна. Доступны: {', '.join(avail) or '—'}"
+        )
+    return version
+
+
+@lru_cache(maxsize=None)
+def load_json(name: str, version: str | None = None) -> dict:
+    ver = resolve_version(version)
+    path = DATA_ROOT / ver / name
+    if not path.exists():
+        raise DatasetError(f"Нет файла данных '{name}' для версии {ver}: {path}")
+    return json.loads(path.read_text(encoding="utf-8"))

xbsllint/diagnostics.py

@@ -0,0 +1,35 @@
+"""Модель диагностик линтера."""
+
+from __future__ import annotations
+
+import enum
+from dataclasses import dataclass
+
+
+class Severity(enum.Enum):
+    ERROR = "error"
+    WARNING = "warning"
+    INFO = "info"
+
+
+@dataclass(frozen=True)
+class Diagnostic:
+    """Одно замечание линтера, привязанное к позиции в файле.
+
+    Строка и колонка – 1-индексированные (как в редакторах и в выводе компиляторов).
+    """
+
+    path: str
+    line: int
+    col: int
+    rule_id: str
+    severity: Severity
+    message: str
+
+    def format(self) -> str:
+        # Формат, дружелюбный к переходу по клику: path:line:col
+        return f"{self.path}:{self.line}:{self.col}: {self.severity.value}: [{self.rule_id}] {self.message}"
+
+    # Сортировка замечаний по месту возникновения
+    def sort_key(self) -> tuple:
+        return (self.path, self.line, self.col, self.rule_id)

xbsllint/engine.py

@@ -0,0 +1,180 @@
+"""Ядро линтера: загрузка исходников, реестр правил и их запуск.
+
+Правила регистрируются декоратором @rule(...) с метаданными (id, тир, severity, scope).
+Область (scope):
+- 'file'    – пофайловое правило: (SourceFile) -> Iterable[Diagnostic];
+- 'project' – кросс-файловое (напр. уникальность Ид): (list[SourceFile]) -> Iterable[Diagnostic].
+
+Тиры: 'A' структура/YAML, 'B' текст/конвенции, 'C' парсер/структура кода, 'D' семантика.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from xbsllint.diagnostics import Diagnostic, Severity
+
+UTF8_BOM = b"\xef\xbb\xbf"
+
+
+@dataclass
+class SourceFile:
+    path: Path
+    kind: str  # 'xbsl' | 'yaml'
+    data: bytes
+    text: str
+    had_bom: bool
+    newline: str  # '\n', '\r\n', '\r', 'mixed' или '' если переводов строк нет
+    decode_error: str | None = None
+    # Кэш тяжёлых представлений (токены, AST, YAML) – заполняется по требованию
+    cache: dict = field(default_factory=dict)
+
+    @property
+    def rel(self) -> str:
+        return str(self.path)
+
+
+def _detect_newline(data: bytes) -> str:
+    crlf = data.count(b"\r\n")
+    cr = data.count(b"\r") - crlf
+    lf = data.count(b"\n") - crlf
+    kinds = [k for k, n in (("\r\n", crlf), ("\r", cr), ("\n", lf)) if n]
+    if not kinds:
+        return ""
+    if len(kinds) > 1:
+        return "mixed"
+    return kinds[0]
+
+
+def make_source(path: Path, data: bytes) -> SourceFile:
+    """Собрать SourceFile из пути и байтов (общий код для диска и памяти)."""
+    kind = "xbsl" if path.suffix == ".xbsl" else "yaml"
+    had_bom = data.startswith(UTF8_BOM)
+    decode_error: str | None = None
+    try:
+        text = data.decode("utf-8-sig")
+    except UnicodeDecodeError as exc:
+        decode_error = str(exc)
+        text = data.decode("utf-8", errors="replace")
+    return SourceFile(
+        path=path,
+        kind=kind,
+        data=data,
+        text=text,
+        had_bom=had_bom,
+        newline=_detect_newline(data),
+        decode_error=decode_error,
+    )
+
+
+def load(path: Path) -> SourceFile:
+    return make_source(path, path.read_bytes())
+
+
+def load_text(name: str, content: str) -> SourceFile:
+    """Собрать SourceFile из содержимого в памяти (для MCP lint_source)."""
+    return make_source(Path(name), content.encode("utf-8"))
+
+
+# --- Реестр правил -------------------------------------------------------------------
+
+FileRuleFn = Callable[[SourceFile], Iterable[Diagnostic]]
+ProjectRuleFn = Callable[[list[SourceFile]], Iterable[Diagnostic]]
+
+
+@dataclass(frozen=True)
+class RuleInfo:
+    id: str
+    title: str
+    tier: str  # 'A' | 'B' | 'C' | 'D'
+    scope: str  # 'file' | 'project'
+    severity: Severity
+    func: Callable
+    enabled_by_default: bool = True
+
+    def as_dict(self) -> dict:
+        return {
+            "id": self.id,
+            "title": self.title,
+            "tier": self.tier,
+            "scope": self.scope,
+            "severity": self.severity.value,
+            "enabled_by_default": self.enabled_by_default,
+        }
+
+
+RULES: list[RuleInfo] = []
+
+
+def rule(
+    rule_id: str,
+    title: str,
+    tier: str,
+    *,
+    scope: str = "file",
+    severity: Severity = Severity.WARNING,
+    enabled_by_default: bool = True,
+) -> Callable[[Callable], Callable]:
+    """Декоратор регистрации правила с метаданными."""
+
+    def deco(fn: Callable) -> Callable:
+        RULES.append(RuleInfo(rule_id, title, tier, scope, severity, fn, enabled_by_default))
+        return fn
+
+    return deco
+
+
+def _is_selected(info: RuleInfo, select: set[str] | None, ignore: set[str] | None) -> bool:
+    # select/ignore сопоставляются по id правила, по группе (часть id до '/')
+    # или по букве тира ('A'..'D')
+    group = info.id.split("/", 1)[0]
+
+    def matches(keys: set[str]) -> bool:
+        return info.id in keys or group in keys or info.tier in keys
+
+    if ignore and matches(ignore):
+        return False
+    if select:
+        # Явный выбор включает правило, даже если оно выключено по умолчанию
+        return matches(select)
+    return info.enabled_by_default
+
+
+def active_rules(select: set[str] | None = None, ignore: set[str] | None = None) -> list[RuleInfo]:
+    return [r for r in RULES if _is_selected(r, select, ignore)]
+
+
+def run_sources(
+    sources: list[SourceFile],
+    *,
+    select: set[str] | None = None,
+    ignore: set[str] | None = None,
+    scopes: tuple[str, ...] = ("file", "project"),
+) -> list[Diagnostic]:
+    diags: list[Diagnostic] = []
+    active = active_rules(select, ignore)
+    if "file" in scopes:
+        file_rules = [r for r in active if r.scope == "file"]
+        for src in sources:
+            for r in file_rules:
+                diags.extend(r.func(src))
+    if "project" in scopes:
+        for r in (r for r in active if r.scope == "project"):
+            diags.extend(r.func(sources))
+    return diags
+
+
+def run(
+    paths: list[Path],
+    *,
+    select: set[str] | None = None,
+    ignore: set[str] | None = None,
+) -> list[Diagnostic]:
+    sources = [load(p) for p in paths]
+    return run_sources(sources, select=select, ignore=ignore)
+
+
+# Импорт пакета правил регистрирует их (декораторы выполняются при импорте модулей).
+from xbsllint import rules as _rules  # noqa: E402,F401

xbsllint/lexer.py

@@ -0,0 +1,222 @@
+"""Лексер XBSL.
+
+Токенизация верна грамматике платформы (InternalBsl.g): двуязычные ключевые слова,
+идентификаторы (Latin/Cyrillic/CJK), числа (в т.ч. форма с буквенными частями),
+многострочные строки с экранированием и интерполяцией, комментарии // /* */ /** */.
+
+Языковые таблицы берутся из xbsllint/data/language.json (генерит tools/extract_grammar.py).
+"""
+
+from __future__ import annotations
+
+import bisect
+import re
+from dataclasses import dataclass, field
+from functools import lru_cache
+
+from xbsllint import dataset
+
+# Класс «буквы» из fragment RULE_LETTER грамматики (Latin + Cyrillic в Ā..῿ + CJK).
+_LETTER = (
+    "A-Za-z"
+    "À-ÖØ-öø-ÿ"
+    "Ā-῿぀-㆏㌀-㍿㐀-㴭一-鿿豈-﫿"
+)
+_IDENT_RE = re.compile(rf"[_{_LETTER}][_{_LETTER}0-9]*")
+# RULE_LITERAL_WITH_NUMBER_PARTS: сначала форма с буквенными частями (макс. откус), затем число.
+_NUMBER_RE = re.compile(rf"(?:[0-9]+[{_LETTER}]+)+[0-9]*|[0-9]+(?:\.[0-9]+)?")
+
+
+@lru_cache(maxsize=1)
+def _language() -> dict:
+    return dataset.load_json("language.json")
+
+
+@lru_cache(maxsize=1)
+def _keyword_forms() -> dict[str, str]:
+    forms: dict[str, str] = {}
+    for canon, entry in _language()["keywords"].items():
+        for f in entry["forms"]:
+            forms[f] = canon
+    return forms
+
+
+@lru_cache(maxsize=1)
+def _operators() -> list[str]:
+    # По убыванию длины – для максимального откуса (?? и ?. раньше ?, :: раньше : и т.д.)
+    return sorted(_language()["operators"], key=lambda s: (-len(s), s))
+
+
+@dataclass
+class Token:
+    kind: str  # KEYWORD | IDENT | NUMBER | STRING | COMMENT | OP | BOM | UNKNOWN | EOF
+    value: str
+    start: int  # смещение начала (вкл.)
+    end: int  # смещение конца (искл.)
+    line: int  # 1-индекс
+    col: int  # 1-индекс
+    end_line: int
+    end_col: int
+    canonical: str | None = None  # для KEYWORD – канон (IF/METHOD/...)
+    subkind: str | None = None  # для COMMENT – line|block|doc
+    flags: dict = field(default_factory=dict)  # напр. {'unterminated': True}
+
+    def __repr__(self) -> str:  # компактно для отладки
+        v = self.value if len(self.value) <= 20 else self.value[:17] + "..."
+        extra = f" {self.canonical}" if self.canonical else (f" {self.subkind}" if self.subkind else "")
+        return f"<{self.kind}{extra} {v!r} @{self.line}:{self.col}>"
+
+
+def _line_starts(text: str) -> list[int]:
+    starts = [0]
+    i, n = 0, len(text)
+    while i < n:
+        c = text[i]
+        if c == "\r":
+            i += 2 if (i + 1 < n and text[i + 1] == "\n") else 1
+            starts.append(i)
+        elif c == "\n":
+            i += 1
+            starts.append(i)
+        else:
+            i += 1
+    return starts
+
+
+class _LineMap:
+    def __init__(self, text: str) -> None:
+        self._starts = _line_starts(text)
+
+    def linecol(self, offset: int) -> tuple[int, int]:
+        line = bisect.bisect_right(self._starts, offset)
+        return line, offset - self._starts[line - 1] + 1
+
+
+def tokenize(text: str) -> list[Token]:
+    """Разобрать исходный текст в список токенов (без пробелов и переводов строк)."""
+    lm = _LineMap(text)
+    ops = _operators()
+    kwforms = _keyword_forms()
+    tokens: list[Token] = []
+    i, n = 0, len(text)
+
+    def emit(kind: str, start: int, end: int, **kw) -> None:
+        sl, sc = lm.linecol(start)
+        el, ec = lm.linecol(end)
+        tokens.append(Token(kind, text[start:end], start, end, sl, sc, el, ec, **kw))
+
+    while i < n:
+        c = text[i]
+
+        # BOM (обычно снимается при декодировании utf-8-sig, но на всякий случай)
+        if c == "":
+            emit("BOM", i, i + 1)
+            i += 1
+            continue
+
+        # Пробелы и переводы строк – тривия, пропускаем
+        if c in " \t":
+            i += 1
+            continue
+        if c in "\r\n":
+            i += 2 if (c == "\r" and i + 1 < n and text[i + 1] == "\n") else 1
+            continue
+
+        # Комментарии (раньше оператора '/')
+        if c == "/" and i + 1 < n:
+            nxt = text[i + 1]
+            if nxt == "/":
+                j = i + 2
+                while j < n and text[j] not in "\r\n":
+                    j += 1
+                emit("COMMENT", i, j, subkind="line")
+                i = j
+                continue
+            if nxt == "*":
+                # doc-комментарий /** ... */ (но не /**/), иначе блочный /* ... */
+                is_doc = text.startswith("/**", i) and not text.startswith("/**/", i)
+                close = text.find("*/", i + 2)
+                if close == -1:
+                    emit("COMMENT", i, n, subkind="doc" if is_doc else "block", flags={"unterminated": True})
+                    i = n
+                    continue
+                end = close + 2
+                emit("COMMENT", i, end, subkind="doc" if is_doc else "block")
+                i = end
+                continue
+
+        # Строки (многострочные, с экранированием \)
+        if c == '"':
+            j = i + 1
+            unterminated = True
+            while j < n:
+                cj = text[j]
+                if cj == "\\":
+                    j += 2
+                    continue
+                if cj == '"':
+                    j += 1
+                    unterminated = False
+                    break
+                j += 1
+            flags = {"unterminated": True} if unterminated else {}
+            emit("STRING", i, min(j, n), flags=flags)
+            i = min(j, n)
+            continue
+
+        # Числа (лидирующая цифра ⇒ число)
+        if c.isdigit():
+            m = _NUMBER_RE.match(text, i)
+            end = m.end() if m else i + 1
+            emit("NUMBER", i, end)
+            i = end
+            continue
+
+        # Идентификаторы и ключевые слова (максимальный откус, затем проверка на ключевое слово)
+        if c == "_" or _IDENT_RE.match(text, i):
+            m = _IDENT_RE.match(text, i)
+            word = m.group(0)
+            canon = kwforms.get(word)
+            if canon is not None:
+                emit("KEYWORD", i, m.end(), canonical=canon)
+            else:
+                emit("IDENT", i, m.end())
+            i = m.end()
+            continue
+
+        # Операторы и пунктуация (максимальный откус по длине)
+        matched = None
+        for op in ops:
+            if text.startswith(op, i):
+                matched = op
+                break
+        if matched is not None:
+            emit("OP", i, i + len(matched))
+            i += len(matched)
+            continue
+
+        # Неизвестный символ – одиночный токен (пусть правило его пометит)
+        emit("UNKNOWN", i, i + 1)
+        i += 1
+
+    sl, sc = lm.linecol(n)
+    tokens.append(Token("EOF", "", n, n, sl, sc, sl, sc))
+    return tokens
+
+
+def tokens(source) -> list[Token]:
+    """Токены исходного файла с кэшированием в source.cache."""
+    cached = source.cache.get("tokens")
+    if cached is None:
+        cached = tokenize(source.text)
+        source.cache["tokens"] = cached
+    return cached
+
+
+def linemap(source) -> _LineMap:
+    """Карта смещение -> (строка, колонка) для файла, с кэшированием."""
+    lm = source.cache.get("linemap")
+    if lm is None:
+        lm = _LineMap(source.text)
+        source.cache["linemap"] = lm
+    return lm