steelmorgan/syntax-checking

Проверка синтаксиса (Syntax Checking)

Любое изменение BSL-кода → немедленная проверка. Без проверки агент может «успешно» завершить задачу с нерабочим кодом.

Два уровня проверки — разная стоимость:

| Инструмент | Скорость | Когда использовать | |------------|----------|-------------------| | get_diagnostics (LSP) | Быстро (секунды) | После каждого изменения, промежуточные проверки | | v8-runner syntax … | Медленно (десятки секунд — минуты) | Финальная проверка: перед коммитом, перед PR, после крупного рефакторинга |

Серверная проверка теперь делается только через CLI v8-runner — отдельные MCP-tools check_syntax/build_project/dump_config упразднены. Подробности команд и правил выбора — в навыке v8-runner (framework/skills/tool-usage/v8-runner/).

Когда применять

| Триггер | Действие | |---------|----------| | После изменения BSL-кода | get_diagnostics — быстрая проверка | | Итеративная правка (цикл edit → check) | get_diagnostics | | После рефакторинга / rename_symbol | get_diagnostics по затронутым файлам | | Ошибка компиляции | get_diagnostics для локализации | | Перед коммитом / перед PR | v8-runner syntax … — финальная проверка | | Завершение задачи | v8-runner syntax … — финальный вердикт |

Самопроверка качества (помимо синтаксиса)

Синтаксис — необходимый минимум, но «компилируется» ≠ «качественно». После того как get_diagnostics/v8-runner syntax подтвердили отсутствие ошибок, прогоните самопроверку по изменённым файлам — это дёшево (LSP, секунды) и ловит то, что синтаксис пропускает:

| Capability | Что показывает | Когда применять | |------------|----------------|-----------------| | get_diagnostics | Все диагностики BSL LS по файлу (точнее workspace-проверки) | После правок — полный список замечаний по файлу | | get_quality_diagnostics | Только security / performance / sql (запрос в цикле, отключение безопасного режима, отсутствие псевдонимов и т.п.) | Перед коммитом — прицельная самопроверка кодером на риски | | get_method_complexity | Цикломатическая + когнитивная сложность по методам, флаг превышения порогов | После написания/правки метода — сигнал «пора рефакторить» (cyclomatic > 20 / cognitive > 15) | | get_module_health | Комбо: сложность + security/perf/sql, сведённые по методам и ранжированные «что рефакторить первым» | Триаж модуля целиком за один вызов — вместо отдельных complexity + quality_diagnostics + ручного сведения |

Это самопроверка кодером, а не замена ревью. get_quality_diagnostics, get_method_complexity и get_module_health опираются на BSL LS; complexity-метрики требуют включённого complexity CodeLens в конфиге BSL LS. Для метрик одного метода — get_method_complexity; для одной категории риска — get_quality_diagnostics; для триажа всего модуля — get_module_health (одиночные при этом не отменяются).

Алгоритм проверки

Промежуточная проверка (после каждого изменения)

1. get_diagnostics(uri) — LSP-диагностика изменённого файла.
2. Если есть error-уровень — исправить и повторить.
3. warning — оценить критичность.

Финальная проверка (перед коммитом)

Выбор команды зависит от format/builder в v8project.yaml (см. v8-runner/references/config-and-backends.md):

# Designer-модули (требует Designer + Designer-формат)
v8-runner build
v8-runner syntax designer-modules --server --thin-client

# Designer-конфигурация
v8-runner build
v8-runner syntax designer-config

# EDT
v8-runner build
v8-runner syntax edt

Тесты (v8-runner test yaxunit …, test va) делают build сами — отдельный build перед ними не нужен.

При расхождении LSP и v8-runner syntax — ориентироваться на v8-runner как финальный вердикт.

Интерпретация результатов

