scope

Documentation

Overview

Package scope provides the scope graph data model for the canopyls LSP server. A scope graph represents lexical scoping structure: definitions introduced in each scope, references that need resolution, and parent/child nesting.

Index

• Constants
• func GetMeta[T any](d *Definition, key string) (T, bool)
• func ResolveAll(root *Scope)
• func ResolveAllGraph(root *Scope, graph *Graph)
• func ResolvePythonImport(importPath string, projectRoot string) string
• func ResolveTypeScriptImport(importPath string, sourceFile string, projectRoot string) string
• func SetMeta(d *Definition, key string, value any)
• type Definition
• type GoImportResolver
  • func NewGoImportResolver(rootDir, modulePath string) *GoImportResolver
  • func (r *GoImportResolver) Resolve(importPath string) (string, error)
• type Graph
  • func BuildFromIndex(idx *model.Index, rootPath string) (*Graph, error)
  • func NewGraph() *Graph
  • func (g *Graph) AddFileScope(path string, s *Scope)
  • func (g *Graph) AddPackageScope(importPath string, s *Scope)
  • func (g *Graph) FileScope(path string) *Scope
  • func (g *Graph) PackageScope(importPath string) *Scope
• type Location
• type Ref
• type Rules
  • func LoadRules(langName string, lang *gotreesitter.Language) (*Rules, error)
• type Scope
  • func BuildFileScope(tree *gotreesitter.Tree, lang *gotreesitter.Language, src []byte, rules *Rules, ...) *Scope
  • func NewScope(kind ScopeKind, parent *Scope) *Scope
  • func (s *Scope) AddDef(def Definition)
  • func (s *Scope) AddRef(ref Ref)
• type ScopeKind

Constants

const (
	DefFunction  = "function"
	DefMethod    = "method"
	DefVariable  = "variable"
	DefParam     = "param"
	DefType      = "type"
	DefClass     = "class"
	DefImport    = "import"
	DefConstant  = "constant"
	DefField     = "field"
	DefInterface = "interface"
)

DefKind constants classify the type of a definition.

Functions

func GetMeta

func GetMeta[T any](d *Definition, key string) (T, bool)

GetMeta retrieves a typed value from definition metadata. Returns zero value and false if the key is missing or wrong type.

func ResolveAll

func ResolveAll(root *Scope)

ResolveAll walks the scope tree and resolves all references using only scope-chain lookup (no cross-file type resolution).

func ResolveAllGraph

func ResolveAllGraph(root *Scope, graph *Graph)

ResolveAllGraph walks the scope tree and resolves all references, using the graph for cross-file type-directed resolution.

func ResolvePythonImport

func ResolvePythonImport(importPath string, projectRoot string) string

ResolvePythonImport resolves a Python import path to a directory on disk. Searches: project root, then common site-packages locations.

func ResolveTypeScriptImport

func ResolveTypeScriptImport(importPath string, sourceFile string, projectRoot string) string

ResolveTypeScriptImport resolves a TypeScript/JavaScript import path to a file. Handles: relative paths, node_modules, @types.

func SetMeta

func SetMeta(d *Definition, key string, value any)

SetMeta writes a value to definition metadata, initializing the map if needed.

Types

type Definition

type Definition struct {
	Name       string
	Kind       string // one of the Def* constants
	TypeAnnot  string // explicit type annotation if present
	ImportPath string // for import definitions
	Loc        Location
	Scope      *Scope // child scope this definition creates (e.g. function body)

	// Type intelligence
	ReturnType  string   // function/method return type
	BaseClasses []string // inheritance chain
	Receiver    string   // method receiver type
	TypeParams  []string // generics: T, K, V

	// Feed metadata (any feed can write, LSP handlers read)
	Metadata map[string]any
}

Definition is a named symbol introduced into a scope.

type GoImportResolver

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

GoImportResolver resolves Go import paths to filesystem directories.

func NewGoImportResolver

func NewGoImportResolver(rootDir, modulePath string) *GoImportResolver

func (*GoImportResolver) Resolve

func (r *GoImportResolver) Resolve(importPath string) (string, error)

Resolve maps an import path to a directory on disk.

type Graph

type Graph struct {
	FileScopes map[string]*Scope
	Packages   map[string]*Scope
}

Graph holds all scope trees for a project, indexed by file path and package import path.

func BuildFromIndex

func BuildFromIndex(idx *model.Index, rootPath string) (*Graph, error)

BuildFromIndex constructs a scope graph for all files in an index.

func NewGraph

func NewGraph() *Graph

NewGraph creates an empty scope graph.

func (*Graph) AddFileScope

func (g *Graph) AddFileScope(path string, s *Scope)

AddFileScope stores a file-level scope for the given file path.

func (*Graph) AddPackageScope

func (g *Graph) AddPackageScope(importPath string, s *Scope)

AddPackageScope stores a package-level scope for the given import path.

func (*Graph) FileScope

func (g *Graph) FileScope(path string) *Scope

FileScope retrieves the scope for the given file path, or nil if not found.

func (*Graph) PackageScope

func (g *Graph) PackageScope(importPath string) *Scope

PackageScope retrieves the scope for the given import path, or nil if not found.

type Location

type Location struct {
	File      string
	StartLine int
	EndLine   int
	StartCol  int
	EndCol    int
}

Location identifies a span in a source file.

type Ref

type Ref struct {
	Name     string
	Member   string // for dotted access: foo.Bar -> Member="Bar"
	Loc      Location
	Resolved *Definition // populated by the resolution pass
}

Ref is a use of a name that needs resolution.

type Rules

type Rules struct {
	Language string
	Query    *gotreesitter.Query
}

Rules holds a compiled scope query for a language.

func LoadRules

func LoadRules(langName string, lang *gotreesitter.Language) (*Rules, error)

LoadRules loads and compiles the .scm scope rules for a language.

type Scope

type Scope struct {
	Kind     ScopeKind
	Parent   *Scope
	Children []*Scope
	Defs     []Definition
	Refs     []Ref
}

Scope represents a lexical scope containing definitions, references, and nested child scopes.

func BuildFileScope

func BuildFileScope(
	tree *gotreesitter.Tree,
	lang *gotreesitter.Language,
	src []byte,
	rules *Rules,
	path string,
) *Scope

BuildFileScope constructs a scope tree from a parse tree using scope rules.

func NewScope

func NewScope(kind ScopeKind, parent *Scope) *Scope

NewScope creates a new scope of the given kind and attaches it as a child of the parent scope. If parent is nil, the scope is a root.

func (*Scope) AddDef

func (s *Scope) AddDef(def Definition)

AddDef adds a definition to this scope.

func (*Scope) AddRef

func (s *Scope) AddRef(ref Ref)

AddRef adds a reference to this scope.

type ScopeKind

type ScopeKind int

ScopeKind classifies the type of lexical scope.

const (
	ScopeFile ScopeKind = iota
	ScopePackage
	ScopeModule
	ScopeClass
	ScopeFunction
	ScopeBlock
)