Использование API в скриптах и инструментах

ESLint предоставляет программный API, позволяющий использовать механизм линтинга вне командной строки — в скриптах, сборщиках, CI-инструментах и собственных утилитах анализа кода. Основная точка входа — класс ESLint, доступный из пакета eslint.

Создание экземпляра линтера

Работа с API начинается с инициализации экземпляра:

import { ESLint } from "eslint";

const eslint = new ESLint({
  cwd: process.cwd(),
  overrideConfigFile: true,
  fix: false,
});

Ключевые параметры конфигурации:

  • cwd — базовая директория анализа проекта
  • overrideConfigFile — явное указание конфигурации (или отключение автопоиска)
  • fix — автоматическое исправление ошибок при линтинге
  • cache — включение кеширования результатов для ускорения повторных запусков
  • ignore — управление применением .eslintignore

При использовании flat config (ESLint 9+) конфигурация передаётся через overrideConfig или загружается автоматически из eslint.config.js.

Линтинг файлов

Основной метод анализа файлов:

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

Метод принимает:

  • одиночные пути
  • glob-шаблоны
  • массивы путей

Возвращаемый результат — массив объектов LintResult, содержащих:

  • путь к файлу
  • массив сообщений об ошибках и предупреждениях
  • статистику (количество ошибок, предупреждений)
  • информацию о применённых фикcах

Пример обработки результатов:

for (const result of results) {
  console.log(result.filePath);

  for (const message of result.messages) {
    console.log(`${message.line}:${message.column} ${message.message}`);
  }
}

Линтинг строкового кода

Для анализа кода без файловой системы используется lintText:

const code = `
const a = 1
console.log(a)
`;

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

filePath важен, поскольку ESLint применяет правила в зависимости от расширения файла и контекста конфигурации.

Автоматическое исправление

ESLint способен модифицировать исходный код:

const eslint = new ESLint({ fix: true });

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

await ESLint.outputFixes(results);

Метод outputFixes записывает изменения обратно в файловую систему. Каждый LintResult содержит поле output, если исправления применимы.

Форматирование результатов

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

const formatter = await eslint.loadFormatter("stylish");
const resultText = formatter.format(results);

console.log(resultText);

Популярные встроенные форматтеры:

  • stylish — человекочитаемый вывод
  • json — структурированные данные
  • compact — краткий формат для CI
  • html — отчёты в виде HTML

Создание собственного форматтера возможно через функцию, принимающую массив результатов.

Работа с результатами в CI-инструментах

ESLint API часто используется в системах непрерывной интеграции для контроля качества кода:

const eslint = new ESLint({ fix: false });

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

const formatter = await eslint.loadFormatter("json");
const output = formatter.format(results);

process.stdout.write(output);

const hasErrors = results.some(
  (r) => r.errorCount > 0
);

process.exitCode = hasErrors ? 1 : 0;

Такая схема позволяет:

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

Кеширование результатов

Для ускорения повторного анализа больших проектов используется кеш:

const eslint = new ESLint({
  cache: true,
  cacheLocation: ".eslintcache",
});

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

Исключения и фильтрация файлов

Игнорирование файлов управляется несколькими уровнями:

  • .eslintignore (legacy режим)
  • поле ignores в flat config
  • параметр ignorePatterns

Пример:

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

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

Доступ к информации о правилах

ESLint API позволяет получать метаданные правил:

const rules = eslint.getRules();

for (const [name, rule] of rules) {
  console.log(name, rule.meta);
}

Это используется для:

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

Параллельный и пакетный анализ

При работе с большими кодовыми базами ESLint эффективно обрабатывает набор файлов:

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

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

Интеграция с инструментами сборки

ESLint API часто включается в пайплайны сборщиков:

export default {
  build: async () => {
    const eslint = new ESLint({ fix: true });

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

    await ESLint.outputFixes(results);
  },
};

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

Обработка ошибок выполнения

Ошибки API могут возникать при:

  • неверной конфигурации
  • отсутствии файлов
  • ошибках парсинга кода
  • несовместимости плагинов
try {
  await eslint.lintFiles(["src"]);
} catch (error) {
  console.error(error.message);
}

Объекты ошибок обычно содержат стек вызовов и контекст конфигурации, что упрощает диагностику проблем в сложных проектах.

Оглавление