api.md

xref Go API

Installation

import (
    xref "github.com/startvibecoding/xref"
    "github.com/startvibecoding/xref/internal/grammars"
)

Indexer

The Indexer scans a directory, extracts symbols from source files, and stores them in a SQLite cache for fast queries.

// Language detector — bridges grammars registry to the indexer.
detect := func(filename string) *xref.Language {
    entry := grammars.DetectLanguage(filename)
    if entry == nil {
        return nil
    }
    return entry.Language()
}

// Create and build the index.
idx := xref.NewIndexer("/path/to/project", detect)
defer idx.Close()

if err := idx.Build(); err != nil {
    log.Fatal(err)
}

// Stats
stats := idx.Stats()
fmt.Printf("%d files, %d symbols\n", stats.FileCount, stats.SymbolCount)

Symbol lookup

// Find a definition.
def, err := idx.Def("MyStruct.Parse")
if err != nil {
    log.Fatal(err)
}
fmt.Printf("%s:%d: %s\n", def.File, def.Line, def.Signature)

Callers and callees

// Who calls this symbol?
callers := idx.Callers("MyStruct.Parse")
for _, c := range callers {
    fmt.Printf("  %s:%d calls %s\n", c.Ref.File, c.Ref.Line, c.To.Key.Name)
}

// What does this symbol call?
callees, err := idx.Callees("MyStruct.Parse")
for _, c := range callees {
    fmt.Printf("  → %s\n", c.To.Key.Name)
}

Call graph

cg := xref.NewCallGraph(idx)

// Transitive callers (up to 3 levels).
callerMap := cg.CallersUp("MyStruct.Parse", 3)
for sym, edges := range callerMap {
    fmt.Printf("%s: called by %d sites\n", sym, len(edges))
}

// Transitive callees (up to 3 levels).
calleeMap := cg.CalleesDown("main.run", 3)
for sym, edges := range calleeMap {
    fmt.Printf("%s: calls %d symbols\n", sym, len(edges))
}

// Formatted call tree.
tree, _ := cg.Tree("MyStruct.Parse", 2)
fmt.Print(xref.FormatCallTree(tree))

Incremental updates

idx := xref.NewIndexer(root, detect)
idx.Build()  // First run: full index

// ... files change ...

idx.Build()  // Second run: only re-parses changed files (mtime-based)

Options

// Custom cache directory.
idx := xref.NewIndexer(root, detect, xref.WithCacheDir("/tmp/xref-cache"))

// Limit parallelism.
idx := xref.NewIndexer(root, detect, xref.WithWorkers(4))

// Restrict to specific languages.
idx := xref.NewIndexer(root, detect, xref.WithLanguages("go", "python"))

// Deep call tree query.
tree, _ := idx.Lookup("main.run", xref.WithMaxDepth(5))

Supported languages

Go, Python, JavaScript, TypeScript, Rust, Java, C, C++. Other languages use a generic node-type heuristic (function/class/variable detection by name).