Пользовательские парсеры

Пользовательские парсеры ESLint позволяют расширить ESLint для поддержки проверки нового нестандартного синтаксиса JavaScript или пользовательского синтаксиса в вашем коде. Парсер отвечает за преобразование вашего кода в абстрактное синтаксическое дерево (AST), которое затем может анализировать и проверять ESLint.

Создание пользовательского парсера

Методы в пользовательских парсерах

Пользовательский парсер — это объект JavaScript с методом parse() или parseForESLint(). Метод parse возвращает только AST, тогда как parseForESLint() также возвращает дополнительные значения, которые позволяют парсеру ещё больше настраивать поведение ESLint.

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

// customParser.js

const espree = require("espree");

// Logs the duration it takes to parse each file.
function parse(code, options) {
    const label = `Parsing file "${options.filePath}"`;
    console.time(label);
    const ast = espree.parse(code, options);
    console.timeEnd(label);
    return ast; // Only the AST is returned.
};

module.exports = { parse };

parse Объект возврата

Метод parse должен просто вернуть объект AST.

parseForESLint Объект возврата

Метод parseForESLint должен вернуть объект, содержащий необходимое свойство ast и необязательные свойства services, scopeManager, и visitorKeys.

• ast должен содержать объект AST.
• services может содержать любые зависящие от парсера сервисы (такие как проверки типов для узлов). Значение свойства services доступно правилам как context.sourceCode.parserServices. По умолчанию это пустой объект.
• scopeManager может быть объектом ScopeManager. Пользовательские парсеры могут использовать настраиваемый анализ области видимости для экспериментальных/улучшенных синтаксических конструкций. По умолчанию используется объект ScopeManager, созданный eslint-scope.
  • Поддержка scopeManager была добавлена в ESLint v4.14.0. Версии ESLint, которые поддерживают scopeManager, будут предоставлять свойство eslintScopeManager: true в parserOptions, которое можно использовать для обнаружения функциональности.
• visitorKeys может быть объектом для настройки обхода AST. Ключами объекта являются типы узлов AST. Каждое значение — массив имён свойств, которые должны быть обходятся. По умолчанию это ключи eslint-visitor-keys.
  • Поддержка visitorKeys была добавлена в ESLint v4.14.0. Версии ESLint, которые поддерживают visitorKeys, будут предоставлять свойство eslintVisitorKeys: true в parserOptions, которое можно использовать для обнаружения функциональности.

Метаданные в пользовательских парсерах

Для упрощения отладки и повышения эффективности кеширования пользовательских парсеров рекомендуется указать имя и версию в объекте meta в корне вашего пользовательского парсера, например:

// preferred location of name and version
module.exports = {
    meta: {
        name: "eslint-parser-custom",
        version: "1.2.3"
    }
};

Свойство meta.name должно соответствовать имени пакета npm для вашего пользовательского парсера, а свойство meta.version должно соответствовать версии пакета npm для вашего пользовательского парсера. Самый простой способ сделать это — прочитать эту информацию из вашего package.json.

Спецификация AST

AST, который должны создавать пользовательские парсеры, основан на ESTree. AST требует дополнительных свойств для подробной информации об исходном коде.

Все узлы

Все узлы должны иметь свойство range.

• range (number[]) — массив из двух чисел. Оба числа — индексы с нуля, представляющие положение в массиве символов исходного кода. Первое — начальная позиция узла, второе — конечная позиция узла. code.slice(node.range[0], node.range[1]) должен содержать текст узла. Этот диапазон не включает пробелы/скобки, которые находятся вокруг узла.
• loc (SourceLocation) не должно быть null. Свойство loc в ESTree определяется как необязательное, но ESLint требует этого свойства. Свойство SourceLocation#source может быть undefined. ESLint не использует свойство SourceLocation#source.

Свойство parent всех узлов должно быть перезаписываемым. Перед тем как правила получат доступ к AST, ESLint устанавливает свойство parent каждого узла в родительский узел во время обхода.

Узел Program

Узел Program должен иметь свойства tokens и comments. Оба свойства — массив с интерфейсом Token ниже.

interface Token {
    type: string;
    loc: SourceLocation;
    // See the "All Nodes" section for details of the `range` property.
    range: [number, number];
    value: string;
}

• tokens (Token[]) — это массив маркеров, которые влияют на поведение программ. Пробелы могут быть произвольными между маркерами, поэтому правила проверяют Token#range для обнаружения пробелов между маркерами. Это должно быть отсортировано по Token#range[0].
• comments (Token[]) — это массив маркеров комментариев. Это должно быть отсортировано по Token#range[0].

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

Узел Literal

Узел Literal должен иметь свойство raw.

• raw (string) — исходный код этого литерала. Это то же самое, что и code.slice(node.range[0], node.range[1]).

Упаковка пользовательского анализатора

Чтобы опубликовать ваш пользовательский анализатор в npm, выполните следующие действия:

1. Создайте пользовательский анализатор, следуя разделу Создание пользовательского анализатора выше.
2. Создайте пакет npm для пользовательского анализатора.
3. В вашем файле package.json установите поле main как файл, который экспортирует ваш пользовательский анализатор.
4. Опубликуйте пакет npm.

Для получения дополнительной информации об публикации пакета npm, обратитесь к документации npm.

После публикации пакета npm, вы можете использовать его, добавив пакет в свой проект. Например:

npm install eslint-parser-myparser --save-dev

Затем добавьте пользовательский анализатор в ваш файл конфигурации ESLint со свойством parser. Например:

// .eslintrc.js

module.exports = {
  parser: 'eslint-parser-myparser',
  // ... rest of configuration
};

Чтобы узнать больше о использовании анализаторов ESLint в вашем проекте, обратитесь к Настройка анализатора.

Пример

Для сложного примера пользовательского анализатора обратитесь к @typescript-eslint/parser исходному коду.

Простой пользовательский анализатор, который предоставляет метод context.sourceCode.parserServices.foo() для правил.

// awesome-custom-parser.js
var espree = require("espree");
function parseForESLint(code, options) {
    return {
        ast: espree.parse(code, options),
        services: {
            foo: function() {
                console.log("foo");
            }
        },
        scopeManager: null,
        visitorKeys: null
    };
};

module.exports = { parseForESLint };

Включите пользовательский анализатор в файл конфигурации ESLint:

// .eslintrc.json
{
    "parser": "./path/to/awesome-custom-parser.js"
}