graph

type BuildStats ¶

type BuildStats struct {
	Files         int
	Symbols       int
	Edges         int
	ResolvedEdges int
	Skipped       int          // dropped by binary/generated/oversize filters
	Unsupported   int          // recognized language with no registered provider
	Diagnostics   int          // files that parsed with warnings/errors
	ByTier        map[Tier]int // files per quality tier
}

BuildStats summarizes a build for reporting.

type CallerRow ¶

type CallerRow struct {
	Caller, Path string
	Line         int
	Rank         float64
}

CallerRow is an inbound call/reference site returned by WhoCalls.

type Confidence ¶

type Confidence string

Confidence labels how an edge's target was resolved. go/ast edges are syntactically exact; tree-sitter / ast-grep edges are heuristic name matches.

const (
	// Extracted: the referenced name resolves to a single indexed definition.
	Extracted Confidence = "extracted"
	// Inferred: a reference whose target was not found (external / unknown).
	Inferred Confidence = "inferred"
	// Ambiguous: the name matches more than one indexed definition.
	Ambiguous Confidence = "ambiguous"
)

type DefRow ¶

type DefRow struct {
	Name, Kind, Signature, Path string
	Line                        int
	Rank                        float64
}

DefRow is a definition site returned by FindDef.

type DiscoveredFile ¶

type DiscoveredFile struct {
	Rel  string // repo-relative path
	Lang string // language label (see extLang)
	Data []byte
	SHA  string // sha256 of Data (hex), for incremental reindex later
}

DiscoveredFile is one candidate source file together with its contents.

func Discover(ctx context.Context, repo string) (files []DiscoveredFile, skipped int, err error)

type Edge ¶

type Edge struct {
	SrcName string // enclosing definition where the reference appears ("" = file scope)
	DstName string // the referenced name (the callee)
	Kind    EdgeKind
	Line    int
}

Edge is a reference from an enclosing symbol to a (possibly external) name.

type EdgeKind ¶

type EdgeKind string

EdgeKind classifies a relationship between a symbol and a referenced name.

const (
	EdgeCall      EdgeKind = "call"
	EdgeReference EdgeKind = "reference"
	EdgeImport    EdgeKind = "import"
	EdgeInherit   EdgeKind = "inherit"
)

type FileGraph ¶

type FileGraph struct {
	File    fileMeta
	Symbols []Symbol
	Edges   []Edge
}

FileGraph is one file's contribution to the graph: its metadata plus the symbols and edges a provider extracted from it.

type FileResult ¶

type FileResult struct {
	Symbols     []Symbol
	Edges       []Edge
	Diagnostics []string // parse warnings/errors; empty means a clean parse
}

FileResult is what a ParserProvider returns for one file.

type Freshness ¶

type Freshness struct {
	BuiltAt    time.Time
	HeadCommit string
	DirtyFiles int
}

Freshness describes when/what the graph was last built against.

type Graph ¶

type Graph struct {
	// contains filtered or unexported fields
}

Graph is a per-repository code graph backed by SQLite.

func Open(dbPath string) (*Graph, error)

func OpenForRepo(repoAbs string) (*Graph, error)

func (g *Graph) BlastRadius(name string, maxDepth, limit int) ([]ImpactRow, error)

func (g *Graph) Build(ctx context.Context, repoPath string, reg *Registry) (BuildStats, error)

func (g *Graph) Close() error

func (g *Graph) Counts() (files, symbols, edges, resolvedEdges int)

func (g *Graph) FindDef(name string, limit int) ([]DefRow, error)

func (g *Graph) Freshness() Freshness

func (g *Graph) RepoMap(limit int) ([]MapRow, error)

func (g *Graph) SearchSymbols(query string, limit int) ([]DefRow, error)

func (g *Graph) Stale(ctx context.Context, repoPath string) (stale bool, changed int, err error)

func (g *Graph) TierCounts() map[Tier]int

func (g *Graph) TrustLabels() []LangTrust

func (g *Graph) Update(ctx context.Context, repoPath string, reg *Registry) (UpdateStats, error)

