codemap

type BuildOptions ¶

type BuildOptions struct {
	Root     string
	MaxFiles int
	Source   SymbolSource

	// WatchDebounce controls how long CachedProvider.StartWatch waits after
	// the last relevant filesystem event before applying pending changes.
	// Zero defaults to 300ms in production; tests can set a few
	// milliseconds so watch-triggered-rebuild tests aren't slow.
	WatchDebounce time.Duration
}

BuildOptions controls a CodeIndex rebuild.

type BuilderProvider ¶

type BuilderProvider struct{ Options BuildOptions }

BuilderProvider rebuilds the index on demand.

func (p BuilderProvider) Index(ctx context.Context) (*CodeIndex, error)

type CachedProvider ¶

type CachedProvider struct {
	Options BuildOptions
	// contains filtered or unexported fields
}

CachedProvider reuses the last index until supported source file paths, mtimes, sizes, or counts change. Without a running watch (see StartWatch) that check is a full workspace walk on every Index call; with one running, Index instead checks a cheap in-memory dirty flag and, when set, patches only the specific paths the watcher observed changing into a persistent buildState (see applyChanges) rather than re-walking and re-parsing the whole workspace.

func (p *CachedProvider) Close()

func (p *CachedProvider) Index(ctx context.Context) (*CodeIndex, error)

func (p *CachedProvider) StartWatch(ctx context.Context) error

type CodeIndex ¶

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

CodeIndex is an immutable structural snapshot. Mutating rebuilds publish a new instance instead of editing this one in place.

func Build(ctx context.Context, opts BuildOptions) (*CodeIndex, error)

func NewIndex(root string, rootID NodeID, nodes map[NodeID]Node, children map[NodeID][]NodeID, edges ...[]Edge) *CodeIndex

func (i *CodeIndex) Children(id NodeID) []NodeID

func (i *CodeIndex) Count() int

func (i *CodeIndex) Cycles(pathOrQuery string, max int) [][]Node

func (i *CodeIndex) Dependencies(pathOrQuery string, max int) []Node

func (i *CodeIndex) Dependents(pathOrQuery string, max int) []Node

func (i *CodeIndex) Edges(kind EdgeKind) []Edge

func (i *CodeIndex) Filter(query string, max int) []Node

func (i *CodeIndex) Impact(pathOrQuery string, depth, max int) ImpactResult

func (i *CodeIndex) Node(id NodeID) (Node, bool)

func (i *CodeIndex) Nodes() []Node

func (i *CodeIndex) Root() NodeID

func (i *CodeIndex) RootPath() string

func (i *CodeIndex) SuggestedContext(paths []string, max int) []ContextSuggestion

func (i *CodeIndex) SymbolsForFile(path string) []Node

type ContextSuggestion ¶

type ContextSuggestion struct {
	File   Node
	Reason string
}

ContextSuggestion is a file worth attaching as context and the reason it was selected.

type Edge ¶

type Edge struct {
	From NodeID
	To   NodeID
	Kind EdgeKind
	Meta string
}

Edge is a directed relationship between two indexed nodes.

type EdgeKind ¶

type EdgeKind string

const (
	EdgeImports EdgeKind = "imports"
)

type FallbackSource ¶

type FallbackSource struct{}

FallbackSource uses yottacode's offline syntax layer when available, then the conservative regex scanner. It keeps /map useful without requiring users to install language servers first.

func (FallbackSource) Symbols(ctx context.Context, path string) ([]lsp.Symbol, string, error)

type ImpactResult ¶

type ImpactResult struct {
	Target               Node
	DirectDependencies   []Node
	DirectDependents     []Node
	TransitiveDependents []Node
	Cycles               [][]Node
	// LikelyTests are files in the target's neighborhood that plausibly test
	// it, per IsTestFor. LikelyDocs are indexed markdown files that mention
	// the target. Both are best-effort relevance signals, not exhaustive.
	LikelyTests []Node
	LikelyDocs  []Node
}

