Documentation
¶
Overview ¶
Package rulesets handles loading, parsing, and merging of Telescope ruleset definitions.
A ruleset controls which rules are enabled, their severity levels, and any custom Spectral rules. Rulesets can extend other rulesets and override individual rule settings.
Built-in Rulesets ¶
Telescope ships with four built-in rulesets accessible via GetBuiltin:
- telescope:recommended — ~35 commonly useful rules
- telescope:all — all available rules (~65+)
- telescope:owasp — security-focused rules
- telescope:strict — recommended + stricter OWASP enforcement
Loading Custom Rulesets ¶
Custom rulesets are YAML files compatible with Spectral's format:
rs, err := rulesets.LoadFile("my-rules.yaml")
Or from bytes:
rs, err := rulesets.LoadBytes(yamlData)
Severity ¶
ParseSeverity converts severity strings ("error", "warn", "info", "hint", "off") to LSP DiagnosticSeverity values.
Package rulesets provides Spectral/vacuum-compatible ruleset loading, resolution, and merging. Rulesets define which rules are enabled and their severity overrides.
Index ¶
- Constants
- func BuildEnabledMap(rs *RuleSet) map[string]bool
- func IsNativeRule(spectralID string) bool
- func NormalizeRuleID(id string) string
- func ParseSeverity(s string) (ctypes.Severity, bool)
- func SpectralToTelescopeID(spectralID string) string
- func TelescopeToSpectralID(telescopeID string) string
- type RuleDefinition
- type RuleSet
- type SeverityOverride
Constants ¶
const ( Recommended = "telescope:recommended" All = "telescope:all" OWASP = "telescope:owasp" Strict = "telescope:strict" )
Built-in ruleset names.
const SpectralOAS = "spectral:oas"
SpectralOAS is the name of the Spectral OpenAPI built-in ruleset.
Variables ¶
This section is empty.
Functions ¶
func BuildEnabledMap ¶
BuildEnabledMap converts a resolved ruleset into a map of rule ID -> enabled.
func IsNativeRule ¶
IsNativeRule reports whether the given Spectral rule ID has a native Telescope implementation.
func NormalizeRuleID ¶
NormalizeRuleID resolves deprecated aliases and returns the canonical rule ID. The mapping is owned by barrelman/rulesets/bridge; this wrapper exists so existing telescope call sites can be migrated gradually.
func ParseSeverity ¶
ParseSeverity converts a severity string to a core Severity.
func SpectralToTelescopeID ¶
SpectralToTelescopeID returns the native Telescope rule ID for a Spectral OAS rule, or the original ID if no mapping exists.
func TelescopeToSpectralID ¶
TelescopeToSpectralID returns the Spectral OAS rule ID for a native Telescope rule, or the original ID if no mapping exists.
Types ¶
type RuleDefinition ¶
type RuleDefinition struct {
Severity string `yaml:"severity,omitempty"`
Description string `yaml:"description,omitempty"`
Message string `yaml:"message,omitempty"`
Given interface{} `yaml:"given,omitempty"`
Then interface{} `yaml:"then,omitempty"`
Formats []string `yaml:"formats,omitempty"`
Recommended *bool `yaml:"recommended,omitempty"`
Options map[string]interface{} `yaml:"options,omitempty"`
}
RuleDefinition defines a rule override within a ruleset. It supports both the full object form and Spectral's shorthand where the value is just a severity string (e.g., `rule-id: error`).
func (*RuleDefinition) UnmarshalYAML ¶
func (rd *RuleDefinition) UnmarshalYAML(node *yaml.Node) error
UnmarshalYAML handles Spectral shorthand syntax where a rule value can be:
- a string: "error", "warn", "info", "hint", "off"
- a boolean: false (same as "off")
- an integer: severity code (0=off, 1=error, 2=warn, 3=info, 4=hint)
- an array: [severity, {options}] (e.g., ["error", {"functionOptions": {...}}])
- a map: full rule definition object
type RuleSet ¶
type RuleSet struct {
Name string `yaml:"name,omitempty"`
Description string `yaml:"description,omitempty"`
Extends interface{} `yaml:"extends,omitempty"`
Rules map[string]RuleDefinition `yaml:"rules,omitempty"`
}
RuleSet is a loaded ruleset that controls which rules are enabled and their severity settings.
func GetBuiltin ¶
GetBuiltin returns a resolved ruleset by its built-in name.
func GetSpectralBuiltin ¶
GetSpectralBuiltin returns a RuleSet for the given Spectral built-in name. Currently only "spectral:oas" is supported.
type SeverityOverride ¶
SeverityOverride maps rule IDs to their overridden severity.
func BuildSeverityOverrides ¶
func BuildSeverityOverrides(rs *RuleSet) []SeverityOverride
BuildSeverityOverrides extracts severity overrides from a resolved ruleset.
Source Files