summary

Documentation

Overview

Package summary provides comprehensive repository statistics collection and presentation. It aggregates data from multiple git commands to build a complete picture of repository health, activity, and structure.

Index

• func Print(s *Summary, opts PrintOptions)
• type CollectorResult
• type CommitSummary
• type ContributorRank
• type ContributorStats
• type HealthIndicators
• type HourlyActivity
• type Metadata
• type MonthlyActivity
• type Options
  • func DefaultOptions(repoPath string) Options
• type PrintOptions
• type RepoIdentity
• type Summary
  • func Collect(ctx context.Context, opts Options) (*Summary, error)
• type TimelineStats
• type WeekdayActivity

Functions

func Print

func Print(s *Summary, opts PrintOptions)

Print outputs the summary in a formatted, readable way.

Types

type CollectorResult

type CollectorResult struct {
	Name  string
	Error error
}

CollectorResult wraps a result with its error for parallel collection.

type CommitSummary

type CommitSummary struct {
	Hash    string
	Date    string
	Author  string
	Subject string
}

CommitSummary holds minimal info about a significant commit.

type ContributorRank

type ContributorRank struct {
	Rank       int
	Name       string
	Email      string
	Commits    int
	Percentage float64
}

ContributorRank represents a contributor with their stats.

type ContributorStats

type ContributorStats struct {
	TotalContributors int
	TopContributors   []ContributorRank
	RecentActive      []ContributorRank // active in last 30 days
	NewContributors   int               // new in last 30 days
}

ContributorStats holds contributor analysis data.

type HealthIndicators

type HealthIndicators struct {
	// Bus factor: how many contributors cover X% of commits
	BusFactor     int
	BusFactorDesc string // "2 contributors cover 90% of commits"

	// Activity trends
	IsActive        bool   // commits in last 30 days
	ActivityTrend   string // "increasing", "stable", "declining"
	DaysSinceCommit int

	// Diversity
	ContributorDiversity float64 // Gini coefficient (0=equal, 1=one person)
	TopContributorShare  float64 // % of commits by top contributor

	// Velocity
	CommitVelocity string // "X commits/week (last 4 weeks)"

	// Stale branches
	StaleBranches int
	UnmergedPRs   int // branches that look like PRs (feature/, fix/, etc.)

	// Code stability
	MostVolatileFiles []string // files with highest churn
}

HealthIndicators holds project health metrics.

type HourlyActivity

type HourlyActivity struct {
	Hour       int
	Count      int
	Percentage float64
}

HourlyActivity holds commit counts for an hour.

type Metadata

type Metadata struct {
	Path           string
	DefaultBranch  string
	TotalCommits   int
	FirstCommit    *CommitSummary
	LastCommit     *CommitSummary
	UniqueAuthors  int
	LocalBranches  int
	RemoteBranches int
	Tags           int
	RepoAge        string // human-readable age (e.g., "2 years, 3 months")
	RemoteURL      string
	RepoInfo       *RepoIdentity // parsed owner/name from remote
}

Metadata contains basic repository information.

type MonthlyActivity

type MonthlyActivity struct {
	Month string // YYYY-MM
	Count int
	Bar   string
}

MonthlyActivity holds commit counts for a month.

type Options

type Options struct {
	RepoPath     string
	TopN         int  // number of top contributors/files to show (default: 10)
	SkipTimeline bool // skip timeline heatmap (faster)
	RawAuthors   bool // skip author grouping, show raw git identities
}

Options configures the summary collection.

func DefaultOptions

func DefaultOptions(repoPath string) Options

DefaultOptions returns sensible defaults.

type PrintOptions

type PrintOptions struct {
	Compact bool // minimal output
}

PrintOptions configures output formatting.

type RepoIdentity

type RepoIdentity struct {
	Host  string
	Owner string
	Name  string
}

RepoIdentity holds parsed remote URL info.

type Summary

type Summary struct {
	Metadata     *Metadata
	Contributors *ContributorStats
	Timeline     *TimelineStats
	Health       *HealthIndicators
	CollectedAt  time.Time
	Duration     time.Duration // how long collection took
}

Summary holds all collected repository statistics. Each section is populated by a dedicated collector.

func Collect

func Collect(ctx context.Context, opts Options) (*Summary, error)

Collect gathers all repository statistics. It runs collectors in parallel where possible for better performance.

type TimelineStats

type TimelineStats struct {
	// Period counts
	Today     int
	ThisWeek  int
	ThisMonth int
	ThisYear  int

	// Trend analysis
	LastWeekDelta      int     // change from previous week
	LastMonthDelta     int     // change from previous month
	Last3WeeksDelta    int     // change vs previous 3-week window
	Last3WeeksDeltaPct float64 // percent change vs previous 3-week window
	AvgPerDay          float64 // average commits per day (last 30 days)
	AvgPerWeek         float64 // average commits per week (last 30 days)

	// Patterns
	WeekdayHeatmap []WeekdayActivity
	HourlyHeatmap  []HourlyActivity
	MonthlyTrend   []MonthlyActivity

	// Ratios
	MergeCommits   int
	DirectCommits  int
	MergeRatio     float64
	WeekendCommits int
	WeekdayCommits int
	WeekendRatio   float64
}

TimelineStats holds commit activity analysis.

type WeekdayActivity

type WeekdayActivity struct {
	Day        string
	Count      int
	Percentage float64
	Bar        string // visual representation
}

WeekdayActivity holds commit counts for a day of week.