ImpactResult is a bounded blast-radius query over import edges.

type LSPSource ¶

type LSPSource struct {
	Manager *lsp.Manager
	Servers map[string][]string
	Root    string
}

LSPSource tries a live language server first and falls back to approximate regex symbols when the server is unavailable or lacks document symbols.

func (s LSPSource) Symbols(ctx context.Context, path string) ([]lsp.Symbol, string, error)

type Node ¶

type Node struct {
	ID       NodeID
	Parent   NodeID
	Kind     NodeKind
	Name     string
	Path     string
	RelPath  string
	Language string
	Symbol   SymbolInfo
	Stats    Stats
}

Node is one immutable item in a CodeIndex snapshot.

func LikelyDocsFor(idx *CodeIndex, targetRel string, max int) []Node

type NodeID ¶

type NodeID string

NodeID is stable within one workspace snapshot. IDs are repo-relative where possible so TUI state and agent output remain readable and deterministic.

type NodeKind ¶

type NodeKind string

NodeKind identifies the coarse graph layer a node belongs to.

const (
	NodeDirectory NodeKind = "directory"
	NodeFile      NodeKind = "file"
	NodeSymbol    NodeKind = "symbol"
)

type Position ¶

type Position struct {
	Line      int
	Character int
}

Position is a zero-based source position. It mirrors LSP coordinates but keeps the codemap package independent from a specific symbol provider.

type Provider ¶

type Provider interface {
	Index(ctx context.Context) (*CodeIndex, error)
}

Provider returns the latest code-map snapshot. TUI rebuilds can swap the snapshot while agent tools keep depending on this tiny read-only surface.

type Range ¶

type Range struct {
	Start Position
	End   Position
}

Range is a half-open source range in zero-based line/character coordinates.

type Reason ¶

type Reason string

Reason explains why a node was suggested as relevant context around a change. Multiple reasons can apply to the same node; callers combine them.

const (
	ReasonChanged    Reason = "changed"
	ReasonImports    Reason = "imports target"
	ReasonImportedBy Reason = "imported by target"
	ReasonTestFor    Reason = "test for target"
	ReasonDocsFor    Reason = "docs for target"
)

type StaticProvider ¶

type StaticProvider struct{ Snapshot *CodeIndex }

StaticProvider returns one immutable index, useful in tests and one-shot runs.

func (p StaticProvider) Index(context.Context) (*CodeIndex, error)

type Stats ¶

type Stats struct {
	LOC      int
	Files    int
	Symbols  int
	Exported int
	Private  int
}

Stats aggregates cheap structure metrics for display and projections.

type SubsystemOverview ¶

type SubsystemOverview struct {
	Dir             Node
	EntryPoints     []Node
	PublicSurface   []Node
	CoreTypes       []Node
	Tests           []Node
	KeyDependencies []Node
}

SubsystemOverview summarizes one directory: entry points, exported public surface, core types, tests, and key external dependencies. It answers "where do I start in this subsystem?" for `/map <dir>`.

func BuildSubsystemOverview(idx *CodeIndex, dirRelPath string, max int) (SubsystemOverview, bool)

type SuggestedItem ¶

type SuggestedItem struct {
	Node    Node
	Reasons []Reason
	Score   int
}

SuggestedItem is one ranked candidate for prompt context around a change.

func SuggestedContext(idx *CodeIndex, changedRelPaths []string, max int) []SuggestedItem

type SymbolInfo ¶

type SymbolInfo struct {
	Kind      string
	Container string
	Exported  bool
	Range     Range
}

SymbolInfo stores metadata only symbol nodes need.

type SymbolSource ¶

type SymbolSource interface {
	Symbols(ctx context.Context, path string) ([]lsp.Symbol, string, error)
}

SymbolSource provides structural symbols for one source file. Implementations can use LSP, fallback parsers, or both.