code

package
v0.1.155 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 24, 2026 License: MIT Imports: 33 Imported by: 0

Documentation

Overview

Package code provides shared implementations for Code service RPCs.

Plugins call into this library instead of reimplementing common logic. Language-specific behavior (e.g. which fixers to run) stays in the plugin.

Package code provides shared, language-agnostic primitives for code operations.

Graph types (CodeNode, CodeGraph, Edge) are the universal representation of a codebase's structure. Language-specific parsers (parse_go.go, etc.) populate these types; Mind and plugins both consume them.

Package code provides the DefaultCodeServer: a complete, language-agnostic implementation of the unified Code.Execute RPC. Plugins embed it and override only language-specific operations (LSP, Fix, dependency management).

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ComputeFileHashes 

func ComputeFileHashes(vfs VFS, dir string, extensions map[string]bool) map[string]string

ComputeFileHashes walks a directory and hashes source files. If extensions is nil, all files are included. Otherwise only matching extensions. Files larger than maxHashFileSize are skipped. Shared by DefaultCodeServer and language-specific servers.

func DedentLines 

func DedentLines(lines []string) []string

DedentLines strips the minimum common leading whitespace from all non-empty lines.

func FormatTimeline 

func FormatTimeline(timelines []*FileTimeline) string

FormatTimeline produces a compact text representation of file timelines, suitable for LLM context or developer review.

func FormatTimelineStats 

func FormatTimelineStats(s TimelineStats) string

FormatTimelineStats produces a readable summary.

func Levenshtein 

func Levenshtein(a, b string) int

Levenshtein computes the edit distance between two strings.

func OperationName 

func OperationName(req *codev0.CodeRequest) string

OperationName returns the oneof field name for dispatch/override keys. This is the SINGLE source of truth for operation name mapping. If you add a new operation to the proto, add it here AND in dispatch(). The test TestOperationName_MatchesDispatch verifies they stay in sync.

Types

type ASTSymbolProvider 

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

ASTSymbolProvider uses ParseGoTreeVFS to extract symbols from Go AST. Zero external dependencies, millisecond performance, works anywhere Go is installed. Tradeoff: no cross-module type resolution.

func NewASTSymbolProvider 

func NewASTSymbolProvider(dir string) *ASTSymbolProvider

NewASTSymbolProvider creates a provider that lazily parses the Go source tree. Uses LocalVFS by default; callers can override vfs for non-local filesystems.

func NewASTSymbolProviderVFS 

func NewASTSymbolProviderVFS(dir string, vfs VFS) *ASTSymbolProvider

NewASTSymbolProviderVFS creates a provider backed by the given VFS.

func (*ASTSymbolProvider) Graph 

func (p *ASTSymbolProvider) Graph() (*CodeGraph, error)

Graph returns the underlying CodeGraph for callers that need it.

func (*ASTSymbolProvider) ListSymbols 

func (p *ASTSymbolProvider) ListSymbols(_ context.Context, file string) ([]*codev0.Symbol, error)

ListSymbols returns proto Symbol messages for a specific file or all files (if file is empty).

type AgeBucket 

type AgeBucket string

AgeBucket classifies code age relative to a reference date. 

const (
	AgeRecent   AgeBucket = "recent"   // < 3 months
	AgeModerate AgeBucket = "moderate" // 3-12 months
	AgeOld      AgeBucket = "old"      // 1-3 years
	AgeAncient  AgeBucket = "ancient"  // > 3 years
)

type ByteLRU 

type ByteLRU struct {

	// MaxEntrySize is the maximum size of a single entry (default 1MB).
	// Files larger than this are not cached.
	MaxEntrySize int64
	// contains filtered or unexported fields
}

ByteLRU is a byte-slice LRU cache with a configurable memory budget. Thread-safe. Used by CachedVFS to cache file contents in RAM.

func NewByteLRU 

func NewByteLRU(capacity int64) *ByteLRU

NewByteLRU creates a new LRU cache with the given capacity in bytes.

func (*ByteLRU) Clear 

func (c *ByteLRU) Clear()

Clear removes all entries.

func (*ByteLRU) Get 

func (c *ByteLRU) Get(key string) []byte

Get returns the cached data for key, or nil if not present. Moves the entry to the front (most recently used).

func (*ByteLRU) Invalidate 

func (c *ByteLRU) Invalidate(key string)

Invalidate removes a key from the cache.

func (*ByteLRU) Len 

func (c *ByteLRU) Len() int

Len returns the number of cached entries.

func (*ByteLRU) Put 

func (c *ByteLRU) Put(key string, data []byte)

Put stores data under key. If the entry exceeds MaxEntrySize, it is not cached. Evicts least recently used entries to stay within capacity.

func (*ByteLRU) Size 

func (c *ByteLRU) Size() int64

Size returns the current memory usage in bytes.

type CachedVFS 

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

CachedVFS wraps a base VFS (typically LocalVFS) with an in-memory file tree cache. Metadata operations (Stat, ReadDir, WalkDir) are served from cache. Reads/writes pass through to the base and update the cache.

On startup, the entire source directory is walked to build the cache. A fsnotify watcher keeps the cache fresh on file changes.

func NewCachedVFS 

func NewCachedVFS(base VFS, dir string) (*CachedVFS, error)

NewCachedVFS creates a CachedVFS rooted at dir, backed by base. It walks dir to populate the cache and starts a background fsnotify watcher.

func (*CachedVFS) Close 

func (c *CachedVFS) Close() error

Close stops the watcher and releases resources.

func (*CachedVFS) Invalidate 

func (c *CachedVFS) Invalidate() error

Invalidate forces a full re-scan of the tree. Use sparingly.

func (*CachedVFS) MkdirAll 

func (c *CachedVFS) MkdirAll(path string, perm os.FileMode) error

func (*CachedVFS) ReadDir 

func (c *CachedVFS) ReadDir(path string) ([]os.DirEntry, error)

func (*CachedVFS) ReadFile 

func (c *CachedVFS) ReadFile(path string) ([]byte, error)

func (*CachedVFS) Remove 

