@alexlit/lint-kit 214.4.0 → 216.0.0

package/packages/config-prettier/plugins/solidity.js

@@ -1,4 +1,17 @@
-/** @see [prettier-plugin-solidity](https://github.com/prettier-solidity/prettier-plugin-solidity) */
-export default {
-  plugins: ['prettier-plugin-solidity'],
-};
+import { mergeConfigs } from '../utils/merge-configs.js';
+
+const DEFAULTS = { plugins: ['prettier-plugin-solidity'] };
+
+/**
+ * Форматирует контракты Solidity
+ *
+ * @param {Partial<import('prettier').Config>} [options] - Опции, накладываемые
+ *   поверх значений по умолчанию. Коллекции (`overrides`, `plugins`)
+ *   дополняются, `plugins` дедуплицируются, более поздние `overrides`
+ *   выигрывают, остальные поля заменяются
+ *
+ * @returns {import('prettier').Config}
+ *
+ * @see [prettier-plugin-solidity](https://github.com/prettier-solidity/prettier-plugin-solidity)
+ */
+export const solidity = (options = {}) => mergeConfigs(DEFAULTS, options);

package/packages/config-prettier/plugins/sort-json.js

@@ -1,5 +1,20 @@
-/** @see [prettier-plugin-sort-json](https://github.com/Gudahtt/prettier-plugin-sort-json) */
-export default {
+import { mergeConfigs } from '../utils/merge-configs.js';
+
+const DEFAULTS = {
   jsonRecursiveSort: true,
   plugins: ['prettier-plugin-sort-json'],
 };
+
+/**
+ * Рекурсивно сортирует ключи JSON-объектов
+ *
+ * @param {Partial<import('prettier').Config>} [options] - Опции, накладываемые
+ *   поверх значений по умолчанию. Коллекции (`overrides`, `plugins`)
+ *   дополняются, `plugins` дедуплицируются, более поздние `overrides`
+ *   выигрывают, остальные поля заменяются
+ *
+ * @returns {import('prettier').Config}
+ *
+ * @see [prettier-plugin-sort-json](https://github.com/Gudahtt/prettier-plugin-sort-json)
+ */
+export const sortJson = (options = {}) => mergeConfigs(DEFAULTS, options);

package/packages/config-prettier/plugins/sql.js

@@ -1,4 +1,17 @@
-/** @see [prettier-plugin-sql](https://github.com/un-ts/prettier/tree/master/packages/sql) */
-export default {
-  plugins: ['prettier-plugin-sql'],
-};
+import { mergeConfigs } from '../utils/merge-configs.js';
+
+const DEFAULTS = { plugins: ['prettier-plugin-sql'] };
+
+/**
+ * Форматирует SQL-запросы
+ *
+ * @param {Partial<import('prettier').Config>} [options] - Опции, накладываемые
+ *   поверх значений по умолчанию. Коллекции (`overrides`, `plugins`)
+ *   дополняются, `plugins` дедуплицируются, более поздние `overrides`
+ *   выигрывают, остальные поля заменяются
+ *
+ * @returns {import('prettier').Config}
+ *
+ * @see [prettier-plugin-sql](https://github.com/un-ts/prettier/tree/master/packages/sql)
+ */
+export const sql = (options = {}) => mergeConfigs(DEFAULTS, options);

package/packages/config-prettier/plugins/tailwindcss.js

@@ -1,5 +1,6 @@
-/** @see [prettier-plugin-tailwindcss](https://github.com/tailwindlabs/prettier-plugin-tailwindcss) */
-export default {
+import { mergeConfigs } from '../utils/merge-configs.js';
+
+const DEFAULTS = {
   plugins: ['prettier-plugin-tailwindcss'],
   tailwindFunctions: [
     'classnames',
@@ -12,3 +13,17 @@ export default {
     'twMerge',
   ],
 };
+
+/**
+ * Сортирует утилитарные классы Tailwind CSS по каноническому порядку
+ *
+ * @param {Partial<import('prettier').Config>} [options] - Опции, накладываемые
+ *   поверх значений по умолчанию. Коллекции (`overrides`, `plugins`)
+ *   дополняются, `plugins` дедуплицируются, более поздние `overrides`
+ *   выигрывают, остальные поля заменяются
+ *
+ * @returns {import('prettier').Config}
+ *
+ * @see [prettier-plugin-tailwindcss](https://github.com/tailwindlabs/prettier-plugin-tailwindcss)
+ */
+export const tailwindcss = (options = {}) => mergeConfigs(DEFAULTS, options);

package/packages/config-prettier/plugins/xml.js

@@ -1,5 +1,20 @@
-/** @see [plugin-xml](https://github.com/prettier/plugin-xml) */
-export default {
+import { mergeConfigs } from '../utils/merge-configs.js';
+
+const DEFAULTS = {
   plugins: ['@prettier/plugin-xml'],
   xmlWhitespaceSensitivity: 'ignore',
 };
+
+/**
+ * Форматирует XML-файлы
+ *
+ * @param {Partial<import('prettier').Config>} [options] - Опции, накладываемые
+ *   поверх значений по умолчанию. Коллекции (`overrides`, `plugins`)
+ *   дополняются, `plugins` дедуплицируются, более поздние `overrides`
+ *   выигрывают, остальные поля заменяются
+ *
+ * @returns {import('prettier').Config}
+ *
+ * @see [plugin-xml](https://github.com/prettier/plugin-xml)
+ */
+export const xml = (options = {}) => mergeConfigs(DEFAULTS, options);

package/packages/config-prettier/utils/merge-configs.js

@@ -0,0 +1,18 @@
+/**
+ * Объединяет конфигурации Prettier
+ *
+ * Коллекции `overrides` и `plugins` дополняются: пользовательские значения идут
+ * после дефолтных, поэтому более поздние overrides выигрывают. `plugins`
+ * дедуплицируются. Остальные поля заменяются значениями из последующих
+ * конфигураций.
+ *
+ * @param {...import('prettier').Config} configs Конфигурации в порядке
+ *   приоритета
+ *
+ * @returns {import('prettier').Config} Объединённая конфигурация
+ */
+export const mergeConfigs = (...configs) => ({
+  ...Object.assign({}, ...configs),
+  overrides: configs.flatMap((config) => config.overrides ?? []),
+  plugins: [...new Set(configs.flatMap((config) => config.plugins ?? []))],
+});

package/packages/config-stylelint/README.md

@@ -1,62 +1,200 @@
-# StyleLint Configuration
+# Stylelint Configuration
 
-## Installation
+[![version](https://npmx.dev/api/registry/badge/version/@alexlit/config-stylelint)](https://www.npmjs.com/package/@alexlit/config-stylelint)
+[![downloads](https://npmx.dev/api/registry/badge/downloads/@alexlit/config-stylelint)](https://npmx.dev/package/@alexlit/config-stylelint)
+[![license](https://npmx.dev/api/registry/badge/license/@alexlit/config-stylelint)](LICENSE)
 
-```sh
+Готовая конфигурация [Stylelint](https://stylelint.io/) для проверки CSS, SCSS и
+Vue-файлов: настроенные правила из популярных stylelint-плагинов - порядок и
+синтаксис свойств, доступность, БЭМ, поддержка SCSS и т.д. Вместо того чтобы
+подключать и настраивать каждый плагин вручную, соберите конфигурацию из готовых
+проверок.
+
+Проверки модульные: по умолчанию ничего не включено - вы сами перечисляете
+нужные в `defineConfig`.
+
+## Установка
+
+```bash
 npm i @alexlit/config-stylelint -D
 ```
 
-## Connection
+## Быстрый старт
 
-- Default
-  ([see plugins enabled by default](https://github.com/alex-lit/lint-kit/blob/master/packages/config-stylelint/index.js))
+```js
+// stylelint.config.js
+import { defineConfig, plugins } from '@alexlit/config-stylelint';
 
-  ```js
-  // stylelint.config.js
-  import { createConfig } from '@alexlit/config-stylelint';
+export default defineConfig([
+  plugins.scss(),
+  plugins.vue(),
 
-  export default createConfig();
-  ```
+  plugins.prettier(),
+]);
+```
 
-- Custom
-
-  ```js
-  // stylelint.config.js
-  import { createConfig } from '@alexlit/config-stylelint';
-
-  export default createConfig(
-    {
-      // disable some default plugins
-      'no-nested-media': false,
-
-      // enable some optional plugins
-      'gamut': true,
-      'logical-css': true,
-    },
-    {
-      // add custom rules
-      rules: {
-        'custom-property-empty-line-before': [
-          'always',
-          {
-            except: ['after-comment', 'after-custom-property', 'first-nested'],
-          },
-        ],
-      },
-    },
-  );
-  ```
+Каждый вызов `plugins.*()` - отдельная проверка. Добавьте только то, что нужно
+проекту; полный список - в разделе [Проверки](#проверки).
+
+Больше проверок - просто допишите их в массив:
+
+```js
+// stylelint.config.js
+import { defineConfig, plugins } from '@alexlit/config-stylelint';
+
+export default defineConfig([
+  plugins.a11y(),
+  plugins.bem(),
+  plugins.colorFormat(),
+  plugins.declarationBlockNoIgnoredProperties(),
+  plugins.gamut(),
+  plugins.highPerformanceAnimation(),
+  plugins.logicalCss(),
+  plugins.mediaUseCustomMedia(),
+  plugins.noNestedMedia(),
+  plugins.noUnresolvedModule(),
+  plugins.noUnsupportedBrowserFeatures(),
+  plugins.order(),
+  plugins.scss(),
+  plugins.selectorNoEmpty(),
+  plugins.useNesting(),
+  plugins.vue(),
+
+  plugins.prettier(),
+]);
+```
+
+## Настройка
+
+### Правила конкретной проверки
+
+Чтобы переопределить правила одной проверки, передайте объект в её вызов:
+
+```js
+// stylelint.config.js
+import { defineConfig, plugins } from '@alexlit/config-stylelint';
+
+export default defineConfig([
+  plugins.useNesting({ rules: { 'csstools/use-nesting': 'never' } }),
+  plugins.noUnresolvedModule({
+    rules: { 'plugin/no-unresolved-module': { alias: { '~': 'src' } } },
+  }),
+]);
+```
+
+`rules` мержатся поверхностно: настройка одноимённого правила из опций заменяет
+дефолтную целиком.
+
+### Правила для отдельных файлов
+
+Чтобы применить правила только к части файлов, используйте `overrides` в опциях
+проверки. Пользовательские overrides добавляются после дефолтных, поэтому
+выигрывают у них:
+
+```js
+// stylelint.config.js
+import { defineConfig, plugins } from '@alexlit/config-stylelint';
+
+export default defineConfig([
+  plugins.useNesting({
+    overrides: [
+      { files: ['**/*.vue'], rules: { 'csstools/use-nesting': 'never' } },
+    ],
+  }),
+]);
+```
+
+`files` обязателен: Stylelint падает с ошибкой, если в override его нет.
+
+### Приоритет настроек
+
+Внутри одной проверки: дефолты → `options.rules` → `options.overrides` (для
+подходящих файлов). Между проверками и вторым аргументом `defineConfig`
+действует тот же порядок: база → проверки по порядку → `options`.
+
+Коллекции (`extends`, `ignoreFiles`, `overrides`, `plugins`) дополняются,
+`plugins` дедуплицируются. Остальные поля, например `customSyntax`, заменяются
+значениями из опций.
+
+### Общие настройки Stylelint
+
+Второй аргумент `defineConfig` - общие опции: собственные правила, файлы для
+игнора и т.д. Он перебивает настройки всех проверок:
+
+```js
+// stylelint.config.js
+import { defineConfig, plugins } from '@alexlit/config-stylelint';
+
+export default defineConfig([plugins.scss(), plugins.vue()], {
+  ignoreFiles: ['fixtures/**'],
+  rules: { 'max-nesting-depth': 3 },
+});
+```
+
+## Проверки
+
+| Проверка                                        | Что делает                                           | Плагин                                                                                                                                  |
+| ----------------------------------------------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `plugins.a11y()`                                | Проверяет типичные ошибки доступности                | [`@double-great/stylelint-a11y`](https://github.com/double-great/stylelint-a11y)                                                        |
+| `plugins.bem()`                                 | Настраивает линтинг по методологии БЭМ               | [`@morev/stylelint-plugin`](https://morevm.github.io/stylelint-plugin/)                                                                 |
+| `plugins.colorFormat()`                         | Нормализует формат цветов (hex → rgb/hsl)            | встроенное правило `color-format/format`                                                                                                |
+| `plugins.declarationBlockNoIgnoredProperties()` | Запрещает бесполезные свойства в блоке объявлений    | [`stylelint-declaration-block-no-ignored-properties`](https://github.com/kristerkari/stylelint-declaration-block-no-ignored-properties) |
+| `plugins.gamut()`                               | Проверяет цвета на выход за пределы цветового охвата | [`stylelint-gamut`](https://github.com/fpetrakov/stylelint-gamut)                                                                       |
+| `plugins.highPerformanceAnimation()`            | Запрещает анимации, нагружающие рендеринг            | [`stylelint-high-performance-animation`](https://github.com/kristerkari/stylelint-high-performance-animation)                           |
+| `plugins.logicalCss()`                          | Проверяет использование логических CSS-свойств       | [`stylelint-plugin-logical-css`](https://github.com/yuschick/stylelint-plugin-logical-css)                                              |
+| `plugins.mediaUseCustomMedia()`                 | Требует использования кастомных медиа-запросов       | [`stylelint-media-use-custom-media`](https://github.com/csstools/stylelint-media-use-custom-media)                                      |
+| `plugins.noIndistinguishableColors()`           | Запрещает неразличимые цвета                         | [`stylelint-no-indistinguishable-colors`](https://github.com/ierhyna/stylelint-no-indistinguishable-colors)                             |
+| `plugins.noNestedMedia()`                       | Запрещает вложенные медиа-запросы                    | [`stylelint-no-nested-media`](https://github.com/dkrnl/stylelint-no-nested-media)                                                       |
+| `plugins.noUnresolvedModule()`                  | Проверяет разрешение импортов                        | [`stylelint-no-unresolved-module`](https://github.com/niksy/stylelint-no-unresolved-module)                                             |
+| `plugins.noUnsupportedBrowserFeatures()`        | Проверяет поддержку CSS-функций целевыми браузерами  | [`stylelint-no-unsupported-browser-features`](https://github.com/ismay/stylelint-no-unsupported-browser-features)                       |
+| `plugins.order()`                               | Настраивает порядок свойств и селекторов             | [`stylelint-order`](https://github.com/hudochenkov/stylelint-order)                                                                     |
+| `plugins.prettier()`                            | Интегрирует Prettier                                 | [`stylelint-prettier`](https://github.com/prettier/stylelint-prettier)                                                                  |
+| `plugins.scss()`                                | Настраивает линтинг SCSS                             | [`stylelint-scss`](https://github.com/kristerkari/stylelint-scss)                                                                       |
+| `plugins.selectorNoEmpty()`                     | Запрещает пустые селекторы                           | [`stylelint-selector-no-empty`](https://github.com/ssivanatarajan/stylelint-selector-no-empty)                                          |
+| `plugins.useNesting()`                          | Требует использования CSS-вложенности                | [`stylelint-use-nesting`](https://github.com/csstools/stylelint-use-nesting)                                                            |
+| `plugins.vue()`                                 | Подключает поддержку Vue.js SFC                      | [`stylelint-config-recommended-vue`](https://github.com/ota-meshi/stylelint-config-recommended-vue)                                     |
+
+## Миграция с v63
+
+v64 - major-релиз: коллекции в опциях проверок теперь дополняют дефолты, а не
+заменяют их.
+
+| Было                                                      | Стало                                                               |
+| --------------------------------------------------------- | ------------------------------------------------------------------- |
+| `plugins.scss({ extends: ['custom'] })` заменял дефолтный | `extends` дополняется, `custom` применяется после дефолтного        |
+| `plugins.useNesting({ plugins: ['custom'] })` заменял     | `plugins` дополняется, дубли убираются                              |
+| `plugins.bem({ overrides: [...] })` заменял дефолтные     | overrides дополняются, пользовательские применяются после дефолтных |
+
+Отключить конкретное дефолтное правило можно через `rules: { 'rule': null }`.
+Общие настройки, которые должны перебивать всё, передавайте вторым аргументом
+`defineConfig`.
+
+## Миграция с v61
+
+v62 - breaking-релиз: проверок по умолчанию больше нет, всё подключается явно.
+
+| v61                             | v62                                            |
+| ------------------------------- | ---------------------------------------------- |
+| `createConfig()`                | перечислите нужные проверки явно               |
+| `createConfig({ gamut: true })` | `defineConfig([plugins.gamut()])`              |
+| `createConfig({ scss: false })` | просто не добавляйте `plugins.scss()` в список |
+| `createConfig({}, options)`     | `defineConfig([...], options)`                 |
+
+Проверки, включённые по умолчанию в v61: `color-format`,
+`declaration-block-no-ignored-properties`, `high-performance-animation`,
+`no-nested-media`, `order`, `scss`, `selector-no-empty`, `use-nesting`, `vue`, а
+также `prettier`.
 
-## Development
+## Разработка
 
-- Check rules
+- Проверка актуальности правил:
 
-  ```sh
+  ```bash
   npx stylelint-find-new-rules
   ```
 
-## Useful links
+## Полезные ссылки
 
-- [Awesome StyleLint](https://github.com/stylelint/awesome-stylelint)
+- [awesome-stylelint](https://github.com/stylelint/awesome-stylelint)
 - [stylelint-scales](https://github.com/jeddy3/stylelint-scales)
 - [stylelint-value-no-unknown-custom-properties](https://github.com/csstools/stylelint-value-no-unknown-custom-properties)

package/packages/config-stylelint/index.d.ts

@@ -0,0 +1,56 @@
+import type { Config } from 'stylelint';
+
+/**
+ * Опции фабрики плагина - частичный конфиг Stylelint, накладываемый поверх
+ * значений по умолчанию.
+ *
+ * Коллекции (`extends`, `ignoreFiles`, `overrides`, `plugins`) дополняют
+ * значения по умолчанию, `rules` мержатся поверхностно, остальные поля
+ * заменяются. Для каждого элемента `overrides` обязателен `files`.
+ */
+type PluginOptions = Partial<Config>;
+
+/**
+ * Пространство имён фабрик конфигов плагинов. Дефолтных плагинов нет -
+ * подключайте нужные явно.
+ */
+interface Plugins {
+  a11y: (options?: PluginOptions) => Config;
+  bem: (options?: PluginOptions) => Config;
+  colorFormat: (options?: PluginOptions) => Config;
+  declarationBlockNoIgnoredProperties: (options?: PluginOptions) => Config;
+  gamut: (options?: PluginOptions) => Config;
+  highPerformanceAnimation: (options?: PluginOptions) => Config;
+  logicalCss: (options?: PluginOptions) => Config;
+  mediaUseCustomMedia: (options?: PluginOptions) => Config;
+  noIndistinguishableColors: (options?: PluginOptions) => Config;
+  noNestedMedia: (options?: PluginOptions) => Config;
+  noUnresolvedModule: (options?: PluginOptions) => Config;
+  noUnsupportedBrowserFeatures: (options?: PluginOptions) => Config;
+  order: (options?: PluginOptions) => Config;
+  prettier: (options?: PluginOptions) => Config;
+  scss: (options?: PluginOptions) => Config;
+  selectorNoEmpty: (options?: PluginOptions) => Config;
+  useNesting: (options?: PluginOptions) => Config;
+  vue: (options?: PluginOptions) => Config;
+}
+
+/** Пространство имён фабрик конфигов плагинов. */
+declare const plugins: Plugins;
+
+/**
+ * Создать конфиг Stylelint.
+ *
+ * Приоритет (от низкого к высокому): база → конфиги плагинов по порядку →
+ * `options`. `extends`, `ignoreFiles`, `overrides` и `plugins` конкатенируются
+ * (дубли `plugins` убираются), `rules` - shallow merge.
+ *
+ * @param pluginConfigs - Конфиги плагинов (например, `[plugins.scss()]`)
+ * @param options - Базовые опции Stylelint, наивысший приоритет
+ */
+declare function defineConfig(
+  pluginConfigs?: Config[],
+  options?: Config,
+): Config;
+
+export { defineConfig, plugins };