VueCraft NPM

Doctor ​

polyrepo doctor — проверка состояния из семи разделов, в основном read-only диагностика плюс несколько небольших, безопасных автофиксов.

bash
polyrepo doctor [options]

Стоит запускать первым делом, если какая-то другая команда ведёт себя странно, в любой момент после переименования основной ветки на GitHub, или просто периодически, чтобы отловить накопившийся мусор до того, как его станет слишком много.

Реальный вывод — запуск на папке репозиториев, где серьёзно ничего не сломано, только два случая, которые doctor и существует, чтобы ловить:

Environment

  ✓ Node.js v22.23.2 (>= 20 required).
  ✓ git version 2.49.0.windows.1.
  ✓ gh version 2.69.0 (2025-03-19) — authenticated as macrulezru.
  ! npm 10.9.8 — not authenticated (only needed for `polyrepo publish`). Run `npm login`.

Config

Config file: C:\work\NPM\polyrepo.config.json
Checking 18 package(s)...
  ✓ 18 package(s) discovered.

Remote sync

Checking 18 package(s) against GitHub, and pruning stale remote-tracking refs...
  ✓ 18 package(s) checked — local default-branch cache matches GitHub.
  ✓ os-detect: pruned 2 stale remote-tracking ref(s) (add-more-examples, new-documentation-refactor).

Branch sync

Fetching and comparing 18 package(s) against origin...
  ✓ 18 package(s) checked — all in sync with origin.

Branch protection

Checking 18 package(s) for branch protection...
  ✓ 18 package(s) checked — default branch is protected on all of them.

Stale bump branches

Checking 18 package(s) for leftover bump branches with a merged PR...
  ✓ No stale bump branches found.

Cross-package dependencies

  ✓ No stale local dependency references found.

Незалогиненный npm — это только предупреждение (он нужен лишь команде publish); две почищенные ветки на os-detect — это ссылки на PR, давно смёрдженные и удалённые на GitHub. Именно doctor их замечает и убирает — больше в CLI это не делает никто.

Разделы ​

  1. Environment — версия Node.js (нужна 20+), есть ли git/gh/npm в PATH, и авторизованы ли gh/npm (авторизация npm — только предупреждение, она нужна лишь для publish).

  2. Config — сколько пакетов реально находит текущий конфиг, и какие репозитории грязные, находятся в состоянии detached HEAD, или не на своей основной ветке.

  3. Remote sync — два смежных фикса, оба — обновление локального указателя, никогда не трогающее файл, ветку или коммит:

    • сравнивает закешированное локально имя основной ветки репозитория с тем, что реально сообщает GitHub прямо сейчас. Git никогда не обновляет этот локальный кеш сам, так что переименование основной ветки на GitHub после клонирования иначе осталось бы незамеченным для всех остальных команд навсегда — там, где обнаружен дрейф, это чинится через git remote set-head origin --auto;
    • запускает git remote prune origin на каждом репозитории, убирая локальные ссылки remotes/origin/x, оставшиеся от веток, уже удалённых на GitHub.

    Оба пункта пропускаются для репозитория, до GitHub которого не удалось достучаться (офлайн, либо gh не авторизован).

  4. Branch sync — делает fetch и сравнивает локальную основную ветку каждого репозитория с origin/<default>: diverged (одновременно и опережает, и отстаёт — fast-forward не сработает, нужно решать руками), behind only (можно безопасно подтянуть через switch-default), либо ahead only (есть локальные коммиты, ещё не запушенные).

  5. Branch protection — реально ли включена защита основной ветки на GitHub у каждого репозитория прямо сейчас. Только отчёт — включение защиты это осознанное решение о политике, не то, что имеет смысл настраивать без спроса.

  6. Stale bump branches — bump мёрджит через PR, намеренно оставляя ветку на origin, так что каждый завершённый bump навсегда оставляет и локальную копию ветки тоже. Этот раздел показывает, сколько локальных веток совпадают с шаблоном <version>-version-bump и у них уже есть смёрдженный PR. См. --clean-branches ниже.

  7. Cross-package dependencies — не устарел ли у какого-то локального пакета диапазон dependencies/devDependencies/peerDependencies, указывающий на другой локальный пакет.

Опции ​

--clean-branches ​

Превращает раздел 6 в интерактивный чекбокс — выбираете, какие устаревшие локальные bump-ветки удалить. Использует git branch -d, который откажется, а не удалит принудительно, если ветка вдруг не до конца смёрджена локально. Ветка на origin никогда не трогается — её удаление не входит в задачу этой команды, это более чувствительное общее состояние, чем локальная ветка, которую никто больше не видит.

Пример:

bash
polyrepo doctor --clean-branches