rating

Documentation

Overview

Package rating turns a run's per-check outcomes into a single repo health grade: a 0-100 score, a letter rating, a coarse verdict, and a per-check breakdown of what moved the score. It is deliberately decoupled from the rest of care (it knows nothing of Output/Report types) and from any feature catalog: each Check carries its own weight and cap, so the grading policy lives at the ecosystem where the checks are registered, not in a central feature->weight map here.

Index

• type Check
• type Contribution
• type Outcome
  • func (o Outcome) String() string
• type Result
  • func Evaluate(checks []Check) Result

Types

type Check

type Check struct {
	Feature string
	Outcome Outcome
	// Weight is the feature's relative importance; 0 (or negative) makes it
	// informational and excludes it from the score.
	Weight int
	// Cap is the worst score this check is allowed to leave standing when it fails,
	// active only when HasCap is set, so a genuine emergency (a committed secret)
	// cannot hide behind a good average.
	Cap    int
	HasCap bool
}

Check is one weighted input to the score: the feature that ran, how it fared, its weight in the average, and any score ceiling it imposes when it fails. Weight and Cap travel on the check itself (stamped from its ecosystem registration), so the engine grades without consulting an external policy map.

type Contribution

type Contribution struct {
	Feature   string  `json:"feature"`
	Outcome   string  `json:"outcome"`
	Weight    int     `json:"weight"`
	Points    float64 `json:"points"`
	Deduction float64 `json:"deduction"`
	Cap       *int    `json:"cap,omitempty"`
	Binding   bool    `json:"binding,omitempty"`
}

Contribution is one graded check's effect on the score: its outcome, the weight it carried, the points it scored (Pass=100, Warn=50, Fail=0), and Deduction, the points it cost the final average versus a clean pass. A failing capped check also reports the Cap it imposed and whether that cap was Binding (the ceiling that actually lowered the grade). Sorted by Deduction so the biggest culprit reads first.

type Outcome

type Outcome int

Outcome is one check's result, mirrored here so the rating engine carries no dependency on the core care types.

const (
	Pass Outcome = iota
	Warn
	Fail
	Skip
)

The outcomes a single check can report, ordered best to worst.

func (Outcome) String

func (o Outcome) String() string

String returns the lowercase wire label for an outcome.

type Result

type Result struct {
	Score     int            `json:"score"`
	Rating    string         `json:"rating"`
	Verdict   string         `json:"verdict"`
	Breakdown []Contribution `json:"breakdown,omitempty"`
}

Result is the computed grade: the numeric score, its letter rating, the coarse verdict tier, and the per-check breakdown explaining how the score was reached.

func Evaluate

func Evaluate(checks []Check) Result

Evaluate computes the grade as a weighted average of per-check scores (Pass=100, Warn=50, Fail=0), excluding skipped and zero-weight checks, then lowers it to the tightest ceiling any failing capped check imposes. With nothing weighted to grade, the score is a perfect 100 (nothing to flag). The returned Breakdown explains the result check by check.