func (c *CachedVFS) Remove(path string) error

func (*CachedVFS) Rename 

func (c *CachedVFS) Rename(oldpath, newpath string) error

func (*CachedVFS) Stat 

func (c *CachedVFS) Stat(path string) (os.FileInfo, error)

func (*CachedVFS) WalkDir 

func (c *CachedVFS) WalkDir(root string, fn fs.WalkDirFunc) error

func (*CachedVFS) WriteFile 

func (c *CachedVFS) WriteFile(path string, data []byte, perm os.FileMode) error

type CodeExecutor 

type CodeExecutor interface {
	Execute(context.Context, *codev0.CodeRequest) (*codev0.CodeResponse, error)
}

CodeExecutor is the interface every code server (Default, Go, …) satisfies.

type CodeGraph 

type CodeGraph struct {
	Nodes map[string]*CodeNode // node ID → node
	Edges []Edge               // all directed edges
	// contains filtered or unexported fields
}

CodeGraph holds the full structural representation of a codebase.

func NewCodeGraph 

func NewCodeGraph() *CodeGraph

NewCodeGraph creates an empty graph.

func ParseGoTree 

func ParseGoTree(dir string) (*CodeGraph, error)

ParseGoTree parses a Go source tree and builds a CodeGraph using the local filesystem. For VFS-backed parsing, use ParseGoTreeVFS.

func ParseGoTreeVFS 

func ParseGoTreeVFS(vfs VFS, dir string) (*CodeGraph, error)

ParseGoTreeVFS parses a Go source tree through a VFS and builds a CodeGraph. It extracts functions, methods, types, file nodes, imports, and call edges.

func (*CodeGraph) AddEdge 

func (g *CodeGraph) AddEdge(e Edge)

AddEdge records a directed edge and updates caller/callee indexes.

func (*CodeGraph) AddNode 

func (g *CodeGraph) AddNode(n *CodeNode)

AddNode inserts or replaces a node and updates the file and name indexes.

func (*CodeGraph) Files 

func (g *CodeGraph) Files() []string

Files returns all unique source files in the graph.

func (*CodeGraph) FindDefinitions 

func (g *CodeGraph) FindDefinitions(name string) []*CodeNode

FindDefinitions returns all nodes whose name matches (case-insensitive). O(1) lookup via the nameIdx — no linear scan of all nodes.

func (*CodeGraph) FindDefinitionsByKind 

func (g *CodeGraph) FindDefinitionsByKind(name string, kind NodeKind) []*CodeNode

FindDefinitionsByKind returns nodes matching both name and kind.

func (*CodeGraph) FindUsages 

func (g *CodeGraph) FindUsages(name string) []*CodeNode

FindUsages returns all callers of any node matching the given name. "Where is X used?" — finds definitions of X, then returns their callers.

func (*CodeGraph) FunctionNodes 

func (g *CodeGraph) FunctionNodes() []*CodeNode

FunctionNodes returns all nodes of kind Function or Method.

func (*CodeGraph) GetCallees 

func (g *CodeGraph) GetCallees(nodeID string) []string

GetCallees returns IDs of nodes that the given node calls.

func (*CodeGraph) GetCallers 

func (g *CodeGraph) GetCallers(nodeID string) []string

GetCallers returns IDs of nodes that call the given node.

func (*CodeGraph) GetCallersOfAny 

func (g *CodeGraph) GetCallersOfAny(nodeIDs []string) []string

GetCallersOfAny returns the union of callers for a set of node IDs. Deduplicates and excludes IDs in the input set.

func (*CodeGraph) GetNeighborhood 

func (g *CodeGraph) GetNeighborhood(nodeID string) *Neighborhood

GetNeighborhood returns the structural neighborhood of a node.

func (*CodeGraph) GetNodesForFile 

func (g *CodeGraph) GetNodesForFile(file string) []string

GetNodesForFile returns all node IDs belonging to a specific file.

func (*CodeGraph) GetSameFile 

func (g *CodeGraph) GetSameFile(nodeID string) []string

GetSameFile returns IDs of all nodes in the same file as the given node.

func (*CodeGraph) NameIndexSize 

func (g *CodeGraph) NameIndexSize() int

NameIndexSize returns the number of unique names in the symbol index.

func (*CodeGraph) RebuildIndexes 

func (g *CodeGraph) RebuildIndexes()

RebuildIndexes recomputes all indexes from raw Nodes and Edges. Call after deserializing from storage.

func (*CodeGraph) RemoveNode 

func (g *CodeGraph) RemoveNode(nodeID string)

RemoveNode deletes a node and all its edges.

func (*CodeGraph) RemoveNodesForFile 

func (g *CodeGraph) RemoveNodesForFile(file string) []string

RemoveNodesForFile removes all nodes associated with a file. Returns the removed IDs.

func (*CodeGraph) ResolveIDs 

func (g *CodeGraph) ResolveIDs(ids []string) []*CodeNode

ResolveIDs maps node IDs to CodeNode pointers, skipping unknowns.

func (*CodeGraph) SearchSymbols 

func (g *CodeGraph) SearchSymbols(query string) []*CodeNode

SearchSymbols returns all nodes whose name contains the query (case-insensitive). Uses the nameIdx for prefix filtering — much faster than scanning all nodes when the index has many entries.

func (*CodeGraph) Stats 

func (g *CodeGraph) Stats() GraphStats

Stats returns aggregate counts.

func (*CodeGraph) SummaryableNodes 

func (g *CodeGraph) SummaryableNodes() []*CodeNode

SummaryableNodes returns all nodes worth generating summaries for (functions, methods, types, files — everything except packages).

type CodeMap 

type CodeMap struct {
	Language string
	Files    []FileMap
}

CodeMap is a structured representation of all symbols in a codebase, organized by file and hierarchy. This is used by Mind to give the LLM a compressed overview of the project's code structure.

func BuildCodeMap 

func BuildCodeMap(language string, symbols []SymbolInput) *CodeMap

BuildCodeMap groups symbols by file and sorts them by line number.

func (*CodeMap) Format 

