Documentation
¶
Overview ¶
Package policy implements the declarative merge-policy gate behind the `commitbrief guard` command (ADR-0029). A policy is a small YAML document (`.commitbrief/policy.yml`) that caps how many findings of each severity a change may carry before it is blocked — a richer, opt-in alternative to the single `--fail-on=<severity>` threshold, aimed at gating high-volume (AI-authored) pull requests.
The gate evaluates the *actionable* finding set — the findings that survive baseline + inline suppression (signal control, ADR-0027) — because that is exactly what `--json` emits and what a human reviewer sees. Rule-id-scoped allow/deny lists are intentionally out of scope: findings carry no stable rule identifier (render.Finding is free-form LLM output), so a name-based rule list would be unreliable; that waits on a finding rule-id field.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrNotFound = errors.New("policy file not found")
ErrNotFound is returned by Load when the policy file does not exist.
Functions ¶
This section is empty.
Types ¶
type Policy ¶
type Policy struct {
// Version is the policy schema version. Only 1 is understood today.
Version int `yaml:"version"`
// Thresholds maps a severity ("critical".."info") to the maximum number
// of findings of that severity allowed before the gate blocks. A severity
// absent from the map — or present with a null/`~` value — is unlimited.
Thresholds map[render.Severity]*int `yaml:"thresholds"`
// Total is an optional cap on the total number of actionable findings.
// nil means no overall cap.
Total *int `yaml:"total"`
}
Policy is the parsed `.commitbrief/policy.yml` document.
func Load ¶
Load reads and validates a policy file. A missing file is reported as a distinct error (errors.Is(err, ErrNotFound)) so the caller can tell "no policy configured" from "policy is malformed".
func Parse ¶
Parse decodes + validates a policy document. Unknown keys are rejected so a typo (e.g. "threshold:") is a hard error, never a silent no-op.
func (*Policy) Evaluate ¶
Evaluate counts the findings by severity and checks them against the policy. findings must be the actionable set (post baseline + suppression). The returned Verdict is deterministic: Counts always has all five severities, and Violations are ordered critical→info, then "total".
type Verdict ¶
type Verdict struct {
Passed bool `json:"passed"`
Counts map[string]int `json:"counts"`
Total int `json:"total"`
Violations []Violation `json:"violations"`
}
Verdict is the result of evaluating findings against a Policy.
type Violation ¶
type Violation struct {
// Severity is the breached severity, or "total" for the overall cap.
Severity string `json:"severity"`
// Allowed is the configured maximum; Actual is the observed count.
Allowed int `json:"allowed"`
Actual int `json:"actual"`
}
Violation is a single breached limit.
Source Files