@alexlit/lint-kit 214.3.0 → 215.0.0

package/packages/config-prettier/README.md

@@ -1,37 +1,120 @@
+[![version](https://npmx.dev/api/registry/badge/version/@alexlit/config-prettier)](https://www.npmjs.com/package/@alexlit/config-prettier)
+[![downloads](https://npmx.dev/api/registry/badge/downloads/@alexlit/config-prettier)](https://npmx.dev/package/@alexlit/config-prettier)
+[![license](https://npmx.dev/api/registry/badge/license/@alexlit/config-prettier)](LICENSE)
+
 # Prettier Configuration
 
-## Installation
+Готовая конфигурация [Prettier](https://prettier.io/) с плагинами для
+форматирования языков и форматов, которых Prettier не поддерживает из коробки
+(PHP, SQL, шаблоны, shell-скрипты и т.д.), а также расширений для сортировки
+JSON и утилит Tailwind CSS. Вместо того чтобы подключать и настраивать каждый
+плагин вручную, соберите конфигурацию из готовых модулей.
+
+Плагины модульные: по умолчанию ничего не включено - вы сами перечисляете нужные
+в `defineConfig`.
+
+## Установка
 
-```sh
+```bash
 npm i @alexlit/config-prettier -D
 ```
 
-## Connection
+## Быстрый старт
+
+```js
+// prettier.config.js
+import { defineConfig, plugins } from '@alexlit/config-prettier';
+
+export default defineConfig([plugins.packageJson(), plugins.xml()]);
+```
+
+Каждый вызов `plugins.*()` - отдельный плагин. Добавьте только то, что нужно
+проекту; полный список - в разделе [Плагины](#плагины).
+
+Больше плагинов - просто допишите их в массив:
+
+```js
+// prettier.config.js
+import { defineConfig, plugins } from '@alexlit/config-prettier';
+
+export default defineConfig([
+  plugins.jsdoc(),
+  plugins.mdc(),
+  plugins.packageJson(),
+  plugins.php(),
+  plugins.pug(),
+  plugins.ruby(),
+  plugins.sh(),
+  plugins.sortJson(),
+  plugins.solidity(),
+  plugins.sql(),
+  plugins.tailwindcss(),
+  plugins.xml(),
+]);
+```
+
+## Настройка
+
+### Настройки конкретного плагина
+
+Чтобы переопределить настройки одного плагина, передайте объект в его вызов:
+
+```js
+// prettier.config.js
+import { defineConfig, plugins } from '@alexlit/config-prettier';
+
+export default defineConfig([
+  plugins.sortJson({ jsonRecursiveSort: false }),
+  plugins.tailwindcss({ tailwindFunctions: ['cn', 'cva'] }),
+]);
+```
+
+### Общие настройки Prettier
+
+Второй аргумент `defineConfig` - общие опции Prettier. Он перебивает настройки
+всех плагинов:
+
+```js
+// prettier.config.js
+import { defineConfig, plugins } from '@alexlit/config-prettier';
+
+export default defineConfig([plugins.php()], {
+  printWidth: 100,
+  singleQuote: false,
+});
+```
 
-- Default
-  ([see plugins enabled by default](https://github.com/alex-lit/lint-kit/blob/master/packages/config-prettier/index.js#L5))
+## Плагины
 
-  ```js
-  // prettier.config.js
-  import { createConfig } from '@alexlit/config-prettier';
+| Плагин                  | Что делает                                      | Пакет                                             |
+| ----------------------- | ----------------------------------------------- | ------------------------------------------------- |
+| `plugins.jsdoc()`       | Нормализует JSDoc-комментарии                   | `prettier-plugin-jsdoc`                           |
+| `plugins.mdc()`         | Форматирует MDC-документы (Nuxt Content)        | `prettier-plugin-mdc`                             |
+| `plugins.packageJson()` | Сортирует ключи в package.json                  | `prettier-plugin-packagejson`                     |
+| `plugins.php()`         | Форматирует PHP-файлы                           | `@prettier/plugin-php`                            |
+| `plugins.pug()`         | Форматирует Pug-шаблоны с сортировкой атрибутов | `@prettier/plugin-pug`                            |
+| `plugins.ruby()`        | Форматирует Ruby и ERB файлы                    | `@prettier/plugin-ruby` + `prettier-plugin-eruby` |
+| `plugins.sh()`          | Форматирует shell-скрипты                       | `prettier-plugin-sh`                              |
+| `plugins.sortJson()`    | Рекурсивно сортирует ключи JSON-объектов        | `prettier-plugin-sort-json`                       |
+| `plugins.solidity()`    | Форматирует контракты Solidity                  | `prettier-plugin-solidity`                        |
+| `plugins.sql()`         | Форматирует SQL-запросы                         | `prettier-plugin-sql`                             |
+| `plugins.tailwindcss()` | Сортирует утилитарные классы Tailwind CSS       | `prettier-plugin-tailwindcss`                     |
+| `plugins.xml()`         | Форматирует XML-файлы                           | `@prettier/plugin-xml`                            |
 
-  export default createConfig();
-  ```
+## Миграция с v23
 
-- Custom
+v24 - breaking-релиз: плагинов по умолчанию больше нет, всё подключается явно.
 
-  ```js
-  // prettier.config.js
-  import { createConfig } from '@alexlit/config-prettier';
+| v23                            | v24                                           |
+| ------------------------------ | --------------------------------------------- |
+| `createConfig()`               | перечислите нужные плагины явно               |
+| `createConfig({ php: true })`  | `defineConfig([plugins.php()])`               |
+| `createConfig({ sql: false })` | просто не добавляйте `plugins.sql()` в список |
+| `createConfig({}, options)`    | `defineConfig([...], options)`                |
 
-  export default createConfig({
-    php: true,
-    ruby: true,
-    sql: false,
-    tailwindcss: false,
-  });
-  ```
+Плагины, включённые по умолчанию в v23: `jsdoc`, `mdc`, `packagejson`, `pug`,
+`sh`, `solidity`, `sort-json`, `xml`.
 
-## Issues
+## Известные проблемы
 
-- **tailwindcss** conflicts with **jsdoc**
+- **tailwindcss** ранее конфликтовал с **jsdoc**

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

@@ -0,0 +1,92 @@
+import type { Config } from 'prettier';
+
+/**
+ * Options of
+ * [prettier-plugin-jsdoc](https://github.com/hosseinmd/prettier-plugin-jsdoc)
+ */
+export interface JsdocOptions {
+  jsdocCommentLineStrategy?: 'fallback' | 'multiLine' | 'singleLine';
+  jsdocSeparateReturnsFromParam?: boolean;
+  jsdocSeparateTagGroups?: boolean;
+}
+
+/**
+ * Plugin factories. Every plugin is connected explicitly: pass
+ * `plugins.<name>()` to `defineConfig`
+ */
+export interface Plugins {
+  /** @see prettier-plugin-jsdoc */
+  jsdoc(options?: Config & JsdocOptions): Config;
+  /** @see prettier-plugin-mdc */
+  mdc(options?: Config): Config;
+  /** @see prettier-plugin-packagejson */
+  packageJson(options?: Config): Config;
+  /** @see plugin-php */
+  php(options?: Config): Config;
+  /** @see plugin-pug */
+  pug(options?: Config & PugOptions): Config;
+  /** @see plugin-ruby */
+  ruby(options?: Config): Config;
+  /** @see prettier-plugin-sh */
+  sh(options?: Config): Config;
+  /** @see prettier-plugin-solidity */
+  solidity(options?: Config): Config;
+  /** @see prettier-plugin-sort-json */
+  sortJson(options?: Config & SortJsonOptions): Config;
+  /** @see prettier-plugin-sql */
+  sql(options?: Config): Config;
+  /** @see prettier-plugin-tailwindcss */
+  tailwindcss(options?: Config & TailwindcssOptions): Config;
+  /** @see plugin-xml */
+  xml(options?: Config & XmlOptions): Config;
+}
+
+/** Options of [plugin-pug](https://github.com/prettier/plugin-pug) */
+export interface PugOptions {
+  pugCommentPreserveSpaces?: string;
+  pugSingleQuote?: boolean;
+  pugSortAttributes?: 'asc' | 'desc' | 'natural' | false;
+  pugWrapAttributesThreshold?: number;
+}
+
+/**
+ * Options of
+ * [prettier-plugin-sort-json](https://github.com/Gudahtt/prettier-plugin-sort-json)
+ */
+export interface SortJsonOptions {
+  jsonRecursiveSort?: boolean;
+}
+
+/**
+ * Options of
+ * [prettier-plugin-tailwindcss](https://github.com/tailwindlabs/prettier-plugin-tailwindcss)
+ */
+export interface TailwindcssOptions {
+  tailwindFunctions?: string[];
+}
+
+/** Options of [plugin-xml](https://github.com/prettier/plugin-xml) */
+export interface XmlOptions {
+  xmlWhitespaceSensitivity?: 'ignore' | 'preserve' | 'strict';
+}
+
+export declare const plugins: Plugins;
+
+/**
+ * Create prettier config
+ *
+ * There are no default plugins - connect the required ones explicitly:
+ *
+ * ```js
+ * defineConfig([plugins.php(), plugins.tailwindcss()], {
+ *   printWidth: 100,
+ * });
+ * ```
+ *
+ * @param pluginConfigs Plugin configs, e.g. `[plugins.php()]`
+ * @param options Base prettier options (highest precedence)
+ */
+export declare function defineConfig(
+  pluginConfigs?: Config[],
+  options?: Config,
+): Config;

package/packages/config-prettier/index.js

@@ -1,87 +1,62 @@
-import { omit } from 'radash';
-
-const DEFAULT_PLUGINS = {
-  'jsdoc': true,
-  'mdc': true,
-  'packagejson': true,
-  'pug': true,
-  'sh': true,
-  'solidity': true,
-  'sort-json': true,
-  'xml': true,
-};
-
-const OPTIONAL_PLUGINS = {
-  php: false,
-  ruby: false,
-  sql: false,
-  tailwindcss: false,
-};
-
-const PLUGINS = { ...DEFAULT_PLUGINS, ...OPTIONAL_PLUGINS };
+import { jsdoc } from './plugins/jsdoc.js';
+import { mdc } from './plugins/mdc.js';
+import { packageJson } from './plugins/packagejson.js';
+import { php } from './plugins/php.js';
+import { pug } from './plugins/pug.js';
+import { ruby } from './plugins/ruby.js';
+import { sh } from './plugins/sh.js';
+import { solidity } from './plugins/solidity.js';
+import { sortJson } from './plugins/sort-json.js';
+import { sql } from './plugins/sql.js';
+import { tailwindcss } from './plugins/tailwindcss.js';
+import { xml } from './plugins/xml.js';
 
 /**
- * Create plugins config list
- *
- * @param {PLUGINS} plugins Enabled/disabled plugins list
- *
- * @returns {import('prettier').Config} Prettier configuration
+ * Фабрики плагинов. Каждый плагин подключается явно: передайте
+ * `plugins.<name>()` в `defineConfig`
  */
-const createPluginsConfig = async (plugins = {}) => {
-  const pluginEntries = Object.entries({ ...PLUGINS, ...plugins });
-
-  const configs = await Promise.all(
-    pluginEntries
-      .filter(([, isActive]) => isActive)
-      .map(async ([name]) => {
-        const { default: config } = await import(
-          `@alexlit/config-prettier/plugins/${name}.js`
-        );
-
-        return config;
-      }),
-  );
-
-  let pluginsConfig = { overrides: [], plugins: [] };
-
-  configs.forEach((config) => {
-    if (config.plugins?.length > 0) {
-      pluginsConfig.plugins.push(...config.plugins);
-    }
-
-    if (config.overrides?.length > 0) {
-      pluginsConfig.overrides.push(...config.overrides);
-    }
-
-    pluginsConfig = {
-      ...pluginsConfig,
-      ...omit(config, ['plugins', 'overrides']),
-    };
-  });
-
-  return pluginsConfig;
+export const plugins = {
+  jsdoc,
+  mdc,
+  packageJson,
+  php,
+  pug,
+  ruby,
+  sh,
+  solidity,
+  sortJson,
+  sql,
+  tailwindcss,
+  xml,
 };
 
 /**
- * Create prettier config
+ * Создать конфигурацию Prettier
+ *
+ * Плагинов по умолчанию нет - подключайте нужные явно:
  *
- * @param {PLUGINS} plugins
- * @param {import('prettier').Config} options Prettier options
+ * ```js
+ * defineConfig(
+ *   [
+ *     plugins.php(),
+ *     plugins.tailwindcss({ tailwindFunctions: ['cn', 'tw'] }),
+ *   ],
+ *   { printWidth: 100 },
+ * );
+ * ```
  *
- * @returns {import('prettier').Config} Prettier configuration
+ * @param {import('prettier').Config[]} pluginConfigs Конфиги плагинов, напр.
+ *   `[plugins.php()]`
+ * @param {import('prettier').Config} options Базовые опции Prettier (наивысший
+ *   приоритет)
+ *
+ * @returns {import('prettier').Config} Конфигурация Prettier
  */
-export const createConfig = async (plugins = {}, options = {}) => {
-  const pluginsConfig = await createPluginsConfig(plugins);
-
-  return {
+export const defineConfig = (pluginConfigs = [], options = {}) => {
+  const config = {
     bracketSameLine: false,
     endOfLine: 'lf',
     objectWrap: 'collapse',
-    overrides: [
-      ...(pluginsConfig.overrides ?? []),
-      ...(options.overrides ?? []),
-    ],
-    plugins: [...(pluginsConfig.plugins ?? []), ...(options.plugins ?? [])],
     proseWrap: 'always',
     quoteProps: 'consistent',
     singleAttributePerLine: true,
@@ -90,7 +65,18 @@ export const createConfig = async (plugins = {}, options = {}) => {
     trailingComma: 'all',
     vueIndentScriptAndStyle: true,
 
-    ...omit(pluginsConfig, ['plugins']),
-    ...omit(options, ['plugins']),
+    // конфиги плагинов перекрывают базовые опции, а пользовательские опции
+    // имеют наивысший приоритет
+    ...Object.assign({}, ...pluginConfigs, options),
+  };
+
+  const sources = [...pluginConfigs, options];
+
+  return {
+    ...config,
+
+    // `overrides` и `plugins` конкатенируются, а не заменяются
+    overrides: sources.flatMap((source) => source.overrides ?? []),
+    plugins: [...new Set(sources.flatMap((source) => source.plugins ?? []))],
   };
 };

package/packages/config-prettier/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alexlit/config-prettier",
-  "version": "23.2.2",
+  "version": "24.1.3",
   "private": false,
   "description": "prettier config",
   "keywords": [
@@ -23,8 +23,10 @@
   ],
   "type": "module",
   "main": "index.js",
+  "types": "index.d.ts",
   "files": [
     "README.md",
+    "index.d.ts",
     "index.js",
     "plugins"
   ],
@@ -35,7 +37,7 @@
     "up": "../../scripts/up.sh"
   },
   "dependencies": {
-    "@prettier/plugin-php": "^0.25.0",
+    "@prettier/plugin-php": "^0.26.0",
     "@prettier/plugin-pug": "^3.6.0",
     "@prettier/plugin-ruby": "^4.0.4",
     "@prettier/plugin-xml": "^3.4.2",
@@ -48,8 +50,7 @@
     "prettier-plugin-solidity": "^2.4.1",
     "prettier-plugin-sort-json": "^4.2.0",
     "prettier-plugin-sql": "^0.20.0",
-    "prettier-plugin-tailwindcss": "^0.8.1",
-    "radash": "^12.1.1"
+    "prettier-plugin-tailwindcss": "^0.8.1"
   },
   "publishConfig": {
     "access": "public",

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

@@ -1,7 +1,16 @@
-/** @see [prettier-plugin-jsdoc](https://github.com/hosseinmd/prettier-plugin-jsdoc) */
-export default {
+/**
+ * Нормализует JSDoc-комментарии
+ *
+ * @param {Partial<import('prettier').Config>} [options]
+ *
+ * @returns {import('prettier').Config}
+ *
+ * @see [prettier-plugin-jsdoc](https://github.com/hosseinmd/prettier-plugin-jsdoc)
+ */
+export const jsdoc = (options = {}) => ({
   jsdocCommentLineStrategy: 'singleLine',
   jsdocSeparateReturnsFromParam: true,
   jsdocSeparateTagGroups: true,
   plugins: ['prettier-plugin-jsdoc'],
-};
+  ...options,
+});

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

@@ -1,5 +1,14 @@
-/** @see [prettier-plugin-mdc](https://github.com/so1ve/prettier-plugin-mdc) */
-export default {
+/**
+ * Форматирует MDC-документы (Nuxt Content)
+ *
+ * @param {Partial<import('prettier').Config>} [options]
+ *
+ * @returns {import('prettier').Config}
+ *
+ * @see [prettier-plugin-mdc](https://github.com/so1ve/prettier-plugin-mdc)
+ */
+export const mdc = (options = {}) => ({
   overrides: [{ files: ['*.md'], options: { parser: 'mdc' } }],
   plugins: ['prettier-plugin-mdc'],
-};
+  ...options,
+});

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

@@ -1,4 +1,13 @@
-/** @see [prettier-plugin-packagejson](https://github.com/matzkoh/prettier-plugin-packagejson) */
-export default {
+/**
+ * Сортирует ключи в package.json
+ *
+ * @param {Partial<import('prettier').Config>} [options]
+ *
+ * @returns {import('prettier').Config}
+ *
+ * @see [prettier-plugin-packagejson](https://github.com/matzkoh/prettier-plugin-packagejson)
+ */
+export const packageJson = (options = {}) => ({
   plugins: ['prettier-plugin-packagejson'],
-};
+  ...options,
+});

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

@@ -1,4 +1,13 @@
-/** @see [plugin-php](https://github.com/prettier/plugin-php) */
-export default {
+/**
+ * Форматирует PHP-файлы
+ *
+ * @param {Partial<import('prettier').Config>} [options]
+ *
+ * @returns {import('prettier').Config}
+ *
+ * @see [plugin-php](https://github.com/prettier/plugin-php)
+ */
+export const php = (options = {}) => ({
   plugins: ['@prettier/plugin-php'],
-};
+  ...options,
+});

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

@@ -1,8 +1,17 @@
-/** @see [plugin-pug](https://github.com/prettier/plugin-pug) */
-export default {
+/**
+ * Форматирует Pug-шаблоны с сортировкой атрибутов и одинарными кавычками
+ *
+ * @param {Partial<import('prettier').Config>} [options]
+ *
+ * @returns {import('prettier').Config}
+ *
+ * @see [plugin-pug](https://github.com/prettier/plugin-pug)
+ */
+export const pug = (options = {}) => ({
   plugins: ['@prettier/plugin-pug'],
   pugCommentPreserveSpaces: 'trim-all',
   pugSingleQuote: false,
   pugSortAttributes: 'asc',
   pugWrapAttributesThreshold: 3,
-};
+  ...options,
+});

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

@@ -1,15 +1,15 @@
 /**
+ * Форматирует Ruby и ERB файлы
+ *
+ * @param {Partial<import('prettier').Config>} [options]
+ *
+ * @returns {import('prettier').Config}
+ *
  * @see [plugin-ruby](https://github.com/prettier/plugin-ruby)
  * @see [prettier-plugin-eruby](https://github.com/ippachi/prettier-plugin-eruby)
  */
-export default {
-  overrides: [
-    {
-      files: '*.html.erb',
-      options: {
-        parser: 'eruby-parse',
-      },
-    },
-  ],
+export const ruby = (options = {}) => ({
+  overrides: [{ files: '*.html.erb', options: { parser: 'eruby-parse' } }],
   plugins: ['@prettier/plugin-ruby', 'prettier-plugin-eruby'],
-};
+  ...options,
+});

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

@@ -1,4 +1,13 @@
-/** @see [prettier-plugin-sh](https://github.com/astorije/prettier-plugin-sh) */
-export default {
+/**
+ * Форматирует shell-скрипты
+ *
+ * @param {Partial<import('prettier').Config>} [options]
+ *
+ * @returns {import('prettier').Config}
+ *
+ * @see [prettier-plugin-sh](https://github.com/astorije/prettier-plugin-sh)
+ */
+export const sh = (options = {}) => ({
   plugins: ['prettier-plugin-sh'],
-};
+  ...options,
+});

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

@@ -1,4 +1,13 @@
-/** @see [prettier-plugin-solidity](https://github.com/prettier-solidity/prettier-plugin-solidity) */
-export default {
+/**
+ * Форматирует контракты Solidity
+ *
+ * @param {Partial<import('prettier').Config>} [options]
+ *
+ * @returns {import('prettier').Config}
+ *
+ * @see [prettier-plugin-solidity](https://github.com/prettier-solidity/prettier-plugin-solidity)
+ */
+export const solidity = (options = {}) => ({
   plugins: ['prettier-plugin-solidity'],
-};
+  ...options,
+});

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

@@ -1,5 +1,14 @@
-/** @see [prettier-plugin-sort-json](https://github.com/Gudahtt/prettier-plugin-sort-json) */
-export default {
+/**
+ * Рекурсивно сортирует ключи JSON-объектов
+ *
+ * @param {Partial<import('prettier').Config>} [options]
+ *
+ * @returns {import('prettier').Config}
+ *
+ * @see [prettier-plugin-sort-json](https://github.com/Gudahtt/prettier-plugin-sort-json)
+ */
+export const sortJson = (options = {}) => ({
   jsonRecursiveSort: true,
   plugins: ['prettier-plugin-sort-json'],
-};
+  ...options,
+});

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

@@ -1,4 +1,13 @@
-/** @see [prettier-plugin-sql](https://github.com/un-ts/prettier/tree/master/packages/sql) */
-export default {
+/**
+ * Форматирует SQL-запросы
+ *
+ * @param {Partial<import('prettier').Config>} [options]
+ *
+ * @returns {import('prettier').Config}
+ *
+ * @see [prettier-plugin-sql](https://github.com/un-ts/prettier/tree/master/packages/sql)
+ */
+export const sql = (options = {}) => ({
   plugins: ['prettier-plugin-sql'],
-};
+  ...options,
+});

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

@@ -1,5 +1,13 @@
-/** @see [prettier-plugin-tailwindcss](https://github.com/tailwindlabs/prettier-plugin-tailwindcss) */
-export default {
+/**
+ * Сортирует утилитарные классы Tailwind CSS по каноническому порядку
+ *
+ * @param {Partial<import('prettier').Config>} [options]
+ *
+ * @returns {import('prettier').Config}
+ *
+ * @see [prettier-plugin-tailwindcss](https://github.com/tailwindlabs/prettier-plugin-tailwindcss)
+ */
+export const tailwindcss = (options = {}) => ({
   plugins: ['prettier-plugin-tailwindcss'],
   tailwindFunctions: [
     'classnames',
@@ -11,4 +19,5 @@ export default {
     'tw',
     'twMerge',
   ],
-};
+  ...options,
+});

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

@@ -1,5 +1,14 @@
-/** @see [plugin-xml](https://github.com/prettier/plugin-xml) */
-export default {
+/**
+ * Форматирует XML-файлы
+ *
+ * @param {Partial<import('prettier').Config>} [options]
+ *
+ * @returns {import('prettier').Config}
+ *
+ * @see [plugin-xml](https://github.com/prettier/plugin-xml)
+ */
+export const xml = (options = {}) => ({
   plugins: ['@prettier/plugin-xml'],
   xmlWhitespaceSensitivity: 'ignore',
-};
+  ...options,
+});