@rt-tools/agent-kit 0.5.2 → 0.6.0

package/assets/rules/testing.md

@@ -2,7 +2,7 @@
 name: testing
 kind: rule
 law: verifiability
-description: Правило под «Закон о проверяемости». Брать при правке любого *.spec.ts и всего, что лежит в apps/site-e2e и apps/admin-e2e. Называет Vitest и Playwright, идентификатор сценария в заголовке, вынос решения в чистую функцию и то, что закрывается сквозной спекой. Готовый код — в паттернах testing-unit и testing-e2e.
+description: Правило под «Закон о проверяемости». Брать при правке любого *.spec.ts и всего, что лежит в сквозных наборах дерева. Называет Vitest и Playwright, идентификатор сценария в заголовке, вынос решения в чистую функцию и то, что закрывается сквозной спекой. Готовый код — в паттернах testing-unit и testing-e2e.
 ---
 
 # Проверяемость — как это устроено здесь
@@ -45,8 +45,21 @@ description: Правило под «Закон о проверяемости».
   переименованный или выкинутый сценарий: тесты при этом остаются зелёными.
 - **Решение выносится в чистую функцию и проверяется вызовом.** Компонент и сервис остаются
   тонкой обёрткой и отдельно не проверяются, пока своего ветвления у них нет.
+- **Решение, зависящее от текущего момента, принимает момент параметром.** Часы машины оно не
+  читает: правило проверяется вызовом, а не подкруткой времени вокруг теста. Умолчание
+  `= new Date()` ставится на границе — там, где решение зовёт процедура или служба.
 - **Процедура Connect проверяется вызовом своего метода с рукописным двойником базы.**
   Контейнер и роутер поднимать не надо: спека проверяет решение, а не раскладку полей.
+- **Сид заводит то, без чего экран не открыть, и ничего, что гость примет за настоящее.**
+  Содержимое, у которого есть автор, — отзывы, вопросы, обсуждения — гость читает как
+  написанное людьми, а стенд собирается из той же базы, что и проверка глазами: три выдуманные
+  цитаты дожили до отдельной задачи и всё это время выглядели отзывами. Настройки владельца —
+  контакты, адрес отправителя, ключи внешних служб — сид не заводит тоже: их вписывают в
+  приложении. То, что нужно редко, включается признаком в окружении, а не сеется всем.
+- **Заведённая проверка встаёт в гейт пуша или в конвейер, а не только в сводную цель.**
+  Сводная цель запускается руками, и проверка, которая живёт только в ней, отвечает тому, кто
+  её вспомнил: молчание такой проверки читается как её зелёный ответ. Три проверки простояли
+  вне гейта, объявляя в собственных списках известного, что падают на новом.
 - **Спека, необратимо меняющая данные стенда, выключена по умолчанию.** `BASE_URL` уводит
   прогон одной переменной, и без выключателя такая спека правила бы данные чужого стенда.
 - **Спеки, которым нужен nginx перед приложением, просыпаются вместе с `BASE_URL`.** Голый
@@ -56,6 +69,24 @@ description: Правило под «Закон о проверяемости».
   `playwright/no-skipped-test` запретил бы его сразу в шестидесяти пяти местах. Рядом со
   строкой отключения пишут причину, а точечный `eslint-disable` остаётся для того, что
   запрещено по делу.
+- **Гард отпускает действие, когда сам сломался.** Нет разборщика входа, пустой ввод, не тот
+  каталог, любая своя ошибка — гард выходит нулём и пропускает: сломанная проверка не имеет
+  права заклинить работу. Объявляется это строкой `FAIL-OPEN` в шапке самого гарда, рядом с
+  перечислением случаев, и туда же дописывается новый случай, когда он находится.
+- **Список известного у проверки именной и объясняет себя сам.** Первым полем перечня стоит имя
+  проверки и слово о том, что перечисленное отказом не считается. Дальше либо два ключа —
+  принятое остаётся навсегда, долг накоплен к заведению проверки и только сокращается, — либо
+  столько ключей, сколько у записей родов. Причина обязательна: снятая проверка без причины
+  через месяц неотличима от недосмотра.
+- **Тест, утверждающий отсутствие, зелен и тогда, когда ищет не то.** Совпадения нет ни у
+  верного текста, ни у опечатки в образце, ни у переименованного ключа — отличить их по цвету
+  прогона нечем. Отрицательное утверждение поэтому идёт в паре с положительным: сначала
+  проверяется, что искомое место вообще найдено, и только потом — что в нём нет того, чего быть
+  не должно.
+- **Заголовок теста обещает больше, чем тело проверяет, и сверка этого не видит.** Номер
+  сценария в заголовке стоит — сценарий числится покрытым, а что именно утверждается, не
+  спрашивает никто. Тело читается вместе с заголовком: обещание в заголовке и утверждение в
+  теле — два разных текста, и расходятся они молча.
 
 ## Чего из закона здесь нет
 
