schema

package
v1.21.0 Latest Latest
Warning

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

 Go to latest Published: Apr 27, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Overview

Package schema has configs, models and global variables for all parts of hotspot.

Index

Constants

View Source 
const (
	CriticalValue = "Critical" // Critical value
	HighValue     = "High"     // High value
	ModerateValue = "Moderate" // Moderate value
	LowValue      = "Low"      // Low value
)

Scoring label constants for criticality levels.

Variables

View Source 
var AllScoringModes = []ScoringMode{HotMode, RiskMode, ComplexityMode, ROIMode}

AllScoringModes returns a list of all supported scoring modes.

View Source 
var DateTimeFormat = time.RFC3339

DateTimeFormat is the default date time representation.

View Source 
var DefaultExclude = formatExcludes(defaultExcludesRaw)

DefaultExclude represents the universal noise exclusion set applied across all analysis modes. It is formatted as a single comma-separated string for use in CLI flags and MCP defaults.

View Source 
var ValidDatabaseBackends = map[DatabaseBackend]struct{}{
	SQLiteBackend:     {},
	MySQLBackend:      {},
	PostgreSQLBackend: {},
	NoneBackend:       {},
}

ValidDatabaseBackends lists all valid database backends.

View Source 
var ValidOutputModes = map[OutputMode]struct{}{
	CSVOut:      {},
	TextOut:     {},
	JSONOut:     {},
	ParquetOut:  {},
	Describe:    {},
	MarkdownOut: {},
	HeatmapOut:  {},
	NoneOut:     {},
}

ValidOutputModes lists all valid output modes.

View Source 
var ValidScoringModes = map[ScoringMode]struct{}{
	HotMode:        {},
	RiskMode:       {},
	ComplexityMode: {},
	ROIMode:        {},
}

ValidScoringModes lists all valid scoring modes.

Functions

func AbbreviateName added in v1.1.0 

func AbbreviateName(name string) string

AbbreviateName formats "Samuel Huang" to "Samuel H". It handles names with parentheses, quotes, backticks, hyphens, and apostrophes appropriately. It also handles single-word names by returning them unchanged, and bot accounts without abbreviation.

func AbbreviateOwners added in v1.1.0 

func AbbreviateOwners(owners []string) []string

AbbreviateOwners applies abbreviation to all owners in the slice.

func CalculateDaysBetween added in v1.14.0 

func CalculateDaysBetween(start, end time.Time) int

CalculateDaysBetween computes the number of days between two time points.

func CalculateDecayFactor added in v1.14.0 

func CalculateDecayFactor(ageDays float64, halfLifeDays float64) float64

CalculateDecayFactor computes a weighting factor [0,1] based on age in days. Formula: e^(-k * ageDays), where k = ln(2) / halfLifeDays.

func FormatOwners added in v1.1.0 

func FormatOwners(owners []string) string

FormatOwners formats the top owners as "S. Huang, J. Doe".

func FormatWeights added in v1.14.0 

func FormatWeights(weights map[string]float64, factorKeys []string) string

FormatWeights formats weights for display in formulas.

func GetDefaultWeights added in v1.0.0 

func GetDefaultWeights(mode ScoringMode) map[BreakdownKey]float64

GetDefaultWeights returns the default weights for a given scoring mode from the YAML config.

func GetDisplayNameForMode added in v1.14.0 

func GetDisplayNameForMode(modeName string) string

GetDisplayNameForMode returns the display name for a given mode name.

func GetDisplayWeightsForMode added in v1.14.0 

func GetDisplayWeightsForMode(mode ScoringMode, activeWeights map[ScoringMode]map[BreakdownKey]float64) map[string]float64

GetDisplayWeightsForMode returns the weights to display for a given scoring mode. Uses active weights if available, otherwise falls back to defaults.

func GetPlainLabel added in v1.12.0 

func GetPlainLabel(score float64) string

GetPlainLabel returns a plain text label indicating the criticality level based on the importance score.

func GetScoringModeMetadata added in v1.19.0 

func GetScoringModeMetadata(mode ScoringMode) (purpose string, factors []string, factorKeys []string)

GetScoringModeMetadata returns the purpose and factors for a mode.

func IsIaCFile added in v1.19.0 

func IsIaCFile(path string) bool

IsIaCFile returns true when the path is likely an infrastructure-as-code file.

func IsPathInFilter added in v1.19.0 

func IsPathInFilter(path, filter string) bool

IsPathInFilter returns true if the path is within the directory or file specified by the filter. It correctly handles directory boundaries to avoid partial matches (e.g. "src" matching "src_old").

func NormalizeTimeseriesPath added in v1.14.0 

func NormalizeTimeseriesPath(repoPath, userPath string) (string, error)

