Documentation
¶
Overview ¶
Package plugin provides an extension system for adding custom rules and rulesets to Telescope.
Index ¶
Constants ¶
const ProtocolVersion = 1
ProtocolVersion is the plugin protocol version. Increment when breaking changes are made to the RPC interface.
Variables ¶
var Handshake = plugin.HandshakeConfig{ ProtocolVersion: ProtocolVersion, MagicCookieKey: "TELESCOPE_PLUGIN", MagicCookieValue: "telescope-rule-plugin-v1", }
Handshake is the go-plugin handshake config. Both host and plugin must agree on these values for the connection to be established.
var PluginMap = map[string]plugin.Plugin{ "rules": &RulePluginRPC{}, }
PluginMap is the map of plugin types the host can serve/consume.
Functions ¶
This section is empty.
Types ¶
type AnalyzeRequest ¶
AnalyzeRequest is sent from host to plugin for each document change.
type AnalyzeResponse ¶
type AnalyzeResponse struct {
Diagnostics []PluginDiagnostic
}
AnalyzeResponse carries diagnostics from plugin back to host.
type GetMetaResponse ¶
type GetMetaResponse struct {
Rules []PluginRuleMeta
}
GetMetaResponse carries rule metadata from plugin to host.
type Host ¶
type Host struct {
// contains filtered or unexported fields
}
Host discovers, launches, and communicates with external plugin binaries. Each plugin runs as a subprocess and communicates via go-plugin RPC.
func (*Host) AnalyzeDirect ¶
func (h *Host) AnalyzeDirect(uri string, content []byte) []protocol.Diagnostic
AnalyzeDirect runs all plugins against content and returns diagnostics. Used by the CLI where there is no DiagnosticEngine.
func (*Host) Analyzer ¶
func (h *Host) Analyzer() treesitter.Analyzer
Analyzer returns a treesitter.Analyzer that dispatches to all loaded plugins. Each document change triggers a single RPC call to each plugin.
func (*Host) Discover ¶
Discover finds and launches plugin executables from the given directory. Each executable in the directory is treated as a separate plugin.
func (*Host) LoadPlugin ¶
LoadPlugin launches a single plugin binary and registers it.
func (*Host) PluginCount ¶
PluginCount returns the number of loaded plugins.
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager loads and registers plugins with the gossip server.
func NewManager ¶
NewManager creates a plugin manager.
func (*Manager) RegisterFunc ¶
func (m *Manager) RegisterFunc(fn PluginFunc) error
RegisterFunc creates and registers a plugin from a constructor function.
type Plugin ¶
type Plugin interface {
// Name returns the plugin's unique identifier.
Name() string
// Version returns the plugin's version string.
Version() string
// Checks returns the tree-sitter pattern-based checks this plugin provides.
// Keys are rule IDs.
Checks() map[string]treesitter.Check
// Analyzers returns the semantic analyzer rules this plugin provides.
// Keys are rule IDs.
Analyzers() map[string]treesitter.Analyzer
// Meta returns metadata for all rules in this plugin.
Meta() []rules.RuleMeta
}
Plugin is the interface that custom rule providers implement.
type PluginDiagnostic ¶
type PluginDiagnostic struct {
StartLine uint32
StartChar uint32
EndLine uint32
EndChar uint32
Severity string // error, warn, info, hint
Code string
Message string
Source string
}
PluginDiagnostic is a single diagnostic result from a plugin rule.
type PluginFunc ¶
PluginFunc is a constructor function that creates a Plugin instance. Plugins can be registered via this function type for lazy initialization.
type PluginRuleMeta ¶
type PluginRuleMeta struct {
ID string
Description string
Severity string // error, warn, info, hint
Category string
Recommended bool
HowToFix string
DocURL string
}
PluginRuleMeta describes a single rule provided by a plugin.
type RulePlugin ¶
type RulePlugin interface {
// GetMeta returns metadata for all rules the plugin provides.
GetMeta() (*GetMetaResponse, error)
// Analyze runs all plugin rules against the given document and returns diagnostics.
Analyze(req *AnalyzeRequest) (*AnalyzeResponse, error)
}
RulePlugin is the interface that plugin binaries implement to provide custom diagnostic rules. The host calls GetMeta once at startup to discover rules, then calls Analyze for each document change.
type RulePluginRPC ¶
type RulePluginRPC struct {
Impl RulePlugin
}
RulePluginRPC implements hashicorp/go-plugin's Plugin interface using net/rpc.
type RunningPlugin ¶
type RunningPlugin struct {
// contains filtered or unexported fields
}
RunningPlugin tracks a single launched plugin subprocess.
type YAMLRulePlugin ¶
type YAMLRulePlugin struct {
// contains filtered or unexported fields
}
YAMLRulePlugin is a plugin constructed from a YAML declarative rule file.
func LoadYAMLPlugin ¶
func LoadYAMLPlugin(path string, logger *slog.Logger) (*YAMLRulePlugin, error)
LoadYAMLPlugin loads a YAML ruleset file and converts its rules into a Plugin. Rules with JSONPath "given" expressions are evaluated through the Spectral engine; rules with tree-sitter pattern strings are registered as tree-sitter Checks for backward compatibility.
func (*YAMLRulePlugin) Analyzers ¶
func (p *YAMLRulePlugin) Analyzers() map[string]treesitter.Analyzer
func (*YAMLRulePlugin) Checks ¶
func (p *YAMLRulePlugin) Checks() map[string]treesitter.Check
func (*YAMLRulePlugin) Meta ¶
func (p *YAMLRulePlugin) Meta() []rules.RuleMeta
func (*YAMLRulePlugin) Name ¶
func (p *YAMLRulePlugin) Name() string
func (*YAMLRulePlugin) Version ¶
func (p *YAMLRulePlugin) Version() string