Spec-Zone.ru › ESLint

Справочник API Node.js

Хотя ESLint предназначен для запуска из командной строки, его можно использовать программно через API Node.js. API Node.js позволяет авторам плагинов и инструментов напрямую использовать функциональность ESLint, не прибегая к интерфейсу командной строки.

Примечание: Используйте недокументированные части API на свой страх и риск. Для использования одобрены только части, явно описанные в этом документе; они останутся стабильными и надежными. Все, что не задокументировано, нестабильно и может быть изменено или удалено в любой момент.

Класс ESLint

Класс ESLint — основной класс для использования в приложениях Node.js.

Этот класс зависит от модуля Node.js fs и файловой системы, поэтому его нельзя использовать в браузерах. Если вы хотите проверять код в браузерах, используйте вместо него класс Linter.

Вот простой пример использования класса ESLint:

const { ESLint } = require("eslint");

(async function main() {
	// 1. Create an instance.
	const eslint = new ESLint();

	// 2. Lint files.
	const results = await eslint.lintFiles(["lib/**/*.js"]);

	// 3. Format the results.
	const formatter = await eslint.loadFormatter("stylish");
	const resultText = formatter.format(results);

	// 4. Output it.
	console.log(resultText);
})().catch(error => {
	process.exitCode = 1;
	console.error(error);
});

Вот пример автоматического исправления проблем, обнаруженных линтером:

const { ESLint } = require("eslint");

(async function main() {
	// 1. Create an instance with the `fix` option.
	const eslint = new ESLint({ fix: true });

	// 2. Lint files. This doesn't modify target files.
	const results = await eslint.lintFiles(["lib/**/*.js"]);

	// 3. Modify the files with the fixed code.
	await ESLint.outputFixes(results);

	// 4. Format the results.
	const formatter = await eslint.loadFormatter("stylish");
	const resultText = formatter.format(results);

	// 5. Output it.
	console.log(resultText);
})().catch(error => {
	process.exitCode = 1;
	console.error(error);
});

А вот пример использования класса ESLint с API lintText:

const { ESLint } = require("eslint");

const testCode = `
  const name = "eslint";
  if(true) {
    console.log("constant condition warning")
  };
`;

(async function main() {
	// 1. Create an instance
	const eslint = new ESLint({
		overrideConfigFile: true,
		overrideConfig: {
			languageOptions: {
				ecmaVersion: 2018,
				sourceType: "commonjs",
			},
		},
	});

	// 2. Lint text.
	const results = await eslint.lintText(testCode);

	// 3. Format the results.
	const formatter = await eslint.loadFormatter("stylish");
	const resultText = formatter.format(results);

	// 4. Output it.
	console.log(resultText);
})().catch(error => {
	process.exitCode = 1;
	console.error(error);
});

◆ new ESLint(options)

const eslint = new ESLint(options);

Создает новый экземпляр ESLint.

Параметры

Конструктор ESLint принимает объект options. Если не указать объект options, для всех параметров будут использованы значения по умолчанию. Объект options имеет следующие свойства.

Перечисление файлов
  • options.cwd (string)
    По умолчанию — process.cwd(). Рабочий каталог. Должен быть абсолютным путем.
  • options.errorOnUnmatchedPattern (boolean)
    По умолчанию — true. Если задано значение, отличное от false, метод eslint.lintFiles() выдаст ошибку, если целевые файлы не найдены.
  • options.globInputPaths (boolean)
    По умолчанию — true. Если задано значение false, метод eslint.lintFiles() не интерпретирует шаблоны glob.
  • options.ignore (boolean)
    По умолчанию — true. Если задано значение false, метод eslint.lintFiles() не учитывает ignorePatterns в конфигурации.
  • options.ignorePatterns (string[] | null)
    По умолчанию — null. Шаблоны игнорируемых файлов, которые следует использовать в дополнение к исключениям из конфигурации. Эти шаблоны задаются относительно cwd.
  • options.passOnNoPatterns (boolean)
    По умолчанию — false. Если задано значение true, при отсутствии совпадений операция проверки немедленно завершается и не сообщает о сбоях.
  • options.warnIgnored (boolean)
    По умолчанию — true. Показывать предупреждения, если список файлов содержит игнорируемые файлы.
Проверка кода
  • options.allowInlineConfig (boolean)
    По умолчанию — true. Если задано значение false, ESLint подавляет директивные комментарии в исходном коде. Если для этого параметра задано значение false, оно переопределяет настройку noInlineConfig в конфигурации.
  • options.baseConfig (Config | Config[] | null)
    По умолчанию — null. Объект конфигурации, дополняемый всеми конфигурациями, используемыми этим экземпляром. С помощью этого параметра можно задать настройки по умолчанию, которые будут использоваться, если они не указаны в файлах конфигурации.
  • options.overrideConfig (Config | Config[] | null)
    По умолчанию — null. Объект конфигурации, добавляемый после всех существующих конфигураций и поэтому применяемый после настроек из файла конфигурации (если он используется).
  • options.overrideConfigFile (null | true | string)
    По умолчанию — null. По умолчанию ESLint выполняет поиск файла конфигурации. Если этому параметру задано значение true, ESLint не выполняет поиск файла конфигурации. Если этому параметру задано значение типа string, ESLint не выполняет поиск файла конфигурации и использует указанное значение как путь к файлу конфигурации.
  • options.plugins (Record<string, Plugin> | null)
    По умолчанию — null. Реализации плагинов, которые ESLint использует для настройки plugins в конфигурации. Это объект, подобный карте. Ключи — это идентификаторы плагинов, а значения — соответствующие реализации.
  • options.ruleFilter (({ruleId: string, severity: number}) => boolean)
    По умолчанию — () => true. Функция-предикат, отбирающая правила для запуска. Эта функция вызывается с объектом, содержащим ruleId и severity, и возвращает true, если правило следует запустить.
  • options.stats (boolean)
    По умолчанию — false. Если задано значение true, в результаты проверки добавляется дополнительная статистика (см. тип Stats).
