Используйте этот справочник после определения политики и выполнения рабочего архитектурного анализа репозитория. Он описывает CLI, типизированные методы gRPC, каноническую идентичность результата, представления SARIF и диаграмм, а также диагностику ошибок. Для validate и describe нужен YAML правила. Для explain и RPC результатов дополнительно нужен ID запуска, сохранённого в DuckDB. Подготовка описана в модели и правилах, условия выпуска — в выполнении и управлении.
Командная строка
Группа architecture содержит три команды только для чтения:
| Команда | Входные данные | Что проверить |
|---|---|---|
validate |
Файл правила и язык | applicable, reason_codes, gate_evaluated. |
describe |
Файл правила и UID или ID компонента | UID, селектор, родитель и непосредственные дочерние компоненты. |
explain |
DuckDB, ID канонического запуска и отпечаток находки | Правило, жизненный цикл, основное и связанные исходные положения, поток кода. |
Из корня репозитория в PowerShell, с gocpg в PATH. Проверьте доступность команды через gocpg architecture --help. Если она отсутствует, соберите текущую версию GoCPG и укажите путь к новому бинарнику в командах ниже:
gocpg architecture validate --file gocpg/docs/examples/architecture-control/architecture.yaml --language python --json
gocpg architecture describe --file gocpg/docs/examples/architecture-control/architecture.yaml --component ui --json
Первый ответ должен содержать example.ui-no-storage, applicable: true и gate_evaluated: false. Второй должен определить UID компонента cmp-example-ui. Нулевого кода завершения validate недостаточно: невыбранный язык может вернуть applicable: false без ошибки команды. Некорректный YAML, неизвестный компонент и отсутствующий файл вызывают диагностический ответ с ненулевым кодом.
После сохранения находки рабочим запуском используйте настоящие run_id и fingerprint, а не значения-заглушки:
gocpg architecture explain --db .gocpg/cpg.duckdb --run-id RUN_ID --fingerprint FINDING_FINGERPRINT --json
explain требует сборки с CGO и читает существующие результаты. Он не анализирует другой граф. В группе нет универсальной команды выполнения произвольного архитектурного правила. Рабочий процесс описан в выполнении и управлении.
GRPC
QueryService предоставляет пять типизированных методов архитектуры только для чтения: GetArchitectureResults, ExportArchitectureResults, ValidateArchitectureResults, DescribeArchitectureResults и ExplainArchitectureFinding. Канонические определения сообщений находятся в gocpg/api/proto/gocpg/v1/query_service.proto исходной рабочей копии CodeGraph. Для чтения сохранённого результата укажите БД и run_id; explain также требует отпечаток находки. Методы загружают канонический результат из DuckDB и возвращают его описание, проверку, объяснение или экспорт.
Поле db следует правилам разрешения путей сервера: относительный селектор разрешается внутри serve --data-dir. Если отдельный запрос разбора или анализа требует исходников и правил, они должны оставаться доступны серверу. Для локального сервера с отражением схемы команда PowerShell ниже показывает типизированное чтение. Замените ID запуска значением, полученным после завершённой рабочей проверки:
grpcurl -plaintext -d '{"db":"projects/shop-api/cpg/current.duckdb","run_id":"RUN_ID"}' `
127.0.0.1:50051 gocpg.v1.QueryService/DescribeArchitectureResults
В JSON-ответе grpcurl поля имеют имена runId, projectKey, commitHash, executionMode, findingCount и complete. Сверьте runId с запрошенным запуском, commitHash — с проверяемой ревизией, а findingCount — с числом сохранённых находок. В определении protobuf те же поля названы run_id, project_key, commit_hash, execution_mode и finding_count; имя complete совпадает. При NOT_FOUND проверьте селектор db и ID сохранённого запуска: сервер не нашёл запись в выбранной БД. При INVALID_ARGUMENT для экспорта выберите одно из значений format в таблице ниже. Некорректная каноническая идентичность также вызывает ошибку. В удалённой установке используйте настроенные TLS и метаданные авторизации из руководства gRPC.
Выбор формата экспорта
Вызовите ExportArchitectureResults с теми же db и run_id, что использовали для просмотра запуска, и укажите поле format:
format |
Результат | Для чего использовать |
|---|---|---|
json |
Канонический результат, application/json |
Сохранить запуск вместе с правилами, находками и идентичностью. |
sarif |
SARIF 2.1.0, application/sarif+json |
Передать находки в инструмент просмотра результатов анализа. |
graph_json |
Граф компонентов и находок, application/json |
Обработать узлы и связи программно. |
mermaid |
Диаграмма, text/vnd.mermaid |
Показать зависимости в документе с поддержкой Mermaid. |
plantuml |
Диаграмма, text/x-plantuml |
Получить изображение через PlantUML. |
Ответ содержит выбранный format, тип содержимого mediaType и байты файла в content. В JSON-ответе grpcurl поле content закодировано в Base64: декодируйте его перед сохранением файла. Типизированный gRPC-клиент получает байты непосредственно. Для JSON проверьте run.run_id и run.commit_hash в декодированном файле; для SARIF — версию 2.1.0 и массив результатов. Диаграммы используйте вместе с каноническим JSON, чтобы сохранить сведения о запуске и находках.
Схема JSON
Канонический результат связывает запуск с проектом, ревизией репозитория, режимом выполнения, полнотой, хешами модели и правил, ревизией управления, покрытием, результатом каждого активного правила, находками и семантическим хешем. Находка содержит правило, контракт, устойчивые UID компонентов, отпечаток и его версию, семантический хеш, состояние жизненного цикла, доказательства отношений и исходные положения. ID запуска выбирает один сохранённый результат. Отпечаток выбирает одну находку внутри него.
ExportArchitectureResults проверяет идентичность запуска, поддерживаемый режим выполнения, уникальность и возможность повторного вычисления отпечатков перед успешной записью представления. Детерминированный порядок массивов позволяет сравнивать один запуск. Разбор JSON проверяет только формат: логика выпуска также должна учитывать полноту, результаты правил и решение. Контракт таблиц и столбцов DuckDB описан в gocpg/docs/api/schema.md исходной рабочей копии CodeGraph.
Например, ответ с complete: false и пустым массивом findings не доказывает отсутствие запрещённых зависимостей. Перед трактовкой числа находок проверьте коммит и записанную причину неполноты.
Представление SARIF
Одна каноническая находка становится одним результатом SARIF. Экспорт копирует идентичность и доказательства. Он не переклассифицирует исходники и не изменяет базовый набор:
| Канонические данные | Поле SARIF |
|---|---|
| ID правила | ruleId |
| Контракт | Текст message.text |
| Сообщение и жизненный цикл | Сообщение результата и свойства |
| Основное подтверждение | locations[0] |
| Другие подтверждения | relatedLocations |
| Путь зависимости | codeFlows.threadFlows.locations |
| Отпечаток | fingerprints["gocpg/v1"] |
| Версия отпечатка | properties.fingerprintVersion |
| Семантический хеш | properties.semanticHash |
Связывайте результат SARIF с сохранённым запуском по каноническому отпечатку. Сообщения и представление URI могут изменяться без изменения идентичности находки. Экспорт проверяет идентичность запуска и находок. Полноту анализа проверяйте по каноническому JSON. Сохраните его рядом с SARIF: он содержит ID запуска и UID компонентов.
Диаграммы Mermaid и PlantUML
graph_json содержит описание запуска, узлы компонентов, участвующих в находках, и связи этих находок. Узел содержит UID в поле id; связь — source, target, finding_fingerprint и edge_type. Mermaid и PlantUML показывают направление от исходного компонента к целевому и подписывают связь ID правила. Идентификаторы узлов диаграммы заменяют специальные символы UID на подчёркивания; PlantUML также выводит исходный UID в подписи. Для полного набора данных о находках используйте канонический JSON.
Перед сравнением диаграмм двух запусков сравните ревизию, хеш модели, хеш правил и семантический хеш. Изменение диаграммы может отражать новые исходники или модель, а не новую зависимость. Диаграмма не разрешает исключение и не изменяет решение о выпуске.
Диагностика
Начните со статуса условий выпуска и кодов причин. До изменения правил отличите полный запуск с нарушениями от неполного:
| Причина | Первая проверка | Восстановление |
|---|---|---|
cpg_not_fresh |
Сравните коммит CPG и проверяемый коммит. | Перестройте факты для точного коммита. |
execution_not_complete |
Изучите ошибки разбора и проходов анализа. | Завершите полный запуск; для неполной блокирующей проверки допускается только одна полная повторная попытка. |
capabilities_not_complete |
Проверьте обязательные факты каждого языка. | Выберите квалифицированный адаптер и профиль либо измените требования правила. |
coverage_not_complete |
Независимо проверьте знаменатели классификации и разрешения зависимостей. | Классифицируйте недостающие сущности и восстановите покрытие фактов. |
active_rule_result_missing |
Сравните число активных правил и результатов. | Найдите пропущенное правило до блокирующей проверки. |
dependency_coverage_unknown_or_empty |
Проверьте учитываемые факты зависимостей и знаменатель. | Восстановите набор фактов: ноль фактов не означает покрытие 100%. |
governance_needs_review |
Сравните отпечаток и семантический хеш с решением. | Рассмотрите находку и повторно выпустите решение для её области. |
NOT_APPLICABLE ожидается для discovery и advisory. FAIL_VIOLATIONS означает, что полный блокирующий запуск нашёл активные нарушения. BLOCKED_INCOMPLETE означает, что доказательства не поддерживают блокирующее решение. Используйте validate для применимости правила, describe для скомпилированной модели компонентов и explain для существующей находки. Эти команды не восстанавливают отсутствующие факты CPG и не заменяют полный рабочий запуск.
Проверки реализации
Запускайте тесты из корня модуля gocpg. Они проверяют CLI, типизированные результаты, представления и отказ при нулевом знаменателе:
go test ./cmd/gocpg -run '^TestArchitectureCLICommands$' -count=1
go test ./pkg/server -run '^TestQueryServiceArchitectureResultsTypedSurfaces$' -count=1
go test ./pkg/architecture -run '^TestCanonicalResultsPersistAndExportDeterministicEvidence$' -count=1
go test ./pkg/architecture -run '^TestResolutionCoverageZeroDenominatorIsIncompleteNotOneHundredPercent$' -count=1