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.
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.
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.
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.
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.
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.
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.
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.
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.
Copyright © 2025 Ben Ricker <ben@jumboturbo.com>
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.
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.
Index ¶
- Constants
- Variables
- func Execute()
- type AuthorContribution
- type AuthorMapping
- type BranchInfo
- type BusFactorAnalysis
- type ChangeLeadTimeStats
- type CommitCadenceStats
- type CommitInfo
- type CommitLeadTime
- type CommitSizeStats
- type ComponentCreationRate
- type ComponentCreationStats
- type ComponentType
- type DeadZoneAnalysis
- type DeadZoneFileStats
- type DirectoryBusFactorStats
- type DirectoryChurnStats
- type DirectoryEntropyAnalysis
- type DirectoryEntropyStats
- type FileChurnStats
- type FileOwnership
- type FilePopularity
- type HealthIssue
- type HealthReport
- type HighRiskCommit
- type HighRiskCommitsStats
- type LongLivedBranchesStats
- type NewContributor
- type OnboardingFootprintStats
- type OwnershipClarityStats
- type ProjectType
- type TestRatioStats
- type TimePeriod
Constants ¶
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 ¶
var ( ErrFoundTarget = errors.New("target found") ErrFoundCommit = errors.New("commit found") )
Sentinel errors for iteration control
var ( ErrIterationComplete = errors.New("iteration complete") ErrReachedMergeBase = errors.New("reached merge base") ErrBranchTooLarge = errors.New("branch too large") )
Sentinel errors for control flow clarity
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 ¶
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 ¶
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