Inspect and export GoCPG architecture results

Use this reference after defining a policy and running the production architecture check for a repository. It covers the CLI, typed gRPC methods, canonical result identity, SARIF and diagram projections, and failure diagnostics. You need the rule YAML for validate and describe; explain and the result RPCs additionally need a persisted DuckDB run ID. Read model and rules for authoring and execution and governance for the gate.

CLI Reference

The architecture command group contains three read-only commands:

From the repository root in PowerShell, with gocpg on PATH. Check command availability with gocpg architecture --help. If it is missing, build the current GoCPG version and use the new binary path in the commands below:

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

The first response should report example.ui-no-storage, applicable: true and gate_evaluated: false. The second should identify the component UID cmp-example-ui. A zero exit from validate is not enough: an unselected language can return applicable: false without a command error. Invalid YAML, an unknown component and a missing file produce a nonzero diagnostic exit.

After a production run has stored a finding, use its actual run_id and fingerprint, not the placeholders below:

gocpg architecture explain --db .gocpg/cpg.duckdb --run-id RUN_ID --fingerprint FINDING_FINGERPRINT --json

explain requires a CGO-enabled build and reads existing results. It does not evaluate another graph. The group has no general command for executing an arbitrary architecture rule; the production path is described in execution and governance.

GRPC Reference

QueryService has five typed, read-only architecture methods: GetArchitectureResults, ExportArchitectureResults, ValidateArchitectureResults, DescribeArchitectureResults, and ExplainArchitectureFinding. The canonical wire definitions are in gocpg/api/proto/gocpg/v1/query_service.proto in the CodeGraph source checkout. To read a persisted result, identify its database and run_id; explain also requires a finding fingerprint. The methods load the canonical result from DuckDB and return its description, validation, explanation, or export.

The db field follows the server’s database path resolution: a relative selector is resolved under serve --data-dir. The source checkout and rules must still be accessible to the server when a separate parse or scan request needs them. For a local server that exposes reflection, this PowerShell command illustrates a typed read; replace the run ID with one returned by a completed production check:

grpcurl -plaintext -d '{"db":"projects/shop-api/cpg/current.duckdb","run_id":"RUN_ID"}' `
  127.0.0.1:50051 gocpg.v1.QueryService/DescribeArchitectureResults

The JSON response from grpcurl uses runId, projectKey, commitHash, executionMode, findingCount and complete. Match runId to the requested run, commitHash to the evaluated revision, and findingCount to the stored findings. The protobuf definition names these fields run_id, project_key, commit_hash, execution_mode and finding_count; complete stays the same. For NOT_FOUND, check the db selector and persisted run ID: the server found no matching record in that database. For an export INVALID_ARGUMENT, select a format from the table below. Invalid canonical identity also produces an error. In a remote deployment, use the configured TLS and authorization metadata described in the external gRPC guide.

Choose an export format

Call ExportArchitectureResults with the same db and run_id used to inspect the run, and set format:

The response contains the selected format, content type mediaType, and file bytes in content. In the JSON response from grpcurl, content is Base64-encoded: decode it before saving the file. A typed gRPC client receives the bytes directly. For JSON, check run.run_id and run.commit_hash in the decoded file; for SARIF, check version 2.1.0 and the results array. Keep diagrams alongside the canonical JSON to retain the run and finding details.

JSON Schema Reference

The canonical result binds a run to project, repository revision, execution mode, completeness, model and rule hashes, governance revision, coverage, every active rule’s outcome, findings and semantic digest. A finding records rule, contract, stable component UIDs, fingerprint and version, semantic hash, lifecycle state, relation evidence, and source locations. The run ID selects one persisted result; the fingerprint selects one finding within it.

ExportArchitectureResults validates run identity, supported execution mode, unique and recomputable fingerprints before writing a successful projection. Deterministic array ordering lets consumers compare the same run reliably. Decoding JSON is only a format check: release logic must also inspect completeness, rule outcomes and gate decision. The DuckDB table and column contract is in gocpg/docs/api/schema.md in the CodeGraph source checkout.

For example, a response with complete: false and an empty findings array does not prove there are no forbidden dependencies. Verify the evaluated commit and the recorded completeness reason before interpreting the count.

SARIF Mapping

One canonical finding becomes one SARIF result. The exporter copies identity and evidence; it does not reclassify source files or revise a baseline:

Use the canonical fingerprint to join SARIF results with the persisted run. Messages and URI rendering can change without changing finding identity. The exporter validates run and finding identity. Check analysis completeness in the canonical JSON. Keep that JSON alongside SARIF: it contains the run ID and component UIDs.

Mermaid and PlantUML Export Guide

graph_json contains the run description, component nodes involved in findings, and the edges for those findings. Each node has its UID in id; each edge has source, target, finding_fingerprint and edge_type. Mermaid and PlantUML show source-to-target direction and label edges with rule IDs. Diagram node identifiers replace special UID characters with underscores; PlantUML also displays the original UID as a label. Use the canonical JSON for the full finding records.

Compare revision, model hash, rules hash and semantic digest before comparing diagrams from two runs. A changed diagram may reflect a changed source or model instead of a newly introduced dependency. A diagram cannot approve a waiver or change a gate decision.

Troubleshooting Guide

Start with the gate status and reason codes. Separate a complete run with violations from an incomplete run before editing rules:

NOT_APPLICABLE is expected for discovery or advisory. FAIL_VIOLATIONS means a complete enforcing run found active violations. BLOCKED_INCOMPLETE means the evidence cannot support an enforcing decision. Use validate for rule applicability, describe for the compiled component model, and explain for one existing finding. These commands cannot repair missing CPG facts or substitute for a full production run.

Executable examples for the normative topics

Run from the gocpg module root. These tests check CLI, typed results, projections and the zero-denominator failure path in the implementation:

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