analysis

package
v1.31.0 Latest Latest
Warning

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

 Go to latest Published: Mar 1, 2026 License: BSD-3-Clause Imports: 9 Imported by: 0

Documentation

Overview

Package analysis provides scope-aware semantic analysis for ELPS lisp source.

The analyzer builds a scope tree from parsed expressions, resolves symbol references, and identifies unresolved symbols. It is designed to be used by lint analyzers for semantic checks like undefined-symbol and unused-variable.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ExtractPackageExports 

func ExtractPackageExports(reg *lisp.PackageRegistry) map[string][]ExternalSymbol

ExtractPackageExports creates a map of package name to exported symbols from a loaded runtime's package registry. This is used to resolve use-package imports for packages defined in Go (stdlib) that cannot be found by workspace scanning.

func ScanWorkspacePackages 

func ScanWorkspacePackages(root string) (map[string][]ExternalSymbol, error)

ScanWorkspacePackages is like ScanWorkspace but returns a map of package name to exported symbols, suitable for use as Config.PackageExports.

func ScanWorkspaceRefs added in v1.31.0 

func ScanWorkspaceRefs(root string, cfg *Config) map[string][]FileReference

ScanWorkspaceRefs walks the workspace directory tree, performs full analysis on each .lisp file, and extracts cross-file references. The cfg should have ExtraGlobals and PackageExports populated from a prior ScanWorkspaceFull call.

Returns a map from SymbolKey.String() to FileReference slices.

Types

type Config 

type Config struct {
	// ExtraGlobals are symbols from other files (e.g. workspace scanning).
	ExtraGlobals []ExternalSymbol

	// PackageExports maps package names to their exported symbols.
	// Used to resolve use-package imports from stdlib and workspace packages.
	PackageExports map[string][]ExternalSymbol

	// Filename is the source file being analyzed.
	Filename string
}

Config controls the behavior of the analyzer.

type ExternalSymbol 

type ExternalSymbol struct {
	Name      string
	Kind      SymbolKind
	Package   string
	Signature *Signature
	Source    *token.Location
	DocString string
}

ExternalSymbol represents a symbol defined in another file.

func ScanWorkspace 

func ScanWorkspace(root string) ([]ExternalSymbol, error)

ScanWorkspace walks a directory tree, parsing all .lisp files and extracting exported top-level definitions. The result can be used as Config.ExtraGlobals for cross-file symbol resolution.

Files that fail to parse are silently skipped (fault tolerant).

func ScanWorkspaceFull added in v1.27.0 

func ScanWorkspaceFull(root string) ([]ExternalSymbol, map[string][]ExternalSymbol, error)

ScanWorkspaceFull walks a directory tree in a single pass, parsing all .lisp files and extracting both global symbols and package exports. It skips hidden directories (names starting with '.') and node_modules.

Files that fail to parse are silently skipped (fault tolerant).

type FileReference added in v1.31.0 

type FileReference struct {
	SymbolKey       SymbolKey
	Source          *token.Location
	File            string          // absolute path
	Enclosing       string          // name of enclosing function ("" if top-level)
	EnclosingSource *token.Location // definition site of enclosing function
	EnclosingKind   SymbolKind      // kind of enclosing function
}

FileReference represents a cross-file reference to a symbol.

func ExtractFileRefs added in v1.31.0 

func ExtractFileRefs(result *Result, filePath string) []FileReference

ExtractFileRefs extracts cross-file-trackable references from an analysis result. Only references to global-scope, non-builtin symbols are included (builtins, special ops, parameters, and locals are skipped).

type Reference 

type Reference struct {
	Symbol *Symbol
	Source *token.Location
	Node   *lisp.LVal
}

Reference records a resolved symbol usage.

type Result 

type Result struct {
	RootScope  *Scope
	Symbols    []*Symbol
	References []*Reference
	Unresolved []*UnresolvedRef
}

Result holds the output of semantic analysis.

func Analyze 

func Analyze(exprs []*lisp.LVal, cfg *Config) *Result

Analyze performs semantic analysis on a set of parsed expressions. It builds a scope tree, resolves references, and collects unresolved symbols.

func AnalyzeFile added in v1.31.0 

