graph

package
v0.0.2 Latest Latest
Warning

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

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

Documentation

Overview

Package graph provides the unified workspace graph engine for Telescope. It manages document sources, dependency edges, invalidation cascades, and the staged processing pipeline. No LSP or CLI dependencies.

Index

Constants

View Source 
const (
	EdgeRef      = navgraph.EdgeRef
	EdgeExternal = navgraph.EdgeExternal
	EdgePathRef  = navgraph.EdgePathRef
)

Edge constants.

View Source 
const (
	StageRaw      = navgraph.StageRaw
	StageParse    = navgraph.StageParse
	StageLint     = navgraph.StageLint
	StageBind     = navgraph.StageBind
	StageValidate = navgraph.StageValidate
	StageAnalyze  = navgraph.StageAnalyze
)

Stage name constants.

Variables

This section is empty.

Functions

This section is empty.

Types

type AnalyzeFunc 

type AnalyzeFunc func(ctx context.Context, uri string, g *WorkspaceGraph) []ctypes.Diagnostic

AnalyzeFunc is a function that produces diagnostics for a document.

type AnalyzeStage 

type AnalyzeStage struct {
	Analyzers []AnalyzeFunc
}

AnalyzeStage runs built-in Go rules and optionally delegates to the Bun sidecar.

func (AnalyzeStage) DependsOn 

func (s AnalyzeStage) DependsOn() []StageName

func (AnalyzeStage) Name 

func (s AnalyzeStage) Name() StageName

func (AnalyzeStage) Run 

func (s AnalyzeStage) Run(ctx context.Context, uri string, g *WorkspaceGraph) error

type BindStage 

type BindStage struct{}

BindStage resolves $ref values and materializes edges in the workspace graph.

func (BindStage) DependsOn 

func (BindStage) DependsOn() []StageName

func (BindStage) Name 

func (BindStage) Name() StageName

func (BindStage) Run 

func (BindStage) Run(_ context.Context, uri string, g *WorkspaceGraph) error

type ChangeAction 

type ChangeAction string

ChangeAction describes what kind of graph mutation occurred. 

const (
	ChangeAddSource    ChangeAction = "add_source"
	ChangeRemoveSource ChangeAction = "remove_source"
	ChangeAddEdge      ChangeAction = "add_edge"
	ChangeRemoveEdges  ChangeAction = "remove_edges"
	ChangeInvalidate   ChangeAction = "invalidate"
	ChangeSetRoot      ChangeAction = "set_root"
)

type ChangeEntry 

type ChangeEntry struct {
	Time     time.Time
	Action   ChangeAction
	URI      string
	Affected []string // URIs affected by this change
}

ChangeEntry records a single graph mutation for debugging and replay.

type ClassificationHint 

type ClassificationHint = navigator.ClassificationHint

ClassificationHint is an alias for navigator's ClassificationHint.

type DocumentSource 

type DocumentSource = navigator.DocumentSource

DocumentSource is an alias for navigator's DocumentSource interface.

type Edge 

type Edge = navgraph.Edge

Edge is an alias for navigator/graph.Edge.

type EdgeKind 

type EdgeKind = navgraph.EdgeKind

EdgeKind is an alias for navigator/graph.EdgeKind.

type FilesystemSource 

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

FilesystemSource reads documents from the local filesystem.

func NewFilesystemSource 

func NewFilesystemSource(path string, hint ClassificationHint) *FilesystemSource

NewFilesystemSource creates a source for a file on disk.

func (*FilesystemSource) Hint 

func (s *FilesystemSource) Hint() ClassificationHint

func (*FilesystemSource) Path 

func (s *FilesystemSource) Path() string

Path returns the absolute filesystem path.

func (*FilesystemSource) Read 

func (s *FilesystemSource) Read(_ context.Context) ([]byte, int64, error)

func (*FilesystemSource) URI 

func (s *FilesystemSource) URI() string

func (*FilesystemSource) Watch 

func (s *FilesystemSource) Watch(ctx context.Context, onChange func(string, navigator.WatchEvent)) func()

type GraphNode 

type GraphNode struct {
	Source       DocumentSource
	Version      int64
	Raw          []byte
	StageResults map[StageName]*StageResult
	DirtyStages  map[StageName]bool
	Diagnostics  []ctypes.Diagnostic
}

GraphNode holds all state for a single document in the workspace graph.

type LSPDocumentProvider 