Автоисправление
  • options.fix (boolean | (message: LintMessage) => boolean)
    По умолчанию — false. Если задано значение true, методы eslint.lintFiles() и eslint.lintText() работают в режиме автоисправления. Если задана функция-предикат, методы передают ей каждое сообщение линтера, а затем используют только те сообщения, для которых функция вернула true.
  • options.fixTypes (("directive" | "problem" | "suggestion" | "layout")[] | null)
    По умолчанию — null. Типы правил, которые методы eslint.lintFiles() и eslint.lintText() используют для автоисправления.
Параметры кэша
  • options.cache (boolean)
    По умолчанию — false. Если задано значение true, метод eslint.lintFiles() кэширует результаты проверки и использует их, если целевые файлы не изменились. Обратите внимание: при обновлении плагинов ESLint кэш не очищается. В этом случае файл кэша нужно удалить вручную. Метод eslint.lintText() не использует кэш, даже если передать методу options.filePath.
  • options.cacheLocation (string)
    По умолчанию — .eslintcache. Метод eslint.lintFiles() записывает кэш в этот файл.
  • options.cacheStrategy (string)
    По умолчанию — "metadata". Стратегия кэширования для обнаружения измененных файлов. Возможные значения: "metadata" или "content".
Подавление сообщений
  • options.applySuppressions (boolean)
    По умолчанию — false. Если задано значение true, подавления из файла подавлений автоматически применяются к результатам методов eslint.lintFiles() и eslint.lintText(). При использовании eslint.lintText() для применения подавлений также необходимо указать параметр filePath.
  • options.suppressionsLocation (string)
    По умолчанию — "eslint-suppressions.json". Путь к файлу подавлений. Путь может быть абсолютным или относительным к cwd.
Другие параметры
  • options.concurrency (number | "auto" | "off")
    По умолчанию — "off". По умолчанию ESLint проверяет все файлы в вызывающем потоке. Если для этого параметра указано целое число, ESLint будет использовать до этого количества рабочих потоков для параллельной проверки файлов. "auto" автоматически выбирает значение. Если указан этот параметр, все остальные параметры должны быть клонируемыми.
  • options.flags (string[])
    По умолчанию — []. Флаги функций, которые следует включить для этого экземпляра.

◆ eslint.lintFiles(patterns)

const results = await eslint.lintFiles(patterns);

Этот метод проверяет файлы, соответствующие шаблонам glob, и возвращает результаты.

Параметры

  • patterns (string | string[])
    Целевые файлы для проверки. Здесь можно указать пути к файлам, каталоги и шаблоны glob.

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

  • (Promise<LintResult[]>)
    Объект promise, который будет разрешен массивом объектов LintResult.

◆ eslint.lintText(code, options)

const results = await eslint.lintText(code, options);

Этот метод проверяет указанный текст исходного кода и возвращает результаты.

По умолчанию метод использует конфигурацию, применяемую к файлам в текущем рабочем каталоге (параметр конструктора cwd). Чтобы использовать другую конфигурацию, передайте options.filePath, и ESLint загрузит ту же конфигурацию, которую использовал бы метод eslint.lintFiles() для файла по пути options.filePath.

Если значение options.filePath настроено как игнорируемое, этот метод возвращает пустой массив. Если параметр options.warnIgnored задан вместе с параметром options.filePath, метод возвращает объект LintResult. В этом случае результат может содержать предупреждение о том, что файл был проигнорирован.

Параметры

Второй параметр options можно не указывать.

  • code (string)
    Текст исходного кода для проверки.
  • options.filePath (string)
    Необязательный параметр. Путь к файлу с текстом исходного кода. Если не указан, result.filePath становится строкой "<text>".
  • options.warnIgnored (boolean)
    Необязательный параметр; по умолчанию используется значение options.warnIgnored, переданное конструктору. Если задано значение true и options.filePath — файл, который ESLint должен игнорировать, этот метод возвращает результат проверки с предупреждением.

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

  • (Promise<LintResult[]>)
    Объект promise, который будет разрешен массивом объектов LintResult. Это массив (хотя результат проверки только один), чтобы интерфейсы этого метода и метода eslint.lintFiles() были похожи.

◆ eslint.getRulesMetaForResults(results)

const results = await eslint.lintFiles(patterns);
const rulesMeta = eslint.getRulesMetaForResults(results);

Этот метод возвращает объект с метаинформацией о каждом правиле, вызвавшем ошибку проверки в указанном results.

Параметры

  • results (LintResult[])
    Массив объектов LintResult, возвращенных вызовом ESLint#lintFiles() или ESLint#lintText().

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

  • (Object)
    Объект, имена свойств которого — идентификаторы правил из results, а значения — метаинформация о соответствующих правилах (если доступна).

◆ eslint.calculateConfigForFile(filePath)

const config = await eslint.calculateConfigForFile(filePath);

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

Параметры

  • filePath (string)
    Путь к файлу, конфигурацию которого нужно вычислить. Пути к каталогам запрещены, поскольку ESLint не может обрабатывать настройку overrides.

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

  • (Promise<Object>)
    Объект promise, который будет разрешен объектом конфигурации.

◆ eslint.findConfigFile(filePath)

const configFilePath = await eslint.findConfigFile(filePath);

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