func AnalyzeFile(source []byte, filename string, cfg *Config) *Result

AnalyzeFile parses and performs full semantic analysis on a single file. Returns nil if the file fails to parse.

type Scope 

type Scope struct {
	Kind     ScopeKind
	Parent   *Scope
	Children []*Scope
	Symbols  map[string]*Symbol
	Node     *lisp.LVal // the AST node that introduced this scope
}

Scope represents a lexical scope in the source.

func NewScope 

func NewScope(kind ScopeKind, parent *Scope, node *lisp.LVal) *Scope

NewScope creates a new scope of the given kind with the given parent.

func ScopeAtPosition added in v1.31.0 

func ScopeAtPosition(root *Scope, line, col int) *Scope

ScopeAtPosition returns the innermost scope that contains the given 1-based ELPS line and column. It walks the scope tree depth-first.

func (*Scope) Define 

func (s *Scope) Define(sym *Symbol)

Define adds a symbol to this scope.

func (*Scope) Lookup 

func (s *Scope) Lookup(name string) *Symbol

Lookup resolves a symbol by walking the parent chain. Returns nil if the symbol is not found.

func (*Scope) LookupLocal 

func (s *Scope) LookupLocal(name string) *Symbol

LookupLocal resolves a symbol only in this scope (not parents).

type ScopeKind 

type ScopeKind int

ScopeKind classifies the kind of scope. 

const (
	ScopeGlobal   ScopeKind = iota // file/module level
	ScopeFunction                  // defun/defmacro body
	ScopeLambda                    // lambda body
	ScopeLet                       // let/let* body
	ScopeFlet                      // flet/labels body
	ScopeDotimes                   // dotimes body
)

func (ScopeKind) String 

func (k ScopeKind) String() string

type Signature 

type Signature struct {
	Params []lisp.ParamInfo
}

Signature describes the parameter signature of a callable symbol.

func (*Signature) MaxArity 

func (sig *Signature) MaxArity() int

MaxArity returns the maximum number of arguments accepted. Returns -1 for variadic functions (those with &rest or &key params).

func (*Signature) MinArity 

func (sig *Signature) MinArity() int

MinArity returns the minimum number of arguments required.

type Symbol 

type Symbol struct {
	Name       string
	Kind       SymbolKind
	Source     *token.Location // nil for builtins
	Scope      *Scope
	Signature  *Signature // non-nil for callables
	DocString  string
	References int
	Exported   bool
	External   bool // true for workspace-scanned or package-imported symbols
}

Symbol represents a defined name in a scope.

func FindEnclosingFunction added in v1.31.0 

func FindEnclosingFunction(root *Scope, line, col int) *Symbol

FindEnclosingFunction finds the function symbol that contains the given 1-based position by walking the scope tree.

type SymbolKey added in v1.31.0 

type SymbolKey struct {
	Name string
	Kind SymbolKind
}

SymbolKey identifies a symbol across files by name and kind.

func SymbolKeyFromNameKind added in v1.31.0 

func SymbolKeyFromNameKind(name string, kind string) SymbolKey

SymbolKeyFromNameKind creates a SymbolKey from raw name and kind strings. The kind string should match SymbolKind.String() output.

func SymbolToKey added in v1.31.0 

func SymbolToKey(sym *Symbol) SymbolKey

SymbolToKey derives a SymbolKey from an analysis Symbol.

func (SymbolKey) String added in v1.31.0 

func (k SymbolKey) String() string

String returns a lookup key for use in maps.

type SymbolKind 

type SymbolKind int

SymbolKind classifies a symbol definition. 

const (
	SymVariable  SymbolKind = iota // set, let binding
	SymFunction                    // defun, flet/labels binding
	SymMacro                       // defmacro
	SymParameter                   // function/lambda parameter
	SymSpecialOp                   // special operator (if, cond, etc.)
	SymBuiltin                     // builtin function
	SymType                        // deftype
)

func (SymbolKind) String 

func (k SymbolKind) String() string

type UnresolvedRef 

type UnresolvedRef struct {
	Name   string
	Source *token.Location
	Node   *lisp.LVal
}

UnresolvedRef records a symbol usage that could not be resolved.

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.