plugin

package
v0.0.0-...-2f47c6c Latest Latest
Warning

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

Go to latest
Published: Mar 12, 2026 License: MIT Imports: 21 Imported by: 0

Documentation

Overview

Package plugin provides an extension system for adding custom rules and rulesets to Telescope.

Index

Constants

View Source
const ProtocolVersion = 1

ProtocolVersion is the plugin protocol version. Increment when breaking changes are made to the RPC interface.

Variables

View Source
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.

View Source
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

type AnalyzeRequest struct {
	URI        string
	Content    []byte
	LanguageID string // yaml, json
}

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 NewHost

func NewHost(logger *slog.Logger) *Host

NewHost creates a plugin host.

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

func (h *Host) Discover(dir string) error

Discover finds and launches plugin executables from the given directory. Each executable in the directory is treated as a separate plugin.

func (*Host) LoadPlugin

func (h *Host) LoadPlugin(path string) error

LoadPlugin launches a single plugin binary and registers it.

func (*Host) PluginCount

func (h *Host) PluginCount() int

PluginCount returns the number of loaded plugins.

func (*Host) Shutdown

func (h *Host) Shutdown()

Shutdown kills all running plugin subprocesses.

type Manager

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

Manager loads and registers plugins with the gossip server.

func NewManager

func NewManager(logger *slog.Logger) *Manager

NewManager creates a plugin manager.

func (*Manager) LoadAll

func (m *Manager) LoadAll(s *gossip.Server) error

LoadAll registers all plugins' rules and metadata with the server.

func (*Manager) Loaded

func (m *Manager) Loaded() []Plugin

Loaded returns the list of loaded plugins.

func (*Manager) Register

func (m *Manager) Register(p Plugin)

Register adds a plugin to the 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

type PluginFunc func() (Plugin, error)

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.

func (*RulePluginRPC) Client

func (p *RulePluginRPC) Client(b *plugin.MuxBroker, c *rpc.Client) (interface{}, error)

func (*RulePluginRPC) Server

func (p *RulePluginRPC) Server(*plugin.MuxBroker) (interface{}, error)

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

Jump to

Keyboard shortcuts

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