ui

package
v0.1.2 Latest Latest
Warning

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

 Go to latest Published: Jul 30, 2026 License: MPL-2.0 Imports: 31 Imported by: 0

Documentation

Overview

Package ui provides the interactive TUI for displaying metrics.

Index

Constants

View Source 
const (
	SortByCorrelation = "correlation"
	SortByDivergence  = "divergence"
	SortByNMI         = "nmi"
)

Sort key strings for --sort. Stable identifiers — appear on the CLI surface and are matched as-is.

View Source 
const (
	SigmaModeManual = "manual"
	SigmaModeAuto   = "auto"
)

SigmaMode distinguishes user-supplied sigma from picker-derived sigma in JSON output. Stable strings — downstream consumers may branch on them.

View Source 
const MIBiasCorrection = "miller-madow"

MIBiasCorrection labels the bias-correction strategy used for the NMI metric. Stable string — downstream consumers branch on it. v1 ships "miller-madow" only.

Variables

This section is empty.

Functions

func CouplingJSON 

func CouplingJSON(report CouplingReport, filter *regexp.Regexp) (string, error)

CouplingJSON returns the coupling report as indented JSON.

func CouplingTable 

func CouplingTable(report CouplingReport, filter *regexp.Regexp) string

CouplingTable renders the coupling report as a single-line sigma header followed by a lipgloss table of pairs.

func FilterCouplingPairs 

func FilterCouplingPairs(
	pairs []evocoupling.CouplingPair,
	pattern *regexp.Regexp,
) []evocoupling.CouplingPair

FilterCouplingPairs returns pairs where at least one package matches pattern.

func FilterMetrics 

func FilterMetrics(metrics []analyzer.Metrics, pattern *regexp.Regexp) []analyzer.Metrics

FilterMetrics returns the subset of metrics whose package matches the regex. A nil regex passes the slice through unchanged.

func GetLanguages 

func GetLanguages(commits []history.CommitMetrics) []string

GetLanguages returns unique languages from commit metrics.

func LintJSON 

func LintJSON(report LintReport) (string, error)

LintJSON renders the report as indented JSON.

func LintText 

func LintText(report LintReport) string

LintText renders the report through lintTextTemplate.

func MIHeaderLine 

func MIHeaderLine(sel MISelection) string

MIHeaderLine renders a one-line MI summary for the text format header. Example: "MI: 12 bins of 14d, min support 3 (miller-madow)".

func MetricsJSON 

func MetricsJSON(
	groups []LanguageMetrics,
	criteria []SortCriterion,
	filter *regexp.Regexp,
) (string, error)

MetricsJSON renders the per-language metrics groups as indented JSON in the simplified table-friendly schema (package + inward/outward counts + instability).

func MetricsJSONExtended 

func MetricsJSONExtended(groups []LanguageMetrics, filter *regexp.Regexp) (string, error)

MetricsJSONExtended returns the full metrics data including detailed coupling information (which packages, what symbols, usage counts, and positions).

func MetricsTable 

func MetricsTable(
	groups []LanguageMetrics,
	criteria []SortCriterion,
	filter *regexp.Regexp,
) string

MetricsTable returns the metrics as styled terminal tables, one per language, sorted by the given criteria.

func MetricsTableWithHotspots 

func MetricsTableWithHotspots(
	groups []LanguageMetrics,
	criteria []SortCriterion,
	filter *regexp.Regexp,
) string

MetricsTableWithHotspots returns tables including hotspot columns.

func PrintHistoryTable 

func PrintHistoryTable(w io.Writer, commits []history.CommitMetrics)

PrintHistoryTable prints charts to the given writer.

func RenderHistoryTable 

func RenderHistoryTable(commits []history.CommitMetrics, width int) string

RenderHistoryTable renders charts for all packages non-interactively. This is useful for debugging chart rendering without TUI interaction.

func ReviewJSON 

func ReviewJSON(r ReviewResult) (string, error)

ReviewJSON renders a ReviewResult as JSON: the changed packages plus any co-change advisories.

func ReviewTable 

