analysis

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

	// PackageSymbols maps package names to ALL symbols (exported and
	// non-exported). Used by resolveQualifiedSymbol as a fallback when
	// a qualified reference (pkg:sym) targets a non-exported symbol.
	// ELPS runtime allows qualified access to any symbol in a package,
	// not just exported ones.
	PackageSymbols map[string][]ExternalSymbol

	// DefForms declares additional definition-form heads for embedding programs.
	// Head is matched exactly against the form head symbol. FormalsIndex must
	// point at the parameter list cell. If BindsName is true, NameIndex points
	// at the defined symbol cell and the analyzer registers it using NameKind.
	DefForms []DefFormSpec

	// PackageImports maps package name to imported package names collected
	// from cross-file use-package declarations during workspace prescan.
	// Per-file analysis applies these imports so symbols from packages
	// imported in other files (e.g. main.lisp) are available.
	PackageImports map[string][]string

	// DefaultPackage overrides the default "user" package for bare files
	// (no in-package declaration). Derived from main.lisp's in-package.
	DefaultPackage string

	// WorkspaceRefs maps SymbolKey.String() to cross-file references.
	// When set, analyzers can check whether a symbol is referenced from
	// other files in the workspace.
	WorkspaceRefs map[string][]FileReference

	// MacroExpander optionally expands user-macro calls at analysis time.
	// When set, the analyzer expands macro calls and analyzes the expanded
	// code, resolving symbols introduced by the macro (e.g. lambda params).
	// If expansion fails, the analyzer falls back to opaque macro handling.
	MacroExpander MacroExpander

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

type DefFormSpec struct {
	Head         string
	FormalsIndex int
	BindsName    bool
	NameIndex    int
	NameKind     SymbolKind
}

type EnvMacroExpander struct {
	Env *lisp.LEnv
	// contains filtered or unexported fields
}

type ExpansionPanic struct {
	// Value is what recover() returned at the aborted call. It is nil in the
	// one case that is not a panic at all: runtime.Goexit unwinding through
	// ExpandMacro (a macro body that reached t.Fatal, say). The abort is
	// counted either way — see EnvMacroExpander.ExpansionPanics.
	Value any

	// GoStack is the Go stack captured inside the recover handler. That
	// handler runs before the panic unwind completes, so the stack points at
	// the panic site rather than at the handler — the same property
	// lisp.(*LEnv).eval relies on when it fills CallStack.GoStack.
	GoStack []byte

	// Macro is the head symbol of the form being expanded and Package the
	// package context it was expanded in, when they could be read. Both are
	// best-effort diagnostics: the form itself may be what was malformed.
	Macro   string
	Package string
}

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

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
}

type MacroExpander interface {
	ExpandMacro(form *lisp.LVal, pkg string) *lisp.LVal
}

type PanicReporter interface {
	// ExpansionPanics returns the number of ExpandMacro calls that did not
	// complete normally over the lifetime of the expander.
	ExpansionPanics() uint64
}

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

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

	// ExtraGlobals are the external symbols that were provided via Config.
	// Stored here so downstream consumers (e.g. lint analyzers) can check
	// for cross-file duplicates without relying on scope lookups that may
	// have been overwritten by local definitions.
	ExtraGlobals []ExternalSymbol

	// WorkspaceRefs maps SymbolKey.String() to cross-file references.
	// Copied from Config. Used by lint analyzers to check whether a symbol
	// is referenced from other workspace files (e.g. unused-function check).
	WorkspaceRefs map[string][]FileReference
}

type ScanConfig struct {
	// MaxFiles is the maximum number of .lisp files to collect.
	// 0 means use DefaultMaxWorkspaceFiles.
	MaxFiles int
	// MaxFileBytes is the maximum size in bytes for a single file.
	// Files exceeding this are skipped. 0 means use DefaultMaxFileBytes.
	MaxFileBytes int64
	// Excludes are glob patterns for files to skip during collection.
	// Patterns are matched against the full path, base name, and each
	// directory component using filepath.Match semantics.
	Excludes []string
	// IncludeDirs are directory names that override ShouldSkipDir.
	// If a directory name matches any entry, it will be walked even if
	// ShouldSkipDir would normally skip it (e.g. "_examples").
	IncludeDirs []string
}

type Scope struct {
	Kind           ScopeKind
	Parent         *Scope
	Children       []*Scope
	Symbols        map[string]*Symbol
	PackageSymbols map[string]*Symbol
	PackageImports map[string]map[string]*Symbol

	Node *lisp.LVal // the AST node that introduced this scope
	// contains filtered or unexported fields
}

type ScopeKind int

type Signature struct {
	Params []lisp.ParamInfo
}

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

type SymbolKey struct {
	Package string
	Name    string
	Kind    SymbolKind
}

type SymbolKind int

type UnresolvedRef struct {
	Name   string
	Source *token.Location
	Node   *lisp.LVal
	// InsideMacroCall is true when the unresolved reference appears inside
	// a user-defined macro call body. Macros may introduce bindings at
	// expansion time that are invisible to static analysis.
	InsideMacroCall bool
}

type WorkspacePrescan struct {
	// Files is the list of .lisp file paths that were scanned.
	Files []string
	// Truncated is true if the file limit was reached during collection.
	Truncated bool
	// ExportedGlobals are exported top-level definitions only.
	// Used by ScanWorkspaceAllWithConfig for backwards compatibility.
	ExportedGlobals []ExternalSymbol
	// PkgExports maps package name to exported symbols.
	PkgExports map[string][]ExternalSymbol
	// AllDefs are all definitions (exported and non-exported).
	// Typically used as Config.ExtraGlobals for cross-file resolution.
	AllDefs []ExternalSymbol
	// PkgAllSymbols maps package name to ALL symbols (exported and
	// non-exported). Used for qualified symbol resolution since ELPS
	// runtime allows pkg:sym access to any symbol in a package.
	PkgAllSymbols map[string][]ExternalSymbol
	// DefForms are DefFormSpecs derived from defmacro definitions whose
	// names start with "def". These can be injected into Config.DefForms
	// for per-file analysis.
	DefForms []DefFormSpec
	// PackageImports maps package name to the list of packages imported
	// via use-package across all workspace files. This enables per-file
	// analysis to resolve symbols from cross-file use-package declarations.
	PackageImports map[string][]string
	// Preamble contains package-management and macro-definition forms
	// (in-package, use-package, export, defmacro) from all workspace files,
	// in source order per file. Pass these to LoadWorkspaceMacros to replay
	// the package setup and register macros in a runtime environment.
	Preamble []*lisp.LVal
	// DefaultPackage is the package declared in main.lisp (if present).
	// Used as the default for bare files (no in-package) so that cross-file
	// resolution works in projects where files inherit the package from
	// load order.
	DefaultPackage string
}