type LSPDocumentProvider interface {
	Content(uri string) (text string, version int32, ok bool)
}

LSPDocumentProvider abstracts gossip's document.Store for reading document content without importing gossip in the core package. Matches the navigator/graph.LSPDocumentProvider interface.

type LSPSource 

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

LSPSource bridges gossip's in-memory document overlays with the graph engine.

func NewLSPSource 

func NewLSPSource(uri string, provider LSPDocumentProvider, hint ClassificationHint) *LSPSource

NewLSPSource creates a source backed by an LSP document overlay.

func (*LSPSource) Hint 

func (s *LSPSource) Hint() ClassificationHint

func (*LSPSource) Read 

func (s *LSPSource) Read(_ context.Context) ([]byte, int64, error)

func (*LSPSource) URI 

func (s *LSPSource) URI() string

func (*LSPSource) Watch 

func (s *LSPSource) Watch(_ context.Context, _ func(string, navigator.WatchEvent)) func()

type LintStage 

type LintStage struct{}

LintStage surfaces Navigator-owned parse/validation issues without re-deriving Telescope-local structural or schema diagnostics.

func (LintStage) DependsOn 

func (LintStage) DependsOn() []StageName

func (LintStage) Name 

func (LintStage) Name() StageName

func (LintStage) Run 

func (LintStage) Run(_ context.Context, uri string, g *WorkspaceGraph) error

type ParseOutput 

type ParseOutput struct {
	SemanticNode   *parser.SemanticNode
	PointerIndex   *parser.PointerIndex
	VirtualDocs    []parser.VirtualDocument
	NavigatorIndex *navigator.Index
}

ParseOutput holds the results of the parse stage.

type ParseStage 

type ParseStage struct {
	Parser    *parser.Parser
	Providers []parser.EmbeddedLanguageProvider
}

ParseStage builds the Navigator semantic/index view plus pointer metadata.

func (ParseStage) DependsOn 

func (s ParseStage) DependsOn() []StageName

func (ParseStage) Name 

func (s ParseStage) Name() StageName

func (ParseStage) Run 

func (s ParseStage) Run(_ context.Context, uri string, g *WorkspaceGraph) error

type PipelineRunner 

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

PipelineRunner orchestrates stage execution across the workspace graph. It respects stage dependencies, uses per-(URI, version) caching, and skips stages whose cached results are still valid.

func NewPipelineRunner 

func NewPipelineRunner(stages []Stage, logger *slog.Logger) (*PipelineRunner, error)

NewPipelineRunner creates a runner with the given stages. Stages are topologically sorted based on their DependsOn declarations.

func (*PipelineRunner) RunAll 

func (p *PipelineRunner) RunAll(ctx context.Context, uri string, g *WorkspaceGraph) error

RunAll executes all pipeline stages for a single URI. Stages with valid cached results are skipped.

func (*PipelineRunner) RunStage 

func (p *PipelineRunner) RunStage(ctx context.Context, uri string, g *WorkspaceGraph, stage StageName) error

RunStage executes a single named stage for a URI.

func (*PipelineRunner) RunThrough 

func (p *PipelineRunner) RunThrough(ctx context.Context, uri string, g *WorkspaceGraph, through StageName) error

RunThrough executes all stages up to and including the given stage.

func (*PipelineRunner) Stages 

func (p *PipelineRunner) Stages() []StageName

Stages returns the ordered list of stage names.

type RawStage 

type RawStage struct{}

RawStage reads content from the DocumentSource.

func (RawStage) DependsOn 

func (RawStage) DependsOn() []StageName

func (RawStage) Name 

func (RawStage) Name() StageName

func (RawStage) Run 

func (RawStage) Run(ctx context.Context, uri string, g *WorkspaceGraph) error

type ReadOnlyGraph 

type ReadOnlyGraph interface {
	Node(uri string) *GraphNode
	AllNodes() []string
	Roots() []string
	EdgesFrom(uri string) []Edge
	EdgesTo(uri string) []Edge
	HasIncomingRefs(uri string) bool
	Dependents(uri string) []string
	Dependencies(uri string) []string
	TransitiveDependencies(uri string) []string
	TransitiveDependents(uri string) []string
	DetectCycles() [][]string
}

ReadOnlyGraph provides a read-only view of the workspace graph for SDK consumers.

type Snapshot 

