Version: v0.3.11 Latest Latest

This package is not in the latest version of its module.

Go to latest
Published: Sep 19, 2023 License: MIT Imports: 14 Imported by: 1




View Source
const (
	SeverityError        = "error"
	SeverityWarn         = "warn"
	SeverityInfo         = "info"
	SeverityHint         = "hint"
	CategoryExamples     = "examples"
	CategoryOperations   = "operations"
	CategoryInfo         = "information"
	CategoryDescriptions = "descriptions"
	CategorySchemas      = "schemas"
	CategorySecurity     = "security"
	CategoryTags         = "tags"
	CategoryValidation   = "validation"
	CategoryOWASP        = "OWASP"
	CategoryAll          = "all"
View Source
const (
	OAS2  = "oas2"
	OAS3  = "oas3"
	OAS31 = "oas3_1"


View Source
var AllFormats = []string{OAS3, OAS31, OAS2}
View Source
var OAS2Format = []string{OAS2}
View Source
var OAS3AllFormat = []string{OAS3, OAS31}
View Source
var OAS3Format = []string{OAS3}
View Source
var OAS3_1Format = []string{OAS31}
View Source
var RuleCategories = make(map[string]*RuleCategory)
View Source
var RuleCategoriesOrdered []*RuleCategory


func CompileRegex added in v0.0.44

func CompileRegex(context RuleFunctionContext, pattern string, results *[]RuleFunctionResult) *regexp.Regexp

CompileRegex attempts to compile the provided `Pattern` from the ruleset. If it fails, returns nil and adds an error to the result set. Any rule using this should then return the results if there is no *Regexp returned.

func ValidateRuleFunctionContextAgainstSchema

func ValidateRuleFunctionContextAgainstSchema(ruleFunction RuleFunction, ctx RuleFunctionContext) (bool, []string)

ValidateRuleFunctionContextAgainstSchema will perform run-time validation against a rule to ensure that options being passed in are acceptable and meet the needs of the Rule schema


type Example

type Example struct {
	Summary       string      `json:"summary,omitempty" yaml:"summary,omitempty"`
	Description   string      `json:"description,omitempty" yaml:"description,omitempty"`
	Value         interface{} `json:"value,omitempty" yaml:"value,omitempty"`
	ExternalValue string      `json:"externalValue,omitempty" yaml:"externalValue,omitempty"`

type Rule

type Rule struct {
	Id                 string         `json:"id,omitempty" yaml:"id,omitempty"`
	Description        string         `json:"description,omitempty" yaml:"description,omitempty"`
	Given              interface{}    `json:"given,omitempty" yaml:"given,omitempty"`
	Formats            []string       `json:"formats,omitempty" yaml:"formats,omitempty"`
	Resolved           bool           `json:"resolved,omitempty" yaml:"resolved,omitempty"`
	Recommended        bool           `json:"recommended,omitempty" yaml:"recommended,omitempty"`
	Type               string         `json:"type,omitempty" yaml:"type,omitempty"`
	Severity           string         `json:"severity,omitempty" yaml:"severity,omitempty"`
	Then               interface{}    `json:"then,omitempty" yaml:"then,omitempty"`
	PrecompiledPattern *regexp.Regexp `json:"-" yaml:"-"` // regex is slow.
	RuleCategory       *RuleCategory  `json:"category,omitempty" yaml:"category,omitempty"`
	Name               string         `json:"-" yaml:"-"`
	HowToFix           string         `json:"howToFix,omitempty" yaml:"howToFix,omitempty"`

Rule is a structure that represents a rule as part of a ruleset.

func (*Rule) GetSeverityAsIntValue

func (r *Rule) GetSeverityAsIntValue() int

GetSeverityAsIntValue will return the severity state of the rule as an integer. If the severity is not known then -1 is returned.

func (Rule) ToJSON

func (r Rule) ToJSON() string

ToJSON render out a rule to JSON.

type RuleAction

type RuleAction struct {
	Field           string      `json:"field,omitempty" yaml:"field,omitempty"`
	Function        string      `json:"function,omitempty" yaml:"function,omitempty"`
	FunctionOptions interface{} `json:"functionOptions,omitempty" yaml:"functionOptions,omitempty"`

RuleAction is what to do, on what field, and what options are to be used.

func CastToRuleAction

func CastToRuleAction(action interface{}) *RuleAction

CastToRuleAction is a utility function to cast an unknown structure into a RuleAction. useful for when building rules or testing out concepts.

type RuleCategory

type RuleCategory struct {
	Id          string `json:"id" yaml:"id"`                   // The category ID
	Name        string `json:"name" yaml:"name"`               // The name of the category
	Description string `json:"description" yaml:"description"` // What is the category all about?

type RuleCategoryResult

type RuleCategoryResult struct {
	Rule      *Rule
	Results   []*RuleFunctionResult
	Seen      int
	Health    int
	Errors    int
	Warnings  int
	Info      int
	Hints     int
	Truncated bool

RuleCategoryResult contains metrics for a rule scored as part of a category.

type RuleFunction

type RuleFunction interface {
	RunRule(nodes []*yaml.Node, context RuleFunctionContext) []RuleFunctionResult // The place where logic is run
	GetSchema() RuleFunctionSchema                                                // How to use the function and its details.

RuleFunction is any compatible structure that can be used to run vacuum rules.

type RuleFunctionContext

type RuleFunctionContext struct {
	RuleAction *RuleAction         `json:"ruleAction,omitempty" yaml:"ruleAction,omitempty"` // A reference to the action defined configured by the rule
	Rule       *Rule               `json:"rule,omitempty" yaml:"rule,omitempty"`             // A reference to the Rule being used for the function
	Given      interface{}         `json:"given,omitempty" yaml:"given,omitempty"`           // Path/s being used by rule, multiple paths can be used
	Options    interface{}         `json:"options,omitempty" yaml:"options,omitempty"`       // Function options
	Index      *index.SpecIndex    `json:"-" yaml:"-"`                                       // A reference to the index created for the spec being parsed
	SpecInfo   *datamodel.SpecInfo `json:"specInfo,omitempty" yaml:"specInfo,omitempty"`     // A reference to all specification information for the spec being parsed.
	Document   libopenapi.Document `json:"-" yaml:"-"`                                       // A reference to the document being parsed

RuleFunctionContext defines a RuleAction, Rule and Options for a RuleFunction being run.

type RuleFunctionProperty

type RuleFunctionProperty struct {
	Name        string `json:"name" yaml:"name"`
	Description string `json:"description" yaml:"description"`

RuleFunctionProperty is used by RuleFunctionSchema to describe the functionOptions a Rule accepts

type RuleFunctionResult

type RuleFunctionResult struct {
	Message      string        `json:"message" yaml:"message"`           // What failed and why?
	Range        reports.Range `json:"range" yaml:"range"`               // Where did it happen?
	Path         string        `json:"path" yaml:"path"`                 // the JSONPath to where it can be found
	RuleId       string        `json:"ruleId" yaml:"ruleId"`             // The ID of the rule
	RuleSeverity string        `json:"ruleSeverity" yaml:"ruleSeverity"` // the severity of the rule used
	Rule         *Rule         `json:"-" yaml:"-"`                       // The rule used
	StartNode    *yaml.Node    `json:"-" yaml:"-"`                       // Start of the violation
	EndNode      *yaml.Node    `json:"-" yaml:"-"`                       // end of the violation
	Timestamp    *time.Time    `json:"-" yaml:"-"`                       // When the result was created.

	// ModelContext may or may nor be populated, depending on the rule used and the context of the rule. If it is
	// populated, then this is a reference to the model that fired the rule. (not currently used yet)
	ModelContext any `json:"-" yaml:"-"`

RuleFunctionResult describes a failure with linting after being run through a rule

func BuildFunctionResult

func BuildFunctionResult(key, message string, value interface{}) RuleFunctionResult

BuildFunctionResult will create a RuleFunctionResult from a key, message and value. Deprecated: use BuildFunctionResultWithDescription instead.

func BuildFunctionResultString

func BuildFunctionResultString(message string) RuleFunctionResult

BuildFunctionResultString will create a RuleFunctionResult from a string already parsed into a message.

func BuildFunctionResultWithDescription added in v0.1.0

func BuildFunctionResultWithDescription(desc, key, message string, value interface{}) RuleFunctionResult

BuildFunctionResultWithDescription will create a RuleFunctionResult from a description, key, message and value.

func MapPathAndNodesToResults

func MapPathAndNodesToResults(path string, startNode, endNode *yaml.Node, results []RuleFunctionResult) []RuleFunctionResult

MapPathAndNodesToResults will map the same start/end nodes with the same path.

type RuleFunctionSchema

type RuleFunctionSchema struct {
	Name          string                 `json:"name,omitempty" yaml:"name,omitempty"`                   // The name of this function **important**
	Required      []string               `json:"required,omitempty" yaml:"required,omitempty"`           // List of all required properties to be set
	RequiresField bool                   `json:"requiresField,omitempty" yaml:"requiresField,omitempty"` // 'field' must be used with this function
	Properties    []RuleFunctionProperty `json:"properties,omitempty" yaml:"properties,omitempty"`       // all properties to be passed to the function
	MinProperties int                    `json:"minProperties,omitempty" yaml:"minProperties,omitempty"` // Minimum number of properties
	MaxProperties int                    `json:"maxProperties,omitempty" yaml:"maxProperties,omitempty"` // Maximum number of properties
	ErrorMessage  string                 `json:"errorMessage,omitempty" yaml:"errorMessage,omitempty"`   // Error message to be used in case of failed validartion.

RuleFunctionSchema describes the name, required properties and a slice of RuleFunctionProperty properties.

func (RuleFunctionSchema) GetPropertyDescription

func (rfs RuleFunctionSchema) GetPropertyDescription(name string) string

GetPropertyDescription is a shortcut method for extracting the description of a property by its name.

type RuleResultSet

type RuleResultSet struct {
	Results    []*RuleFunctionResult `json:"results,omitempty" yaml:"results,omitempty"` // All the results!
	WarnCount  int                   `json:"warningCount" yaml:"warningCount"`           // Total warnings
	ErrorCount int                   `json:"errorCount" yaml:"errorCount"`               // Total errors
	InfoCount  int                   `json:"infoCount" yaml:"infoCount"`                 // Total info
	// contains filtered or unexported fields

RuleResultSet contains all the results found during a linting run, and all the methods required to filter, sort and calculate counts.

func NewRuleResultSet

func NewRuleResultSet(results []RuleFunctionResult) *RuleResultSet

NewRuleResultSet will encapsulate a set of results into a set, that can then be queried. the function will create pointers to results, instead of copying them again.

func NewRuleResultSetPointer added in v0.0.4

func NewRuleResultSetPointer(results []*RuleFunctionResult) *RuleResultSet

NewRuleResultSetPointer will encapsulate a set of results into a set, that can then be queried. the function will create pointers to results, instead of copying them again.

func (*RuleResultSet) CalculateCategoryHealth

func (rr *RuleResultSet) CalculateCategoryHealth(category string) int

CalculateCategoryHealth checks how many errors and warnings a category has generated and determine a value between 0 and 100, 0 being errors fired, 100 being no warnings and no errors.

func (*RuleResultSet) GenerateSpectralReport

func (rr *RuleResultSet) GenerateSpectralReport(source string) []reports.SpectralReport

GenerateSpectralReport will return a Spectral compatible report structure, easily serializable

func (*RuleResultSet) GetErrorCount

func (rr *RuleResultSet) GetErrorCount() int

GetErrorCount will return the number of errors returned by the rule results.

func (*RuleResultSet) GetErrorsByRuleCategory

func (rr *RuleResultSet) GetErrorsByRuleCategory(category string) []*RuleFunctionResult

GetErrorsByRuleCategory will return all results with an error level severity from rule category.

func (*RuleResultSet) GetHintByRuleCategory added in v0.0.2

func (rr *RuleResultSet) GetHintByRuleCategory(category string) []*RuleFunctionResult

GetHintByRuleCategory will return all results with hint level severity from rule category.

func (*RuleResultSet) GetInfoByRuleCategory

func (rr *RuleResultSet) GetInfoByRuleCategory(category string) []*RuleFunctionResult

GetInfoByRuleCategory will return all results with an info level severity from rule category.

func (*RuleResultSet) GetInfoCount

func (rr *RuleResultSet) GetInfoCount() int

GetInfoCount will return the number of warnings returned by the rule results.

func (*RuleResultSet) GetResultsByRuleCategory

func (rr *RuleResultSet) GetResultsByRuleCategory(category string) []*RuleFunctionResult

GetResultsByRuleCategory will return results filtered by the supplied category

func (*RuleResultSet) GetResultsForCategoryWithLimit added in v0.0.2

func (rr *RuleResultSet) GetResultsForCategoryWithLimit(category string, limit int) *RuleResultsForCategory

GetResultsForCategoryWithLimit is identical to GetRuleResultsForCategory, except for the fact that there will be a limit on the number of results returned, defined by the limit arg. This is used by the HTML report to stop gigantic files from being created, iterating through all the results.

func (*RuleResultSet) GetRuleResultsForCategory

func (rr *RuleResultSet) GetRuleResultsForCategory(category string) *RuleResultsForCategory

GetRuleResultsForCategory will return all rules that returned results during linting, complete with pre compiled statistics for easy indexing.

func (*RuleResultSet) GetWarnCount

func (rr *RuleResultSet) GetWarnCount() int

GetWarnCount will return the number of warnings returned by the rule results.

func (*RuleResultSet) GetWarningsByRuleCategory

func (rr *RuleResultSet) GetWarningsByRuleCategory(category string) []*RuleFunctionResult

GetWarningsByRuleCategory will return all results with a warning level severity from rule category.

func (*RuleResultSet) Len

func (rr *RuleResultSet) Len() int

Len returns the length of the results

func (*RuleResultSet) Less

func (rr *RuleResultSet) Less(i, j int) bool

Less determines which result has the lower line number

func (*RuleResultSet) PrepareForSerialization added in v0.0.4

func (rr *RuleResultSet) PrepareForSerialization(info *datamodel.SpecInfo)

PrepareForSerialization will create a new Range for start and end nodes as well as pre-render code. When saving a vacuum report, this will be required, so the report can be re-constructed later without the original spec being required.

func (*RuleResultSet) SortResultsByLineNumber

func (rr *RuleResultSet) SortResultsByLineNumber() []*RuleFunctionResult

SortResultsByLineNumber will re-order the results by line number. This is a destructive sort, Once the results are sorted, they are permanently sorted.

func (*RuleResultSet) Swap

func (rr *RuleResultSet) Swap(i, j int)

Swap will re-sort a result if it's in the wrong order.

type RuleResultsForCategory

type RuleResultsForCategory struct {
	RuleResults []*RuleCategoryResult
	Category    *RuleCategory

RuleResultsForCategory boils down result statistics for a linting category

func (*RuleResultsForCategory) Len

func (rr *RuleResultsForCategory) Len() int

Len returns the length of the results

func (*RuleResultsForCategory) Less

func (rr *RuleResultsForCategory) Less(i, j int) bool

Less determines which result has the lower severity (errors bubble to top)

func (*RuleResultsForCategory) Swap

func (rr *RuleResultsForCategory) Swap(i, j int)

Swap will re-sort a result if it's in the wrong order.

type SearchResult

type SearchResult struct {
	Key  string `json:"key"`
	Line int    `json:"line"`
	Col  int    `json:"col"`

SearchResult represents the position of a result in a specification.


Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL