easy-png-tools2/web/eslint-plugins

ESLint-плагины и дизайн-токены: детали

Эта часть репозитория подробно описана здесь, а не в корневом AGENTS.md: рутина-разработка её не требует, детали нужны только при правке самих линт-правил или конфигов.

Структура

• web/eslint-plugins/ — локальные ESLint-плагины.
  • design-tokens/ — правила для <style>-блоков svelte-компонентов.
  • isolation/ — правило изоляции old/new UI.
  • conventions/ — конвенции кода (интерфейс пропсов, запрет union-алиасов).
  • i18n/ — кросс-языковой линтер словарей (dict-consistency).
  • __tests__/ — юнит-тесты (Vitest + RuleTester/Linter).
  • __fixtures__/ — фикстуры для тестов: миниатюрный src/app.css (словарь токенов), файлы для изоляционных тестов и мини-словари lib/i18n/.
• web/scripts/:
  • lint-all.mjs — оркестратор lint:all.
  • check-tokens.mjs + token-audit/ — токен-аудит по app.css.
  • postcss-hct.mjs — постcss-плагин эммита hct() в sRGB-hex.
• web/stylelint.config.js, web/postcss.config.js — конфиги stylelint/css.

Конфигурация ESLint (web/eslint.config.js)

Устроена инкрементально:

