callgraph

type BuildOpts struct {
	// IncludeFieldAccess keeps heuristic argref/field-access call sites even
	// when they don't resolve to a known function symbol. Default false —
	// unresolved CallSite.IsArgRef entries are dropped to avoid reporting
	// vars (`ctx`, `localPath`) and member access (`opts.Slug`) as callees.
	IncludeFieldAccess bool
}

type CallChainNode struct {
	Symbol      *parser.Symbol    `json:"symbol"`
	Children    []CallChainNode   `json:"children,omitempty"`
	CallLine    uint32            `json:"callLine,omitempty"`
	Cycle       bool              `json:"cycle,omitempty"`
	Speculative []SpeculativeCall `json:"speculative,omitempty"` // candidates for unresolved calls
	Kind        string            `json:"kind,omitempty"`        // empty = normal; CrossLanguageFetchKind for synthetic nodes
	Depth       int               `json:"depth,omitempty"`       // only set on synthetic cross-language nodes
}

type CallEdge struct {
	Caller      *parser.Symbol // function containing the call
	Callee      *parser.Symbol // target function (nil if unresolved)
	CalleeName  string         // original name from source
	Receiver    string         // qualifier if method call
	Line        uint32         // 1-based call site line
	IsInterface bool           // true when resolved via interface dispatch (go/types or SCIP)
}

type CallGraph struct {
	Edges         []CallEdge
	Symbols       []*parser.Symbol
	TypeRels      []parser.TypeRelationship // interface/extends/embeds relationships
	HookCallbacks []string                  // function names registered as hook callbacks
	Tier          string                    // "basic" (tree-sitter), "enhanced" (go/types merged), "full" (future)
	Backend       string                    // resolution backend: "tree-sitter", "tree-sitter+go/types", "tree-sitter+scip"
	// UsesIndex maps a target file's relative path to a list of relative paths
	// of Astro files that render it as a component (<Foo />). Populated by
	// ResolveTemplateRefs during BuildFromRepo. Enables impact_analysis to
	// report file-level USES callers for Astro components.
	UsesIndex map[string][]string
}

type HookRoute struct {
	Method  string // "ACTION" or "FILTER"
	Path    string // hook name
	Handler string // callback function name (empty for client-side)
	Side    string // "server" or "client"
	Line    uint32
}

type SpeculativeCall struct {
	Name       string  `json:"name"`
	File       string  `json:"file"`
	Line       int     `json:"line"`
	Confidence float64 `json:"confidence"` // 0.0-1.0
}

type TemplateUsage struct {
	// From is the relative path of the file that contains the template ref.
	From string
	// To is the relative path of the imported component file.
	To string
	// Line is the 1-based line number of the tag usage in the source file.
	Line uint32
}

type TraceOpts struct {
	Direction string // "callees" (default) or "callers"
	MaxDepth  int    // default 5, max 10

	// CrossRefs, when non-nil, extends the trace through HANDLES/FETCHES
	// edges at +1 depth beyond the existing call graph. Noop when nil.
	CrossRefs graphx.CrossRefs
	// Repo is the repo key used for CrossRefs lookups. Required when CrossRefs is set.
	Repo string
}

type TraceRepoInput struct {
	Root     string
	Symbol   string
	Focus    string
	Language string
	Opts     TraceOpts

	// IncludeFieldAccess keeps heuristic argref/field-access call sites even
	// when they don't resolve to a known function symbol. Default false —
	// unresolved argref captures (`opts.Slug`, `ctx`, `localPath`) are
	// dropped. Set via the `field_access=true` MCP tool flag for legacy
	// permissive behaviour.
	IncludeFieldAccess bool
}

type TraceResult struct {
	Root       *parser.Symbol  `json:"root,omitempty"`
	Tree       []CallChainNode `json:"tree"`
	MaxDepth   int             `json:"maxDepth"`
	TotalNodes int             `json:"totalNodes"`
	Resolved   int             `json:"resolved"`
	Unresolved int             `json:"unresolved"`
	Tier       string          `json:"tier,omitempty"`
}