cmd

package
v1.1.0 Latest Latest
Warning

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

Go to latest
Published: Sep 12, 2025 License: MIT Imports: 20 Imported by: 0

Documentation

Overview

Copyright © 2025 Ben Ricker

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Copyright © 2025 Ben Ricker <ben@jumboturbo.com>

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Index

Constants

View Source
const (
	// DefaultFallbackFileAge is the assumed age for files that exist but weren't
	// modified in the analysis window. This avoids expensive individual git history
	// lookups for every file while providing a reasonable default.
	DefaultFallbackFileAge = 2 * 365 * 24 * time.Hour // 2 years
)

Configuration constants for Gitallica analysis

Variables

View Source
var (
	ErrFoundTarget = errors.New("target found")
	ErrFoundCommit = errors.New("commit found")
)

Sentinel errors for iteration control

View Source
var (
	ErrIterationComplete = errors.New("iteration complete")
	ErrReachedMergeBase  = errors.New("reached merge base")
	ErrBranchTooLarge    = errors.New("branch too large")
)

Sentinel errors for control flow clarity

View Source
var DefaultAuthorMappings = []AuthorMapping{}

DefaultAuthorMappings contains the default author normalization mappings. These can be overridden in configuration files. DefaultAuthorMappings is empty by default. Configure as needed in your application.

Functions

func Execute

func Execute()

Execute adds all child commands to the root command and sets flags appropriately. This is called by main.main(). It only needs to happen once to the rootCmd.

Types

type AuthorContribution

type AuthorContribution struct {
	Author     string
	Lines      int // Lines authored (was Commits)
	Percentage float64
}

AuthorContribution represents an author's contribution to a directory

type AuthorMapping added in v1.1.0

type AuthorMapping struct {
	Patterns  []string // Email or name patterns to match
	Canonical string   // Canonical email address to use
}

AuthorMapping represents a mapping from various email/name patterns to a canonical author

type BranchInfo

type BranchInfo struct {
	Name             string
	AgeInDays        float64
	Status           string // "active", "merged", "stale"
	Risk             string // "Healthy", "Warning", "Risky", "Critical"
	LastCommitAuthor string
	LastCommitTime   time.Time
	CommitCount      int
	DivergencePoint  string // Hash of the divergence commit
}

BranchInfo represents information about a Git branch

type BusFactorAnalysis

type BusFactorAnalysis struct {
	TimeWindow       string
	TotalDirectories int
	DirectoryStats   []DirectoryBusFactorStats
	OverallRiskDirs  []DirectoryBusFactorStats
	HealthyDirs      []DirectoryBusFactorStats
}

BusFactorAnalysis represents the overall bus factor analysis

type ChangeLeadTimeStats

type ChangeLeadTimeStats struct {
	TotalCommits         int
	AverageLeadTimeHours float64
	MedianLeadTimeHours  float64
	P95LeadTimeHours     float64
	EliteCommits         int
	HighCommits          int
	MediumCommits        int
	LowCommits           int
	DORAPerformanceLevel string // "Elite", "High", "Medium", "Low", "Unknown"
	SlowestCommits       []CommitLeadTime
	FastestCommits       []CommitLeadTime
	Commits              []CommitLeadTime
}

ChangeLeadTimeStats contains analysis results for change lead time

type CommitCadenceStats

type CommitCadenceStats struct {
	TotalCommits            int
	TotalPeriods            int
	AverageCommitsPerPeriod float64
	TrendDirection          string // "Increasing", "Decreasing", "Stable", "Unknown"
	TrendStrength           float64
	SustainabilityLevel     string // "Healthy", "Caution", "Warning", "Critical"
	Spikes                  []TimePeriod
	Dips                    []TimePeriod
	TimePeriods             []TimePeriod
}

CommitCadenceStats contains analysis results

type CommitInfo

type CommitInfo struct {
	Hash    string
	Time    time.Time
	Files   []string
	Message string
	Author  string // Optional: author email for analysis
}

CommitInfo represents commit information for analysis