Параметры

  • filePath (string)
    Необязательный параметр. Путь к файлу, для которого нужно найти соответствующий файл конфигурации. Если не указан, ESLint определяет файл конфигурации на основе текущего рабочего каталога этого экземпляра.

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

  • (Promise<string | undefined>)
    Объект promise, который будет разрешен абсолютным путем к используемому файлу конфигурации или значением undefined, если файл конфигурации не используется (например, если задано overrideConfigFile: true).

◆ eslint.isPathIgnored(filePath)

const isPathIgnored = await eslint.isPathIgnored(filePath);

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

Параметры

  • filePath (string)
    Путь к файлу, который нужно проверить.

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

  • (Promise<boolean>)
    Объект promise, который будет разрешен значением, указывающим, игнорируется ли файл. Если файл игнорируется, будет возвращено true.

◆ eslint.loadFormatter(nameOrPath)

const formatter = await eslint.loadFormatter(nameOrPath);

Этот метод загружает форматтер. Форматтеры преобразуют результаты проверки в строку, понятную человеку или машиночитаемую.

Параметры

  • nameOrPath (string | undefined)
    Путь к файлу, который нужно проверить. Допустимы следующие значения:
    • undefined. В этом случае загружается встроенный форматтер "stylish".
    • Имя встроенного форматтера.
    • Имя стороннего форматтера. Например:
      • "foo" загрузит eslint-formatter-foo.
      • "@foo" загрузит @foo/eslint-formatter.
      • "@foo/bar" загрузит @foo/eslint-formatter-bar.
    • Путь к файлу, в котором определен форматтер. Чтобы отличить путь от имени, он должен содержать один или несколько разделителей пути (/). Например, начинаться с ./.

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

  • (Promise<LoadedFormatter>)
    Объект promise, который будет разрешен объектом LoadedFormatter.

◆ eslint.hasFlag(flagName)

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

if (eslint.hasFlag("x_feature")) {
	// handle flag
}

Параметры

  • flagName (string)
    Флаг для проверки.

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

  • (boolean)
    Значение True, если флаг включен.

◆ ESLint.version

const version = ESLint.version;

Строка с номером версии ESLint. Например, "7.0.0".

Это статическое свойство.

◆ ESLint.defaultConfig

const defaultConfig = ESLint.defaultConfig;

Конфигурация по умолчанию, которую ESLint использует внутри. Она предоставляется инструментам, которым нужно вычислять конфигурации с теми же настройками по умолчанию, что и у ESLint. Учтите, что конфигурация по умолчанию может меняться от версии к версии, поэтому не следует полагаться на наличие каких-либо конкретных ключей или значений.

Это статическое свойство.

◆ ESLint.fromOptionsModule(optionsURL)

const eslint = await ESLint.fromOptionsModule(optionsURL);

Этот метод создает экземпляр класса ESLint с параметрами, загруженными из модуля. Например:

// eslint-options.js

import config from "./my-eslint-config.js";

export default {
	concurrency: "auto",
	overrideConfig: config,
	overrideConfigFile: true,
	stats: true,
};

// main.js

...
const optionsURL = new URL("./eslint-options.js", import.meta.url);
const eslint = await ESLint.fromOptionsModule(optionsURL);
...

Параметр concurrency требует, чтобы все остальные параметры были клонируемыми, чтобы их можно было передавать рабочим потокам. Это ограничение не применяется, если параметры загружаются из модуля, поскольку в этом случае рабочим потокам передается URL модуля, а не объект параметров.

Это статический метод.

Параметры

  • optionsURL (URL)
    URL модуля параметров. Это может быть любой допустимый URL, например URL файла или URL данных.

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

  • (Promise<ESLint>)
    Новый экземпляр класса ESLint.

◆ ESLint.outputFixes(results)

await ESLint.outputFixes(results);

Этот метод записывает в соответствующие файлы код, измененный функцией автоисправления ESLint. Если какие-либо измененные файлы не существуют, метод ничего не делает.

Это статический метод.

Параметры

  • results (LintResult[])
    Объекты LintResult для записи.

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

  • (Promise<void>)
    Объект promise, который будет разрешен после записи всех файлов.

◆ ESLint.getErrorResults(results)

const filteredResults = ESLint.getErrorResults(results);

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

Это статический метод.

Параметры

  • results (LintResult[])
    Объекты LintResult для фильтрации.

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

  • (LintResult[])
    Отфильтрованные объекты LintResult.

◆ Тип LintResult

Значение LintResult содержит сведения о результате проверки каждого файла. Его возвращают методы eslint.lintFiles() и eslint.lintText(). Оно имеет следующие свойства:

  • filePath (string)
    Абсолютный путь к файлу, для которого получен этот результат. Если путь к файлу неизвестен (когда методу eslint.lintText() не передан параметр options.filePath), используется строка "<text>".
  • messages (LintMessage[])
    Массив объектов LintMessage.
  • suppressedMessages (SuppressedLintMessage[])
    Массив объектов SuppressedLintMessage.
  • fixableErrorCount (number)
    Количество ошибок, которые можно автоматически исправить с помощью параметра конструктора fix.
  • fixableWarningCount (number)
    Количество предупреждений, которые можно автоматически исправить с помощью параметра конструктора fix.
  • errorCount (number)
    Количество ошибок. Сюда входят исправляемые ошибки и критические ошибки.
  • fatalErrorCount (number)
    Количество критических ошибок.
  • warningCount (number)
    Количество предупреждений. Сюда входят исправляемые предупреждения.
  • output (string | undefined)
    Измененный текст исходного кода. Это свойство не определено, если исправляемые сообщения отсутствуют.
  • source (string | undefined)
    Исходный текст кода. Это свойство не определено, если сообщения отсутствуют или существует свойство output.
  • stats (Stats | undefined)
    Объект Stats. Он содержит статистику производительности проверки, собранную с помощью параметра stats.
  • usedDeprecatedRules ({ ruleId: string; replacedBy: string[]; info: DeprecatedInfo | undefined }[])
    Сведения об устаревших правилах, использованных для проверки этого файла. Для свойства info задается значение rule.meta.deprecated, если правило использует новое свойство deprecated.

