Флаг --fix и его поведение

Механизм работы автоматических исправлений

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

Каждое правило в ESLint может возвращать объект исправления через API контекста:

  • context.report({ fix(fixer) { ... } })

Исправления агрегируются и применяются после завершения анализа файла. В результате файл перезаписывается уже с учётом внесённых изменений.

Ключевой момент: автоматические правки не являются побочным эффектом линтинга, они выполняются отдельным этапом, что позволяет сначала собрать все ошибки, затем применить изменения атомарно.

Типы исправлений и их ограничения

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

  • замена узлов AST (replace)
  • удаление диапазона кода (remove)
  • вставка текста (insert)

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

  • meta.fixable: "code" — исправления, затрагивающие синтаксис и структуру
  • meta.fixable: "whitespace" — исправления, связанные с форматированием

Если правило не имеет fixable, флаг --fix его игнорирует.

Примеры типичных автоматических исправлений:

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

Алгоритм применения исправлений

Процесс применения --fix можно разложить на несколько этапов:

  1. Парсинг файлов и построение AST
  2. Запуск всех включённых правил
  3. Сбор сообщений об ошибках и предупреждениях
  4. Извлечение всех fix-операций
  5. Сортировка и проверка пересечений диапазонов изменений
  6. Применение безопасных исправлений
  7. Повторный линтинг (в некоторых случаях)

Особое значение имеет проверка конфликтующих фиксов. Если два исправления затрагивают один и тот же диапазон кода, ESLint может:

  • применить только одно из них
  • либо пропустить оба, если есть риск повреждения кода

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

Безопасность автоматических исправлений

ESLint придерживается принципа «safe fix only». Это означает, что любые изменения должны гарантированно сохранять поведение программы.

По этой причине:

  • не применяются исправления, меняющие логику выполнения
  • игнорируются потенциально неоднозначные трансформации
  • предпочтение отдаётся локальным изменениям текста

Например, правило может предложить исправление, но оно не будет применено, если существует риск изменения семантики:

  • переименование идентификаторов
  • перестройка цепочек вызовов
  • изменение порядка выражений

Поведение при запуске CLI

Флаг используется на уровне командной строки:

eslint src --fix

В этом режиме ESLint:

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

Важный аспект: если файл содержит ошибки, но ни одно правило не поддерживает автоматическое исправление, файл остаётся без изменений.

При использовании в больших проектах --fix часто комбинируется с указанием конкретных директорий:

eslint "src/**/*.{js,ts}" --fix

Влияние конфигурации правил

Поведение --fix напрямую зависит от конфигурации ESLint:

  • включённые правила определяют набор возможных исправлений
  • уровень строгости (error, warn) не влияет на применимость фикса
  • отключённые правила не участвуют в генерации исправлений

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

Конфликты и порядок применения

При наличии нескольких правил, изменяющих один участок кода, возникает конкуренция исправлений. ESLint применяет их с учётом внутреннего порядка:

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

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

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

Повторный запуск линтера после фиксов

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

Пример сценария:

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

Поэтому результат работы --fix не всегда является финальным состоянием кода с точки зрения всех правил.

Ограничения системы автоматического исправления

Флаг --fix имеет ряд системных ограничений:

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

Дополнительно ESLint не гарантирует, что повторный запуск с --fix не изменит результат, если правила взаимодействуют сложным образом.

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

В CI/CD --fix применяется ограниченно, поскольку изменение файлов во время сборки может быть нежелательным. Типовые сценарии:

  • локальное использование перед коммитом
  • pre-commit хуки
  • форматирование кода перед пушем

В автоматизированных пайплайнах чаще используется режим проверки без фиксации:

eslint src

или с генерацией отчёта.

Поведение с частичными изменениями файлов

ESLint не заменяет файл целиком, а применяет точечные изменения. Это означает:

  • сохраняются не затронутые участки файла
  • сохраняются комментарии (если они не затронуты фиксом)
  • минимизируется дифф при изменениях

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

Взаимодействие с парсерами и современными конфигурациями

В современных конфигурациях ESLint (flat config и новые версии парсеров) механизм --fix остаётся неизменным по концепции, но зависит от корректной работы AST.

Если парсер:

  • некорректно строит AST
  • теряет диапазоны токенов

то автоматические исправления могут быть неточными или частично отключёнными.

Это особенно критично при использовании нестандартных синтаксисов (TypeScript, JSX, экспериментальные предложения ECMAScript).

Оглавление