forgeplan coverage

forgeplan coverage сверяет модули, обнаруженные forgeplan scan, с разделами Affected Files в каждом артефакте и сообщает, какие модули не имеют задокументированного решения. Непокрытые модули - это слепые пятна: код, который вы запускаете без какого-либо задокументированного обоснования.

Это представление проекта “знаем ли мы, почему это существует?”. В сочетании с drift (соответствуют ли ADRs по-прежнему коду?) оно обеспечивает полную сверку кодовой базы ⟷ артефактов.

Когда использовать

Архитектурный обзор: “какие модули полностью недокументированы?”
После рефакторинга, который разделил или объединил модули - повторное сканирование, пересчёт покрытия.
Онбординг: покажите новому члену команды, какие файлы имеют ADRs, которые он должен прочитать в первую очередь.
Заполнение устаревших данных: используйте --backfill для автоматической вставки разделов Affected Files в артефакты, созданные до требования о связывании модулей.

Когда НЕ использовать

До запуска forgeplan scan - для покрытия сначала требуется инвентаризация модулей.
В маленьких проектах с 1–2 файлами - сигнал низкий.

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

forgeplan coverage [OPTIONS]

Опции

      --backfill  Заполнить раздел "Affected Files" в отсутствующих артефактах
  -h, --help      Вывести справку
  -V, --version   Вывести версию

Примеры

Стандартный отчёт о покрытии

forgeplan scan         # обновить список модулей
forgeplan coverage

Вывод:

Decision coverage
─────────────────
covered (5):
  crates/forgeplan-core/src/scoring      ADR-001, PRD-005
  crates/forgeplan-core/src/lifecycle    ADR-005
  crates/forgeplan-core/src/db           ADR-002, ADR-003
  crates/forgeplan-core/src/search       PRD-039, RFC-006
  crates/forgeplan-cli/src/commands      RFC-001

uncovered (3) ⚠ blind spots:
  crates/forgeplan-core/src/fpf
  crates/forgeplan-core/src/routing
  crates/forgeplan-mcp/src/transport

overall coverage: 62% (5 of 8 modules)

Заполнение устаревших артефактов

forgeplan coverage --backfill

Добавляет раздел-заполнитель ## Affected Files в артефакты, у которых его нет, делая их видимыми для покрытия и drift в будущем. Вам всё равно придётся заполнять список вручную, но структура будет готова.

Фокус на непокрытых модулях

forgeplan coverage --json | jq '.uncovered[]'

Создаёт плоский список, который можно передать генератору бэклога: “напишите ADR для каждого непокрытого модуля”.

Интерпретация вывода

Раздел	Значение
covered	модуль → список артефактов, объявляющих его в `Affected Files`
uncovered	модуль с нулевыми ссылками на артефакты - задокументируйте обоснование!
overall	процент отсканированных модулей, имеющих хотя бы одно решение

Здоровый проект имеет покрытие выше 70%. Ниже 50% означает, что вы пишете код интуитивно. 100% обычно является избыточной документацией - некоторым служебным модулям не нужны ADRs.

Как это вписывается в рабочий процесс

scan → coverage → spot uncovered module → forgeplan new adr → link affected files → re-run

Покрытие - это инструмент “что мне документировать дальше?”. Оно превращает архитектурный обзор из “ощущений” в приоритизированный список.

См. также

forgeplan scan - заполнить инвентаризацию модулей
forgeplan drift - вторая половина сверки кодовой базы
forgeplan new adr - создать недостающую документацию
forgeplan health - включает покрытие в сводку на уровне проекта
Обзор CLI