Метод lintFiles и lintText

Метод lintFiles в классе ESLint предназначен для анализа файловых наборов, заданных через пути, glob-шаблоны или массивы путей. Он выполняет полноценный процесс линтинга на основе конфигурации ESLint, включая загрузку правил, плагинов и парсеров, а также применение игнорирования (.eslintignore или ignores в flat config).

Сигнатура

eslint.lintFiles(patterns)
  • patterns — string | string[] Представляет путь к файлу, директории или glob-выражение.

Поведение метода

При вызове lintFiles происходит:

  • разрешение путей и glob-шаблонов;
  • сбор файлов, подходящих под конфигурацию игнорирования;
  • применение правил ESLint к каждому файлу;
  • формирование массива результатов линтинга.

Метод работает асинхронно и возвращает Promise.

Возвращаемое значение

Promise<LintResult[]>

Каждый элемент массива представляет результат анализа одного файла:

type LintResult = {
  filePath: string;
  messages: LintMessage[];
  errorCount: number;
  warningCount: number;
  fixableErrorCount: number;
  fixableWarningCount: number;
  source?: string;
  output?: string;
};

Структура сообщений

type LintMessage = {
  ruleId: string | null;
  severity: 1 | 2;
  message: string;
  line: number;
  column: number;
  endLine?: number;
  endColumn?: number;
  fix?: {
    range: [number, number];
    text: string;
  };
};

Пример использования

import { ESLint } from "eslint";

const eslint = new ESLint();

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

results.forEach(result => {
  console.log(result.filePath);
  console.log(result.errorCount, result.warningCount);
});

Особенности работы

  • Поддерживается параллельная обработка файлов внутри ESLint.
  • Игнорируемые файлы исключаются до анализа.
  • При включённой опции fix: true ESLint возвращает изменённый код в поле output.
const eslint = new ESLint({ fix: true });
const results = await eslint.lintFiles(["src"]);

Метод lintText

Метод lintText используется для анализа строкового содержимого без привязки к файловой системе. Он применяется в случаях, когда код существует в памяти: редакторы, виртуальные файлы, CI-пайплайны, динамически сгенерированный код.

Сигнатура

eslint.lintText(code, options)

Параметры

  • code — string Анализируемый JavaScript/TypeScript код.

  • options — object | string

Основные поля options:

{
  filePath?: string;
  warnIgnored?: boolean;
  overrideConfig?: object;
  overrideConfigFile?: string;
  fix?: boolean;
}

Назначение параметров

  • filePath Позволяет эмулировать файл. Используется для применения правил, зависящих от расширения или пути.

  • overrideConfig Позволяет передать конфигурацию ESLint напрямую, без .eslintrc или eslint.config.js.

  • fix Включает автоисправление кода.

  • warnIgnored Определяет поведение при попадании под игнорируемые правила.

Возвращаемое значение

Promise<LintResult[]>

Несмотря на обработку одного текста, результат всегда возвращается массивом, где обычно содержится один элемент.

Пример использования

import { ESLint } from "eslint";

const eslint = new ESLint();

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

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

console.log(results[0].messages);

Применение overrideConfig

const results = await eslint.lintText("var a = 1", {
  overrideConfig: {
    rules: {
      semi: ["error", "always"]
    }
  }
});

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

Сравнение lintFiles и lintText

Источник данных

  • lintFiles — файловая система, glob-паттерны
  • lintText — строка в памяти

Область применения

  • lintFiles используется для анализа проектов и каталогов
  • lintText используется для единичных фрагментов кода

Контекст конфигурации

  • lintFiles автоматически учитывает .eslintignore, eslint.config.js, .eslintrc
  • lintText требует явного указания filePath или overrideConfig для полного контроля

Поведение автоисправлений

Оба метода поддерживают fix, но:

  • lintFiles записывает изменения в output для каждого файла
  • lintText возвращает исправленный код в output без файловой записи

Структура результата линтинга

Независимо от метода, итоговая структура данных одинакова:

{
  filePath: string,
  messages: LintMessage[],
  errorCount: number,
  warningCount: number,
  fixableErrorCount: number,
  fixableWarningCount: number,
  output?: string
}

Поведение счетчиков

  • errorCount — количество ошибок (severity: 2)
  • warningCount — количество предупреждений (severity: 1)
  • fixableErrorCount — ошибки, которые могут быть автоматически исправлены
  • fixableWarningCount — предупреждения с автофиксом

Работа с автоисправлением

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

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

await ESLint.outputFixes(results);

Функция outputFixes записывает изменения обратно в файловую систему.

Для lintText запись не выполняется:

const results = await eslint.lintText("var a = 1", { fix: true });

console.log(results[0].output);

Поведение с виртуальными путями

При использовании lintText значение filePath влияет на:

  • выбор parserOptions
  • применение overrides
  • определение окружения (env)
  • выбор правил по расширению
await eslint.lintText("const x: number = 1", {
  filePath: "file.ts"
});

В данном случае включается TypeScript-конфигурация, если она предусмотрена.

Производительность и архитектурные особенности

lintFiles

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

lintText

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

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

Анализ проекта

await eslint.lintFiles(["src/**/*.js", "src/**/*.ts"]);

Проверка пользовательского ввода

await eslint.lintText(userCode, {
  filePath: "input.js"
});

Динамическая проверка фрагмента

const snippet = "function test() { return 1 }";

await eslint.lintText(snippet, {
  overrideConfig: {
    rules: {
      curly: "error"
    }
  }
});

Особенности интеграции с конфигурацией ESLint

Оба метода учитывают:

  • flat config (eslint.config.js)
  • legacy config (.eslintrc)
  • плагины и парсеры
  • глобальные переменные окружения

Различие проявляется только в способе определения контекста файла: физический путь против виртуального.

Обработка результатов и пост-обработка

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

  • фильтрация по severity
  • группировка по файлам
  • генерация отчётов (JSON, HTML, SARIF)
  • интеграция в CI/CD пайплайны
const errorsOnly = results.map(r => ({
  file: r.filePath,
  errors: r.messages.filter(m => m.severity === 2)
}));

Поведение при ошибках конфигурации

Если конфигурация ESLint некорректна:

  • lintFiles прерывает обработку соответствующего файла
  • lintText возвращает ошибку как сообщение в messages или выбрасывает исключение при критических сбоях

Ключевые различия в контексте исполнения

Характеристика lintFiles lintText
Источник кода Файлы Строка
Поддержка glob Да Нет
Игнорирование Автоматическое Частичное
Автофикс запись В файл В память
Типичный сценарий Проект Фрагмент кода
Оглавление