func (cm *CodeMap) Format() string

Format produces a compact text representation suitable for LLM system prompts. It uses ~1 line per symbol to stay within context budgets.

func (*CodeMap) Stats 

func (cm *CodeMap) Stats() CodeMapStats

Stats returns summary statistics about the code map.

type CodeMapStats 

type CodeMapStats struct {
	Files   int
	Symbols int
}

type CodeNode 

type CodeNode struct {
	ID        string   // unique: "pkg/api/router.go::SetupRoutes"
	Kind      NodeKind // function, method, type, file, package
	Name      string   // short name: "SetupRoutes"
	File      string   // relative path: "pkg/api/router.go"
	Line      int      // starting line number
	EndLine   int      // ending line number (0 if unknown)
	Signature string   // from AST/LSP: "func SetupRoutes(r chi.Router)"
	Doc       string   // documentation comment, if any
	Body      string   // source text of the node (for summary generation)

	// Relationship IDs.
	Children []string // functions/types contained in this file/package
	Calls    []string // outgoing: functions this node calls
	CalledBy []string // incoming: functions that call this node
	Imports  []string // package paths imported by this file
}

CodeNode represents a single element in the code graph.

func (*CodeNode) QualifiedName 

func (n *CodeNode) QualifiedName() string

QualifiedName returns "File::Name" for display.

type CodebaseContext 

type CodebaseContext struct {
	Module    string
	Language  string
	Packages  []*codev0.PackageInfo
	CodeMap   *CodeMap
	DepGraph  *DepGraph
	Graph     *CodeGraph
	Timelines []*FileTimeline
	Stats     TimelineStats
}

CodebaseContext holds all analysis layers assembled from a single code server. It is the unified input for LLM prompts, relevance scoring, and edit planning.

func BuildCodebaseContext 

func BuildCodebaseContext(ctx context.Context, server CodeExecutor) (*CodebaseContext, error)

BuildCodebaseContext runs the full analysis pipeline through a CodeExecutor (typically GoCodeServer) and returns a populated CodebaseContext.

func (*CodebaseContext) FilePaths 

func (cc *CodebaseContext) FilePaths() []string

FilePaths returns all source file paths known to this context.

func (*CodebaseContext) Format 

func (cc *CodebaseContext) Format(budget int) string

Format produces a token-budgeted text representation for LLM system prompts. Budget is in bytes; 0 means unlimited. Sections are included in priority order: header > code map > dep graph > timeline > call graph.

type DefaultCodeServer 

type DefaultCodeServer struct {
	codev0.UnimplementedCodeServer

	SourceDir string
	FS        VFS
	// contains filtered or unexported fields
}

DefaultCodeServer implements every Code.Execute operation with sensible, language-agnostic defaults. Plugins embed this and call Override to replace handlers for operations they specialize (e.g. Fix, ListSymbols, deps).

func NewDefaultCodeServer 

func NewDefaultCodeServer(sourceDir string, opts ...ServerOption) *DefaultCodeServer

NewDefaultCodeServer creates a server rooted at sourceDir. By default it uses LocalVFS (direct os.* calls).

func (*DefaultCodeServer) Close 

func (s *DefaultCodeServer) Close() error

Close releases resources held by the server (e.g. CachedVFS watcher, git repo).

func (*DefaultCodeServer) Execute 

func (s *DefaultCodeServer) Execute(ctx context.Context, req *codev0.CodeRequest) (*codev0.CodeResponse, error)

Execute dispatches the incoming CodeRequest to the appropriate handler.

func (*DefaultCodeServer) FileOps 

func (s *DefaultCodeServer) FileOps() FileOperation

FileOps returns a FileOperation view over this server's VFS and root. Use it when only file operations (read, write, list, delete, move, copy, search, replace) are needed, so Search and ReplaceInFile always run on the virtual layer (e.g. overlay) instead of disk.

func (*DefaultCodeServer) GetSourceDir 

func (s *DefaultCodeServer) GetSourceDir() string

GetSourceDir returns the root directory for this server (implements VFSProvider).

func (*DefaultCodeServer) GetVFS 

func (s *DefaultCodeServer) GetVFS() VFS

GetVFS returns the VFS backend used by this server (implements VFSProvider).

func (*DefaultCodeServer) Override 

func (s *DefaultCodeServer) Override(op string, handler OperationHandler)

Override registers a custom handler for an operation name. Names match the oneof field names: "read_file", "write_file", "fix", etc.

func (*DefaultCodeServer) SetWriteListener 

func (s *DefaultCodeServer) SetWriteListener(l WriteListener)

SetWriteListener installs a post-mutation hook. It is called after every successful WriteFile, CreateFile, DeleteFile, and MoveFile dispatched through Execute. Language plugins wire their LSP's textDocument/didChange through this so the LSP's in-memory view stays in sync with disk without waiting for the filesystem watcher.

Safe to call after construction; nil clears the listener. The listener is invoked synchronously after the mutation commits; if you need async fire-and-forget, do the dispatch inside your own listener.

type DepEdge 

type DepEdge struct {
	From string
	To   string
}

DepEdge represents a directed dependency from one package to another.

type DepGraph 

type DepGraph struct {
	Module   string
	Packages []PackageNode
}

DepGraph represents the package dependency graph of a project. Nodes are packages; edges are import relationships.

func BuildDepGraph 

func BuildDepGraph(module string, packages []PackageInput) *DepGraph

BuildDepGraph creates a DepGraph from raw package data.

func (*DepGraph) ConnectedComponents 

func (g *DepGraph) ConnectedComponents() [][]string

ConnectedComponents returns groups of packages that are connected via internal imports (undirected). Packages in different components have no import relationship and can be worked on independently.

func (*DepGraph) Format 

func (g *DepGraph) Format() string

Format produces a compact text representation of the dependency graph.

func (*DepGraph) InternalEdges 

func (g *DepGraph) InternalEdges() []DepEdge

InternalEdges returns only edges between packages within the same module.

func (*DepGraph) Leaves 

func (g *DepGraph) Leaves() []string

Leaves returns packages that don't import any other internal package.

