Documentation
¶
Overview ¶
Package impact provides unified change impact analysis for Trace.
Description ¶
This package orchestrates multiple analysis tools (blast radius, breaking changes, test coverage, side effects, data flow) to provide a comprehensive "what happens if I change this?" report. It is designed to be the primary tool agents use before making changes.
Thread Safety ¶
All types in this package are safe for concurrent use after initialization.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrInvalidInput indicates invalid input parameters. ErrInvalidInput = errors.New("invalid input") // ErrSymbolNotFound indicates the target symbol was not found. ErrSymbolNotFound = errors.New("symbol not found") // ErrGraphNotReady indicates the graph is not frozen or not available. ErrGraphNotReady = errors.New("graph not ready") // ErrContextCanceled indicates the context was canceled. ErrContextCanceled = errors.New("context canceled") // ErrAnalysisFailed indicates one or more analyses failed. ErrAnalysisFailed = errors.New("analysis failed") )
Sentinel errors for the impact package.
Functions ¶
This section is empty.
Types ¶
type AnalyzeOptions ¶
type AnalyzeOptions struct {
// IncludeBreaking enables breaking change analysis (requires proposed change).
IncludeBreaking bool
// IncludeBlastRadius enables blast radius analysis.
IncludeBlastRadius bool
// IncludeCoverage enables test coverage analysis.
IncludeCoverage bool
// IncludeSideEffects enables side effect analysis.
IncludeSideEffects bool
// IncludeDataFlow enables data flow analysis.
IncludeDataFlow bool
// MaxCallers limits the number of callers to analyze.
MaxCallers int
// MaxHops limits the depth of indirect caller analysis.
MaxHops int
// IncludeDetailedSideEffects includes full side effect details in response.
IncludeDetailedSideEffects bool
// IncludeFileLists includes file lists in response.
IncludeFileLists bool
}
AnalyzeOptions configures the impact analysis.
func DefaultAnalyzeOptions ¶
func DefaultAnalyzeOptions() AnalyzeOptions
DefaultAnalyzeOptions returns options with all analyses enabled.
func QuickAnalyzeOptions ¶
func QuickAnalyzeOptions() AnalyzeOptions
QuickAnalyzeOptions returns options for fast analysis (blast radius + coverage only).
type ChangeImpact ¶
type ChangeImpact struct {
// TargetID is the symbol being analyzed.
TargetID string `json:"target_id"`
// TargetName is the human-readable name of the target.
TargetName string `json:"target_name"`
// ProposedChange describes what change is being analyzed.
// May be a new signature, description, or empty for general impact.
ProposedChange string `json:"proposed_change,omitempty"`
// IsBreaking indicates if the proposed change would break callers.
IsBreaking bool `json:"is_breaking"`
// BreakingChanges lists specific breaking changes detected.
BreakingChanges []reason.BreakingChange `json:"breaking_changes,omitempty"`
// DirectCallers is the count of functions that directly call the target.
DirectCallers int `json:"direct_callers"`
// IndirectCallers is the count of functions that transitively call the target.
IndirectCallers int `json:"indirect_callers"`
// TotalImpact is the total number of symbols affected (direct + indirect + implementers).
TotalImpact int `json:"total_impact"`
// FilesAffected lists unique files that may need changes.
FilesAffected []string `json:"files_affected,omitempty"`
// BlastRiskLevel is the risk level from blast radius analysis.
BlastRiskLevel analysis.RiskLevel `json:"blast_risk_level"`
// TestsCovering is the count of tests that cover this symbol.
TestsCovering int `json:"tests_covering"`
// CoverageLevel indicates how well the symbol is tested.
CoverageLevel CoverageLevel `json:"coverage_level"`
// TestFiles lists test files that should be run after changes.
TestFiles []string `json:"test_files,omitempty"`
// HasSideEffects indicates if the target has external effects.
HasSideEffects bool `json:"has_side_effects"`
// SideEffectCount is the total number of side effects.
SideEffectCount int `json:"side_effect_count"`
// SideEffectTypes lists the categories of side effects (file_io, network, etc.).
SideEffectTypes []string `json:"side_effect_types,omitempty"`
// SideEffects contains detailed side effect information.
SideEffects []reason.SideEffect `json:"side_effects,omitempty"`
// DataSinks lists where data from this function ends up (response, DB, file, etc.).
DataSinks []string `json:"data_sinks,omitempty"`
// RiskLevel is the overall risk assessment.
RiskLevel RiskLevel `json:"risk_level"`
// RiskScore is the numeric risk score (0.0 = safe, 1.0 = very risky).
RiskScore float64 `json:"risk_score"`
// Confidence is how confident we are in the analysis (0.0-1.0).
Confidence float64 `json:"confidence"`
// SuggestedActions lists recommended actions before making the change.
SuggestedActions []string `json:"suggested_actions"`
// Warnings contains important warnings about the change.
Warnings []string `json:"warnings,omitempty"`
// Limitations lists what we couldn't analyze.
Limitations []string `json:"limitations,omitempty"`
}
ChangeImpact is the unified result of change impact analysis.
Description ¶
Combines results from blast radius, breaking change, test coverage, side effect, and data flow analysis into a single actionable report. Includes an overall risk score and suggested actions.
Thread Safety ¶
ChangeImpact is immutable after creation.
type ChangeImpactAnalyzer ¶
type ChangeImpactAnalyzer struct {
// contains filtered or unexported fields
}
ChangeImpactAnalyzer orchestrates multiple analysis tools to provide comprehensive change impact assessment.
Description ¶
ChangeImpactAnalyzer combines blast radius, breaking change, test coverage, side effect, and data flow analysis into a single unified report. It runs independent analyses in parallel for performance.
Thread Safety ¶
ChangeImpactAnalyzer is safe for concurrent use after initialization.
func NewChangeImpactAnalyzer ¶
func NewChangeImpactAnalyzer(g *graph.Graph, idx *index.SymbolIndex) *ChangeImpactAnalyzer
NewChangeImpactAnalyzer creates a new analyzer with all sub-analyzers.
Description ¶
Creates an analyzer that orchestrates blast radius, breaking change, test coverage, side effect, and data flow analysis.
Inputs ¶
- g: Code graph. Must be frozen before calling AnalyzeImpact.
- idx: Symbol index for lookups.
Outputs ¶
- *ChangeImpactAnalyzer: Ready-to-use analyzer.
Example ¶
analyzer := impact.NewChangeImpactAnalyzer(graph, index) result, err := analyzer.AnalyzeImpact(ctx, "pkg.Function", "func(ctx, new) error", nil)
func (*ChangeImpactAnalyzer) AnalyzeImpact ¶
func (a *ChangeImpactAnalyzer) AnalyzeImpact( ctx context.Context, targetID string, proposedChange string, opts *AnalyzeOptions, ) (*ChangeImpact, error)
AnalyzeImpact performs comprehensive change impact analysis.
Description ¶
Orchestrates multiple analysis tools to provide a unified view of what would happen if the target symbol is changed. Runs independent analyses in parallel for performance. The proposed change is optional - if not provided, breaking change analysis is skipped.
Inputs ¶
- ctx: Context for cancellation and timeout.
- targetID: Symbol ID to analyze (e.g., "pkg/auth.go:10:ValidateToken").
- proposedChange: Optional new signature for breaking change analysis.
- opts: Analysis options (nil uses defaults).
Outputs ¶
- *ChangeImpact: Unified analysis results.
- error: Non-nil if validation fails or all analyses fail.
Performance ¶
Target latency: < 500ms for typical codebase. Independent analyses run in parallel.
Example ¶
result, err := analyzer.AnalyzeImpact(ctx,
"handlers/user.go:10:HandleUser",
"func(ctx context.Context, req *Request) (*Response, error)",
nil,
)
if err != nil {
return err
}
fmt.Printf("Risk: %s (%.2f)\n", result.RiskLevel, result.RiskScore)
for _, action := range result.SuggestedActions {
fmt.Printf("- %s\n", action)
}
Limitations ¶
- Breaking change analysis requires proposedChange to be provided.
- Data flow analysis is function-level, not variable-level.
- Side effect detection uses pattern matching, may miss dynamic calls.
func (*ChangeImpactAnalyzer) WithRiskWeights ¶
func (a *ChangeImpactAnalyzer) WithRiskWeights(w RiskWeights) *ChangeImpactAnalyzer
WithRiskWeights sets custom risk calculation weights.
Description ¶
Allows customizing how different factors contribute to the overall risk score. Returns the analyzer for method chaining.
Example ¶
analyzer := impact.NewChangeImpactAnalyzer(g, idx).WithRiskWeights(RiskWeights{
Breaking: 0.40, // Increase weight of breaking changes
BlastRadius: 0.20,
TestCoverage: 0.20,
SideEffects: 0.10,
Exported: 0.10,
})
type CoverageLevel ¶
type CoverageLevel string
CoverageLevel indicates how well a symbol is tested.
const ( // CoverageGood indicates the symbol has direct test coverage. CoverageGood CoverageLevel = "good" // CoveragePartial indicates indirect coverage only. CoveragePartial CoverageLevel = "partial" // CoverageNone indicates no test coverage detected. CoverageNone CoverageLevel = "none" )
type RiskLevel ¶
type RiskLevel string
RiskLevel indicates the overall risk of a proposed change.
const ( // RiskCritical indicates very high risk - many callers, breaking changes, no tests. RiskCritical RiskLevel = "CRITICAL" // RiskHigh indicates high risk - significant impact that needs careful review. RiskHigh RiskLevel = "HIGH" // RiskMedium indicates moderate risk - some impact but manageable. RiskMedium RiskLevel = "MEDIUM" // RiskLow indicates low risk - minimal impact, well-tested. RiskLow RiskLevel = "LOW" )
type RiskWeights ¶
type RiskWeights struct {
Breaking float64 // Weight for breaking changes (default 0.30)
BlastRadius float64 // Weight for caller count (default 0.25)
TestCoverage float64 // Weight for test coverage (default 0.20)
SideEffects float64 // Weight for side effects (default 0.15)
Exported float64 // Weight for public API exposure (default 0.10)
}
RiskWeights defines the weights for risk score calculation.
func DefaultRiskWeights ¶
func DefaultRiskWeights() RiskWeights
DefaultRiskWeights returns the default risk calculation weights.
Source Files