type Snapshot struct {
	ID              uint64
	Nodes           map[string]SnapshotNode
	Diagnostics     map[string][]ctypes.Diagnostic
	Roots           []string
	PointerIndices  map[string]*parser.PointerIndex
	VirtualDocs     map[string][]parser.VirtualDocument
	Classifications map[string]*classify.FileClassification
}

Snapshot is an immutable point-in-time view of the workspace graph state. Sync handlers read from the current snapshot; async analysis builds the next.

type SnapshotManager 

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

SnapshotManager holds the current snapshot and builds next snapshots atomically. Thread-safe for concurrent reads.

func NewSnapshotManager 

func NewSnapshotManager() *SnapshotManager

NewSnapshotManager creates a new SnapshotManager.

func (*SnapshotManager) Build 

func (m *SnapshotManager) Build(g *WorkspaceGraph) *Snapshot

Build creates a new snapshot from the graph's current state and swaps it in.

func (*SnapshotManager) BuildNext 

func (m *SnapshotManager) BuildNext(ctx context.Context, g *WorkspaceGraph, pipeline *PipelineRunner) *Snapshot

BuildNext runs the pipeline on all enqueued URIs, produces a new snapshot, and atomically swaps it as the current. If pipeline is nil, only the snapshot is rebuilt without running pipeline stages.

func (*SnapshotManager) Current 

func (m *SnapshotManager) Current() *Snapshot

Current returns the latest immutable snapshot.

func (*SnapshotManager) Enqueue 

func (m *SnapshotManager) Enqueue(uri string)

Enqueue marks a URI for re-processing in the next snapshot.

func (*SnapshotManager) OnSnapshot 

func (m *SnapshotManager) OnSnapshot(fn func(*Snapshot))

OnSnapshot registers a callback for when a new snapshot becomes current.

type SnapshotNode 

type SnapshotNode struct {
	URI          string
	Version      int64
	Raw          []byte
	StageResults map[StageName]interface{} // stage-specific cached data
}

SnapshotNode holds the immutable per-document state within a snapshot.

type Stage 

type Stage interface {
	// Name returns the unique identifier for this stage.
	Name() StageName

	// DependsOn returns the stages that must complete before this one.
	DependsOn() []StageName

	// Run executes the stage for a single document node. It may read
	// previous stage results from the graph and should store its result
	// via graph.SetStageResult().
	Run(ctx context.Context, uri string, graph *WorkspaceGraph) error
}

Stage represents a single processing step in the pipeline. Stages declare their dependencies and are executed in topological order.

func DefaultStages 

func DefaultStages() []Stage

DefaultStages returns the built-in stage implementations in dependency order.

type StageName 

type StageName = navgraph.StageName

StageName is an alias for navigator/graph.StageName.

type StageResult 

type StageResult struct {
	Stage       StageName           // which stage produced this
	Data        interface{}         // stage-specific output
	Version     int64               // document version when this result was computed
	Diagnostics []ctypes.Diagnostic // diagnostics produced by this stage
	Duration    time.Duration       // how long the stage took
}

StageResult holds the cached output of a pipeline stage.

type SyntheticSource 

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

SyntheticSource provides document content programmatically without a backing file. Used by the SDK to inject specs for analysis.

func NewSyntheticSource 

func NewSyntheticSource(uri string, content []byte, hint ClassificationHint) *SyntheticSource

NewSyntheticSource creates a source with initial content.

func (*SyntheticSource) Hint 

func (s *SyntheticSource) Hint() ClassificationHint

func (*SyntheticSource) Read 

func (s *SyntheticSource) Read(_ context.Context) ([]byte, int64, error)

func (*SyntheticSource) URI 

func (s *SyntheticSource) URI() string

func (*SyntheticSource) Update 

func (s *SyntheticSource) Update(content []byte)

Update replaces the content and bumps the version, notifying watchers.

func (*SyntheticSource) Watch 

func (s *SyntheticSource) Watch(_ context.Context, onChange func(string, navigator.WatchEvent)) func()

type ValidateStage 

type ValidateStage struct{}

ValidateStage is a compatibility pass-through stage retained so existing stage-based consumers keep the same topology while Navigator owns validation.

func (ValidateStage) DependsOn 

func (s ValidateStage) DependsOn() []StageName

func (ValidateStage) Name 

func (s ValidateStage) Name() StageName

func (ValidateStage) Run 

func (s ValidateStage) Run(_ context.Context, uri string, g *WorkspaceGraph) error

type WorkspaceGraph 

type WorkspaceGraph struct {
	ChangeLog []ChangeEntry
	// contains filtered or unexported fields
}

WorkspaceGraph is the unified directed graph replacing both project.FileGraph and openapi.IndexCache. It maintains forward/reverse edge indexes and per-node pipeline stage caches with invalidation cascades.

func NewWorkspaceGraph 

func NewWorkspaceGraph() *WorkspaceGraph

NewWorkspaceGraph creates an empty workspace graph.

func (*WorkspaceGraph) AddEdge 

func (g *WorkspaceGraph) AddEdge(edge Edge)

AddEdge records a directed edge. Duplicates are allowed (the graph stores all).

func (*WorkspaceGraph) AddSource 

func (g *WorkspaceGraph) AddSource(src DocumentSource)

AddSource adds a document source to the graph. If the URI already exists, its source is replaced.

func (*WorkspaceGraph) AllNodes 

func (g *WorkspaceGraph) AllNodes() []string

AllNodes returns all URIs in the graph.

func (*WorkspaceGraph) Dependencies 

func (g *WorkspaceGraph) Dependencies(uri string) []string

Dependencies returns URIs that the given URI references via any edge kind.

func (*WorkspaceGraph) Dependents 

func (g *WorkspaceGraph) Dependents(uri string) []string

Dependents returns URIs that reference the given URI via any edge kind.

func (*WorkspaceGraph) DetectCycles 

func (g *WorkspaceGraph) DetectCycles() [][]string

DetectCycles returns all URIs that participate in reference cycles.

func (*WorkspaceGraph) EdgesFrom 

func (g *WorkspaceGraph) EdgesFrom(uri string) []Edge

EdgesFrom returns all outgoing edges from the given URI.

func (*WorkspaceGraph) EdgesTo 

func (g *WorkspaceGraph) EdgesTo(uri string) []Edge

EdgesTo returns all incoming edges to the given URI (reverse lookup).

func (*WorkspaceGraph) HasIncomingRefs 

func (g *WorkspaceGraph) HasIncomingRefs(uri string) bool

HasIncomingRefs returns true if any edge points to the given URI, indicating it is a $ref target in the workspace graph.

func (*WorkspaceGraph) Invalidate 

func (g *WorkspaceGraph) Invalidate(uri string) []string

Invalidate marks all stages dirty for the given URI and cascades to dependent nodes. Returns the full set of affected URIs.

func (*WorkspaceGraph) Node 

func (g *WorkspaceGraph) Node(uri string) *GraphNode

Node returns the graph node for a URI, or nil if not found.

func (*WorkspaceGraph) RemoveEdgesFrom 

func (g *WorkspaceGraph) RemoveEdgesFrom(uri string) []string

RemoveEdgesFrom removes all outgoing edges from the given URI and returns the URIs of previously referenced targets.

func (*WorkspaceGraph) RemoveSource 

func (g *WorkspaceGraph) RemoveSource(uri string) []string

RemoveSource removes a document and all its edges from the graph. Returns the URIs of nodes that were affected by the removal.

func (*WorkspaceGraph) Roots 

func (g *WorkspaceGraph) Roots() []string

Roots returns all URIs marked as root documents.

func (*WorkspaceGraph) SetRoot 

func (g *WorkspaceGraph) SetRoot(uri string, isRoot bool)

SetRoot marks a URI as a root document (entry point).

func (*WorkspaceGraph) SetStageResult 

func (g *WorkspaceGraph) SetStageResult(uri string, stage StageName, result *StageResult)

SetStageResult stores a pipeline stage result for a URI.

func (*WorkspaceGraph) StageResult 

func (g *WorkspaceGraph) StageResult(uri string, stage StageName) *StageResult

StageResult returns the cached result for a pipeline stage, or nil.

func (*WorkspaceGraph) TransitiveDependencies 

func (g *WorkspaceGraph) TransitiveDependencies(uri string) []string

TransitiveDependencies returns all URIs reachable by walking outgoing edges from the given URI (breadth-first). The starting URI is not included.

func (*WorkspaceGraph) TransitiveDependents 

func (g *WorkspaceGraph) TransitiveDependents(uri string) []string

TransitiveDependents returns all URIs reachable by walking reverse edges from the given URI (breadth-first). The starting URI is not included.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.