easy-png-tools2/docs/plan-tech-debt.md

План: закрытие техдолга перед переездом old/ (C17)

Статус: план к выполнению. Ветка feat/redesign. Входит в гейт перед переездом старых файлов в old/ (backlog №14; см. также archive/plan-migrate-remaining.md — техдолг «чинить по заведённым задачам, не игнорировать правилами»). Целевое состояние по завершении: svelte-check → 0 errors, pnpm test → зелёный, lint:all → без ошибок (допустим только задокументированный остаток), дизайн-токены → единый словарь preview.css.

Состав техдолга (на 2026-09-07)

• svelte-check error — ToolCard.svelte:19:36: resolve(normalizedHref) принимает только типизированный роут, а normalizedHref: string. Красный svelte-check, висит на каждом прогоне.
• фейл теста — src/lib/palette.test.ts: ENOENT src/app.css (файл разъехался на old.css + design2.css при редизайне). Тест проверял контрасты палитры по токенам старого app.css (text/surface/bg/link/ accent/danger/border). При гейтах pnpm test красный, хотя 607 тестов проходят.
• design-tokens в kit/** — ~335 ошибок lint:all от локального плагина eslint-plugins/design-tokens (захардкоженные цвета/размеры/длительности/ z-index/color-mix() в <style>-блоках svelte), плюс stylelint по CSS.
• a11y-предупреждение — ColorField.svelte.
• пустой ruleset — Toggle.svelte.

Этапы

Этап 1 — «зелёные» гейты (мелкие, по ~10–40 строк каждый)

1. ToolCard — убрать ошибку типов: либо валидировать href против набора известных маршрутов, либо явно протащить типизированный роут из каталога. Проверка: svelte-check 0 errors.
2. palette.test.ts — переписать чтение на новый словарь: тест контрастов гоняется по токенам preview.css (:root + [data-theme="dark"], цвета --color-*/--brand-*). Отдельно: взять из нового дизайна, какие пары реально проверить (текст/фон, muted, акцент/бренд, бордер). Если часть проверок потеряла смысл в новом дизайне — сократить, не растягивать.
3. a11y ColorField + пустой ruleset Toggle — пофиксить прямо в этих компонентах.

Гейт этапа: svelte-check 0 errors, pnpm test зелёный.

Этап 2 — миграция kit/** на design-токены (main объём)

Цель — lint:all без ошибок design-tokens (все примитивы/color-mix() уходят в токены preview.css).

Вариант А (основной): авто-фикс одноразовым скриптом. Писать скрипт ТОЛЬКО если он гарантированно ничего не испортит. Гарантии:

• Скрипт — одноразовый (web/scripts/fix-design-tokens.mjs), после прогона удаляется либо помечается неактуальным.
• Строгая карта замен: примитив → токен 1:1, только если значение точно совпадает с уже существующим токеном словаря preview.css (цвет → --color-*/--brand-*, радиус → --radius-*, размер → --space-*/--size-*, длительность → --duration-*, z-index → --z-*). Никаких новых токенов скрипт не генерирует.
• Замены — только примитивы, не содержащие var()/calc()/color-mix(); исключения по правилам плагина (0, 0px, 1px, проценты, unitless) не трогаются. color-mix() → выносится в preview.css как производный --color-* токен (может требовать ручного решения имени).
• Скрипт обрабатывает только src/lib/components/kit/** и src/preview.css (scoped-пути плагина) и только <style>-блоки/.css — логику/разметку не меняет, только строки стилей.
• После прогона: обязательный дифф-ревью (все изменения — замена значений на var(--x), ничего удалено/переставлено), затем полный lint:all + svelte-check + pnpm test. Если хоть что-то вне «замена примитива на токен» — скрипт считается проваленным, откатываем и переходим на вариант Б.

Вариант Б (страховка): руками, пакетами по компонентам. Если скрипт не удался — чистим/заводим токены вручную, пакетами по компонентам (1–2 на задачу, диф < ~500 строк). Отсутствующие токены (например --space-2xl/--space-panel, уже дважды обходились в SchemaTextSource) добавляем в словарь preview.css осознанно.

Гейт этапа: pnpm --dir web lint:all — только допустимый остаток (неиспользуемые токены — варнинг), плюс регресс-прогон тестов и svelte-check.

Этап 3 — чистота словаря preview.css

• Разобрать варнинги неиспользуемых токенов (check-tokens): либо использовать, либо удалить из словаря.
• После этапа 2 — повторный аудит токенов (pnpm --dir web exec node scripts/check-tokens.mjs): parity light/dark, hct-only, без мёртвых токенов.

Этап 4 — финальные гейты (гейт переезда old/)

1. pnpm --dir web exec svelte-check --tsconfig ./tsconfig.json → 0 errors
2. pnpm --dir web test → зелёный
3. pnpm --dir web exec prettier --check . → чистый
4. pnpm --dir web lint:all → 0 (или только задокументированный остаток)
5. Обе ветки открываются: старый UI /, новый /preview

После зеленых гейтов — закрытие задач и переход к backlog №14 (переезд старых файлов в old/).

Порядок и коммиты

• Коммиты атомарные, < ~500 строк (AGENTS). По завершении каждой мини-задачи — ревью (агент не коммитит).
• Техдолг чинится по заведённым задачам, правила линтеров не отключаются и не игнорируются.