utils

package
v0.21.2 Latest Latest
Warning

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

 Go to latest Published: Dec 20, 2025 License: MIT Imports: 27 Imported by: 1

Documentation

Index

Constants

View Source 
const (
	RuleIDBreakingChange = "breaking-change"
	RuleIDAPIChange      = "api-change"
)

Rule IDs for change violations

View Source 
const DefaultBreakingConfigFile = "changes-rules.yaml"

DefaultBreakingConfigFile is the default filename for breaking rules configuration

Variables

View Source 
var (
	LocationRegex    = regexp.MustCompile(`((?:[a-zA-Z]:)?[^\s│]*?[/\\]?[^\s│/\\]+\.[a-zA-Z]+):(\d+):(\d+)`)
	JsonPathRegex    = regexp.MustCompile(`\$\.\S+`)
	CircularRefRegex = regexp.MustCompile(`\b[a-zA-Z0-9_-]+(?:\s*->\s*[a-zA-Z0-9_-]+)+\b`)
	PartRegex        = regexp.MustCompile(`([a-zA-Z0-9_-]+)|(\s*->\s*)`)
	BacktickRegex    = regexp.MustCompile("`([^`]+)`")
	SingleQuoteRegex = regexp.MustCompile(`'([^']+)'`)
	LogPrefixRegex   = regexp.MustCompile(`\[([^]]+)]`)
)
View Source 
var ChangeViolationRules = struct {
	BreakingChange *model.Rule
	APIChange      *model.Rule
}{
	BreakingChange: &model.Rule{
		Id:           RuleIDBreakingChange,
		Description:  "Detects breaking API changes that may affect consumers",
		Severity:     "error",
		RuleCategory: model.RuleCategories[model.CategoryValidation],
		HowToFix:     "Review this breaking change carefully. Consider versioning your API or communicating the change to consumers before deployment.",
	},
	APIChange: &model.Rule{
		Id:           RuleIDAPIChange,
		Description:  "Detects API changes between specification versions",
		Severity:     "warn",
		RuleCategory: model.RuleCategories[model.CategoryValidation],
		HowToFix:     "Review this API change to ensure it behaves as expected.",
	},
}

ChangeViolationRules contains pre-configured rules for change violations

Functions

func ApplyBreakingRulesConfig added in v0.21.0 

func ApplyBreakingRulesConfig(config *wcModel.BreakingRulesConfig)

ApplyBreakingRulesConfig applies config to libopenapi's active config. The config is merged on top of the default rules, so users only need to specify the rules they want to override. Call with nil to reset to defaults.

func BuildEndNode added in v0.9.0 

func BuildEndNode(node *yaml.Node) *yaml.Node

BuildEndNode will return a new yaml.Node with the same line as the input node, but with a column that is the sum of the input node's column and the length of the input node's value.

func ConvertToMarshalable added in v0.17.10 

func ConvertToMarshalable(data interface{}) interface{}

ConvertToMarshalable attempts to convert problematic structures to JSON-marshalable ones. This is a helper that can be used to fix issues, but for validation we just report them.

func CountBreakingChanges added in v0.21.0 

func CountBreakingChanges(changes *wcModel.DocumentChanges) int

CountBreakingChanges returns the number of breaking changes in a DocumentChanges

func CountNonBreakingChanges added in v0.21.0 

func CountNonBreakingChanges(changes *wcModel.DocumentChanges) int

CountNonBreakingChanges returns the number of non-breaking changes in a DocumentChanges

func CreateCustomHTTPClient added in v0.17.8 

func CreateCustomHTTPClient(config HTTPClientConfig) (*http.Client, error)

CreateCustomHTTPClient creates an HTTP client with custom TLS configuration for certificate-based authentication and custom CA certificates.

func CreateHTTPClientIfNeeded added in v0.21.0 

func CreateHTTPClientIfNeeded(config HTTPClientConfig) (*http.Client, error)

CreateHTTPClientIfNeeded creates a custom HTTP client only if TLS configuration is provided. Returns nil (no error) if no custom configuration is needed, allowing use of default client.

func CreateRemoteURLHandler added in v0.17.8 

func CreateRemoteURLHandler(client *http.Client) func(url string) (*http.Response, error)

CreateRemoteURLHandler creates a RemoteURLHandler function for use with libopenapi that uses the provided HTTP client for all remote requests.

func FilterIgnoredResults added in v0.17.11 

