parser

type CallSite struct {
	Name     string // called function or method name
	Receiver string // qualifier for method calls (e.g. "fmt" in "fmt.Println"), empty for plain calls
	Line     uint32 // 1-based line number
	File     string // absolute file path
	// IsArgRef is true when this site comes from a heuristic argument-position
	// or struct-literal-value capture (e.g. `Register("x", handler)` —
	// `handler`). Most of these are plain values, not function references, so
	// the call graph drops unresolved IsArgRef sites unless the caller opts in
	// via the MCP field_access=true flag (filtered in the callgraph layer).
	IsArgRef bool
}

type Capabilities struct {
	// SitterLanguage is the tree-sitter grammar. Nil for fallback/regex-only handlers.
	SitterLanguage *sitter.Language

	// TagsQuery is the compiled query for symbol extraction (functions, types, etc.).
	TagsQuery *sitter.Query

	// CallsQuery is the compiled query for call-site extraction. Nil if unsupported.
	CallsQuery *sitter.Query

	// RelationshipsQuery is the compiled query for type relationship extraction. Nil if unsupported.
	RelationshipsQuery *sitter.Query

	// MapCapture converts a single tree-sitter capture into a Symbol.
	// Bound to the handler method so it can access handler-specific logic.
	// Returns nil if the capture should be skipped.
	//
	// IMPORTANT: wire this from a POINTER receiver (e.g. goLang.MapCapture where
	// goLang is *goHandler). A value-receiver bound before init() finishes would
	// capture a zero-value copy and miss any subsequent field writes on the
	// singleton.
	MapCapture func(captureName string, node *sitter.Node, src []byte) *Symbol
}

type LanguageHandler interface {
	// Language returns the canonical language name (e.g. "go", "python").
	Language() string

	// Extensions returns the file extensions handled (e.g. [".go"]).
	Extensions() []string

	// Parse parses the given source file and returns its symbol table.
	// path is used for language detection and populating Symbol.File fields.
	Parse(path string, src []byte, opts ParseOpts) (*ParseResult, error)

	// Capabilities returns the compiled tree-sitter queries and language
	// grammar reference for this handler. Callers use this to determine
	// whether call extraction or relationship extraction is supported.
	Capabilities() Capabilities

	// MapCapture converts a single tree-sitter capture into a Symbol.
	// Returns nil if the capture should be skipped.
	MapCapture(captureName string, node *sitter.Node, source []byte) *Symbol
}

type NodeKind string

type ParseOpts struct {
	// Language overrides auto-detection.
	Language string

	// Parser is an optional tree-sitter parser to reuse. When non-nil, Parse
	// will use it instead of creating a new parser. The caller retains
	// ownership and must not use it concurrently.
	Parser *sitter.Parser

	// IncludeBody includes the full source text of each symbol.
	IncludeBody bool

	// IncludeImports includes import declarations in the result.
	IncludeImports bool

	// IncludeTypeRels extracts type relationships (embeds/extends/implements)
	// during parse. When false, TypeRels is left empty.
	IncludeTypeRels bool
}

type ParseResult struct {
	// File is the absolute path to the parsed file.
	File string

	// Language is the detected programming language.
	Language string

	// Symbols is the ordered list of symbols found in the file.
	Symbols []*Symbol

	// Imports is the list of import paths/modules declared in the file.
	Imports []string

	// TemplateRefs holds capitalised JSX-style component tag usages found in
	// the template body of Astro (and future Svelte/Vue) files. Empty for all
	// other languages. Each entry is one occurrence; callers may deduplicate.
	// Resolution of names to file paths requires joining against Imports.
	TemplateRefs []preproc.TemplateRef `json:"template_refs,omitempty"`

	// TypeRels is the list of type relationships (embeds/extends/implements)
	// extracted during parse. Populated only when ParseOpts.IncludeTypeRels is true.
	TypeRels []TypeRelationship `json:"type_rels,omitempty"`

	// Lines is the number of lines in the source file. Optional; populated by
	// callers that already count lines while reading source.
	Lines int `json:"lines,omitempty"`

	// Error is set if parsing failed or produced an error node in the tree.
	Error error
}

type RelKind string

type Symbol struct {
	// Name is the symbol's identifier (e.g. "ServeHTTP", "Config", "maxRetries").
	Name string

	// Kind is the symbol type (function, struct, etc.).
	Kind NodeKind

	// Language is the source language (go, python, etc.).
	Language string

	// File is the absolute path to the source file.
	File string

	// StartLine is the 1-based line number where the symbol definition begins.
	StartLine uint32

	// EndLine is the 1-based line number where the symbol definition ends.
	EndLine uint32

	// Signature is the function/type signature extracted from the AST.
	// For functions: full signature with parameters and return types.
	// For types: the type definition header.
	Signature string

	// Body is the full source text of the symbol (only populated when requested).
	Body string

	// DocComment is the documentation comment immediately preceding the symbol.
	DocComment string

	// Complexity is the estimated cyclomatic complexity of the function/method body.
	// Only populated for functions and methods (0 for other symbol kinds).
	Complexity int

	// CognitiveComplexity is the cognitive complexity of the function body (nesting-aware).
	// Only populated for functions and methods (0 for other kinds).
	CognitiveComplexity int

	// BodyHash is a content hash of the normalized symbol body.
	// Used for fast equality checks in code comparison (0 means not computed).
	BodyHash uint64

	// Receiver is the type name for methods (e.g. "Config" for impl Config,
	// "Display for Config" for impl Display for Config). Empty for free functions.
	Receiver string

	// IsPublic indicates the symbol has public visibility (pub in Rust, uppercase in Go).
	IsPublic bool

	// Attributes are annotations/decorators (e.g. "#[test]", "#[derive(Clone)]").
	Attributes []string

	// RuneKind is the canonical Svelte 5 rune category for KindRune symbols.
	// Values: "state", "derived", "effect", "props", "bindable", "inspect", "host".
	// Empty for all non-rune symbols.
	RuneKind string
}

type TypeRelationship struct {
	Subject string  // the type declaring the relationship
	Target  string  // the referenced type
	Kind    RelKind // relationship kind
	Line    uint32  // 1-based line number
	File    string  // absolute file path
}