index

Documentation

Index

• Constants
• func ComputeAvgFieldLen(entries []Entry) float64
• func ComputeIDF(entries []Entry) map[string]float64
• func IndexPath() (string, error)
• func NeedsRebuild(cached Index, sourceDirs []string) bool
• func Save(idx Index) error
• func SourceDirs() ([]string, error)
• type Entry
• type EntryType
• type Frontmatter
  • func ParseFrontmatter(content []byte) (Frontmatter, error)
• type Index
  • func ForceRebuild(sourceDirs []string) (Index, error)
  • func Load() (Index, error)
  • func LoadOrRebuild(sourceDirs []string) (Index, time.Duration, error)
• type ScanResult
  • func Scan(sourceDirs []string) (ScanResult, error)

Constants

const CurrentVersion = 9

CurrentVersion is the index schema version; bump when Entry shape changes.

Functions

func ComputeAvgFieldLen

func ComputeAvgFieldLen(entries []Entry) float64

ComputeAvgFieldLen returns the average number of keywords per entry. Used as the avgdl denominator in BM25 length normalization.

func ComputeIDF

func ComputeIDF(entries []Entry) map[string]float64

ComputeIDF calculates dampened inverse document frequency for all keywords. Returns a multiplier ranging from 0.5 (ubiquitous) to 2.0 (unique).

func IndexPath

func IndexPath() (string, error)

IndexPath returns ~/.config/claudette/index.json.

func NeedsRebuild

func NeedsRebuild(cached Index, sourceDirs []string) bool

NeedsRebuild checks whether the cached index is stale relative to source dirs. It also accounts for changes to ~/.config/claudette/aliases.yaml — both modification (mtime change) and deletion/creation (zero-vs-nonzero mtime).

func Save

func Save(idx Index) error

Save writes the index atomically using temp-file-then-rename.

func SourceDirs

func SourceDirs() ([]string, error)

SourceDirs returns the directories to scan, combining user-configured source_dirs (from config.json) with defaults and plugin directories.

Types

type Entry

type Entry struct {
	Type             EntryType      `json:"type"`
	Name             string         `json:"name"`
	Title            string         `json:"title"`
	Desc             string         `json:"desc,omitzero"` // one-liner from frontmatter description
	Category         string         `json:"category"`
	FilePath         string         `json:"file_path"`
	FileMtime        time.Time      `json:"file_mtime"`                  // mtime of the source .md file at scan time
	Keywords         map[string]int `json:"keywords"`                    // word -> field weight (name=3, title=2, tag=2, desc=1)
	Bigrams          []string       `json:"bigrams,omitzero"`            // consecutive word pairs from title
	HitCount         int            `json:"hit_count,omitzero"`          // raw aggregated usage count (diagnostics only)
	HitCountDecayed  float64        `json:"hit_count_decayed,omitempty"` // exponentially-decayed hit count (scorer uses this)
	SuggestedAliases []string       `json:"suggested_aliases,omitempty"` // co-occurrence-derived alias candidates (populated at rebuild; scored at weight 1)
}

Entry is a single searchable item in the index.

type EntryType

type EntryType string

EntryType identifies the source of a searchable entry.

const (
	TypeKB      EntryType = "kb"
	TypeSkill   EntryType = "skill"
	TypeAgent   EntryType = "agent"
	TypeCommand EntryType = "command"
)

type Frontmatter

type Frontmatter struct {
	Name        string   `yaml:"name"`
	Description string   `yaml:"description"`
	Tags        []string `yaml:"tags"`
	Aliases     []string `yaml:"aliases"`
}

Frontmatter holds parsed YAML header from component .md files.

func ParseFrontmatter

func ParseFrontmatter(content []byte) (Frontmatter, error)

ParseFrontmatter extracts YAML between --- delimiters. Returns zero Frontmatter if no valid frontmatter found.

type Index

type Index struct {
	Version             int                `json:"version"`
	BuildTime           time.Time          `json:"build_time"`
	SourceMtime         time.Time          `json:"source_mtime"`
	FileCount           int                `json:"file_count"`
	AliasesMtime        time.Time          `json:"aliases_mtime,omitzero"`         // mtime of aliases.yaml at build time (zero if absent)
	ZeroKeywordCount    int                `json:"zero_keyword_count,omitzero"`    // entries with no keywords after parse (authoring signal)
	ColdEntryCount      int                `json:"cold_entry_count,omitzero"`      // entries never hit, >90d old, not brand-new (>7d old)
	FrequentMissTokens  []string           `json:"frequent_miss_tokens,omitempty"` // top missed tokens above threshold; empty when below
	SuggestedAliasCount int                `json:"suggested_alias_count,omitzero"` // entries with alias candidates pending review
	Entries             []Entry            `json:"entries"`
	IDF                 map[string]float64 `json:"idf,omitzero"`  // inverse document frequency per keyword
	AvgFieldLen         float64            `json:"avg_field_len"` // average number of keywords per entry (for BM25)
}

Index is the on-disk cache of all scanned entries.

func ForceRebuild

func ForceRebuild(sourceDirs []string) (Index, error)

ForceRebuild scans, builds, and persists a fresh index unconditionally.

func Load

func Load() (Index, error)

Load reads the index from disk. Returns os.ErrNotExist if missing.

func LoadOrRebuild

func LoadOrRebuild(sourceDirs []string) (Index, time.Duration, error)

LoadOrRebuild loads the index and rebuilds it if stale. Returns the elapsed rebuild duration when a rebuild happened; 0 on cache hit.

type ScanResult

type ScanResult struct {
	Entries   []Entry
	MaxMtime  time.Time
	FileCount int
}

ScanResult holds the output of a directory scan.

func Scan

func Scan(sourceDirs []string) (ScanResult, error)

Scan walks all source directories and builds entries.