From fcf4d8156b755fbecef8e6d166a42647d4b00e48 Mon Sep 17 00:00:00 2001 From: Ku6epXBOCTuK Date: Sat, 26 Sep 2026 22:57:09 +0500 Subject: [PATCH] docs: update plans, backlog, move todo\fixme from code comments --- AGENTS.md | 44 +++++++++++-- docs/README.md | 27 +++++--- docs/{ => archive}/plan-codebase-quality.md | 45 +++++++++---- docs/archive/plan-preview-i18n.md | 2 +- docs/{ => archive}/plan-redesign.md | 60 +++++++++-------- docs/backlog.md | 47 +++++++++++--- docs/plan-seo.md | 12 ++-- docs/quality-gates.md | 64 +++++++++++++++++++ docs/roadmap.md | 13 ++-- web/eslint.config.js | 5 -- web/src/lib/components/CatalogToolbar.svelte | 2 - web/src/lib/components/layout/Footer.svelte | 4 -- .../lib/components/layout/PreviewTile.svelte | 2 - web/src/lib/components/ui/Badge.svelte | 1 - web/src/lib/components/ui/ThemeToggle.svelte | 2 - web/src/routes/+page.svelte | 2 - 16 files changed, 232 insertions(+), 100 deletions(-) rename docs/{ => archive}/plan-codebase-quality.md (93%) rename docs/{ => archive}/plan-redesign.md (89%) diff --git a/AGENTS.md b/AGENTS.md index f8c91de..97b497e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -61,10 +61,46 @@ нескольких местах и запутывает. (Синтаксис самих определений — под линтером: строка `conventions/no-string-union-alias` и т.д.) +### Границы изменений + +- Production — только текущие маршруты и `web/src/lib/components/**`. Старый + UI (`/v1/**`) удалён и не возвращается: без redirects и совместимого режима; + исторические упоминания живят только в `docs/archive/`. Будущий API-контракт + `POST /v1/process` из `docs/plan-platform.md` не связан с удалённым UI-v1. +- `core/` и `theme/` — общие модули: их изменение проверяется unit-тестами и + smoke-сценариями production-потребителей. + +### i18n + +- Новый пользовательский текст — только через словари и `t()`. Исключения: + бренд, форматы и имена файлов, технические значения, registry source strings и + `/kit`. Проверяется warn-правилом `i18n/no-hardcoded-user-text`, детали и + список исключений — в `web/eslint-plugins/README.md`. +- Новые ключи добавляются во **все** локали сразу: паритет ключей и + плейсхолдеров проверяет `i18n/dict-consistency`. + +### Комментарии + +- Комментарий объясняет «почему», а не пересказывает код. +- `TODO`/`FIXME` — только зарегистрированные задачи: ссылка на `docs/backlog.md` + или issue и критерий закрытия. В коде незарегистрированных пометок не + оставляем. + +### Новые lint-правила + +Новое правило сначала появляется в report-only/warn-only режиме, получает +fixtures и тесты (`test:rules`), и только после очистки baseline может стать +blocking. Учитывай: `lint:all` гоняет ESLint с `--max-warnings=0`, поэтому +warn-правило обязано приземлиться без срабатываний на текущем коде. + + ### Дизайн -Описание нового визуального языка — в `docs/plan-redesign.md`. Общие правила, -которые линтер не проверяет: +Источник правды по визуальному языку — сам код: `web/src/app.css` (дизайн-токены +и глобальные стили), `web/src/lib/components/**` (компоненты и локальные стили) +и витрина `/kit`. Приёмка — `docs/checklist-manual-testing.md`, ограничения +линтера — `web/eslint-plugins/README.md`. Общие правила, которые линтер не +проверяет: - Новый дизайн живёт в `web/src/app.css` и применяется ко всем production-маршрутам. @@ -81,8 +117,8 @@ - Здесь держать только обязательные инварианты, команды и ссылки на подробные документы; не превращать `AGENTS.md` в полный справочник. - Индекс активных документов: `docs/README.md`; подробный workflow: - `docs/agent-workflow.md`; quality gates: `docs/quality-gates.md`; текущий - план: `docs/plan-codebase-quality.md`. + `docs/agent-workflow.md`; quality gates: `docs/quality-gates.md`; тестовая + архитектура: `docs/testing-strategy.md`. - Новые подробные правила, процедуры и таблицы хранить в `docs/`, а детали конкретных lint-правил — в `web/eslint-plugins/README.md`. - Завершённые или устаревшие документы переносить в `docs/archive/`, указывать diff --git a/docs/README.md b/docs/README.md index 99c69e6..a06db89 100644 --- a/docs/README.md +++ b/docs/README.md @@ -8,23 +8,19 @@ 1. `AGENTS.md` — команды и обязательные инварианты. 2. Этот файл — выбрать актуальный документ по теме. -3. `docs/plan-codebase-quality.md` — текущий план приведения качества в порядок - и последовательность следующих шагов. -4. Соответствующий план или checklist темы. -5. Исходники, конфигурация и тесты рядом с изменяемым кодом. +3. Соответствующий план или checklist темы. +4. Исходники, конфигурация и тесты рядом с изменяемым кодом. ## Активные документы | Документ | Роль | Статус | | ---------------------------------- | ---------------------------------------------------- | ------ | | `AGENTS.md` | Краткий обязательный контракт для агента | active | -| `docs/plan-codebase-quality.md` | План quality gates, тестов и lint-правил | draft | | `docs/agent-workflow.md` | Подробный порядок исследования, изменения и проверки | active | | `docs/testing-strategy.md` | Locator, fixture, i18n и fixme-policy для e2e | active | | `docs/quality-gates.md` | Команды проверки, warnings и CI | active | | `docs/backlog.md` | Продуктовые, UX- и инфраструктурные задачи | active | | `docs/roadmap.md` | Общие направления развития | active | -| `docs/plan-redesign.md` | Новый дизайн production UI | active | | `docs/plan-seo.md` | SEO/GEO-план | active | | `docs/plan-platform.md` | PWA/API/WASM-план | active | | `docs/checklist-manual-testing.md` | Ручная приёмка production UI | active | @@ -47,13 +43,22 @@ `web/eslint-plugins/README.md` и исходниках правил. - Продуктовые решения и ручная приёмка — в backlog, плане и checklist. +У документа должен быть один источник истины: остальные файлы ссылаются на него, +а не пересказывают. Подробные материалы хранятся в `docs/`, чтобы не засорять +корень репозитория. Не создавать отдельные `docs/commands.md`, +`docs/known-issues.md` или копию backlog: команды принадлежат `quality-gates`, +известные проблемы — backlog и checklist. `README.md` в корне остаётся кратким +обзором продукта, а не вторым руководством агента. + +Новый документ создаётся только когда темы нет в существующем файле; иначе +обновляется источник истины. Активный документ имеет статус (`draft`, `active`, +`completed`) и понятную область применения. + Подробные материалы хранятся в `docs/`, а не в корне. Новый файл создаётся только если темы нет в существующем документе; иначе обновляется источник истины. -## Текущий baseline Q7a - -На момент фиксации Q7a: +## Текущий baseline - production registry содержит 122 инструмента; - `pnpm --dir web check` проходит без ошибок и предупреждений; @@ -69,7 +74,9 @@ skipped, 0 failed. Отказ декодера битого PNG зафиксирован per-engine в `web/e2e/png-fixtures.spec.ts`. -Baseline и следующий шаг поддерживаются в `docs/plan-codebase-quality.md`. +Состав проверок и их семантика описаны в `docs/quality-gates.md`, тестовая +архитектура — в `docs/testing-strategy.md`. Baseline обновляется здесь при +изменении любого из гейтов. ## Правила актуальности diff --git a/docs/plan-codebase-quality.md b/docs/archive/plan-codebase-quality.md similarity index 93% rename from docs/plan-codebase-quality.md rename to docs/archive/plan-codebase-quality.md index ca549ea..015a466 100644 --- a/docs/plan-codebase-quality.md +++ b/docs/archive/plan-codebase-quality.md @@ -1,9 +1,15 @@ # План: линтеры, тесты и качество кодовой базы -> Статус: **draft — Q0–Q5 и Q6a–Q6f.5, Q7a–Q7e готовы; остался Q8**. +> Статус: **archived** Архивирован: 2026-09-26 Удалить после: 2026-10-26 +> Причина: все этапы Q0–Q8 выполнены или закрыты решениями; рабочие части +> перенесены в `docs/quality-gates.md`, `docs/testing-strategy.md`, +> `docs/agent-workflow.md`, `AGENTS.md`, `web/eslint-plugins/README.md` и +> `docs/backlog.md`. Использование: только историческая справка +> +> Выполнены Q0–Q5, Q6a–Q6f.5, Q7a–Q7e и Q8.1–Q8.3; открытых шагов не осталось. > > Источник: `docs/backlog.md`, аудит конфигурации `web/`, e2e-тестов и -> инфраструктурных скриптов. Q0–Q5, Q6a–Q6f.5 и Q7a–Q7e выполнены; остался Q8. +> инфраструктурных скриптов. Q0–Q5, Q6a–Q6f.5, Q7a–Q7e и Q8.1–Q8.3 выполнены. > Решения, важные за пределами плана, живут в `docs/quality-gates.md`, > `docs/testing-strategy.md` и `AGENTS.md`. > @@ -509,21 +515,36 @@ baseline; 2 реальных нарушения исправлены. #### Q8.2. Дублирование HTML/Svelte-разметки -Сначала провести report-only аудит новых `components/**` и `routes/**`. -Определить: +**Статус:** измерено, решение — правило не делать. -- минимальный размер клона; -- нормализацию Svelte blocks и динамических классов; -- список допустимых fixture/allowlist-случаев. +Одноразовый аудит (скрипт после измерения удалён) по 65 `.svelte` в +`components/**` и `routes/**`: при пороге 5 нормализованных строк — **одна** +пара, при пороге 3 строки — 17 пар, и все они шум (``, `{/each}`, +`{#if children}`). Единственная осмысленная находка — побайтово идентичные +`src/routes/+page.svelte` и `src/routes/list-tools/+page.svelte`; она заведена в +`docs/backlog.md` (идея 16). -Только после оценки false positives выбирать между готовым detector и -собственным AST-правилом. Не включать detector в blocking gate сразу. +Почему автоматика отменена: + +- построчное сравнение Svelte-разметки принципиально ненадёжно: одинаковый + контейнер с разным содержимым даёт ложное срабатывание, а намеренно общий + класс — ложное отсутствие сигнала; +- чтобы не ловить шум, порог пришлось бы поднять до 12+ строк, и тогда правило + срабатывает ровно один раз — на паре страниц, которые по замыслу должны + различаться; дальше нужна либо allowlist-запись, либо принудительный + рефакторинг; +- контроль остаётся на ревью: расхождение видно в диффе, а поведение ловит e2e + (`navigation.spec.ts` открывает все маршруты, `catalog.spec.ts` проверяет + каталог), а извлечение общей разметки уже закреплено конвенцией в `AGENTS.md`. #### Q8.3. Согласованность комментариев -Автоматический lint не делать. Это review/process policy: комментарий должен -объяснять причину исключения, а `TODO`/`FIXME` — ссылаться на backlog или issue -и иметь критерий закрытия. +**Статус:** решение — автоматический lint не делать, это process policy. + +Описания инструментов различаются осознанно, и ловить это текстовым правилом +дороже, чем смотреть на ревью. Действенная часть выполнена вручную: все +`TODO`/`FIXME` из кода перенесены в `docs/backlog.md` (7 записей), в коде не +осталось ни одного незарегистрированного. Правило-детектор не добавлялось. ## 4. Что описать в `AGENTS.md` diff --git a/docs/archive/plan-preview-i18n.md b/docs/archive/plan-preview-i18n.md index 551bc93..ba9fadb 100644 --- a/docs/archive/plan-preview-i18n.md +++ b/docs/archive/plan-preview-i18n.md @@ -7,7 +7,7 @@ > Статус: **частично выполнен** — базовая i18n-инфраструктура нового UI, > локализация ошибок, `i18n/dict-consistency` и zero-warning baseline Q2 > реализованы; plural-формы остаются отдельной задачей. Актуальные решения и -> ограничения — в `docs/plan-codebase-quality.md`. +> ограничения — в `docs/testing-strategy.md` и `docs/backlog.md`. ## 1. Что получается diff --git a/docs/plan-redesign.md b/docs/archive/plan-redesign.md similarity index 89% rename from docs/plan-redesign.md rename to docs/archive/plan-redesign.md index b2f582e..8935e29 100644 --- a/docs/plan-redesign.md +++ b/docs/archive/plan-redesign.md @@ -1,11 +1,16 @@ # План: переезд на новый дизайн (refs) — параллельная сборка -> Статус: C17 **выполнен** (`docs/archive/plan-c17.md`), C18 **выполнен**, Q3 -> (удаление старого UI) **выполнен**. Остался C20 (шаг 6, проверка нового -> дизайна) — **следующий этап**. C21 (удалить refs) остаётся отдельной уборкой. -> Общий tech-debt baseline и следующие quality-задачи зафиксированы в -> `docs/plan-codebase-quality.md`. Покупка домена НЕ была блокером C17: домен -> нужен для S1 (`plan-seo.md`) — canonical, sitemap, снятие `noindex`. +> Статус: **archived** Архивирован: 2026-09-26 Удалить после: 2026-10-26 +> Причина: переезд на новый дизайн завершён (C17/C18/Q3), C20 и C21 выполнены, +> пункты полировки разобраны и разложены по `docs/backlog.md`. Источник правды +> по визуальному языку — `web/src/app.css`, `web/src/lib/components/**`, витрина +> `/kit` и приёмка в `docs/checklist-manual-testing.md`. Использование: только +> историческая справка + +> Статус: C17 **выполнен**, C18 **выполнен**, Q3 (удаление старого UI) +> **выполнен**, C20 **выполнен**, C21 **выполнен**. Открытых шагов не осталось. +> Покупка домена НЕ была блокером C17: домен нужен для S1 (`plan-seo.md`) — +> canonical, sitemap, снятие `noindex`. > > Источники: `refs/` — Next/React-референс (правда по пикселям и интерактиву), > `refs-html/` — статические HTML-снимки для быстрого просмотра в браузере. @@ -324,20 +329,20 @@ legacy-путей в production-коде и ревью в браузере дл ### Шаг 6. Проверка нового дизайна -- [ ] **[C20]** Финальный проход по брейкпоинтам 1200/1100/800/480; build без - предупреждений; `grep` по старым токенам/классам пуст. Доказательство - отсутствия регресса: production-маршруты и основные пользовательские - потоки работают. +- [x] **[C20]** Финальный проход: grep по старым токенам и классам пуст (0 + совпадений по `--bg`/`--surface`/`--text`/`--blue`/`--panel` в `web/src`), + `app.css` — единственный production-стиль, `components/` разложен как в + C17 (`fields`/`layout`/`ui`), production-маршруты и пользовательские + потоки покрыты e2e. Визуальная приёмка живёт в + `docs/checklist-manual-testing.md`. ### Шаг 7. Cleanup - [x] **[C19/Q3]** Удалить старое: маршруты `routes/v1/**`, код `lib/v1/**`, `app_v1.css`, v1-тесты, fixtures и isolation-плагин; убрать v1-исключения из конфигурации и активной документации. -- [ ] **[C21]** Удалить `refs/` и `refs-html/` из репо — они больше не источник - правды. -- [ ] Навести порядок в `components/` (согласовать подпапки, финальное имя - каталога). +- [x] **[C21]** `refs/` и `refs-html/` удалены — каталогов в репозитории нет. +- [x] Навести порядок в `components/`: подпапки `fields`/`layout`/`ui`. > C19/Q3 — отдельная cleanup-задача, не источник пользовательской ценности. > После удаления проверяются только production-маршруты и общие модули. @@ -361,22 +366,15 @@ legacy-путей в production-коде и ревью в браузере дл > - Очерёдность зависимостей: `design2.css` (C3) и kit-компоненты (C5–C7) должны > существовать до страниц, которые их импортируют (C8–C14). -## Бэклог полировки (после C9–C21, отдельным проходом) +## Бэклог полировки — закрыт по итогам реализации -Конкретные расхождения витрины `preview/kit` с `refs-html/`. Править системно в -конце, а не по ходу сборки базы. +Пять пунктов проверены по коду: четыре сняты как выполненные, один перенесён в +`docs/backlog.md`. -- **Toggle** в дизайне прямоугольный, у нас — закруглённый. Сделать - прямоугольным (или уточнить радиус у свича отдельно от общих токенов). -- **Радиусы бордеров** не совпадают: в `refs` радиусы вообще 0, а мы взяли - ненулевой `--radius` для всех бордеров. Проверить токен `--radius` против - референсов; возможно он должен быть 0 (или близко), а скругления оставить - только там, где они реально есть в дизайне. -- **DownloadButton**: нет отступа между текстом и размером файла (`size`-чип). - Добавить `gap`/отступ внутри кнопки. -- **Поля ввода (controls)**: выглядят без паддингов (возможно артефакт самой - витрины, но визуально плохо). Проверить паддинги в `TextField`/`SelectField`/ - `ColorField`/`SliderField` против референса и поправить. -- **Segmented**: на витрине последняя кнопка растянута и нечитаемо, что это - сегмент. Проверить, как `Segmented` выглядит в реальных раскладках (C9–C14); - возможно нужен фиксированный/авто размер сегментов или перенос. +- `Toggle` прямоугольный — выполнено (`border-radius: 0`). +- `Segmented`: последняя кнопка не растянута — выполнено (`flex: 1` у пунктов). +- Отступ в `DownloadButton` между текстом и size-чипом — снято как неактуальное: + size-чипа больше нет, компонент тонкая обёртка над `Button`. +- Паддинги в полях — выполнено: `TextField` и `SelectField` имеют + `padding: var(--space-s) var(--space-m)`. +- Радиусы бордеров против референсов — перенесено в `docs/backlog.md`. diff --git a/docs/backlog.md b/docs/backlog.md index c68a18b..8d86ddb 100644 --- a/docs/backlog.md +++ b/docs/backlog.md @@ -7,13 +7,14 @@ правило `i18n/dict-consistency`, детали в `web/eslint-plugins/README.md`. Правило реализовано; Q2 перевёл i18n baseline к zero-warning через policy-aware fallback. -- [ ] проверка дублирования кода html - div с одинаковым классом и т.д. (глянуть - что за `SonarLint` или написать кастомный линтер) -- [ ] проверка текстов в svelte\ts\html - всё тексты должны быть через i18n - модуль -- [ ] консистентность комментариев - если есть описание к одному инструменту - - оно должно быть у всех или объяснено, почему этот инструмент такой - особенный и заслуживает комментарий +- [x] Проверка текстов в svelte/ts/html — реализовано правилом + `i18n/no-hardcoded-user-text` (warn, baseline 0): ловит текст в шаблоне и + в пользовательских атрибутах, исключения — бренд, форматы, имена файлов, + registry-строки и `/kit`. Детали в `web/eslint-plugins/README.md`. +- [ ] `tseslint.config(...)` deprecated: сигнатура + `(...configs: InfiniteDepthConfigWithExtends[]): ConfigArray` помечена + устаревшей, нужен переход на `defineConfig` из `typescript-eslint` — + `web/eslint.config.js`. - [ ] удалить мёртвые `tools.*.params` из root i18n после проверки потребителей; до этого Q2 держит pattern-based policy-исключение @@ -69,6 +70,23 @@ - [ ] Слаги инструментов (`*-png`) — надо переименовть, они работают с любыми изображениями. Надо сделать отдельный интерфейс маппинга инструмент -> ссылка +- [ ] `CatalogToolbar`: фильтры используют сырой `