OpenIntegrations/AGENTS.md

# Руководство для AGENTS

## Каноничный исходный код

- Основная реализация библиотеки находится в `src/ru/BSL/OpenIntegrations`.
- Если поведение кода и тестов расходится, в первую очередь считать этот каталог источником истины.

## Каноничные тесты

- Основные BSL-тесты находятся в `src/ru/BSL/Tests`.
- При разборе бизнес-логики сначала анализировать эти тесты, и только затем зеркала.

## Зеркало OneScript

- Зеркальные файлы OneScript находятся в `src/ru/OInt` (включая `src/ru/OInt/tests`).
- Использовать этот каталог для проверки CLI/runtime-паритета, но не как первый источник при разборе BSL-регрессий.

## Соглашения по тестовым модулям

- У каждого функционального модуля есть два связанных тестовых модуля с тем же базовым именем:
  - основные тесты с префиксом `OPIt_`
  - тесты CLI с префиксом `OPItc_`
  - функциональные модули используют префикс `OPI_`
- Не редактировать модули `OPItc_` вручную: CLI-тесты генерируются автоматически в CI-пайплайне из модулей `OPIt_`.
- Каждый тестовый модуль должен содержать:
  - область `ЗапускаемыеТесты` с процедурами-обертками
  - область `АтомарныеТесты` с атомарными проверками
- Запускаемые тесты вызывают несколько атомарных.
- Количество атомарных тестов должно соответствовать количеству методов функционального модуля.
- Количество запускаемых тестов должно соответствовать количеству областей функционального модуля.
- Текст тестовых модулей используется для формирования примеров кода в документации
- Служебные комментарии `//SKIP` и `//END` используются для исключения частей кода теста при формировании примера для документации. `// SKIP` позволяет исключить конкретную строку внутри теста, `//END` - завершает запись примера. Весь служебный код, который идет после `//END` не попадает в пример кода для документации
- При формировании атомарных тестов нельзя выносить повторяющийся код в служебные функции, так как это может привести к недопониманию при их использовании в качестве примеров для документации
- В спорных/неочевидных ситуациях ориентироваться на существующие тесты как на каноничные примеры.

## Реестр и функции проверок

- Каждый запускаемый тест должен быть указан в `ПолучитьТаблицуТестов` в модуле `OPI_ПолучениеДанныхТестов`.
- В `OPI_ПолучениеДанныхТестов` также находятся функции-проверки:
  - по одной функции-проверке на каждый атомарный тест
  - с возможным ветвлением внутри по параметру `Вариант`

## Правила именования

- Формат имени атомарного теста:
  - `<ИмяМодуляБезПрефикса>_<ИмяМетодаФункциональногоМодуля>`
- Формат имени запускаемого теста:
  - `<ЛюбоеСокращениеИмениМодуляБезПрефикса><ИмяОбласти>`
- Формат имени функции-проверки:
  - `Проверка_<ИмяАтомарногоТеста>`