Documentation
¶
Overview ¶
Package repo implements BroCode's deterministic project intelligence layer: a repo map (entry points, structure, hot files) built without the LLM, and cross-session usage tracking ("the more BroCode is used, the smarter it gets"). Both persist under .brocode/ and are injected into the system prompt so every session starts warm without spending tokens on re-discovery.
- RepoMap: tree (depth-2) + entry points, built deterministically from the filesystem, cached to .brocode/repo-map.json keyed by a content hash of the file list — rebuilt only when the project actually changes.
- Usage: counts how often each file is read/edited per session, aggregated across sessions in .brocode/usage.json, so warm starts can prioritize the files the team actually works on (not just the ones the LLM guessed).
Package scope provides smart scope pre-selection: given a user prompt, it quickly identifies which files/directories are most relevant so BroCode can focus its exploration instead of scanning the entire workspace.
Index ¶
- func DetectStack(files []string) []string
- func DirtyFiles(workspaceDir string, files []string) []string
- func ListProjectFiles(workspaceDir string) []string
- func SuggestFocusDirs(results []RelevanceResult) []string
- func SummarizeScope(results []RelevanceResult, prompt string) string
- func UpdateSnapshot(workspaceDir string, files []string)
- type Map
- type RelevanceResult
- type RepoInfo
- type Stack
- type Usage
- type Workspace
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DetectStack ¶ added in v0.1.1
DetectStack returns just the stack names (no evidence files).
func DirtyFiles ¶ added in v0.1.2
DirtyFiles returns the set of source files that have changed (by mtime) since the last snapshot was taken, or all files if no snapshot exists yet. This enables incremental LSP scans: only re-open files whose mtime or size differs from the cached snapshot, skipping unchanged files entirely. Call UpdateSnapshot after scanning to refresh the baseline.
func ListProjectFiles ¶ added in v0.1.2
ListProjectFiles returns the full list of project source files (relative, sorted, with heavy dirs / sensitive files / binary extensions excluded). Public wrapper around listProjectFiles for use by the smart-scope layer.
func SuggestFocusDirs ¶ added in v0.1.2
func SuggestFocusDirs(results []RelevanceResult) []string
SuggestFocusDirs returns the directories that contain the highest-scoring files, as a suggestion for BroCode to focus exploration. Returns at most 5.
func SummarizeScope ¶ added in v0.1.2
func SummarizeScope(results []RelevanceResult, prompt string) string
SummarizeScope produces a short markdown summary of which files/dirs BroCode should focus on, for injection into the system prompt.
func UpdateSnapshot ¶ added in v0.1.2
UpdateSnapshot writes the current mtime signatures for the given files, refreshing the dirty-file baseline. Called after a successful scan.
Types ¶
type Map ¶
type Map struct {
// Tree is a compact depth-2 directory listing (relative paths).
Tree []string `json:"tree"`
// EntryPoints are the files/commands a developer reaches for first
// (main.go, package.json bin, cmd/, index.ts, ...).
EntryPoints []string `json:"entry_points"`
// Stacks are the repo's primary languages, detected from manifest and
// entry-point files ("go", "node", "ts", "rust", ...), each with the
// files that evidence it. The prompt renders them as a one-line STACK
// hint ("STACK: go (go.mod, main.go)") and biases the skill catalog
// toward the repo's stack.
Stacks []Stack `json:"stacks,omitempty"`
// HotFiles are the top-N files by usage frequency ("" when no usage yet).
HotFiles []string `json:"hot_files"`
// Hash is the content hash of the file list this map was built from.
Hash string `json:"hash"`
}
Map is the deterministic project map: a depth-2 tree plus detected entry points and the most-used files (from cross-session usage).
func BuildMap ¶
BuildMap walks the workspace and produces a deterministic Map, honoring the cache: when the file-list hash matches the cached map's hash it is returned as-is (no re-scan). Usage is merged in so hot files reflect the latest cross-session counts. Returns nil when the workspace is unusable.
type RelevanceResult ¶ added in v0.1.2
type RelevanceResult struct {
Path string
Score float64
Reason string // human-readable reason for the score
}
RelevanceResult is a file path with a 0-1 relevance score to the prompt.
func ScoreFiles ¶ added in v0.1.2
func ScoreFiles(files []string, prompt string, limit int) []RelevanceResult
ScoreFiles ranks files by relevance to a user prompt keyword. Uses filename matching, directory path matching, and file extension hints. Returns top `limit` results sorted by score descending.
type RepoInfo ¶ added in v0.1.1
type RepoInfo struct {
Name string `json:"name"`
Path string `json:"path"`
IsGit bool `json:"is_git"`
}
RepoInfo describes a single repository inside a workspace.
type Stack ¶ added in v0.1.1
Stack is one detected language plus the files that evidence it.
func DetectStackInfo ¶ added in v0.1.1
DetectStackInfo returns the repo's primary languages, derived deterministically from manifest files (go.mod → "go", package.json → "node", Cargo.toml → "rust", ...) refined by entry-point code files (package.json alone cannot tell TS from JS; src/main.ts → "ts"). Each stack carries its evidence files so the prompt can render "STACK: go (go.mod, main.go)". Used to bias the skill catalog toward the repo's stack and to emit a one-line STACK hint, so stack-specific skills follow the repo instead of relying on the model to guess. Empty when no stack is detectable.
type Usage ¶
type Usage struct {
// contains filtered or unexported fields
}
Usage counts how often each file was read or edited across sessions, so warm starts can prioritize what the team actually works on. Persisted to .brocode/usage.json; counts decay slowly so long-gone hotspots fade.
type Workspace ¶ added in v0.1.1
Workspace describes a multi-repo or single-repo project workspace.
func DiscoverWorkspace ¶ added in v0.1.1
DiscoverWorkspace scans rootPath for git repositories. If rootPath itself is a git repo, it's included as the primary repo. Additionally, immediate subdirectories that contain .git are discovered. If .brocode/workspace.json exists, its configured repos are loaded.
func (*Workspace) FindRepoForPath ¶ added in v0.1.1
FindRepoForPath returns the matching repository for a given file path.