loader

package
v0.13.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 13, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Overview

Package loader provides issue loading and file discovery utilities. This file handles automatic .gitignore management for the .bv directory.

Index

Constants

View Source 
const BeadsDirEnvVar = "BEADS_DIR"

BeadsDirEnvVar is the name of the environment variable for custom beads directory

View Source 
const DefaultMaxBufferSize = 1024 * 1024 * 10

DefaultMaxBufferSize is the default buffer size for the scanner (10MB).

View Source 
const SprintsFileName = "sprints.jsonl"

SprintsFileName is the canonical filename for sprint storage.

Variables

View Source 
var IssuePool = sync.Pool{
	New: func() any {
		issuePoolNews.Add(1)
		return &model.Issue{
			Dependencies: make([]*model.Dependency, 0, defaultDepsCap),
			Comments:     make([]*model.Comment, 0, defaultCommentsCap),
			Labels:       make([]string, 0, defaultLabelsCap),
		}
	},
}

IssuePool manages reusable Issue structs. Only return issues when they are no longer referenced by any snapshot.

View Source 
var PreferredJSONLNames = []string{"issues.jsonl", "beads.jsonl", "beads.base.jsonl"}

PreferredJSONLNames defines the priority order for looking up beads data files.

Functions

func EnsureBVInGitignore added in v0.10.3 

func EnsureBVInGitignore(projectDir string) error

EnsureBVInGitignore ensures that .bv/ is listed in the project's .gitignore file. This prevents bv-specific files (semantic search index, baselines, drift config, etc.) from polluting the git repository.

The function is idempotent and safe to call multiple times. It will:

  • Create .gitignore if it doesn't exist
  • Add ".bv/" if it's not already present (checks for .bv, .bv/, .bv/*, etc.)
  • Preserve existing file content and formatting

Returns nil on success, or an error if the file cannot be read/written.

func FindJSONLPath 

func FindJSONLPath(beadsDir string) (string, error)

FindJSONLPath locates the beads JSONL file in the given directory. Prefers issues.jsonl (canonical per beads upstream) over beads.jsonl (backward compat). Skips backup files and merge artifacts.

func FindJSONLPathWithWarnings added in v0.10.3 

func FindJSONLPathWithWarnings(beadsDir string, warnFunc func(msg string)) (string, error)

FindJSONLPathWithWarnings is like FindJSONLPath but optionally reports warnings about detected merge artifacts via the provided callback.

func GetBeadsDir added in v0.10.3 

func GetBeadsDir(repoPath string) (string, error)

GetBeadsDir returns the beads directory path, respecting BEADS_DIR env var. If BEADS_DIR is set, it is used directly. Otherwise, falls back to .beads in the given repoPath (or cwd if empty).

func GetIssue added in v0.13.0 

func GetIssue() *model.Issue

GetIssue retrieves an Issue from the pool and resets it.

func IssuePoolStats added in v0.13.0 

func IssuePoolStats() (hits uint64, misses uint64)

IssuePoolStats returns the total pool hits and misses since process start.

func LoadIssues 

func LoadIssues(repoPath string) ([]model.Issue, error)

LoadIssues reads issues from the beads directory. Respects BEADS_DIR environment variable, otherwise uses .beads in repoPath. Automatically finds the correct JSONL file (issues.jsonl preferred, beads.jsonl fallback).

func LoadIssuesFromFile 

func LoadIssuesFromFile(path string) ([]model.Issue, error)

LoadIssuesFromFile reads issues directly from a specific JSONL file path.

func LoadIssuesFromFileWithOptions added in v0.10.3 

func LoadIssuesFromFileWithOptions(path string, opts ParseOptions) ([]model.Issue, error)

LoadIssuesFromFileWithOptions reads issues from a file with custom options.

func LoadSprints added in v0.10.3 

func LoadSprints(repoPath string) ([]model.Sprint, error)

LoadSprints reads sprints from .beads/sprints.jsonl under repoPath. Missing file is treated as "no sprints" (empty slice, nil error).

func LoadSprintsFromFile added in v0.10.3 

func LoadSprintsFromFile(path string) ([]model.Sprint, error)

LoadSprintsFromFile reads sprints directly from a specific JSONL file path. Missing file is treated as "no sprints" (empty slice, nil error).

func ParseIssues added in v0.10.3 

func ParseIssues(r io.Reader) ([]model.Issue, error)

ParseIssues parses JSONL content from a reader into issues. Handles UTF-8 BOM stripping, large lines, and validation.

func ParseIssuesWithOptions added in v0.10.3 

func ParseIssuesWithOptions(r io.Reader, opts ParseOptions) ([]model.Issue, error)

ParseIssuesWithOptions parses JSONL content with custom options.

func ParseSprints added in v0.10.3 

func ParseSprints(r io.Reader) ([]model.Sprint, error)

ParseSprints parses JSONL content from a reader into sprints. Malformed or invalid sprints are skipped with warnings written to stderr, consistent with ParseIssues behavior (suppressed in robot mode).

func PutIssue added in v0.13.0 

func PutIssue(issue *model.Issue)