NormalizeTimeseriesPath normalizes a user-provided path relative to the repo root and ensures it's within the repository boundaries.

func OwnersEqual added in v1.1.0 

func OwnersEqual(a, b []string) bool

OwnersEqual compares two slices of owners, considering them equal if they contain the same owners regardless of order.

func ParseBoolString added in v1.14.0 

func ParseBoolString(s string) (bool, error)

ParseBoolString parses a string value into a boolean. Accepts "yes", "no", "true", "false", "1", "0" (case-insensitive). Returns an error for invalid values.

func ParseLookbackDuration added in v1.14.0 

func ParseLookbackDuration(s string) (time.Duration, error)

ParseLookbackDuration converts strings like "3 months" or "720h" into a single time.Duration. It first tries custom parsing for human-readable formats (e.g., "30 days", "2 weeks", "30d"), then falls back to Go's built-in time.ParseDuration for standard formats.

func ParseRelativeTime added in v1.14.0 

func ParseRelativeTime(s string, now time.Time) (time.Time, error)

ParseRelativeTime converts strings like "2 years ago" or "30d ago" into a time.Time in the past.

func ShouldIgnore added in v1.14.0 

func ShouldIgnore(path string, excludes []string) bool

ShouldIgnore returns true if the given path matches any of the exclude patterns. This is a convenience wrapper around PathMatcher for one-off checks.

Performance Note: For repeated checks (e.g. in a loop), create a PathMatcher using NewPathMatcher instead to achieve zero-allocation matching.

Types

type AggregateOutput 

type AggregateOutput struct {
	FileStats map[string]*FileAggregation
	EndTime   time.Time // The end time of the analysis window (reference for decay)
}

AggregateOutput is the aggregation of all things from the one-pass Git operation.

type AnalysisQueryFilter added in v1.14.0 

type AnalysisQueryFilter struct {
	URN    string // Filter by repository URN (empty = all)
	Limit  int    // Maximum number of results (0 = no limit)
	Offset int    // Number of results to skip
}

AnalysisQueryFilter provides filtering and pagination for analysis queries.

type AnalysisRunRecord added in v1.8.0 

type AnalysisRunRecord struct {
	AnalysisID         int64
	URN                string
	StartTime          time.Time
	EndTime            *time.Time
	RunDurationMs      *int32
	TotalFilesAnalyzed *int32
	ConfigParams       *string
}

AnalysisRunRecord represents a row from the hotspot_analysis_runs table.

type AnalysisStatus added in v1.6.0 

type AnalysisStatus struct {
	Backend            string           `json:"backend"`
	Connected          bool             `json:"connected"`
	TotalRuns          int              `json:"total_runs"`
	LastRunID          int64            `json:"last_run_id"`
	LastRunTime        time.Time        `json:"last_run_time"`
	OldestRunTime      time.Time        `json:"oldest_run_time"`
	TotalFilesAnalyzed int              `json:"total_files_analyzed"`
	TableSizes         map[string]int64 `json:"table_sizes"`
}

AnalysisStatus represents the status of the analysis store.

type BatchAnalysisResultsOutput added in v1.21.0 

type BatchAnalysisResultsOutput struct {
	Results  []RepoShape `json:"results"`
	Metadata Metadata    `json:"metadata"`
}

BatchAnalysisResultsOutput is the standard container for fleet-wide batch analysis results.

type BatchFileResult added in v1.17.0 

type BatchFileResult struct {
	Path    string
	Metrics FileMetrics
	Scores  FileScores
}

BatchFileResult groups all data for a single file to be stored in the analysis store.

type BlastRadiusPair added in v1.16.0 

type BlastRadiusPair struct {
	Source   string  `json:"source"`    // The "source" file or the center of the radius
	Target   string  `json:"target"`    // The coupled file
	Score    float64 `json:"score"`     // Coupling score (Jaccard Index)
	CoChange int     `json:"co_change"` // Number of times they changed together
}

BlastRadiusPair represents a pair of files that are logically coupled.

type BlastRadiusResult added in v1.16.0 

type BlastRadiusResult struct {
	Summary BlastRadiusSummary `json:"summary"`
	Pairs   []BlastRadiusPair  `json:"pairs"`
}

BlastRadiusResult is the top-level response for the get_blast_radius tool.

type BlastRadiusResultsOutput added in v1.20.0 

type BlastRadiusResultsOutput struct {
	Results  BlastRadiusResult `json:"results"`
	Metadata Metadata          `json:"metadata"`
}

BlastRadiusResultsOutput is the standard container for blast radius analysis results.

type BlastRadiusSummary added in v1.16.0 

