index

Documentation

Overview

Package index builds an air-gapped, model-free repo map: a ranked, token- budgeted skeleton of a codebase (definition signatures) so a small local model can call real symbols without loading whole files (INDEX-001, Aider's repo-map approach). Go is parsed with go/ast; other first-class languages via the pure-Go ctags-style extractor (INDEX-009/010) — no CGO, no network. Ranking is personalized PageRank over a def/ref file graph (AST edges for Go, text edges for the rest), seeded by the task's mentioned identifiers.

Index

• Constants
• func AssembleContext(root string, mentions []string, budget int) string
• func Build(opts Options) (string, error)
• func ChangedSince(prev, cur Snapshot) (changed, removed []string)
• func FirstClassLanguages() []string
• func GuardRetrieval(method string) error
• func IsFirstClass(lang string) bool
• func LangFromPath(path string) string
• func NormalizeLang(lang string) string
• func StructuralLanguages() []string
• type Capabilities
  • func DefaultCapabilities() Capabilities
• type Options
• type Snapshot
  • func SnapshotDir(root string) Snapshot
• type Symbol
  • func ExtractSymbols(lang, content string) []Symbol
• type Tier
  • func RetrievalTier(lang string, caps Capabilities) Tier
  • func (t Tier) String() string

Constants

const RetrievalDoctrine = "grep-first: grep/glob/LSP/repo-map; never embeddings"

RetrievalDoctrine documents aegis's air-gap retrieval doctrine (INDEX-003): the default and only sanctioned retrieval is grep/glob/LSP/repo-map — never an embeddings/vector engine, which needs a hosted or heavy local model and adds latency a small CPU-bound model can't afford. A Jan-2026 benchmark also shows deterministic AST-derived retrieval is ~20x cheaper and more complete.

Functions

func AssembleContext

func AssembleContext(root string, mentions []string, budget int) string

AssembleContext builds a bounded context bundle for a task (INDEX-005): the repo-map skeleton (breadth) followed by the bodies of the files relevant to the task's mentions, ranked to fit a char budget — repo map first (half the budget), then file bodies until the budget is spent. Model-free and grep-first (INDEX-003); SCIP-precise def selection (INDEX-002) is an optional future enhancement to which files are pulled, not a prerequisite.

func Build

func Build(opts Options) (string, error)

Build scans Root's Go sources and returns a ranked, budget-bounded repo map.

func ChangedSince

func ChangedSince(prev, cur Snapshot) (changed, removed []string)

ChangedSince returns the paths added or modified vs prev (changed) and the paths deleted (removed), so incremental re-indexing processes only what changed (INDEX-004). The tree-sitter edit() re-parse + file watcher are the CGO/OS follow-on; this is the model-free change-detection core.

func FirstClassLanguages

func FirstClassLanguages() []string

FirstClassLanguages returns aegis's first-class retrieval set (INDEX-008).

func GuardRetrieval

func GuardRetrieval(method string) error

GuardRetrieval returns an error if method is not a sanctioned grep-first retrieval (i.e. it is an embeddings/vector/RAG engine), enforcing the air-gap doctrine (INDEX-003).

func IsFirstClass

func IsFirstClass(lang string) bool

IsFirstClass reports whether a language is in aegis's first-class set; anything else degrades to the grep floor (INDEX-008 / INDEX-007).

func LangFromPath

func LangFromPath(path string) string

LangFromPath returns the canonical language id for a file path ("" if unknown).

func NormalizeLang

func NormalizeLang(lang string) string

NormalizeLang maps a language name/alias/extension to its canonical id.

func StructuralLanguages

func StructuralLanguages() []string

StructuralLanguages returns the languages the pure-Go extractor covers (INDEX-009).

Types

type Capabilities

type Capabilities struct {
	Precise    map[string]bool
	Structural map[string]bool
}

Capabilities declares which languages have a bundled precise server (LSP/SCIP) and which have an embedded structural grammar, so the ladder picks a tier from what is actually shipped — never assuming coverage that isn't bundled. Populated per the INDEX-008 parity rule (first-class languages only).

func DefaultCapabilities

func DefaultCapabilities() Capabilities

DefaultCapabilities reports what aegis ships TODAY: Go via go/ast plus the INDEX-009 pure-Go ctags-style extractor give every first-class language a structural tier; no precise servers are bundled yet (LSP/SCIP deferred), so the precise tier is currently empty.

type Options

type Options struct {
	Root        string   // repo root to scan
	Mentions    []string // task identifiers/paths that personalize ranking (boost relevant files)
	TokenBudget int      // approximate character budget for the rendered map (default 4000)
}

Options configures Build.

type Snapshot

type Snapshot map[string]string

Snapshot maps a repo-relative path to its content hash — a Merkle leaf per file (INDEX-004). Comparing two snapshots yields exactly the files that changed, so re-indexing touches only those, not the whole tree.

func SnapshotDir

func SnapshotDir(root string) Snapshot

SnapshotDir hashes root's source files into a Snapshot (INDEX-004), reusing the same file set the repo map indexes.

type Symbol

type Symbol struct {
	Name string
	Sig  string // one-line elided signature
}

Symbol is a renderable top-level definition.

func ExtractSymbols

func ExtractSymbols(lang, content string) []Symbol

ExtractSymbols returns top-level definition symbols for a source file's content in the given language (INDEX-009). Returns nil for a language without patterns — the caller then degrades to the grep tier (INDEX-007).

type Tier

type Tier int

Tier is a retrieval capability level (INDEX-007). Higher = more precise.

const (
	// TierGrep is the universal text floor (INDEX-003) — any language, always.
	TierGrep Tier = iota
	// TierStructural is a def/ref skeleton (go/ast today; tree-sitter/WASM once
	// INDEX-001-P01 lands).
	TierStructural
	// TierPrecise is compiler-grade go-to-def / find-refs (LSP / SCIP).
	TierPrecise
)

func RetrievalTier

func RetrievalTier(lang string, caps Capabilities) Tier

RetrievalTier returns the best available tier for a language, never below Grep (INDEX-007). An unknown or unsupported language resolves to Grep — never an error — so development in an unindexed language still works, at the text floor.

func (Tier) String

func (t Tier) String() string

String renders the tier so the active retrieval level is observable, never a silent downgrade (INDEX-007).