sdk

package
v0.0.1 Latest Latest
Warning

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

Go to latest
Published: Jun 8, 2026 License: MIT Imports: 15 Imported by: 0

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

View Source
const (
	SeverityError   = ctypes.SeverityError
	SeverityWarning = ctypes.SeverityWarning
	SeverityInfo    = ctypes.SeverityInfo
	SeverityHint    = ctypes.SeverityHint
)

Convenience aliases matching common usage.

Variables

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

type Category = rules.Category

type Components

type Components = openapi.Components

type DescriptionValue

type DescriptionValue = openapi.DescriptionValue

type Document

type Document = openapi.Document

type Example

type Example = openapi.Example

type ExternalDocs

type ExternalDocs = openapi.ExternalDocs
type Header = openapi.Header

type Index

type Index = openapi.Index

type Info

type Info = openapi.Info
type Link = openapi.Link

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 Loc

type Loc = openapi.Loc

type MediaType

type MediaType = openapi.MediaType

type Meta

type Meta = rules.RuleMeta

type Node

type Node = openapi.Node

type Operation

type Operation = openapi.Operation

type Option

type Option func(*WorkspaceConfig)

Option configures a Workspace.

func WithBuiltinRules

func WithBuiltinRules(enabled bool) Option

WithBuiltinRules enables or disables the built-in Telescope rules.

func WithConfig

func WithConfig(cfg *config.Config) Option

WithConfig sets the Telescope configuration.

func WithCustomRules

func WithCustomRules(enabled bool) Option

WithCustomRules enables or disables custom rule loading via the Bun sidecar.

func WithGoroutinePoolSize

func WithGoroutinePoolSize(size int) Option

WithGoroutinePoolSize sets the maximum number of goroutines for parallel analysis.

func WithLogger

func WithLogger(logger *slog.Logger) Option

WithLogger sets the logger for the workspace.

func WithStages

func WithStages(stages []graph.Stage) Option

WithStages overrides the default pipeline stages.

type Parameter

type Parameter = openapi.Parameter

type PathItem

type PathItem = openapi.PathItem

type Reporter

type Reporter = rules.Reporter

type RequestBody

type RequestBody = openapi.RequestBody

type Response

type Response = openapi.Response

type Schema

type Schema = openapi.Schema

type SecurityRequirement

type SecurityRequirement = openapi.SecurityRequirement

type SecurityScheme

type SecurityScheme = openapi.SecurityScheme

type Server

type Server = openapi.Server

type ServerVariable

type ServerVariable = openapi.ServerVariable

type Tag

type Tag = openapi.Tag

type ValidationResult

type ValidationResult = rules.ValidationResult

type Validator

type Validator = rules.Validator

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 New

func New(opts ...Option) (*Workspace, error)

New creates a new Workspace with the given options.

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

func (w *Workspace) AnalyzeURI(ctx context.Context, uri string) ([]ctypes.Diagnostic, error)

AnalyzeURI runs the pipeline for a single document and returns its diagnostics.

func (*Workspace) Close

func (w *Workspace) Close() error

Close releases resources associated with the workspace.

func (*Workspace) Graph

func (w *Workspace) Graph() graph.ReadOnlyGraph

Graph returns a read-only view of the workspace graph.

func (*Workspace) Index

func (w *Workspace) Index(uri string) interface{}

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

func (w *Workspace) OnSnapshot(fn func(*graph.Snapshot))

OnSnapshot registers a callback for when a new snapshot is built.

func (*Workspace) RemoveSource

func (w *Workspace) RemoveSource(uri string)

RemoveSource removes a document from the workspace.

func (*Workspace) Snapshot

func (w *Workspace) Snapshot() *graph.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.

type WorkspaceConfig

type WorkspaceConfig struct {
	BuiltinRules      bool
	CustomRules       bool
	Logger            *slog.Logger
	Stages            []graph.Stage
	Config            *config.Config
	GoroutinePoolSize int
}

WorkspaceConfig holds configuration for a Workspace instance.

Jump to

Keyboard shortcuts

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