Documentation
¶
Overview ¶
Package sdk provides the public Go API for using Telescope as a library.
Workspace API (Programmatic Linting) ¶
Use Workspace to lint OpenAPI specs without running the LSP server:
ws, err := sdk.New()
if err != nil {
log.Fatal(err)
}
defer ws.Close()
// Add files from disk or synthetic content
ws.AddSource(graph.NewFilesystemSource("openapi.yaml", graph.ClassificationHint{}))
// Or: ws.AddSource(graph.NewSyntheticSource("file:///spec.yaml", content, graph.ClassificationHint{}))
result, err := ws.Analyze(ctx)
if err != nil {
log.Fatal(err)
}
for uri, diags := range result.Diagnostics {
for _, d := range diags {
fmt.Printf("%s:%d: [%s] %s\n", uri, d.Range.Start.Line+1, d.Code, d.Message)
}
}
See docs/SDK.md for the full guide.
Custom rules ¶
User-defined rules are authored as YAML (under openapi.rules and related config) and TypeScript/JavaScript executed by the optional Bun sidecar. There is no Go plugin or subprocess RPC surface for custom rules.
Available Types ¶
Re-exported OpenAPI model types (Document, Operation, Schema, Parameter, etc.) and rule helpers (Reporter, Meta, Category, Validator) are available as type aliases for consumers that embed Telescope.
Validators ¶
Composable validators are available via the V variable:
sdk.V.Required() sdk.V.CamelCase() sdk.V.All(sdk.V.Required(), sdk.V.MinLength(3))
Package sdk re-exports OpenAPI model and rules types for library consumers.
Index ¶
- Constants
- Variables
- func LintContent(uri string, content []byte) ([]ctypes.Diagnostic, error)
- type AnalysisResult
- type Category
- type Components
- type DescriptionValue
- type Document
- type Example
- type ExternalDocs
- type Header
- type Index
- type Info
- type Link
- type LintOptions
- type LintResult
- type Loc
- type MediaType
- type Meta
- type Node
- type Operation
- type Option
- type Parameter
- type PathItem
- type Reporter
- type RequestBody
- type Response
- type Schema
- type SecurityRequirement
- type SecurityScheme
- type Server
- type ServerVariable
- type Tag
- type ValidationResult
- type Validator
- type Workspace
- func (w *Workspace) AddSource(src graph.DocumentSource)
- func (w *Workspace) Analyze(ctx context.Context) (*AnalysisResult, error)
- func (w *Workspace) AnalyzeURI(ctx context.Context, uri string) ([]ctypes.Diagnostic, error)
- func (w *Workspace) Close() error
- func (w *Workspace) Graph() graph.ReadOnlyGraph
- func (w *Workspace) Index(uri string) interface{}
- func (w *Workspace) OnSnapshot(fn func(*graph.Snapshot))
- func (w *Workspace) RemoveSource(uri string)
- func (w *Workspace) Snapshot() *graph.Snapshot
- func (w *Workspace) Watch(ctx context.Context, onChange func(*graph.Snapshot)) (context.CancelFunc, error)
- type WorkspaceConfig
Constants ¶
const ( SeverityError = ctypes.SeverityError SeverityWarning = ctypes.SeverityWarning SeverityInfo = ctypes.SeverityInfo SeverityHint = ctypes.SeverityHint )
const ( Error = ctypes.SeverityError Warn = ctypes.SeverityWarning Hint = ctypes.SeverityHint )
Convenience aliases matching common usage.
const ( Naming = rules.CategoryNaming Documentation = rules.CategoryDocumentation Structure = rules.CategoryStructure Types = rules.CategoryTypes Security = rules.CategorySecurity Servers = rules.CategoryServers Paths = rules.CategoryPaths References = rules.CategoryReferences Syntax = rules.CategorySyntax OWASP = rules.CategoryOWASP )
Variables ¶
var V = rules.V
V exposes composable validator constructors. Use V.Required(), V.MinLength(n), V.Pattern(re), etc.
Functions ¶
func LintContent ¶
func LintContent(uri string, content []byte) ([]ctypes.Diagnostic, error)
LintContent runs Telescope's full rule suite against in-memory content. The uri parameter is used for diagnostic reporting.
Types ¶
type AnalysisResult ¶
type AnalysisResult struct {
Diagnostics map[string][]ctypes.Diagnostic // URI -> diagnostics
NodeCount int
EdgeCount int
RootDocuments []string
Duration time.Duration
SnapshotID uint64
StageDurations map[string]time.Duration // stage name -> total duration
RuleDurations map[string]time.Duration // rule code -> total duration
}
AnalysisResult contains the results of a workspace analysis run.
func (*AnalysisResult) DiagnosticsForURI ¶
func (r *AnalysisResult) DiagnosticsForURI(uri string) []ctypes.Diagnostic
DiagnosticsForURI returns diagnostics for a specific document.
func (*AnalysisResult) HasErrors ¶
func (r *AnalysisResult) HasErrors() bool
HasErrors returns true if any diagnostic has error severity.
func (*AnalysisResult) TotalDiagnostics ¶
func (r *AnalysisResult) TotalDiagnostics() int
TotalDiagnostics returns the total count of diagnostics across all documents.
type Components ¶
type Components = openapi.Components
type DescriptionValue ¶
type DescriptionValue = openapi.DescriptionValue
type ExternalDocs ¶
type ExternalDocs = openapi.ExternalDocs
type LintOptions ¶
type LintOptions struct {
// MinSeverity filters diagnostics. Only diagnostics with severity <=
// this value are kept (1=error, 2=warning, 3=info, 4=hint). Zero
// means no filtering.
MinSeverity ctypes.Severity
// ConfigPath points to a .telescope.yaml file.
ConfigPath string
// RulesetPath points to a ruleset YAML file merged into config rules.
RulesetPath string
// WorkspaceRoot is used for config discovery and relative plugin paths.
WorkspaceRoot string
// NoExternalLSP is a deprecated no-op retained for compatibility.
NoExternalLSP bool
// Include overrides config include globs when set.
Include []string
// Exclude overrides config exclude globs when set.
Exclude []string
// TargetVersion overrides OpenAPI target version (3.0/3.1/3.2).
TargetVersion string
}
LintOptions controls linting behavior.
type LintResult ¶
type LintResult struct {
File string
URI string
Diagnostics []ctypes.Diagnostic
}
LintResult holds diagnostics for a single linted file.
func LintFiles ¶
func LintFiles(files []string, opts LintOptions) ([]LintResult, error)
LintFiles runs Telescope's full rule suite against the given spec files and returns diagnostics per file. No external binary or Node.js needed.
type Option ¶
type Option func(*WorkspaceConfig)
Option configures a Workspace.
func WithBuiltinRules ¶
WithBuiltinRules enables or disables the built-in Telescope rules.
func WithConfig ¶
WithConfig sets the Telescope configuration.
func WithCustomRules ¶
WithCustomRules enables or disables custom rule loading via the Bun sidecar.
func WithGoroutinePoolSize ¶
WithGoroutinePoolSize sets the maximum number of goroutines for parallel analysis.
func WithLogger ¶
WithLogger sets the logger for the workspace.
func WithStages ¶
WithStages overrides the default pipeline stages.
type RequestBody ¶
type RequestBody = openapi.RequestBody
type SecurityRequirement ¶
type SecurityRequirement = openapi.SecurityRequirement
type SecurityScheme ¶
type SecurityScheme = openapi.SecurityScheme
type ServerVariable ¶
type ServerVariable = openapi.ServerVariable
type ValidationResult ¶
type ValidationResult = rules.ValidationResult
type Workspace ¶
type Workspace struct {
// contains filtered or unexported fields
}
Workspace provides the stable public Go API for using Telescope as a library. It wraps the core graph engine, pipeline runner, and snapshot manager into a single high-level interface suitable for CLI tools and external consumers that need programmatic analysis.
func (*Workspace) AddSource ¶
func (w *Workspace) AddSource(src graph.DocumentSource)
AddSource adds a document source to the workspace and runs the pipeline.
func (*Workspace) Analyze ¶
func (w *Workspace) Analyze(ctx context.Context) (*AnalysisResult, error)
Analyze runs the full analysis pipeline on all documents in the workspace and returns aggregated results.
func (*Workspace) AnalyzeURI ¶
AnalyzeURI runs the pipeline for a single document and returns its diagnostics.
func (*Workspace) Graph ¶
func (w *Workspace) Graph() graph.ReadOnlyGraph
Graph returns a read-only view of the workspace graph.
func (*Workspace) Index ¶
Index returns the OpenAPI index data from the current snapshot for a given URI. Returns the raw stage result from the lint stage, or nil if unavailable.
func (*Workspace) OnSnapshot ¶
OnSnapshot registers a callback for when a new snapshot is built.
func (*Workspace) RemoveSource ¶
RemoveSource removes a document from the workspace.
func (*Workspace) Snapshot ¶
Snapshot returns the current immutable snapshot, or nil if none has been built.
func (*Workspace) Watch ¶
func (w *Workspace) Watch(ctx context.Context, onChange func(*graph.Snapshot)) (context.CancelFunc, error)
Watch starts background processing. When documents change, the snapshot manager queues them and calls onChange with each new snapshot. Returns a cancel function to stop watching.