Это руководство объясняет, как результат архитектурного анализа становится решением о выпуске. Оно предназначено для владельцев репозиториев и операторов CI, у которых уже есть проверенная модель и CPG нужной ревизии. Начните с модели и правил, чтобы определить компоненты и контракты. Для изучения выходных данных используйте интерфейсы и результаты.
gocpg architecture validate проверяет только схему правила и применимость языка. Рабочему процессу CI нужны политика проекта, ключ проекта, документ управления выпуском и выходной файл. Также требуется подтверждение, что граф, факты, модель и правила относятся к проверяемому коммиту.
Выберите профиль для этапа внедрения
Начните с discovery, когда ещё определяете компоненты. Используйте advisory, чтобы рассмотреть находки и настроить политику вместе с командой. После фиксации базового долга enforce_new проверяет новые нарушения. Выберите enforce_all, когда выпуск должен учитывать и существующий долг, или strict, когда требуется полная матрица проверок, включая пустые выборки.
Профиль задаёт отношение к находкам, а полнота входных данных определяет, может ли система принять блокирующее решение.
Профили условий выпуска
Проверка оценивает полноту доказательств до подсчёта находок. Требуются актуальный CPG, полный запуск или эквивалентный инкрементальный запуск, результат каждого активного правила, все обязательные возможности, известные знаменатели зависимостей, покрытие классификации и разрешения зависимостей, а также доверенные решения управления.
| Профиль | Обработка находок | Решение |
|---|---|---|
discovery |
Помогает построить модель и классифицировать сущности. | NOT_APPLICABLE |
advisory |
Показывает находки, пока команда проверяет политику. | NOT_APPLICABLE |
enforce_new |
Блокирует новые находки без исключений. | PASS или FAIL_VIOLATIONS при полных доказательствах. |
enforce_all |
Блокирует новые и известные находки без исключений. | PASS или FAIL_VIOLATIONS при полных доказательствах. |
strict |
Применяет полную матрицу проверок, включая пустые выборки. | PASS или FAIL_VIOLATIONS при полных доказательствах. |
Любой блокирующий профиль возвращает BLOCKED_INCOMPLETE, если входные данные устарели, неполны, неизвестны или не заслуживают доверия. Только PASS устанавливает release_allowed=true. NOT_APPLICABLE означает, что блокирующее решение не запрашивалось. Для запуска без разрешённых фактов зависимостей нужен известный знаменатель: пустой результат не позволяет заявить покрытие разрешения 100%.
Ниже приведена форма вызова CI для рабочего репозитория. Запускайте её из корня репозитория в PowerShell. Нужны gocpg в PATH, базовая ссылка Git и четыре пути, настроенные для одного проекта. Замените пути и ключ проекта своими. Политика — это манифест политики репозитория, а не отдельное правило kind: architecture, используемое командой architecture validate.
При первом запуске создайте каталог вывода и постройте CPG из того же корня репозитория. Команда ci-update использует сохранённую привязку CPG к исходникам; для отсутствующей базы архитектурный запуск возвращает git_source_scope_unavailable.
New-Item -ItemType Directory -Force .gocpg | Out-Null
gocpg parse --input . --output .gocpg/cpg.duckdb --lang python
Затем обновите граф и получите архитектурный артефакт:
gocpg ci-update --input . --output .gocpg/cpg.duckdb `
--base-ref origin/main --head-ref HEAD --lang python `
--architecture-policy .gocpg/architecture/policy.yaml `
--architecture-project-key my-repository `
--architecture-release-control .gocpg/architecture/release-control.yaml `
--architecture-artifact .gocpg/architecture/result.json --json
Четыре архитектурных флага передаются вместе. Минимальный документ управления выпуском для рассмотрения находок может выбрать advisory, но всё равно должен соответствовать текущей схеме и требованиям к доказательствам репозитория. Проверьте идентичность запуска, полноту, результаты правил и статус условий выпуска в выходном файле. Успешного кода завершения CLI недостаточно для подтверждения PASS. Руководство по внедрению объясняет общую последовательность перехода.
Действие по результату
| Результат | Следующее действие |
|---|---|
PASS |
Используйте архитектурный результат в пакете приёмки выпуска. |
FAIL_VIOLATIONS |
Рассмотрите блокирующие находки: исправьте зависимости или получите решение об исключении для текущей области. Затем повторите анализ. |
BLOCKED_INCOMPLETE |
Проверьте ревизию CPG, полноту результатов правил и доверие к документу управления. Обновите недостающие входы и повторите запуск. |
NOT_APPLICABLE |
Рассмотрите результаты discovery/advisory и выберите блокирующий профиль, когда политика готова к применению. |
Базовый набор известных находок
Базовый набор фиксирует уже рассмотренный долг для точного правила, версии отпечатка, отпечатка находки и семантического хеша правила. В enforce_new точная известная находка исключается из числа новых нарушений. enforce_all и strict продолжают учитывать известный долг без исключений. Базовый набор подтверждает рассмотрение находки, но не делает зависимость допустимой и не изменяет граф.
Например, UI импортирует хранилище. Если отпечаток рассмотрен как существующий долг, следующий идентичный запуск может считать находку известной. При смене direct на transitive меняется семантический хеш: прежнее решение переходит в needs_review. Если импорт исчезает и затем возвращается, находка считается повторно появившейся, а не автоматически известной.
Безопасная последовательность: полный запуск, рассмотренное предложение для каждой находки, выпуск подписанного манифеста управления плоскостью управления, затем новый запуск с привязкой к этому манифесту. Локальные выгрузки базового набора помогают проверить изменения, но не разрешают подавление находок.
Исключения и доверие
Исключение относится к одной находке и имеет срок действия. Оно содержит владельца правила, заявителя, согласующего, причину, ссылку на решение, отпечаток, семантический хеш, версию отпечатка и область действия. Заявитель и согласующий должны быть разными участниками. Изменение отпечатка, правила, репозитория или ревизии требует нового решения. Псевдоним символа не переносит исключение.
Подписываемые данные Ed25519 связывают проект, репозиторий, коммит, ветку, хеши модели и правил, период действия и монотонную ревизию. Доверенные публичные ключи и состояние отзыва поступают из плоскости управления или конфигурации CI. Проверяются подпись, ID ключа, отзыв, срок действия и точная область. Истёкшие, отозванные, неиспользованные и устаревшие исключения остаются видимыми находками. Ошибка подписи или области блокирует проверку с BLOCKED_INCOMPLETE.
Например, исключение подписано для коммита A, а политика проверяется на B. Не копируйте отпечаток в локальный YAML для подавления находки. После полного запуска получите решение для текущей области.
Инкрементальные проверки
Планировщик использует изменённые пути и UID затронутых компонентов, чтобы решить, можно ли повторно использовать работу. Изменения модели, публичного API, рёбер зависимостей, сильно связных компонент, базового набора и исключений расширяют область пересчёта. Неизвестные компоненты или неполная область пересчёта вызывают ошибку. По умолчанию полный запуск выбирается, если доля затронутых компонентов превышает 0.20. Изменение модели всегда требует полного запуска.
incremental_complete имеет полномочия для выпуска только при совпадении отпечатков, состояний жизненного цикла, базового набора и исключений, покрытия, семантического хеша и решения с полным запуском на тех же данных. Неполный блокирующий запуск получает одну синхронную полную повторную попытку. Если она неполна, завершилась ошибкой, устарела или не совпадает, результат остаётся BLOCKED_INCOMPLETE.
Например, перенос src/ui/ в новый компонент изменяет классификацию и может затронуть рёбра вне списка изменённых файлов. Поэтому изменение модели запускает полный анализ. Проверка только изменённых файлов пропустила бы связи переклассифицированных сущностей.
Переход с прежних проверок
Для прежних проверок выбирается решение: migrate, retain advisory, retire или defer. Режимы discovery и advisory могут показывать явно помеченные прежние доказательства. Но прежний результат не создаёт канонический PASS, состояние находки, базовый набор, исключение или разрешение выпуска.
- Перечислите прежние обработчики и наборы правил; назначьте каждому решение.
- Выполните прежний и канонический процессы параллельно на одной ревизии. Классифицируйте различия по устойчивому отпечатку и подтверждающим исходникам.
- Квалифицируйте эталонные примеры и устраните необъяснённые блокирующие пропуски нарушений.
- Наблюдайте два реальных цикла выпуска в advisory с устойчивой семантической идентичностью.
- Переведите потребителей на сохранённые канонические результаты и подтвердите отключение прежней блокирующей проверки.
Откат может вернуть блокирующий режим в advisory. Он не даёт прежней проверке полномочий разрешать выпуск. Локальная проверка совпадения подтверждает только свои тестовые данные, а не промышленное внедрение.
Проверки реализации
Из корня модуля gocpg эти тесты проверяют контракты реализации. Они не доказывают, что произвольный репозиторий прошёл условия выпуска.
go test ./pkg/architecture -run '^TestSignedGovernanceRequiresExactScopeAndSeparationOfDuties$' -count=1
go test ./pkg/architecture -run '^TestNormativeGovernanceRequiresCompleteScopeRevisionAndRevocationState$' -count=1
go test ./pkg/architecture -run '^TestNormativeReleaseGateFiveProfilesAndStateMatrix$' -count=1
go test ./pkg/architecture -run '^TestStory1240FullIncrementalEquivalence$' -count=1
go test ./pkg/architecture -run '^TestCodeGraphReleaseGateRejectsLegacyAuthorityInEnforceNew$' -count=1