type BlastRadiusSummary struct {
	TotalCommits int     `json:"total_commits"` // Total commits analyzed
	TotalPairs   int     `json:"total_pairs"`   // Number of highly coupled pairs found
	Threshold    float64 `json:"threshold"`     // Min coupling score used for filtering
}

BlastRadiusSummary provides metadata about the analysis.

type BreakdownKey added in v1.1.2 

type BreakdownKey string

BreakdownKey represents keys used in scoring breakdowns. 

const (
	BreakdownContrib BreakdownKey = "contrib" // nContrib
	BreakdownCommits BreakdownKey = "commits" // nCommits
	BreakdownLOC     BreakdownKey = "loc"     // nLOC
	BreakdownSize    BreakdownKey = "size"    // nSize
	BreakdownAge     BreakdownKey = "age"     // nAge
	BreakdownChurn   BreakdownKey = "churn"   // nChurn

	BreakdownGini       BreakdownKey = "gini"        // nGiniRaw
	BreakdownInvContrib BreakdownKey = "inv_contrib" // nInvContrib
	BreakdownLowRecent  BreakdownKey = "low_recent"  // nInvRecentCommits (Staleness / Decay)
)

Breakdown keys used in the scoring logic.

type CacheStatus added in v1.6.0 

type CacheStatus struct {
	Backend         string    `json:"backend"`
	Connected       bool      `json:"connected"`
	TotalEntries    int       `json:"total_entries"`
	LastEntryTime   time.Time `json:"last_entry_time"`
	OldestEntryTime time.Time `json:"oldest_entry_time"`
	TableSizeBytes  int64     `json:"table_size_bytes"`
}

CacheStatus represents the status of the cache store.

type CheckFailedFile added in v1.9.0 

type CheckFailedFile struct {
	Path      string
	Mode      ScoringMode
	Score     float64
	Threshold float64
}

CheckFailedFile represents a file that failed the policy check.

type CheckMaxScoreFile added in v1.10.2 

type CheckMaxScoreFile struct {
	Path   string
	Owners []string
}

CheckMaxScoreFile represents a file that achieved the maximum score for a mode.

type CheckResult added in v1.9.0 

type CheckResult struct {
	Passed        bool
	FailedFiles   []CheckFailedFile
	TotalFiles    int
	CheckedModes  []ScoringMode
	TargetRef     string
	BaseRef       string
	Thresholds    map[ScoringMode]float64
	MaxScores     map[ScoringMode]float64
	MaxScoreFiles map[ScoringMode][]CheckMaxScoreFile
	Lookback      time.Duration
	AvgScores     map[ScoringMode]float64 // Average score per mode
}

CheckResult holds the results of a policy check.

type CheckResultsOutput added in v1.20.0 

type CheckResultsOutput struct {
	Results  *CheckResult `json:"results"`
	Metadata Metadata     `json:"metadata"`
}

CheckResultsOutput is the standard container for policy check analysis results.

type CompareAnalysisOutput added in v0.5.0 

type CompareAnalysisOutput struct {
	FileResults   []FileResult
	FolderResults []FolderResult
}

CompareAnalysisOutput is for one of the core algorithms.

type ComparisonDetail added in v1.10.3 

type ComparisonDetail struct {
	Path         string      `json:"path"`          // Relative path to the target in the repository
	BeforeScore  float64     `json:"before_score"`  // Score from the original/base analysis
	AfterScore   float64     `json:"after_score"`   // Score from the comparison/new analysis
	Delta        float64     `json:"delta"`         // CompScore - BaseScore (Positive means worse/higher)
	DeltaCommits Metric      `json:"delta_commits"` // Change in total commits (Positive means more activity)
	DeltaChurn   Metric      `json:"delta_churn"`   // Change in total churn (Positive means more volatility)
	Status       Status      `json:"status"`        // Intrinsic status of the file as of now
	BeforeOwners []string    `json:"before_owners"` // Owners from the base analysis
	AfterOwners  []string    `json:"after_owners"`  // Owners from the target analysis
	Mode         ScoringMode `json:"mode"`          // Scoring mode (hot, risk, complexity, roi)

	*FileComparison   `json:"file_compare,omitempty"`
	*FolderComparison `json:"folder_compare,omitempty"`
}

ComparisonDetail holds the base info, target info, and their associated deltas.

type ComparisonResult added in v0.5.0 

type ComparisonResult struct {
	Details []ComparisonDetail `json:"details"`
	Summary ComparisonSummary  `json:"summary"`
}

ComparisonResult holds the comparison details and summary.

type ComparisonResultsOutput added in v1.14.0 

type ComparisonResultsOutput struct {
	Results  ComparisonResult `json:"results"`
	Metadata Metadata         `json:"metadata"`
}

ComparisonResultsOutput is the standard container for comparison analysis results.

