repomap

Documentation

Index

• Variables
• func CtagsAvailable() bool
• func FormatLines(files []RankedFile, maxTokens int, root string) string
• func FormatMap(files []RankedFile, maxTokens int, verbose, detail bool) string
• func LanguageFor(ext string) string
• func PersistInventory(inv *Inventory, cacheDir string) error
• func QueryInventory(cacheDir string, filter string) (string, error)
• func Register(e *sdk.Extension)
• type Config
  • func DefaultConfig() Config
• type FileInfo
  • func ScanFiles(ctx context.Context, root string) ([]FileInfo, error)
• type FileMetrics
• type FileSymbols
  • func ParseGenericFile(path, root, language string) (*FileSymbols, error)
  • func ParseGoFile(path, root string) (*FileSymbols, error)
  • func ParseWithCtags(ctx context.Context, root string, files []FileInfo) ([]*FileSymbols, error)
• type Inventory
  • func LoadInventory(cacheDir string) *Inventory
  • func ScanInventory(ctx context.Context, root string) (*Inventory, error)
• type Map
  • func New(root string, cfg Config) *Map
  • func (m *Map) Build(ctx context.Context) error
  • func (m *Map) BuiltAt() time.Time
  • func (m *Map) Dirty()
  • func (m *Map) LoadCache(cacheDir string) bool
  • func (m *Map) SaveCache(cacheDir string) error
  • func (m *Map) SetCacheDir(dir string)
  • func (m *Map) Stale() bool
  • func (m *Map) String() string
  • func (m *Map) StringDetail() string
  • func (m *Map) StringLines() string
  • func (m *Map) StringVerbose() string
• type RankedFile
  • func BudgetFiles(ranked []RankedFile, maxTokens int) []RankedFile
  • func RankFiles(files []*FileSymbols) []RankedFile
• type Symbol

Variables

var ErrNotCodeProject = errors.New("no source files found")

ErrNotCodeProject is returned by Build when the target directory contains no recognisable source files. Callers should treat this as a normal condition, not an error — the project is simply not a code project.

Functions

func CtagsAvailable

func CtagsAvailable() bool

CtagsAvailable reports whether ctags with JSON output support is on PATH.

func FormatLines

func FormatLines(files []RankedFile, maxTokens int, root string) string

FormatLines formats ranked files showing actual source code lines. root is the project root for resolving file paths.

func FormatMap

func FormatMap(files []RankedFile, maxTokens int, verbose, detail bool) string

FormatMap formats ranked files into a token-budgeted text representation. maxTokens controls the output size (estimated as len(text)/4). Returns empty string if no files have symbols. When verbose is true, shows all symbols without summarization. When detail is true, shows signatures for funcs/methods and fields for structs.

func LanguageFor

func LanguageFor(ext string) string

LanguageFor returns the language ID for a file extension, or "" if unsupported.

func PersistInventory

func PersistInventory(inv *Inventory, cacheDir string) error

func QueryInventory

func QueryInventory(cacheDir string, filter string) (string, error)

func Register

func Register(e *sdk.Extension)

Register wires the repomap extension into a shared SDK extension.

Types

type Config

type Config struct {
	MaxTokens      int // token budget for output (default: 1024)
	MaxTokensNoCtx int // budget when no files in conversation (default: 2048)
}

Config holds repomap configuration.

func DefaultConfig

func DefaultConfig() Config

DefaultConfig returns the default configuration.

type FileInfo

type FileInfo struct {
	Path     string // relative to project root
	Language string // language ID
}

FileInfo holds a discovered file with its language.

func ScanFiles

func ScanFiles(ctx context.Context, root string) ([]FileInfo, error)

ScanFiles discovers source files in the given directory. Uses git ls-files when available, falls back to directory walking.

type FileMetrics

type FileMetrics struct {
	Path    string `json:"path"`
	Lines   int    `json:"lines"`
	Imports int    `json:"imports"`
	LastMod string `json:"last_modified"`
}

type FileSymbols

type FileSymbols struct {
	Path       string // relative path from project root
	Language   string // language ID
	Package    string // Go package name (empty for non-Go)
	ImportPath string // Go import path from module (empty for non-Go)
	Symbols    []Symbol
	Imports    []string // import paths (Go) or module names (other)
}

FileSymbols holds all symbols extracted from a single source file.

func ParseGenericFile

func ParseGenericFile(path, root, language string) (*FileSymbols, error)

ParseGenericFile extracts symbols from a non-Go source file using regex patterns. path is absolute, root is the project root for relative path calculation.

