docs: update plans, backlog, move todo\fixme from code comments

This commit is contained in:
2026-09-26 22:57:09 +05:00
parent b59a434c65
commit fcf4d8156b
16 changed files with 232 additions and 100 deletions
+64
View File
@@ -90,6 +90,70 @@ per-project лимит воркеров, а browser matrix упирается в
pattern-based policy для временно неиспользуемых `tools.*.params`; это не
молчаливый `allowPaths`-список.
## Решения, принятые без автоматизации
Здесь лежат решения «что сознательно НЕ вводим», чтобы не пересматривать их
заново через полгода. Для каждого — причина и то, что пересмотрело бы решение. В
`docs/backlog.md` такие пункты не дублируются: backlog живёт задачами, а не
историей решений.
### Детектор дублирования разметки — не вводим
Ни свой AST-правило, ни готовая зависимость (jscpd, `eslint-plugin-sonarjs`).
- Измерение по 65 `.svelte` в `components/**` и `routes/**`: при пороге 5
нормализованных строк — одна осмысленная пара, при пороге 3 строки — 17 пар и
все они шум (`</label>`, `{/each}`, `{#if children}`). Семейство
schema-контролов делит максимум 4 строки — это законное сходство by design.
- Причина: построчное сравнение Svelte-разметки принципиально ненадёжно —
одинаковый контейнер с разным содержимым даёт ложное срабатывание, а намеренно
общий класс — ложную тишину. Чтобы не ловить шум, порог пришлось бы поднять до
12+ строк, и тогда правило срабатывает ровно один раз.
- Контроль остаётся на ревью (расхождение видно в диффе) и на поведенческих
e2e-проверках; извлечение общей разметки закреплено конвенцией в `AGENTS.md`.
- Пересмотреть, если появится реально «уехавшая» копипаста в компонентах или
библиотека разрастётся на уровень композиций страниц.
### Линтер согласованности комментариев — не вводим
Описания инструментов различаются осознанно, и ловить это текстовым правилом
дороже, чем смотреть на ревью. Действенная часть выполнена вручную: все
`TODO`/`FIXME` перенесены в backlog, незарегистрированных пометок в коде нет;
новые запрещены правилом в `AGENTS.md`.
### Visual snapshots — не вводим
`toHaveScreenshot` сравнивает страницу с PNG-baseline из прошлого коммита. При
активно меняющемся визуальном языке это превращает каждый дизайн-PR в
перегенерацию и ревью картинок, а baseline платформенные (снимок с Windows не
совпадёт на `ubuntu-latest`). Потребность закрывают e2e-поведение, `lint:tokens`
с token audit, i18n-гейт и ручной чеклист. Вернуться стоит, когда визуальный
язык стабилизируется; тогда первым идёт `/kit` в двух темах, а baseline
рождаются на Linux.
### Fail-режим для unused-token аудита — не вводим
Остаётся предупреждением: `verify` входит в deploy-workflow, поэтому стилевой
долг блокировал бы деплой сайта. Кроме того, аудит видит только ссылки
`var(--x)`, и чтение токена из JS дало бы ложное срабатывание. Правило «новый
токен — вместе с потребителем» живёт в `AGENTS.md`.
### Per-project `expect.timeout` — не задаём
Firefox и WebKit отдают результат так же быстро, как Chromium: расхождения
объясняются памятью, а не скоростью движка. Таймаут под конкретную машину —
магическое число, которое придётся подстраивать на каждом раннере, поэтому
`lint`/Playwright-конфиг остаётся с дефолтами, а проблема решается лимитом
воркеров.
### Coverage: браузерные модули вне scope
`src/lib/core/domText.ts` и `src/lib/core/io.ts` (canvas, `createImageBitmap`)
исключены из coverage-гейта: в node-Vitest они не исполнимы, и их включение
превращало бы метрику в шум. `registry/*` из scope НЕ исключены — низкое
покрытие там означает непокрытую логику, а не ограничение окружения. Список
исключений с причинами — в `docs/testing-strategy.md`.
## CI
`.github/workflows/quality.yml`: