storage

package
v0.2.5 Latest Latest
Warning

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

 Go to latest Published: Aug 28, 2026 License: Apache-2.0 Imports: 16 Imported by: 0

Documentation

Overview

CANARY: REQ=CBIN-146; FEATURE="ContextManagement"; ASPECT=Engine; STATUS=IMPL; UPDATED=2025-10-18

CANARY: REQ=CBIN-129; FEATURE="DatabaseMigrations"; ASPECT=Storage; STATUS=IMPL; OWNER=canary; UPDATED=2025-10-16

CANARY: REQ=CBIN-140; FEATURE="GapRepository"; ASPECT=Storage; STATUS=IMPL; UPDATED=2025-10-17

CANARY: REQ=CBIN-146; FEATURE="DatabaseModes"; ASPECT=Storage; STATUS=IMPL; UPDATED=2025-10-18

CANARY: REQ=CBIN-146; FEATURE="ProjectRegistry"; ASPECT=Storage; STATUS=IMPL; UPDATED=2025-10-18

CANARY: REQ=CBIN-123; FEATURE="TokenStorage"; ASPECT=Storage; STATUS=IMPL; OWNER=canary; UPDATED=2025-10-16

Index

Constants

View Source 
const (
	DBDriver        = "sqlite"
	DBMigrationPath = "migrations"
	DBSourceName    = "iofs"
	DBURLProtocol   = "sqlite://"
	MigrateAll      = "all"
	LatestVersion   = 6 // Update this when adding new migrations
)
View Source 
const DefaultSearchLimit = 25

DefaultSearchLimit caps keyword searches to protect agent context. Deliberately small; callers raise it explicitly (--limit / limit param) when they need more.

Variables

View Source 
var ErrDatabaseNotPopulated = errors.New("database not migrated")

Functions

func AutoMigrate 

func AutoMigrate(dbPath string) error

AutoMigrate automatically migrates the database if needed

func DatabasePopulated 

func DatabasePopulated(db *sqlx.DB, targetVersion int) (bool, error)

DatabasePopulated checks if the database is fully migrated and populated We only return an error here if we're getting database issues. Bool return should reflect the state of the database.

func InitDB 

func InitDB(dbPath string) (*sqlx.DB, error)

InitDB initializes the database connection

func MigrateDB 

func MigrateDB(dbPath string, steps string) error