• На весь код — парсинг TS/Svelte + правило @typescript-eslint/consistent-type-imports (запрет инлайн-тип-импортов, prefer: 'type-imports').
• Полные recommended-наборы (eslint + typescript-eslint + eslint-plugin-svelte) навешаны только на новый код (src/lib/components/**, src/routes/**), чтобы старый код не засыпался предсуществующими ошибками. Старый код (C17) — src/lib/v1/**, src/routes/v1/**. Когда старый дизайн удалён (C19), scoped-блок убирается и recommended включается на весь код.
• Scoped-пути двигаются вместе с папками (см. plan-redesign.md §10): не оставлять устаревшие пути в eslint.config.js (C17 уже двигал routes/preview/** → routes/** и components/kit/** → components/**; на C19 при наведении порядка в components/ paths останутся components/** + routes/**).
• Для *.svelte выключен prefer-const (пропсы в Svelte 5 пишутся через let).
• allowDefaultProject перечисляет test-файлы и фикстуры точечно (glob'ы с ** там запрещены tseslint) — при добавлении файлов в __tests__/ / __fixtures__/ дописать их туда же.
• design-tokens правила применяются к тем же scoped-путям (src/lib/components/**, src/routes/**).
• isolation-правило включено на весь **/*.{ts,svelte}.

Правила плагина design-tokens

• design-tokens/no-hardcoded-in-svelte — запрет прямых цветов/размеров/ длительностей/z-index и color-mix() (результат токенизировать в CSS). Исключения размеров: 0, 0px, 1px, проценты и unitless (line-height).
• design-tokens/no-category-mismatch — size-свойство не может использовать color-токен (--color-*/--brand-*) и наоборот.
• design-tokens/no-token-definition-in-svelte — определение --x: в компоненте не может содержать примитив (hex/rgb/oklch/px/rem); допустимы производные от токенов (var(), calc(), unitless-числа).
• design-tokens/no-undefined-in-svelte — var(--x) в <style> должен быть определён в src/app.css (словарь токенов) или локально в компоненте. Файл читается один раз и кэшируется (не glob-зависим).

(ESLint лезет в <style>-блоки через постпрефес postcss AST от svelte-eslint-parser; stylelint прогоняется по всем CSS-файлам.)

Правило плагина i18n (i18n/dict-consistency)

Кросс-языковой линтер словарей lib/i18n/ (план: docs/plan-preview-i18n.md §Фаза 8). Сравнивает каждый словарь со всеми остальными локалями (не только с BASE). Список локалей берётся из LOCALES в lib/i18n/dict.ts — новый словарь подхватывается без правки правила.

• warn-only, никогда error — пропущенный перевод не валит сборку.
• Диагностика живёт там, где фикс: каждый файл репортит только свои расхождения:
  • паритет ключей: правило собирает union всех ключей из словарей-соседей (с диска) и для текущего файла репортит те, которых в нём нет — ровно одно предупреждение на разрыв, независимо от числа локалей, где ключ есть; пропавшая целая секция репортится один раз (не по каждому потомку);
  • пустые значения: "" и строка из одних пробелов;
  • паритет плейсхолдеров: у одинакового ключа набор {name} сравнивается с каноническим (мажоритарный по локалям, при равенстве — первый по LOCALES) — ловит потерянную при переводе переменную ровно один раз, даже когда отклоняется одна-единственная локаль.
• Словари-соседи читаются с диска и кэшируются на процесс линта (как no-undefined-in-svelte); каждый парсится @typescript-eslint/parser (синтакс, без типов).
• Опция allowPaths: string[] — dot-path ключи, исключаемые из всех проверок (осознанные отклонения до достижения zero-warn).
• Тесты: __tests__/dict-consistency.test.ts, фикстуры-словари в __fixtures__/src/lib/i18n/ (en, ru, de — консистентные, zero-warn) — в тестах подаются модифицированные варианты en.ts/ru.ts против эталонных на диске.

Токены-префиксы (целевой словарь дизайна)

• Цвета: --color-*, бренд --brand-main / --brand-alt — единственные две переменные, которым разрешено быть hex/rgb, остальные цвета — только hct() и только в app.css.
• Размеры: --space-*, --text-* (font-size), --radius-*, --size-*.
• Брейкпоинты: @custom-media --bp-mobile (max-width: 640px) / --bp-tablet (800px) / --bp-desktop (1100px) — объявляются в app.css, используются как @media (--bp-*). CSS-переменные в @media не работают, поэтому отдельных --bp-* токенов нет; раскрытие делает postcss-плагин postcss-custom-media (конфиг web/postcss.config.js, определения подтягиваются через @csstools/postcss-global-data).
• z-index: --z-*; длительности/анимации: --duration-*, --ease-*.

Нюансы stylelint:

• Правило custom-property-pattern тестирует паттерн без -- (--x → x), а declaration-property-value-disallowed-list — целиком с --.
• custom-property-empty-line-before перенастроен (after-custom-property в ignore, не в except): пустые строки между подряд идущими токенами свободны и --fix их не удаляет — можно группировать цветовые и размерные токены в app.css отдельными блоками.

Токен-аудит (check-tokens.mjs)

Лёгкий оркестратор поверх web/scripts/token-audit/*. Проверяет:

• Parity: каждый цветовой токен из :root обязан иметь пару в [data-theme="dark"] и наоборот. Производные токены (значение содержит var(), напр. hct(from var(--...))) из пары исключены — они наследуют тему автоматически.
• hct-only для цветов: ЛЮБОЕ цветовое значение в app.css обязано быть hct(...) — и литерал, и производное hct(from var(...) h c t). Исключения: только --brand-main / --brand-alt (seed-токены, любая форма) и color-mix(...) (единственный легальный способ смешать два токена). oklch()/rgb()/#hex в --color-* запрещены.

Выводит варнинг о неиспользуемых токенах app.css (определены, но нигде не используются) — выход он не меняет. Провалом (exit 1) считаются только parity и hct-авторство.

Тесты кастомных линт-правил

Линт-правила покрыты юнит-тестами (Vitest, test:rules):

• __tests__/design-tokens.test.ts — три чистых правила (no-hardcoded-in-svelte, no-category-mismatch, no-token-definition-in-svelte) через RuleTester со строковыми кейсами; no-undefined-in-svelte — через Linter API, т.к. читает словарь токенов из __fixtures__/src/app.css (не из реального src/app.css).
• __tests__/no-mixed-imports.test.ts — isolation-правило через Linter API с cwd на __fixtures__: правило резолвит импорты по реальным файлам, поэтому цели импортов обязаны существовать на диске.
• Хелпер __tests__/helpers.ts собирает Linter с cwd = __fixtures__ — process.cwd() не трогается, реальные src/ не читаются.

Запуск: pnpm --dir web test:rules (vitest run eslint-plugins/__tests__). Полный pnpm --dir web test тоже их гоняет.

Фикстуры живут в __fixtures__/ и сами прогоняются линтом (eslint .), поэтому добавление/правка стабов — тоже работа с валидным кодом.

Isolation-правило (isolation/no-mixed-imports)

Полная взаимная изоляция старого (v1) и нового (корень) UI. В отличие от no-restricted-imports, правило резолвит каждый импорт (и $lib/..., и относительные .//../) до реального файла и классифицирует стороны по фактическому пути, поэтому относительным импортом правило не обойти.

• Старое: routes/v1/**, lib/v1/**.
• Новое: routes/** без v1/**; корневой lib целиком (lib/**) без lib/v1/** и без общих пакетов.
• Общее (разрешено обоим) — только служебные пакеты: core/, theme. v1 не высовывается: из lib/v1/** наружу разрешены импорты лишь в общие пакеты и в собственный форк i18n (lib/v1/i18n/**).
• Плагин конфигурируем (опции old/new + root/alias в eslint.config.js): перенос старых файлов в папки old/ — это правка glob-паттернов в настройке, а не код правила.
• Изоляция уже достигнута: старый lib/v1/registry.ts/registry-helpers.ts не тянут registry-schema (пилоты add-border/add-stroke работают через params), registry.ts не импортирует ToolSchema; новый list-tools использует $lib/tool-icons.ts, а не старые lib/v1/tools/tool-icons.ts.

Линтер только показывает ошибки, старый код (непрефиксованные токены, hex в app_v1.css) — известный техдолг, его НЕ чинить и не игнорировать правилами.