Загрузка конфигурации программно

Архитектура конфигурации в программном режиме

ESLint предоставляет возможность работы не только через CLI и конфигурационные файлы, но и через программный API. В этом режиме конфигурация формируется динамически и передаётся в экземпляр линтера напрямую, что позволяет интегрировать анализ кода в сложные пайплайны сборки, тестирования и серверные процессы.

Ключевым объектом программного интерфейса является класс ESLint, предоставляемый пакетом eslint. Он инкапсулирует механизм разрешения конфигурации, загрузки плагинов, применения правил и выполнения анализа файлов или строкового кода.

import { ESLint } from "eslint";

Внутри экземпляра происходит построение конфигурационного дерева, которое может включать:

  • базовые конфигурации (base config)
  • расширения (extends)
  • плагины (plugins)
  • переопределения (overrides)
  • игнорирование (ignorePatterns)
  • пользовательские правила

Создание экземпляра ESLint с конфигурацией

Программная конфигурация может быть задана непосредственно при создании экземпляра ESLint.

import { ESLint } from "eslint";

const eslint = new ESLint({
  overrideConfig: {
    rules: {
      semi: ["error", "always"],
      quotes: ["error", "single"]
    }
  }
});

Параметр overrideConfig имеет наивысший приоритет и перекрывает конфигурации из файлов .eslintrc, если они используются в проекте.

Основные параметры конструктора:

  • cwd — базовая директория для поиска конфигураций
  • overrideConfig — конфигурация, заданная программно
  • overrideConfigFile — путь к альтернативному конфигурационному файлу
  • useEslintrc — включение/отключение загрузки .eslintrc
  • fix — автоматическое исправление ошибок
  • ignore — игнорирование стандартных .eslintignore

Загрузка файловой конфигурации программно

ESLint способен автоматически подхватывать конфигурационные файлы из файловой системы. При создании экземпляра без overrideConfig используется стандартный механизм разрешения:

const eslint = new ESLint({
  cwd: process.cwd()
});

В этом случае выполняется поиск конфигурации в следующем порядке:

  • eslint.config.js (Flat Config)
  • .eslintrc.js, .eslintrc.cjs, .eslintrc.json
  • поля eslintConfig в package.json

Если используется Flat Config (eslint.config.js), загрузка происходит через новый конфигурационный движок, основанный на массиве конфигураций.

Программная загрузка Flat Config

Flat Config представляет собой массив конфигурационных объектов, которые могут быть переданы напрямую в overrideConfig.

const eslint = new ESLint({
  overrideConfig: [
    {
      files: ["**/*.js"],
      rules: {
        "no-console": "warn"
      }
    },
    {
      files: ["**/*.test.js"],
      rules: {
        "no-console": "off"
      }
    }
  ]
});

Каждый элемент массива представляет слой конфигурации, применяемый последовательно.

Flat Config позволяет отказаться от глубокого наследования extends, заменяя его композиционной моделью.

Динамическое формирование конфигурации

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

import { ESLint } from "eslint";

const isProduction = process.env.NODE_ENV === "production";

const eslint = new ESLint({
  overrideConfig: {
    rules: {
      "no-debugger": isProduction ? "error" : "off",
      "no-console": isProduction ? "error" : "warn"
    }
  }
});

Такой подход позволяет формировать контекстно-зависимую конфигурацию без изменения файлов проекта.

Отключение загрузки файловой конфигурации

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

const eslint = new ESLint({
  useEslintrc: false,
  overrideConfig: {
    rules: {
      eqeqeq: "error"
    }
  }
});

В этом режиме игнорируются все .eslintrc и package.json конфигурации, используется только объект overrideConfig.

Переопределение конфигурации через overrideConfigFile

Параметр overrideConfigFile позволяет явно указать альтернативный конфигурационный файл, который будет иметь приоритет над стандартным поиском.

const eslint = new ESLint({
  overrideConfigFile: "./config/eslint.custom.config.js"
});

Такой механизм применяется при необходимости централизованного управления конфигурацией вне стандартной структуры проекта.

Программная загрузка и анализ файлов

После создания экземпляра конфигурация становится частью внутреннего состояния линтера. Основной метод анализа — lintFiles.

const results = await eslint.lintFiles(["src/**/*.js"]);

Процесс включает:

  • разрешение конфигурации для каждого файла
  • применение правил
  • выполнение парсинга AST
  • формирование отчёта

