readable — еще один линтер для PHP

Хочу представить линтер для PHP readable. Сейчас в нем 16 правил, которые должны улучшить читабельность кода. К основным преимуществам можно отнести:

• скорость — меньше секунды на 1000 файлов
• настройка baseline — можно не исправлять все ошибки в проекте сразу, а создать конфигурацию с текущими ошибками. И игнорировать их, но реагировать на новые.
• правила писать проще чем в аналогах (субъективно)

Важные два дисклаймера:

1. Я основной контрибьютор, поэтому могу быть субъективным. Изначально, readable написан для бельгийской компании officient. Они уже некоторое время его используют у себя внутри, и решили сделать readable открытым проектом.
2. Он написан на JS.

Установка и запуск

readable устанавливаеться через npm:

$ npm install @officient/readable --save-dev

После установки, надо создать конфигурационный файл:

$ npx readable --init

И можно запускать:

$ npx readable

Правила

Сейчас в readable 16 правил:

1. namespace-max-files — максимальное количество файлов в неймспейсе
2. argument-override — запрет изменения значения аргументов функции
3. file-max-size — максимальное количество строк в файле
4. empty-catch — запрет на пустой catch блок
5. class-comment — перед объявлением класса должен быть какой-нибудь комментарий, что этот класс делает
6. forbidden-functions — список запрещенных функций (eval, print_r ...)
7. missing-braces — обязательные скобки в блоке после if, for ...
8. variable-length — минимальная длина имени переменной (можно добавлять исключения $id, $i)
9. function-max-size — максимальная длина функции
10. loop-max-size — максимальная длина цикла
11. forbidden-function-prefix — запрет на определенные слова в начале имени функции. Например, checkSomething — возвращает булево значение, или бросает исключение?
12. if-assigment — присваивание внутри условия if
13. complex-if — смешивание && и || внутри условия if
14. ternary-max-length — максимальная длина строки с тернарным оператором
15. loop-max-nest — максимальная вложенность циклов
16. max-nest — максимальная вложенность блоков

Создание правил и внутренняя особенность

readable при проверки файла не строит синтаксическое дерево, а просто разбивает входной файл на массив токенов. Это — существенное отличие от аналогов. Возможно, это где-то ограничивает возможности, но с другой стороны:

1. readable быстрее. Так как, построение дерева из токенов довольно ресурсоёмкая задача.
2. Правила писать субъективно проще. Потому что, не надо разбираться в конкретном представлении синтаксического дерева.

Давайте для примера возьмем правило loop-max-size. Весь его код:

const loops = ['for', 'foreach'];

module.exports = {
  check(maxLines, tokens, report) {
    tokens.matchAll(loops, (token) => {
      const end = token.copy().step().stepToClosing(); // skip ()
      end.step().stepToClosing();
      const lines = (end.current().line - token.current().line);
      if (lines > maxLines) {
        report(`Loop is longer than ${maxLines} lines [${lines}].`, token.current());
      }
    });
  },
};

В правиле указано:

1. найти все for и foreach.
2. Взять следующий токен .step(), это будет открывающая скобка (. Дойти до закрывающей скобки .stepToClosing().
3. Повторить второй шаг но уже для тела цикла ({ и }).
4. Проверить длину тела цикла.

Вместо заключения

Я использую readable в своих проектах как дополнительный линтер для кода. Мне все нравится, особенно baseline (справедливости ради, такое есть и в Psalm). У него есть возможность занять нишу именно вспомогательного линтера.