type ComparisonSummary added in v0.8.0 

type ComparisonSummary struct {
	// 1. Net Score Delta
	NetScoreDelta float64 `json:"net_score_delta"`

	// 2. Net Churn Delta
	NetChurnDelta Metric `json:"net_churn_delta"`

	// 3. File Status Counts
	TotalNewFiles      int `json:"total_new_files"`
	TotalInactiveFiles int `json:"total_inactive_files"`
	TotalModifiedFiles int `json:"total_modified_files"`

	// 4. Ownership Changes
	TotalOwnershipChanges int `json:"total_ownership_changes"`
}

ComparisonSummary has high-level deltas and counts.

type CoupledFile added in v1.16.0 

type CoupledFile struct {
	Path     string  `json:"path"`      // Path of the coupled file
	Score    float64 `json:"score"`     // Coupling score (0.0 to 1.0)
	How      string  `json:"how"`       // Human-readable reason (e.g., "Changed together 15 times")
	CoChange int     `json:"co_change"` // Number of times these files changed together
}

CoupledFile represents a file and its coupling strength to a target.

type DatabaseBackend added in v1.10.0 

type DatabaseBackend string

DatabaseBackend represents the database used for analysis, migration, etc. 

const (
	SQLiteBackend     DatabaseBackend = "sqlite" // default
	MySQLBackend      DatabaseBackend = "mysql"
	PostgreSQLBackend DatabaseBackend = "postgresql"
	NoneBackend       DatabaseBackend = "none"
)

All cache backends supported.

type EnrichedFileResult added in v1.12.0 

type EnrichedFileResult struct {
	Rank  int    `json:"rank"`
	Label string `json:"label"`
	FileResult
}

EnrichedFileResult adds presentation data to a FileResult.

func EnrichFiles added in v1.12.0 

func EnrichFiles(files []FileResult) []EnrichedFileResult

EnrichFiles adds rank and label to a list of file results.

type EnrichedFolderResult added in v1.12.0 

type EnrichedFolderResult struct {
	Rank  int    `json:"rank"`
	Label string `json:"label"`
	FolderResult
}

EnrichedFolderResult adds presentation data to a FolderResult.

func EnrichFolders added in v1.12.0 

func EnrichFolders(folders []FolderResult) []EnrichedFolderResult

EnrichFolders adds rank and label to a list of folder results.

type FileAggregation added in v1.18.0 

type FileAggregation struct {
	Commits        Metric
	Churn          Metric
	LinesAdded     Metric
	LinesDeleted   Metric
	DecayedCommits Metric
	DecayedChurn   Metric
	FirstCommit    time.Time
	Contributors   map[string]Metric // Author name -> commit count

	// Recent Activity (Fixed window, e.g. 30 days)
	RecentCommits      Metric
	RecentChurn        Metric
	RecentLinesAdded   Metric
	RecentLinesDeleted Metric
	RecentContributors map[string]Metric
}

FileAggregation consolidates all metrics for a single file during aggregation.

type FileComparison added in v0.4.3 

type FileComparison struct {
	DeltaLOC     Metric `json:"delta_loc"`     // Change in LOC (Positive means file growth)
	DeltaContrib Metric `json:"delta_contrib"` // Change in contributors (Positive means contrib growth)
}

FileComparison has file deltas.

type FileMetrics 

type FileMetrics struct {
	AnalysisTime           time.Time
	TotalCommits           Metric
	TotalChurn             Metric
	LinesAdded             Metric
	LinesDeleted           Metric
	DecayedCommits         Metric
	DecayedChurn           Metric
	LinesOfCode            Metric
	ContributorCount       Metric
	RecentCommits          Metric
	RecentChurn            Metric
	RecentLinesAdded       Metric
	RecentLinesDeleted     Metric
	RecentContributorCount Metric
	AgeDays                Metric
	GiniCoefficient        float64
	FileOwner              string
	RecencySignal          float64
	RecencyThresholdLow    float64
	RecencyThresholdHigh   float64
}

FileMetrics represents raw git metrics for a single file.

type FileResult added in v0.5.0 

