Documentation
¶
Overview ¶
Package engine runs rules over an OpenAPI document and scores the result.
It knows nothing about any particular ruleset. A rule is a function over a spec.Document that records, through a Context, each place it looked and each place it found a problem. Recording the places it looked is what makes a score possible: a rule that checked 40 parameters and found 2 without a description is doing much better than one that checked 3 and found 2, and a bare count of findings cannot tell those apart.
Index ¶
- type CategoryScore
- type Context
- func (c *Context) Check(ok bool, op string, node *yaml.Node, ptr, msg string)
- func (c *Context) CheckWeighted(ok bool, weight float64, op string, node *yaml.Node, ptr, msg string)
- func (c *Context) Fail(op string, node *yaml.Node, ptr, msg string)
- func (c *Context) Option(name string) int
- func (c *Context) Pass()
- type Finding
- type Options
- type Report
- type Rule
- type RuleResult
- type Severity
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type CategoryScore ¶
type CategoryScore struct {
Name string
Score float64
// Applicable is false when no rule in the category found anything to
// check. Such a category is left out of the overall score.
Applicable bool
}
CategoryScore is the severity-weighted mean of a category's applicable rule scores, from 0 to 100.
type Context ¶
Context is what a rule reports through.
func (*Context) CheckWeighted ¶
func (c *Context) CheckWeighted(ok bool, weight float64, op string, node *yaml.Node, ptr, msg string)
CheckWeighted is Check for a place that should count for more or less than one in the score. The finding is reported the same either way; only its share of the rule's score changes.
func (*Context) Fail ¶
Fail records a place the rule looked and found a problem. node is used for the file, line and column; pass the most specific node available.
type Finding ¶
type Finding struct {
Rule string `json:"rule"`
Severity Severity `json:"-"`
Category string `json:"category"`
Message string `json:"message"`
// Operation is the label of the operation the finding belongs to, or ""
// for document-level findings.
Operation string `json:"operation,omitempty"`
// File is the file the finding is in, or "" for the root document.
File string `json:"file,omitempty"`
Pointer string `json:"pointer"`
Line int `json:"line"`
Column int `json:"column"`
}
Finding is one problem at one place.
type Options ¶
type Options struct {
// Ignore reports whether a finding has been accepted. An ignored finding
// is kept in RuleResult.Suppressed and counts as a pass.
Ignore func(Finding) bool
}
Options adjusts a run.
type Report ¶
type Report struct {
Document string
Version string
Operations int
Rules []RuleResult
Categories []CategoryScore
// Score is the mean of the applicable category scores, from 0 to 100.
Score float64
// Skipped lists remote files that could not be fetched, so the schemas
// behind them were not checked. A report with any is incomplete, and
// its score describes only the part of the spec that was reached.
Skipped []spec.Skip
// Stale lists remote files checked from the cache because they could
// not be fetched this run.
Stale []string
}
Report is the outcome of running a ruleset over one document.
func Run ¶
Run applies rules to doc. Rules run in the order given, and categories are reported in the order they first appear in that list.
func (*Report) Findings ¶
Findings returns every reported finding, most severe first, then in document order.
func (*Report) Suppressed ¶
Suppressed returns the findings configuration chose to ignore, in the same order as Findings.
type Rule ¶
type Rule struct {
ID string // kebab-case, stable: it is how people configure a rule
Title string
Category string
Severity Severity
// Options are the rule's tunable thresholds and their current values.
// The keys a rule declares here are the only ones configuration may set.
Options map[string]int
Check func(*Context)
}
Rule is one check.
type RuleResult ¶
type RuleResult struct {
Rule *Rule
Checked int
// Failed counts findings that were reported. Suppressed findings are
// not in it: a finding someone has accepted counts as a pass.
Failed int
Findings []Finding
Suppressed []Finding
// Weight and FailedWeight are Checked and Failed with each place counted
// at its weight, and are what the score is computed from. They equal the
// counts unless the rule used CheckWeighted.
Weight, FailedWeight float64
}
RuleResult is how one rule did.
func (RuleResult) Applicable ¶
func (r RuleResult) Applicable() bool
Applicable reports whether the rule found anything to look at. A spec with no request bodies has nothing to say about request examples, and should neither gain nor lose for it.
func (RuleResult) Score ¶
func (r RuleResult) Score() float64
Score is the weighted fraction of checked places that passed, from 0 to 1.
type Severity ¶
type Severity int
Severity grades how badly a finding hurts.
const ( // Info is worth fixing but rarely stops an agent on its own. Info Severity = iota + 1 // Warning makes an agent more likely to pick the wrong operation or send // the wrong arguments. Warning // Error stops an agent outright, or makes the operation impossible to // expose as a tool without hand editing. Error )
func ParseSeverity ¶
ParseSeverity is the inverse of String. It returns 0 for anything else.
Source Files