func (*DepGraph) Roots 

func (g *DepGraph) Roots() []string

Roots returns packages that are not imported by any other internal package.

type DiffKind 

type DiffKind int

DiffKind describes whether a line was added, removed, or unchanged. 

const (
	DiffContext DiffKind = iota // unchanged context line
	DiffAdd                     // added line
	DiffRemove                  // removed line
)

func (DiffKind) String 

func (k DiffKind) String() string

type DiffLine 

type DiffLine struct {
	Kind    DiffKind
	Content string
	OldLine int // 0 if the line doesn't exist in the old file
	NewLine int // 0 if the line doesn't exist in the new file
}

DiffLine is a single line within a hunk.

type Edge 

type Edge struct {
	From string   // source node ID
	To   string   // target node ID
	Kind EdgeKind // relationship type
}

Edge represents a directed relationship between two nodes.

type EdgeKind 

type EdgeKind int

EdgeKind classifies a relationship between two nodes. 

const (
	EdgeCalls    EdgeKind = iota // function A calls function B
	EdgeContains                 // file/package contains function/type
	EdgeImports                  // file imports a package
)

func (EdgeKind) String 

func (e EdgeKind) String() string

type EditResult 

type EditResult struct {
	Content  string // the file after replacement
	Strategy string // which strategy matched
	OK       bool
}

EditResult holds the outcome of a smart edit attempt.

func SmartEdit 

func SmartEdit(content, find, replace string) EditResult

SmartEdit tries all matching strategies to apply a FIND/REPLACE on content. Strategies are tried in order of decreasing precision:

  1. Exact substring match
  2. Trailing whitespace normalized
  3. Fully trimmed (all leading+trailing whitespace per line)
  4. Indentation-shifted (same content, different indent level)
  5. Anchor-based (first+last unique lines locate the region)
  6. Fuzzy scored (Levenshtein per line)
  7. Fuzzy block (60% line match threshold)

type FileChange 

type FileChange struct {
	Path    string
	Type    string // "create", "modify", "delete"
	Content []byte // nil for deletes
}

FileChange records a single file mutation in the overlay.

type FileDiff 

type FileDiff struct {
	OldPath string
	NewPath string
	Hunks   []Hunk
}

FileDiff represents the structured diff of a single file.

func ParseUnifiedDiff 

func ParseUnifiedDiff(raw string) []FileDiff

ParseUnifiedDiff parses the output of `git diff` (unified format) into structured FileDiff objects with line numbers on every line.

func (*FileDiff) Summary 

func (fd *FileDiff) Summary() string

Summary returns a concise description of the diff suitable for an LLM prompt.

type FileMap 

type FileMap struct {
	Path    string
	Symbols []SymbolEntry
}

FileMap represents the symbols in a single file.

type FileOperation 

type FileOperation interface {
	ReadFile(ctx context.Context, path string) ([]byte, error)
	WriteFile(ctx context.Context, path string, data []byte) error
	ListFiles(ctx context.Context, path string, recursive bool, extensions []string) ([]string, error)
	DeleteFile(ctx context.Context, path string) error
	MoveFile(ctx context.Context, oldPath, newPath string) error
	CopyFile(ctx context.Context, srcPath, destPath string) error
	Search(ctx context.Context, opts SearchOpts) (*SearchResult, error)
	ReplaceInFile(ctx context.Context, path, find, replace string) (changed bool, err error)
}

FileOperation provides VFS-only operations. All paths are relative to the root passed at construction. Search and ReplaceInFile run on the VFS (no ripgrep on disk), so overlay/virtual state is consistent.

func NewFileOps 

func NewFileOps(vfs VFS, root string) FileOperation

NewFileOps returns a FileOperation that uses vfs with all paths under root. Paths passed to its methods must be relative to root (e.g. "foo/bar.go").

type FileTimeline 

type FileTimeline struct {
	Path   string
	Chunks []TimelineChunk
}

FileTimeline is the temporal breakdown of a single source file.

func BuildFileTimeline 

func BuildFileTimeline(path string, blameLines []*codev0.GitBlameLine, refDate time.Time) *FileTimeline

BuildFileTimeline groups blame lines into consecutive chunks by commit hash, classifies each by age relative to refDate, and extracts a summary.

func BuildProjectTimeline 

func BuildProjectTimeline(ctx context.Context, vfs VFS, rootDir string, extensions []string, refDate time.Time) ([]*FileTimeline, error)

BuildProjectTimeline blames every source file and returns timelines sorted by path. It uses the VFS to discover files, skipping test files, vendor, and generated directories, then runs git blame directly via exec.Command.

func (*FileTimeline) Lines 

func (ft *FileTimeline) Lines() int

Lines returns total line count (EndLine of last chunk).

func (*FileTimeline) Newest 

func (ft *FileTimeline) Newest() time.Time

Newest returns the most recent chunk date, or zero time if empty.

func (*FileTimeline) Oldest 

func (ft *FileTimeline) Oldest() time.Time

Oldest returns the earliest chunk date, or zero time if empty.

type GitBlameLine 

type GitBlameLine struct {
	Hash    string
	Author  string
	Date    string
	Line    int32
	Content string
}

GitBlameLine holds blame information for a single line.

type GitCommitInfo 

type GitCommitInfo struct {
	Hash         string
	ShortHash    string
	Author       string
	Date         string
	Message      string
	FilesChanged int32
}

GitCommitInfo holds parsed commit data (used by both native and exec paths).

type GitDiffFileInfo 

type GitDiffFileInfo struct {
	Path      string
	Additions int32
	Deletions int32
	Status    string
}

GitDiffFileInfo holds per-file diff statistics.

type GoCodeServer 

type GoCodeServer struct {
	*DefaultCodeServer
	// contains filtered or unexported fields
}

GoCodeServer extends DefaultCodeServer with Go-specific operations: ListSymbols (via pluggable SymbolProvider), GetProjectInfo (go list), and ListDependencies (go list -m). It provides the same data as the go-generic agent but without requiring Docker or gopls.

func NewGoCodeServer 

