trace

Documentation

Index

• Variables
• type Annotator
• type DefSite
• type Edge
• type Index
  • func BuildIndex(root string) (*Index, error)
• type Node
• type NoteRef
• type Result
  • func Trace(idx *Index, symbols []string, maxDepth int, annotate Annotator) *Result

Variables

var DefaultParseTimeoutMicros uint64 = 2_000_000

DefaultParseTimeoutMicros bounds each per-file gotreesitter parse. A single pathological file can otherwise drive gotreesitter's GLR error-recovery into unbounded transient allocation (observed >1GB). On timeout gotreesitter returns a partial tree with a nil error, which is acceptable for definition indexing. A value of 0 disables the timeout (gotreesitter's default, full-parse behavior).

Types

type Annotator

type Annotator func(query string) []NoteRef

Annotator maps a node's source-span text to related nn notes. The caller supplies the ranking (for example, the memoizing per-field BM25 scorer used by nn grep/ast/shuf), keeping trace decoupled from the note/index packages. A nil Annotator leaves every node's NNNotes empty.

type DefSite

type DefSite struct {
	Name        string
	Kind        string
	File        string
	StartLine   int
	EndLine     int
	StartByte   uint32
	EndByte     uint32
	Source      []byte
	CycleMarker string
}

DefSite is a located symbol definition extracted from a source file.

type Edge

type Edge struct {
	From     string `json:"from"`
	To       string `json:"to"`
	Resolved bool   `json:"resolved"`
}

Edge is a directed call edge in the trace result.

type Index

type Index struct {
	ByName map[string][]*DefSite
	All    []*DefSite
}

Index maps symbol names to their definition sites across a directory tree.

func BuildIndex

func BuildIndex(root string) (*Index, error)

BuildIndex walks root, parses all grammar-detected files via gotreesitter, and returns an Index of all definition sites. Files are parsed concurrently using a bounded goroutine pool.

type Node

type Node struct {
	ID                string    `json:"id"`
	Name              string    `json:"name"`
	Kind              string    `json:"kind"`
	File              string    `json:"file"`
	Line              int       `json:"line"`
	Resolved          bool      `json:"resolved"`
	CycleMarker       string    `json:"cycle_marker,omitempty"`
	AmbiguousReceiver bool      `json:"ambiguous_receiver,omitempty"`
	Receiver          string    `json:"receiver,omitempty"`
	NNNotes           []NoteRef `json:"nn_notes"`
}

Node is a call-graph node in the trace result.

type NoteRef

type NoteRef struct {
	ID    string `json:"id"`
	Title string `json:"title"`
}

NoteRef is a reference to an nn note attached to a resolved node.

type Result

type Result struct {
	Nodes []Node `json:"nodes"`
	Edges []Edge `json:"edges"`
}

Result is the full call-graph output of a Trace call.

func Trace

func Trace(idx *Index, symbols []string, maxDepth int, annotate Annotator) *Result

Trace performs a DFS from the named entry-point symbols up to maxDepth, annotates each resolved node with related nn notes via the supplied annotate function, and returns the graph result.