type CommitLeadTime

type CommitLeadTime struct {
	Hash           string
	Author         string
	CommitTime     time.Time
	DeployTime     time.Time
	LeadTimeHours  float64
	Classification string // "Elite", "High", "Medium", "Low"
	Message        string
}

CommitLeadTime represents a commit with its lead time measurement

type CommitSizeStats

type CommitSizeStats struct {
	Hash         string
	Message      string
	Author       string
	Date         time.Time
	Additions    int
	Deletions    int
	FilesChanged int
	RiskScore    int
	RiskLevel    string
}

CommitSizeStats represents size and risk statistics for a single commit.

type ComponentCreationRate

type ComponentCreationRate struct {
	TimeWindow    string
	TotalCreated  int
	ByType        map[string]int
	SpikeDetected bool
	SpikeReason   string
}

ComponentCreationRate tracks creation rate over time

type ComponentCreationStats

type ComponentCreationStats struct {
	ComponentType string
	Count         int
	Files         []string
	FileSet       map[string]bool // O(1) lookup for duplicate prevention
	FirstSeen     time.Time
	LastSeen      time.Time
}

ComponentCreationStats tracks component creation statistics

type ComponentType

type ComponentType struct {
	Name        string
	Patterns    []*regexp.Regexp
	Extensions  []string
	Description string
}

ComponentType represents different types of components across frameworks

type DeadZoneAnalysis

type DeadZoneAnalysis struct {
	TimeWindow      string
	TotalFiles      int
	DeadZoneFiles   []DeadZoneFileStats
	ActiveFiles     int
	DeadZoneCount   int
	DeadZonePercent float64
}

DeadZoneAnalysis represents the overall dead zone analysis

type DeadZoneFileStats

type DeadZoneFileStats struct {
	Path           string
	LastModified   time.Time
	AgeInMonths    int
	Size           int64
	RiskLevel      string
	Recommendation string
}

DeadZoneFileStats represents statistics for a potentially stale file

type DirectoryBusFactorStats

type DirectoryBusFactorStats struct {
	Path              string
	TotalLines        int                // Total lines of code in directory
	AuthorLines       map[string]int     // Lines authored by each contributor
	AuthorPercentages map[string]float64 // Percentage of lines authored by each contributor
	BusFactor         int
	RiskLevel         string
	Recommendation    string
	TopContributors   []AuthorContribution
}

DirectoryBusFactorStats represents bus factor statistics for a directory

type DirectoryChurnStats

type DirectoryChurnStats struct {
	Path         string
	Additions    int
	Deletions    int
	TotalLOC     int
	ChurnPercent float64
	Status       string
	FileCount    int
}

DirectoryChurnStats represents aggregated churn statistics for a directory.

type DirectoryEntropyAnalysis

type DirectoryEntropyAnalysis struct {
	TimeWindow      string
	ProjectType     ProjectType
	TotalDirs       int
	AvgEntropy      float64
	HighEntropyDirs []DirectoryEntropyStats
	LowEntropyDirs  []DirectoryEntropyStats
}

DirectoryEntropyAnalysis represents the overall analysis

type DirectoryEntropyStats

type DirectoryEntropyStats struct {
	Path           string
	FileCount      int
	FileTypes      map[string]int
	Entropy        float64
	EntropyLevel   string
	Recommendation string
}

DirectoryEntropyStats represents entropy statistics for a directory

type FileChurnStats

type FileChurnStats struct {
	Path         string
	Additions    int
	Deletions    int
	TotalLOC     int
	ChurnPercent float64
	Status       string
}

FileChurnStats represents churn statistics for a single file.

type FileOwnership

type FileOwnership struct {
	FilePath          string
	TopContributor    string
	TopOwnership      float64
	TotalContributors int
	Status            string
	Recommendation    string
	CommitsByAuthor   map[string]int
}

FileOwnership represents ownership information for a single file

type FilePopularity

type FilePopularity struct {
	FilePath   string
	TouchCount int
	Percentage float64
}

