Проверка изменений нативного API — документация

Эталон API, CLI-сравнение, хеши методов и диагностика отличий.

Этот порядок нужен при изменении нативного API ReckfellExtension: аргументов, возвращаемых типов, значений по умолчанию, свойств, сигналов и перечислений. Он сравнивает прежнее описание API с API, зарегистрированным проверяемым редактором. Проверка не охватывает привязки C#, форматы проектов и поведение загруженного расширения.

Сохраните достоверный эталон

Храните прежний и проверяемый редакторы отдельно. Используйте сопоставимые параметры сборки: платформа, точность чисел, включённые модули и устаревшие привязки влияют на состав API. Выгрузка из сокращённого шаблона не заменяет API редактора.

Публичная версия продукта — 1.0.0. Рядом с выгрузкой сохраняйте SHA-256 исполняемого файла и параметры сборки: отображаемой версии недостаточно для различения двух сборок в разработке. Не подменяйте эталон выгрузкой проверяемого редактора ради успешного результата.

Задайте в BASE_EDITOR и NEW_EDITOR абсолютные пути к исполняемым файлам командной строки двух редакторов. В QA_PROJECT укажите небольшой корректный проект Reckfell, отдельный от рабочего. Выполняйте команды в новом доступном для записи каталоге проверки. Примеры для shell предполагают, что эти переменные уже заданы:

Командная строка
"$BASE_EDITOR" --headless --xr-mode off --path "$QA_PROJECT" --dump-extension-api

Результат — extension_api.json в текущем рабочем каталоге, а не обязательно в QA_PROJECT. Сохраните его как эталон до следующей команды выгрузки. Проверьте наличие файла, корректность JSON, ожидаемые header и классы. Одного нулевого кода завершения выгрузки недостаточно: верхний уровень этой команды возвращает успех, не передавая результат функции записи.

Сравните проверяемый редактор с сохранённым файлом:

Командная строка
"$NEW_EDITOR" --headless --xr-mode off --path "$QA_PROJECT" --validate-extension-api "$PWD/extension_api.json"

Валидатор возвращает ноль при успешном сравнении, ненулевой код — при отклонённом сравнении или ошибке входных данных. Сохраняйте stdout и stderr. Пока есть предупреждения, одного кода завершения недостаточно для вывода о чистой проверке.

Как читать результат

Входной JSON — прежний контракт, запущенный редактор предоставляет проверяемый API. Проверка направленная: она выясняет, сохранились ли описанные ранее элементы. Это не проверка равенства; намеренно неполный эталон не подтверждает весь API.

Диагностика или изменение	Значение и действие
`Could not open file` / ошибка разбора JSON	Сначала исправьте путь или повреждённый эталон. Это ещё не проблема совместимости.
`different engine version` / более новая minor-версия	Валидатор отклоняет другую major-версию и эталон с большей minor-версией. Не редактируйте заголовок для обхода проверки.
`API was removed`	Элемент эталона отсутствует в проверяемом API. Проверьте зарегистрированное имя и параметры сборки, затем обоснованность удаления.
Изменились число аргументов, тип, результат или `default_value`	Проверьте контракт и сгенерированных потребителей. Даже необязательный новый аргумент может изменить нативную привязку.
`Hash changed`	Прежний хеш метода не совпал с текущим и не найден среди хешей совместимости. Комментарий или правка JSON не исправляют привязку.
Имя аргумента изменилось, сравнение успешно	Сравнение аргументов допускает переименование. Отдельно проверьте исходные вызовы и именованные аргументы: успешный результат не подтверждает совместимость исходного кода.
Структурных различий нет	Запустите затронутое расширение и проверки поведения. Совпадающие сигнатуры не проверяют семантику и владение памятью.

Установленный Runtime сейчас выдаёт 17 предупреждений вида Compatibility hash ... mapped to non-existent hash ... при формировании API. Причина — устаревшие записи специальных соответствий хешей. Сравнение с собственной выгрузкой и целевые отрицательные тесты работают, но предупреждения остаются нерешённой проблемой нативного аудита. Сохраняйте их в отчёте; не подавляйте и не называйте выгрузку свободной от предупреждений.

Изменение нативного метода

Проверяйте вместе объявление C++, вызов ClassDB::bind_method и сгенерированный API. Если существующий контракт Reckfell должен оставаться вызываемым, привязке совместимости нужны прежняя сигнатура и поведение. Предпочтительно передать вызов текущей реализации, а не копировать алгоритм. Прежние значения по умолчанию задавайте явно. Приведение с потерей диапазона или отбрасывание результата требуют отдельных проверок поведения.

В текущей реализации AStarGrid2D есть конкретный образец:

core/math/a_star_grid_2d.h: актуальные трёхаргументные get_id_path и get_point_path, значение allow_partial_path = false.
core/math/a_star_grid_2d.cpp: публичные привязки с DEFVAL(false) и подключение соседнего файла .compat.inc.
core/math/a_star_grid_2d.compat.inc: адаптеры двух аргументов передают false и регистрируются через ClassDB::bind_compatibility_method.

Адаптеры защищены DISABLE_DEPRECATED; параметр deprecated=no определяет этот макрос. Проверяйте ту конфигурацию, которую собираетесь выпускать. Не добавляйте в рамках этой работы прежние имена Entity, устаревшие форматы проектов и мигратор. Адаптеры нативных методов не выполняют миграцию форматов.

После изменения API пересоберите затронутую конфигурацию по соответствующему руководству по сборке, обновите затронутые привязки и пересоберите потребителей. Затем сравните API с сохранённым эталоном и запустите небольшое расширение, проверяющее изменённый метод, значения по умолчанию, результат и владение памятью. Обновите документацию API и запись об изменении. Текстовый файл со списком разрешённых отличий не меняет результат этого CLI-валидатора.

Для проверки руководства установленный редактор Windows создал выгрузку; на временных JSON выполнены сравнение с самим собой и случаи изменённого хеша, значения по умолчанию, имени аргумента, отсутствующего метода, другой major-версии и отсутствующего файла. Движок не пересобирался и не изменялся, совместимость двух релизов не подтверждалась, бинарное нативное расширение не загружалось.