@@ -76,23 +107,30 @@ description: Правило под «Закон о проверяемости».
 - **Зелёный `nx test <проект>` не значит, что хоть один файл исполнялся.** Либа без своего
   `vitest.config.mts` не запускает ничего — так тесты домена броней не запускались ни разу.
   Либа с конфигом, но без единого `*.spec.ts`, проходит зелёной из-за `passWithNoTests: true`,
-  который стоит во всех 203 конфигах дерева, и на глаз эти два случая неотличимы: в обоих
-  прогон успешен. Без единого теста живут 131 либа из 203 — почти две трети. Перед правкой в
+  который обычно стоит в каждом конфиге дерева, и на глаз эти два случая неотличимы: в обоих
+  прогон успешен. Доля либ без единого теста меряется пересчётом ниже — в дереве, где его
+  завели впервые, она вышла почти в две трети. Перед правкой в
   незнакомой либе проверяется, есть ли в ней хоть один `*.spec.ts`; если нет — первый
   заводится этой же правкой, а не откладывается: откладывать здесь не с чего, долг уже
   накоплен. Пересчёт: `for d in $(find libs -name vitest.config.mts -exec dirname {} \;); do
 [ -z "$(find "$d" -name '*.spec.ts')" ] && echo "$d"; done | wc -l`.
+- **Зелёная сводка покрытия не значит, что тесты проходят.** Сверка читает заголовки тестов и
+  сопоставляет их со сценариями спека; исполняется ли тест и чем он кончается — она не знает
+  вовсе, и падающий тест значится в ней покрытием. Три сценария одной панели падали и до правки
+  экрана, а нашлось это только прогоном. Перед правкой экрана его сквозные тесты гоняются один
+  раз до первой строки кода: иначе чужое падение читается как своя регрессия, а своё — как
+  чужое.
 - **«Executable doesn't exist» — состояние машины, а не дефект правки.** Установлен только
   chromium, `firefox` и `webkit` падают всегда: гонять `--project=chromium`, узкий экран —
   `--project=mobile-chrome`. Та же ошибка приходит после смены версии Playwright: браузер
   ставится под конкретную версию, и после подъёма нужен повторный
   `npx playwright install chromium`. Девять тестов так и упали, и это выглядело регрессией
   обновления.
-- **Первому прогону сразу после установки браузера верить нельзя.** Два падения `admin-e2e`
-  не повторились ни при отдельном прогоне тех же тестов, ни при втором полном. Такой прогон
-  повторяют, а выводы делают по второму.
-- Сквозные тесты админки без `E2E_ADMIN_EMAIL` и `E2E_ADMIN_PASSWORD` пропускаются молча — в
-  отчёте они значатся `skipped`, и прогон выглядит успешным.
+- **Первому прогону сразу после установки браузера верить нельзя.** Два падения сквозного
+  набора не повторились ни при отдельном прогоне тех же тестов, ни при втором полном. Такой
+  прогон повторяют, а выводы делают по второму.
+- Сквозная спека, которой нужен вход, без учётных данных в окружении пропускается молча — в
+  отчёте она значится `skipped`, и прогон выглядит успешным. Имена переменных — при дереве.
 - **Справочник флоу вторых сценариев не заводит.** В `docs/E2E_<ДОМЕН>_FLOWS.md` кладут то,
   чего в спеке домена нет и быть не должно: `qa-dataid` элементов, состояния разметки, ловушки
   стенда. Обещанное поведение остаётся сценарием в `scenarios.md`: если списать его во второе

package/assets/rules/translations.md

@@ -2,7 +2,7 @@
 name: translations
 kind: rule
 law: locales