func FilterIgnoredResults(results []model.RuleFunctionResult, ignored model.IgnoredItems) []model.RuleFunctionResult

FilterIgnoredResults does the filtering of ignored results on non-pointer result elements

func FilterIgnoredResultsPtr added in v0.17.11 

func FilterIgnoredResultsPtr(results []*model.RuleFunctionResult, ignored model.IgnoredItems) []*model.RuleFunctionResult

FilterIgnoredResultsPtr filters the given results slice, taking out any (RuleID, Path) combos that were listed in the ignore file

func GenerateChangeReport added in v0.21.0 

func GenerateChangeReport(originalSpecPath string, newSpecBytes []byte, newSpecFilePath string) (*wcModel.DocumentChanges, error)

GenerateChangeReport compares two specs and generates a DocumentChanges report This is the simple version that only returns DocumentChanges (for backwards compatibility) newSpecFilePath is the path to the new spec file - its directory is used for $ref resolution (optional, empty = cwd)

func GenerateChangeViolations added in v0.21.0 

func GenerateChangeViolations(changes *wcModel.DocumentChanges, opts ChangeViolationOptions) []*model.RuleFunctionResult

GenerateChangeViolations converts DocumentChanges into vacuum RuleFunctionResult violations. It walks all changes and creates violations based on whether they are breaking or not. Returns nil if changes is nil or options don't require any violations.

func IsChangeReportFile added in v0.21.0 

func IsChangeReportFile(path string) bool

IsChangeReportFile checks if a file path appears to be a JSON change report based on file extension

func IsSpecFile added in v0.21.0 

func IsSpecFile(path string) bool

IsSpecFile checks if a file path appears to be an OpenAPI spec file

func LoadBreakingRulesConfig added in v0.21.0 

func LoadBreakingRulesConfig(configPath string) (*wcModel.BreakingRulesConfig, error)

LoadBreakingRulesConfig loads breaking rules from specified path or default locations. If configPath is specified, it must exist or an error is returned. If configPath is empty, searches default locations (CWD and ~/.config/). Returns nil with no error if no config is found (use libopenapi defaults).

func LoadChangeReportFromFile added in v0.21.0 

func LoadChangeReportFromFile(path string) (*wcModel.DocumentChanges, error)

LoadChangeReportFromFile loads a what-changed JSON report from a file

func LocateComponentPaths added in v0.18.0 

func LocateComponentPaths(
	context model.RuleFunctionContext,
	component v3.Foundational,
	keyNode *yaml.Node,
	valueNode *yaml.Node,
) (primaryPath string, allPaths []string)

LocateComponentPaths finds all paths where a component appears in the document. It uses DrDocument.LocateModelsByKeyAndValue to find all locations where the component is referenced, not just its definition location. This is a generic version that works with any component type that has GenerateJSONPath. Returns the primary path and all paths where the component appears.

func LocateSchemaPropertyPaths added in v0.17.10 

func LocateSchemaPropertyPaths(
	context model.RuleFunctionContext,
	schema *v3.Schema,
	keyNode *yaml.Node,
	valueNode *yaml.Node,
) (primaryPath string, allPaths []string)

LocateSchemaPropertyPaths finds all paths where a schema property appears in the document. It uses DrDocument.LocateModelsByKeyAndValue to find all locations where the schema is referenced, not just its definition location. Returns the primary path and all paths where the schema appears.

func OpenURL added in v0.19.3 

func OpenURL(url string) error

OpenURL opens the given URL in the system's default browser

func QuickCheckMarshalable added in v0.17.10 

func QuickCheckMarshalable(data interface{}) bool

QuickCheckMarshalable does a quick check to see if data can be marshaled to JSON without doing a deep analysis. Returns true if marshalable, false otherwise.

func RenderMarkdownTable added in v0.16.15 

func RenderMarkdownTable(headers []string, rows [][]string) string

RenderMarkdownTable builds a Markdown table from headers and rows.

func ResetBreakingRulesConfig added in v0.21.0 

func ResetBreakingRulesConfig()

ResetBreakingRulesConfig resets the active breaking rules to defaults. This is a convenience wrapper around wcModel.ResetActiveBreakingRulesConfig().

func ShouldUseCustomHTTPClient added in v0.17.8 

func ShouldUseCustomHTTPClient(config HTTPClientConfig) bool

ShouldUseCustomHTTPClient returns true if any TLS-related configuration is provided