func NewGoCodeServer(dir string, serverOpts []ServerOption, goOpts ...GoServerOption) *GoCodeServer

NewGoCodeServer creates a Go-aware code server. By default it uses ASTSymbolProvider (ParseGoTree) for symbols. Pass WithSymbolProvider() to use LSP or any other implementation. ServerOptions are forwarded to the embedded DefaultCodeServer (e.g. WithVFS).

func (*GoCodeServer) GetProjectInfo 

func (s *GoCodeServer) GetProjectInfo(ctx context.Context, req *codev0.GetProjectInfoRequest) (*codev0.GetProjectInfoResponse, error)

GetProjectInfo implements the standalone gRPC RPC (not through Execute).

func (*GoCodeServer) ListDependencies 

func (s *GoCodeServer) ListDependencies(ctx context.Context, req *codev0.ListDependenciesRequest) (*codev0.ListDependenciesResponse, error)

ListDependencies implements the standalone gRPC RPC.

func (*GoCodeServer) ListSymbols 

func (s *GoCodeServer) ListSymbols(ctx context.Context, req *codev0.ListSymbolsRequest) (*codev0.ListSymbolsResponse, error)

ListSymbols implements the standalone gRPC RPC (not through Execute).

func (*GoCodeServer) VFS 

func (s *GoCodeServer) VFS() VFS

VFS returns the underlying VFS of the code server.

type GoServerOption 

type GoServerOption func(*GoCodeServer)

GoServerOption configures a GoCodeServer.

func WithSymbolProvider 

func WithSymbolProvider(sp SymbolProvider) GoServerOption

WithSymbolProvider overrides the default AST-based symbol provider. Use this to plug in an LSP-backed provider when gopls is available.

type GraphStats 

type GraphStats struct {
	TotalNodes int
	TotalEdges int
	Functions  int
	Methods    int
	Types      int
	Files      int
	Packages   int
}

GraphStats holds aggregate counts for a code graph.

func (GraphStats) String 

func (s GraphStats) String() string

type HotspotFile 

type HotspotFile struct {
	Path   string
	Chunks int
}

HotspotFile tracks files with many distinct commit chunks.

type Hunk 

type Hunk struct {
	OldStart int // 1-based starting line in the old version
	OldCount int
	NewStart int // 1-based starting line in the new version
	NewCount int
	Header   string // optional hunk header (function name, etc.)
	Lines    []DiffLine
}

Hunk is a contiguous block of changes within a file diff.

type LocalVFS 

type LocalVFS struct{}

LocalVFS delegates every call to the os/filepath standard library. This is the default for DefaultCodeServer -- zero behavior change from the original direct-os implementation.

func (LocalVFS) MkdirAll 

func (LocalVFS) MkdirAll(path string, perm os.FileMode) error

func (LocalVFS) ReadDir 

func (LocalVFS) ReadDir(path string) ([]os.DirEntry, error)

func (LocalVFS) ReadFile 

func (LocalVFS) ReadFile(path string) ([]byte, error)

func (LocalVFS) Remove 

func (LocalVFS) Remove(path string) error

func (LocalVFS) Rename 

func (LocalVFS) Rename(oldpath, newpath string) error

func (LocalVFS) Stat 

func (LocalVFS) Stat(path string) (os.FileInfo, error)

func (LocalVFS) WalkDir 

func (LocalVFS) WalkDir(root string, fn fs.WalkDirFunc) error

func (LocalVFS) WriteFile 

func (LocalVFS) WriteFile(path string, data []byte, perm os.FileMode) error

type MemoryVFS 

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

MemoryVFS is a pure in-memory filesystem. All paths are absolute. Safe for concurrent use.

func NewMemoryVFS 

func NewMemoryVFS() *MemoryVFS

NewMemoryVFS creates an empty in-memory filesystem.

func NewMemoryVFSFrom 

func NewMemoryVFSFrom(files map[string]string) *MemoryVFS

NewMemoryVFSFrom creates a MemoryVFS pre-populated with the given files. Keys are absolute paths, values are file contents.

func (*MemoryVFS) MkdirAll 

func (m *MemoryVFS) MkdirAll(path string, _ os.FileMode) error

func (*MemoryVFS) ReadDir 

func (m *MemoryVFS) ReadDir(path string) ([]os.DirEntry, error)

func (*MemoryVFS) ReadFile 

func (m *MemoryVFS) ReadFile(path string) ([]byte, error)

func (*MemoryVFS) Remove 

func (m *MemoryVFS) Remove(path string) error

func (*MemoryVFS) Rename 

func (m *MemoryVFS) Rename(oldpath, newpath string) error

func (*MemoryVFS) Stat 

func (m *MemoryVFS) Stat(path string) (os.FileInfo, error)

func (*MemoryVFS) WalkDir 

func (m *MemoryVFS) WalkDir(root string, fn fs.WalkDirFunc) error

func (*MemoryVFS) WriteFile 

func (m *MemoryVFS) WriteFile(path string, data []byte, _ os.FileMode) error

type NativeGit 

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

NativeGit wraps a go-git Repository for in-process git operations. Eliminates fork/exec overhead for common operations (log, show, diff). Falls back to exec for operations go-git doesn't support well (blame with line ranges).

func OpenNativeGit 

func OpenNativeGit(dir string) *NativeGit

OpenNativeGit opens a git repository at dir. Returns nil (not error) if dir is not a git repo — callers should fall back to exec-based git.

func (*NativeGit) DiffStat 

func (g *NativeGit) DiffStat(ctx context.Context, baseRef, headRef string) ([]*GitDiffFileInfo, error)

