Exempt mounted test suites from the manifest id and version rule; mod documentation

docs/ru.md

@@ -0,0 +1,72 @@
+# Validator — проверка модов без запуска игры
+
+Validator читает каждый мод запущенной игры — манифесты, файлы данных, сценарии, патчи сцен и исходники C# — и сообщает, что сломано или подозрительно: ссылку на предмет, сцену или фон, которые никто не объявляет, неизвестную команду сценария, неверный параметр, недостающую зависимость. Проверка запускается в фоне при каждом старте игры и пишет отчёт, так что опечатка находится раньше, чем игрок доберётся до строки с ней.
+
+Проверяется то, что видно в файлах. Validator не играет в игру: сценарий, который он принял, всё равно может вести себя не так, как задумывал автор, а код, собирающий идентификаторы на ходу, проследить невозможно.
+
+## Ошибка и её исправление
+
+Строка сценария, выдающая игроку волчье мясо, с опечаткой в id предмета:
+
+```scenario
+scene: home_kitchen
+priority: 0
+---
+action item.add id=food/wolf_meet count=1
+end
+```
+
+После следующего запуска Cthangover в отчёте появляется:
+
+```json
+{
+  "severity": "error",
+  "code": "REF_NOT_FOUND",
+  "message": "item 'food/wolf_meet' is referenced but never declared",
+  "mod": "cthangover_game",
+  "file": "scenarios/doc_validator_demo.scenario",
+  "line": 4,
+  "suggestion": "declare item 'food/wolf_meet' or fix the reference",
+  "related": null
+}
+```
+
+Мод, файл и строка указывают на ошибку. С `food/wolf_meat` проблема исчезает, а счётчик ошибок в сводке уменьшается на единицу (с 18 до 17 в этом прогоне).
+
+## Как запустить и как читать отчёт
+
+- Проверка стартует сама, когда входишь в игру, которая его содержит (Cthangover включает его в свой набор инструментов разработчика), после загрузки модов и идёт в фоновом потоке; игре она не мешает.
+- В лог на каждый прогон пишется строка: `validator: started, 33 mod(s) queued`, затем итоги по ошибкам, предупреждениям и заметкам.
+- Отчёт пишется в `user://validation/report.json` (в папке пользовательских данных игры). В нём сводка, проверенные моды с их версиями и контрольными суммами и список проблем.
+
+У каждой проблемы есть:
+
+- `severity` — `error` (что-то сломано), `warning` (похоже на ошибку) или `info` (стоит взглянуть, например предмет, на который никто не ссылается);
+- `code` — род проблемы, например `REF_NOT_FOUND`, `JSON_PARSE_ERROR`, `SCHEMA_MISSING_FIELD`, `SCHEMA_UNKNOWN_PARAM`, `DECL_UNUSED`, `DYNAMIC_KEY`;
+- `mod`, `file`, `line` — где исправлять; `suggestion` — что делать.
+
+Заметки `DYNAMIC_KEY` означают, что ключ собирается во время выполнения, и Validator не может его проверить; ошибками они не являются.
+
+## Что проверяется
+
+Проверки идут в три фазы:
+
+1. **Схема** — в `manifest.json` есть строки `id` и `version`; JSON-файлы разбираются.
+2. **Контракты** — что мод объявляет и на что ссылается: сущности всех видов (персонажи, предметы, задания, навыки, рецепты, действия и виды, описанные схемами), команды и действия сценария с их параметрами, патчи сцен, свойства, которые читает и пишет код C#.
+3. **Сверка** — у каждой ссылки есть объявление, `depends` покрывает то, что мод берёт у других, а объявления, которыми никто не пользуется, перечислены.
+
+Сценарные действия и их параметры сверяются со схемами, которые поставляют моды (см. Schemas), по тем же правилам, что и в палитре команд.
+
+## Настройки
+
+На вкладке настроек мода в менеджере модов:
+
+- **Enabled**, **Run on start** — отключают прогон;
+- **Parse C#**, **Parse GDScript** (по умолчанию выключено, медленно), **Parse scenarios** — какие источники читать;
+- **Write report**, **Report path** — куда пишется `report.json`;
+- **Block mods on error** — есть в настройках, но в текущей версии ни на что не влияет: моды не блокируются никогда.
+
+## Если что-то пошло не так
+
+1. **Отчёта нет.** Игра закрылась до конца прогона (для Cthangover это около полуминуты) или выключен **Write report**.
+2. **Много строк `DYNAMIC_KEY`.** Нормально для кода, который собирает ключи; это заметки.