graphx

type Analytics interface {
	// Symbol returns the pagerank, community, and surprise signals for a
	// single symbol in the given repo.
	Symbol(ctx context.Context, repoKey, symbolName, file string) (Signals, error)

	// TopPageRank returns the k symbols with the highest pagerank in the repo,
	// ordered descending. Returns an empty slice (not an error) when the graph
	// has no snapshot.
	TopPageRank(ctx context.Context, repoKey string, k int) ([]Signal, error)
}

type CrossRefs interface {
	// HandlesRoute returns the HTTP Route served by a handler symbol, and
	// whether such a binding was found. Returns Route{}, false, nil when absent.
	HandlesRoute(ctx context.Context, repoKey, symbolName, file string) (Route, bool, error)

	// FetchedBy returns the frontend (or upstream) symbols that issue HTTP
	// requests to the given route. Returns nil, nil when none are found.
	FetchedBy(ctx context.Context, repoKey string, route Route) ([]SymbolRef, error)

	// TestedBy returns test functions that directly cover the given production
	// symbol. Returns nil, nil when no test edges are recorded.
	TestedBy(ctx context.Context, repoKey, symbolName, file string) ([]SymbolRef, error)
}

type Noop struct{}

type Route struct {
	// Method is the HTTP method (e.g. "GET", "POST"). Empty means any.
	Method string
	// Path is the route path pattern (e.g. "/api/users/:id").
	Path string
}

type Signal struct {
	Symbol SymbolRef
	Signals
}

type Signals struct {
	// PageRank is the normalized PageRank score (0..1).
	PageRank float64
	// Community is the Louvain community identifier. Empty when unassigned.
	Community string
	// Surprise is the structural surprise score (higher = less expected).
	Surprise float64
	// Found is false when the graph has no snapshot for this repo/symbol.
	// Zero values for PageRank/Community/Surprise are meaningless when Found is false.
	Found bool
}

type SymbolRef struct {
	// Name is the qualified symbol name (e.g. "pkg.FunctionName").
	Name string
	// File is the source file path relative to the repo root.
	File string
}