Методология оценки состояния проекта

Используйте оценку дашборда, чтобы определить, какие риски требуют внимания перед выпуском и как меняется состояние проекта после исправлений. Балл объединяет результаты проверок, а его расшифровка показывает вклад каждой области.

На дашборде есть два уровня оценки:

1. аудит проекта по двенадцати вопросам Q1–Q12, шкала 0–10;
2. итоговый Health Score, шкала 0–100, который объединяет Audit, Compliance, Release, SCA и Quality.

Разбирайте балл вместе с его составом, источником данных и временем расчёта. Результат аудита Q1–Q12 хранится в quality_assessment. Исторические оценки по секциям сохраняются отдельно с отметкой о совместимости.

Аудит использует Code Property Graph (CPG) — граф структуры кода, вызовов и потоков данных. Как GoCPG строит и обогащает этот граф, описано в статье «Как GoCPG строит CPG и чем этот подход отличается от Joern». Модель компонентов, архитектурный DSL, presets, baseline/waiver и release profiles собраны отдельно в руководстве по контролю архитектуры. Штатный порядок запуска и разбора результата приведён в руководстве по аудиту проекта на основе CPG.

Как оценивается аудит Q1–Q12

У каждого фактора есть стабильный ID и версионируемое определение: риск, совокупность объектов, к которым он применим, источники свидетельств, единица измерения, нормализация, формула, пороги, применимость и ограничения. В таблице приведён состав текущей модели unified-quality.v1.

Вклад данных и балл фактора

У каждой канонической находки или метрики есть один основной фактор. Отчёт может сослаться на те же данные в другом разделе. В расчёте их вклад учитывается один раз. Находка, рассчитанная из метрики, сохраняет идентификатор исходных данных.

Модель переводит каждый принятый вклад в badness — меру неблагополучия на отрезке [0, 1]. Версия определения задаёт преобразование, вес, пороги и ограничения по риску:

uncapped_score = 10 × (1 - min(1, sum(weight × badness)))
factor_score = min(uncapped_score, применимые risk_cap)

Если ограничений risk_cap нет, балл равен uncapped_score.

В текущей модели все двенадцать факторов имеют одинаковый вес. Изменение весов, нормализации или порогов требует новой версии модели и отдельного решения о калибровке. В отчёте сохраняются model_version, контрольная сумма основы, ревизии исходников и CPG, доступные возможности анализа, реестр подтверждающих данных и ограничения.

Оценки секций классического аудита

Классический отчёт дополнительно сохраняет оценку каждой Q-секции. Для находок суммируется вес W с убывающим вкладом повторов, после чего применяется формула:

section_score = 10 × exp(-0.3 × W)

Для Q10 исходная оценка покрытия рассчитывается отдельно:

coverage_score = 10 × (0.82 × method_coverage + 0.18 × line_coverage)

Затем применяются поправки на риск непокрытых методов. Верхняя граница корректировки общего классического балла равна overall_score_raw + 3.5 по умолчанию; установка может изменить предел через audit_overall_score_max_uplift. Эти значения остаются в отчёте для объяснения классического аудита и совместимости. Они не заменяют факторные оценки unified-quality.v1 и не разрешают расчёт при неполных обязательных данных.

Полнота данных и общий балл

Фактор получает статус measured, partial, unavailable или not_applicable. Неподдерживаемые факты, ошибки запроса, отсутствующие знаменатели и неполное покрытие CPG остаются явными. Они не превращаются в ноль или нейтральный проходной балл.

Общий балл считается как взвешенное среднее применимых факторов только тогда, когда все применимые факторы полны и в отчёте нет блокирующих ограничений. В остальных случаях score_eligible=false, а overall_score=null. Дополнительные границы:

• для Q10 используйте структурную тестируемость вместе с фактическим покрытием тестами, когда оно требуется профилем проекта;
• для Q4 и Q5 сопоставляйте графовые метрики с измерениями времени выполнения и пропускной способности;
• для Q12 проверяйте содержание документов и результаты ревью;
• полнота возможностей анализа и свежесть CPG проверяются при любом количестве находок.

Исторические оценки совместимости

Старые отчёты могут содержать severity-weighted оценки секций, metric penalties, module_health и числовой overall_score. CodeGraph сохраняет исходную версию этих значений либо помечает их как legacy-unversioned, если версия не была записана. Текущие отчёты используют балл своей версии модели. Повторный расчёт из полного набора сохранённых исходных данных создаёт отдельную оценку со ссылкой на источник.

Как оцениваются остальные компоненты

Compliance

Отчёт ГОСТ Р 56939 присваивает каждому применимому процессу статус:

• full = 1;
• partial = 0,5;
• gap = 0;
• n_a исключается из знаменателя.

compliance_score = 100 × сумма process_value / число применимых процессов

Если применимых процессов нет, результат равен 0. Отчёт сохраняет список критических пробелов вместе с итоговым процентом.

Release

Release Gate запускает набор проверок выбранного профиля. Каждая проверка имеет severity blocker или warning:

• любой непройденный blocker → fail;
• blocker нет, но есть непройденный warning → warn;
• все проверки пройдены → pass.

Неизвестный профиль, ошибка проверки или отказ авторизации дают запрет по умолчанию. В стандартном профиле critical-замечания запрещены, high-замечания ограничены пятью, средняя цикломатическая сложность — 15, а покрытие должно быть не ниже 55%. Последние две проверки — warnings. Профили gost-56939, standard и minimal имеют разные наборы требований, поэтому рядом со статусом следует читать идентификатор профиля и результаты отдельных проверок.