| Поле | Действие | |------|----------| | success: true | Продолжать | | success: false | Исправить errors (каждая: file, line, message, severity) | | warnings | Оценить критичность | | Таймаут | Сузить scope (--source-set <NAME>) или вернуться к LSP по конкретным модулям |

Severity: error (блокирует компиляцию) > warning > information / hint.

Suppression-маркеры как evidence

Suppression-комментарий — это улика, а не декоративный шум. Из него извлекают конкретные коды и проверяют обоснованность отключения.

Синтаксис маркеров

| Инструмент | Синтаксис | |------------|-----------| | АПК | //{ АПК:142 - комментарий … //} | | BSL Language Server | // BSLLS:LineLength-off … // BSLLS:LineLength-on | | EDT | // @suppress-warning("module-empty-method") или //@skip-check |

Методика интерпретации

1. Извлечь буквальные коды из комментария: числовой или мнемонический идентификатор (АПК:142, LineLength, имя правила EDT).
2. Резолвить через справочник стандартов: для АПК-кодов — ask_1c_ai («расшифруй диагностику АПК:142»); для BSL LS — ITS-документация по имени правила; для EDT — документация правил EDT.
3. Признать обоснованным только при тройной поддержке: литеральный код + диапазон отключения + ссылка на стандарт. Если хотя бы один элемент отсутствует — пометить «suppression не обоснован».
4. Приоритет действий: сначала исправить код → затем сузить диапазон подавления → оставить suppression только в крайнем случае с явной ссылкой на стандарт или ограничение платформы.

Признак «suppression не обоснован»

Комментарий не содержит ни кода диагностики, ни ссылки на стандарт — обязательно флагировать для ревью.

// Плохо — нет кода, нет обоснования:
// BSLLS:LineLength-off
ОченьДлиннаяСтрокаБезПояснения = ...
// BSLLS:LineLength-on

// Хорошо — код + диапазон + обоснование:
// BSLLS:LineLength-off // АПК:142: строка формирования запроса, разбиение ухудшает читаемость (ITS: стандарт 720)
ТекстЗапроса = "SELECT ... FROM ...";
// BSLLS:LineLength-on

Capabilities и инструменты

| Capability / CLI | Назначение | Стоимость | |------------------|------------|-----------| | get_diagnostics (MCP lsp-bsl-bridge) | LSP-диагностика файла | Быстро — основной инструмент | | v8-runner syntax designer-modules | Проверка Designer-модулей через платформу | Медленно — только финальная проверка | | v8-runner syntax designer-config | Проверка Designer-конфигурации | Медленно | | v8-runner syntax edt | Проверка EDT-проекта | Медленно |

Контроль результата финальной проверки

v8-runner syntax … может занимать десятки секунд — минуты. Для длительных прогонов используй инструмент Monitor:

1. Запусти в фоне (Bash run_in_background: true), перенаправь stdout в файл лога.
2. Подпишись через Monitor с фильтром ERROR:|error:|Ошибок:|success — уведомление придёт при первом совпадении.
3. Завершай ожидание: процесс завершился ИЛИ в stdout появился error: / Ошибок: 0 / success.
4. После завершения прочитай итог из stdout: при наличии ошибок — файл, строка, текст.

Для коротких прогонов (--source-set <NAME>) Monitor не обязателен — достаточно синхронного запуска.

Типичные ошибки

| Ошибка | Обходной путь | |--------|---------------| | LSP не запущен | v8-runner syntax … как fallback | | Команда syntax … не поддерживается для текущего format/builder | См. v8-runner/references/config-and-backends.md; не изобретать raw 1cv8/ibcmd-флаги | | Таймаут на полной проверке | Сузить через --source-set <NAME>; LSP по конкретным модулям | | Проект EDT не найден | Проверить format/builder и source-set в v8project.yaml | | Непонятные errors | navigate_symbol к месту ошибки; ask_ai_assistant |

---

depends_on:

• framework/skills/tool-usage/v8-runner/SKILL.md

---