func ParseGoFile

func ParseGoFile(path, root string) (*FileSymbols, error)

ParseGoFile extracts exported symbols from a Go source file. path is absolute, root is the project root for relative path calculation.

func ParseWithCtags

func ParseWithCtags(ctx context.Context, root string, files []FileInfo) ([]*FileSymbols, error)

ParseWithCtags runs ctags once over all files and returns FileSymbols for each non-Go file in the list. Files must be absolute paths; root is used only for computing relative paths in output.

type Inventory

type Inventory struct {
	Files     []FileMetrics `json:"files"`
	Scanned   string        `json:"scanned"`
	RootPath  string        `json:"root_path"`
	Truncated bool          `json:"truncated,omitempty"` // true when file cap was reached
}

func LoadInventory

func LoadInventory(cacheDir string) *Inventory

func ScanInventory

func ScanInventory(ctx context.Context, root string) (*Inventory, error)

type Map

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

Map holds the built repository map state.

func New

func New(root string, cfg Config) *Map

New creates a new Map for the given project root.

func (*Map) Build

func (m *Map) Build(ctx context.Context) error

Build performs a full scan → parse → rank pipeline. Safe for concurrent use.

func (*Map) BuiltAt

func (m *Map) BuiltAt() time.Time

BuiltAt returns the time of the last successful build, or zero time if never built.

func (*Map) Dirty

func (m *Map) Dirty()

Dirty marks the map as needing a rebuild by zeroing builtAt, bypassing the stale debounce. Use after code-changing tool calls.

func (*Map) LoadCache

func (m *Map) LoadCache(cacheDir string) bool

LoadCache loads a previously saved map from disk. Returns false if the cache is missing, corrupt, or for a different version.

func (*Map) SaveCache

func (m *Map) SaveCache(cacheDir string) error

SaveCache writes the current map state to disk.

func (*Map) SetCacheDir

func (m *Map) SetCacheDir(dir string)

SetCacheDir enables disk caching. Build() will save to this directory.

func (*Map) Stale

func (m *Map) Stale() bool

Stale reports whether any tracked file has been modified since the last build. Uses file mtimes for fast checking. Also stale if Build has never been called. Debounced: returns false if last build was <30s ago.

func (*Map) String

func (m *Map) String() string

String returns the current formatted map output. Returns empty string if Build has not been called or produced no symbols.

func (*Map) StringDetail

func (m *Map) StringDetail() string

StringDetail returns the full detailed map output with signatures and struct fields. Returns empty string if Build has not been called or produced no symbols.

func (*Map) StringLines

func (m *Map) StringLines() string

StringLines returns the source-line format showing actual code definitions. More concise than verbose mode, more useful than compact mode. Returns empty string if Build has not been called or produced no symbols.

func (*Map) StringVerbose

func (m *Map) StringVerbose() string

StringVerbose returns the full verbose map output (all symbols, no summarization). Returns empty string if Build has not been called or produced no symbols.

type RankedFile

type RankedFile struct {
	FileSymbols
	Score       int    // higher = more important
	Tag         string // e.g. "entry", ""
	DetailLevel int    // set by BudgetFiles: -1=omit, 0=header, 1=summary, 2=symbols, 3=symbols+fields
}

RankedFile is a FileSymbols with an importance score.

func BudgetFiles

func BudgetFiles(ranked []RankedFile, maxTokens int) []RankedFile

BudgetFiles assigns a DetailLevel to each RankedFile within the given token budget. When maxTokens is 0, all files get DetailLevel 2 (unlimited mode for verbose/detail).

Detail levels:

-1: omitted (budget overflow, counted in footer)
 0: header only — path + optional (package name)
 1: summary — path + "5 types, 3 funcs"
 2: full symbol groups
 3: symbols + struct/interface field expansion

func RankFiles

func RankFiles(files []*FileSymbols) []RankedFile

RankFiles scores and sorts files by importance. Returns files sorted by score descending, then by path ascending for ties.

type Symbol

type Symbol struct {
	Name      string // e.g. "Agent", "New", "Run"
	Kind      string // "function", "method", "struct", "interface", "constant", "variable", "type", "class", "enum"
	Signature string // e.g. "(ctx, provider, opts) *Agent" — params + return, no func keyword
	Receiver  string // e.g. "*Agent" — methods only, empty for functions
	Exported  bool   // true if the symbol is exported (uppercase first letter)
	Line      int    // 1-based source line number (0 = unknown)
}

Symbol represents a single extracted symbol from a source file.