type FileResult struct {
	Path                 string    `json:"path"`                 // Relative path to the file in the repository
	UniqueContributors   Metric    `json:"unique_contributors"`  // Number of different authors who modified the file
	Commits              Metric    `json:"commits"`              // Total number of commits affecting this file
	RecentContributors   Metric    `json:"recent_contributors"`  // Recent contributor count within a time window
	RecentCommits        Metric    `json:"recent_commits"`       // Recent commit count within a time window
	RecentChurn          Metric    `json:"recent_churn"`         // Recent churn within a time window
	RecentLinesAdded     Metric    `json:"recent_lines_added"`   // Recent lines added
	RecentLinesDeleted   Metric    `json:"recent_lines_deleted"` // Recent lines deleted
	DecayedCommits       Metric    `json:"decayed_commits"`      // Time-weighted commit count
	DecayedChurn         Metric    `json:"decayed_churn"`        // Time-weighted churn count
	RecentWindowDays     int       `json:"recent_window_days"`   // Number of days defining the 'recent' window
	SizeBytes            int64     `json:"size_bytes"`           // Current size of the file in bytes (Stay int64 as it's a file property)
	LinesOfCode          Metric    `json:"lines_of_code"`        // Current lines of code
	AgeDays              Metric    `json:"age_days"`             // Age of the file in days since first commit
	Churn                Metric    `json:"churn"`                // Total number of lines added/deleted
	LinesAdded           Metric    `json:"lines_added"`          // Total lines added
	LinesDeleted         Metric    `json:"lines_deleted"`        // Total lines deleted
	Gini                 float64   `json:"gini"`                 // Gini coefficient of commit distribution (0-1, lower is more even)
	FirstCommit          time.Time `json:"first_commit"`         // Timestamp of the file's first commit
	Owners               []string  `json:"owners"`               // Top 2 owners by commit count
	RecencySignal        float64   `json:"recency_signal"`       // 0-1 freshness score (recent activity vs lifetime volume)
	RecencyThresholdLow  float64   `json:"recency_threshold_low"`
	RecencyThresholdHigh float64   `json:"recency_threshold_high"`

	Mode          ScoringMode                              `json:"mode"`                 // Scoring mode used (hot, risk, complexity, roi)
	ModeScore     float64                                  `json:"score"`                // Computed score for the current mode (0-100)
	Reasoning     []string                                 `json:"reasoning,omitempty"`  // Human-and-AI-readable justifications for the score
	ModeBreakdown map[BreakdownKey]float64                 `json:"breakdown"`            // Normalized contribution of each metric to the score
	AllScores     map[ScoringMode]float64                  `json:"scores"`               // All computed scores by mode
	AllBreakdowns map[ScoringMode]map[BreakdownKey]float64 `json:"breakdowns,omitempty"` // Score breakdowns for all modes
}

FileResult represents the Git and file system metrics for a single file.

func (FileResult) GetChurn added in v0.9.1 

func (f FileResult) GetChurn() Metric

GetChurn returns the total churn.

func (FileResult) GetCommits added in v0.9.1 

func (f FileResult) GetCommits() Metric

GetCommits returns the total commit count.

func (FileResult) GetOwners added in v1.1.0 

func (f FileResult) GetOwners() []string

GetOwners returns the top owners.

func (FileResult) GetPath added in v0.9.1 

func (f FileResult) GetPath() string

GetPath returns the file path.

func (FileResult) GetScore added in v0.9.1 

func (f FileResult) GetScore() float64

GetScore returns the computed score.

type FileResultsOutput added in v1.14.0 

type FileResultsOutput struct {
	Results  []EnrichedFileResult `json:"results"`
	Metadata Metadata             `json:"metadata"`
}

FileResultsOutput is the standard container for file analysis results.

type FileScores added in v1.6.0 

type FileScores struct {
	AnalysisTime    time.Time
	HotScore        float64  // hot mode score
	RiskScore       float64  // risk mode score
	ComplexityScore float64  // complexity mode score
	ROIScore        float64  // roi mode score
	ScoreLabel      string   // current mode name
	Reasoning       []string // justifications for the current score
}

FileScores represents final computed scores for a single file.

type FileScoresMetricsRecord added in v1.8.0 

type FileScoresMetricsRecord struct {
	AnalysisID             int64
	FilePath               string
	AnalysisTime           time.Time
	TotalCommits           Metric
	TotalChurn             Metric
	LinesAdded             Metric
	LinesDeleted           Metric
	DecayedCommits         Metric
	DecayedChurn           Metric
	LinesOfCode            Metric
	ContributorCount       Metric
	RecentCommits          Metric
	RecentChurn            Metric
	RecentLinesAdded       Metric
	RecentLinesDeleted     Metric
	RecentContributorCount Metric
	AgeDays                Metric
	GiniCoefficient        float64
	FileOwner              *string
	ScoreHot               float64
	ScoreRisk              float64
	ScoreComplexity        float64
	ScoreROI               float64
	ScoreLabel             string
	Reasoning              []string
	RecencySignal          float64
	RecencyThresholdLow    float64
	RecencyThresholdHigh   float64
}

FileScoresMetricsRecord represents a row from the hotspot_file_scores_metrics table.

type FolderComparison added in v0.4.3 

type FolderComparison struct{}

FolderComparison has folder deltas.

type FolderResult added in v0.5.0 

