Флаг --inspect-config

Назначение флага --inspect-config заключается в отображении итоговой конфигурации ESLint для конкретного файла или набора файлов после применения всех механизмов объединения: наследования, переопределений, подключённых плагинов и внутренних правил разрешения конфигурации. Этот режим используется как инструмент диагностики, позволяющий точно определить, какая конфигурация фактически применяется к анализируемому коду.

Флаг особенно важен в средах, где конфигурация ESLint формируется из нескольких источников: базовых конфигов, расширений (extends), локальных переопределений (overrides), плагинов и нового flat config-подхода.

При запуске ESLint с --inspect-config происходит полное построение финальной конфигурации для указанного контекста. В отличие от обычного запуска линтера, где результатом являются ошибки и предупреждения, данный режим фокусируется исключительно на конфигурации.

Ключевая задача режима:

  • показать итоговую конфигурацию после всех преобразований;
  • отобразить фактический набор правил и их состояния;
  • выявить источник конкретного правила или настройки;
  • упростить диагностику конфликтов между конфигурациями.

Базовый синтаксис

Типовой формат использования:

eslint --inspect-config path/to/file.js

В некоторых версиях ESLint также допускаются дополнительные параметры:

eslint --inspect-config path/to/file.js --format json

или вывод в файл:

eslint --inspect-config path/to/file.js > config.json

Процесс формирования итоговой конфигурации

Перед формированием вывода ESLint проходит несколько этапов:

1. Определение конфигурационного контекста

Система определяет:

  • путь к файлу;
  • тип проекта (ESM / CommonJS);
  • наличие flat config (eslint.config.js) или legacy (.eslintrc).

2. Сбор конфигурационных источников

Собираются все доступные источники:

  • локальные .eslintrc.*;
  • секции overrides;
  • конфигурации из extends;
  • плагины (plugins);
  • встроенные пресеты.

3. Нормализация конфигурации

Все источники приводятся к единому формату:

  • объединяются правила (rules);
  • разрешаются конфликты приоритетов;
  • вычисляются финальные значения параметров.

4. Применение файловых переопределений

Если используются overrides, они применяются строго по совпадению glob-паттернов, что может полностью изменить итоговый набор правил для конкретного файла.

Структура выводимой конфигурации

Результатом выполнения является JSON-структура, содержащая полностью развернутую конфигурацию.

Основные секции:

rules

Содержит финальный набор правил ESLint:

"rules": {
  "no-unused-vars": "error",
  "eqeqeq": ["error", "always"]
}

Здесь отражаются:

  • уровень строгости (off, warn, error);
  • дополнительные параметры правила;
  • результат объединения конфликтующих конфигураций.

languageOptions

Определяет параметры разбора кода:

  • версия ECMAScript;
  • тип модулей;
  • глобальные переменные;
  • парсер.

Пример:

"languageOptions": {
  "ecmaVersion": 2022,
  "sourceType": "module"
}

plugins

Список подключённых плагинов после разрешения зависимостей:

"plugins": {
  "react": {}
}

settings

Глобальные настройки, используемые плагинами:

"settings": {
  "react": {
    "version": "detect"
  }
}

Flat config и legacy конфигурации

Legacy подход

В старой системе конфигурации (.eslintrc) применяется каскадное наследование:

  • .eslintrc
  • .eslintrc.json
  • .eslintrc.js
  • extends

При инспекции отображается уже результат объединения всех слоёв.

Flat config

В современном подходе (eslint.config.js) структура становится линейной:

  • массив конфигурационных объектов;
  • явное управление порядком применения;
  • отсутствие скрытого наследования.

При использовании --inspect-config flat-конфигурация отображается как уже нормализованный список блоков, применённых к файлу.

Наследование и механизм extends

Механизм extends является одним из наиболее частых источников сложностей.

При инспекции видно:

  • какие конфигурации были расширены;
  • в каком порядке они применялись;
  • какие правила были перезаписаны.

Пример типичной цепочки:

"extends": [
  "eslint:recommended",
  "plugin:react/recommended"
]

После обработки результат может существенно отличаться от исходных пресетов.

Overrides и файловые контексты

overrides позволяют задавать разные правила для разных типов файлов.

Пример логики:

  • *.js → базовые правила
  • *.test.js → отключение строгих проверок
  • *.ts → подключение TypeScript-правил

В режиме инспекции видно:

  • какой override сработал;
  • какие правила были заменены;
  • итоговое состояние после применения.

Подключение плагинов и разрешение зависимостей

Плагины проходят этап резолва:

  • поиск пакета в node_modules;
  • загрузка экспортируемых правил;
  • регистрация namespace правил.

В инспектируемой конфигурации отображается уже конечное состояние, без промежуточных импортов.

Диагностика конфликтов конфигурации

Флаг используется для выявления проблем:

Перекрытие правил

Когда одно и то же правило задаётся в разных местах:

  • базовая конфигурация;
  • plugin config;
  • override.

Итоговое значение может быть неожиданным.

Потеря правил

Часто происходит при:

  • неправильном порядке extends;
  • переопределении rules: {} без учета базовых значений.

Несовместимость плагинов

Иногда плагины требуют определённые версии parser или languageOptions, что становится видно только в финальной конфигурации.

Типичные сценарии использования инспекции

Проверка итогового уровня строгости

Позволяет увидеть, какие правила реально активны:

  • включены ли recommended-наборы;
  • не были ли они случайно отключены.

Анализ неожиданного поведения линтера

Если ESLint не сообщает об ошибках там, где ожидается, инспекция показывает:

  • отключено ли правило;
  • переопределено ли оно;
  • применяется ли override.

Проверка конфигурации перед миграцией

При переходе:

  • с legacy на flat config;
  • между версиями ESLint;
  • между наборами правил.

Отличие от print-config

Ранее использовался --print-config, который выполнял похожую задачу, но:

  • имел менее структурированный вывод;
  • хуже отображал внутренние источники;
  • не учитывал новые механизмы flat config.

--inspect-config ориентирован на более точное отображение финального состояния после полной обработки всех уровней конфигурации.

Особенности интерпретации результата

При анализе вывода важно учитывать:

  • результат уже является «финальной точкой» вычислений;
  • исходные конфиги могут быть частично потеряны в агрегированном виде;
  • порядок правил отражает приоритеты, а не порядок объявления.

Внутренние уровни приоритета конфигурации

Общая иерархия применения:

  1. встроенные значения ESLint;
  2. базовые конфигурации;
  3. extends;
  4. плагины;
  5. overrides;
  6. локальные inline-настройки.

Итоговая инспекция показывает результат применения всех уровней одновременно, без разделения на источники в большинстве случаев, но с сохранением ключевых маркеров происхождения.

Оглавление