Гигиена кода

Две независимые команды, которые обращают внимание человека на что-то важное, ничего не меняя в коде: empty-catch находит обработку ошибок, которая молча ничего не делает, todo-report собирает разбросанные по проекту заметки TODO/FIXME/HACK в один список. Обе только для чтения.

empty-catch

Находит catch-блоки, которые ничего не делают с ошибкой, или делают настолько мало, что по факту её проглатывают.

devtoolz empty-catch [paths...] [options]

Полностью пустой catch (e) {} — простой случай, уже покрыт ESLint-правилом no-empty. Настоящая ценность — catch, тело которого состоит только из вызовов console.* (любой метод — console.debug/console.info проглатывают ошибку ровно так же, как console.log) и ничего больше: без throw, без записи в переменную внешней области видимости, без return с осмысленным значением. Синтаксически такой код абсолютно корректен, обычные lint-правила его не поймают — нужна семантическая проверка, а не синтаксическая.

Реальный вывод — catch-блок, который только логирует ошибку:

Scanned 1 file.

1 problem found:
  src/example.ts:4:5  console-only  only logged, never handled — silently swallowed either way

Комментарий освобождает находку от отчёта

Комментарий внутри catch-блока — найденный через реальный сканер токенов, а не текстовый поиск, так что // внутри строки его не собьёт с толку — убирает находку из отчёта, тот же принцип, что у ESLint-правила no-empty для документированных пустых блоков:

try {
  await api.save(draft)
} catch (e) {
  // best-effort autosave — a failed one just means the user's next
  // keystroke retries it, nothing to surface to them
}

Это не попадёт в отчёт — комментарий воспринимается как уже принятое человеком решение, а не как то, что всё ещё требует решения.

.vue-файлы

Блок <script> проверяется тем же путём через парсер TypeScript, что и любой другой файл — та же конвенция, которую console-strip и весь остальной набор используют для Vue-компонентов.

Опции

[paths...]

Файлы/директории для обработки (по умолчанию: текущая директория).

--cwd <path>

Относительно чего резолвятся корневые пути.

--ext <list>

Список расширений через запятую. По умолчанию: .ts,.tsx,.js,.jsx,.cjs,.mjs,.vue.

--ignore <glob>

Дополнительный паттерн игнорирования (повторяемый) поверх встроенных по умолчанию.

--no-respect-gitignore

Не учитывать также .gitignore проекта.

Намеренно без --fix — единственно правильного способа реально обработать ошибку не существует, решение остаётся за человеком.

Пример:

devtoolz empty-catch src              # сканировать директорию
devtoolz empty-catch src --json       # машиночитаемый вывод

todo-report

Сводка по TODO/FIXME/HACK-комментариям в проекте — file:line плюс сам текст заметки.

devtoolz todo-report [paths...] [options]

Комментарии находятся так же, как и везде в наборе — реальным проходом токенайзера, с предварительным маскированием всех строк/шаблонов/regex/JSX-текста — так что строка вида const s = "TODO: not a real one" никогда не будет принята за находку. Тег матчится как отдельное слово в любом месте комментария (// see TODO above тоже считается, как и в большинстве редакторов с подсветкой TODO), регистронезависимо — но в отчёте тег всегда показывается ровно в настроенном написании, а не в том, что реально было в исходнике.

Реальный вывод — TODO, обёрнутый на несколько строк // подряд, и однострочный FIXME:

Scanned 2 files.

2 comments found (TODO: 1, FIXME: 1):
  src/notes.ts:1:4  TODO   TODO: this endpoint still uses the v1 auth header format — migrate to the bearer-token scheme once the backend team ships the v2 endpoint, see ticket INFRA-482 for the rollout plan
  src/notes.ts:8:4  FIXME  FIXME: race condition when two tabs save at once

Обёрнутые заметки склеиваются в одну строку

Настоящая заметка часто пишется в несколько строк // подряд, или в одну строку /* */-блока — тег есть только на первой из них. Команда продолжает поглощать последующие строки того же комментария в текст заметки, пока они не пустые и сами не начинают новую помеченную заметку, так что в отчёте видна вся мысль целиком, а не обрезанная на середине предложения. Пример выше (src/notes.ts:1:4) — как раз такой случай: три физические строки //, одна находка в отчёте.

--tags — какие метки искать

devtoolz todo-report src --tags NOTE,REVIEW

Матчатся только настроенные теги — TODO/FIXME в исходнике полностью игнорируются, если --tags настроен на что-то другое:

Scanned 2 files.

Nothing found. Somebody already did their homework.

--max — порог вместо жёсткого нуля

Проект, который осознанно живёт с текущим долгом, не обязательно хочет, чтобы каждый прогон падал. --max <n> заставляет команду падать, только когда находок больше этого числа:

Scanned 2 files.

2 comments found (TODO: 1, FIXME: 1):
  src/notes.ts:1:4  TODO   TODO: this endpoint still uses the v1 auth header format — migrate to the bearer-token scheme once the backend team ships the v2 endpoint, see ticket INFRA-482 for the rollout plan
  src/notes.ts:8:4  FIXME  FIXME: race condition when two tabs save at once

Within the configured limit (--max 5).

Без --max по умолчанию действует жёсткий 0 — падает любая найденная заметка, тот же простой дефолт, что и у dead-exports.

.vue-файлы

Блок <script> проходит через тот же путь токенайзера, что и любой другой файл; комментарии <!-- --> внутри <template> находятся построчным сканом — та же конвенция, что у strip-comments'а собственной обработки <template>, включая то же известное ограничение: без полноценного SFC-парсера шаблонов строка вида <!-- --> внутри значения атрибута будет ошибочно принята за настоящий комментарий.

Опции

[paths...]

Файлы/директории для обработки (по умолчанию: текущая директория).

--cwd <path>

Относительно чего резолвятся корневые пути.

--tags <list>

Список тегов через запятую. По умолчанию: TODO,FIXME,HACK.

--max <n>

Не падать, пока находок не больше этого числа. По умолчанию: 0 (падает на любой находке).

--ext <list>

Список расширений через запятую. По умолчанию: .ts,.tsx,.js,.jsx,.cjs,.mjs,.vue.

--ignore <glob>

Дополнительный паттерн игнорирования (повторяемый) поверх встроенных по умолчанию.

--no-respect-gitignore

Не учитывать также .gitignore проекта.

Пример:

devtoolz todo-report src                   # теги по умолчанию, падает на любой находке
devtoolz todo-report src --tags NOTE       # искать только свой тег
devtoolz todo-report src --max 20          # не падать, пока находок не больше 20