type FolderResult struct {
	Path               string   `json:"path"`                // Relative path to the folder in the repository
	Commits            Metric   `json:"commits"`             // Total number of commits across all contained files
	Churn              Metric   `json:"churn"`               // Total number of lines added/deleted across all contained files
	DecayedCommits     Metric   `json:"decayed_commits"`     // Time-weighted commits across all contained files
	DecayedChurn       Metric   `json:"decayed_churn"`       // Time-weighted churn across all contained files
	Score              float64  `json:"score"`               // Computed importance score for the folder
	Gini               float64  `json:"gini"`                // Gini coefficient of commit distribution in the folder
	UniqueContributors Metric   `json:"unique_contributors"` // Number of unique contributors in the folder
	Owners             []string `json:"owners"`              // Top 2 owners by commit count

	TotalLOC         Metric      `json:"total_loc"`          // Sum of LOC of all contained files (used for weighted average)
	WeightedScoreSum float64     `json:"weighted_score_sum"` // Sum of (FileScore * FileLOC)
	Mode             ScoringMode `json:"mode"`               // Scoring mode used (hot, risk, complexity, roi)
}

FolderResult holds the final computed scores and aggregated metrics for a folder.

func (FolderResult) GetChurn added in v0.9.1 

func (f FolderResult) GetChurn() Metric

GetChurn returns the total churn.

func (FolderResult) GetCommits added in v0.9.1 

func (f FolderResult) GetCommits() Metric

GetCommits returns the total commit count.

func (FolderResult) GetOwners added in v1.1.0 

func (f FolderResult) GetOwners() []string

GetOwners returns the top owners.

func (FolderResult) GetPath added in v0.9.1 

func (f FolderResult) GetPath() string

GetPath returns the folder path.

func (FolderResult) GetScore added in v0.9.1 

func (f FolderResult) GetScore() float64

GetScore returns the computed score.

type FolderResultsOutput added in v1.14.0 

type FolderResultsOutput struct {
	Results  []EnrichedFolderResult `json:"results"`
	Metadata Metadata               `json:"metadata"`
}

FolderResultsOutput is the standard container for folder analysis results.

type JourneyResult added in v1.16.0 

type JourneyResult struct {
	Summary JourneySummary `json:"summary"` // High-level overview
	Steps   []JourneyStep  `json:"steps"`   // Per-transition details, newest first
}

JourneyResult is the top-level response for the get_release_journey MCP tool.

type JourneyResultsOutput added in v1.20.0 

type JourneyResultsOutput struct {
	Results  JourneyResult `json:"results"`
	Metadata Metadata      `json:"metadata"`
}

JourneyResultsOutput is the standard container for release journey analysis results.

type JourneyStep added in v1.16.0 

type JourneyStep struct {
	BaseRef   string           `json:"base_ref"`   // Starting tag/ref
	TargetRef string           `json:"target_ref"` // Ending tag/ref
	Result    ComparisonResult `json:"result"`     // Full comparison details and summary
}

JourneyStep represents the hotspot delta between two successive releases.

type JourneySummary added in v1.16.0 

type JourneySummary struct {
	TotalSteps         int     `json:"total_steps"`          // Number of transitions analyzed
	TotalNewFiles      int     `json:"total_new_files"`      // Cumulative new files across all steps
	TotalInactiveFiles int     `json:"total_inactive_files"` // Cumulative retired files
	NetScoreDelta      float64 `json:"net_score_delta"`      // Sum of all step score deltas
	PeakDeltaStep      string  `json:"peak_delta_step"`      // Transition with the largest net score delta
	Mode               string  `json:"mode"`                 // Scoring mode used
}

JourneySummary provides an aggregated overview across all steps.

type Metadata added in v1.14.0 

type Metadata struct {
	AnalysisDuration time.Duration `json:"analysis_duration_ns"`
	AnalysisTime     string        `json:"analysis_duration"`
	Workers          int           `json:"workers"`
	CacheBackend     string        `json:"cache_backend"`
	Timestamp        time.Time     `json:"timestamp"`
}

Metadata contains runtime information about the analysis.

func BuildMetadata added in v1.14.0 

func BuildMetadata(runtime RuntimeSettings, duration time.Duration) Metadata

BuildMetadata constructs a standard metadata object from runtime and duration.

type Metric added in v1.14.0 

type Metric float64

Metric is a smart numeric type for the Hotspot engine. It serves as the core magnitude unit across the entire pipeline.

Key Responsibilities:

  1. Captures continuous magnitudes (e.g., fractional churn/commits).
  2. Bridges V6 DB migration via sql.Scanner and driver.Valuer.
  3. JSON marshals whole numbers as integers for backward compatibility.
  4. Supports .Display() with intelligent formatting for fractions.