PutIssue returns an Issue to the pool for reuse. After this call, the issue must not be used.

func ReturnIssuePtrsToPool added in v0.13.0 

func ReturnIssuePtrsToPool(issues []*model.Issue)

ReturnIssuePtrsToPool returns a slice of pooled issue pointers to the pool. Use this when a snapshot is replaced and no longer referenced.

func SaveSprints added in v0.10.3 

func SaveSprints(repoPath string, sprints []model.Sprint) error

SaveSprints writes sprints to .beads/sprints.jsonl under repoPath.

func SaveSprintsToFile added in v0.10.3 

func SaveSprintsToFile(path string, sprints []model.Sprint) error

SaveSprintsToFile writes sprints to a specific file path. The write is atomic (temp file + rename) to be safe with editors and watchers.

Types

type CacheStats 

type CacheStats struct {
	TotalEntries int           `json:"total_entries"`
	ValidEntries int           `json:"valid_entries"`
	MaxAge       time.Duration `json:"max_age"`
}

CacheStats holds cache statistics

type GitLoader 

type GitLoader struct {
	// contains filtered or unexported fields
}

GitLoader loads beads from git history

func NewGitLoader 

func NewGitLoader(repoPath string) *GitLoader

NewGitLoader creates a new git history loader for the given repo

func NewGitLoaderWithCacheTTL 

func NewGitLoaderWithCacheTTL(repoPath string, cacheTTL time.Duration) *GitLoader

NewGitLoaderWithCacheTTL creates a loader with custom cache TTL

func (*GitLoader) CacheStats 

func (g *GitLoader) CacheStats() CacheStats

CacheStats returns cache statistics

func (*GitLoader) ClearCache 

func (g *GitLoader) ClearCache()

ClearCache removes all cached entries

func (*GitLoader) GetCommitsBetween 

func (g *GitLoader) GetCommitsBetween(fromRev, toRev string) ([]RevisionInfo, error)

GetCommitsBetween returns commits between two revisions

func (*GitLoader) HasBeadsAtRevision 

func (g *GitLoader) HasBeadsAtRevision(revision string) (bool, error)

HasBeadsAtRevision checks if beads files exist at a given revision

func (*GitLoader) ListRevisions 

func (g *GitLoader) ListRevisions(limit int) ([]RevisionInfo, error)

ListRevisions returns commits that modified beads files

func (*GitLoader) LoadAt 

func (g *GitLoader) LoadAt(revision string) ([]model.Issue, error)

LoadAt loads issues from a specific git revision revision can be: SHA, branch name, tag name, HEAD~N, or date expression

func (*GitLoader) LoadAtDate 

func (g *GitLoader) LoadAtDate(t time.Time) ([]model.Issue, error)

LoadAtDate loads issues from the state at a specific date/time Uses git rev-list to find the commit at or before the given time

func (*GitLoader) ResolveRevision 

func (g *GitLoader) ResolveRevision(revision string) (string, error)

ResolveRevision resolves any git revision to its commit SHA

type ParseOptions added in v0.10.3 

type ParseOptions struct {
	// WarningHandler is called with warning messages (e.g., malformed JSON).
	// If nil, warnings are printed to os.Stderr.
	WarningHandler func(string)

	// BufferSize sets the maximum line size (in bytes) to read at once.
	// Lines longer than this are skipped with a warning.
	// If 0, uses DefaultMaxBufferSize (10MB).
	BufferSize int

	// IssueFilter optionally filters parsed issues. Return true to include.
	// When nil, all valid issues are included.
	IssueFilter func(*model.Issue) bool
}

ParseOptions configures the behavior of ParseIssues.

type PooledIssues added in v0.13.0 

type PooledIssues struct {
	Issues   []model.Issue
	PoolRefs []*model.Issue
}

PooledIssues bundles parsed issues with their pooled backing objects. The pooled references must be returned via ReturnIssuePtrsToPool when the snapshot is no longer used.

func LoadIssuesFromFilePooled added in v0.13.0 

func LoadIssuesFromFilePooled(path string) (PooledIssues, error)

LoadIssuesFromFilePooled reads issues directly from a JSONL file path with pooling enabled.

func LoadIssuesFromFileWithOptionsPooled added in v0.13.0 

func LoadIssuesFromFileWithOptionsPooled(path string, opts ParseOptions) (PooledIssues, error)

LoadIssuesFromFileWithOptionsPooled reads issues from a file with pooling enabled. The caller must return pooled issues via ReturnIssuePtrsToPool when no longer needed.

func ParseIssuesWithOptionsPooled added in v0.13.0 

func ParseIssuesWithOptionsPooled(r io.Reader, opts ParseOptions) (PooledIssues, error)

ParseIssuesWithOptionsPooled parses JSONL content with pooling enabled. The caller must return pooled issues via ReturnIssuePtrsToPool when no longer needed.

type RevisionInfo 

type RevisionInfo struct {
	SHA       string    `json:"sha"`
	Timestamp time.Time `json:"timestamp"`
	Message   string    `json:"message"`
}

RevisionInfo describes a git commit

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.