Аудит проекта на основе CPG — Документация CodeGraph

CodeGraph использует единый pipeline аудита для CLI, дашборда, плановых запусков, сценариев, экспорта и истории. Профиль задаёт глубину проверки, но не переключает систему на другой движок аудита.

Это руководство пригодится для оценки проекта, разбора типовых дефектов и сравнения совместимых результатов. Отчёт помогает направить ревью, но не заменяет security gate или архитектурный release gate.

Выбор глубины

Выбор глубины
Режим	Профиль CLI	Объём и стоимость	Когда запускать
`quick`	`ci_fast`	Изменённые файлы и объявленное замыкание зависимостей; ограниченный набор проверок синтаксиса, символов, CFG и критичных правил.	Pull request и короткий цикл обратной связи.
`standard`	`standard`	Весь проект, архитектура, data flow и метрики качества.	Регулярный аудит и подготовка сопоставимой основы.
`deep`	`deep_security`	Стандартный режим плюс alias-sensitive, field-sensitive и feasibility-проверки в пределах явного бюджета.	Подтверждение сложных security- и data-flow-находок.

tests_light относится к профилям области GoCPG и не образует четвёртый режим аудита проекта. Для быстрого режима нужна реальная delta-основа. Если её нет, CodeGraph фиксирует пробел в данных и не рассчитывает оценку всего проекта.

Детерминированный стандартный аудит запускается из корня репозитория:

python -m src.cli audit --db <cpg.duckdb> --source-path <project-root> --profile standard --format json --output <audit.json> --skip-llm-conclusion --skip-persistence

База должна принадлежать настроенному проекту. Флаг --skip-persistence отключает запись проекций аудита, однако проверка свежести может обновить устаревший CPG. Если такая запись нежелательна, используйте временную или управляемую базу проекта.

Канонический результат

Сначала проверьте объект quality_assessment, а не поля совместимости:

pipeline_id содержит идентификатор unified_audit_pipeline.v1;
model_version задаёт версию расчётной модели;
mode и basis связывают результат с областью анализа и ревизией;
factors содержит Q1-Q12, их статус, оценку, покрытие и ограничения;
score_eligible разрешает или запрещает расчёт общего балла;
overall_score остаётся пустым при нехватке обязательных данных;
release_authority для оценки качества всегда равен false.

В исторических отчётах могут быть прежние оценки по секциям и общий балл. CodeGraph сохраняет их как явно помеченные данные совместимости. Они не заменяют недоступную каноническую оценку и не пересчитываются молча по новой модели.

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

Типовые дефекты

Единый отчёт проверяет три регулярно встречающихся класса:

Типовые дефекты
Класс	Что нужно для подтверждённой находки	Когда фиксируется пробел анализа
Magic number	AST-контекст, роль символа или вызова и применимая policy.	Константу нельзя безопасно классифицировать или язык не поддержан.
Swallowed exception	Свидетельство error flow: ошибка потеряна, а не передана, обработана или намеренно преобразована.	Call graph или модель обработки ошибок для языка неполны.
Несоответствие SQL схеме	Разобранный SQL, исполняемый call witness, владелец движка, идентификатор схемы, bind- и result-контракты.	SQL формируется динамически, схема не определена либо statement не покрыт parser/schema evidence.

Кандидат сканера ещё не считается дефектом приложения. Результат получает один из статусов: подтверждённая находка, обоснованное отсутствие дефекта, неподдерживаемый случай или пробел анализа. False positive попадает в backlog детектора, а отсутствующее свидетельство — в работу над покрытием анализа. Скрывать такие случаи через suppression приложения нельзя.

После исправления укажите одну из допустимых disposition: application_fix, detector_fix, approved_defer или evidence_gap. Повторите подходящий режим на той же основе сравнения; старый результат должен остаться неизменным.

Диагностические метрики

Метрики методов и классов версионируются. Запись содержит digest определения, языковой профиль, единицу измерения, идентификатор сущности, ревизии исходников и CPG, статус полноты и witnesses. Неподдерживаемые или неизмеримые значения остаются пустыми, а не превращаются в нули.

Percentile имеет смысл только внутри совместимой cohort с зафиксированным составом и достаточным размером выборки. Rename, move, split, merge, смена модели или определения могут прервать прямое сравнение. Верхний percentile Halstead и сложности служит подсказкой для ревью. Он не запускает автоматический рефакторинг и не переводится в часы или стоимость.

Очередь вмешательств

Отчёт может содержать intervention_prioritization.v1. Механизм группирует совместимые сигналы по стабильной сущности и структурной причине, а priority, urgency, readiness и confidence хранит раздельно. Очередь ограничена по размеру и иногда остаётся пустой.

Решение принимает человек. Очередь не меняет код, не открывает release gate и не доказывает причинную пользу. При нехватке данных эксперимент получает статус inconclusive; действующая основа сохраняется, пока проверка на замороженной выборке не пройдёт объявленные guardrails.

Когда оценку нельзя трактовать как чистую

Не используйте общий балл, если:

CPG устарел, неполон или относится к другой ревизии;
отсутствует обязательная capability или знаменатель eligible population;
детектор вернул неподдерживаемый или неразрешённый результат;
режим, версия модели, digest определения, область проекта или cohort несовместимы с результатом для сравнения;
score_eligible=false либо overall_score=null.

Восстановите доказательства и повторите тот же штатный запуск. Код завершения 0, пустой список находок или прежний числовой балл не исправляют неполный канонический результат.

Проектные архитектурные правила описаны в руководстве по контролю архитектуры. GoCPG загружает инварианты только из явно выбранных policy и release-control файлов и не подставляет правила CodeGraph при анализе другого проекта.