analysis

type APIContract struct {
	// Path is the file path of the contract.
	Path string `json:"path"`

	// Type is the contract type (openapi, graphql, protobuf).
	Type string `json:"type"`

	// Version is the API version (if specified).
	Version string `json:"version,omitempty"`

	// Endpoints are the defined endpoints.
	Endpoints []ContractEndpoint `json:"endpoints"`
}

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

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

type APIDependency struct {
	// Endpoint is the API endpoint (URL path or service method).
	Endpoint string `json:"endpoint"`

	// Method is the HTTP method (GET, POST, etc.) or RPC method.
	Method string `json:"method"`

	// Type is the API type (REST, GraphQL, gRPC).
	Type APIType `json:"type"`

	// SourceSymbol is the symbol containing this dependency.
	SourceSymbol string `json:"source_symbol"`

	// FilePath is the file containing the dependency.
	FilePath string `json:"file_path"`

	// Line is the line number of the dependency.
	Line int `json:"line"`

	// ServiceName is the external service name (if detectable).
	ServiceName string `json:"service_name,omitempty"`

	// Contract is the API contract reference (if any).
	Contract string `json:"contract,omitempty"`

	// Confidence is how confident we are in this detection (0-100).
	Confidence int `json:"confidence"`
}

type APIType string

type AnalyzeOptions struct {
	MaxDirectCallers   int           `json:"max_direct_callers"`
	MaxIndirectCallers int           `json:"max_indirect_callers"`
	MaxHops            int           `json:"max_hops"`
	Timeout            time.Duration `json:"timeout"`
	TestPatterns       []string      `json:"test_patterns"`
	TestDirs           []string      `json:"test_dirs"`
}

type BlastRadius struct {
	Target          string        `json:"target"`
	RiskLevel       RiskLevel     `json:"risk_level"`
	DirectCallers   []Caller      `json:"direct_callers"`
	IndirectCallers []Caller      `json:"indirect_callers"`
	Implementers    []Implementer `json:"implementers,omitempty"`
	SharedDeps      []SharedDep   `json:"shared_deps,omitempty"`
	FilesAffected   []string      `json:"files_affected"`
	TestFiles       []string      `json:"test_files"`
	Summary         string        `json:"summary"`
	Recommendation  string        `json:"recommendation"`
	Truncated       bool          `json:"truncated,omitempty"`
	TruncatedReason string        `json:"truncated_reason,omitempty"`
}

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

type Caller struct {
	ID       string `json:"id"`
	Name     string `json:"name"`
	FilePath string `json:"file_path"`
	Line     int    `json:"line"`
	Hops     int    `json:"hops"`
}

type ChangeClassifier struct{}

type ChangeImpact struct {
	// ChangeType identifies what kind of change this describes.
	ChangeType string `json:"change_type"`

	// Impact is the severity of the change.
	// One of: "BREAKING", "COMPATIBLE", "SAFE".
	Impact string `json:"impact"`

	// AffectedSites is the count of locations that would need updates.
	// For BREAKING changes, this is the number of callers/implementers.
	AffectedSites int `json:"affected_sites"`

	// Description explains the impact in human-readable terms.
	Description string `json:"description"`

	// Example provides a code example if applicable.
	Example string `json:"example,omitempty"`
}

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

type ChurnScore struct {
	// ChangesLast30Days is the number of commits affecting this file
	// in the last 30 days.
	ChangesLast30Days int `json:"changes_last_30_days"`

	// ChangesLast90Days is the number of commits affecting this file
	// in the last 90 days.
	ChangesLast90Days int `json:"changes_last_90_days"`

	// BugReportsLinked is the count of commits with "fix", "bug", or
	// issue references (e.g., "#123") in the last 90 days.
	BugReportsLinked int `json:"bug_reports_linked"`

	// LastModified is when the file was last changed (Unix milliseconds UTC).
	LastModified int64 `json:"last_modified"`

	// ChurnLevel categorizes the churn rate.
	// One of: "LOW", "MODERATE", "HIGH".
	ChurnLevel string `json:"churn_level"`

	// Contributors lists unique authors who modified this file recently.
	Contributors []string `json:"contributors,omitempty"`
}

type CodeOwnerRule struct {
	Pattern string   // Glob pattern (e.g., "*.go", "/src/auth/**")
	Owners  []string // List of owners (e.g., "@team", "user@example.com")
	Line    int      // Line number in CODEOWNERS file (for debugging)
}

type ConfidenceCalculator struct{}