FilePopularity represents how often a file is touched by new contributors

type HealthIssue added in v1.1.0

type HealthIssue struct {
	Category       string // e.g., "Code Quality", "Performance", "Risk"
	Metric         string // e.g., "churn", "bus-factor"
	Severity       string // "Critical", "High", "Medium", "Low"
	Score          int    // 1-100 severity score
	Description    string // Human-readable description
	Recommendation string // Actionable recommendation
	Details        string // Additional context or data
}

HealthIssue represents a single health issue found in the codebase

type HealthReport added in v1.1.0

type HealthReport struct {
	RepositoryPath string
	AnalysisTime   time.Time
	TimeWindow     string
	TotalIssues    int
	CriticalIssues int
	HighIssues     int
	MediumIssues   int
	LowIssues      int
	Issues         []HealthIssue
	Summary        string
}

HealthReport represents the overall health check results

type HighRiskCommit

type HighRiskCommit struct {
	Hash         string
	Author       string
	Date         time.Time
	Message      string
	LinesChanged int // Total additions + deletions
	FilesChanged int
	Risk         string
	Reason       string
}

HighRiskCommit represents a commit with risk analysis

type HighRiskCommitsStats

type HighRiskCommitsStats struct {
	TotalCommits  int
	LowRisk       int
	ModerateRisk  int
	HighRisk      int
	CriticalRisk  int
	AverageLines  float64
	AverageFiles  float64
	LargestCommit HighRiskCommit
	RiskyCommits  []HighRiskCommit // Only moderate+ risk commits
}

HighRiskCommitsStats contains analysis statistics

type LongLivedBranchesStats

type LongLivedBranchesStats struct {
	TotalBranches        int
	AverageBranchAge     float64
	HealthyBranches      int
	WarningBranches      int
	RiskyBranches        int
	CriticalBranches     int
	TrunkBasedCompliance string // "Excellent", "Good", "Moderate", "Poor", "Critical", "Unknown"
	OldestBranch         *BranchInfo
	RiskyBranchDetails   []BranchInfo
	Branches             []BranchInfo
}

LongLivedBranchesStats contains analysis results for branch lifespans

type NewContributor

type NewContributor struct {
	Email           string
	FirstCommitTime time.Time
	FilesTouched    int
	CommitsAnalyzed int
	Status          string
	Recommendation  string
	FilesModified   []string
}

NewContributor represents a new contributor's onboarding pattern

type OnboardingFootprintStats

type OnboardingFootprintStats struct {
	TotalContributors      int
	AnalyzedContributors   int
	AverageFilesTouched    float64
	SimpleOnboarding       int
	ModerateOnboarding     int
	ComplexOnboarding      int
	OverwhelmingOnboarding int
	Contributors           []NewContributor
	CommonFiles            []FilePopularity
	TimeWindow             string
}

OnboardingFootprintStats represents the onboarding footprint analysis

type OwnershipClarityStats

type OwnershipClarityStats struct {
	TotalFiles    int
	FilesAnalyzed int
	HealthyFiles  int
	CautionFiles  int
	WarningFiles  int
	CriticalFiles int
	UnknownFiles  int
	FileOwnership []FileOwnership
}

OwnershipClarityStats represents the ownership clarity analysis for files

type ProjectType

type ProjectType struct {
	Name         string
	RootPatterns []string
	ExpectedDirs map[string][]string
	Description  string
}

ProjectType represents different types of software projects

type TestRatioStats

type TestRatioStats struct {
	TestLOC        int
	SourceLOC      int
	OtherLOC       int
	TotalLOC       int
	TestRatio      float64
	Status         string
	Recommendation string
	TestFiles      int
	SourceFiles    int
	OtherFiles     int
	TotalFiles     int
}

TestRatioStats represents the test-to-code ratio analysis

type TimePeriod

type TimePeriod struct {
	Start       time.Time
	End         time.Time
	CommitCount int
	Severity    string // For spikes/dips: "Low", "Medium", "High"
}

TimePeriod represents a time window with commit count

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL