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

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

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

Одно число не заменяет исходные доказательства. Перед решением о выпуске нужно проверить состав оценки, её источник и свежесть. Современный отчёт публикует quality_assessment как канонический результат Q1-Q12. Исторические оценки по секциям остаются явно помеченными данными совместимости и не заменяют отсутствующий канонический балл.

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

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

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

Вклад evidence и балл фактора

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

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

factor_score = 10 × (1 - min(1, sum(weight × badness)))

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

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

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

section_score = 10 × exp(-0.3 × W)

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

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

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

Нехватка evidence и общий балл

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

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

• Q10 может показать структурную тестируемость, но runtime coverage остаётся отдельным требованием, если оно обязательно для профиля проекта;
• структурные proxy Q4 и Q5 не доказывают runtime throughput или capacity;
• наличие docstring для Q12 не доказывает правильность и полезность документации;
• пустой список находок не исправляет отсутствующую capability или устаревший CPG.

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

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

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

Compliance

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

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

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

Если применимых процессов нет, результат равен 0, а не 100. Список critical gaps остаётся отдельным доказательством: одинаковый процент не означает одинаковый профиль пробелов.

Release

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

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

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

SCA

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

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

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

Quality

В Quality по умолчанию используются веса: runtime coverage — 40%, documentation coverage — 20%, dead-code ratio — 20% и complexity — 20%. В итоговом Health Score веса такие: audit — 30%, compliance — 25%, release — 20%, SCA — 15% и quality — 10%.

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 конкретного ответа важнее значений по умолчанию из документации.

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

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

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

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

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

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

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

• 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

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

Источники истины

• src/workflow/scenarios/_audit_utils.py — соответствие Q1–Q12 сценариям.
• src/workflow/scenarios/audit_scoring/ — severity, метрики, Q10 и итог Audit.
• src/api/services/dashboard/aggregation_core/aggregation_snapshot_mixin.py — происхождение данных секций и пересчёт по снимку.
• src/compliance/gost_56939/models.py — Compliance.
• src/release/gate.py и config.yaml — Release Gate.
• src/api/services/dashboard/aggregation_core/aggregation_scoring_mixin.py — SCA, Quality, Health Score, оценки и риск.
• src/config/runtime_sections/unified_config_dashboard.py — веса и пороги по умолчанию.

Маршруты и действия описаны в руководстве пользователя, а телеметрия — в руководстве по мониторингу.