type ConfidenceScore struct {
	// Score is a percentage (0-100) indicating confidence.
	Score int `json:"score"`

	// Level categorizes the score.
	// One of: "HIGH", "MEDIUM", "LOW".
	Level string `json:"level"`

	// UncertaintyReasons explains why confidence was reduced.
	// Empty if confidence is HIGH.
	UncertaintyReasons []string `json:"uncertainty_reasons,omitempty"`
}

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

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

type ConfigDependency struct {
	// Key is the configuration key name.
	Key string `json:"key"`

	// Type is the type of configuration (env, viper, flag, file).
	Type ConfigType `json:"type"`

	// DefaultValue is the default value (if detectable).
	DefaultValue string `json:"default_value,omitempty"`

	// Required indicates if this config is required.
	Required bool `json:"required"`

	// SourceSymbol is the symbol containing this dependency.
	SourceSymbol string `json:"source_symbol"`

	// FilePath is the file containing the dependency.
	FilePath string `json:"file_path"`

	// Line is the line number of the dependency.
	Line int `json:"line"`

	// Confidence is how confident we are in this detection (0-100).
	Confidence int `json:"confidence"`
}

type ConfigType string

type ContractEndpoint struct {
	Path        string   `json:"path"`
	Method      string   `json:"method,omitempty"`
	OperationID string   `json:"operation_id,omitempty"`
	Summary     string   `json:"summary,omitempty"`
	Parameters  []string `json:"parameters,omitempty"`
}

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

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

type CoverageInfo struct {
	// SymbolID is the symbol this coverage applies to.
	SymbolID string `json:"symbol_id"`

	// LineCoverage is the percentage of lines covered (0.0-1.0).
	LineCoverage float64 `json:"line_coverage"`

	// BranchCoverage is the percentage of branches covered (0.0-1.0).
	BranchCoverage float64 `json:"branch_coverage"`

	// CoveredLines is the number of lines with coverage.
	CoveredLines int `json:"covered_lines"`

	// TotalLines is the total number of lines.
	TotalLines int `json:"total_lines"`

	// CoveredBy is the list of test functions that cover this symbol.
	CoveredBy []string `json:"covered_by,omitempty"`
}

type CoverageRisk string

type CoverageStats struct {
	TotalFiles   int     `json:"total_files"`
	TotalLines   int     `json:"total_lines"`
	CoveredLines int     `json:"covered_lines"`
	Coverage     float64 `json:"coverage"`
}

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

type DeadCodeDetectorOption func(*deadCodeOptions)

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

type DeadCodeInfo struct {
	// IsDead indicates if the target symbol is dead.
	IsDead bool `json:"is_dead"`

	// Reason for being dead (if IsDead is true).
	Reason string `json:"reason,omitempty"`

	// Confidence in the dead code detection (0-100).
	Confidence int `json:"confidence,omitempty"`

	// DeadCallerCount is how many callers are themselves dead.
	DeadCallerCount int `json:"dead_caller_count,omitempty"`

	// TotalDeadLines is total dead lines in the codebase.
	TotalDeadLines int `json:"total_dead_lines,omitempty"`

	// DeadFunctionCount is total dead functions.
	DeadFunctionCount int `json:"dead_function_count,omitempty"`

	// DeadTypeCount is total dead types.
	DeadTypeCount int `json:"dead_type_count,omitempty"`
}

type DeadCodeResult struct {
	// UnusedFunctions are functions with no callers.
	UnusedFunctions []DeadSymbol `json:"unused_functions"`

	// UnusedTypes are types with no usages.
	UnusedTypes []DeadSymbol `json:"unused_types"`

	// UnusedConstants are constants with no references.
	UnusedConstants []DeadSymbol `json:"unused_constants"`

	// TotalDeadLines is the estimated total lines of dead code.
	TotalDeadLines int `json:"total_dead_lines"`
}

type DeadSymbol struct {
	// ID is the unique symbol identifier.
	ID string `json:"id"`

	// Name is the symbol's name.
	Name string `json:"name"`

	// FilePath is the file containing the symbol.
	FilePath string `json:"file_path"`

	// Line is the starting line number.
	Line int `json:"line"`

	// EndLine is the ending line number (for line count estimation).
	EndLine int `json:"end_line,omitempty"`

	// Reason explains why this is considered dead.
	Reason string `json:"reason"`

	// Confidence is how confident we are (0-100).
	// Lower for exported symbols, reflection-heavy code, etc.
	Confidence int `json:"confidence"`
}

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

type EnhancedAnalyzerOption func(*EnhancedAnalyzer)