This architecture makes Hotspot "Sponge-Ready"—capable of ingesting and blending fuzzy or weighted signals from non-git sources like JIRA, Slack, or CI logs.

func (Metric) Display added in v1.14.0 

func (n Metric) Display() string

Display returns a human-friendly string representation. It hides decimals for whole numbers and uses sensible precision for fractions.

func (Metric) Float64 added in v1.14.0 

func (n Metric) Float64() float64

Float64 returns the underlying float64 value.

func (Metric) Int added in v1.14.0 

func (n Metric) Int() int

Int returns the value as a rounded integer.

func (Metric) MarshalJSON added in v1.14.0 

func (n Metric) MarshalJSON() ([]byte, error)

MarshalJSON implements custom JSON marshaling to avoid decimal noise for whole numbers.

func (*Metric) Scan added in v1.14.0 

func (n *Metric) Scan(src any) error

Scan implements the sql.Scanner interface for database retrieval.

func (Metric) String added in v1.14.0 

func (n Metric) String() string

String implements the fmt.Stringer interface.

func (*Metric) UnmarshalJSON added in v1.14.0 

func (n *Metric) UnmarshalJSON(data []byte) error

UnmarshalJSON implements custom JSON unmarshaling.

func (Metric) Value added in v1.14.0 

func (n Metric) Value() (driver.Value, error)

Value implements the driver.Valuer interface for database persistence.

type MetricsMode added in v1.2.0 

type MetricsMode struct {
	Name       string             `json:"name"`
	Purpose    string             `json:"purpose"`
	Factors    []string           `json:"factors"`
	FactorKeys []string           `json:"factor_keys,omitempty"` // Only used for JSON output
	Weights    map[string]float64 `json:"weights,omitempty"`     // Only used for JSON output
	Formula    string             `json:"formula,omitempty"`     // Only used for JSON output
}

MetricsMode represents a scoring mode for display purposes.

type MetricsModeWithData added in v1.2.0 

type MetricsModeWithData struct {
	MetricsMode
	Weights map[string]float64 `json:"weights"`
	Formula string             `json:"formula"`
}

MetricsModeWithData extends MetricsMode with computed weights and formula.

type MetricsRenderModel added in v1.2.0 

type MetricsRenderModel struct {
	Title               string                `json:"title"`
	Description         string                `json:"description"`
	Modes               []MetricsModeWithData `json:"modes"`
	SpecialRelationship map[string]string     `json:"special_relationship"`
}

MetricsRenderModel contains all processed data needed for displaying metrics definitions.

func BuildMetricsRenderModel added in v1.14.0 

func BuildMetricsRenderModel(activeWeights map[ScoringMode]map[BreakdownKey]float64) *MetricsRenderModel

BuildMetricsRenderModel constructs the complete render model with all processed data.

type OutputMode added in v1.1.2 

type OutputMode string

OutputMode represents the format of the output. 

const (
	CSVOut      OutputMode = "csv"
	TextOut     OutputMode = "text" // default
	JSONOut     OutputMode = "json"
	ParquetOut  OutputMode = "parquet"
	Describe    OutputMode = "describe"
	MarkdownOut OutputMode = "markdown"
	HeatmapOut  OutputMode = "heatmap"
	NoneOut     OutputMode = "none"
)

All output modes supported.

type PathMatcher added in v1.18.0 

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

PathMatcher provides efficient path matching against a set of exclude patterns. It pre-processes patterns to avoid redundant string operations during matching.

func NewPathMatcher added in v1.18.0 

func NewPathMatcher(excludes []string) *PathMatcher

NewPathMatcher creates a new PathMatcher from a set of exclude patterns.

func (*PathMatcher) Match added in v1.18.0 

func (m *PathMatcher) Match(path string) bool

Match returns true if the path matches any of the exclude patterns.

type Preset added in v1.15.0 

type Preset struct {
	Name                 PresetName  `json:"name"`
	Description          string      `json:"description"`
	Mode                 ScoringMode `json:"mode"`
	Limit                int         `json:"limit"`
	Workers              int         `json:"workers"`
	Follow               bool        `json:"follow"`
	Detail               bool        `json:"detail"`
	Start                string      `json:"start,omitempty"` // relative time string, e.g. "2 years ago"
	Transitions          int         `json:"transitions"`     // Suggested value for get_release_journey
	RecencyThresholdLow  float64     `json:"recency_threshold_low"`
	RecencyThresholdHigh float64     `json:"recency_threshold_high"`
	Exclude              string      `json:"exclude,omitempty"`
	Output               OutputMode  `json:"output,omitempty"`
	Color                bool        `json:"color,omitempty"`
	Owner                bool        `json:"owner,omitempty"`
	Precision            int         `json:"precision,omitempty"`
	Explain              bool        `json:"explain,omitempty"`
}