◆ Тип LintMessage

Значение LintMessage содержит сведения об отдельной ошибке проверки. Оно содержится в свойстве messages типа LintResult. Оно имеет следующие свойства:

  • ruleId (string | null)
    Имя правила, вызвавшего это сообщение линтера. Если сообщение создано ядром ESLint, а не правилом, здесь указано null.
  • severity (1 | 2)
    Серьезность сообщения. 1 означает предупреждение, а 2 — ошибку.
  • fatal (boolean | undefined)
    true, если это критическая ошибка, не связанная с правилом, например ошибка разбора.
  • message (string)
    Текст сообщения об ошибке.
  • messageId (string | undefined)
    Идентификатор сообщения об ошибке проверки. Это свойство не определено, если правило не использует идентификаторы сообщений.
  • line (number | undefined)
    Номер строки (начиная с 1), в которой начинается сообщение.
  • column (number | undefined)
    Номер столбца (начиная с 1), в котором начинается сообщение.
  • endLine (number | undefined)
    Номер строки (начиная с 1), в которой заканчивается сообщение. Это свойство не определено, если сообщение не относится к диапазону.
  • endColumn (number | undefined)
    Номер столбца (начиная с 1), в котором заканчивается сообщение. Это свойство не определено, если сообщение не относится к диапазону.
  • fix (EditInfo | undefined)
    Объект EditInfo для автоисправления. Это свойство не определено, если сообщение нельзя исправить.
  • suggestions ({ desc: string; fix: EditInfo; messageId?: string; data?: object }[] | undefined)
    Список предложений. Каждое предложение — это пара из описания и объекта EditInfo для исправления кода. Пользователи API, например интеграции с редакторами, могут выбрать одно из них для устранения проблемы, указанной в сообщении. Это свойство не определено, если для сообщения нет предложений.

◆ Тип SuppressedLintMessage

Значение SuppressedLintMessage содержит сведения об отдельной подавленной ошибке проверки. Оно содержится в свойстве suppressedMessages типа LintResult. Оно имеет следующие свойства:

  • ruleId (string | null)
    То же, что ruleId в типе LintMessage.
  • severity (1 | 2)
    То же, что severity в типе LintMessage.
  • fatal (boolean | undefined)
    То же, что fatal в типе LintMessage.
  • message (string)
    То же, что message в типе LintMessage.
  • messageId (string | undefined)
    То же, что messageId в типе LintMessage.
  • line (number | undefined)
    То же, что line в типе LintMessage.
  • column (number | undefined)
    То же, что column в типе LintMessage.
  • endLine (number | undefined)
    То же, что endLine в типе LintMessage.
  • endColumn (number | undefined)
    То же, что endColumn в типе LintMessage.
  • fix (EditInfo | undefined)
    То же, что fix в типе LintMessage.
  • suggestions ({ desc: string; fix: EditInfo; messageId?: string; data?: object }[] | undefined)
    То же, что suggestions в типе LintMessage.
  • suppressions ({ kind: string; justification: string}[])
    Список подавлений. Каждое подавление представляет собой пару из типа и обоснования.

◆ Тип EditInfo

Значение EditInfo содержит сведения для редактирования текста. Оно содержится в свойствах fix и suggestions типа LintMessage. Оно имеет следующие свойства:

  • range ([number, number])
    Пара индексов в тексте исходного кода (отсчет начинается с 0), задающая удаляемый фрагмент.
  • text (string)
    Текст для добавления.

Эти сведения об изменении означают замену диапазона свойства range значением свойства text. Это похоже на sourceCodeText.slice(0, edit.range[0]) + edit.text + sourceCodeText.slice(edit.range[1]). Поэтому операция является добавлением, если значения свойств range[0] и range[1] совпадают, и удалением, если значение свойства text — пустая строка.

◆ Тип LoadedFormatter

Значение LoadedFormatter — это объект для преобразования объектов LintResult в текст. Его возвращает метод eslint.loadFormatter(). Он имеет следующий метод:

  • format ((results: LintResult[], resultsMeta?: ResultsMeta) => string | Promise<string>)
    Метод для преобразования объектов LintResult в текст. resultsMeta — необязательный параметр, предназначенный главным образом для ESLint CLI; он может содержать свойства color и maxWarningsExceeded, которые передаются через объект context при вызове этим методом базовой функции форматтера. Обратите внимание: ESLint автоматически создает свойства cwd и rulesMeta объекта context, поэтому при вызове этого метода обычно не нужно передавать второй аргумент.

loadESLint()

Функция loadESLint() используется интеграциями, которым необходимо поддерживать разные версии ESLint. Эта функция возвращает подходящую реализацию класса ESLint в зависимости от переданных аргументов:

const { loadESLint } = require("eslint");

// loads the default ESLint that the CLI would use based on process.cwd()
const DefaultESLint = await loadESLint();

// loads the flat config version specifically
const FlatESLint = await loadESLint({ useFlatConfig: true });

// loads the legacy version specifically if possible, otherwise falls back to flat config version
const LegacyESLint = await loadESLint({ useFlatConfig: false });

Затем можно использовать возвращенный конструктор для создания нового экземпляра ESLint, например:

// loads the default ESLint that the CLI would use based on process.cwd()
const DefaultESLint = await loadESLint();
const eslint = new DefaultESLint();