type EnhancedBlastRadius struct {
	// BlastRadius embeds the core CB-17 result.
	// This includes: Target, RiskLevel, DirectCallers, IndirectCallers,
	// Implementers, SharedDeps, FilesAffected, TestFiles, Summary, Recommendation.
	BlastRadius

	// SecurityPath contains security analysis results (single primary path).
	// Nil if security analysis didn't run or found nothing.
	SecurityPath *SecurityPath `json:"security_path,omitempty"`

	// SecurityPaths contains all detected security paths.
	// Used by CB-17c for multiple path detection.
	SecurityPaths []SecurityPath `json:"security_paths,omitempty"`

	// ChurnScore contains historical churn analysis (single primary).
	// Nil if git is unavailable or analysis failed.
	ChurnScore *ChurnScore `json:"churn_score,omitempty"`

	// ChurnScores contains all churn scores for affected files.
	// Used by CB-17c for comprehensive churn analysis.
	ChurnScores []ChurnScore `json:"churn_scores,omitempty"`

	// Ownership contains code ownership information.
	// Nil if CODEOWNERS is missing or analysis failed.
	Ownership *Ownership `json:"ownership,omitempty"`

	// ChangeImpacts describes potential impacts of different change types.
	// Empty if classification couldn't be performed.
	ChangeImpacts []ChangeImpact `json:"change_impacts"`

	// Confidence indicates analysis reliability.
	// Always populated (defaults to HIGH if no issues detected).
	Confidence *ConfidenceScore `json:"confidence,omitempty"`

	// EnricherResults tracks which enrichers ran successfully.
	// Useful for debugging partial results.
	EnricherResults []EnricherResult `json:"enricher_results,omitempty"`

	// AnalyzedAt is when this analysis was performed (Unix milliseconds UTC).
	AnalyzedAt int64 `json:"analyzed_at"`

	// GraphGeneration is the graph version used for analysis.
	// Used for cache invalidation.
	GraphGeneration uint64 `json:"graph_generation"`

	// TransitiveCount is the total number of transitive callers.
	TransitiveCount int `json:"transitive_count,omitempty"`

	// DeadCode contains dead code analysis for this symbol.
	DeadCode *DeadCodeInfo `json:"dead_code,omitempty"`

	// Coverage contains test coverage information for this symbol.
	Coverage *CoverageInfo `json:"coverage,omitempty"`

	// UntestedCallers are callers that lack test coverage.
	UntestedCallers []Caller `json:"untested_callers,omitempty"`

	// CoverageRisk indicates the coverage risk level.
	// One of: "HIGH_UNTESTED", "PARTIAL", "COVERED".
	CoverageRisk string `json:"coverage_risk,omitempty"`

	// SchemaDependencies are database schema dependencies.
	SchemaDependencies []SchemaDependency `json:"schema_dependencies,omitempty"`

	// APIDependencies are external API dependencies.
	APIDependencies []APIDependency `json:"api_dependencies,omitempty"`

	// ConfigDependencies are configuration dependencies.
	ConfigDependencies []ConfigDependency `json:"config_dependencies,omitempty"`

	// RollbackRisk assesses the difficulty of rolling back changes.
	RollbackRisk *RollbackRisk `json:"rollback_risk,omitempty"`

	// PredictiveRisk contains predictive risk scoring based on history.
	PredictiveRisk *PredictiveRisk `json:"predictive_risk,omitempty"`
}

