Documentation
¶
Index ¶
- func AtomicWrite(path string, data []byte) error
- func AtomicWriteExclusive(path string, data []byte) error
- func DeleteDoc(docsDir, filename string) error
- func ExtractSlug(filename string) string
- func FindReferencingDocs(docsDir, filename string) ([]string, error)
- func Marshal(meta domain.DocMeta, body string) ([]byte, error)
- func NormalizeAfter(after string) string
- func QuickHealthCheck(docsDir string) (int, error)
- func ReadDocContent(path string) (string, error)
- func RegenerateIndex(docsDir string) error
- func Unmarshal(data []byte) (domain.DocMeta, string, error)
- func ValidateFilename(filename string) error
- func ValidateMeta(meta domain.DocMeta) error
- type CorpusStore
- type DiagnosticReport
- type FixReport
- type Issue
- type SearchResult
- type WriteResult
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AtomicWrite ¶
AtomicWrite writes data to path via a temp file + rename for crash safety. Sets explicit 0644 permissions on the resulting file. Overwrites if exists.
func AtomicWriteExclusive ¶
AtomicWriteExclusive writes data to path via a temp file + hard link. Unlike AtomicWrite, it fails if path already exists (returns an error where os.IsExist reports true). This avoids the TOCTOU race inherent in Stat-then-Rename patterns.
func DeleteDoc ¶
DeleteDoc removes a document from docsDir and regenerates the README index. Returns an error if the file does not exist or cannot be removed. Index regeneration errors are returned separately (wrapped with context).
func ExtractSlug ¶
ExtractSlug extracts the slug from a filename with pattern {type}-{slug}-{date}.md. Example: "decision-auth-strategy-2026-03-07.md" → "auth-strategy"
func FindReferencingDocs ¶
FindReferencingDocs returns filenames of documents whose `related:` field references the given filename (compared without .md extension).
func NormalizeAfter ¶
NormalizeAfter converts a YYYY-MM date to YYYY-MM-01 for lexicographic comparison. YYYY-MM-DD values pass through unchanged.
func QuickHealthCheck ¶
QuickHealthCheck performs a fast health check on the docs directory. Returns the number of issues found:
- orphan .tmp files (interrupted writes)
- missing or empty README.md index
This is NOT the full diagnostic — see lore doctor (Story 5.1).
func ReadDocContent ¶
ReadDocContent returns the full file content (front matter + body) for display. The path argument is expected to come from SearchResult.Path (produced by SearchDocs), which constructs paths via filepath.Join(dir, entry.Name()) — never from user input.
func RegenerateIndex ¶
RegenerateIndex creates or updates the README.md index in docsDir. It scans all .md files (except README.md), parses their front matter, and generates a sorted table. The result is written atomically.
func ValidateFilename ¶
ValidateFilename rejects path traversal attempts in user-supplied filenames.
func ValidateMeta ¶
ValidateMeta checks that required fields (type, date, status) are present, that type is a recognized DocType constant, and that date is in YYYY-MM-DD format.
Types ¶
type CorpusStore ¶
type CorpusStore struct {
Dir string // path to .lore/docs/
}
CorpusStore implements domain.CorpusReader for the local filesystem.
type DiagnosticReport ¶
type DiagnosticReport struct {
Issues []Issue
DocCount int // number of valid .md documents scanned
Checked int // total number of checks performed
}
DiagnosticReport holds the results of a full corpus health check.
func Diagnose ¶
func Diagnose(docsDir string) (*DiagnosticReport, error)
Diagnose performs a comprehensive health check on the docs directory. It checks for orphan .tmp files, broken references, stale index, stale cache (metadata.json), and invalid front matter.
type FixReport ¶
type FixReport struct {
Fixed int // number of issues successfully fixed
Remaining int // number of issues that still need manual attention
Errors int // number of errors during fix (permission, etc.)
Details []string // descriptions of actions taken
}
FixReport holds the results of automatic repairs.
type Issue ¶
type Issue struct {
Category string // "orphan-tmp", "broken-ref", "stale-index", "stale-cache", "invalid-frontmatter"
File string // file concerned
Detail string // human-readable description
AutoFix bool // repairable automatically?
}
Issue represents a single diagnostic finding.
type SearchResult ¶
type SearchResult struct {
Filename string
Path string
Meta domain.DocMeta
Title string // first # heading from body, fallback: slug from filename
}
SearchResult represents a single search hit from SearchDocs.
func FindDocByCommit ¶
func FindDocByCommit(dir string, commitHash string) (*SearchResult, error)
FindDocByCommit searches for a document whose front matter commit field matches commitHash (strict equality — caller resolves short hashes before calling). Returns nil if no match is found.
func SearchDocs ¶
SearchDocs searches documents matching keyword (case-insensitive) in filename, tags, and body, then applies type and date filters from DocFilter. Returns results sorted by date descending.
type WriteResult ¶
type WriteResult struct {
Filename string // e.g. "decision-auth-strategy-2026-03-07.md"
Path string // e.g. "/path/to/.lore/docs/decision-auth-strategy-2026-03-07.md"
IndexErr error // non-nil if index regeneration failed (non-fatal)
}
WriteResult contains the outcome of a WriteDoc operation.
func WriteDoc ¶
WriteDoc creates a document in the given directory via AtomicWrite. subject is used for the filename slug (e.g., "add JWT middleware" → "add-jwt-middleware"). After writing, it regenerates the README index. Index errors are surfaced in WriteResult.IndexErr but do not cause WriteDoc itself to fail.
Source Files