Если вы не уверены, какую систему конфигурации использует возвращенный конструктор, проверьте свойство configType: оно содержит либо "flat", либо "eslintrc":

// loads the default ESLint that the CLI would use based on process.cwd()
const DefaultESLint = await loadESLint();

if (DefaultESLint.configType === "flat") {
	// do something specific to flat config
}

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

SourceCode

Тип SourceCode представляет разобранный исходный код, который обрабатывает ESLint. Он используется внутри ESLint и также доступен для работы с уже разобранным кодом. Можно создать новый экземпляр SourceCode, передав строку с кодом и абстрактное синтаксическое дерево (AST) в формате ESTree (включая сведения о местоположении, диапазонах, комментариях и токенах):

const SourceCode = require("eslint").SourceCode;

const code = new SourceCode("var foo = bar;", ast);

Конструктор SourceCode выдает ошибку, если в AST отсутствуют какие-либо обязательные сведения.

Конструктор SourceCode удаляет метку порядка байтов Unicode (BOM). Обратите внимание: AST также следует строить по тексту без этой метки.

const SourceCode = require("eslint").SourceCode;

const code = new SourceCode("\uFEFFvar foo = bar;", ast);

assert(code.hasBOM === true);
assert(code.text === "var foo = bar;");

SourceCode#splitLines()

Это статическая функция объекта SourceCode, которая используется для разделения текста исходного кода на массив строк.

const SourceCode = require("eslint").SourceCode;

const code = "var a = 1;\nvar b = 2;";

// split code into an array
const codeLines = SourceCode.splitLines(code);

/*
    Value of codeLines will be
    [
        "var a = 1;",
        "var b = 2;"
    ]
 */

Linter

Объект Linter выполняет фактическую проверку кода JavaScript. Он не выполняет никаких операций с файловой системой, а просто анализирует код и сообщает о результатах. В частности, объект Linter не обрабатывает файлы конфигурации. Если вы не работаете в браузере, вероятно, вам следует использовать вместо него класс ESLint.

Linter — это конструктор, и вы можете создать новый экземпляр, передав ему параметры, которые хотите использовать. Доступны следующие параметры:

  • cwd — путь к каталогу, который следует считать текущим рабочим каталогом. Он доступен правилам через context.cwd (см. Объект контекста). Если cwd имеет значение undefined, он будет нормализован до process.cwd(), если определён глобальный объект process (например, в среде выполнения Node.js), или до undefined в противном случае.

Например:

const Linter = require("eslint").Linter;
const linter1 = new Linter({ cwd: "path/to/project" });
const linter2 = new Linter();