type Enricher interface {
	// Name returns a unique identifier for logging and metrics.
	//
	// # Description
	//
	// The name should be a short, lowercase, underscore-separated string
	// that identifies this enricher (e.g., "security_path", "churn").
	//
	// # Outputs
	//
	//   - string: Unique identifier for this enricher.
	Name() string

	// Priority determines execution order (lower = earlier).
	//
	// # Description
	//
	// Enrichers with the same priority run in parallel using errgroup.
	// Priority groups execute sequentially.
	//
	// # Priority Guidelines
	//
	//   - 1: Critical analysis that other enrichers may depend on
	//   - 2: Independent secondary analysis
	//   - 3: Derived analysis that aggregates other results
	//
	// # Range
	//
	// Valid range: 1-10 (1 = first, 10 = last).
	//
	// # Outputs
	//
	//   - int: Priority level (1-10).
	Priority() int

	// Enrich adds analysis data to the result.
	//
	// # Description
	//
	// Performs the enricher's analysis and modifies the result in place.
	// The result is pre-populated with base BlastRadius data from CB-17.
	//
	// # Inputs
	//
	//   - ctx: Context for cancellation/timeout. Must be checked frequently.
	//     Implementations should check ctx.Err() at least every 10ms of work.
	//   - target: The symbol and context being analyzed.
	//   - result: The result to enrich. Modify appropriate fields in place.
	//
	// # Outputs
	//
	//   - error: Non-nil on failure. Partial enrichment is acceptable.
	//     Errors do not fail the overall analysis; they're logged and
	//     the enricher's contribution is marked as missing.
	//
	// # Behavior Requirements
	//
	//   - Must be idempotent (calling twice produces same result)
	//   - Must respect context cancellation (return ctx.Err())
	//   - Should complete within 50ms for good UX
	//   - May return partial results if timeout is imminent
	//   - Must not modify fields owned by other enrichers
	//
	// # Example
	//
	//   func (e *MyEnricher) Enrich(ctx context.Context, target *EnrichmentTarget, result *EnhancedBlastRadius) error {
	//       // Check cancellation at start
	//       if ctx.Err() != nil {
	//           return ctx.Err()
	//       }
	//
	//       // Do analysis...
	//       data := e.analyze(target)
	//
	//       // Check cancellation after work
	//       if ctx.Err() != nil {
	//           return ctx.Err()
	//       }
	//
	//       // Enrich result
	//       result.MyData = data
	//       return nil
	//   }
	Enrich(ctx context.Context, target *EnrichmentTarget, result *EnhancedBlastRadius) error
}

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

type EnricherResult struct {
	// Name is the enricher's unique identifier.
	Name string

	// Success indicates whether the enricher completed without error.
	Success bool

	// Error contains the error message if Success is false.
	// Empty string if no error.
	Error string

	// DurationMs is how long the enricher took in milliseconds.
	DurationMs int64

	// Skipped indicates the enricher was skipped (e.g., due to timeout).
	Skipped bool

	// SkipReason explains why the enricher was skipped.
	SkipReason string
}

type EnrichmentTarget struct {
	// SymbolID is the unique identifier of the target symbol.
	// Format: "path/to/file.go:line:name"
	SymbolID string

	// Symbol is the resolved AST symbol. May be nil if the symbol
	// could not be found (e.g., it was deleted or is dynamically generated).
	Symbol *ast.Symbol

	// Graph is the frozen code graph. Must be read-only at this point.
	// Use graph.Query methods to find relationships.
	Graph *graph.Graph

	// Index is the symbol index for O(1) lookups by ID, name, file, or kind.
	Index *index.SymbolIndex

	// RepoPath is the absolute path to the repository root.
	// Used by enrichers that need to access files (e.g., CODEOWNERS, git).
	RepoPath string

	// BaseResult is the CB-17 blast radius result.
	// Enrichers use this to access callers, implementers, etc.
	BaseResult *BlastRadius
}

type Implementer struct {
	TypeID     string `json:"type_id"`
	TypeName   string `json:"type_name"`
	MethodID   string `json:"method_id,omitempty"`
	MethodName string `json:"method_name,omitempty"`
	FilePath   string `json:"file_path"`
	Line       int    `json:"line"`
}

type IrreversibleChange struct {
	// Type is the type of irreversible change.
	Type IrreversibleChangeType `json:"type"`

	// Description describes what was changed.
	Description string `json:"description"`

	// Location is where the change occurs.
	Location string `json:"location"`

	// Impact describes the impact of this change.
	Impact string `json:"impact"`
}

type IrreversibleChangeType string

type Ownership struct {
	// PrimaryOwner is the team/person from CODEOWNERS matching the target file.
	// Format: "@team-name" or "@username" or "email@example.com".
	// Empty if no CODEOWNERS match.
	PrimaryOwner string `json:"primary_owner,omitempty"`

	// SecondaryOwners are owners of files in the blast radius.
	// These teams should be notified of changes.
	SecondaryOwners []string `json:"secondary_owners,omitempty"`

	// ReviewerHint suggests who should review based on recent activity.
	// May be a specific person who recently worked on this code.
	ReviewerHint string `json:"reviewer_hint,omitempty"`

	// OwnershipSource indicates where ownership was determined from.
	// One of: "CODEOWNERS", "git_blame", "fallback".
	OwnershipSource string `json:"ownership_source,omitempty"`
}

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

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

