Documentation
¶
Overview ¶
@index Turns ranked search candidates into a list a reader can judge.
Index ¶
Constants ¶
const PageHitBudget = 50
PageHitBudget is the point past which one answer stops taking on more files.
It bounds a page without ever trimming a file: a file is added whole or left for the next page, and the first file of a page is always added. So a file holding sixty hits is still answered with sixty hits — it just travels alone. Half a file is worse evidence than a long one, because the reader cannot tell which half they got.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type File ¶
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
}
File is every hit one file answered the query with.
The file is the unit of a search answer because it is the unit of reading: a reader picks a file first and a declaration inside it second. Grouping also removes the old reason to hide hits — ten hits in one file cost one decision, not ten — so a shown file arrives whole.
@intent make the file, not the declaration, the thing a caller chooses between.
type IntentHit ¶ added in v0.13.0
IntentHit is what the intent index said about one candidate: the recorded reason it matched and the query terms written in it. @intent carry the intent query's evidence into the list without the list depending on the intent packages.
type List ¶
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
// Note is set only when Files is empty, and says which kind of empty it is:
// nothing retrieved, nothing explainable, or a page past the end.
Note string
}
List is a whole search answer, including what it decided not to show. @intent make "nothing to show" a readable answer rather than an empty array.
func Build ¶
Build turns the reranked candidate pool into a list whose every entry can be justified, and reports what it left out.
The order it is handed is the order it keeps. Ranking was measured against the golden set and its job turned out to be membership, not sequence: a reader who reads all ten lines is unaffected by which is third. So this changes who is in the list, never who is first — except that weak results kept by IncludeWeak go last, since they are there to be scrolled past.
@requires nodes arrive in the order rank.Rerank left them, and carry their loaded Annotation. @ensures the returned Files never exceed Options.Limit, and every returned file carries all of its justified hits. @ensures Note is non-empty exactly when Files is empty. @intent give a reader or an agent a file list where every line states why it is there.
type Match ¶
type Match string
Match names one reason a candidate is in the list. @intent let a reader see which part of a result the query actually touched.
type NodeRef ¶ added in v0.13.0
NodeRef names one node across repositories. Node ids are unique only within a namespace, so a federated answer needs both to address a node. @intent key per-node intent evidence so it cannot leak onto another repository's node.
type Options ¶
type Options struct {
Limit int
Offset int
// 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
}
Options are the caller's choices about how wide the list may be. @domainRule Limit and Offset are both counted in files, never in hits, so paging never splits a file. @intent keep the bounds a caller controls — page size, page position, strictness — in one argument.
type Result ¶
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
}
Result is one candidate and the case for it. @intent carry a search hit together with the evidence that justifies showing it.
Source Files