-description: Правило под «Закон о локалях и переводах». Брать при заведении любого видимого текста, правке словарей libs/common/i18n, префиксов локалей сайта и перевода контента объекта. Называет восемь локалей, Transloco, производные переводы и начальную валюту локали. Готовый код — в паттерне translations-key.
+description: Правило под «Закон о локалях и переводах». Брать при заведении любого видимого текста, правке словарей libs/common/i18n, префиксов локалей сайта и перевода контента объекта. Называет локали перевода, словари, производные переводы и начальную валюту локали. Готовый код — в паттерне translations-key.
 ---
 
 # Локали и переводы — как это устроено здесь
@@ -15,7 +15,7 @@ description: Правило под «Закон о локалях и перев
 
 | В законе             | Здесь                                                                                               |
 | -------------------- | --------------------------------------------------------------------------------------------------- |
-| локаль сайта         | одна из восьми: `en`, `ru`, `de`, `zh-Hans`, `zh-Hant`, `ko`, `th`, `hi`                            |
+| локаль сайта         | одна из локалей перевода; их набор — в `implementation.md` рядом                                    |
 | локаль по умолчанию  | `en` — отдаётся из корня, без префикса в адресе                                                     |
 | локаль ввода         | `source_locale` в запросе сохранения объекта; берётся из языка админки                              |
 | словарь              | JSON-словари Transloco в `libs/common/i18n/src/lib/dictionaries/<локаль>/`, разложенные по разделам |
@@ -54,6 +54,8 @@ description: Правило под «Закон о локалях и перев
 ## Паттерны
 
 - `translations-key` — заведение ключа во всех локалях перевода и подстановка в разметку.
+- `translations-content` — перевод содержимого записи: производный перевод, запись локали
+  руками, отказ провайдера, сброс кэша отданных страниц.
 
 ## Ловушки
 
@@ -63,7 +65,11 @@ description: Правило под «Закон о локалях и перев
   на общий, сайт, письма и админку.
 - **Перевод контента идёт до транзакции сохранения:** страница объекта не должна оказаться
   наполовину переведённой. Кэш сбрасывается после записи и один раз.
-- **Без ключа `ANTHROPIC_API_KEY` сохранение проходит,** но переводы остаются прежними, и
-  владелец видит предупреждение `propertySaveTranslationFailed`.
+- **Без ключа переводов сохранение проходит,** но переводы остаются прежними, и владелец видит
+  предупреждение об этом на своём экране. Ключ лежит секретом владения в хранилище, а не
+  переменной окружения, и заводит его владелец экраном интеграций: одноимённая переменная в
+  составе прода приложением не читается. Состояния ключа — паттерн `git-workflow-secrets`.
+- **Ветки локалей надеты не на все маршруты сайта, и новый раздел в них не попадает** —
+  раскладка, её ловушка и готовый код лежат в правиле `seo` и паттерне `seo-page`.
 - Новый маршрут сайта без ветки под каждую локаль существует только в локали по умолчанию:
-  `/de/<путь>` отдаст 404 и поисковику, и гостю.
+  путь под префиксом другой локали отдаст 404 и поисковику, и гостю.

package/assets/rules/typescript-conventions.md

@@ -33,6 +33,11 @@ description: Правило под «Закон об устройстве код
   различаются в месте использования, а не переходом к объявлению.
 - **Суффикс имени файла находит в нём обещанное объявление.** Список суффиксов закрыт: слово,
   которого в нём нет, суффиксом не считается, и такой файл правило не судит.
+- **Файл не длиннее 500 строк, и считаются все строки — пустые и комментарии тоже.** Файл,
+  который не влезает на экран целиком, читают по частям, и правку в нём делают, не увидев
+  остального. Для `.ts` это держит правило линтера; файлы обвязки — сценарии и скрипты — до
+  него не доходят и судятся отдельной проверкой дерева. Накопленное к дню включения
+  перечислено поимённо, и строка оттуда снимается вместе с делением своего файла.
 - **Тип берётся из того пакета, где объявлен.** Своя копия чужого типа расходится с оригиналом
   молча, а компилируется из них только одна.
 - **Двухступенчатое приведение `as unknown as` запрещено правилом линтера.** Вместо него —

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rt-tools/agent-kit",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "Переносимый слой правил для агента: законы, хуки, проверки и агенты, раскладываемые в репозиторий одной командой",
   "author": "RT Team",
   "license": "Apache-2.0",