func (g *Graph) WhoCalls(name string, limit, offset int) ([]CallerRow, error)

type GraphState ¶

type GraphState struct {
	HeadCommit string
	DirtyFiles int
	BuiltAt    time.Time
	Files      int
	Symbols    int
	Edges      int
	Tiers      map[Tier]int
	Trust      []LangTrust
	Stale      bool
	Changed    int
}

GraphState is a quick, read-only snapshot of a repo's built graph, for UI badges and the detail view. It parses and builds nothing.

func StateFor(repoAbs string) (GraphState, bool)

type ImpactRow ¶

type ImpactRow struct {
	Name, Path string
	Depth      int
}

ImpactRow is a transitively-affected symbol returned by BlastRadius.

type Kind ¶

type Kind string

Kind classifies a defined symbol.

const (
	KindFunc      Kind = "function"
	KindMethod    Kind = "method"
	KindClass     Kind = "class"
	KindStruct    Kind = "struct"
	KindInterface Kind = "interface"
	KindType      Kind = "type"
	KindVar       Kind = "var"
	KindConst     Kind = "const"
	KindModule    Kind = "module"
)

type LangTrust ¶

type LangTrust struct {
	Lang  string `json:"language"`
	Tier  Tier   `json:"tier"`
	Files int    `json:"files"`
}

LangTrust describes the parser quality used for a language in a built graph.

type MapRow ¶

type MapRow struct {
	Path, Kind, Name, Signature string
	Rank                        float64
}

MapRow is one entry in the ranked repo map.

type ParserProvider ¶

type ParserProvider interface {
	// Name identifies the backend, e.g. "go/ast" or "ast-grep".
	Name() string
	// Tier reports the expected parse quality for a language label.
	Tier(lang string) Tier
	// Extract parses files (all of language lang, located under repoRoot) and
	// returns a FileResult keyed by SourceFile.Rel. A file that partially fails
	// should yield a FileResult with Diagnostics rather than aborting the batch,
	// so one bad file never fails the build.
	Extract(ctx context.Context, repoRoot, lang string, files []SourceFile) (map[string]FileResult, error)
}

ParserProvider extracts symbols and edges from a batch of same-language files.

Implementations are language backends (go/ast in-process; ast-grep out-of-process). Batch (rather than per-file) so an external tool like ast-grep can scan a whole repo in one invocation instead of spawning a process per file. A provider may handle several languages; Tier reports its expected quality per language so callers can label results.

type Registry ¶

type Registry struct {
	// contains filtered or unexported fields
}

Registry maps a language label to the ParserProvider that handles it.

func DefaultRegistry() *Registry

func (r *Registry) For(lang string) (ParserProvider, bool)

type SourceFile ¶

type SourceFile struct {
	Rel  string
	Data []byte
}

SourceFile is one file handed to a provider: its repo-relative path and bytes.

type Store ¶

type Store struct {
	// contains filtered or unexported fields
}

Store is the per-repo SQLite graph database. It owns the schema and the queries; orchestration lives in Graph (graph.go).

func (s *Store) Close() error

type Symbol ¶

type Symbol struct {
	Name      string
	Kind      Kind
	Signature string // one-line skeleton (no body), for the repo map
	StartLine int
	EndLine   int
}

Symbol is a defined entity in a file — a node in the graph.

type Tier ¶

type Tier string

Tier is the parse quality a provider expects for a language. It is surfaced to the agent so it knows how much to trust the graph versus reading the file.

const (
	TierPrecise     Tier = "precise"     // exact semantics (Go via go/ast)
	TierGood        Tier = "good"        // clean tree-sitter parse
	TierBestEffort  Tier = "best-effort" // partial parse; some symbols may be missing
	TierUnsupported Tier = "unsupported"
)

type UpdateStats ¶

type UpdateStats struct {
	Changed, Added, Deleted, Reused      int
	Files, Symbols, Edges, ResolvedEdges int
}

UpdateStats summarizes an incremental update.