@alexlit/lint-kit 214.4.0 → 216.0.0

package/packages/config-hooks/README.md

@@ -1,53 +1,135 @@
 # Hooks Configuration
 
-## Installation
+[![version](https://npmx.dev/api/registry/badge/version/@alexlit/config-hooks)](https://www.npmjs.com/package/@alexlit/config-hooks)
+[![downloads](https://npmx.dev/api/registry/badge/downloads/@alexlit/config-hooks)](https://npmx.dev/package/@alexlit/config-hooks)
+[![license](https://npmx.dev/api/registry/badge/license/@alexlit/config-hooks)](LICENSE)
 
-```sh
+Готовые конфигурации для git-хуков проекта - три инструмента, которые вместе
+следят за качеством коммитов:
+
+- **commitlint** - проверяет, что сообщение коммита написано по
+  [Conventional Commits](https://www.conventionalcommits.org/) (`fix: ...`,
+  `feat: ...` и т.д.);
+- **lint-staged** - запускает линтеры и форматтеры только на файлах, попавших в
+  коммит;
+- **simple-git-hooks** - устанавливает сами хуки в `.git/hooks`.
+
+## Установка
+
+```bash
 npm i @alexlit/config-hooks -D
 ```
 
-## Connection
+## Подключение
+
+### 1. commitlint
 
-- commitlint
+```js
+// commitlint.config.js
+export default { extends: ['@alexlit/config-hooks/commitlint'] };
+```
+
+Коммит с сообщением не по Conventional Commits будет отклонён.
 
-  ```js
-  // commitlint.config.js
-  export default { extends: ['@alexlit/config-hooks/commitlint'] };
-  ```
+### 2. lint-staged
 
-- lint-staged
+```js
+// lint-staged.config.js
+import { defineConfig } from '@alexlit/config-hooks';
 
-  ```js
-  // lint-staged.config.js
-  import { createLintStagedConfig } from '@alexlit/config-hooks';
+export default defineConfig();
+```
 
-  export default createLintStagedConfig(
-    // optional plugins list
-    { stylelint: false },
+`defineConfig()` возвращает готовую карту «тип файла → команды»: при
+`git commit` к изменённым файлам применяются только подходящие линтеры
+(например, `.vue` - eslint + stylelint + prettier, `.md` - prettier +
+markdownlint). Ниже - [настройка](#настройка-lint-staged).
 
-    // optional config
-    {
-      '*.css': [], // disable existing rule
-      '*.yaml': ['echo "Hello, .yaml!"'], // custom rule
-    },
-  );
-  ```
+### 3. simple-git-hooks
 
-- simple-git-hooks
+Пропишите хуки в `package.json` и установите их:
 
-  ```json
-  // package.json
-  {
-    "scripts": { "prepare": "simple-git-hooks" },
-    "simple-git-hooks": {
-      "commit-msg": "npx commitlint --edit",
-      "pre-commit": "npx lint-staged"
-    }
+```json
+// package.json
+{
+  "scripts": { "prepare": "simple-git-hooks" },
+  "simple-git-hooks": {
+    "commit-msg": "npx commitlint --edit",
+    "pre-commit": "npx lint-staged"
   }
-  ```
+}
+```
+
+```bash
+git config --unset core.hooksPath || true
+rm -rf .git/hooks/*
+npx simple-git-hooks
+```
+
+Скрипт `prepare` установит хуки автоматически после `npm install`.
+
+## Настройка lint-staged
+
+У `defineConfig(plugins?, config?)` два необязательных аргумента.
+
+### Линтеры
+
+Первый аргумент - включает и выключает линтеры (по умолчанию включены все):
+
+| Линтер         | Команда                                             | Файлы                                                     |
+| -------------- | --------------------------------------------------- | --------------------------------------------------------- |
+| `eslint`       | `eslint --fix`                                      | `*.js`, `*.ts`, `*.jsx`, `*.tsx`, `*.vue`, `*.json` и др. |
+| `prettier`     | `prettier --write`                                  | почти все текстовые файлы                                 |
+| `stylelint`    | `stylelint --fix`                                   | `*.css`, `*.scss`, `*.sass`, `*.pcss`, `*.vue`            |
+| `htmllint`     | `linthtml`                                          | `*.html`                                                  |
+| `markdownlint` | `markdownlint --fix`                                | `*.md`                                                    |
+| `npmlint`      | `npmPkgJsonLint`                                    | `package.json`                                            |
+| `lockfilelint` | `lockfile-lint --type npm --path package-lock.json` | `package-lock.json`                                       |
+
+Выключенный линтер заменяется на `echo "... disabled"` - правило остаётся, но
+ничего не делает.
+
+```js
+// stylelint и htmllint выключены
+export default defineConfig({ stylelint: false, htmllint: false });
+```
+
+### Свои правила
+
+Второй аргумент - дополняет или переопределяет карту по паттернам:
+
+```js
+// lint-staged.config.js
+import { defineConfig } from '@alexlit/config-hooks';
+
+export default defineConfig(
+  // 1. линтеры
+  { stylelint: false },
+
+  // 2. правила по паттернам
+  {
+    '*.css': [], // пустой массив - отключить правило для css
+    '*.yaml': ['echo "Hello, .yaml!"'], // своя команда
+  },
+);
+```
+
+## Миграция v9 → v10
+
+v10 - breaking-релиз: функция переименована для консистентности с остальными
+пакетами `@alexlit/config-*` (`defineConfig` в `config-prettier`,
+`config-stylelint`).
+
+| v9                             | v10                  |
+| ------------------------------ | -------------------- |
+| `createLintStagedConfig()`     | `defineConfig()`     |
+| `createLintStagedConfig(a, b)` | `defineConfig(a, b)` |
+
+Аргументы и их поведение не изменились - достаточно заменить имя функции.
+
+## Полезные ссылки
 
-  ```sh
-  git config --unset core.hooksPath || true
-  rm -rf .git/hooks/*
-  npx simple-git-hooks
-  ```
+- [conventionalcommits](https://www.conventionalcommits.org/)
+- [commitlint](https://commitlint.org/)
+- [lint-staged](https://github.com/lint-staged/lint-staged)
+- [simple-git-hooks](https://github.com/typicode/simple-git-hooks)

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

@@ -0,0 +1,19 @@
+/** Флаги включения и выключения линтеров (по умолчанию включены все). */
+type LintersFlags = Record<string, boolean>;
+
+/** Карта «паттерн файла → команды». */
+type LintStagedRules = Record<string, string | string[]>;
+
+/**
+ * Создать конфигурацию lint-staged.
+ *
+ * @param plugins - Включение и выключение линтеров
+ * @param config - Свои правила по паттернам: дополняют или переопределяют карту
+ *   по умолчанию
+ */
+declare function defineConfig(
+  plugins?: LintersFlags,
+  config?: LintStagedRules,
+): LintStagedRules;
+
+export { defineConfig };

package/packages/config-hooks/lint-staged.js

@@ -1,12 +1,14 @@
 /**
- * Create lint-staged config
+ * Создать конфигурацию lint-staged.
  *
- * @param {Record<string, boolean>} plugins Enabled plugins
- * @param {Record<string, unknown>} config Users config
+ * @param {Record<string, boolean>} [plugins] - Включение и выключение линтеров
+ *   (по умолчанию включены все)
+ * @param {Record<string, unknown>} [config] - Свои правила по паттернам:
+ *   дополняют или переопределяют карту по умолчанию
  *
- * @returns {Record<string, unknown>} Lint-staged configuration
+ * @returns {Record<string, unknown>} Карта «паттерн файла → команды»
  */
-const createLintStagedConfig = (plugins = {}, config = {}) => {
+const defineConfig = (plugins = {}, config = {}) => {
   const pluginsList = {
     eslint: true,
     htmllint: true,
@@ -83,4 +85,4 @@ const createLintStagedConfig = (plugins = {}, config = {}) => {
   };
 };
 
-export { createLintStagedConfig };
+export { defineConfig };

package/packages/config-hooks/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alexlit/config-hooks",
-  "version": "9.1.1",
+  "version": "10.0.0",
   "private": false,
   "description": "Hooks config",
   "keywords": [
@@ -23,9 +23,11 @@
   ],
   "type": "module",
   "main": "lint-staged.js",
+  "types": "index.d.ts",
   "files": [
     "README.md",
     "commitlint.js",
+    "index.d.ts",
     "lint-staged.js"
   ],
   "scripts": {

package/packages/config-htmllint/README.md

@@ -1,38 +1,66 @@
 # HTMLLint Configuration
 
-## Installation
+[![version](https://npmx.dev/api/registry/badge/version/@alexlit/config-htmllint)](https://www.npmjs.com/package/@alexlit/config-htmllint)
+[![downloads](https://npmx.dev/api/registry/badge/downloads/@alexlit/config-htmllint)](https://npmx.dev/package/@alexlit/config-htmllint)
+[![license](https://npmx.dev/api/registry/badge/license/@alexlit/config-htmllint)](LICENSE)
 
-```sh
+Готовая конфигурация [linthtml](https://github.com/linthtml/linthtml) - линтера
+HTML-разметки. Пакет объединяет рекомендованный базовый конфиг
+`@linthtml/linthtml-config-recommended` с дополнительными правилами (в том числе
+проверками доступности и стиля разметки), чтобы подключить линтер одной строкой
+и не держать сотни строк настроек в каждом проекте.
+
+## Установка
+
+```bash
 npm i @alexlit/config-htmllint -D
 ```
 
-## Connection
+## Быстрый старт
+
+```js
+// linthtml.config.js
+import { defineConfig } from '@alexlit/config-htmllint';
 
-- Default
-  ([see rules enabled by default](https://github.com/alex-lit/lint-kit/blob/master/packages/config-htmllint/index.js))
+export default defineConfig();
+```
+
+Готово: подключены рекомендованный конфиг, правила пакета и дефолтные опции
+линтера.
 
-  ```js
-  // linthtml.config.js
-  import { createConfig } from '@alexlit/config-htmllint';
+## Настройка
 
-  export default createConfig();
-  ```
+Аргумент `options` накладывается поверх значений по умолчанию: `rules` - shallow
+merge, `extends` и `ignoreFiles` - конкатенация.
 
-- Custom
+```js
+// linthtml.config.js
+import { defineConfig } from '@alexlit/config-htmllint';
 
-  ```js
-  // linthtml.config.js
-  import { createConfig } from '@alexlit/config-htmllint';
+export default defineConfig({
+  'line-max-len-ignore-regex': false,
 
-  export default createConfig({
-    'attr-name-ignore-regex': false,
+  'rules': { 'indent-width': [true, 4], 'title-max-len': [true, 60] },
+});
+```
 
-    rules: {
-      'indent-width': [true, 4],
-    },
-  });
-  ```
+## Миграция v1 → v2
 
-## VSCode extention
+v2 - breaking-релиз: функция переименована для консистентности с остальными
+пакетами `@alexlit/config-*`.
+
+| v1                   | v2                   |
+| -------------------- | -------------------- |
+| `createConfig()`     | `defineConfig()`     |
+| `createConfig(opts)` | `defineConfig(opts)` |
+
+Аргументы и их поведение не изменились - достаточно заменить имя функции.
+
+## Расширение для VSCode
 
 [vscode-linthtml](https://marketplace.visualstudio.com/items?itemName=kamikillerto.vscode-linthtml)
+
+## Полезные ссылки
+
+- [linthtml](https://github.com/linthtml/linthtml)
+- [linthtml-config-recommended](https://github.com/linthtml/linthtml-config-recommended)

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

@@ -0,0 +1,13 @@
+import type { Config } from '@linthtml/linthtml';
+
+/**
+ * Создать конфигурацию linthtml.
+ *
+ * База (расширяется рекомендованным конфигом):
+ * `@linthtml/linthtml-config-recommended` плюс дефолтные опции линтера и
+ * правила. Всё, что передано в `options`, накладывается поверх базы; `extends`
+ * и `ignoreFiles` конкатенируются, `rules` - shallow merge.
+ *
+ * @param options - Опции linthtml, накладываемые поверх значений по умолчанию
+ */
+export declare function defineConfig(options?: Config): Config;

package/packages/config-htmllint/index.js

@@ -1,26 +1,34 @@
 /**
- * Create linthtml config
+ * Создать конфигурацию linthtml.
  *
- * @param options LintHTML options
+ * База (расширяется рекомендованным конфигом):
+ * `@linthtml/linthtml-config-recommended` плюс дефолтные опции линтера и
+ * правила ниже. Всё, что передано в `options`, накладывается поверх базы;
+ * `extends` и `ignoreFiles` конкатенируются, `rules` - shallow merge.
+ *
+ * @param {import('@linthtml/linthtml').Config} [options] - Опции linthtml,
+ *   накладываемые поверх значений по умолчанию
+ *
+ * @returns {import('@linthtml/linthtml').Config}
  *
  * @see [linthtml](https://github.com/linthtml/linthtml)
  */
-export const createConfig = (options = {}) => ({
+export const defineConfig = (options = {}) => ({
   'attr-name-ignore-regex': false,
   'id-class-ignore-regex': false,
   'line-max-len-ignore-regex': false,
-  maxerr: false,
+  'maxerr': false,
   'raw-ignore-regex': false,
   'spec-char-escape': false,
   'text-ignore-regex': false,
   ...options,
-  extends: [
+  'extends': [
     '@linthtml/linthtml-config-recommended',
 
     ...(options.extends ?? []),
   ],
-  ignoreFiles: [...(options.rules ?? [])],
-  rules: {
+  'ignoreFiles': [...(options.ignoreFiles ?? [])],
+  'rules': {
     'attr-order': [true, ['id', 'class']],
     'attr-quote-style': [true, 'double'],
     'button-req-content': true,

package/packages/config-htmllint/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alexlit/config-htmllint",
-  "version": "1.3.2",
+  "version": "2.0.0",
   "private": false,
   "description": "htmllint config",
   "keywords": [
@@ -25,9 +25,11 @@
   ],
   "type": "module",
   "main": "index.js",
+  "types": "index.d.ts",
   "files": [
     "README.md",
-    "index.js"
+    "index.js",
+    "index.d.ts"
   ],
   "scripts": {
     "lint": "cd ../../ && ./scripts/lint.htmllint.sh",

package/packages/config-markdownlint/README.md

@@ -1,16 +1,51 @@
-# MarkdownLint Configuration
+# Markdownlint Configuration
 
-## Installation
+[![npm version](https://npmx.dev/api/registry/badge/version/@alexlit/config-markdownlint)](https://www.npmjs.com/package/@alexlit/config-markdownlint)
+[![downloads](https://npmx.dev/api/registry/badge/downloads/@alexlit/config-markdownlint)](https://npmx.dev/package/@alexlit/config-markdownlint)
+[![license](https://npmx.dev/api/registry/badge/license/@alexlit/config-markdownlint)](LICENSE)
 
-```sh
+Готовый набор правил
+[markdownlint](https://github.com/DavidAnson/markdownlint) - линтера
+Markdown-файлов. Пакет подключается одной строкой через `extends`, чтобы не
+держать конфигурацию в каждом проекте отдельно: включены все правила линтера по
+умолчанию, сняты спорные ограничения (длина строки, HTML) и зафиксирован стиль
+код-блоков и списков.
+
+Формат пакета - JSON: это конвенция markdownlint-cli, которая загружает конфиги
+только в форматах JSON/YAML и не поддерживает JS-конфиги.
+
+## Установка
+
+```bash
 npm i @alexlit/config-markdownlint -D
 ```
 
-## Connection
+## Быстрый старт
+
+```json
+// .markdownlint.json
+{ "extends": "@alexlit/config-markdownlint" }
+```
+
+Готово: линтер работает с набором правил пакета.
+
+## Настройка
+
+Перечислите нужные правила в своём `.markdownlint.json` - собственные ключи
+перекрывают одноимённые правила из `extends`.
 
 ```json
 // .markdownlint.json
 {
-  "extends": "@alexlit/config-markdownlint"
+  "extends": "@alexlit/config-markdownlint",
+
+  "no-inline-html": true,
+  "ul-style": { "style": "asterisk" }
 }
 ```
+
+## Полезные ссылки
+
+- [markdownlint](https://github.com/DavidAnson/markdownlint)
+- [Список правил](https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md)
+- [markdownlint-cli](https://github.com/igorshubovych/markdownlint-cli)

package/packages/config-markdownlint/index.json

@@ -3,14 +3,12 @@
   "code-fence-style": { "style": "backtick" },
   "default": true,
   "first-line-heading": false,
-
   "line-length": {
     "code_blocks": false,
     "headings": false,
     "strict": false,
     "tables": false
   },
-
   "no-inline-html": false,
   "ol-prefix": { "style": "ordered" },
   "ul-style": { "style": "dash" }

package/packages/config-markdownlint/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alexlit/config-markdownlint",
-  "version": "2.27.0",
+  "version": "2.27.1",
   "private": false,
   "description": "markdownlint config",
   "keywords": [

package/packages/config-npmlint/README.md

@@ -1,18 +1,61 @@
 # NPMLint Configuration
 
-[npm-package-json-lint](https://github.com/tclindner/npm-package-json-lint)
+[![version](https://npmx.dev/api/registry/badge/version/@alexlit/config-npmlint)](https://www.npmjs.com/package/@alexlit/config-npmlint)
+[![downloads](https://npmx.dev/api/registry/badge/downloads/@alexlit/config-npmlint)](https://npmx.dev/package/@alexlit/config-npmlint)
+[![license](https://npmx.dev/api/registry/badge/license/@alexlit/config-npmlint)](LICENSE)
 
-## Installation
+Готовая конфигурация
+[npm-package-json-lint](https://github.com/tclindner/npm-package-json-lint) -
+линтера `package.json` файлов. Пакет собирает рекомендованный базовый конфиг
+`npm-package-json-lint-config-default` (обязательные `name` и `version`,
+корректный формат имени и версии, типы всех разделов манифеста) и подключается
+одной строкой через `extends`, чтобы не держать конфигурацию в каждом проекте
+отдельно.
 
-```sh
+Формат пакета - JSON: это конвенция npm-package-json-lint, которая загружает
+конфиги только в форматах JSON/YAML и не поддерживает JS-конфиги.
+
+## Установка
+
+```bash
 npm i @alexlit/config-npmlint -D
 ```
 
-## Connection
+## Быстрый старт
+
+```json
+// .npmpackagejsonlintrc.json
+{ "extends": "@alexlit/config-npmlint" }
+```
+
+Готово: линтер работает с набором правил пакета.
+
+## Настройка
+
+Перечислите нужные правила в своём `.npmpackagejsonlintrc.json` - собственные
+ключи перекрывают одноимённые правила из `extends`. Значение правила: `"error"`,
+`"warning"` или `"off"`.
 
 ```json
 // .npmpackagejsonlintrc.json
 {
-  "extends": "@alexlit/config-npmlint"
+  "extends": "@alexlit/config-npmlint",
+
+  "rules": { "keywords-type": "warning", "require-version": "off" }
 }
 ```
+
+Ошибку можно не снять, а ослабить - замените `"error"` на `"warning"`, чтобы
+проблема не ломала сборку.
+
+Кроме `package.json` пакет умеет проверять `package-lock.json` через
+[lockfile-lint](https://github.com/lirantal/lockfile-lint) - бинарь уже входит в
+зависимости пакета.
+
+## Полезные ссылки
+
+- [npm-package-json-lint](https://github.com/tclindner/npm-package-json-lint)
+- [Список правил](https://npmpackagejsonlint.org/docs/rules)
+- [Конфигурация](https://npmpackagejsonlint.org/docs/configuration)
+- [npm-package-json-lint-config-default](https://github.com/tclindner/npm-package-json-lint-config-default)
+- [lockfile-lint](https://github.com/lirantal/lockfile-lint)

package/packages/config-npmlint/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alexlit/config-npmlint",
-  "version": "10.1.0",
+  "version": "10.1.1",
   "private": false,
   "description": "npmlint config",
   "keywords": [
@@ -8,8 +8,8 @@
     "json",
     "lint",
     "npm",
-    "package",
-    "npmlint"
+    "npm-package-json-lint",
+    "package"
   ],
   "homepage": "https://github.com/alex-lit/lint-kit/tree/master/packages/config-npmlint#readme",
   "bugs": {