Preset is a named collection of recommended configuration defaults derived from the example configuration files in examples/cli/.

func AllPresets added in v1.15.0 

func AllPresets() []Preset

AllPresets returns all defined presets in a stable order.

func GetPreset added in v1.15.0 

func GetPreset(name PresetName) Preset

GetPreset returns the Preset definition for a given name from the YAML config.

type PresetName added in v1.15.0 

type PresetName string

PresetName identifies a named configuration preset. 

const (
	PresetSmall PresetName = "small"
	PresetLarge PresetName = "large"
	PresetInfra PresetName = "infra"
)

Named configuration presets.

type RepoShape added in v1.15.0 

type RepoShape struct {
	URN                string     `json:"urn,omitempty"`
	FileCount          int        `json:"file_count"`
	TotalCommits       float64    `json:"total_commits"`
	UniqueContributors int        `json:"unique_contributors"`
	AvgChurnPerFile    float64    `json:"avg_churn_per_file"`
	IaCFileRatio       float64    `json:"iac_file_ratio"`
	RecommendedPreset  PresetName `json:"recommended_preset"`
	Reasoning          []string   `json:"reasoning,omitempty"`
	Preset             Preset     `json:"preset"`
	AnalyzedAt         time.Time  `json:"analyzed_at"`
}

RepoShape captures key metrics from the first aggregation pass to characterize a repository.

type RepoShapeOutput added in v1.20.0 

type RepoShapeOutput struct {
	Results  RepoShape `json:"results"`
	Metadata Metadata  `json:"metadata"`
}

RepoShapeOutput is the standard container for repository shape analysis results.

type RuntimeSettings added in v1.14.0 

type RuntimeSettings interface {
	GetWorkers() int
	GetCacheBackend() DatabaseBackend
}

RuntimeSettings matches the minimal interface needed for metadata building.

type ScoringMode added in v1.1.2 

type ScoringMode string

ScoringMode represents the scoring mode used. 

const (
	HotMode        ScoringMode = "hot" // default
	RiskMode       ScoringMode = "risk"
	ComplexityMode ScoringMode = "complexity"
	ROIMode        ScoringMode = "roi"
)

All scoring modes supported.

type ShapeTemplates added in v1.19.0 

type ShapeTemplates struct {
	Infra             string
	LargeFiles        string
	LargeContributors string
	Compounding       string
	Small             string
}

ShapeTemplates returns the reasoning templates for shape analysis.

func GetShapeTemplates added in v1.19.0 

func GetShapeTemplates() ShapeTemplates

GetShapeTemplates returns the reasoning templates defined in shape_heuristics.yaml.

type ShapeThresholds added in v1.19.0 

type ShapeThresholds struct {
	IaCRatio         float64
	FileCount        int
	ContributorCount int
}

ShapeThresholds returns the configuration thresholds for shape analysis.

func GetShapeThresholds added in v1.19.0 

func GetShapeThresholds() ShapeThresholds

GetShapeThresholds returns the thresholds defined in shape_heuristics.yaml.

type SingleAnalysisOutput added in v0.5.0 

type SingleAnalysisOutput struct {
	FileResults   []FileResult
	FolderResults []FolderResult
	*AggregateOutput
}

SingleAnalysisOutput is for one of the core algorithms.

type Status added in v1.1.2 

type Status string

Status represents the status of a file. 

const (
	NewStatus      Status = "new"
	ActiveStatus   Status = "active"
	InactiveStatus Status = "inactive"
	UnknownStatus  Status = "unknown"
)

All status supported.

type TimeseriesPoint added in v0.9.0 

type TimeseriesPoint struct {
	Period   string        `json:"period"`
	Start    time.Time     `json:"start"`
	End      time.Time     `json:"end"`
	Score    float64       `json:"score"`
	Path     string        `json:"path"`
	Owners   []string      `json:"owners"`   // Top owners for this time period
	Mode     ScoringMode   `json:"mode"`     // Scoring mode (hot, risk, complexity, roi)
	Lookback time.Duration `json:"lookback"` // Dynamic lookback duration for this point
}

TimeseriesPoint represents a single data point in the timeseries.

type TimeseriesResult added in v0.9.0 

type TimeseriesResult struct {
	Points []TimeseriesPoint `json:"points"`
}

TimeseriesResult holds the timeseries data points.

type TimeseriesResultsOutput added in v1.20.0 

type TimeseriesResultsOutput struct {
	Results  TimeseriesResult `json:"results"`
	Metadata Metadata         `json:"metadata"`
}

TimeseriesResultsOutput is the standard container for timeseries analysis results.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.