domain

Documentation

Index

• Constants
• Variables
• func DocTypeNames() []string
• func DocsPath(workDir string) string
• func Slugify(s string) string
• func ValidDocType(t string) bool
• type AIProvider
• type AIStatsAggregate
• type AIUsage
• type AIUsageRecord
• type AIUsageStore
• type CallOptions
• type CodeSignature
• type CommitInfo
• type CommitPattern
• type CommitRecord
• type CommitStore
• type CorpusReader
• type DailyAIStats
• type Decision
• type DocFilter
• type DocIndexEntry
• type DocIndexStore
• type DocMeta
• type DocStatus
• type DocType
• type GitAdapter
• type IOStreams
• type InstallResult
• type LoreStore
• type Option
  • func WithMaxTokens(n int) Option
  • func WithModel(m string) Option
  • func WithSystem(s string) Option
  • func WithTemperature(t float64) Option
  • func WithTimeout(d time.Duration) Option
• type PatternStore
• type ReviewCacheEntry
• type ReviewCacheStore
• type ScopeStatsResult
• type SignatureStore
• type StoreMaintenanceOps
• type UsageTracker

Constants

const (
	// LoreDir is the root directory name for Lore data.
	LoreDir = ".lore"

	// DocsDir is the subdirectory name for documentation files.
	DocsDir = "docs"

	// TemplatesDir is the subdirectory name for project-local templates.
	TemplatesDir = "templates"
)

Directory components within the .lore structure. These are path *segments*, not full paths. Use filepath.Join with a workDir or loreDir to construct full paths.

Variables

var (
	ErrNotFound       = errors.New("not found")
	ErrCorrupted      = errors.New("corrupted")
	ErrAlreadyExists  = errors.New("already exists")
	ErrNotInitialized = errors.New("lore not initialized")
	ErrNotGitRepo     = errors.New("not a git repository")
	ErrNotInteractive = errors.New("not interactive")
	ErrNotImplemented = errors.New("not implemented")
)

Functions

func DocTypeNames

func DocTypeNames() []string

DocTypeNames returns sorted list of valid document type names.

func DocsPath

func DocsPath(workDir string) string

DocsPath returns the path to the docs directory relative to workDir.

func Slugify

func Slugify(s string) string

Slugify converts a string to a URL-friendly slug (display purposes). For filename generation, use storage.slugify which also handles accents and length limits.

func ValidDocType

func ValidDocType(t string) bool

ValidDocType reports whether t is a recognized document type. This is the single source of truth for accepted types.

Types

type AIProvider

type AIProvider interface {
	Complete(ctx context.Context, prompt string, opts ...Option) (string, error)
}

type AIStatsAggregate

type AIStatsAggregate struct {
	TotalCalls     int
	TotalTokensIn  int
	TotalTokensOut int
	TotalCachedIn  int
	TotalCostUSD   float64
	AvgLatencyMS   int
	CacheHitRate   float64
	ByMode         map[string]AIStatsAggregate
}

type AIUsage

type AIUsage struct {
	InputTokens  int
	OutputTokens int
	Model        string
}

AIUsage holds token usage stats from an AI provider call.

type AIUsageRecord

type AIUsageRecord struct {
	Timestamp     time.Time
	Mode          string // polish|review|render|ask|consult|merge
	Provider      string
	Model         string
	TokensIn      int
	TokensOut     int
	CachedIn      int
	CostUSD       float64
	LatencyMS     int
	CommitHash    string
	DocID         string
	PromptVersion int
}

type AIUsageStore

type AIUsageStore interface {
	RecordAIUsage(usage AIUsageRecord) error
	AIStatsSince(since time.Time) (*AIStatsAggregate, error)
	AIStatsByDay(days int) ([]DailyAIStats, error)
}

AIUsageStore handles AI usage recording (Phase 1 — stub).

type CallOptions

type CallOptions struct {
	Model       string
	MaxTokens   int
	Temperature float64
	Timeout     time.Duration
	System      string
}

type CodeSignature

type CodeSignature struct {
	CommitHash string
	FilePath   string
	EntityName string
	EntityType string // func|method|type|struct|interface|class|trait|enum|const_block
	SigHash    string // SHA-256 of normalized body
	Lang       string
	LineStart  int
	ChangeType string // added|deleted|modified|moved|context
}

type CommitInfo

type CommitInfo struct {
	Hash        string
	Author      string
	Date        time.Time
	Message     string
	Type        string
	Scope       string
	Subject     string
	Branch      string // current branch at commit time; "" if detached HEAD
	IsMerge     bool   // true when the commit has more than one parent
	ParentCount int    // number of parent commits (0 for root, 1 for normal, 2+ for merge)
}

type CommitPattern

type CommitPattern struct {
	ConvType         string
	Scope            string
	TotalCount       int
	DocumentedCount  int
	SkippedCount     int
	AutoSkippedCount int
	AvgDiffLines     int
	AvgScore         int
	DocRate          float64 // DocumentedCount / TotalCount
	SkipRate         float64 // SkippedCount / TotalCount
}