MigrateDB applies the database migrations stored in migrations/*.sql It takes a single argument which is either "all" to migrate to the latest version or an integer to migrate by that many steps.

func NeedsMigration 

func NeedsMigration(dbPath string) (bool, int, error)

NeedsMigration checks if the database exists and needs migration

func TeardownDB 

func TeardownDB(dbPath string, steps string) error

TeardownDB is the negative inverse of MigrateDB, rolling back migrations It takes a single argument which is either "all" to roll back all migrations or an integer to roll back by that many steps.

Types

type Checkpoint 

type Checkpoint struct {
	ID           int
	Name         string
	Description  string
	CommitHash   string
	CreatedAt    string
	TotalTokens  int
	StubCount    int
	ImplCount    int
	TestedCount  int
	BenchedCount int
	SnapshotJSON string
}

Checkpoint represents a state snapshot

type ContextManager 

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

ContextManager manages the current project context

func NewContextManager 

func NewContextManager(manager *DatabaseManager) *ContextManager

NewContextManager creates a new context manager

func (*ContextManager) DetectProject 

func (cm *ContextManager) DetectProject() (*Project, error)

DetectProject attempts to detect the current project from the working directory

func (*ContextManager) GetCurrent 

func (cm *ContextManager) GetCurrent() (*Project, error)

GetCurrent returns the currently active project

func (*ContextManager) SwitchTo 

func (cm *ContextManager) SwitchTo(projectID string) error

SwitchTo switches the current project context to the specified project ID

type DB 

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

DB wraps the SQLite database connection

func Open 

func Open(dbPath string) (*DB, error)

Open opens or creates the CANARY database Note: Migrations are handled automatically by the CLI's PersistentPreRunE

func (*DB) Close 

func (db *DB) Close() error

Close closes the database connection

func (*DB) CreateCheckpoint 

func (db *DB) CreateCheckpoint(name, description, commitHash, snapshotJSON string) error

CreateCheckpoint creates a state snapshot

func (*DB) GetAllTokens 

func (db *DB) GetAllTokens() ([]*Token, error)

GetAllTokens retrieves all tokens across all projects

func (*DB) GetCheckpoints 

func (db *DB) GetCheckpoints() ([]*Checkpoint, error)

GetCheckpoints retrieves all checkpoints

func (*DB) GetFilesByReqID 

func (db *DB) GetFilesByReqID(reqID string, excludeSpecs bool) (map[string][]*Token, error)

CANARY: REQ=CBIN-CLI-001; FEATURE="QueryAbstraction"; ASPECT=Storage; STATUS=TESTED; TEST=TestCANARY_CBIN_CLI_001_Storage_GetFilesByReqID; UPDATED=2025-10-16 GetFilesByReqID groups tokens by file path for a requirement

func (*DB) GetRefsByReqID 

func (db *DB) GetRefsByReqID(reqID string) ([]*Ref, error)

GetRefsByReqID returns refs for one requirement, ordered by file then line.

func (*DB) GetTokensByProject 

func (db *DB) GetTokensByProject(projectID string) ([]*Token, error)

CANARY: REQ=CBIN-146; FEATURE="TokenNamespacing"; ASPECT=Storage; STATUS=IMPL; UPDATED=2025-10-18 GetTokensByProject retrieves all tokens for a specific project

func (*DB) GetTokensByReqID 

func (db *DB) GetTokensByReqID(reqID string) ([]*Token, error)

GetTokensByReqID retrieves all tokens for a requirement

func (*DB) GetTokensByReqIDAndProject 

func (db *DB) GetTokensByReqIDAndProject(reqID, projectID string) ([]*Token, error)

GetTokensByReqIDAndProject retrieves tokens for a requirement within a specific project

func (*DB) ListTokens 

func (db *DB) ListTokens(filters map[string]string, idPattern string, orderBy string, limit int) ([]*Token, error)

CANARY: REQ=CBIN-145; FEATURE="PriorityFiltering"; ASPECT=Storage; STATUS=IMPL; UPDATED=2025-10-17 ListTokens retrieves tokens with filters and ordering idPattern is a regex pattern for filtering requirement IDs (e.g., "CBIN-[1-9][0-9]{2,}")

func (*DB) ReplaceRefs 

func (db *DB) ReplaceRefs(kind string, refs []Ref) error

ReplaceRefs atomically replaces all refs of the given kind.

func (*DB) SearchTokens 

func (db *DB) SearchTokens(keywords string, limit int) ([]*Token, error)

CANARY: REQ=CBIN-205; FEATURE="ContextCaps"; ASPECT=Storage; STATUS=TESTED; TEST=TestCANARY_CBIN_205_SearchTokensLimit; UPDATED=2026-08-28 SearchTokens searches by keywords across keyword tags, feature names, requirement IDs, file paths, test names, and bench names, bounded by limit (or DefaultSearchLimit when limit <= 0).

func (*DB) UpdatePriority 

func (db *DB) UpdatePriority(reqID, feature string, priority int) error

UpdatePriority updates the priority of a token

func (*DB) UpdateSpecStatus 

func (db *DB) UpdateSpecStatus(reqID, specStatus string) error

UpdateSpecStatus updates the spec status

func (*DB) UpsertToken 

func (db *DB) UpsertToken(token *Token) error

UpsertToken inserts or updates a token

type DatabaseManager 

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

DatabaseManager manages both global and local database connections

func NewDatabaseManager 

func NewDatabaseManager() *DatabaseManager

NewDatabaseManager creates a new database manager

func (*DatabaseManager) Close 

func (dm *DatabaseManager) Close() error

Close closes the database connection

func (*DatabaseManager) DB 

func (dm *DatabaseManager) DB() *sql.DB

DB returns the underlying database connection

func (*DatabaseManager) Discover 

func (dm *DatabaseManager) Discover() error

Discover attempts to find an existing database, with local taking precedence over global

func (*DatabaseManager) Initialize 

func (dm *DatabaseManager) Initialize(mode DatabaseMode) error

Initialize initializes the database in the specified mode

func (*DatabaseManager) Location 

func (dm *DatabaseManager) Location() string

Location returns the database file path

func (*DatabaseManager) Mode 

func (dm *DatabaseManager) Mode() DatabaseMode

Mode returns the current database mode

type DatabaseMode 

type DatabaseMode int

DatabaseMode represents the initialization mode for the database 

const (
	GlobalMode DatabaseMode = iota
	LocalMode
)

func (DatabaseMode) String 

func (dm DatabaseMode) String() string

String returns the string representation of DatabaseMode

type GapCategory 

type GapCategory struct {
	ID          int
	Name        string
	Description string
	CreatedAt   time.Time
}

GapCategory represents a gap category

type GapConfig 

type GapConfig struct {
	ID                  int
	MaxGapInjection     int
	MinHelpfulThreshold int
	RankingStrategy     string
	CreatedAt           time.Time
	UpdatedAt           time.Time
}

GapConfig represents gap analysis configuration

type GapEntry 

type GapEntry struct {
	ID               int
	GapID            string
	ReqID            string
	Feature          string
	Aspect           string
	Category         string
	Description      string
	CorrectiveAction string
	CreatedAt        time.Time
	CreatedBy        string
	HelpfulCount     int
	UnhelpfulCount   int
}

GapEntry represents a gap analysis entry

type GapQueryFilter 

type GapQueryFilter struct {
	ReqID    string
	Feature  string
	Aspect   string
	Category string
	Limit    int
}

GapQueryFilter represents query filters for gap entries

type GapRepository 

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

GapRepository handles gap analysis database operations

func NewGapRepository 

func NewGapRepository(db *DB) *GapRepository

NewGapRepository creates a new gap repository

func (*GapRepository) CreateEntry 

func (r *GapRepository) CreateEntry(entry *GapEntry) error

CreateEntry creates a new gap analysis entry

func (*GapRepository) GenerateGapReport 

func (r *GapRepository) GenerateGapReport(reqID string) (string, error)

GenerateGapReport generates a formatted gap analysis report

func (*GapRepository) GetCategories 

func (r *GapRepository) GetCategories() ([]*GapCategory, error)

GetCategories retrieves all gap categories

func (*GapRepository) GetConfig 

func (r *GapRepository) GetConfig() (*GapConfig, error)

GetConfig retrieves the gap analysis configuration

func (*GapRepository) GetEntriesByReqID 

func (r *GapRepository) GetEntriesByReqID(reqID string) ([]*GapEntry, error)

GetEntriesByReqID retrieves all gap entries for a requirement

func (*GapRepository) GetEntryByGapID 

func (r *GapRepository) GetEntryByGapID(gapID string) (*GapEntry, error)

GetEntryByGapID retrieves a gap entry by its gap ID

func (*GapRepository) GetTopGaps 

func (r *GapRepository) GetTopGaps(reqID string, config *GapConfig) ([]*GapEntry, error)

GetTopGaps retrieves top gaps for a requirement based on configuration

func (*GapRepository) MarkHelpful 

func (r *GapRepository) MarkHelpful(gapID string) error

MarkHelpful increments the helpful count for a gap entry

func (*GapRepository) MarkUnhelpful 

func (r *GapRepository) MarkUnhelpful(gapID string) error

MarkUnhelpful increments the unhelpful count for a gap entry

func (*GapRepository) QueryEntries 

func (r *GapRepository) QueryEntries(filter GapQueryFilter) ([]*GapEntry, error)

QueryEntries queries gap entries with filters

func (*GapRepository) UpdateConfig 

func (r *GapRepository) UpdateConfig(config *GapConfig) error

UpdateConfig updates the gap analysis configuration

type Project 

type Project struct {
	ID        string
	Name      string
	Path      string
	Active    bool
	CreatedAt string
	Metadata  string // JSON metadata
}

Project represents a registered project in the canary system

type ProjectRegistry 

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

ProjectRegistry manages project registration and queries

func NewProjectRegistry 

func NewProjectRegistry(manager *DatabaseManager) *ProjectRegistry

NewProjectRegistry creates a new project registry

func (*ProjectRegistry) GetByID 

func (pr *ProjectRegistry) GetByID(id string) (*Project, error)

GetByID retrieves a project by its ID

func (*ProjectRegistry) GetByPath 

func (pr *ProjectRegistry) GetByPath(path string) (*Project, error)

GetByPath retrieves a project by its path

func (*ProjectRegistry) List 

func (pr *ProjectRegistry) List() ([]*Project, error)

List returns all registered projects

func (*ProjectRegistry) Register 

func (pr *ProjectRegistry) Register(project *Project) error

Register adds a new project to the registry

func (*ProjectRegistry) Remove 

func (pr *ProjectRegistry) Remove(id string) error

Remove deletes a project from the registry

type Ref 

type Ref struct {
	ReqID      string `db:"req_id" json:"req_id"`
	Kind       string `db:"kind" json:"kind"`
	FilePath   string `db:"file_path" json:"file_path"`
	LineNumber int    `db:"line_number" json:"line_number"`
	Context    string `db:"context" json:"context,omitempty"`
}

Ref is a requirement reference found outside CANARY tokens (diagrams, docs).

type Token 

type Token struct {
	ID          int
	ReqID       string
	Feature     string
	Aspect      string
	Status      string
	FilePath    string
	LineNumber  int
	Test        string
	Bench       string
	Owner       string
	Priority    int
	Phase       string
	Keywords    string
	SpecStatus  string
	CreatedAt   string
	UpdatedAt   string
	StartedAt   string
	CompletedAt string
	CommitHash  string
	Branch      string
	DependsOn   string
	Blocks      string
	RelatedTo   string
	RawToken    string
	IndexedAt   string

	// CANARY: REQ=CBIN-136; FEATURE="DocDatabaseSchema"; ASPECT=Storage; STATUS=IMPL; UPDATED=2025-10-16
	// Documentation tracking fields
	DocPath      string // Comma-separated doc file paths (e.g., "user:docs/user.md,api:docs/api.md")
	DocHash      string // Comma-separated SHA256 hashes (abbreviated, first 16 chars)
	DocType      string // Documentation type (user, technical, feature, api, architecture)
	DocCheckedAt string // ISO 8601 timestamp of last staleness check
	DocStatus    string // DOC_CURRENT, DOC_STALE, DOC_MISSING, DOC_UNHASHED

	// CANARY: REQ=CBIN-146; FEATURE="TokenNamespacing"; ASPECT=Storage; STATUS=IMPL; UPDATED=2025-10-18
	// Multi-project support
	ProjectID string // Project identifier for token isolation
}

Token represents a parsed CANARY token with extended metadata

Source Files

View all Source files

Directories

Path Synopsis
CANARY: REQ=CBIN-146; FEATURE="TestInfrastructure"; ASPECT=Storage; STATUS=IMPL; UPDATED=2025-10-18
 CANARY: REQ=CBIN-146; FEATURE="TestInfrastructure"; ASPECT=Storage; STATUS=IMPL; UPDATED=2025-10-18

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.