Documentation
¶
Overview ¶
Package localize provides graph-guided code localization — given a natural-language issue or question, returns the top-K code entities most relevant to investigate.
This is a primitives-only implementation of the LocAgent pattern (ACL 2025, arXiv 2503.09089). Where LocAgent runs an LLM agent loop that selects multi-hop expansion steps, this package executes a deterministic graph-traversal pipeline:
- Match seeds via the existing ranking.RankByQuery PageRank scorer (handles tokenization, seed matching, and bidirectional ranking).
- BFS from each seed up to `depth` steps over allowed edge types.
- Score visited nodes by seed_score / (1 + distance) and aggregate across paths (a node reached from multiple seeds wins).
- Return top-K by combined score with file_path + qualified_name for each entry so callers (Opus, Cursor, etc.) can fetch source directly via get_code_snippet.
LocAgent's published F1 (92.7% file-level localization) comes from the full LLM-in-the-loop variant. The primitives-only variant here puts the structural-traversal layer in code-graph; client LLMs do the final relevance judgment when consuming the ranked output. This trades some accuracy for determinism, latency, and not requiring an LLM credential inside the MCP server.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var AllowedEdgeTypes = map[string]bool{ "CALLS": true, "DEFINES": true, "DEFINES_METHOD": true, "IMPORTS": true, "CONTAINS": true, "MEMBER_OF": true, "USES_TYPE": true, "IMPLEMENTS": true, "OVERRIDE": true, }
AllowedEdgeTypes lists the edge types BFS will traverse. Restricted to the relationships that "localization" cares about; broader edges (TESTS, FILE_CHANGES_WITH, HTTP_CALLS) are intentionally excluded to avoid bringing in test files and infrastructure noise.
Functions ¶
This section is empty.
Types ¶
type LocalizedEntity ¶
type LocalizedEntity struct {
ID int64 `json:"id"`
Label string `json:"label"`
Name string `json:"name"`
QualifiedName string `json:"qualified_name"`
FilePath string `json:"file_path"`
StartLine int `json:"start_line"`
EndLine int `json:"end_line"`
Score float64 `json:"score"`
Distance int `json:"distance"` // shortest distance from any seed (0 = seed itself)
ReachedVia []string `json:"reached_via"` // edge types traversed to reach this node
}
LocalizedEntity is one entry in the CodeLocalize result.
func CodeLocalize ¶
func CodeLocalize(st *store.Store, project, issue string, depth, topK int) ([]LocalizedEntity, error)
CodeLocalize takes a natural-language issue/question and returns the top-K graph entities most relevant to investigate. depth controls the BFS expansion radius from seed nodes; topK is clamped to [1, 50].
Uses substring seed matching for backward compatibility. Use CodeLocalizeWithStrategy to choose substring / embedding / hybrid.
func CodeLocalizeWithStrategy ¶
func CodeLocalizeWithStrategy(ctx context.Context, st *store.Store, project, issue string, depth, topK int, strategy ranking.SeedStrategy) ([]LocalizedEntity, error)
CodeLocalizeWithStrategy is CodeLocalize with explicit seed-strategy selection. Hybrid is recommended for natural-language issues — it merges substring (catches identifier-exact queries) with embedding (catches intent-style queries that don't share substrings with names).
Source Files