ESLint предоставляет программный API поверх собственного ядра линтинга, где центральным элементом выступает объект, инкапсулирующий процесс анализа кода, загрузку конфигураций, применение правил и форматирование результатов. Этот объект служит точкой входа для интеграции линтера в сборочные системы, тестовые окружения и пользовательские инструменты автоматизации.
Основная логика работы строится вокруг создания экземпляра, который конфигурируется параметрами окружения, путями к конфигурационным файлам и набором правил. Внутри реализуется пайплайн: загрузка конфигурации → разрешение плагинов → анализ файлов → формирование отчёта → применение форматтера.
Создание экземпляра осуществляется через конструктор, который принимает объект конфигурации. Этот объект определяет поведение линтера на уровне проекта.
Ключевые параметры:
Внутренне экземпляр сохраняет состояние окружения и использует его при каждом запуске линтинга, что позволяет повторно использовать тяжёлые ресурсы: загруженные правила, резолверы и конфигурации.
Центральной функцией является метод анализа файлов, который принимает набор путей и возвращает структурированный отчёт о найденных проблемах.
Процесс работы включает:
Метод возвращает массив отчётов, где каждый элемент соответствует одному файлу и содержит:
Типовая структура результата:
[
{
filePath: "src/index.js",
messages: [
{
ruleId: "no-unused-vars",
severity: 2,
message: "'x' is defined but never used",
line: 3,
column: 5
}
],
errorCount: 1,
warningCount: 0
}
]Отдельный режим работы предназначен для анализа фрагментов кода, не привязанных к файловой системе. Он используется в редакторах кода, интерактивных окружениях и тестовых раннерах.
Метод принимает:
Особенность данного режима заключается в том, что он не выполняет файловый резолвинг, но сохраняет полноценную систему правил и парсинга.
Экземпляр ESLint обладает встроенным механизмом загрузки конфигурации, который поддерживает несколько источников:
Приоритет конфигурации определяется следующим образом:
Разрешение конфигурации выполняется один раз для каждой области файлов, после чего результат кешируется внутри экземпляра.
Экземпляр предоставляет механизм загрузки форматтера, преобразующего внутреннюю структуру результатов в человекочитаемый формат.
Форматтеры могут быть:
Процесс форматирования включает:
Пример логики использования:
const eslint = new ESLint();
const results = await eslint.lintFiles(["src/**/*.js"]);
const formatter = await eslint.loadFormatter("stylish");
const output = formatter.format(results);Встроенная система фиксов позволяет модифицировать исходный код на основе правил, поддерживающих автоматическое исправление.
Механизм работы:
Поддерживаются два режима:
Результат содержит дополнительное поле output, где
находится исправленный код.
Для повышения производительности используется кэширование. Оно особенно важно при анализе больших проектов.
Кэш хранит:
При повторном запуске система сравнивает хеши и пропускает анализ неизменённых файлов.
Кэш может быть:
Экземпляр поддерживает динамическое подключение плагинов, расширяющих функциональность линтера.
Плагины могут содержать:
Резолвинг плагинов осуществляется через Node.js-механизм модулей, с
учётом текущего рабочего каталога и параметров cwd.
При загрузке происходит:
Ошибки в процессе анализа делятся на несколько категорий:
Каждое сообщение содержит:
Эта структура унифицирована, что позволяет одинаково обрабатывать результаты в редакторах и CI-системах.
Работа с файлами осуществляется через стандартные механизмы Node.js, но дополнительно поддерживается:
Разрешение путей происходит относительно cwd, что
позволяет переносить конфигурации между окружениями без изменений.
Полный цикл обработки одного файла включает последовательность этапов:
Каждый этап изолирован и может быть расширен через плагины или кастомные парсеры.
Экземпляр рассчитан на использование в асинхронной среде. Основные операции возвращают Promise, что позволяет:
При этом внутреннее состояние экземпляра не предполагает конкурентной модификации конфигурации во время выполнения анализа, что обеспечивает предсказуемость результатов.
Каждое правило может иметь зависимости:
Разрешение зависимостей происходит при инициализации конфигурации. В случае конфликтов приоритет определяется локальностью конфигурации и порядком подключения расширений.
Результат работы экземпляра представляет собой нормализованный набор данных, пригодный для дальнейшей обработки.
Он включает:
Эта структура служит основой для построения интерфейсов анализа кода, отчётных систем и интеграций с CI/CD пайплайнами.