evidence

type Coverage struct {
	WithReason   int `json:"with_reason"`
	Declarations int `json:"declarations"`
}

type File struct {
	// Namespace is empty outside federated search. Two repositories can each
	// hold an internal/app/main.go, and those are two files, not one.
	Namespace string
	FilePath  string
	Hits      []Result
}

type IntentHit struct {
	Reason string
	Terms  []string
}

type List struct {
	Files        []File
	WeakFiltered int
	// OverflowFiles is how many further files this page did not reach, whether
	// the Limit or the page budget stopped it. It separates "this is
	// everything" from "this is the first ten files of thirty".
	OverflowFiles int
	// PoolTruncated says the candidate pool this list was built from came back
	// full: the backend had at least as many candidates as the pool could hold
	// and may have had more. Build never sets it — it is a fact about the fetch,
	// which happens before this package sees anything — so whoever fetched the
	// pool sets it.
	//
	// It is deliberately not folded into OverflowFiles, which counts files and
	// only ever counts files. Read together they separate the two ways a page
	// can end: OverflowFiles == 0 with PoolTruncated false is the whole answer,
	// while OverflowFiles == 0 with PoolTruncated true is only the end of the
	// candidates that were fetched.
	PoolTruncated bool
	// NextOffset is the offset the page after this one starts at. It is set
	// whether or not another page exists; OverflowFiles and PoolTruncated are
	// what say whether asking for it is worth anything.
	//
	// It is carried rather than recomputed by the caller because "offset plus
	// the files on this page" is only right when the page is one contiguous run
	// of the answer. Whoever cut the page is the only one who knows that.
	NextOffset int
	// Coverage is how much of the searched repositories recorded a reason at all.
	// Build does not measure it — it is a fact about the index, which is read
	// before this package sees anything — so it arrives on Options and is carried
	// through unchanged.
	Coverage Coverage
	// Note is set only when Files is empty, and says which kind of empty it is:
	// nothing retrieved, nothing explainable, a page past the end, or a
	// repository where nobody ever recorded a reason to search.
	Note string
}

type Match string

type NodeRef struct {
	Namespace string
	ID        uint
}

type Options struct {
	Limit  int
	Offset int
	// PerNamespace makes Limit and Offset a budget every namespace gets on its
	// own rather than one budget the namespaces compete for. Federated search
	// sets it; a single-repository search has one namespace and cannot tell the
	// difference.
	//
	// Sharing one budget meant a limit smaller than the namespace count silenced
	// whole repositories, and the page ended up an arbitrary subset of the
	// answer rather than a run of it — so the offset that would resume it did
	// not exist.
	PerNamespace bool
	// IncludeWeak keeps candidates no signal explains, after the explainable
	// ones. Off by default, because a list padded with unexplainable results
	// reads as "here are ten answers" when there were two.
	IncludeWeak bool
	// Intent is what the intent query said about each node it returned. A node
	// with an entry here is justified by it — the terms are the proof — even
	// when its name, path, and @intent share no token with the query.
	Intent map[NodeRef]IntentHit
	// Coverage is how much of the searched repositories recorded a reason at all.
	// It is an input rather than something set on the returned list afterwards
	// because the note depends on it: which kind of empty an empty answer is
	// cannot be decided without knowing whether anybody wrote a reason down.
	Coverage Coverage
}

type Result struct {
	Node   graph.Node
	Intent string
	// Matched lists every signal the query touched, in a fixed order: name,
	// path, intent. It is empty only for a weak result kept by IncludeWeak.
	Matched []Match
	// Reason is the recorded reason the intent index matched — the node's
	// @intent, or its @domainRule when no @intent exists. It is set only for
	// hits the intent query returned, so an empty Reason means the hit earned
	// its place on name, path, or token overlap alone.
	Reason string
	// MatchedTerms are the terms of the query written in Reason, as the intent
	// scorer counted them. They are the proof behind MatchIntent when token
	// overlap alone cannot see the match.
	MatchedTerms []string
}