В этом примере правила, выполняемые для linter1, получат path/to/project из context.cwd. Правила, выполняемые для linter2, получат process.cwd(), если определён глобальный объект process, или undefined в противном случае (например, в браузере на странице https://eslint.org/demo).

Linter#verify

Самый важный метод объекта Linter — verify(), который запускает проверку заданного текста. Этот метод принимает три аргумента:

  • code — исходный код для проверки (строка или экземпляр SourceCode).
  • config — объект конфигурации или массив объектов конфигурации.
    • Примечание: если вы хотите проверять текст и считывать конфигурацию из файловой системы, используйте вместо этого ESLint#lintFiles() или ESLint#lintText().
  • options — (необязательно) дополнительные параметры для этого запуска.
    • filename — (необязательно) имя файла, связываемое с исходным кодом.
    • preprocess — (необязательно) функция, описанная в документации «Процессоры в плагинах» как метод preprocess.
    • postprocess — (необязательно) функция, описанная в документации «Процессоры в плагинах» как метод postprocess.
    • filterCodeBlock — (необязательно) функция, определяющая, какие блоки кода должен обрабатывать линтер. Функция получает два аргумента. Первый аргумент — виртуальное имя файла блока кода. Второй аргумент — текст блока кода. Если функция возвращает true, линтер обрабатывает блок кода. Если функция не указана, линтер обрабатывает только блоки кода *.js. Если вы указали функцию filterCodeBlock, она переопределяет это поведение по умолчанию, поэтому линтер не обрабатывает блоки кода *.js автоматически.
    • disableFixes — (необязательно) если задано значение true, линтер не добавляет ни свойство fix, ни свойство suggestions в результат проверки.
    • allowInlineConfig — (необязательно) задайте значение false, чтобы запретить встроенным комментариям изменять правила ESLint.
    • reportUnusedDisableDirectives — (необязательно) если задано значение true, добавляет сообщения об ошибках для неиспользуемых директив eslint-disable и eslint-enable, если в отключённой области и без того не было бы обнаружено проблем.
    • ruleFilter — (необязательно) функция-предикат, определяющая, какие правила следует запускать. Она получает объект, содержащий ruleId и severity, и возвращает true, если правило следует запустить.

Если третий аргумент является строкой, он интерпретируется как filename.

Вызвать verify() можно следующим образом:

const Linter = require("eslint").Linter;
const linter = new Linter();

const messages = linter.verify(
	"var foo;",
	{
		rules: {
			semi: 2,
		},
	},
	{ filename: "foo.js" },
);

// or using SourceCode

const Linter = require("eslint").Linter,
	linter = new Linter(),
	SourceCode = require("eslint").SourceCode;

const code = new SourceCode("var foo = bar;", ast);

const messages = linter.verify(
	code,
	{
		rules: {
			semi: 2,
		},
	},
	{ filename: "foo.js" },
);

Метод verify() возвращает массив объектов, содержащих сведения о предупреждениях и ошибках, обнаруженных при проверке. Например:

[
	{
		fatal: false,
		ruleId: "semi",
		severity: 2,
		line: 1,
		column: 23,
		message: "Expected a semicolon.",
		fix: {
			range: [1, 15],
			text: ";",
		},
	},
];

Для каждого сообщения проверки доступны следующие сведения:

  • column — столбец, в котором произошла ошибка.
  • fatal — обычно отсутствует, но принимает значение true, если произошла ошибка разбора (не связанная с правилом).
  • line — строка, в которой произошла ошибка.
  • message — сообщение, которое следует вывести.
  • messageId — идентификатор сообщения, использованный для его создания (это свойство отсутствует, если правило не использует идентификаторы сообщений).
  • ruleId — идентификатор правила, вызвавшего сообщение (или null, если fatal имеет значение true).
  • severity — 1 или 2 в зависимости от конфигурации.
  • endColumn — конечный столбец диапазона, в котором произошла ошибка (это свойство отсутствует, если диапазон не задан).
  • endLine — конечная строка диапазона, в котором произошла ошибка (это свойство отсутствует, если диапазон не задан).
  • fix — объект с описанием исправления проблемы (это свойство отсутствует, если исправление недоступно).
  • suggestions — массив объектов с описанием возможных исправлений, которые редакторы могут применять программно (подробности см. в документации «Работа с правилами»).

Получить подавленные сообщения предыдущего запуска можно с помощью метода getSuppressedMessages(). Если предыдущего запуска не было, getSuppressedMessage() вернёт пустой список.

const Linter = require("eslint").Linter;
const linter = new Linter();

const messages = linter.verify(
	"var foo = bar; // eslint-disable-line -- Need to suppress",
	{
		rules: {
			semi: ["error", "never"],
		},
	},
	{ filename: "foo.js" },
);
const suppressedMessages = linter.getSuppressedMessages();

console.log(suppressedMessages[0].suppressions); // [{ "kind": "directive", "justification": "Need to suppress" }]

Также можно получить экземпляр объекта SourceCode, используемого внутри linter, с помощью метода getSourceCode():

const Linter = require("eslint").Linter;
const linter = new Linter();

const messages = linter.verify(
	"var foo = bar;",
	{
		rules: {
			semi: 2,
		},
	},
	{ filename: "foo.js" },
);

const code = linter.getSourceCode();

console.log(code.text); // "var foo = bar;"

Таким образом можно получить текст и AST, использованные при последнем запуске linter.verify().

Linter#verifyAndFix()

Этот метод похож на verify, но также запускает автоматическое исправление, аналогичное флагу --fix командной строки. Объект результата будет содержать автоматически исправленный код, а также оставшиеся сообщения проверки для кода, который не удалось исправить автоматически.

const Linter = require("eslint").Linter;
const linter = new Linter();

const messages = linter.verifyAndFix("var foo", {
	rules: {
		semi: 2,
	},
});

Объект, возвращаемый этим методом:

{
    fixed: true,
    output: "var foo;",
    messages: []
}

Доступны следующие сведения:

  • fixed — true, если код был исправлен.
  • output — текст исправленного кода (может совпадать с входными данными, если исправления не применялись).
  • messages — коллекция всех сообщений для заданного кода (содержит те же сведения, что описаны выше в блоке verify).

Linter#version/Linter.version

Каждый экземпляр Linter имеет свойство version, содержащее номер семантической версии ESLint, которой соответствует этот экземпляр Linter.

const Linter = require("eslint").Linter;
const linter = new Linter();

linter.version; // => '9.0.0'

Также доступно свойство Linter.version, которое можно прочитать, не создавая экземпляр Linter:

const Linter = require("eslint").Linter;

Linter.version; // => '9.0.0'

Linter#getTimes()

Этот метод позволяет получить время, затраченное на разбор, исправление и проверку файла. См. свойство times объекта Stats.

Linter#getFixPassCount()

Этот метод позволяет получить количество выполненных проходов автоматического исправления. См. свойство fixPasses объекта Stats.

Linter#hasFlag()

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

const Linter = require("eslint").Linter;
const linter = new Linter({ flags: ["x_feature"] });

console.log(linter.hasFlag("x_feature")); // true

RuleTester

eslint.RuleTester — это утилита для написания тестов правил ESLint. Она используется внутри ESLint для встроенных правил, а также может использоваться плагинами.

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

"use strict";

const rule = require("../../../lib/rules/my-rule"),
	RuleTester = require("eslint").RuleTester;

const ruleTester = new RuleTester();

ruleTester.run("my-rule", rule, {
	valid: [
		{
			code: "var foo = true",
			options: [{ allowFoo: true }],
		},
	],

	invalid: [
		{
			code: "var invalidVariable = true",
			errors: [{ message: "Unexpected invalid variable." }],
		},
		{
			code: "var invalidVariable = true",
			errors: [{ message: /^Unexpected.+variable/ }],
		},
	],

	// optional
	assertionOptions: {
		requireMessage: true,
		requireLocation: false,
		requireData: true,
	},
});

Конструктор RuleTester принимает необязательный объект, который можно использовать для задания значений по умолчанию для тестовых случаев. Например, если во всех тестовых случаях используется ES2015, его можно задать как значение по умолчанию:

const ruleTester = new RuleTester({ languageOptions: { ecmaVersion: 2015 } });
Совет

Если не указать параметры для конструктора RuleTester, будут использоваться значения ESLint по умолчанию (languageOptions: { ecmaVersion: "latest", sourceType: "module" }).

RuleTester.setDefaultConfig(config)

const RuleTester = require("eslint").RuleTester;

// Apply a default config for subsequently created RuleTester instances
RuleTester.setDefaultConfig({
	languageOptions: { ecmaVersion: 2022, sourceType: "module" },
});

const ruleTester = new RuleTester(); // picks up defaults above

Устанавливает конфигурацию по умолчанию для экземпляров RuleTester, созданных после этого вызова.

Это статический метод.

Параметры

  • config (Config)
    Объект конфигурации, применяемый по умолчанию ко всем тестам. Он применяется до параметров конструктора RuleTester для отдельных экземпляров и до конфигурации для отдельных тестов. Выбрасывает TypeError, если config не является объектом.

RuleTester.getDefaultConfig()

const currentDefaultConfig = RuleTester.getDefaultConfig();

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

Это статический метод.

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

  • (Config)
    Текущий объект конфигурации по умолчанию.

RuleTester.resetDefaultConfig()

RuleTester.resetDefaultConfig();

Сбрасывает конфигурацию по умолчанию до встроенных значений ESLint для экземпляров RuleTester, создаваемых впоследствии.

Это статический метод.

RuleTester#run()

Метод RuleTester#run() используется для запуска тестов. Ему следует передать следующие аргументы:

  • Имя правила (строка).
  • Сам объект правила (см. «Работа с правилами»).
  • Объект, содержащий свойства valid и invalid, каждое из которых представляет собой массив тестовых случаев.
    • В этом объекте также можно передать свойство assertionOptions, чтобы настроить требования к проверкам тестовых случаев invalid и обеспечить единообразие.

Тестовый случай — это объект со следующими свойствами:

  • name (строка, необязательно): имя тестового случая, упрощающее его поиск.
  • code (строка, обязательно): исходный код, для которого следует запустить правило.
  • options (массив, необязательно): параметры, передаваемые правилу. Уровень важности правила не следует включать в этот список.
  • before (функция, необязательно): функция, выполняемая перед проверкой случая.
  • after (функция, необязательно): функция, выполняемая после проверки случая независимо от её результата.
  • filename (строка, необязательно): имя файла для данного случая (полезно для правил, проверяющих имена файлов).
  • only (логическое значение, необязательно): запускать только этот случай для отладки в поддерживаемых тестовых платформах.

Помимо перечисленных выше свойств, недопустимые тестовые случаи также могут содержать следующие свойства:

  • errors (число или массив, обязательно): проверяет некоторые свойства ошибок, которые, как ожидается, правило должно выдать при обработке этого кода. Если задано число, проверяется количество возникших ошибок. В противном случае это должен быть список объектов, каждый из которых содержит сведения об одной обнаруженной ошибке. Для ошибки можно использовать следующие свойства (все необязательны, если не указано иное):

    • message (строка/регулярное выражение): сообщение об ошибке. Необходимо указать это свойство или messageId.
    • messageId (строка): идентификатор ошибки. Необходимо указать это свойство или message. Подробности см. в разделе «Тестирование ошибок с messageId».
    • data (объект): данные-заполнители, которые можно использовать вместе с messageId.
    • line (число): номер строки обнаруженного расположения, начиная с 1.
    • column (число): номер столбца обнаруженного расположения, начиная с 1.
    • endLine (число): номер конечной строки обнаруженного расположения, начиная с 1.
    • endColumn (число): номер конечного столбца обнаруженного расположения, начиная с 1.
    • suggestions (массив): массив объектов с описанием предлагаемых исправлений для проверки. Обязательно, если правило предлагает варианты исправления. Подробности см. в разделе «Тестирование предложений».

    Если вместо объекта ошибка задана строкой, эта строка используется для проверки message ошибки.

  • output (строка, обязательно, если правило исправляет код): проверяет результат применения правила для одного прохода автоматического исправления (например, с флагом командной строки --fix). Если задано значение null или свойство не указано, проверяется, что ни одна из обнаруженных проблем не предлагает автоматического исправления.

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

{
    code: "let foo;",
    languageOptions: { ecmaVersion: 2015 }
}

Если допустимый тестовый случай содержит только свойство code, его можно указать в виде строки с кодом, а не объекта с ключом code.

При желании можно настроить следующие assertionOptions, применяемые ко всем проверкам ошибок в этом вызове:

  • requireMessage (логическое значение/"message"/"messageId", необязательно):
    • Если задано значение true, каждый блок errors должен проверять ожидаемые сообщения об ошибках: либо с помощью строк/регулярных выражений в массиве errors, либо с помощью message/messageId в объектах ошибок.
    • Если задано значение "message", каждый блок errors должен проверять ожидаемые сообщения об ошибках: либо с помощью строк/регулярных выражений в массиве errors, либо с помощью message в объектах ошибок.
    • Если задано значение "messageId", каждый блок errors должен проверять ожидаемые сообщения об ошибках с помощью messageId в объектах ошибок.
  • requireLocation (логическое значение, необязательно): если задано значение true, каждый блок errors должен представлять собой массив объектов, и каждый объект должен содержать свойства расположения line, column, endLine и endColumn. Свойства endLine и endColumn можно не указывать, если фактическая ошибка их не содержит.
  • requireData (логическое значение/"error"/"suggestion", необязательно):
    • Если задано значение true, каждый объект ошибки, содержащий messageId, и каждый объект предложения, содержащий messageId, также должен содержать data, если сообщение, указанное в messageId, содержит заполнители.
    • Если задано значение "error", каждый объект ошибки, содержащий messageId, также должен содержать data, если сообщение, указанное в messageId, содержит заполнители.
    • Если задано значение "suggestion", каждый объект предложения, содержащий messageId, также должен содержать data, если сообщение, указанное в messageId, содержит заполнители.

Тестирование ошибок с messageId

Если тестируемое правило использует messageId, в тестовом случае можно использовать свойство messageId, чтобы проверить messageId обнаруженной ошибки вместо её message.

{
    code: "let foo;",
    errors: [{ messageId: "unexpected" }]
}

Для сообщений с заполнителями тестовый случай также может использовать свойство data, чтобы дополнительно проверить message обнаруженной ошибки.

{
    code: "let foo;",
    errors: [{ messageId: "unexpected", data: { name: "foo" } }]
}

Обратите внимание: data в тестовом случае не проверяет data, переданный в context.report. Вместо этого оно используется для формирования ожидаемого текста сообщения, который затем сравнивается с полученным message.

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

Результат применения исправлений можно проверить с помощью свойства output недопустимого тестового случая. Свойство output следует использовать только в том случае, если ожидается применение исправления к указанному code; если изменений кода не ожидается, output можно не указывать. Например:

ruleTester.run("my-rule-for-no-foo", rule, {
	valid: [],
	invalid: [
		{
			code: "var foo;",
			output: "var bar;",
			errors: [
				{
					messageId: "shouldBeBar",
					line: 1,
					column: 5,
				},
			],
		},
	],
});

В конце этого недопустимого тестового случая RuleTester ожидает применения исправления, в результате которого код изменится с var foo; на var bar;. Если результат после применения исправления не совпадёт с ожидаемым, тест завершится неудачей.

Важно

ESLint старается применить все исправления, но не гарантирует, что будут применены все. Поэтому каждое исправление следует проверять в отдельном тестовом случае RuleTester, а не проверять несколько исправлений в одном тестовом случае. Если два исправления конфликтуют (поскольку применяются к одному и тому же фрагменту кода), RuleTester применяет только первое исправление.

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

Предложения можно тестировать, задав ключ suggestions в объекте ошибки. Если задано число, проверяется количество предложений для этой ошибки. В противном случае это должен быть массив объектов, каждый из которых содержит сведения об одном предложении. Можно использовать следующие свойства:

  • desc (строка): значение desc предложения. Необходимо указать это свойство или messageId.
  • messageId (строка): значение messageId предложения для предложений, использующих messageId. Необходимо указать это свойство или desc.
  • data (объект): данные-заполнители, которые можно использовать вместе с messageId.
  • output (строка, обязательно): строка кода, представляющая результат применения предлагаемого исправления к входному коду.

Пример:

ruleTester.run("my-rule-for-no-foo", rule, {
	valid: [],
	invalid: [
		{
			code: "var foo;",
			errors: [
				{
					suggestions: [
						{
							desc: "Rename identifier 'foo' to 'bar'",
							output: "var bar;",
						},
					],
				},
			],
		},
	],
});

Свойства messageId и data в объектах тестирования предложений работают так же, как в объектах тестирования ошибок. Подробности см. в разделе «Тестирование ошибок с messageId».

ruleTester.run("my-rule-for-no-foo", rule, {
	valid: [],
	invalid: [
		{
			code: "var foo;",
			errors: [
				{
					suggestions: [
						{
							messageId: "renameFoo",
							data: { newName: "bar" },
							output: "var bar;",
						},
					],
				},
			],
		},
	],
});

Настройка RuleTester

Для запуска тестов RuleTester использует две функции: describe и it. Эти функции могут поступать из разных источников:

  1. Если RuleTester.describe и RuleTester.it заданы как значения-функции, RuleTester будет использовать RuleTester.describe и RuleTester.it для запуска тестов. Это позволяет настроить поведение RuleTester в соответствии с используемой вами тестовой платформой.

    Если RuleTester.itOnly задано как значение-функция, RuleTester будет вызывать RuleTester.itOnly вместо RuleTester.it для запуска случаев с only: true. Если RuleTester.itOnly не задано, но у RuleTester.it есть свойство-функция only, RuleTester будет использовать RuleTester.it.only в качестве резервного варианта.

  2. В противном случае, если describe и it доступны как глобальные переменные, RuleTester будет использовать globalThis.describe и globalThis.it для запуска тестов, а globalThis.it.only — для запуска случаев с only: true. Это позволяет RuleTester работать с такими платформами, как Mocha, без дополнительной настройки.

  3. В противном случае RuleTester#run просто выполнит все тесты последовательно и выбросит ошибку, если какой-либо из них завершится неудачей. Это означает, что можно просто выполнить тестовый файл, вызывающий RuleTester.run, с помощью Node.js, не используя тестовую платформу.

RuleTester#run вызывает функцию describe с двумя аргументами: строкой с описанием правила и функцией обратного вызова. Функция обратного вызова вызывает функцию it со строкой с описанием тестового случая и тестовой функцией. Тестовая функция завершится успешно, если тест пройден, и выбросит ошибку, если тест не пройден. Сигнатура only совпадает с сигнатурой it. RuleTester вызывает it или only для каждого случая, даже если для некоторых случаев задано only: true; за обеспечение исключительности тестовых случаев отвечает тестовая платформа. (Обратите внимание: это стандартное поведение тестовых наборов при использовании таких платформ, как Mocha; эта информация важна только в том случае, если вы планируете настраивать RuleTester.describe, RuleTester.it или RuleTester.itOnly.)

Пример настройки RuleTester:

"use strict";

const RuleTester = require("eslint").RuleTester,
	test = require("my-test-runner"),
	myRule = require("../../../lib/rules/my-rule");

RuleTester.describe = function (text, method) {
	RuleTester.it.title = text;
	return method.call(this);
};

RuleTester.it = function (text, method) {
	test(RuleTester.it.title + ": " + text, method);
};

// then use RuleTester as documented

const ruleTester = new RuleTester();

ruleTester.run("my-rule", myRule, {
	valid: [
		// valid test cases
	],
	invalid: [
		// invalid test cases
	],
});

© OpenJS Foundation and other contributors
Licensed under the MIT License.
https://eslint.org/docs/latest/integrate/nodejs-api

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API