SCA

SCA-компонент использует количество уязвимостей зависимостей по уровню серьёзности:

sca = clamp(1 - 0.15 × critical - 0.08 × high - 0.02 × medium, 0, 1)

Low и info в эту формулу не входят, но остаются в SCA-отчёте. Формула не заменяет анализ достижимости: она оценивает сохранённый severity summary.

Quality

Quality объединяет четыре показателя: фактическое покрытие строк тестами — 40%, покрытие документацией — 20%, долю используемого кода — 20% и сложность — 20%. В формуле доля используемого кода равна 1 - dead_code_ratio, а вклад сложности уменьшается по мере роста её среднего значения.

complexity_norm = min(avg_complexity / 20, 1)
quality = 0.40 × runtime_line_coverage
        + 0.20 × documentation_coverage
        + 0.20 × (1 - dead_code_ratio)
        + 0.20 × (1 - complexity_norm)

Все доли лежат в диапазоне 0–1. Если фактическое покрытие строк недоступно, его вклад равен нулю и причина недоступности сохраняется в score_breakdown.

Итоговый Health Score

Текущая версия score_formula_version — v1. По умолчанию:

health_score = 100 × clamp(
  0.30 × audit/10
  + 0.25 × compliance/100
  + 0.20 × release
  + 0.15 × sca
  + 0.10 × quality,
  0, 1
)

Для Release используются значения pass = 1, warn = 0,5, fail = 0. Установка может переопределить веса, поэтому score_breakdown конкретного ответа важнее значений по умолчанию из документации.

Пример расчёта

Для иллюстрации возьмём полный набор данных: Audit = 8, Compliance = 80%, Release = pass, одна high-уязвимость и две medium-уязвимости зависимостей. Critical-уязвимостей нет. Покрытие строк равно 75%, документации — 60%, доля мёртвого кода — 10%, средняя сложность — 10.

Сначала рассчитайте компоненты: SCA = 1 - 0,08 - 2 × 0,02 = 0,88. Quality = 0,40 × 0,75 + 0,20 × 0,60 + 0,20 × 0,90 + 0,20 × 0,50 = 0,70.

Сумма вкладов даёт Health Score = 84,2, оценку B и риск low для заданных входов. При расчёте каждый взвешенный вклад округляется до двух знаков перед суммированием.

Что означает «Источник оценки»

Блок показывает не ещё одну формулу, а происхождение данных каждой Q-секции:

• current — секция пересчитана из метрик текущей ревизии;
• snapshot — текущих метрик недостаточно, использован свежий снимок аудита;
• stale_snapshot — доступен только устаревший снимок;
• n_a — секция неприменима к этому проекту;
• needs_audit — надёжной текущей основы или снимка нет.

Дашборд пересчитывает только те Q-секции, для которых есть надёжное метрическое соответствие. Например, Q6 остаётся needs_audit без полноценного архитектурного аудита. Снимок по умолчанию считается свежим не дольше 168 часов, но установка может изменить этот срок. Сверяйте ссылки на источники, идентификатор ревизии и время получения доказательств.

Отдельно поверхность проекта может иметь состояния current, stale, missing, updating, failed или unknown. Высокая оценка на устаревшем либо неизвестном основании не разрешает выпуск.

Когда итог недоступен

Сначала проверяйте health_score_available, затем число. При отсутствии обязательных доказательств CodeGraph возвращает оценку N/A и риск unknown. Поле health_score при этом может сохранять числовое значение внутреннего расчёта. При health_score_available=false не используйте его как доступную оценку проекта. Стабильные причины включают:

• audit_snapshot_missing;
• compliance_report_missing;
• release_gate_missing;
• sca_summary_missing.

Причина недоступности указывает, какие данные нужно восстановить или получить заново.

Оценки и уровни риска

Ниже приведены пороги по умолчанию. Установка может переопределить пороги оценок и риска.

Риск учитывает и рабочие сигналы: critical при балле < 40, critical finding или compliance < 40; high при балле < 55 или Release fail; medium при балле < 70 или Release warn; иначе low.

Воспроизводимая проверка

python -m src.cli dashboard health 'PROJECT' --format json

Выполняйте команду в PowerShell из корня исходного репозитория CodeGraph с установленным Python-окружением. Замените PROJECT именем зарегистрированного проекта. Для содержательной оценки нужны его CPG и сохранённые свидетельства аудита, compliance, release и SCA. При недоступной оценке сначала прочитайте причины в ответе и восстановите соответствующие данные.

Проверяйте вместе health_score_available, score_formula_version, score_breakdown, risk_level, снимок аудита и основу анализа. Повторение на той же ревизии доказательств должно дать тот же результат.

Команда по умолчанию использует --basis-mode best_effort. Параметр --basis-mode require_coherent_audit_basis включает строгую проверку основы. При несогласованной основе команда завершает работу с кодом 2. С --format json ответ содержит blocked=true и объект analysis_basis: прочитайте его причину и рекомендуемое действие. Для просмотра основы в JSON выполните python -m src.cli dashboard basis 'PROJECT' --format json. Доступность рассчитанного балла указана в health_score_available.

Связанные руководства

• Аудит проекта на основе CPG — получить и разобрать результаты Q1–Q12.
• Руководство пользователя дашборда — найти показатели и перейти к их источникам.
• Эксплуатация дашборда — обновить данные и проверить состояние проекта.
• Мониторинг — настроить сбор метрик и оповещения.