Результат представляет собой массив объектов с детальной информацией о нарушениях.

Анализ строкового кода с конфигурацией

ESLint поддерживает анализ кода без файловой системы через lintText.

const code = "const a = 1";

const results = await eslint.lintText(code, {
  filePath: "virtual.js"
});

Параметр filePath используется для:

  • определения применимых правил по расширению
  • выбора конфигурации через overrides
  • корректного применения parserOptions

Управление текущей рабочей директорией

Контекст разрешения конфигурации зависит от параметра cwd.

const eslint = new ESLint({
  cwd: "/project/root"
});

Этот параметр влияет на:

  • поиск конфигурационных файлов
  • разрешение плагинов
  • интерпретацию относительных путей
  • работу с extends

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

Автоматическое исправление ошибок включается через fix.

const eslint = new ESLint({
  fix: true,
  overrideConfig: {
    rules: {
      semi: ["error", "always"]
    }
  }
});

После анализа требуется дополнительный шаг для сохранения исправлений:

const results = await eslint.lintFiles(["src/**/*.js"]);

await ESLint.outputFixes(results);

Игнорирование и фильтрация файлов

ESLint поддерживает игнорирование файлов на уровне конфигурации и конструктора.

const eslint = new ESLint({
  ignore: true,
  overrideConfig: {
    ignorePatterns: ["dist/", "node_modules/"]
  }
});

Игнорирование может быть:

  • глобальным (ignore)
  • конфигурационным (ignorePatterns)
  • файловым (.eslintignore)

Интеграция с плагинами при программной загрузке

Плагины могут передаваться через overrideConfig.plugins при условии, что они уже импортированы или доступны через node resolution.

import pluginJs from "@eslint/js";

const eslint = new ESLint({
  overrideConfig: {
    plugins: {
      js: pluginJs
    },
    rules: {
      "js/no-undef": "error"
    }
  }
});

В Flat Config плагин обычно передаётся как объект с набором правил и конфигураций.

Обработка нескольких конфигурационных слоёв

При программной загрузке конфигурации ESLint объединяет слои в следующем порядке приоритета:

  1. overrideConfig (наивысший приоритет)
  2. overrideConfigFile
  3. Flat Config (eslint.config.js)
  4. .eslintrc*
  5. конфигурации по умолчанию

Конфликты правил разрешаются по принципу последнего применённого значения.

Кэширование и производительность загрузки конфигурации

Внутри ESLint реализовано кэширование:

  • загруженных конфигураций
  • разрешённых плагинов
  • вычисленных override-цепочек

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

Использование нескольких экземпляров ESLint

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

const base = new ESLint({
  overrideConfig: { rules: { semi: "error" } }
});

const strict = new ESLint({
  overrideConfig: { rules: { semi: "error", "no-console": "error" } }
});

Каждый экземпляр строит собственное конфигурационное дерево и не разделяет внутреннее состояние.

Детерминированность конфигурации при программной загрузке

При корректной настройке cwd, overrideConfig и отключении побочных источников конфигурации достигается детерминированное поведение линтера. Это критично для CI/CD систем, где требуется воспроизводимый результат анализа независимо от локального окружения разработчика.

Расширенные сценарии динамической загрузки

Конфигурация может формироваться на основе внешних данных:

  • результатов анализа зависимостей
  • типов сборки (development / production)
  • версий ECMAScript
  • типов окружения (browser / node)
function createESLint(env) {
  return new ESLint({
    useEslintrc: false,
    overrideConfig: {
      env: {
        node: env === "node",
        browser: env === "browser"
      },
      rules: {
        "no-var": env === "production" ? "error" : "warn"
      }
    }
  });
}

Особенности разрешения конфигурации в Flat Config

Flat Config использует линейную модель обработки:

  • конфигурации применяются сверху вниз
  • каждый файл сопоставляется с набором files/ignores
  • наследование заменяется композицией

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

Контроль поведения линтера через конфигурационный API

Программная загрузка конфигурации делает ESLint частью прикладной логики приложения. Конфигурация становится вычисляемым объектом, а не статическим файлом, что позволяет встроить линтер в системы:

  • сборки модульных приложений
  • серверные валидаторы кода
  • инструменты автоматического рефакторинга
  • системы проверки качества кода в runtime
Оглавление