func SuppliedOrDefault added in v0.7.0 

func SuppliedOrDefault(supplied, original string) string

Types

type ChangeFilter added in v0.21.0 

type ChangeFilter struct {
	// contains filtered or unexported fields
}

ChangeFilter filters vacuum results based on what-changed data

func CreateChangeFilterFromFlags added in v0.21.0 

func CreateChangeFilterFromFlags(changesFlag, originalFlag string, newSpecBytes []byte, newSpecFilePath string, drDoc *drModel.DrDocument) (*ChangeFilter, error)

CreateChangeFilterFromFlags creates a ChangeFilter based on the provided flags. If originalFlag is set, compares the original spec file with newSpecBytes. If changesFlag is set, loads the change report from the JSON file. Returns nil filter (no error) if neither flag is set. newSpecFilePath is the path to the new spec file - its directory is used for $ref resolution (optional, empty = cwd)

func CreateChangeFilterFromSpecs added in v0.21.0 

func CreateChangeFilterFromSpecs(originalSpecPath string, newSpecBytes []byte, newSpecFilePath string, drDoc *drModel.DrDocument) (*ChangeFilter, error)

CreateChangeFilterFromSpecs creates a ChangeFilter by comparing an original spec file with the new spec bytes, using the provided DrDocument for model location newSpecFilePath is the path to the new spec file - its directory is used for $ref resolution (optional, empty = cwd)

func LoadChangeFilterFromReport added in v0.21.0 

func LoadChangeFilterFromReport(reportPath string, drDoc *drModel.DrDocument) (*ChangeFilter, error)

LoadChangeFilterFromReport creates a ChangeFilter from a pre-existing JSON change report file

func NewChangeFilter added in v0.21.0 

func NewChangeFilter(changes *wcModel.DocumentChanges, drDoc *drModel.DrDocument) *ChangeFilter

NewChangeFilter creates a new ChangeFilter from DocumentChanges and a DrDocument

func (*ChangeFilter) FilterResults added in v0.21.0 

func (cf *ChangeFilter) FilterResults(results []*model.RuleFunctionResult) []*model.RuleFunctionResult

FilterResults returns only results that affect changed areas

func (*ChangeFilter) FilterResultsValues added in v0.21.0 

func (cf *ChangeFilter) FilterResultsValues(results []model.RuleFunctionResult) ([]model.RuleFunctionResult, *ChangeFilterStats)

FilterResultsValues filters a value slice directly, avoiding pointer conversion overhead. Returns the filtered slice and statistics.

func (*ChangeFilter) FilterResultsWithStats added in v0.21.0 

func (cf *ChangeFilter) FilterResultsWithStats(results []*model.RuleFunctionResult) ([]*model.RuleFunctionResult, *ChangeFilterStats)

FilterResultsWithStats returns filtered results AND statistics about what was filtered

func (*ChangeFilter) GetChangedLineCount added in v0.21.0 

func (cf *ChangeFilter) GetChangedLineCount() int

GetChangedLineCount returns the number of changed lines

func (*ChangeFilter) GetChangedModelCount added in v0.21.0 

func (cf *ChangeFilter) GetChangedModelCount() int

GetChangedModelCount returns the number of changed models

func (*ChangeFilter) HasChanges added in v0.21.0 

func (cf *ChangeFilter) HasChanges() bool

HasChanges returns true if there are any changes to filter by

func (*ChangeFilter) IsInChangedArea added in v0.21.0 

func (cf *ChangeFilter) IsInChangedArea(result *model.RuleFunctionResult) bool

IsInChangedArea checks if a single result is in a changed area

func (*ChangeFilter) IsLineChanged added in v0.21.0 

func (cf *ChangeFilter) IsLineChanged(line int) bool

IsLineChanged returns true if the given line number is in the changed lines set

type ChangeFilterStats added in v0.21.0 

type ChangeFilterStats struct {
	TotalResultsBefore   int            // Results before filtering
	TotalResultsAfter    int            // Results after filtering
	ResultsDropped       int            // TotalBefore - TotalAfter
	RulesFullyFiltered   []string       // Rules where ALL results were removed
	RulesPartialFiltered map[string]int // Rule -> count of results dropped (partial)
}

ChangeFilterStats holds statistics about what was filtered

func (*ChangeFilterStats) GetDroppedPercentage added in v0.21.0 

func (s *ChangeFilterStats) GetDroppedPercentage() int

