Documentation
¶
Overview ¶
Package rules provides the rule definition framework for Telescope's OpenAPI diagnostic engine.
Defining Rules ¶
Rules are built using a fluent API starting with Define:
rules.Define("my-rule", rules.RuleMeta{
ID: "my-rule",
Description: "Operations must have a summary",
Severity: protocol.SeverityWarning,
Category: CategoryNaming,
Recommended: true,
}).Operations(func(path, method string, op *openapi.Operation, r *Reporter) {
if op.Summary.Text == "" {
r.At(op.Loc, "%s %s is missing a summary", method, path)
}
}).Register(s)
Available visitor methods on RuleBuilder: Document, Info, Paths, Operations, Schemas, RecursiveSchemas, Parameters, Responses, Tags, Servers, RequestBodies, SecuritySchemes, Examples, and Custom.
Reporting Diagnostics ¶
The Reporter collects diagnostics with precise source locations. It supports chainable modifiers:
r.WithTags(protocol.DiagnosticTagDeprecated).At(loc, "deprecated") r.WithRelated(otherLoc, uri, "also defined here").At(loc, "duplicate")
Validators ¶
Composable field validators are available via the V variable:
V.Required() V.CamelCase() V.All(V.Required(), V.MinLength(3))
Registry ¶
DefaultRegistry holds metadata for all registered rules. Use it to enumerate available rules, filter by category, or look up rule details.
Walking ¶
Walk traverses an openapi.Index and invokes Visitors callbacks, which is what the rule builder uses internally.
Package rules provides the rule registry, metadata types, and registration functions for all Telescope diagnostic rules.
Index ¶
- Constants
- Variables
- func CollectAll(analyzerFn, checkFn func(s *gossip.Server)) ([]NamedAnalyzer, []NamedCheck)
- func GetIndex(ctx *treesitter.AnalysisContext) *openapi.Index
- func RegisterGossip(b *barrelman.RuleBuilder, s *gossip.Server)
- func RunAnalyzers(analyzers []NamedAnalyzer, idx *openapi.Index, docURI string, ...) []ctypes.Diagnostic
- func RunAnalyzersProto(analyzers []NamedAnalyzer, idx *openapi.Index, docURI string, ...) []protocol.Diagnostic
- func RunChecks(checks []NamedCheck, tree *treesitter.Tree, lang *tree_sitter.Language) []ctypes.Diagnostic
- func RunChecksProto(checks []NamedCheck, tree *treesitter.Tree, lang *tree_sitter.Language) []protocol.Diagnostic
- func WalkIndex(idx *openapi.Index, v Visitors, r *Reporter)
- type AnalysisContext
- type AnalysisData
- type AnalyzerOption
- type Category
- type CrossRefResolver
- type FieldValidation
- type NamedAnalyzer
- type NamedCheck
- type Registry
- type Reporter
- type Rule
- type RuleBuilder
- type RuleMeta
- type ValidationResult
- type Validator
- type Visitors
Constants ¶
const ( CategoryNaming = barrelman.CategoryNaming CategoryDocumentation = barrelman.CategoryDocumentation CategoryStructure = barrelman.CategoryStructure CategoryTypes = barrelman.CategoryTypes CategorySecurity = barrelman.CategorySecurity CategoryServers = barrelman.CategoryServers CategoryPaths = barrelman.CategoryPaths CategoryReferences = barrelman.CategoryReferences CategorySyntax = barrelman.CategorySyntax CategoryOWASP = barrelman.CategoryOWASP )
const DocBaseURL = barrelman.DocBaseURL
const Source = barrelman.Source
Variables ¶
var ( IsCapitalized = barrelman.IsCapitalized IsKebabCase = barrelman.IsKebabCase ContainsHTTPVerb = barrelman.ContainsHTTPVerb HasTrailingSlash = barrelman.HasTrailingSlash IsHTTPS = barrelman.IsHTTPS ContainsCredentials = barrelman.ContainsCredentials ExtractPathParams = barrelman.ExtractPathParams NonParamSegments = barrelman.NonParamSegments PathParamRegex = barrelman.PathParamRegex )
var DefaultRegistry = barrelman.DefaultRegistry
var Define = barrelman.Define
var Field = barrelman.Field
var NewRegistry = barrelman.NewRegistry
var NewReporter = barrelman.NewReporter
var V = barrelman.V
var ValidateOperationFields = barrelman.ValidateOperationFields
var ValidateSchemaFields = barrelman.ValidateSchemaFields
var Walk = barrelman.Walk
Functions ¶
func CollectAll ¶
func CollectAll(analyzerFn, checkFn func(s *gossip.Server)) ([]NamedAnalyzer, []NamedCheck)
CollectAll calls analyzerFn and checkFn (which should invoke RegisterAll for analyzers and checks respectively) and returns all built analyzers and checks. This uses gossip Server hooks to capture everything, including analyzers registered directly via s.Analyze() (like oas3-schema).
func GetIndex ¶
func GetIndex(ctx *treesitter.AnalysisContext) *openapi.Index
GetIndex extracts the *openapi.Index from a treesitter AnalysisContext. Supports both raw *openapi.Index (legacy) and *bridge.AnalysisData.
func RegisterGossip ¶
func RegisterGossip(b *barrelman.RuleBuilder, s *gossip.Server)
RegisterGossip is a convenience function for registering a barrelman rule with both the registry and a gossip server.
func RunAnalyzers ¶
func RunAnalyzers(analyzers []NamedAnalyzer, idx *openapi.Index, docURI string, tree *treesitter.Tree, opts ...AnalyzerOption) []ctypes.Diagnostic
RunAnalyzers runs all provided analyzers against an openapi.Index and returns the combined diagnostics as protocol-independent core types. When tree is non-nil, it is passed through the AnalysisContext so tree-dependent analyzers (like oas3-schema) can execute.
func RunAnalyzersProto ¶
func RunAnalyzersProto(analyzers []NamedAnalyzer, idx *openapi.Index, docURI string, tree *treesitter.Tree, opts ...AnalyzerOption) []protocol.Diagnostic
RunAnalyzersProto is like RunAnalyzers but returns protocol.Diagnostic for backward compatibility with consumers that need protocol types directly.
func RunChecks ¶
func RunChecks(checks []NamedCheck, tree *treesitter.Tree, lang *tree_sitter.Language) []ctypes.Diagnostic
RunChecks executes pattern-based tree-sitter checks against the given tree and returns the combined diagnostics as core types.
func RunChecksProto ¶
func RunChecksProto(checks []NamedCheck, tree *treesitter.Tree, lang *tree_sitter.Language) []protocol.Diagnostic
RunChecksProto executes pattern-based tree-sitter checks and returns protocol diagnostics for backward compatibility.
Types ¶
type AnalysisContext ¶
type AnalysisContext = barrelman.AnalysisContext
type AnalysisData ¶
type AnalysisData = bridge.AnalysisData
func GetAnalysisData ¶
func GetAnalysisData(ctx *treesitter.AnalysisContext) *AnalysisData
GetAnalysisData extracts the full AnalysisData from a treesitter AnalysisContext. Returns nil if UserData is not *AnalysisData.
type AnalyzerOption ¶
type AnalyzerOption func(*AnalysisData)
AnalyzerOption configures optional fields on AnalysisData.
func WithResolver ¶
func WithResolver(r CrossRefResolver) AnalyzerOption
WithResolver sets the cross-file resolver on AnalysisData.
func WithTargetVersion ¶
func WithTargetVersion(v openapi.Version) AnalyzerOption
WithTargetVersion sets the target OpenAPI version for fragment validation.
type CrossRefResolver ¶
type CrossRefResolver = barrelman.CrossRefResolver
type FieldValidation ¶
type FieldValidation = barrelman.FieldValidation
type NamedAnalyzer ¶
type NamedAnalyzer struct {
ID string
Meta RuleMeta
Analyzer treesitter.Analyzer
}
NamedAnalyzer pairs a rule ID with its built analyzer for use outside the gossip LSP server (e.g., CLI lint mode).
func CollectAnalyzers ¶
func CollectAnalyzers(fn func(s *gossip.Server)) []NamedAnalyzer
CollectAnalyzers calls fn (which should invoke RegisterAll for analyzers) and returns all built analyzers. This enables CLI lint without requiring the gossip DiagnosticEngine. Kept for backward compatibility; prefer CollectAll for full coverage.
type NamedCheck ¶
type NamedCheck struct {
Name string
Check treesitter.Check
}
NamedCheck pairs a rule name with its Check definition for CLI execution.
type RuleBuilder ¶
type RuleBuilder = barrelman.RuleBuilder
type ValidationResult ¶
type ValidationResult = barrelman.ValidationResult
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package checks implements syntactic diagnostic rules.
|
Package checks implements syntactic diagnostic rules. |
|
Package rulestest provides test helpers for validating Telescope rules.
|
Package rulestest provides test helpers for validating Telescope rules. |