Флаг --report-unused-disable-directives

Флаг --report-unused-disable-directives предназначен для обнаружения неиспользуемых директив отключения правил ESLint. Его основная задача — выявлять случаи, когда комментарии вида eslint-disable, eslint-disable-line, eslint-disable-next-line или аналогичные больше не влияют на результат проверки кода.

В процессе развития проекта код изменяется: удаляются строки, переписываются функции, обновляются правила линтера. В результате некоторые директивы отключения становятся бесполезными, поскольку правило больше не вызывает ошибку или предупреждение в соответствующем участке кода. Такие комментарии засоряют кодовую базу и создают ложное впечатление о наличии проблем, которые необходимо подавлять.

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

Проблема неиспользуемых отключений

Рассмотрим пример:

/* eslint-disable no-console */

function greet(name) {
    return `Hello, ${name}`;
}

Комментарий отключает правило no-console, однако в файле отсутствуют вызовы console.log(), console.error() и другие обращения к объекту console.

С точки зрения ESLint директива стала бесполезной.

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

Базовое использование

Флаг добавляется в команду запуска ESLint:

eslint src --report-unused-disable-directives

Во время анализа ESLint дополнительно проверяет, использовалась ли каждая директива отключения хотя бы для одной проблемы.

Если директива не понадобилась, линтер сообщает об этом.

Например:

/* eslint-disable no-alert */

function sum(a, b) {
    return a + b;
}

Запуск:

eslint app.js --report-unused-disable-directives

Результат:

Unused eslint-disable directive (no problems were reported from 'no-alert')

Проверка директивы eslint-disable

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

Пример:

/* eslint-disable no-console */

console.log("Application started");

Здесь директива действительно используется, поскольку правило no-console могло бы сообщить об ошибке.

При включённом флаге предупреждение не появится.

Если же вызов console.log() удалить:

/* eslint-disable no-console */

const version = "1.0.0";

то ESLint сообщит о неиспользуемой директиве.

Проверка директивы eslint-disable-line

Директива может отключать правило только для текущей строки.

Пример:

const result = value == 10; // eslint-disable-line eqeqeq

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

После изменения кода:

const result = value === 10; // eslint-disable-line eqeqeq

нарушение исчезает.

При запуске ESLint с флагом:

eslint . --report-unused-disable-directives

будет найдено неиспользуемое отключение.

Проверка директивы eslint-disable-next-line

Аналогично работает и отключение для следующей строки.

Пример:

// eslint-disable-next-line no-console
console.log("Debug");

После удаления вызова:

// eslint-disable-next-line no-console
const debugMode = true;

директива становится ненужной.

Флаг позволяет быстро выявить такие ситуации.

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

Одна директива может отключать несколько правил одновременно.

Пример:

/* eslint-disable no-console, no-alert */

console.log("Message");

В данном случае используется только правило no-console.

Правило no-alert не участвует в подавлении ошибок.

При запуске проверки ESLint способен определить, что часть директивы не используется.

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

Типичный жизненный цикл отключения правила

Шаг 1. Возникновение ошибки

console.log("Debug");

ESLint сообщает:

Unexpected console statement.

Шаг 2. Добавление отключения

/* eslint-disable no-console */

console.log("Debug");

Ошибка исчезает.

Шаг 3. Изменение кода

const debugMessage = "Debug";

Использование console.log() удалено.

Шаг 4. Появление неиспользуемой директивы

Комментарий остаётся:

/* eslint-disable no-console */

const debugMessage = "Debug";

Теперь директива больше не нужна.

Шаг 5. Обнаружение проблемы

Команда:

eslint . --report-unused-disable-directives

сообщает о лишнем отключении.

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

В больших кодовых базах количество директив отключения может исчисляться сотнями или тысячами.

Например:

/* eslint-disable no-console */
/* eslint-disable no-alert */
/* eslint-disable no-unused-vars */
/* eslint-disable prefer-const */

После нескольких лет разработки часть таких комментариев теряет актуальность.

Проблемы возникают по нескольким причинам:

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

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

Совместное использование с CI/CD

Очень распространённый сценарий — запуск ESLint с данным флагом в конвейере непрерывной интеграции.

Пример:

eslint src --report-unused-disable-directives

Во время проверки pull request система автоматически обнаруживает лишние директивы.

Это помогает поддерживать чистоту кода без ручного аудита.

Пример фрагмента CI-конфигурации:

lint:
  script:
    - eslint src --report-unused-disable-directives

Если разработчик оставил ненужное отключение, проверка завершится сообщением об ошибке.

Отличие от обычной проверки ESLint

Стандартный запуск:

eslint .

ищет нарушения правил.

Например:

console.log("test");

будет найдено нарушение no-console.

Однако следующий код:

/* eslint-disable no-console */

const name = "John";

не вызовет замечаний.

Для ESLint по умолчанию наличие лишней директивы не считается проблемой.

После добавления флага:

eslint . --report-unused-disable-directives

линейтер начинает анализировать и сами директивы отключения.

Влияние на качество кодовой базы

Использование флага позволяет решить несколько задач одновременно.

Снижение технического долга

Старые отключения постепенно накапливаются и усложняют сопровождение проекта.

Регулярная проверка помогает избавляться от них автоматически.

Повышение доверия к комментариям

Когда в проекте встречается:

/* eslint-disable no-undef */

возникает ожидание, что правило действительно отключено по важной причине.

Если половина таких комментариев устарела, доверие к ним снижается.

Упрощение ревью кода

Во время анализа изменений становится проще понять, какие отключения действительно необходимы.

Более строгий контроль качества

Каждая директива должна иметь реальное назначение.

Ненужные исключения быстро выявляются и удаляются.

Типичные ошибки при использовании

Забытая директива после рефакторинга

Было:

// eslint-disable-next-line no-console
console.log(message);

Стало:

// eslint-disable-next-line no-console
sendMessage(message);

Директива больше не требуется.

Удаление проблемного кода

Было:

/* eslint-disable no-alert */

alert("Warning");

Стало:

/* eslint-disable no-alert */

showNotification("Warning");

Комментарий остался, но уже не выполняет никакой функции.

Удаление правила из конфигурации

Конфигурация:

{
    "rules": {
        "no-alert": "off"
    }
}

Код:

/* eslint-disable no-alert */

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

Пример комплексной проверки

Файл:

/* eslint-disable no-console */
/* eslint-disable no-alert */

const version = "1.0.0";

// eslint-disable-next-line eqeqeq
const result = value === 10;

В коде отсутствуют:

  • вызовы console;
  • вызовы alert;
  • нарушение правила eqeqeq.

Запуск:

eslint app.js --report-unused-disable-directives

позволит обнаружить все лишние отключения.

В результате разработчик сможет сократить файл до следующего состояния:

const version = "1.0.0";

const result = value === 10;

Рекомендации по использованию

Включение в ежедневную разработку

Наиболее эффективным считается постоянное использование флага при запуске линтера:

eslint src --report-unused-disable-directives

Проверка перед релизом

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

Регулярная очистка старых директив

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

Минимизация количества eslint-disable

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

Поведение в различных версиях ESLint

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

Флаг --report-unused-disable-directives превращает комментарии отключения правил в полноценный объект контроля. ESLint начинает отслеживать не только нарушения кода, но и актуальность самих исключений, что позволяет поддерживать конфигурацию линтинга чистой, понятной и соответствующей текущему состоянию проекта.

Оглавление