From 473b62ef53a6c2f85690d8e05124955243d77b83 Mon Sep 17 00:00:00 2001 From: Ku6epXBOCTuK Date: Fri, 25 Sep 2026 16:02:29 +0500 Subject: [PATCH] docs: update codebase quality plan --- docs/plan-codebase-quality.md | 98 ++++++++++++++++++++++++----------- 1 file changed, 67 insertions(+), 31 deletions(-) diff --git a/docs/plan-codebase-quality.md b/docs/plan-codebase-quality.md index b66bb42..b540dbe 100644 --- a/docs/plan-codebase-quality.md +++ b/docs/plan-codebase-quality.md @@ -14,20 +14,39 @@ 1. Сначала stabilизировать существующие проверки и тестовые контракты, а не добавлять новые сложные lint-правила. -2. Старый UI (`src/lib/v1/`, `src/routes/v1/`, `app_v1.css`) и новый UI - (`src/lib/components/`, `src/routes/` без `v1/`) остаются изолированными. - Глобальное расширение recommended-правил выполняется только в рамках C19. -3. `core/` и `theme/` — общие модули. Их изменения проверяются unit-тестами и - smoke-сценариями для обеих веток. -4. Изменения делаются небольшими атомарными частями, в соответствии с +2. Старый UI (`src/lib/v1/`, `src/routes/v1/`, `app_v1.css`) больше не является + обязательной поддерживаемой версией: текущий production на корневых маршрутах + уже достаточно стабилен для использования. +3. Пока `/v1` существует, старый и новый UI остаются изолированными. Не тратить + время на исправления, тесты и документацию, которые нужны только v1. +4. Удаление v1 — реальный следующий cleanup-задача (Q3). Не ждать, пока legacy + начнёт мешать, и не тратить время на его поддержку; если задача упирается в + v1, Q3 выполняется перед ней. +5. `core/` и `theme/` — общие модули. Их изменения проверяются unit-тестами и + smoke-сценариями для обеих веток, пока ветка v1 не удалена. +6. Изменения делаются небольшими атомарными частями, в соответствии с `AGENTS.md`. -5. Каждый новый lint-rule сначала появляется в report-only/warn-only режиме, +7. Каждый новый lint-rule сначала появляется в report-only/warn-only режиме, получает fixtures и тесты, и только после очистки baseline становится blocking. -6. Детали реализации правил остаются в `web/eslint-plugins/README.md`; +8. Детали реализации правил остаются в `web/eslint-plugins/README.md`; `AGENTS.md` содержит краткие обязательные политики, понятные агенту без дополнительных поисков, и ссылки на подробные документы. +### Политика legacy v1 + +- v1 можно удалить; это разрешённый cleanup, а не обязательная работа перед + каждой задачей. +- Не добавлять новые v1-фичи, не чинить v1-баги и не расширять v1-тесты без + прямой зависимости текущей задачи от legacy-кода. +- Если задача требует изменений в v1 или общих модулях, сначала выполнить Q3, + если это не противоречит атомарности текущей задачи, и продолжить работу + только с production-веткой. +- Если порядок работ изменится, Q3 можно перенести как целый cleanup, но не + возвращать постоянную поддержку v1. +- После удаления проверить маршруты, импорты, i18n, тесты, документацию и + конфигурацию lint; старые ссылки не оставлять как «источник совместимости». + ## 2. Что уже есть и что мешает - `i18n/dict-consistency` реализован и подключён как `warn-only` @@ -129,9 +148,26 @@ pnpm --dir web test:e2e - Plural-формы остаются отдельной задачей после Q2 и не смешиваются с этим этапом. -### Q3. Тестовый контракт e2e +### Q3. Удалить v1 (следующий cleanup) -**Оценка:** M. **Зависимости:** Q0, решение по i18n и генераторам. +**Статус:** следующий шаг после Q2. **Оценка:** M. **Зависимости:** Q0, Q1, Q2. + +- Удалить `web/src/routes/v1/**`, `web/src/lib/v1/**`, `app_v1.css`, v1-specific + i18n/tests и оставшиеся v1-ссылки. +- Убрать v1 из isolation/lint/test-конфигураций и документации; не оставлять + исключения только ради удалённого кода. +- Обновить shared `core`/`theme` проверки: после удаления v1 проверять только + production-потребителя. +- Прогнать `pnpm verify` и отдельный e2e smoke production-маршрутов. +- Не выполнять удаление как побочный эффект другого PR; это отдельная атомарная + задача. + +**Готово, когда:** production build и verify зелёные, v1-маршруты и файлы +отсутствуют, а ссылки и конфиги не содержат legacy-путей. + +### Q4. Тестовый контракт e2e + +**Оценка:** M. **Зависимости:** Q0–Q3, решение по i18n и генераторам. - Основной locator: `role`, `aria-*`, `getByLabel`, stable `id`/`href`. - `data-testid` использовать только там, где семантического API недостаточно: @@ -158,9 +194,9 @@ pnpm --dir web test:e2e **Готово, когда:** изменение формулировки, класса или порядка элементов не ломает поведенческий тест без изменения пользовательского контракта. -### Q4. Закрыть известные preview-баги +### Q5. Закрыть известные preview-баги -**Оценка:** M. **Зависимости:** Q3. +**Оценка:** M. **Зависимости:** Q4. 1. Выбрать поведение `resize-png` и `crop-png` при загрузке изображения: source-aware defaults, осмысленные статические defaults или отдельный @@ -178,9 +214,9 @@ pnpm --dir web test:e2e **Готово, когда:** каждый known issue либо исправлен и покрыт зелёным тестом, либо явно перенесён в отдельную продуктовую задачу с владельцем и критерием. -### Q5. Расширение unit и browser-покрытия +### Q6. Расширение unit и browser-покрытия -**Оценка:** M–L. **Зависимости:** Q3, Q4. +**Оценка:** M–L. **Зависимости:** Q4, Q5. Сначала: @@ -200,9 +236,9 @@ pnpm --dir web test:e2e Не применять один одинаковый smoke-сценарий к image-, text-, generator- и file-result-инструментам. -### Q6. Укрепление lint-инфраструктуры +### Q7. Укрепление lint-инфраструктуры -**Оценка:** M. **Зависимости:** Q1, Q2. +**Оценка:** M. **Зависимости:** Q1, Q2, Q3. - Очистить или использовать unused design tokens; после очистки решить, должен ли unused audit быть fail-режимом. @@ -214,9 +250,9 @@ file-result-инструментам. hardcoded colors наравне со Svelte styles. - Новые правила подключать только после fixtures, `test:rules` и baseline. -### Q7. Новые автоматические правила +### Q8. Новые автоматические правила -**Оценка:** L. **Зависимости:** Q3, Q6. +**Оценка:** L. **Зависимости:** Q4, Q7. #### Дублирование HTML/Svelte-разметки @@ -225,8 +261,7 @@ file-result-инструментам. - минимальный размер клона; - нормализацию Svelte blocks и динамических классов; -- список допустимых fixture/allowlist-случаев; -- исключение `v1`. +- список допустимых fixture/allowlist-случаев. Только после оценки false positives выбирать между готовым detector и собственным AST-правилом. Не включать detector в blocking gate сразу. @@ -256,7 +291,8 @@ Blanket-запрет всех string literals не использовать. 1. Какой набор команд считается полным quality gate и что означает успешный результат при warnings. -2. Старый/new scope и запрет глобального расширения lint до C19. +2. Старый/new scope и политику v1: v1 можно удалить, но пока он существует, не + расширять на него новые правила и не тратить время на его поддержку. 3. Политику e2e: semantic locators, допустимый `data-testid`, запрет бессмысленных counts/classes/alt/exact prose. 4. Политику i18n: новые пользовательские тексты через i18n; registry source, @@ -320,8 +356,8 @@ history или пересоздают как новый активный док | `docs/README.md` | Индекс активных документов, карта источников истины и краткий порядок чтения для агента | Q0; при добавлении нового активного документа | | `docs/agent-workflow.md` | Подробный workflow: исследование, изменение, проверка, работа с legacy и обновление документации | Q0–Q1; только для процессов, не описанных кратко в `AGENTS.md` | | `docs/quality-gates.md` | Команды проверки, semantics errors/warnings, порядок запуска и требования CI | Q1; при изменении scripts/config/CI | -| `docs/testing-strategy.md` | Слои тестов, locator policy, i18n assertions, fixtures, `test.fixme` и правила e2e | Q3; при изменении тестовой архитектуры | -| `docs/architecture-overview.md` | Карта `core`, registry, executor, нового UI и `/v1`, shared-модули и зависимости | Q4 или перед крупным рефакторингом; не дублировать существующие планы | +| `docs/testing-strategy.md` | Слои тестов, locator policy, i18n assertions, fixtures, `test.fixme` и правила e2e | Q4; при изменении тестовой архитектуры | +| `docs/architecture-overview.md` | Карта `core`, registry, executor, нового UI и `/v1`, shared-модули и зависимости | Q5 или перед крупным рефакторингом; не дублировать существующие планы | | `web/eslint-plugins/README.md` | Детали custom lint rules, token policy и fixtures | Уже существует; менять только вместе с правилами | | `docs/archive/README.md` | Политика временного архива, даты и удаления через 30 дней | Q0; обновлять при изменении архивной политики | @@ -334,19 +370,19 @@ checklist. `README.md` в корне остаётся кратким обзор 1. **Q0** — синхронизация backlog/checklist/AGENTS. 2. **Q1** — `verify` и PR quality gate. -3. **Q3** — тестовый контракт и stale-тесты. -4. **Q4** — preview-баги и снятие `fixme`. -5. **Q2** — i18n parity и strict warning gate. -6. **Q6** — тесты lint-инфраструктуры и unused tokens. -7. **Q5** — расширенное покрытие. -8. **Q7** — report-only duplicate/text audits; blocking — только после baseline. +3. **Q2** — i18n parity и strict warning gate. +4. **Q3** — удалить v1 отдельной атомарной задачей. +5. **Q4** — тестовый контракт и stale-тесты для production UI. +6. **Q5** — preview-баги и снятие `fixme`. +7. **Q6** — расширенное покрытие. +8. **Q7** — тесты lint-инфраструктуры и unused tokens. +9. **Q8** — report-only duplicate/text audits; blocking — только после baseline. Каждый PR должен быть атомарным и небольшим; не объединять `SchemaPreview` refactor, новые i18n-правила и исправление продуктовых багов в одну работу. -## 6. Отложить за пределы этого плана +## 6. Отдельные направления и что не начинать автоматически -- удаление `/v1` и глобальное расширение recommended (C19); - полноценный browser/visual/coverage matrix; - полноценная PWA/API/WASM-платформа; - `SchemaPreview` state/view-model refactor;