type CommitRecord

type CommitRecord struct {
	Hash               string
	Date               time.Time
	Branch             string
	Scope              string
	ConvType           string
	Subject            string
	Message            string
	FilesChanged       int
	LinesAdded         int
	LinesDeleted       int
	DocID              string  // nullable — filename of generated doc
	Decision           string  // documented|skipped|pending|auto-skipped|merge-skipped|unknown
	DecisionScore      int     // nullable — score 0-100
	DecisionConfidence float64 // nullable
	SkipReason         string  // nullable
	QuestionMode       string  // full|reduced|confirm|none
}

CommitRecord is the store-layer view of a commit (what we persist). Not a replacement for CommitInfo which is the git-layer view.

type CommitStore

type CommitStore interface {
	RecordCommit(rec CommitRecord) error
	GetCommit(hash string) (*CommitRecord, error)
	CommitsByScope(scope string, days int) ([]CommitRecord, error)
	CommitsByBranch(branch string) ([]CommitRecord, error)
	CommitsSince(since time.Time) ([]CommitRecord, error)
	UndocumentedCommits() ([]CommitRecord, error)
	CommitCountByDecision() (map[string]int, error)
	ScopeStats(scope string, days int) (ScopeStatsResult, error)
}

CommitStore handles commit recording and querying.

type CorpusReader

type CorpusReader interface {
	ReadDoc(id string) (string, error)
	ListDocs(filter DocFilter) ([]DocMeta, error)
}

type DailyAIStats

type DailyAIStats struct {
	Date      string
	Calls     int
	TokensIn  int
	TokensOut int
	CostUSD   float64
}

type Decision

type Decision = string

Decision represents the outcome of the documentation decision engine.

const (
	DecisionDocumented   Decision = "documented"
	DecisionSkipped      Decision = "skipped"
	DecisionAutoSkipped  Decision = "auto-skipped"
	DecisionMergeSkipped Decision = "merge-skipped"
	DecisionPending      Decision = "pending"
	DecisionUnknown      Decision = "unknown"
)

type DocFilter

type DocFilter struct {
	Type   string
	After  string // YYYY-MM-DD, inclusive
	Before string // YYYY-MM-DD, inclusive
	Tags   []string
	Status string
	Text   string // case-insensitive search in body and filename
	Branch string // filter by branch name
	Scope  string // filter by scope
}

type DocIndexEntry

type DocIndexEntry struct {
	Filename         string
	Type             string
	Date             string
	CommitHash       string
	Branch           string
	Scope            string
	Status           string
	Tags             []string // stored as comma-separated in DB
	Related          []string // stored as comma-separated in DB
	GeneratedBy      string
	AngelaMode       string
	ConsolidatedInto string
	ContentHash      string // SHA-256 of body
	SummaryWhy       string
	SummaryWhat      string
	TitleExtracted   string
	WordCount        int
	UpdatedAt        time.Time
}

DocIndexEntry is the store-layer view of a document's metadata.

type DocIndexStore

type DocIndexStore interface {
	IndexDoc(entry DocIndexEntry) error
	RemoveDoc(filename string) error
	GetDoc(filename string) (*DocIndexEntry, error)
	DocsByScope(scope string) ([]DocIndexEntry, error)
	DocsByBranch(branch string) ([]DocIndexEntry, error)
	DocsByType(docType string) ([]DocIndexEntry, error)
	UnconsolidatedDocs(scope string) ([]DocIndexEntry, error)
	AllDocSummaries(limit int) ([]DocIndexEntry, error)
	DocsByCommitHash(hash string) ([]DocIndexEntry, error)
	SearchDocs(ctx context.Context, query string) ([]DocIndexEntry, error)
	DocCount() (int, error)
}

DocIndexStore handles document index operations.

type DocMeta

type DocMeta struct {
	Type        string   `yaml:"type"`
	Date        string   `yaml:"date"`
	Commit      string   `yaml:"commit,omitempty"`
	Branch      string   `yaml:"branch,omitempty"`
	Scope       string   `yaml:"scope,omitempty"`
	Status      string   `yaml:"status"`
	Tags        []string `yaml:"tags,omitempty"`
	Related     []string `yaml:"related,omitempty"`
	GeneratedBy string   `yaml:"generated_by,omitempty"`
	AngelaMode  string   `yaml:"angela_mode,omitempty"`

	// Synthesized records the signatures of every Example Synthesizer
	// that has produced output for this doc. The map key is
	// the synthesizer Name (e.g. "api-postman"), and the value carries the
	// fields defined by synthesizer.Signature (hash, at, version, sections,
	// evidence_count, warnings).
	//
	// Stored as map[string]map[string]any to keep the domain package free
	// of dependencies on internal/angela. Converted to/from typed
	// synthesizer.Signature inside the synthesizer package.
	Synthesized map[string]map[string]any `yaml:"synthesized,omitempty"`

	Filename string `yaml:"-"` // populated at runtime by ListDocs, not serialized
}