type PredictiveRisk struct {
	// Score is the overall risk score (0-100, higher = riskier).
	Score int `json:"score"`

	// Level is the risk level category.
	Level PredictiveRiskLevel `json:"level"`

	// Factors are the factors contributing to the score.
	Factors []PredictiveRiskFactor `json:"factors"`

	// HistoricalBugCount is the number of past bugs in this area.
	HistoricalBugCount int `json:"historical_bug_count"`

	// ChurnRate is the change frequency (changes per week).
	ChurnRate float64 `json:"churn_rate"`

	// ComplexityScore is the estimated complexity (if available).
	ComplexityScore int `json:"complexity_score,omitempty"`

	// FailureProbability is the estimated probability of failure (0.0-1.0).
	FailureProbability float64 `json:"failure_probability"`

	// Recommendations are suggested risk mitigation steps.
	Recommendations []string `json:"recommendations,omitempty"`
}

type PredictiveRiskFactor struct {
	// Name is the factor name.
	Name string `json:"name"`

	// Description explains the factor.
	Description string `json:"description"`

	// Contribution is the score contribution (0-100).
	Contribution int `json:"contribution"`

	// Evidence provides supporting data.
	Evidence string `json:"evidence,omitempty"`
}

type PredictiveRiskLevel string

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

type RiskConfig struct {
	CriticalThreshold int `json:"critical_threshold"`
	HighThreshold     int `json:"high_threshold"`
	MediumThreshold   int `json:"medium_threshold"`
}

type RiskFactor struct {
	// Factor is the risk factor name.
	Factor string `json:"factor"`

	// Description explains the risk.
	Description string `json:"description"`

	// Weight is the contribution to the overall score (0-100).
	Weight int `json:"weight"`
}

type RiskLevel string

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

type RollbackRisk struct {
	// Level is the overall risk level.
	Level RollbackRiskLevel `json:"level"`

	// Score is a numeric score (0-100, higher = harder to rollback).
	Score int `json:"score"`

	// IrreversibleChanges are changes that cannot be undone.
	IrreversibleChanges []IrreversibleChange `json:"irreversible_changes,omitempty"`

	// HighRiskFactors are factors contributing to rollback difficulty.
	HighRiskFactors []RiskFactor `json:"high_risk_factors,omitempty"`

	// MitigationSteps are suggested steps to enable safe rollback.
	MitigationSteps []string `json:"mitigation_steps,omitempty"`

	// RequiresDataMigration indicates if data migration is needed.
	RequiresDataMigration bool `json:"requires_data_migration"`

	// RequiresAPIVersioning indicates if API versioning is needed.
	RequiresAPIVersioning bool `json:"requires_api_versioning"`

	// EstimatedRecoveryComplexity estimates rollback complexity.
	EstimatedRecoveryComplexity string `json:"estimated_recovery_complexity"`
}

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

type RollbackRiskLevel string

type SQLOperation string

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

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

type SchemaDependency struct {
	// Table is the database table name.
	Table string `json:"table"`

	// Columns are specific columns referenced (if detectable).
	Columns []string `json:"columns,omitempty"`

	// Operation is the SQL operation type.
	Operation SQLOperation `json:"operation"`

	// SourceSymbol is the symbol containing this dependency.
	SourceSymbol string `json:"source_symbol"`

	// FilePath is the file containing the dependency.
	FilePath string `json:"file_path"`

	// Line is the line number of the dependency.
	Line int `json:"line"`

	// RawQuery is the detected SQL snippet (truncated for safety).
	RawQuery string `json:"raw_query,omitempty"`

	// ORM is the ORM framework detected (if any).
	ORM string `json:"orm,omitempty"`

	// Confidence is how confident we are in this detection (0-100).
	Confidence int `json:"confidence"`
}

type SecurityPath struct {
	// IsSecuritySensitive indicates the symbol is in a security path.
	IsSecuritySensitive bool `json:"is_security_sensitive"`

	// PathType identifies the type of security path.
	// One of: "AUTH", "AUTHZ", "PII", "CRYPTO", "SECRETS".
	// Empty string if not security sensitive.
	PathType string `json:"path_type,omitempty"`

	// Reason explains why this was classified as security-sensitive.
	// Human-readable explanation for agents.
	Reason string `json:"reason,omitempty"`

	// RequiresReview indicates whether changes need security review.
	RequiresReview bool `json:"requires_review"`

	// MatchedPatterns lists which patterns triggered detection.
	// Useful for debugging false positives.
	MatchedPatterns []string `json:"matched_patterns,omitempty"`

	// CallChainSecurity indicates the symbol is called BY security code.
	// A function may not look security-sensitive itself but is in the
	// security call chain.
	CallChainSecurity bool `json:"call_chain_security,omitempty"`
}

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

type SharedDep struct {
	ID        string   `json:"id"`
	Name      string   `json:"name"`
	UsedBy    []string `json:"used_by"`
	UsageType string   `json:"usage_type"`
	Warning   string   `json:"warning"`
}