compound

type BodyAnalysis struct {
	ErrorExits      int  `json:"error_exits"` // panic/return err patterns
	HasDeferCleanup bool `json:"has_defer_cleanup"`
	HasTODO         bool `json:"has_todo"`
}

type CallRef struct {
	Name     string `json:"name"`
	File     string `json:"file"`
	Line     uint32 `json:"line"`
	Receiver string `json:"receiver,omitempty"`
}

type DeadCodeScoreLookup interface {
	LoadDeadCodeScore(ctx context.Context, repoKey, name, file string) (float32, bool)
}

type LearningsLookup interface {
	Nearest(ctx context.Context, repo, symbol string, k int) ([]learnings.Record, error)
}

type MatchRef struct {
	Name     string `json:"name"`
	Kind     string `json:"kind"`
	File     string `json:"file"`
	Line     uint32 `json:"line"`
	Receiver string `json:"receiver,omitempty"`
}

type PrepareChangeOpts struct {
	MaxDepth int // max impact traversal depth (default 5)

	// Graph optionally surfaces community and pagerank signals for the target
	// and its direct callers. When nil the new fields stay zero and are omitted.
	Graph graphx.Analytics

	// Repo is the user-supplied repo key (host-facing form).
	Repo string

	// Root is the container-resolved repo path used to key the persistent
	// graph. When set, takes precedence over Repo for graph lookups because
	// the graph is indexed under the resolved path, not the user-facing one.
	Root string
}

type PrepareChangeResult struct {
	Found    bool             `json:"found"`
	Symbol   SymbolInfo       `json:"symbol,omitempty"`
	Impact   *impact.Result   `json:"impact,omitempty"`
	IsDead   bool             `json:"is_dead"`
	DeadCode *deadcode.Result `json:"dead_code_summary,omitempty"`
	Tier     string           `json:"tier"`
	Warnings []string         `json:"warnings,omitempty"`

	// CommunitiesCrossed is the count of distinct Louvain community IDs among
	// the target symbol and its direct callers. Zero when Graph is cold
	// (all Found=false) — omitted from JSON output in that case.
	CommunitiesCrossed int `json:"communities_crossed,omitempty"`

	// HighPRCallers names direct callers whose PageRank is in the repo-level
	// top decile (top 10% by TopPageRank). Nil when Graph is cold or no
	// caller qualifies — omitted from JSON output in that case.
	HighPRCallers []string `json:"high_pagerank_callers,omitempty"`
}

type SymbolInfo struct {
	Name       string `json:"name"`
	Kind       string `json:"kind"`
	File       string `json:"file"`
	StartLine  uint32 `json:"start_line"`
	EndLine    uint32 `json:"end_line"`
	Signature  string `json:"signature,omitempty"`
	Complexity int    `json:"complexity,omitempty"`
	Receiver   string `json:"receiver,omitempty"`
}

type SymbolRanker interface {
	SymbolStructuralRank(ctx context.Context, repoKey, name, file string, pagerank float64) string
}

type UnderstandOpts struct {
	IncludeCallers bool
	MaxCallees     int // default 20
	MaxCallers     int // default 20

	// OxCodes enables body analysis via ox-codes scoped search. Optional.
	OxCodes *oxcodes.Client

	// Root is the repository root path, required when OxCodes is set.
	Root string

	// Repo is the user-supplied repo key (slug, URL, or host path) used to
	// look up prior learnings. Must match the value persisted by
	// review_pr (dry_run=false) for lookups to succeed.
	Repo string

	// Learnings optionally sources prior review findings for the symbol.
	// When nil (not configured) or Nearest returns no rows, the result's
	// PriorLearnings field stays empty and is omitted from JSON output.
	Learnings LearningsLookup

	// Graph optionally surfaces pagerank/community/surprise for the symbol.
	// When nil or the graph has no snapshot, GraphSignals.Found stays false.
	Graph graphx.Analytics

	// Refs optionally sources cross-reference edges from the AGE graph.
	// Used to surface tested_by coverage edges. When nil, tested_by is omitted.
	Refs graphx.CrossRefs

	// DeadCodeScores optionally sources CE reranker scores for dead-code detection.
	// When nil, dead_code_score is omitted from the result.
	DeadCodeScores DeadCodeScoreLookup

	// SymbolRanker optionally computes a human-readable structural importance rank.
	// When nil, structural_rank is omitted from the result.
	SymbolRanker SymbolRanker
}

type UnderstandResult struct {
	Symbol         SymbolInfo         `json:"symbol"`
	Callees        []CallRef          `json:"callees,omitempty"`
	Callers        []CallRef          `json:"callers,omitempty"`
	Tier           string             `json:"tier"`
	Warnings       []string           `json:"warnings,omitempty"`
	Body           *BodyAnalysis      `json:"body_analysis,omitempty"`
	PriorLearnings []learnings.Record `json:"prior_learnings,omitempty"`
	// GraphSignals holds pagerank/community/surprise when the persistent graph
	// has them. Signals.Found==false means the graph is cold; omitted from output.
	GraphSignals *graphx.Signals `json:"graph_signals,omitempty"`
	// DeadCodeScore is the CE reranker confidence that this symbol is genuine dead code.
	// Only present when the symbol has no callers and code_graph has pre-scored it.
	// Negative float; closer to 0 means more likely to be genuine dead code.
	DeadCodeScore *float32 `json:"dead_code_score,omitempty"`
	// DeadCodeNote explains the score when DeadCodeScore is set.
	DeadCodeNote string `json:"dead_code_note,omitempty"`
	// TestedBy lists test functions that directly cover this symbol via AGE TESTED_BY edges.
	TestedBy []graphx.SymbolRef `json:"tested_by,omitempty"`
	// StructuralRank is a human-readable summary of the symbol's architectural centrality.
	// e.g. "Top 2% (6th of 4040 symbols by structural centrality)"
	// Only present when the graph has pagerank data for this symbol.
	StructuralRank string `json:"structural_rank,omitempty"`
}