GetDroppedPercentage returns the percentage of results that were filtered out

type ChangeResult added in v0.21.0 

type ChangeResult struct {
	DocumentChanges *wcModel.DocumentChanges
	RootNode        *drV3.Node // Root node for tree rendering (nil when loading from JSON)
}

ChangeResult holds the results of a change comparison including the tree for rendering

func GenerateChangeReportWithTree added in v0.21.0 

func GenerateChangeReportWithTree(originalSpecPath string, newSpecBytes []byte, newSpecFilePath string) (*ChangeResult, error)

GenerateChangeReportWithTree compares two specs using the doctor's changerator Returns both the DocumentChanges and the node tree for rendering newSpecFilePath is the path to the new spec file - its directory is used for $ref resolution (optional, empty = cwd)

type ChangeStats added in v0.21.0 

type ChangeStats struct {
	TotalChanges    int
	Added           int
	Modified        int
	Removed         int
	BreakingChanges int
}

ChangeStats holds summary statistics about changes in a DocumentChanges

func ExtractChangeStats added in v0.21.0 

func ExtractChangeStats(changes *wcModel.DocumentChanges) *ChangeStats

ExtractChangeStats analyzes DocumentChanges and returns aggregated statistics

func (*ChangeStats) HasChanges added in v0.21.0 

func (s *ChangeStats) HasChanges() bool

HasChanges returns true if there are any changes

type ChangeViolationOptions added in v0.21.0 

type ChangeViolationOptions struct {
	WarnOnChanges   bool // Inject warning violations for non-breaking changes
	ErrorOnBreaking bool // Inject error violations for breaking changes
}

ChangeViolationOptions configures which changes should be converted to violations

type ConfigValidationError added in v0.21.0 

type ConfigValidationError struct {
	FilePath string
	Result   *wcModel.ConfigValidationResult
}

ConfigValidationError wraps validation errors with file context

func (*ConfigValidationError) Error added in v0.21.0 

func (e *ConfigValidationError) Error() string

func (*ConfigValidationError) FormatValidationErrors added in v0.21.0 

func (e *ConfigValidationError) FormatValidationErrors() string

FormatValidationErrors returns a formatted string of all validation errors

type HTTPClientConfig added in v0.17.8 

type HTTPClientConfig struct {
	CertFile string
	KeyFile  string
	CAFile   string
	Insecure bool
}

HTTPClientConfig holds configuration for creating a custom HTTP client

type LintFileRequest added in v0.9.0 

type LintFileRequest struct {
	FileName                 string
	BaseFlag                 string
	MultiFile                bool
	Remote                   bool
	SkipCheckFlag            bool
	Silent                   bool
	DetailsFlag              bool
	TimeFlag                 bool
	NoMessageFlag            bool
	ExtensionRefs            bool
	AllResultsFlag           bool
	FailSeverityFlag         string
	CategoryFlag             string
	SnippetsFlag             bool
	ErrorsFlag               bool
	TotalFiles               int
	FileIndex                int
	TimeoutFlag              int
	LookupTimeoutFlag        int
	IgnoreArrayCircleRef     bool
	IgnorePolymorphCircleRef bool
	NoClip                   bool
	IgnoredResults           model.IgnoredItems
	DefaultRuleSets          rulesets.RuleSets
	SelectedRS               *rulesets.RuleSet
	Functions                map[string]model.RuleFunction
	Lock                     *sync.Mutex
	Logger                   *slog.Logger
	PipelineOutput           bool
	ShowRules                bool
	HTTPClientConfig         HTTPClientConfig
}

type MarshalingIssue added in v0.17.10 

type MarshalingIssue struct {
	Line     int
	Column   int
	Path     string
	Reason   string
	KeyValue string // The actual key that's problematic
}

MarshalingIssue represents a location where JSON marshaling will fail

func CheckJSONMarshaling added in v0.17.10 

func CheckJSONMarshaling(data interface{}, rootNode *yaml.Node) []MarshalingIssue

CheckJSONMarshaling attempts to marshal the data and returns any marshaling issues found. It only performs deep checking if the initial marshal fails.

func FindMarshalingIssuesInYAML added in v0.17.10 

func FindMarshalingIssuesInYAML(rootNode *yaml.Node) []MarshalingIssue

FindMarshalingIssuesInYAML directly checks the YAML AST for marshaling issues without needing the unmarshaled data. This is useful when SpecJSON is nil.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.