Documentation
¶
Overview ¶
Package repomap provides tree-sitter-based tag extraction for building repository maps with ranked symbol importance.
Index ¶
- Constants
- func ElideSingle(source []byte, tag Tag, bodyStart, bodyEnd uint) string
- func EstimateTokens(s string) int
- func LangFromExt(path string) string
- type ElisionRenderer
- type FallbackExtractor
- type FileGraph
- func (g *FileGraph) EdgeCount() int
- func (g *FileGraph) EnrichFromLSP(sourceFile string, refs []Location)
- func (g *FileGraph) NodeCount() int
- func (g *FileGraph) PageRank(damping float64, epsilon float64, maxIter int, ...) map[string]float64
- func (g *FileGraph) RankFiles(damping float64, personalization map[string]float64) []RankedFile
- type Location
- type MetricsSink
- type NoopSink
- type RankedFile
- type SymbolRequester
- type Tag
- type TagCache
- func (c *TagCache) AllFiles() (map[string][]Tag, error)
- func (c *TagCache) Clear() error
- func (c *TagCache) Close() error
- func (c *TagCache) GetOrExtract(filePath string, extractFn func() ([]Tag, error)) ([]Tag, error)
- func (c *TagCache) InvalidateFile(filePath string) error
- func (c *TagCache) SetMetricsSink(sink MetricsSink)
- func (c *TagCache) Version() int64
- type TagExtractor
- type TagKind
- type TreeRenderer
Constants ¶
const ( LookupHit = "hit" LookupMiss = "miss" )
Cache lookup result constants — closed enum per Phase 53 D-04.
const ( ExtractorTreesitter = "treesitter" ExtractorLSP = "lsp" ExtractorFallback = "fallback" )
Extractor type constants — closed enum per Phase 53 D-07.
Variables ¶
This section is empty.
Functions ¶
func ElideSingle ¶
ElideSingle takes pre-computed body range and returns the elided text for a single tag. Useful for rendering individual tags without re-parsing.
func EstimateTokens ¶
EstimateTokens approximates token count as len(s)/4. Per D-12: character-based token estimation, no external dependency.
func LangFromExt ¶
LangFromExt maps file extensions to language identifiers used by tree-sitter.
Types ¶
type ElisionRenderer ¶
type ElisionRenderer struct {
// contains filtered or unexported fields
}
ElisionRenderer produces compact, token-efficient views of source files by showing definition signatures with bodies replaced by an ellipsis marker. Per D-13: full signature + ellipsis. Per D-14: struct/class fields shown. Per D-15: elision at render time using byte ranges from tags.
func NewElisionRenderer ¶
func NewElisionRenderer(registry *treesitter.GrammarRegistry) *ElisionRenderer
NewElisionRenderer creates an ElisionRenderer using the shared grammar registry.
func (*ElisionRenderer) RenderFile ¶
func (r *ElisionRenderer) RenderFile(source []byte, lang string, tags []Tag) string
RenderFile produces a compact elided view of the def tags in a file. Only def tags are rendered; ref tags are ignored. Bodies of functions/methods are replaced with an ellipsis marker. Struct/class fields are preserved (D-14).
type FallbackExtractor ¶
type FallbackExtractor struct{}
FallbackExtractor produces def-only tags from LSP documentSymbol responses for languages without tree-sitter grammars. Per D-07, all symbols are mapped as TagDef; no references are extracted via this path.
func NewFallbackExtractor ¶
func NewFallbackExtractor() *FallbackExtractor
NewFallbackExtractor creates a new FallbackExtractor.
func (*FallbackExtractor) Extract ¶
func (f *FallbackExtractor) Extract(ctx context.Context, requester SymbolRequester, filePath string, uri string) ([]Tag, error)
Extract calls textDocument/documentSymbol via the given requester and returns def-only tags. Nested DocumentSymbol children produce qualified names (e.g. "ClassName.methodName") per D-03.
type FileGraph ¶
type FileGraph struct {
// Edges maps source file -> target file -> weight.
Edges map[string]map[string]float64
// Files is the set of all file nodes in the graph.
Files map[string]bool
// contains filtered or unexported fields
}
FileGraph is an in-memory directed graph where nodes are file paths and edges represent cross-file ref-to-def relationships weighted by reference count. Per D-02: in-memory only, no persistence of edges.
func BuildGraph ¶
BuildGraph constructs a FileGraph from all cached tags. Per D-01: file-level graph with cross-file ref-to-def edges. Per D-03: edge weight = sqrt(reference count).
func NewFileGraph ¶
func NewFileGraph() *FileGraph
NewFileGraph creates an empty FileGraph with initialized maps.
func (*FileGraph) EnrichFromLSP ¶
EnrichFromLSP adds cross-file reference edges from LSP references. Called opportunistically when a WorkerLease is already active. Per D-10: opportunistic only. Per D-11: additive edges.
func (*FileGraph) PageRank ¶
func (g *FileGraph) PageRank(damping float64, epsilon float64, maxIter int, personalization map[string]float64) map[string]float64
PageRank computes PageRank scores for all files in the graph using power iteration. If personalization is non-nil and non-empty, it is used as the teleportation vector (Personalized PageRank); otherwise uniform teleportation is used.
Parameters:
- damping: probability of following a link (typically 0.85)
- epsilon: convergence threshold (sum of abs rank differences)
- maxIter: maximum number of iterations
- personalization: optional map of file -> teleport weight
Per T-28-02: maxIter caps computation to mitigate DoS on large graphs.
type Location ¶
Location is a minimal reference location used by EnrichFromLSP. It avoids importing the gen package into the repomap package.
type MetricsSink ¶
type MetricsSink interface {
// RepoMapLookup increments helix_repomap_lookups_total for a
// (language, result) pair. result MUST be one of the LookupXxx
// constants below — closed enum per Phase 53 D-04.
RepoMapLookup(language, result string)
// RepoMapExtractObserve records the elapsed seconds of a single
// extractor invocation (cache-miss path only). extractor MUST be one
// of the ExtractorXxx constants below — closed enum per Phase 53 D-07.
RepoMapExtractObserve(language, extractor string, seconds float64)
}
MetricsSink is the minimal surface repomap needs from the observability layer. Implemented ad-hoc by *obs.Metrics (compile-time-checked at wire-up in internal/daemon/wiring_test.go); repomap itself never imports internal/obs (Phase 53 D-15).
Method signatures are frozen to match the *obs.Metrics helpers declared in internal/obs/metrics.go (Phase 53 D-15). If those helper signatures drift, the wiring_test.go compile-time assertion fails — fix is to ALIGN this interface, NOT to mutate internal/obs/metrics.go.
type NoopSink ¶
type NoopSink struct{}
NoopSink is used by tests and bootstrap paths where metrics are not wired. All methods are lock-free no-ops; a value-receiver keeps them trivially inlinable.
func (NoopSink) RepoMapExtractObserve ¶
RepoMapExtractObserve implements MetricsSink.
func (NoopSink) RepoMapLookup ¶
RepoMapLookup implements MetricsSink.
type RankedFile ¶
RankedFile pairs a file path with its PageRank score. Used by the rendering layer to produce token-budgeted output.
type SymbolRequester ¶
type SymbolRequester interface {
Request(ctx context.Context, method string, params, result interface{}) error
}
SymbolRequester abstracts the LSP documentSymbol request for testability. WorkerLease from lspool satisfies this interface via its Request method.
type Tag ¶
type Tag struct {
Name string
Kind TagKind
File string
Line int
Column int
StartByte uint
EndByte uint
}
Tag represents a single definition or reference extracted from a source file. Per D-01: two kinds only (def/ref). Per D-02: flat, no scope nesting. Per D-04: byte offsets only, no raw text stored.
type TagCache ¶
type TagCache struct {
// contains filtered or unexported fields
}
TagCache provides SQLite-backed persistence for extracted tags with mtime-based invalidation. Tags survive daemon restarts and client reconnects. The cache uses a separate tags.db file independent from the memory store (per D-09).
func NewTagCache ¶
NewTagCache opens (or creates) the SQLite tag cache at dbPath, initializes the schema, and configures WAL mode with a busy timeout. Follows the same pattern as internal/memory/index.go.
func (*TagCache) AllFiles ¶
AllFiles returns all cached file paths with their tags. Used by graph building to iterate the entire tag cache.
func (*TagCache) GetOrExtract ¶
GetOrExtract returns cached tags for filePath if the file's mtime has not changed. On cache miss or mtime mismatch, it calls extractFn to get fresh tags, stores them, and returns them.
Per D-10: file-level mtime invalidation. Per D-12: lazy (no eager warming). Per T-27-05: all SQL uses parameterized queries only.
func (*TagCache) InvalidateFile ¶
InvalidateFile removes all cached tags for the given file.
func (*TagCache) SetMetricsSink ¶
func (c *TagCache) SetMetricsSink(sink MetricsSink)
SetMetricsSink wires the MetricsSink at startup (called from internal/daemon/daemon.go post-init wiring; see Phase 53 D-15). Safe to call multiple times; overwrites the previous sink. A nil argument is normalized to NoopSink{} so the GetOrExtract emission sites never need nil-checks.
Decision (Plan 53-03 setter pattern): adding the sink as a setter rather than a NewTagCache constructor argument avoids touching every existing NewTagCache caller (skill repomap, tests, future seams). Mirrors the existing post-init wiring pattern at daemon.go:290-323 (12a/12b/12c).
type TagExtractor ¶
type TagExtractor struct {
// contains filtered or unexported fields
}
TagExtractor extracts def/ref tags from source files using tree-sitter queries. Queries are compiled once per language and reused across files.
func NewTagExtractor ¶
func NewTagExtractor(registry *treesitter.GrammarRegistry) (*TagExtractor, error)
NewTagExtractor creates a TagExtractor with compiled queries for all supported languages. Returns an error if any query fails to compile.
type TreeRenderer ¶
type TreeRenderer struct {
// contains filtered or unexported fields
}
TreeRenderer produces tree-structured, token-budgeted views of ranked files with elided symbol definitions. It combines the PageRank ranking from FileGraph with the ElisionRenderer from Phase 27 to produce compact repo maps.
func NewTreeRenderer ¶
func NewTreeRenderer(elider *ElisionRenderer, cache *TagCache, rootDir string) *TreeRenderer
NewTreeRenderer creates a TreeRenderer for the given workspace root.
func (*TreeRenderer) RenderBudgeted ¶
func (r *TreeRenderer) RenderBudgeted(ranked []RankedFile, budget int) string
RenderBudgeted renders ranked files as a tree, using binary search on file count to maximize coverage within the token budget. Per D-13: prune lowest-ranked files first via binary search. At least 1 file is always included regardless of budget.
Source Files