AGENTS.md

Инструкции для агентов

Подготовка среды

• Установи зависимости проекта: opm install -l --dev
• Если для локального запуска тестов в среде нет 1testrunner, установи его: opm install 1testrunner

Структура проекта

• src/
  • BenchmarkOneScript/
    • cmd/ — CLI
    • core/
      • annotations/ — работа с аннотациями
      • common/ — общие утилиты и CLI-парсеры
      • config/ — конфигурация запуска бенчмарков
      • descriptors/ — дескрипторы бенчмарков и их коллекции
      • environment/ — сведения о среде выполнения
      • exporters/ — экспорт результатов и артефактов
      • parameters/ — параметры бенчмарков и их источники
      • reporting/ — построение и вывод отчетов
      • running/ — запуск, процессы, кейсы
      • serialization/ — сериализация настроек и результатов
  • BenchmarkOneScript.Extensions/ — расширение типов для библиотеки
  • Chronometer/ — хронометр для точных замеров времени
• tests/ — наборы тестов
• tasks/ — служебные сценарии запуска тестов и покрытия
• samples/
  • api/ — примеры использования API
  • benchmarks/
    • examples/ — базовые примеры бенчмарков
    • features/ — примеры пользовательских возможностей
  • handlers/ — примеры обработчиков событий
  • paramsSources/ — примеры источников параметров
• docs/ — пользовательская документация
• build/ — служебные сценарии подготовки сборки

Code style

• Следуй существующему стилю в репозитории, не смешивай разные стили в одном файле.
• Публичную библиотечную логику держи в core, CLI-специфику в cmd.
• Для классов и модулей обычно используются регионы:
  • #Область ОбработчикиСобытий
  • #Область ПрограммныйИнтерфейс
  • #Область СлужебныйПрограммныйИнтерфейс
  • #Область СлужебныеПроцедурыИФункции
• Публичные методы и функции располагай в ПрограммныйИнтерфейс, вспомогательные процедуры и функции — в СлужебныеПроцедурыИФункции.
• Служебный, но экспортный программный интерфейс модулей располагай в СлужебныйПрограммныйИнтерфейс.
• Непубличные переменные уровня класса или модуля именуй с префиксом _.
• Публичные методы, конструкторы и другие элементы программного интерфейса документируй комментариями, если трогаешь или добавляешь их.
• Для публичного API сохраняй принятый формат комментариев с блоками Параметры и Возвращаемое значение, если они уместны.
• Новые имена типов, методов и тестовых файлов делай предметными, а не техническими.

Тесты

Запуск

• Точечный запуск набора тестов: 1testrunner tests\Тесты.os
• Точечный запуск отдельного теста: 1testrunner tests\Тесты.os ИмяТеста
• Полный запуск всех тестов: oscript tasks/test.os
• Запуск покрытия: oscript tasks/coverage.os

Когда что запускать

• Для обычной итерации предпочитай точечные прогоны.
• Полный прогон oscript tasks/test.os не запускай без явного запроса пользователя.
• Если меняется покрываемый код, добавь или обнови точечные тесты и запусти минимум релевантный набор.
• Некоторые интеграционные прогоны могут требовать запуск вне песочницы.

Соглашения

• Имена тестов начинаются с ТестДолжен_....
• Для инициализации и завершения уровня набора используй &Инициализация и &Завершение.
• Для подготовки и очистки отдельных тестов допустимо использовать пару &Перед и &После, если это действительно логика уровня отдельного теста.
• В тестах обычно используются регионы:
  • #Область ОбработчикиСобытий
  • #Область Тесты
  • #Область СлужебныеПроцедурыИФункции
• Внутри тестов явно разделяй подготовку, действие и проверку комментариями:
  • // Подготовка
  • // Действие
  • // Проверка
  • если вызов и проверка неразделимы, допустимо // Действие и Проверка
• Если меняются только входные данные и ожидания, предпочитай параметризованные тесты через &Параметры(...).