func ReviewTable(r ReviewResult) string

ReviewTable renders a ReviewResult as a table (dependency changes as text + summary as table).

func ReviewText 

func ReviewText(r ReviewResult) string

ReviewText renders a ReviewResult as plain text. Only packages with actual changes are shown; unchanged packages are omitted.

func RunHistoryInteractive 

func RunHistoryInteractive(
	commits []history.CommitMetrics,
	fetcher MetricsFetcher,
	workspaceCheckout WorkspaceCheckout,
) error

RunHistoryInteractive launches the interactive TUI for history metrics.

func RunInteractive 

func RunInteractive(
	groups []LanguageMetrics,
	criteria []SortCriterion,
	filter *regexp.Regexp,
) error

RunInteractive launches the interactive TUI for metrics display.

func RunInteractiveWithLoading 

func RunInteractiveWithLoading(
	ctx context.Context,
	analyzers []analyzer.Analyzer,
	dir fs.FS,
	criteria []SortCriterion,
	filter *regexp.Regexp,
	rootDir string,
	enricher PostAnalysisFunc,
) error

RunInteractiveWithLoading launches the interactive TUI with a loading screen that displays while the analyzers run. The enricher callback, if non-nil, is called after analysis to enrich groups with additional data (e.g. hotspots).

func RunReviewInteractive 

func RunReviewInteractive(r ReviewResult) error

RunReviewInteractive launches the interactive TUI for the review command.

func SigmaHeaderLine 

func SigmaHeaderLine(sel SigmaSelection) string

SigmaHeaderLine renders a one-line sigma summary for the text/table format header. Examples: 

Sigma: 14d 0h (auto, target ±0.05, ESS=412)
Sigma: 14d (manual)
Sigma: 30d (auto, target ±0.05, ESS=87, low confidence: insufficient_commits)

func SortCouplingPairs 

func SortCouplingPairs(pairs []evocoupling.CouplingPair, key string) []evocoupling.CouplingPair