DiffStat returns file-level diff statistics between two refs. For full unified diff output, fall back to exec (go-git's patch is verbose).

func (*NativeGit) HEAD 

func (g *NativeGit) HEAD() (string, error)

HEAD returns the current HEAD commit hash.

func (*NativeGit) ListBranches 

func (g *NativeGit) ListBranches() ([]string, error)

ListBranches returns all local branch names.

func (*NativeGit) Log 

func (g *NativeGit) Log(ctx context.Context, maxCount int, ref, path, since string) ([]*GitCommitInfo, error)

Log returns recent commits, optionally filtered by path and since date.

func (*NativeGit) Show 

func (g *NativeGit) Show(ctx context.Context, ref, path string) (string, bool, error)

Show returns the content of a file at a given ref.

type NativeJJ 

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

NativeJJ implements VCSProvider for Jujutsu (jj) repositories. All operations go through the jj CLI — there is no Go library for jj.

func OpenNativeJJ 

func OpenNativeJJ(dir string) *NativeJJ

OpenNativeJJ returns a NativeJJ if dir contains a .jj directory and jj is installed. Returns nil if jj is not available or dir is not a jj repo.

func (*NativeJJ) Blame 

func (j *NativeJJ) Blame(ctx context.Context, path string, startLine, endLine int32) ([]*GitBlameLine, error)

func (*NativeJJ) Diff 

func (j *NativeJJ) Diff(ctx context.Context, baseRef, headRef, path string, contextLines int, statOnly bool) (string, []*GitDiffFileInfo, error)

func (*NativeJJ) Log 

func (j *NativeJJ) Log(ctx context.Context, maxCount int, ref, path, since string) ([]*GitCommitInfo, error)

func (*NativeJJ) Show 

func (j *NativeJJ) Show(ctx context.Context, ref, path string) (string, bool, error)

type Neighborhood 

type Neighborhood struct {
	Node     *CodeNode
	Callers  []*CodeNode
	Callees  []*CodeNode
	SameFile []*CodeNode
}

Neighborhood captures the structural context around a node.

type NodeKind 

type NodeKind int

NodeKind classifies a code graph node. 

const (
	NodeFunction NodeKind = iota // standalone function
	NodeMethod                   // method on a type
	NodeType                     // struct or interface declaration
	NodeFile                     // source file
	NodePackage                  // directory / package
)

func (NodeKind) String 

func (k NodeKind) String() string

type OperationHandler 

type OperationHandler func(ctx context.Context, req *codev0.CodeRequest) (*codev0.CodeResponse, error)

OperationHandler processes a single code operation within Execute.

type OverlayVFS 

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

OverlayVFS layers in-memory writes/deletes on top of a base VFS. Reads check the overlay first, then fall through to the base. Writes never touch the base until Commit() is called.

func NewOverlayVFS 

func NewOverlayVFS(base VFS) *OverlayVFS

NewOverlayVFS wraps an existing VFS with an in-memory overlay.

func (*OverlayVFS) Base 

func (o *OverlayVFS) Base() VFS

Base returns the underlying VFS.

func (*OverlayVFS) BaseSnapshot 

func (o *OverlayVFS) BaseSnapshot(path string) ([]byte, bool)

BaseSnapshot returns the base content captured when the overlay first touched a file. Returns nil, false if no snapshot exists.

func (*OverlayVFS) Commit 

func (o *OverlayVFS) Commit() error

Commit flushes all overlay writes to the base VFS and applies deletes.

func (*OverlayVFS) DeletedFiles 

func (o *OverlayVFS) DeletedFiles() []string

DeletedFiles returns the set of file paths that have pending deletes.

func (*OverlayVFS) Diff 

func (o *OverlayVFS) Diff() []FileChange

Diff returns a list of all file changes in the overlay.

func (*OverlayVFS) Dirty 

func (o *OverlayVFS) Dirty() bool

Dirty returns true if the overlay has any pending changes.

func (*OverlayVFS) MkdirAll 

func (o *OverlayVFS) MkdirAll(path string, perm os.FileMode) error

func (*OverlayVFS) ModifiedFiles 

func (o *OverlayVFS) ModifiedFiles() []string

ModifiedFiles returns the set of file paths that have pending writes.

func (*OverlayVFS) ReadDir 

func (o *OverlayVFS) ReadDir(path string) ([]os.DirEntry, error)

func (*OverlayVFS) ReadFile 

func (o *OverlayVFS) ReadFile(path string) ([]byte, error)

func (*OverlayVFS) Remove 

func (o *OverlayVFS) Remove(path string) error

func (*OverlayVFS) Rename 

func (o *OverlayVFS) Rename(oldpath, newpath string) error

func (*OverlayVFS) Rollback 

func (o *OverlayVFS) Rollback()

Rollback discards all overlay changes.

func (*OverlayVFS) Stat 

func (o *OverlayVFS) Stat(path string) (os.FileInfo, error)

func (*OverlayVFS) WalkDir 

func (o *OverlayVFS) WalkDir(root string, fn fs.WalkDirFunc) error

func (*OverlayVFS) WriteFile 

func (o *OverlayVFS) WriteFile(path string, data []byte, perm os.FileMode) error

type PackageInput 

type PackageInput struct {
	Name    string
	Path    string
	Imports []string
	Files   []string
	Doc     string
}

BuildDepGraph constructs a dependency graph from package info.

type PackageNode 

type PackageNode struct {
	Name    string
	Path    string
	Imports []string
	Files   []string
	Doc     string
}

PackageNode represents one package in the dependency graph.

type PythonASTSymbolProvider 

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

PythonASTSymbolProvider extracts symbols from Python files using Python's ast module via a subprocess.

func NewPythonASTSymbolProvider 

func NewPythonASTSymbolProvider(sourceDir string) *PythonASTSymbolProvider

NewPythonASTSymbolProvider creates a provider that parses Python files.

func (*PythonASTSymbolProvider) Close 

func (p *PythonASTSymbolProvider) Close()

Close removes the temporary script file.

func (*PythonASTSymbolProvider) ListSymbols 

func (p *PythonASTSymbolProvider) ListSymbols(ctx context.Context, file string) ([]*codev0.Symbol, error)

ListSymbols extracts symbols from a file or the entire source directory.

type PythonCodeServer 

type PythonCodeServer struct {
	*DefaultCodeServer
	// contains filtered or unexported fields
}

PythonCodeServer extends DefaultCodeServer with Python-specific operations: GetProjectInfo (pyproject.toml + uv), ListDependencies (uv pip list), and ListSymbols (via pluggable SymbolProvider — AST or LSP).

func NewPythonCodeServer 

func NewPythonCodeServer(dir string, serverOpts []ServerOption, pyOpts ...PythonServerOption) *PythonCodeServer

NewPythonCodeServer creates a Python-aware code server.

func (*PythonCodeServer) GetProjectInfo 

func (s *PythonCodeServer) GetProjectInfo(ctx context.Context, req *codev0.GetProjectInfoRequest) (*codev0.GetProjectInfoResponse, error)

func (*PythonCodeServer) ListDependencies 

func (s *PythonCodeServer) ListDependencies(ctx context.Context, req *codev0.ListDependenciesRequest) (*codev0.ListDependenciesResponse, error)

func (*PythonCodeServer) ListSymbols 

func (s *PythonCodeServer) ListSymbols(ctx context.Context, req *codev0.ListSymbolsRequest) (*codev0.ListSymbolsResponse, error)

type PythonServerOption 

type PythonServerOption func(*PythonCodeServer)

PythonServerOption configures a PythonCodeServer.

func WithPythonSymbolProvider 

func WithPythonSymbolProvider(sp SymbolProvider) PythonServerOption

WithPythonSymbolProvider overrides the default symbol provider.

type RelevanceScorer 

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

RelevanceScorer ranks files by structural relevance to a text query. All signals are computed from data already available in CodebaseContext -- no embeddings or LLM calls required.

func NewRelevanceScorer 

func NewRelevanceScorer(cc *CodebaseContext, vfs VFS, rootDir string, opts ...ScorerOption) *RelevanceScorer

NewRelevanceScorer creates a scorer from a CodebaseContext and its backing server. vfs and rootDir are used for the search signal; pass a DefaultCodeServer's FS and SourceDir.

func (*RelevanceScorer) ScoreFiles 

func (r *RelevanceScorer) ScoreFiles(ctx context.Context, query string, files []string) []ScoredFile

ScoreFiles ranks the provided files by relevance to the query. Returns results sorted by descending score.

func (*RelevanceScorer) TopK 

func (r *RelevanceScorer) TopK(ctx context.Context, query string, files []string, k int) []ScoredFile

TopK returns the top K files from ScoreFiles.

type ScoredFile 

type ScoredFile struct {
	Path  string
	Score float64

	SearchHits  int
	SymbolHits  int
	Callers     int
	RecentLines int
	Importers   int
}

ScoredFile is a file path annotated with a composite relevance score.

type ScorerOption 

type ScorerOption func(*RelevanceScorer)

ScorerOption configures a RelevanceScorer.

func WithWeights 

func WithWeights(search, symbol, callGraph, recency, centrality float64) ScorerOption

WithWeights sets custom signal weights. Default: 0.35, 0.25, 0.15, 0.15, 0.10.

type SearchMatch 

type SearchMatch struct {
	File string // relative to root
	Line int
	Text string
}

SearchMatch is one search result.

type SearchOpts 

type SearchOpts struct {
	Pattern         string
	Literal         bool
	CaseInsensitive bool
	Path            string   // subdirectory (relative to root)
	Extensions      []string // e.g. [".go", ".py"]
	Exclude         []string // glob patterns
	MaxResults      int      // 0 = 100
	ContextLines    int
}

SearchOpts configures a text search.

type SearchResult 

type SearchResult struct {
	Matches   []SearchMatch
	Truncated bool
}

SearchResult holds all matches. 

func Search(ctx context.Context, root string, opts SearchOpts) (*SearchResult, error)

Search runs ripgrep on a local directory.

func SearchTrigram 

func SearchTrigram(_ context.Context, vfs VFS, idx *TrigramIndex, root string, opts SearchOpts) (*SearchResult, error)

SearchTrigram performs trigram-accelerated search. The index narrows candidates to files containing the query's trigrams, then regex matches only those files. Falls back to SearchVFS if trigrams can't be extracted (e.g., pure wildcard pattern).

func SearchVFS 

func SearchVFS(_ context.Context, vfs VFS, root string, opts SearchOpts) (*SearchResult, error)

SearchVFS performs regex-based text search over a VFS. Used when the filesystem is non-local (MemoryVFS, OverlayVFS) and ripgrep can't run.

type ServerOption 

type ServerOption func(*DefaultCodeServer)

ServerOption configures a DefaultCodeServer.

func WithCachedFS 

func WithCachedFS() ServerOption

WithCachedFS enables in-memory file tree caching backed by fsnotify. Metadata operations (Stat, ReadDir, WalkDir) are served from cache. File reads/writes pass through to disk. Cache is kept fresh via fsnotify.

func WithContentCache 

func WithContentCache(budgetBytes int64) ServerOption

WithContentCache enables in-memory file content caching on top of CachedVFS. File reads are served from RAM with LRU eviction. Invalidated by fsnotify. Implies WithCachedFS. budgetBytes is the maximum memory for cached content (default 200MB if 0).

func WithTrigramIndex 

func WithTrigramIndex() ServerOption

WithTrigramIndex enables trigram-based search indexing for sub-linear text search. Implies WithContentCache (trigram index reads content from cache). Files are indexed at startup and updated incrementally via fsnotify.

func WithVFS 

func WithVFS(vfs VFS) ServerOption

WithVFS sets a custom VFS backend. Defaults to LocalVFS.

type SymbolEntry 

type SymbolEntry struct {
	Name      string
	Kind      string // "function", "struct", "method", "interface", "class", "constant", "variable"
	Signature string
	Line      int
	Parent    string
	Children  []SymbolEntry
}

SymbolEntry is a flattened symbol record for the code map.

type SymbolInput 

type SymbolInput struct {
	Name      string
	Kind      string
	Signature string
	File      string
	Line      int
	Parent    string
	Children  []SymbolInput
}

BuildCodeMap constructs a CodeMap from raw symbol data (as returned by ListSymbols). Each SymbolInput mirrors the proto Symbol message but in plain Go types.

type SymbolProvider 

type SymbolProvider interface {
	ListSymbols(ctx context.Context, file string) ([]*codev0.Symbol, error)
}

SymbolProvider abstracts how symbols are resolved for a codebase. Default implementation: ASTSymbolProvider (Go AST via ParseGoTree). Override with LSPSymbolProvider (gopls) for full cross-module resolution.

type TSASTSymbolProvider 

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

TSASTSymbolProvider extracts symbols from TypeScript/JavaScript files using the TypeScript compiler API via a Node.js subprocess.

func NewTSASTSymbolProvider 

func NewTSASTSymbolProvider(sourceDir string) *TSASTSymbolProvider

NewTSASTSymbolProvider creates a provider that parses TS/JS files.

func (*TSASTSymbolProvider) Close 

func (p *TSASTSymbolProvider) Close()

Close removes the temporary script file.

func (*TSASTSymbolProvider) ListSymbols 

func (p *TSASTSymbolProvider) ListSymbols(ctx context.Context, file string) ([]*codev0.Symbol, error)

ListSymbols extracts symbols from a file or the entire source directory.

func (*TSASTSymbolProvider) ListSymbolsByFile 

func (p *TSASTSymbolProvider) ListSymbolsByFile(ctx context.Context) (map[string][]*codev0.Symbol, error)

ListSymbolsByFile returns symbols grouped by relative file path.

type TimelineChunk 

type TimelineChunk struct {
	StartLine int
	EndLine   int
	Hash      string
	Author    string
	Date      time.Time
	Age       AgeBucket
	Summary   string // first non-blank content line in the range
}

TimelineChunk groups consecutive lines from the same commit.

type TimelineStats 

type TimelineStats struct {
	TotalLines  int
	TotalFiles  int
	TotalChunks int

	LinesByAge map[AgeBucket]int // lines per bucket

	NewestFile string    // most recently modified file
	NewestDate time.Time // date of most recent change
	OldestFile string    // oldest untouched file
	OldestDate time.Time // date of oldest change

	Hotspots []HotspotFile // files with most distinct chunks (frequently patched)
}

TimelineStats summarizes the temporal distribution of a project's code.

func ComputeTimelineStats 

func ComputeTimelineStats(timelines []*FileTimeline) TimelineStats

ComputeTimelineStats derives project-wide statistics from a set of timelines.

type TrigramIndex 

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

TrigramIndex provides sub-linear text search by maintaining posting lists of trigrams (3-byte sequences) to file IDs. A search query extracts trigrams, intersects their posting lists, and only scans the resulting candidate files.

Typical speedup: 10-100x on large repos vs linear scan.

func NewTrigramIndex 

func NewTrigramIndex() *TrigramIndex

NewTrigramIndex creates an empty trigram index.

func (*TrigramIndex) AddFile 

func (idx *TrigramIndex) AddFile(path string, content []byte)

AddFile indexes the content of a file. If the file was previously indexed, it is removed first (full re-index of that file).

func (*TrigramIndex) Query 

func (idx *TrigramIndex) Query(pattern string) []string

Query returns candidate file paths that contain ALL trigrams from the pattern. For short patterns (<3 bytes), returns all indexed files (no filtering possible). The candidates are a superset of actual matches — callers must verify with regex.

func (*TrigramIndex) RemoveFile 

func (idx *TrigramIndex) RemoveFile(path string)

RemoveFile removes a file from the index.

func (*TrigramIndex) Size 

func (idx *TrigramIndex) Size() int

Size returns the number of indexed files.

type VCSProvider 

type VCSProvider interface {
	// Log returns recent commits, optionally filtered by ref, path, and date.
	Log(ctx context.Context, maxCount int, ref, path, since string) ([]*GitCommitInfo, error)

	// Diff returns a diff between two refs (or working copy if refs are empty).
	// Returns the full diff text and per-file statistics.
	Diff(ctx context.Context, baseRef, headRef, path string, contextLines int, statOnly bool) (string, []*GitDiffFileInfo, error)

	// Show returns the content of a file at a specific ref.
	Show(ctx context.Context, ref, path string) (string, bool, error)

	// Blame returns line-by-line authorship of a file.
	Blame(ctx context.Context, path string, startLine, endLine int32) ([]*GitBlameLine, error)
}

VCSProvider abstracts version control operations. Both git and jj implement this interface, allowing the DefaultCodeServer to dispatch VCS operations without knowing which VCS is in use.

The response types (GitCommitInfo, GitDiffFileInfo, etc.) are VCS-agnostic despite their "Git" prefix — they map to the Code proto responses.

type VFS 

type VFS interface {
	ReadFile(path string) ([]byte, error)
	WriteFile(path string, data []byte, perm os.FileMode) error
	Remove(path string) error
	Rename(oldpath, newpath string) error
	Stat(path string) (os.FileInfo, error)
	MkdirAll(path string, perm os.FileMode) error
	WalkDir(root string, fn fs.WalkDirFunc) error
	ReadDir(path string) ([]os.DirEntry, error)
}

VFS abstracts filesystem operations so DefaultCodeServer can work with local disk, in-memory stores, overlay layers, or remote backends. All paths are absolute -- the server joins SourceDir + relative before calling.

type VFSProvider 

type VFSProvider interface {
	GetVFS() VFS
	GetSourceDir() string
}

VFSProvider is implemented by servers that expose their underlying VFS and root directory for in-process use (e.g. relevance scoring, timeline building).

type WriteListener 

type WriteListener func(ctx context.Context, kind, path, prevPath string, content []byte) error

WriteListener is called after every successful file mutation so that language plugins can push the new content into their LSP's in-memory view via textDocument/didChange. Without this, gopls and pylsp only notice the edit when their filesystem watcher fires — latency that breaks the agent's "edit → query symbols → see own edit" inner loop.

The listener receives the mutation kind ("write", "create", "delete", "move"), the relative path (destination for moves), and the new file content if available. For deletes and moves the content argument is nil. For the move kind, prevPath is the source path; it is empty otherwise.

Errors returned by the listener are logged by the caller but do NOT fail the mutation — notification is best-effort. A failing LSP shouldn't break file I/O.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.