type DocStatus

type DocStatus = string

DocStatus represents the lifecycle state of a document.

const (
	StatusDraft     DocStatus = "draft"
	StatusPublished DocStatus = "published"
	StatusArchived  DocStatus = "archived"
)

type DocType

type DocType = string

DocType represents the category of a document.

const (
	DocTypeDecision DocType = "decision"
	DocTypeFeature  DocType = "feature"
	DocTypeBugfix   DocType = "bugfix"
	DocTypeRefactor DocType = "refactor"
	DocTypeRelease  DocType = "release"
	DocTypeNote     DocType = "note"
	DocTypeSummary  DocType = "summary"
)

Document type constants.

type GitAdapter

type GitAdapter interface {
	Diff(ref string) (string, error)
	Log(ref string) (*CommitInfo, error)

	CommitExists(ref string) (bool, error)
	IsMergeCommit(ref string) (bool, error)

	IsInsideWorkTree() bool

	HeadRef() (string, error)
	// HeadCommit returns the full commit info for HEAD in a single git
	// invocation, replacing separate HeadRef() + Log(ref) calls.
	HeadCommit() (*CommitInfo, error)
	IsRebaseInProgress() (bool, error)

	CommitMessageContains(ref, marker string) (bool, error)

	GitDir() (string, error)

	InstallHook(hookType string) (InstallResult, error)
	UninstallHook(hookType string) error
	HookExists(hookType string) (bool, error)

	CommitRange(from, to string) ([]string, error)
	LatestTag() (string, error)

	LogAll() ([]CommitInfo, error)
	CurrentBranch() (string, error)
}

type IOStreams

type IOStreams struct {
	Out io.Writer
	Err io.Writer
	In  io.Reader
}

type InstallResult

type InstallResult struct {
	Installed     bool   // true if the hook was installed
	HooksPathWarn string // non-empty if core.hooksPath is configured
}

InstallResult describes the outcome of a hook install operation.

type LoreStore

type LoreStore interface {
	CommitStore
	DocIndexStore
	SignatureStore
	AIUsageStore
	ReviewCacheStore
	PatternStore
	StoreMaintenanceOps
}

LoreStore is the composed interface for the full store. Consumers that only need a subset should accept the focused interface (CommitStore, DocIndexStore, etc.) instead of LoreStore.

type Option

type Option func(*CallOptions)

func WithMaxTokens

func WithMaxTokens(n int) Option

func WithModel

func WithModel(m string) Option

func WithSystem

func WithSystem(s string) Option

func WithTemperature

func WithTemperature(t float64) Option

func WithTimeout

func WithTimeout(d time.Duration) Option

type PatternStore

type PatternStore interface {
	UpdatePattern(convType, scope string, decision string, diffLines, score int) error
	GetPattern(convType, scope string) (*CommitPattern, error)
	AllPatterns() ([]CommitPattern, error)
}

PatternStore handles commit pattern tracking (Phase 2 — stub).

type ReviewCacheEntry

type ReviewCacheEntry struct {
	ReviewDate   time.Time
	CorpusHash   string
	CorpusCount  int
	FindingsJSON string
	TokensIn     int
	TokensOut    int
	Provider     string
	Model        string
}

type ReviewCacheStore

type ReviewCacheStore interface {
	CacheReview(report ReviewCacheEntry) error
	GetCachedReview(corpusHash string) (*ReviewCacheEntry, error)
	ReviewHistory(limit int) ([]ReviewCacheEntry, error)
}

ReviewCacheStore handles review caching (Phase 1 — stub).

type ScopeStatsResult

type ScopeStatsResult struct {
	TotalCommits    int
	DocumentedCount int
	SkippedCount    int
	LastDocDate     int64
	LastCommitDate  int64
}

ScopeStatsResult holds aggregated statistics for a scope, computed via SQL instead of loading all records into memory.

type SignatureStore

type SignatureStore interface {
	StoreSignatures(commitHash string, sigs []CodeSignature) error
	FindBySignatureHash(sigHash string) ([]CodeSignature, error)
	SignaturesForCommit(commitHash string) ([]CodeSignature, error)
	EntityHistory(entityName, lang string) ([]CodeSignature, error)
}

SignatureStore handles code signature tracking (Phase 1 — stub).

type StoreMaintenanceOps

type StoreMaintenanceOps interface {
	Rebuild(ctx context.Context, docsDir string, git GitAdapter) error
	Vacuum() error
	Close() error
}

StoreMaintenanceOps handles store lifecycle operations.

type UsageTracker

type UsageTracker interface {
	LastUsage() *AIUsage
}

UsageTracker is optionally implemented by AIProviders that can report token usage.