storage

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

type ListOptions struct {
	// Maximum number of results to return (0 = unlimited)
	Limit int

	// Number of results to skip (for pagination)
	Offset int

	// Only include reports after this time (inclusive)
	Since time.Time

	// Only include reports before this time (inclusive)
	Until time.Time
}

type ReportMetadata struct {
	// Unique identifier for this report
	ID string `json:"id"`

	// Absolute path to the analyzed project
	ProjectPath string `json:"project_path"`

	// When this analysis was performed
	Timestamp time.Time `json:"timestamp"`

	// Git commit hash at time of analysis (optional)
	GitCommit string `json:"git_commit,omitempty"`

	// Git branch name at time of analysis (optional)
	GitBranch string `json:"git_branch,omitempty"`

	// Summary metrics (optional, for quick display)
	TotalFiles    int     `json:"total_files,omitempty"`
	TotalLines    int     `json:"total_lines,omitempty"`
	AvgComplexity float64 `json:"avg_complexity,omitempty"`
	AvgCoverage   float64 `json:"avg_coverage,omitempty"`
	IssueCount    int     `json:"issue_count,omitempty"`
}

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

type Storage interface {
	// Save stores an analysis report with metadata.
	//
	// The report is assigned a unique ID and stored with the provided metadata
	// (timestamp, Git commit, branch). Returns an error if storage fails.
	//
	// Example:
	//   report := &StoredReport{
	//       ID: "abc-123",
	//       ProjectPath: "/path/to/project",
	//       Timestamp: time.Now(),
	//       GitCommit: "def456",
	//       Result: analysisResult,
	//   }
	//   err := storage.Save(ctx, report)
	Save(ctx context.Context, report *StoredReport) error

	// GetLatest retrieves the most recent report for a project.
	//
	// Returns the latest report based on timestamp, or nil if no reports
	// exist for the project. The projectPath should be an absolute path
	// for consistent matching across runs.
	//
	// Example:
	//   latest, err := storage.GetLatest(ctx, "/path/to/project")
	//   if latest != nil {
	//       // Compare with current analysis
	//   }
	GetLatest(ctx context.Context, projectPath string) (*StoredReport, error)

	// GetByID retrieves a specific report by its unique ID.
	//
	// Returns the report with the given ID, or an error if not found.
	// Useful for retrieving specific historical reports for comparison.
	//
	// Example:
	//   report, err := storage.GetByID(ctx, "abc-123")
	GetByID(ctx context.Context, id string) (*StoredReport, error)

	// List returns reports for a project, optionally filtered and paginated.
	//
	// Returns metadata for matching reports ordered by timestamp (newest first).
	// Use ListOptions to filter by date range and implement pagination.
	//
	// Example:
	//   opts := ListOptions{Limit: 10, Since: oneWeekAgo}
	//   reports, err := storage.List(ctx, "/path/to/project", opts)
	List(ctx context.Context, projectPath string, opts ListOptions) ([]*ReportMetadata, error)

	// Delete removes a report by ID.
	//
	// Returns an error if the report doesn't exist or deletion fails.
	// Use with caution as this operation is irreversible.
	//
	// Example:
	//   err := storage.Delete(ctx, "abc-123")
	Delete(ctx context.Context, id string) error

	// Close cleans up storage resources.
	//
	// Should be called when the storage is no longer needed to release
	// any open connections, file handles, or other resources.
	//
	// Example:
	//   defer storage.Close()
	Close() error
}

type StoredReport struct {
	// Unique identifier for this report (UUID)
	ID string `json:"id"`

	// Absolute path to the analyzed project
	ProjectPath string `json:"project_path"`

	// When this analysis was performed
	Timestamp time.Time `json:"timestamp"`

	// Git commit hash at time of analysis (optional)
	GitCommit string `json:"git_commit,omitempty"`

	// Git branch name at time of analysis (optional)
	GitBranch string `json:"git_branch,omitempty"`

	// The complete analysis result
	Result *analyzer.AnalysisResult `json:"result"`
}