Documentation
¶
Overview ¶
Package scoring converts raw analysis metrics to normalized scores (1-10 scale) using piecewise linear interpolation over configurable breakpoints.
The scoring system provides a consistent, predictable mapping from raw values (complexity counts, percentages, file sizes) to user-facing scores that directly correlate with agent-readiness tiers. All metrics flow through the Interpolate function, ensuring uniform scoring behavior across categories.
Scoring philosophy: Breakpoints are empirically derived from agent success rates across diverse codebases. For example, complexity >15 correlates with 3x higher agent error rates, so the breakpoint mapping reflects this empirical relationship.
Index ¶
Constants ¶
const ( ScoreExcellent = 10.0 ScoreGood = 8.0 ScoreAboveAvg = 7.0 ScoreAdequate = 6.0 ScoreBelowAvg = 5.0 ScorePoor = 4.0 ScoreWeak = 3.0 ScoreVeryPoor = 2.0 ScoreMinimum = 1.0 )
Score scale constants used in breakpoint definitions. Using named constants improves readability and reduces magic number count.
const ( TierReadyMin = 8.0 TierAssistedMin = 6.0 TierLimitedMin = 4.0 TierHostileMin = 1.0 )
Tier threshold constants for composite score classification.
const ( WeightCodeHealth = 0.25 WeightSemantics = 0.10 WeightArchitecture = 0.20 WeightDocumentation = 0.15 WeightTemporal = 0.10 WeightTesting = 0.15 WeightAgentEval = 0.10 )
Category weight constants define the relative importance of each category in the composite score. Must sum to ~1.0 across all categories.
const ( MetricWeightPrimary = 0.30 MetricWeightHigh = 0.25 MetricWeightMedium = 0.20 MetricWeightStandard = 0.15 MetricWeightLow = 0.10 MetricWeightMinimal = 0.05 )
Metric weight constants define the relative importance of sub-metrics within each category. Reused across categories where weight values coincide.
const ( ComplexityGood = 5.0 ComplexityAdequate = 10.0 ComplexityWeak = 20.0 ComplexityCritical = 40.0 FuncLenGood = 5.0 FuncLenAdequate = 15.0 FuncLenWeak = 30.0 FuncLenPoor = 60.0 FuncLenCritical = 100.0 FileSizeGood = 50.0 FileSizeAdequate = 150.0 FileSizeWeak = 300.0 FileSizePoor = 500.0 FileSizeCritical = 1000.0 CouplingAdequate = 5.0 CouplingWeak = 10.0 CouplingCritical = 20.0 DupRateGood = 3.0 DupRateAdequate = 8.0 DupRateWeak = 15.0 DupRateCritical = 50.0 MaxFileSizeGood = 200.0 MaxFileSizeAdequate = 500.0 MaxFileSizeWeak = 1000.0 MaxFileSizePoor = 2000.0 MaxFileSizeCritical = 5000.0 LargeFilePctGood = 5.0 LargeFilePctAdequate = 15.0 LargeFilePctWeak = 30.0 LargeFilePctPoor = 50.0 LargeFilePctCritical = 75.0 )
C1 breakpoint value constants.
const ( TypeAnnotationWeak = 30.0 TypeAnnotationAdequate = 50.0 TypeAnnotationGood = 80.0 NamingWeak = 70.0 NamingAdequate = 85.0 NamingGood = 95.0 MagicNumGood = 5.0 MagicNumAdequate = 15.0 MagicNumWeak = 30.0 MagicNumCritical = 50.0 NullSafetyWeak = 30.0 NullSafetyAdequate = 50.0 NullSafetyGood = 80.0 )
C2 breakpoint value constants.
const ( DirDepthGood = 3.0 DirDepthAdequate = 5.0 DirDepthWeak = 7.0 DirDepthCritical = 10.0 FanoutGood = 3.0 FanoutAdequate = 6.0 FanoutWeak = 10.0 FanoutCritical = 15.0 CircDepsAdequate = 3.0 CircDepsPoor = 5.0 CircDepsCritical = 10.0 ImportCompGood = 4.0 ImportCompAdequate = 6.0 ImportCompCritical = 8.0 DeadExportsGood = 5.0 DeadExportsAdequate = 15.0 DeadExportsWeak = 30.0 DeadExportsCritical = 50.0 )
C3 breakpoint value constants.
const ( ReadmeWordsWeak = 100.0 ReadmeWordsAdequate = 300.0 ReadmeWordsGood = 500.0 ReadmeWordsExcel = 1000.0 CommentDensityWeak = 5.0 CommentDensityAdequate = 10.0 CommentDensityGood = 15.0 CommentDensityExcel = 25.0 APIDocWeak = 30.0 APIDocAdequate = 50.0 APIDocGood = 80.0 )
C4 breakpoint value constants.
const ( ChurnExcel = 50.0 ChurnGood = 100.0 ChurnAdequate = 300.0 ChurnWeak = 600.0 ChurnCritical = 1000.0 TempCouplingGood = 5.0 TempCouplingAdequate = 15.0 TempCouplingWeak = 25.0 TempCouplingCritical = 30.0 AuthorFragGood = 4.0 AuthorFragWeak = 6.0 AuthorFragCritical = 8.0 CommitStabMinimum = 0.5 CommitStabAdequate = 3.0 CommitStabGood = 7.0 CommitStabExcel = 14.0 HotspotExcel = 20.0 HotspotGood = 30.0 HotspotAdequate = 50.0 HotspotWeak = 70.0 HotspotCritical = 80.0 )
C5 breakpoint value constants.
const ( TestRatioPoor = 0.2 TestRatioAdequate = 0.5 TestRatioGood = 0.8 TestRatioExcel = 1.5 CoveragePoor = 30.0 CoverageAdequate = 50.0 CoverageGood = 70.0 CoverageExcel = 90.0 IsolationPoor = 40.0 IsolationAdequate = 60.0 IsolationGood = 80.0 IsolationExcel = 95.0 AssertDensityAdequate = 3.0 AssertDensityExcel = 5.0 TestFileRatioPoor = 0.3 TestFileRatioAdequate = 0.5 TestFileRatioGood = 0.7 TestFileRatioExcel = 0.9 )
C6 breakpoint value constants.
const ( C7ScorePoor = 4.0 C7ScoreAboveAvg = 7.0 )
C7 breakpoint value constants.
const ( FileSizeFloorThreshold = 2.0 // file_size_avg score at or below this triggers the cap FileSizeFloorCap = 4.0 // maximum C1 score when the floor triggers )
C1 file size penalty floor constants. When file_size_avg scores at or below FileSizeFloorThreshold (indicating avg file sizes that are structurally hostile for AI agents), the C1 category score is capped at FileSizeFloorCap regardless of other metrics. Rationale: files averaging 750+ LOC often cannot fit in agent context windows, making the codebase difficult to navigate even if other metrics are favorable. The weighted average alone cannot capture this blocker.
Variables ¶
This section is empty.
Functions ¶
func CategoryScore ¶
CategoryScore computes the weighted average of sub-scores within a category.
Returns -1.0 if all sub-scores are unavailable (Score < 0), indicating the category cannot be scored.
func Interpolate ¶
func Interpolate(breakpoints []Breakpoint, rawValue float64) float64
Interpolate computes the score for a given raw value using piecewise linear interpolation over the provided breakpoints. Values below the first breakpoint use the first score; values above the last use the last score.
Types ¶
type Breakpoint ¶
type Breakpoint struct {
Value float64 `yaml:"value"` // raw metric value
Score float64 `yaml:"score"` // corresponding score (1-10)
}
Breakpoint defines a mapping from a raw metric value to a score. Breakpoints must be sorted by Value in ascending order.
type CategoryConfig ¶
type CategoryConfig struct {
Name string `yaml:"name"`
Weight float64 `yaml:"weight"`
Metrics []MetricThresholds `yaml:"metrics"`
}
CategoryConfig defines the scoring configuration for one category.
type MetricThresholds ¶
type MetricThresholds struct {
Name string `yaml:"name"`
Weight float64 `yaml:"weight"`
Breakpoints []Breakpoint `yaml:"breakpoints"`
}
MetricThresholds defines the breakpoints for scoring a single metric.
type Scorer ¶
type Scorer struct {
Config *ScoringConfig
}
Scorer computes scores from raw analysis metrics using configurable breakpoints.
func (*Scorer) Score ¶
func (s *Scorer) Score(results []*types.AnalysisResult) (*types.ScoredResult, error)
Score computes scored results from raw analysis metrics.
type ScoringConfig ¶
type ScoringConfig struct {
Categories map[string]CategoryConfig `yaml:"categories"`
Tiers []tierConfig `yaml:"tiers"`
}
ScoringConfig holds all scoring thresholds and weights. Categories are stored in a map keyed by category identifier (e.g., "C1", "C2").
func DefaultConfig ¶
func DefaultConfig() *ScoringConfig
DefaultConfig returns the default scoring configuration with breakpoints for all metrics across C1-C7 categories.
func LoadConfig ¶
func LoadConfig(path string) (*ScoringConfig, error)
LoadConfig loads a ScoringConfig from a YAML file at path. If path is empty, returns DefaultConfig(). The YAML is unmarshaled into a copy of DefaultConfig so that missing fields retain their default values.
func (*ScoringConfig) Category ¶
func (sc *ScoringConfig) Category(name string) CategoryConfig
Category returns the CategoryConfig for the given category name. Returns a zero-value CategoryConfig if the category is not found.
Source Files