Cogna Policy Rules

This directory contains the built-in OPA Rego policies for cogna check.

Structure

policies/
  compat.rego   # all built-in compatibility rules (package cogna.compat)

OPA Entrypoint

data.cogna.compat.deny

Rule metadata contract

Every deny output object must include:

• rule_id: canonical rule id (for example compat.go.signature-changed)
• level: error | warning | note
• message: human-readable summary
• path: source path in diff payload
• docs: canonical policy documentation URL

Canonical docs URL pattern:

https://cogna.xaclabs.dev/docs/policies#rule-<rule_id_with_dots_replaced_by_dashes>

Example for compat.go.signature-changed:

https://cogna.xaclabs.dev/docs/policies#rule-compat-go-signature-changed

Built-in rule index

core

• compat.core.removed-declaration — Public declaration was removed and callers will break.
• compat.core.new-declaration — Public declaration was added.
• compat.core.deprecated-declaration — Public declaration became deprecated.

go

• compat.go.pointer-receiver-changed — Go pointer receiver compatibility changed.
• compat.go.receiver-changed — Go receiver type changed.
• compat.go.method-set-shrunk — Go method set shrank.
• compat.go.method-set-expanded — Go method set expanded and needs review.
• compat.go.signature-changed — Go public signature changed.

rust

• compat.rust.became-unsafe — Rust public item became unsafe.
• compat.rust.extern-abi-added — Rust extern ABI was added.
• compat.rust.extern-abi-changed — Rust extern ABI changed.
• compat.rust.where-clause-changed — Rust where-clause changed.
• compat.rust.signature-changed — Rust public signature changed.

terraform

• compat.terraform.provider-ref-changed — Terraform provider reference changed.
• compat.terraform.prevent-destroy-added — Terraform prevent_destroy was added.
• compat.terraform.create-before-destroy-added — Terraform create_before_destroy was added.
• compat.terraform.ignore-changes-expanded — Terraform ignore_changes expanded.
• compat.terraform.lifecycle-changed — Terraform lifecycle metadata changed.
• compat.terraform.input-became-required — Terraform input became required and callers must update configuration.
• compat.terraform.output-removed — Terraform output was removed and downstream references can break.

openapi

• compat.openapi.http-method-changed — OpenAPI HTTP method changed.
• compat.openapi.became-required — OpenAPI field or parameter became required.
• compat.openapi.status-codes-added — OpenAPI status codes were added.
• compat.openapi.media-types-added — OpenAPI media types were added.
• compat.openapi.operation-changed — OpenAPI operation changed.
• compat.openapi.response-status-removed — OpenAPI response status code was removed.
• compat.openapi.response-schema-narrowed — OpenAPI response schema narrowed and clients may fail to parse it.

component

• compat.component.version-upgrade — Software component version changed.
• compat.component.metadata-changed — Software component metadata changed.

Adding custom rules

Add new .rego files to this directory and keep package cogna.compat. For custom rules, follow the same metadata contract and set docs to a stable URL.

Helper functions in compat.rego