SortCouplingPairs returns pairs re-sorted by the requested key. NMI / divergence sort puts nil-valued pairs (NaN-suppressed, MI-not-computed) at the bottom — they carry no signal for the requested axis. Unknown sort keys are treated as correlation (Analyze's default order, already applied upstream).

func SortIndicator 

func SortIndicator(criteria []SortCriterion, field SortField) string

SortIndicator returns a sort direction indicator for column headers.

func SortMetrics 

func SortMetrics(metrics []analyzer.Metrics, fns ...SortFunc) []analyzer.Metrics

SortMetrics sorts a copy of metrics by applying sort functions in order. The first non-zero result wins (multi-key sort).

Types

type CommitTouchInfo 

type CommitTouchInfo struct {
	SHA       string           `json:"sha"`
	Message   string           `json:"message"`
	Timestamp time.Time        `json:"timestamp"`
	Files     []FileChangeStat `json:"files"`
}

CommitTouchInfo holds info about a commit that touched a package.

type CouplingReport 

type CouplingReport struct {
	SigmaSelection SigmaSelection             `json:"sigma_selection"`
	MISelection    *MISelection               `json:"mi_selection,omitempty"`
	Pairs          []evocoupling.CouplingPair `json:"pairs"`
}

CouplingReport is the top-level coupling output surface: sigma metadata plus the ranked pairs.

type FileChangeStat 

type FileChangeStat struct {
	Path      string `json:"path"`
	Additions int    `json:"additions"`
	Deletions int    `json:"deletions"`
}

FileChangeStat holds change stats for a single file.

type HotspotData 

type HotspotData struct {
	Scores  map[string]hotspot.PackageScore `json:"scores"`
	Commits map[string][]CommitTouchInfo    `json:"commits,omitempty"`
}

HotspotData carries hotspot analysis results for a language group.

type HotspotLanguageMetricsSummary 

type HotspotLanguageMetricsSummary struct {
	Language string                  `json:"language"`
	Metrics  []HotspotMetricsSummary `json:"metrics"`
}

HotspotLanguageMetricsSummary pairs a language with its HotspotMetricsSummary records.

type HotspotMetricsSummary 

type HotspotMetricsSummary struct {
	Package     string  `json:"package"`
	Inward      int     `json:"inward"`
	Outward     int     `json:"outward"`
	Instability float64 `json:"instability"`
	ChangeFreq  float64 `json:"change_freq,omitempty"`
	Hotspot     float64 `json:"hotspot,omitempty"`
}

HotspotMetricsSummary extends MetricsSummary with hotspot fields. Returned alongside the table format (package, inward count, outward count, instability) when hotspot analysis is enabled.

type LanguageMetrics 

type LanguageMetrics struct {
	Language string             `json:"language"`
	Metrics  []analyzer.Metrics `json:"metrics"`
	Hotspots *HotspotData       `json:"hotspots,omitempty"`
}

LanguageMetrics pairs a language name with its metrics.

type LanguageMetricsSummary 

type LanguageMetricsSummary = analyzer.LanguageMetricsSummary

LanguageMetricsSummary pairs a language with its MetricsSummary records (re-export from analyzer).

type LanguageTimeSeries 

type LanguageTimeSeries struct {
	Language string
	Series   []PackageTimeSeries
}

LanguageTimeSeries groups time series by language.

func TransformToTimeSeries 

func TransformToTimeSeries(commits []history.CommitMetrics) []LanguageTimeSeries

TransformToTimeSeries converts commit metrics to per-package time series. Returns a map of language -> []PackageTimeSeries.

type LintLanguageReport 

type LintLanguageReport struct {
	Language   string          `json:"language"`
	Violations []LintViolation `json:"violations"`
}

LintLanguageReport groups violations for one language block.

type LintReport 

type LintReport struct {
	Languages []LintLanguageReport `json:"languages"`
}

LintReport is the full lint verdict across language blocks.

func (LintReport) Total 

func (r LintReport) Total() int

Total returns the number of violations across all languages.

type LintViolation 

type LintViolation struct {
	Kind string `json:"kind"`
	Edge string `json:"edge"`
	Rule string `json:"rule,omitempty"`
}

LintViolation is one gate failure, shaped for output.

type MISelection 

type MISelection struct {
	Enabled         bool    `json:"enabled"`
	BinWidthSeconds float64 `json:"bin_width_seconds"`
	NBins           int     `json:"n_bins"`
	MinSupport      int     `json:"min_support"`
	BiasCorrection  string  `json:"bias_correction"`
	// LowConfidence is true when the bin count is too small for MI to be
	// meaningful — design doc open question 4, floor at 8 bins.
	LowConfidence bool `json:"low_confidence,omitempty"`
}

MISelection describes the MI pass parameters. Populated only when MI is enabled (omitempty drops the block from the JSON for the v1 default-off path). Mirrors the sigma_selection shape so reviewers reading the JSON see one consistent metadata surface.

type MetricsFetcher 

type MetricsFetcher func(ctx context.Context, sha string) ([]history.LanguageMetrics, error)

MetricsFetcher fetches full metrics for a commit SHA. Returns metrics grouped by language, or an error.

type MetricsSummary 

type MetricsSummary = analyzer.MetricsSummary

MetricsSummary is the simplified per-package metrics record (re-export from analyzer).

type PackageDataPoint 

type PackageDataPoint struct {
	SHA         string
	Timestamp   time.Time
	Message     string
	Inward      int
	Outward     int
	Instability float64
}

PackageDataPoint holds metrics for a single package at a single commit.

type PackageTimeSeries 

type PackageTimeSeries struct {
	Package      string
	Language     string
	DataPoints   []PackageDataPoint
	ChangeFreq   float64 // from hotspot analysis (0 when no hotspot data)
	HotspotScore float64 // from hotspot analysis (0 when no hotspot data)
}

PackageTimeSeries holds time series data for a single package.

func FilterByLanguage 

func FilterByLanguage(all []LanguageTimeSeries, lang string) []PackageTimeSeries

FilterByLanguage returns time series for a specific language.

type PostAnalysisFunc 

type PostAnalysisFunc func(groups []LanguageMetrics, analyzers []analyzer.Analyzer) error

PostAnalysisFunc is an optional callback invoked after analysis completes but before the results are sent to the UI. It enriches the groups in-place (e.g. with hotspot data).

type ReviewResult 

type ReviewResult struct {
	BaseLabel  string
	HeadLabel  string
	Diffs      []diff.PackageDiff
	PrevAll    []analyzer.Metrics
	CurrAll    []analyzer.Metrics
	Advisories []evocoupling.Advisory
}

ReviewResult holds everything needed to render a review.

type SigmaSelection 

type SigmaSelection struct {
	Mode              string  `json:"mode"`
	SigmaSeconds      float64 `json:"sigma_seconds"`
	SigmaHuman        string  `json:"sigma_human"`
	TargetStddev      float64 `json:"target_stddev"`
	RequiredESS       float64 `json:"required_ess"`
	AchievedESSMedian float64 `json:"achieved_ess_median"`
	AchievedESSP25    float64 `json:"achieved_ess_p25"`
	LowConfidence     bool    `json:"low_confidence"`
	Reason            string  `json:"reason,omitempty"`
	DensityCapSeconds float64 `json:"density_cap_seconds,omitempty"`
	DensityCapHuman   string  `json:"density_cap_human,omitempty"`
}

SigmaSelection describes how the kernel bandwidth was chosen. Populated for both manual (--sigma) and auto modes — the auto-derivation fields are always present so a reviewer reading the JSON can see what the picker would have chosen even when overridden.

type SortCriterion 

type SortCriterion struct {
	Field     SortField
	Direction SortDirection
}

SortCriterion pairs a field with a direction.

func DefaultSort 

func DefaultSort() []SortCriterion

DefaultSort returns the default sort: instability desc, outward desc, inward desc.

func ParseSort 

func ParseSort(s string) ([]SortCriterion, error)

ParseSort parses a sort string like "package:asc,instability:desc".

func ToggleSort 

func ToggleSort(current []SortCriterion, field SortField) []SortCriterion

ToggleSort cycles sort on a field: first press → asc, second → desc, third → reset to default.

type SortDirection 

type SortDirection int

SortDirection is ascending or descending. 

const (
	Asc  SortDirection = iota
	Desc SortDirection = iota
)

SortDirection enum: ascending or descending.

type SortField 

type SortField int

SortField identifies a column to sort by. 

const (
	SortPackage     SortField = iota
	SortInward      SortField = iota
	SortOutward     SortField = iota
	SortInstability SortField = iota
	SortChangeFreq  SortField = iota
	SortHotspot     SortField = iota
)

SortField enum: the column identifiers the metrics table can sort by.

type SortFunc 

type SortFunc func(a, b analyzer.Metrics) int

SortFunc compares two metrics, returning negative/zero/positive.

func BuildSortFuncs 

func BuildSortFuncs(criteria []SortCriterion, scores map[string]hotspot.PackageScore) []SortFunc

BuildSortFuncs converts criteria into a SortFunc slice. Scores may be nil; change_freq/hotspot criteria are skipped when nil.

func ByChangeFreq 

func ByChangeFreq(scores map[string]hotspot.PackageScore, dir SortDirection) SortFunc

ByChangeFreq returns a SortFunc that sorts by change frequency.

func ByField 

func ByField(field SortField, dir SortDirection) SortFunc

ByField returns a SortFunc for a built-in field with direction. For SortChangeFreq/SortHotspot it returns a no-op (use ByChangeFreq/ByHotspot instead).

func ByHotspot 

func ByHotspot(scores map[string]hotspot.PackageScore, dir SortDirection) SortFunc

ByHotspot returns a SortFunc that sorts by hotspot score.

type WorkspaceCheckout 

type WorkspaceCheckout func(sha string) (workspacePath string, err error)

WorkspaceCheckout checks out a commit in the workspace and returns the workspace path. This is used to open files from a specific commit's snapshot in the editor.

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.