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

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

Примечание: Использование недокументированных частей API происходит на ваш страх и риск. Только те части API, которые специально указаны в этом документе, одобрены для использования и будут оставаться стабильными и надёжными. Любые недокументированные части 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 (ConfigData | ConfigData[] | null)
  По умолчанию null. Объект конфигурации, расширенный всеми конфигурациями, используемыми с этим экземпляром. Вы можете использовать эту опцию для определения значений по умолчанию, которые будут использоваться, если ваши файлы конфигурации их не задают.
• options.overrideConfig (ConfigData | ConfigData[] | null)
  По умолчанию null. Объект конфигурации, переопределяет все конфигурации, используемые с этим экземпляром. Вы можете использовать эту опцию для определения настроек, которые будут использоваться, даже если ваши файлы конфигурации их задают.
• options.overrideConfigFile (string | boolean)
  По умолчанию false. Путь к файлу конфигурации, переопределяет все конфигурации, используемые с этим экземпляром. Опция options.overrideConfig применяется после применения этой опции.
• 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, к результатам проверки добавляется дополнительная статистика (см. Тип статистики).

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

• 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. В этом случае вам нужно вручную удалить файл кэша. Метод eslint.lintText() не использует кэш, даже если вы передаёте options.filePath в метод.
• options.cacheLocation (string)
  По умолчанию .eslintcache. Метод eslint.lintFiles() записывает кэши в этот файл.
• options.cacheStrategy (string)
  По умолчанию "metadata". Стратегия для использования кэша для определения изменённых файлов. Может быть либо "metadata", либо "content".

Другие опции

• options.flags (string[])
  По умолчанию []. Флаги функций, которые необходимо включить для этого экземпляра.

◆ eslint.lintFiles(patterns)

const results = await eslint.lintFiles(patterns);

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

Параметры

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

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

• (Promise<LintResult[]>)
  Обещание, которое будет выполнено с массивом объектов 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[]>)
  Обещание, которое будет выполнено с массивом объектов 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>)
  Обещание, которое будет выполнено с объектом конфигурации.

◆ eslint.isPathIgnored(filePath)

const isPathIgnored = await eslint.isPathIgnored(filePath);

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

Параметры

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

Значение возврата

• (Promise<boolean>)
  Обещание, которое будет выполнено со значением, игнорируется ли файл или нет. Если файл игнорируется, то возвращается 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>)
  Обещание, которое будет выполнено с объектом 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.outputFixes(results)

await ESLint.outputFixes(results);

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

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

Параметры

• results (LintResult[])
  Объекты LintResult, которые нужно записать.

Значение возврата

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

◆ ESLint.getErrorResults(results)

const filteredResults = ESLint.getErrorResults(results);

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

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

Параметры

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

Значение возврата

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

◆ Тип LintResult

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

• filePath (string)
  Абсолютный путь к файлу этого результата. Это строка "<text>" если путь к файлу неизвестен (когда вы не передали опцию options.filePath методу eslint.lintText()).
• 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[] }[])
  Информация о устаревших правилах, которые использовались для проверки этого файла.

◆ Тип 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])
  Пара индексов с нулевой базой в тексте исходного кода для удаления.
• 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 и может содержать только свойство maxWarningsExceeded, которое будет передано в объект context при вызове функции форматирования. Обратите внимание, что ESLint автоматически генерирует свойства cwd и rulesMeta объекта context, поэтому обычно нет необходимости передавать второй аргумент при вызове этого метода.

loadESLint()

Функция loadESLint() используется для интеграций, которые хотят поддерживать как текущую систему конфигурации (плоская конфигурация), так и старую систему конфигурации (eslintrc). Эта функция возвращает правильную реализацию класса 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
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 удаляет BOM Unicode. Обратите внимание, что 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 или вызовом context.getCwd() (см. Объект контекста). Если 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 или при вызове context.getCwd(). Те, которые запущены на 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 - идентификатор сообщения, используемого для генерации сообщения (это свойство опущено, если правило не использует идентификаторы сообщений).
• nodeType - (Устаревшее: это свойство будет удалено в будущей версии ESLint.) тип узла или токена, о котором сообщалось с проблемой.
• ruleId - идентификатор правила, которое сгенерировало сообщения (или null, если fatal имеет значение true).
• severity - 1 или 2, в зависимости от вашей конфигурации.
• endColumn - конечный столбец диапазона, в котором произошла ошибка (это свойство опущено, если это не диапазон).
• endLine - конечная строка диапазона, в котором произошла ошибка (это свойство опущено, если это не диапазон).
• fix - объект, описывающий исправление проблемы (это свойство опущено, если исправление недоступно).
• suggestions - массив объектов, описывающих возможные исправления lint для редакторов, чтобы программно включить (см. подробности в документации по работе с правилами).

Вы можете получить подавленные сообщения из предыдущего запуска с помощью метода 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/ }]
        }
    ]
});

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

const ruleTester = new RuleTester({ languageOptions: { ecmaVersion: 2015 } });

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

• Название правила (строка)
• Объект правила (см. “Работа с правилами”)
• Объект, содержащий свойства valid и invalid, каждое из которых — массив, содержащий тестовые случаи.

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

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

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

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

  • message (строка/регулярное выражение): Сообщение об ошибке. Должно быть указано или messageId
  • messageId (строка): Идентификатор ошибки. Должно быть указано или message. См. тестирование ошибок с messageId для получения подробностей
  • data (объект): Данные-заполнитель, которые можно использовать в сочетании с messageId
  • type (строка): (Устаревшее: это свойство будет удалено в будущей версии ESLint.) Тип отчётного узла AST
  • line (число): Номер строки (с учётом 1) отчётного местоположения
  • column (число): Номер колонки (с учётом 1) отчётного местоположения
  • endLine (число): Номер строки (с учётом 1) конца отчётного местоположения
  • endColumn (число): Номер колонки (с учётом 1) конца отчётного местоположения
  • suggestions (массив): Массив объектов с деталями предложений для проверки. Требуется, если правило генерирует предложения. См. Тестирование предложений для подробностей

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

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

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

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

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

Тестирование ошибок с 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; . Если результат после применения исправления не совпадает, то тест завершается неудачей.

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

Предложения можно проверить, определив ключ 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
    ]
})