domain

type AnalysisCoverage struct {
	TotalFiles    int
	AnalyzedFiles int
	SkippedFiles  int
	Diagnostics   []AnalysisDiagnostic
}

type AnalysisDiagnostic struct {
	FilePath string         `json:"file_path" yaml:"file_path"`
	Code     DiagnosticCode `json:"code" yaml:"code"`
	Message  string         `json:"message" yaml:"message"`
}

type AnalysisFailure struct {
	Analysis AnalysisKind        `json:"analysis" yaml:"analysis"`
	Code     AnalysisFailureCode `json:"code" yaml:"code"`
	Message  string              `json:"message" yaml:"message"`
	FilePath string              `json:"file_path,omitempty" yaml:"file_path,omitempty"`
	// contains filtered or unexported fields
}

type AnalysisFailureCode string

type AnalysisFailureReporter interface {
	AnalysisFailures() []AnalysisFailure
}

type AnalysisKind string

type AnalysisScopeKind string

type AnalyzeConfigurationLoader interface {
	LoadAnalyzeExecutionConfig(configPath string, targetPath string) (AnalyzeExecutionConfig, error)
}

type AnalyzeExecutionConfig struct {
	ConfigPath  string
	ProjectRoot string

	IncludePatterns []string
	ExcludePatterns []string
	Recursive       bool
	ShowDetails     bool

	ComplexityEnabled            bool
	ComplexityReportUnchanged    bool
	ComplexityMinComplexity      int
	ComplexityLowThreshold       int
	ComplexityMediumThreshold    int
	ComplexityMaxComplexity      int
	CognitiveComplexityThreshold int
	NestingDepthThreshold        int

	FunctionSLOCWarnThreshold     int
	FunctionSLOCCriticalThreshold int

	DeadCodeEnabled bool

	CloneLSHEnabled       string
	CloneLSHAutoThreshold int

	SystemEnabled             bool
	SystemAnalyzeDependencies bool
	SystemAnalyzeArchitecture bool
	ModuleGraph               ModuleGraphOptions

	CommunitiesEnabled         bool
	CommunitiesEnabledExplicit bool
}

type AnalyzeOutputFormatter interface {
	Write(response *AnalyzeResponse, format OutputFormat, writer io.Writer) error
}

type AnalyzeResponse struct {
	// Analysis results
	Complexity  *ComplexityResponse      `json:"complexity,omitempty" yaml:"complexity,omitempty"`
	DeadCode    *DeadCodeResponse        `json:"dead_code,omitempty" yaml:"dead_code,omitempty"`
	Clone       *CloneResponse           `json:"clone,omitempty" yaml:"clone,omitempty"`
	CBO         *CBOResponse             `json:"cbo,omitempty" yaml:"cbo,omitempty"`
	LCOM        *LCOMResponse            `json:"lcom,omitempty" yaml:"lcom,omitempty"`
	System      *SystemAnalysisResponse  `json:"system,omitempty" yaml:"system,omitempty"`
	Communities *CommunityAnalysisResult `json:"community_analysis,omitempty" yaml:"community_analysis,omitempty"`
	MockData    *MockDataResponse        `json:"mock_data,omitempty" yaml:"mock_data,omitempty"`

	// Cross-analysis module quality rollups
	ModuleQuality []ModuleQualityMetrics `json:"module_quality,omitempty" yaml:"module_quality,omitempty"`

	// Actionable suggestions derived from analysis results
	Suggestions []Suggestion `json:"suggestions,omitempty" yaml:"suggestions,omitempty"`
	// Project-level read and parse failures, independent of selected analyzers.
	Diagnostics []AnalysisDiagnostic `json:"diagnostics,omitempty" yaml:"diagnostics,omitempty"`
	// Analyzer execution failures. Partial results remain available when set.
	Failures []AnalysisFailure `json:"failures,omitempty" yaml:"failures,omitempty"`

	// Overall summary
	Summary AnalyzeSummary `json:"summary" yaml:"summary"`

	// Metadata
	SchemaVersion int       `json:"schema_version" yaml:"schema_version"`
	GeneratedAt   time.Time `json:"generated_at" yaml:"generated_at"`
	Duration      int64     `json:"duration_ms" yaml:"duration_ms"`
	Version       string    `json:"version" yaml:"version"`
}

type AnalyzeSummary struct {
	// File statistics
	TotalFiles    int `json:"total_files" yaml:"total_files"`
	AnalyzedFiles int `json:"analyzed_files" yaml:"analyzed_files"`
	SkippedFiles  int `json:"skipped_files" yaml:"skipped_files"`

	// Analysis status
	ComplexityEnabled bool `json:"complexity_enabled" yaml:"complexity_enabled"`
	DeadCodeEnabled   bool `json:"dead_code_enabled" yaml:"dead_code_enabled"`
	CloneEnabled      bool `json:"clone_enabled" yaml:"clone_enabled"`
	CBOEnabled        bool `json:"cbo_enabled" yaml:"cbo_enabled"`
	MockDataEnabled   bool `json:"mock_data_enabled" yaml:"mock_data_enabled"`

	// System-level (module dependencies & architecture) summary used for scoring
	DepsEnabled               bool    `json:"deps_enabled" yaml:"deps_enabled"`
	ArchEnabled               bool    `json:"arch_enabled" yaml:"arch_enabled"`
	CommunitiesEnabled        bool    `json:"communities_enabled" yaml:"communities_enabled"`
	DepsTotalModules          int     `json:"deps_total_modules" yaml:"deps_total_modules"`
	DepsModulesInCycles       int     `json:"deps_modules_in_cycles" yaml:"deps_modules_in_cycles"`
	DepsMaxDepth              int     `json:"deps_max_depth" yaml:"deps_max_depth"`
	DepsMainSequenceDeviation float64 `json:"deps_main_sequence_deviation" yaml:"deps_main_sequence_deviation"`
	ArchCompliance            float64 `json:"arch_compliance" yaml:"arch_compliance"`

	// Community detection metrics used for scoring (populated when CommunitiesEnabled).
	CommunityCount            int      `json:"community_count" yaml:"community_count"`
	CommunityModularity       float64  `json:"community_modularity" yaml:"community_modularity"`
	CommunityBridgeModules    int      `json:"community_bridge_modules" yaml:"community_bridge_modules"`
	CommunityInternalEdges    int      `json:"community_internal_edges" yaml:"community_internal_edges"`
	CommunityCrossEdges       int      `json:"community_cross_edges" yaml:"community_cross_edges"`
	CommunityPackageAlignment *float64 `json:"community_package_alignment,omitempty" yaml:"community_package_alignment,omitempty"`
	CommunityLayerAlignment   *float64 `json:"community_layer_alignment,omitempty" yaml:"community_layer_alignment,omitempty"`

	// Key metrics
	// TotalFunctions is the complete analyzed population used for aggregate metrics.
	TotalFunctions int `json:"total_functions" yaml:"total_functions"`
	// Class-scope fields are reported separately from the established function
	// aggregates and do not change health-score semantics.
	TotalClassScopes              int `json:"total_class_scopes" yaml:"total_class_scopes"`
	MaxClassComplexity            int `json:"max_class_complexity" yaml:"max_class_complexity"`
	MaxClassCognitiveComplexity   int `json:"max_class_cognitive_complexity" yaml:"max_class_cognitive_complexity"`
	MaxClassNestingDepth          int `json:"max_class_nesting_depth" yaml:"max_class_nesting_depth"`
	HighComplexityClassScopeCount int `json:"high_complexity_class_scope_count" yaml:"high_complexity_class_scope_count"`
	// FunctionsParsed is always equal to TotalFunctions. It is retained only
	// for JSON/YAML schema compatibility and will be removed; consumers should
	// read TotalFunctions.
	FunctionsParsed            int     `json:"functions_parsed" yaml:"functions_parsed"`
	AverageComplexity          float64 `json:"average_complexity" yaml:"average_complexity"`
	AverageCognitiveComplexity float64 `json:"average_cognitive_complexity" yaml:"average_cognitive_complexity"`
	AverageNestingDepth        float64 `json:"average_nesting_depth" yaml:"average_nesting_depth"`
	HighComplexityCount        int     `json:"high_complexity_count" yaml:"high_complexity_count"`

	DeadCodeCount    int `json:"dead_code_count" yaml:"dead_code_count"`
	CriticalDeadCode int `json:"critical_dead_code" yaml:"critical_dead_code"`
	WarningDeadCode  int `json:"warning_dead_code" yaml:"warning_dead_code"`
	InfoDeadCode     int `json:"info_dead_code" yaml:"info_dead_code"`

	TotalClones     int     `json:"total_clones" yaml:"total_clones"`
	ClonePairs      int     `json:"clone_pairs" yaml:"clone_pairs"`
	CloneGroups     int     `json:"clone_groups" yaml:"clone_groups"`
	CodeDuplication float64 `json:"code_duplication_percentage" yaml:"code_duplication_percentage"`

	CBOClasses            int     `json:"cbo_classes" yaml:"cbo_classes"`
	HighCouplingClasses   int     `json:"high_coupling_classes" yaml:"high_coupling_classes"`     // CBO > 7 (High Risk)
	MediumCouplingClasses int     `json:"medium_coupling_classes" yaml:"medium_coupling_classes"` // 3 < CBO ≤ 7 (Medium Risk)
	AverageCoupling       float64 `json:"average_coupling" yaml:"average_coupling"`

	LCOMEnabled       bool    `json:"lcom_enabled" yaml:"lcom_enabled"`
	LCOMClasses       int     `json:"lcom_classes" yaml:"lcom_classes"`
	HighLCOMClasses   int     `json:"high_lcom_classes" yaml:"high_lcom_classes"`     // LCOM4 > 5 (High Risk)
	MediumLCOMClasses int     `json:"medium_lcom_classes" yaml:"medium_lcom_classes"` // 2 < LCOM4 ≤ 5 (Medium Risk)
	AverageLCOM       float64 `json:"average_lcom" yaml:"average_lcom"`

	MockDataCount        int `json:"mock_data_count" yaml:"mock_data_count"`
	MockDataErrorCount   int `json:"mock_data_error_count" yaml:"mock_data_error_count"`
	MockDataWarningCount int `json:"mock_data_warning_count" yaml:"mock_data_warning_count"`
	MockDataInfoCount    int `json:"mock_data_info_count" yaml:"mock_data_info_count"`

	// Overall health score (0-100)
	HealthScore int    `json:"health_score" yaml:"health_score"`
	Grade       string `json:"grade" yaml:"grade"` // A, B, C, D, F

	// Individual category scores (0-100)
	ComplexityScore   int `json:"complexity_score" yaml:"complexity_score"`
	DeadCodeScore     int `json:"dead_code_score" yaml:"dead_code_score"`
	DuplicationScore  int `json:"duplication_score" yaml:"duplication_score"`
	CouplingScore     int `json:"coupling_score" yaml:"coupling_score"`
	CohesionScore     int `json:"cohesion_score" yaml:"cohesion_score"`
	DependencyScore   int `json:"dependency_score" yaml:"dependency_score"`
	ArchitectureScore int `json:"architecture_score" yaml:"architecture_score"`
	CommunityScore    int `json:"community_score" yaml:"community_score"`

	// CommunityRiskScore is a system-level 0-100 risk signal (higher = worse).
	// It is the inverse of CommunityScore and only meaningful when communities ran.
	CommunityRiskScore int `json:"community_risk_score" yaml:"community_risk_score"`
}

type ArchitectureAnalysisResult struct {
	// Overall architecture compliance
	ComplianceScore    float64 `json:"compliance_score" yaml:"compliance_score"`       // Overall compliance score (0-1, where 1.0 = 100% compliant). Computed as 1 - WeightedViolations/TotalRules (clamped to [0,1]).
	TotalViolations    int     `json:"total_violations" yaml:"total_violations"`       // Raw number of violations (one per ArchitectureViolation entry).
	WeightedViolations int     `json:"weighted_violations" yaml:"weighted_violations"` // Severity-weighted violation count used as the ComplianceScore numerator: error * 5 + warning * 1.
	TotalRules         int     `json:"total_rules" yaml:"total_rules"`                 // Total number of rule invocations checked (ComplianceScore denominator).

	// Layer analysis
	LayerAnalysis          *LayerAnalysis          `json:"layer_analysis" yaml:"layer_analysis"`                   // Layer violation analysis
	CohesionAnalysis       *CohesionAnalysis       `json:"cohesion_analysis" yaml:"cohesion_analysis"`             // Package cohesion analysis
	ResponsibilityAnalysis *ResponsibilityAnalysis `json:"responsibility_analysis" yaml:"responsibility_analysis"` // SRP violation analysis

	// Detailed violations
	Violations        []ArchitectureViolation   `json:"violations" yaml:"violations"`                 // All architecture violations
	SeverityBreakdown map[ViolationSeverity]int `json:"severity_breakdown" yaml:"severity_breakdown"` // Violations by severity

	// Architecture recommendations
	Recommendations    []ArchitectureRecommendation `json:"recommendations" yaml:"recommendations"`         // Specific recommendations
	RefactoringTargets []string                     `json:"refactoring_targets" yaml:"refactoring_targets"` // Modules needing refactoring
}

type ArchitectureRecommendation struct {
	Type        RecommendationType     `json:"type" yaml:"type"`               // Type of recommendation
	Priority    RecommendationPriority `json:"priority" yaml:"priority"`       // Priority level
	Title       string                 `json:"title" yaml:"title"`             // Short title
	Description string                 `json:"description" yaml:"description"` // Detailed description
	Benefits    []string               `json:"benefits" yaml:"benefits"`       // Expected benefits
	Effort      EstimatedEffort        `json:"effort" yaml:"effort"`           // Estimated effort
	Modules     []string               `json:"modules" yaml:"modules"`         // Affected modules
	Steps       []string               `json:"steps" yaml:"steps"`             // Implementation steps
}

type ArchitectureRules struct {
	// Style is an optional preset name: "layered", "hexagonal", "clean", "mvc".
	// When non-empty and Layers/Rules are empty, the service loads the matching
	// preset's layers and rules. Empty/"layered" preserves the legacy behavior.
	Style string `json:"style" yaml:"style"`

	// Layer rules
	Layers []Layer     `json:"layers" yaml:"layers"`
	Rules  []LayerRule `json:"rules" yaml:"rules"`

	// Package rules
	PackageRules []PackageRule `json:"package_rules" yaml:"package_rules"`

	// Custom rules
	CustomRules []CustomRule `json:"custom_rules" yaml:"custom_rules"`

	// Neutral prefixes to strip from module names before layer matching
	NeutralPrefixes []string `json:"neutral_prefixes" yaml:"neutral_prefixes"`

	// Global settings
	StrictMode        bool     `json:"strict_mode" yaml:"strict_mode"`
	AllowedPatterns   []string `json:"allowed_patterns" yaml:"allowed_patterns"`
	ForbiddenPatterns []string `json:"forbidden_patterns" yaml:"forbidden_patterns"`
}

type ArchitectureViolation struct {
	Type        ViolationType     `json:"type" yaml:"type"`               // Type of violation
	Severity    ViolationSeverity `json:"severity" yaml:"severity"`       // Severity level
	Module      string            `json:"module" yaml:"module"`           // Module involved
	Target      string            `json:"target" yaml:"target"`           // Target of violation (if applicable)
	Rule        string            `json:"rule" yaml:"rule"`               // Rule that was violated
	Description string            `json:"description" yaml:"description"` // Human-readable description
	Suggestion  string            `json:"suggestion" yaml:"suggestion"`   // Suggested remediation
	Location    *SourceLocation   `json:"location" yaml:"location"`       // Location in code (if available)
}

type BridgeModule struct {
	Module              string   `json:"module" yaml:"module"`
	Community           string   `json:"community" yaml:"community"`
	CrossCommunityEdges int      `json:"cross_community_edges" yaml:"cross_community_edges"`
	TargetCommunities   []string `json:"target_communities" yaml:"target_communities"`
}

type CBOAnalysisOptions struct {
	// Include system and built-in dependencies
	IncludeBuiltins bool

	// Maximum depth for dependency resolution
	MaxDependencyDepth int

	// Exclude patterns for class names
	ExcludeClassPatterns []string

	// Only analyze public classes (exclude private classes starting with _)
	PublicClassesOnly bool
}

type CBOConfigurationLoader interface {
	// LoadConfig loads configuration from the specified path
	LoadConfig(path string) (*CBORequest, error)

	// LoadDefaultConfig discovers configuration from targetPath (the analyzed
	// path) and falls back to built-in defaults when none is found
	LoadDefaultConfig(targetPath string) *CBORequest

	// MergeConfig merges CLI flags with configuration file
	MergeConfig(base *CBORequest, override *CBORequest) *CBORequest
}

type CBOMetrics struct {
	// Core CBO metric - number of classes this class depends on
	CouplingCount int `json:"coupling_count" yaml:"coupling_count"`

	// Breakdown by dependency type
	InheritanceDependencies     int `json:"inheritance_dependencies" yaml:"inheritance_dependencies"`           // Base classes
	TypeHintDependencies        int `json:"type_hint_dependencies" yaml:"type_hint_dependencies"`               // Type annotations
	InstantiationDependencies   int `json:"instantiation_dependencies" yaml:"instantiation_dependencies"`       // Object creation
	AttributeAccessDependencies int `json:"attribute_access_dependencies" yaml:"attribute_access_dependencies"` // Method calls and attribute access
	ImportDependencies          int `json:"import_dependencies" yaml:"import_dependencies"`                     // Explicitly imported classes

	// Dependency details
	DependentClasses []string `json:"dependent_classes" yaml:"dependent_classes"` // List of class names this class depends on
}

type CBOOutputFormatter interface {
	// Format formats the analysis response according to the specified format
	Format(response *CBOResponse, format OutputFormat) (string, error)

	// Write writes the formatted output to the writer
	Write(response *CBOResponse, format OutputFormat, writer io.Writer) error
}

type CBORequest struct {
	// Input files or directories to analyze
	Paths []string

	// Output configuration
	OutputFormat OutputFormat
	OutputWriter io.Writer
	OutputPath   string // Path to save output file (for HTML format)
	NoOpen       bool   // Don't auto-open HTML in browser
	ShowDetails  *bool  // nil = unset, non-nil = explicitly set

	// Filtering and sorting
	MinCBO    int
	MaxCBO    int // 0 means no limit
	SortBy    SortCriteria
	ShowZeros *bool // Include classes with CBO = 0

	// CBO thresholds for risk assessment
	LowThreshold    int // Default: 3 (industry standard)
	MediumThreshold int // Default: 7 (industry standard)

	// Configuration
	ConfigPath string

	// Analysis options
	Recursive       *bool
	IncludePatterns []string
	ExcludePatterns []string

	// Analysis scope
	IncludeBuiltins       *bool // Include dependencies on built-in types
	IncludeImports        *bool // Include imported modules in dependency count
	GroupNamespaceImports *bool // Collapse alias.Member references to a single alias edge
}

type CBOResponse struct {
	// Analysis results
	Classes []ClassCoupling `json:"classes" yaml:"classes"`
	Summary CBOSummary      `json:"summary" yaml:"summary"`

	// Warnings and issues
	Warnings []string          `json:"warnings" yaml:"warnings"`
	Errors   []string          `json:"errors" yaml:"errors"`
	Failures []AnalysisFailure `json:"failures,omitempty" yaml:"failures,omitempty"`

	// Metadata
	GeneratedAt string      `json:"generated_at" yaml:"generated_at"`
	Version     string      `json:"version" yaml:"version"`
	Config      interface{} `json:"config" yaml:"config"` // Configuration used for analysis
}

type CBOService interface {
	// Analyze performs CBO analysis on the given request
	Analyze(ctx context.Context, req CBORequest) (*CBOResponse, error)

	// AnalyzeFile analyzes a single Python file
	AnalyzeFile(ctx context.Context, filePath string, req CBORequest) (*CBOResponse, error)
}

type CBOSummary struct {
	TotalClasses    int     `json:"total_classes" yaml:"total_classes"`
	AverageCBO      float64 `json:"average_cbo" yaml:"average_cbo"`
	MaxCBO          int     `json:"max_cbo" yaml:"max_cbo"`
	MinCBO          int     `json:"min_cbo" yaml:"min_cbo"`
	ClassesAnalyzed int     `json:"classes_analyzed" yaml:"classes_analyzed"`
	FilesAnalyzed   int     `json:"files_analyzed" yaml:"files_analyzed"`

	// Risk distribution
	LowRiskClasses    int `json:"low_risk_classes" yaml:"low_risk_classes"`
	MediumRiskClasses int `json:"medium_risk_classes" yaml:"medium_risk_classes"`
	HighRiskClasses   int `json:"high_risk_classes" yaml:"high_risk_classes"`

	// CBO distribution
	CBODistribution map[string]int `json:"cbo_distribution" yaml:"cbo_distribution"`

	// Most coupled classes (top 10)
	MostCoupledClasses []ClassCoupling `json:"most_coupled_classes" yaml:"most_coupled_classes"`

	// Classes with highest impact (most depended upon)
	MostDependedUponClasses []string `json:"most_depended_upon_classes" yaml:"most_depended_upon_classes"`
}

type CategorizedError struct {
	Category ErrorCategory
	Message  string
	Original error
}

type CircularDependency struct {
	Modules      []string         `json:"modules" yaml:"modules"`           // Modules in the cycle
	Dependencies []DependencyPath `json:"dependencies" yaml:"dependencies"` // Dependency paths forming the cycle
	Severity     CycleSeverity    `json:"severity" yaml:"severity"`         // Severity level
	Size         int              `json:"size" yaml:"size"`                 // Number of modules
	Description  string           `json:"description" yaml:"description"`   // Human-readable description
}

type CircularDependencyAnalysis struct {
	HasCircularDependencies  bool                 `json:"has_circular_dependencies" yaml:"has_circular_dependencies"`   // True if cycles exist
	TotalCycles              int                  `json:"total_cycles" yaml:"total_cycles"`                             // Number of circular dependencies
	TotalModulesInCycles     int                  `json:"total_modules_in_cycles" yaml:"total_modules_in_cycles"`       // Number of modules involved in cycles
	CircularDependencies     []CircularDependency `json:"circular_dependencies" yaml:"circular_dependencies"`           // All detected cycles
	CycleBreakingSuggestions []string             `json:"cycle_breaking_suggestions" yaml:"cycle_breaking_suggestions"` // Suggestions for breaking cycles
	CoreInfrastructure       []string             `json:"core_infrastructure" yaml:"core_infrastructure"`               // Modules in multiple cycles
}

type ClassCohesion struct {
	// Class identification
	Name      string `json:"name" yaml:"name"`
	FilePath  string `json:"file_path" yaml:"file_path"`
	StartLine int    `json:"start_line" yaml:"start_line"`
	EndLine   int    `json:"end_line" yaml:"end_line"`

	// LCOM metrics
	Metrics LCOMMetrics `json:"metrics" yaml:"metrics"`

	// Risk assessment
	RiskLevel RiskLevel `json:"risk_level" yaml:"risk_level"`
}

type ClassCoupling struct {
	// Class identification
	Name      string `json:"name" yaml:"name"`
	FilePath  string `json:"file_path" yaml:"file_path"`
	StartLine int    `json:"start_line" yaml:"start_line"`
	EndLine   int    `json:"end_line" yaml:"end_line"`

	// CBO metrics
	Metrics CBOMetrics `json:"metrics" yaml:"metrics"`

	// Risk assessment
	RiskLevel RiskLevel `json:"risk_level" yaml:"risk_level"`

	// Additional context
	IsAbstract  bool     `json:"is_abstract" yaml:"is_abstract"`
	BaseClasses []string `json:"base_classes" yaml:"base_classes"`
}

type Clone struct {
	ID         int            `json:"id" yaml:"id" csv:"id"`
	Type       CloneType      `json:"type" yaml:"type" csv:"type"`
	Location   *CloneLocation `json:"location" yaml:"location" csv:"location"`
	Content    string         `json:"content,omitempty" yaml:"content,omitempty" csv:"content"`
	Hash       string         `json:"hash" yaml:"hash" csv:"hash"`
	Size       int            `json:"size" yaml:"size" csv:"size"` // Number of AST nodes
	LineCount  int            `json:"line_count" yaml:"line_count" csv:"line_count"`
	Complexity int            `json:"complexity" yaml:"complexity" csv:"complexity"`
}

type CloneConfigurationLoader interface {
	// LoadCloneConfig loads clone detection configuration from file
	LoadCloneConfig(configPath string) (*CloneRequest, error)

	// SaveCloneConfig saves clone detection configuration to file
	SaveCloneConfig(config *CloneRequest, configPath string) error

	// GetDefaultCloneConfig discovers clone configuration from targetPath (the
	// analyzed path) and falls back to built-in defaults when none is found
	GetDefaultCloneConfig(targetPath string) *CloneRequest

	// MergeConfig merges request values over loaded configuration.
	MergeConfig(base *CloneRequest, override *CloneRequest) *CloneRequest
}

type CloneGroup struct {
	ID         int       `json:"id" yaml:"id" csv:"id"`
	Clones     []*Clone  `json:"clones" yaml:"clones" csv:"clones"`
	Type       CloneType `json:"type" yaml:"type" csv:"type"`
	Similarity float64   `json:"similarity" yaml:"similarity" csv:"similarity"`
	Size       int       `json:"size" yaml:"size" csv:"size"`
}

type CloneLocation struct {
	FilePath  string `json:"file_path" yaml:"file_path" csv:"file_path"`
	StartLine int    `json:"start_line" yaml:"start_line" csv:"start_line"`
	EndLine   int    `json:"end_line" yaml:"end_line" csv:"end_line"`
	StartCol  int    `json:"start_col" yaml:"start_col" csv:"start_col"`
	EndCol    int    `json:"end_col" yaml:"end_col" csv:"end_col"`
}

type CloneOutputFormatter interface {
	// FormatCloneResponse formats a clone response according to the specified format
	FormatCloneResponse(response *CloneResponse, format OutputFormat, writer io.Writer) error

	// FormatCloneStatistics formats clone statistics
	FormatCloneStatistics(stats *CloneStatistics, format OutputFormat, writer io.Writer) error
}

type ClonePair struct {
	ID         int       `json:"id" yaml:"id" csv:"id"`
	Clone1     *Clone    `json:"clone1" yaml:"clone1" csv:"clone1"`
	Clone2     *Clone    `json:"clone2" yaml:"clone2" csv:"clone2"`
	Similarity float64   `json:"similarity" yaml:"similarity" csv:"similarity"`
	Distance   float64   `json:"distance" yaml:"distance" csv:"distance"`
	Type       CloneType `json:"type" yaml:"type" csv:"type"`
	Confidence float64   `json:"confidence" yaml:"confidence" csv:"confidence"`
}

type CloneRequest struct {
	// Input parameters
	Paths           []string `json:"paths"`
	Recursive       *bool    `json:"recursive"`
	IncludePatterns []string `json:"include_patterns"`
	ExcludePatterns []string `json:"exclude_patterns"`

	// Analysis configuration
	MinLines            int     `json:"min_lines"`
	MinNodes            int     `json:"min_nodes"`
	SimilarityThreshold float64 `json:"similarity_threshold"`
	MaxEditDistance     float64 `json:"max_edit_distance"`
	IgnoreLiterals      *bool   `json:"ignore_literals"`
	IgnoreIdentifiers   *bool   `json:"ignore_identifiers"`
	SkipDocstrings      *bool   `json:"skip_docstrings"`

	// Type-specific thresholds
	Type1Threshold float64 `json:"type1_threshold"`
	Type2Threshold float64 `json:"type2_threshold"`
	Type3Threshold float64 `json:"type3_threshold"`
	Type4Threshold float64 `json:"type4_threshold"`

	// Advanced analysis options
	EnableDFA bool `json:"enable_dfa"` // Enable Data Flow Analysis for enhanced Type-4 detection

	// Output configuration
	OutputFormat OutputFormat `json:"output_format"`
	OutputWriter io.Writer    `json:"-"`
	OutputPath   string       `json:"output_path"` // Path to save output file (for HTML format)
	NoOpen       bool         `json:"no_open"`     // Don't auto-open HTML in browser
	ShowDetails  *bool        `json:"show_details"`
	ShowContent  *bool        `json:"show_content"`
	SortBy       SortCriteria `json:"sort_by"`
	GroupClones  *bool        `json:"group_clones"`

	// Grouping options
	GroupMode      string  `json:"group_mode"`      // connected, star, complete_linkage, k_core
	GroupThreshold float64 `json:"group_threshold"` // Minimum similarity for group membership
	KCoreK         int     `json:"k_core_k"`        // k-core's k value

	// Filtering
	MinSimilarity float64     `json:"min_similarity"`
	MaxSimilarity float64     `json:"max_similarity"`
	CloneTypes    []CloneType `json:"clone_types"`

	// Configuration file
	ConfigPath string `json:"config_path"`

	// Performance configuration
	Timeout time.Duration `json:"timeout"` // Maximum time for clone analysis (0 = no timeout)

	// LSH acceleration (opt-in)
	LSHEnabled             string  `json:"lsh_enabled"`        // "auto", "true", "false"
	LSHAutoThreshold       int     `json:"lsh_auto_threshold"` // Auto-enable LSH for N+ fragments
	LSHSimilarityThreshold float64 `json:"lsh_similarity_threshold"`
	LSHBands               int     `json:"lsh_bands"`
	LSHRows                int     `json:"lsh_rows"`
	LSHHashes              int     `json:"lsh_hashes"`
}

type CloneResponse struct {
	// Results
	Clones      []*Clone         `json:"clones" yaml:"clones" csv:"clones"`
	ClonePairs  []*ClonePair     `json:"clone_pairs" yaml:"clone_pairs" csv:"clone_pairs"`
	CloneGroups []*CloneGroup    `json:"clone_groups" yaml:"clone_groups" csv:"clone_groups"`
	Statistics  *CloneStatistics `json:"statistics" yaml:"statistics" csv:"statistics"`

	// Metadata
	Request  *CloneRequest `json:"request,omitempty" yaml:"request,omitempty" csv:"-"`
	Duration int64         `json:"duration_ms" yaml:"duration_ms" csv:"duration_ms"`
	Success  bool          `json:"success" yaml:"success" csv:"success"`
	Error    string        `json:"error,omitempty" yaml:"error,omitempty" csv:"error"`
	// Errors holds per-file failures. Error above reports why the whole run
	// failed; a file listed here was skipped while the run itself succeeded,
	// so its contents are absent from every statistic in this response.
	Errors   []string          `json:"errors,omitempty" yaml:"errors,omitempty" csv:"-"`
	Failures []AnalysisFailure `json:"failures,omitempty" yaml:"failures,omitempty" csv:"-"`
}

type CloneService interface {
	// DetectClones performs clone detection on the given request
	DetectClones(ctx context.Context, req *CloneRequest) (*CloneResponse, error)

	// DetectClonesInFiles performs clone detection on specific files
	DetectClonesInFiles(ctx context.Context, filePaths []string, req *CloneRequest) (*CloneResponse, error)

	// ComputeSimilarity computes similarity between two code fragments
	ComputeSimilarity(ctx context.Context, fragment1, fragment2 string) (float64, error)
}

type CloneSortCriteria string

type CloneStatistics struct {
	TotalFragments    int            `json:"total_fragments" yaml:"total_fragments" csv:"total_fragments"` // All extracted fragments (functions, classes, etc.)
	TotalClones       int            `json:"total_clones" yaml:"total_clones" csv:"total_clones"`          // Fragments detected as clones
	TotalClonePairs   int            `json:"total_clone_pairs" yaml:"total_clone_pairs" csv:"total_clone_pairs"`
	TotalCloneGroups  int            `json:"total_clone_groups" yaml:"total_clone_groups" csv:"total_clone_groups"`
	ClonesByType      map[string]int `json:"clones_by_type" yaml:"clones_by_type" csv:"clones_by_type"`
	AverageSimilarity float64        `json:"average_similarity" yaml:"average_similarity" csv:"average_similarity"`
	LinesAnalyzed     int            `json:"lines_analyzed" yaml:"lines_analyzed" csv:"lines_analyzed"`
	NodesAnalyzed     int            `json:"nodes_analyzed" yaml:"nodes_analyzed" csv:"nodes_analyzed"`
	FilesAnalyzed     int            `json:"files_analyzed" yaml:"files_analyzed" csv:"files_analyzed"`
}

type CloneType int

type CohesionAnalysis struct {
	PackageCohesion     map[string]float64 `json:"package_cohesion" yaml:"package_cohesion"`           // Package -> cohesion score
	LowCohesionPackages []string           `json:"low_cohesion_packages" yaml:"low_cohesion_packages"` // Packages with low cohesion
	CohesionSuggestions map[string]string  `json:"cohesion_suggestions" yaml:"cohesion_suggestions"`   // Package -> suggestion
}

type CommunityAnalysisOutputFormatter interface {
	Format(response *CommunityAnalysisResult, format OutputFormat) (string, error)
	Write(response *CommunityAnalysisResult, format OutputFormat, writer io.Writer) error
}

type CommunityAnalysisRequest struct {
	// Input files or directories to analyze
	Paths []string

	// SourcePaths preserves the original user-provided paths before file expansion.
	// Used for project-root detection when Paths contains only resolved files.
	SourcePaths []string

	// Output configuration
	OutputFormat OutputFormat
	OutputWriter io.Writer
	OutputPath   string
	NoOpen       bool

	// Configuration
	ConfigPath      string
	ProjectRoot     string
	Recursive       *bool
	IncludePatterns []string
	ExcludePatterns []string

	// Community detection options
	Algorithm           string
	Scope               string
	MinCommunitySize    int
	IncludeLazyEdges    *bool
	ReportBridgeModules *bool
	Resolution          float64

	// Module graph options
	IncludeStdLib     *bool
	IncludeThirdParty *bool
	FollowRelative    *bool

	// ArchitectureRules supplies configured layers for layer mismatch scoring.
	// Loaded from config when not set explicitly.
	ArchitectureRules *ArchitectureRules
}

type CommunityAnalysisResult struct {
	Algorithm        string             `json:"algorithm" yaml:"algorithm"`
	Scope            string             `json:"scope" yaml:"scope"`
	TotalCommunities int                `json:"total_communities" yaml:"total_communities"`
	Modularity       float64            `json:"modularity" yaml:"modularity"`
	Communities      []CommunityMetrics `json:"communities" yaml:"communities"`
	BridgeModules    []BridgeModule     `json:"bridge_modules" yaml:"bridge_modules"`

	// Package mismatch metrics compare inferred communities to declared package boundaries.
	PackageAlignmentScore *float64 `json:"package_alignment_score,omitempty" yaml:"package_alignment_score,omitempty"`
	SplitPackages         []string `json:"split_packages,omitempty" yaml:"split_packages,omitempty"`
	MixedCommunities      []string `json:"mixed_communities,omitempty" yaml:"mixed_communities,omitempty"`

	// Layer mismatch metrics compare inferred communities to configured architecture layers.
	LayerAlignmentScore   *float64 `json:"layer_alignment_score,omitempty" yaml:"layer_alignment_score,omitempty"`
	CrossLayerCommunities []string `json:"cross_layer_communities,omitempty" yaml:"cross_layer_communities,omitempty"`
	LayerBridgeModules    []string `json:"layer_bridge_modules,omitempty" yaml:"layer_bridge_modules,omitempty"`

	// RiskScore is a system-level community risk score (0-100, higher = worse),
	// populated by ScoreCommunityResult. Nil when fewer than two communities were
	// detected (no meaningful modular structure to score).
	RiskScore *int `json:"community_risk_score,omitempty" yaml:"community_risk_score,omitempty"`

	// ContextMap is a compact, agent-optimized view of the communities (which
	// modules to inspect together, which modules bridge clusters). Populated by
	// ScoreCommunityResult whenever at least one community was detected.
	ContextMap *CommunityContextMap `json:"community_context_map,omitempty" yaml:"community_context_map,omitempty"`

	// ModuleDependencies holds directed edges for DOT export and is omitted from JSON/YAML.
	ModuleDependencies []CommunityModuleDependency `json:"-" yaml:"-"`

	// BridgeModuleCount is the number of detected bridge modules from the
	// underlying analysis. It is tracked independently of BridgeModules (which is
	// only populated when bridge reporting is enabled) so risk scoring does not
	// depend on a presentation option. Omitted from JSON/YAML.
	BridgeModuleCount int `json:"-" yaml:"-"`

	Warnings []string          `json:"warnings,omitempty" yaml:"warnings,omitempty"`
	Errors   []string          `json:"errors,omitempty" yaml:"errors,omitempty"`
	Failures []AnalysisFailure `json:"failures,omitempty" yaml:"failures,omitempty"`

	GeneratedAt string      `json:"generated_at" yaml:"generated_at"`
	Version     string      `json:"version" yaml:"version"`
	Config      interface{} `json:"config,omitempty" yaml:"config,omitempty"`
}

type CommunityAnalysisService interface {
	Analyze(ctx context.Context, req CommunityAnalysisRequest) (*CommunityAnalysisResult, error)
}

type CommunityBundle struct {
	CommunityID          string   `json:"community_id" yaml:"community_id"`
	Modules              []string `json:"modules" yaml:"modules"`
	ModuleCount          int      `json:"module_count" yaml:"module_count"`
	Packages             []string `json:"packages" yaml:"packages"`
	RiskLevel            string   `json:"risk_level" yaml:"risk_level"`
	BridgeModules        []string `json:"bridge_modules" yaml:"bridge_modules"`
	SuggestedReviewScope string   `json:"suggested_review_scope,omitempty" yaml:"suggested_review_scope,omitempty"`
	Summary              string   `json:"summary" yaml:"summary"`
}

type CommunityConfigurationLoader interface {
	LoadConfig(path string) (*CommunityAnalysisRequest, error)
	LoadDefaultConfig(targetPath string) *CommunityAnalysisRequest
	MergeConfig(base *CommunityAnalysisRequest, override *CommunityAnalysisRequest) *CommunityAnalysisRequest
}

type CommunityContextMap struct {
	Version       int                   `json:"version" yaml:"version"`
	Bundles       []CommunityBundle     `json:"bundles" yaml:"bundles"`
	BridgeModules []ContextBridgeModule `json:"bridge_modules" yaml:"bridge_modules"`
}

type CommunityMetrics struct {
	ID                          string   `json:"id" yaml:"id"`
	Modules                     []string `json:"modules" yaml:"modules"`
	Packages                    []string `json:"packages" yaml:"packages"`
	InternalEdges               int      `json:"internal_edges" yaml:"internal_edges"`
	ExternalEdges               int      `json:"external_edges" yaml:"external_edges"`
	ExternalDependencyRatio     float64  `json:"external_dependency_ratio" yaml:"external_dependency_ratio"`
	IncomingCrossCommunityEdges int      `json:"incoming_cross_community_edges" yaml:"incoming_cross_community_edges"`
	OutgoingCrossCommunityEdges int      `json:"outgoing_cross_community_edges" yaml:"outgoing_cross_community_edges"`
	Size                        int      `json:"size" yaml:"size"`

	// Package mismatch metrics (omitted when package metadata is unavailable).
	DominantPackage  string  `json:"dominant_package,omitempty" yaml:"dominant_package,omitempty"`
	PackageCount     int     `json:"package_count,omitempty" yaml:"package_count,omitempty"`
	PackageAlignment float64 `json:"package_alignment,omitempty" yaml:"package_alignment,omitempty"`

	// Layer mismatch metrics (omitted when architecture layers are not configured).
	DominantLayer  string   `json:"dominant_layer,omitempty" yaml:"dominant_layer,omitempty"`
	LayerCount     int      `json:"layer_count,omitempty" yaml:"layer_count,omitempty"`
	Layers         []string `json:"layers,omitempty" yaml:"layers,omitempty"`
	LayerAlignment *float64 `json:"layer_alignment,omitempty" yaml:"layer_alignment,omitempty"`

	// RiskLevel classifies the community as low/medium/high using documented
	// thresholds (see docs/ANALYZE_SCORING.md). Populated by ScoreCommunityResult.
	RiskLevel string `json:"risk_level,omitempty" yaml:"risk_level,omitempty"`
}

type CommunityModuleDependency struct {
	From string
	To   string
}

type ComplexityMetrics struct {
	// McCabe cyclomatic complexity
	Complexity int `json:"complexity" yaml:"complexity"`

	// Cognitive complexity (SonarQube-style)
	CognitiveComplexity int `json:"cognitive_complexity" yaml:"cognitive_complexity"`

	// CFG metrics
	Nodes int `json:"nodes" yaml:"nodes"`
	Edges int `json:"edges" yaml:"edges"`

	// Nesting depth
	NestingDepth int `json:"nesting_depth" yaml:"nesting_depth"`

	// Statement counts
	IfStatements      int `json:"if_statements" yaml:"if_statements"`
	LoopStatements    int `json:"loop_statements" yaml:"loop_statements"`
	ExceptionHandlers int `json:"exception_handlers" yaml:"exception_handlers"`
	SwitchCases       int `json:"switch_cases" yaml:"switch_cases"`

	// SLOC is the source lines of code within this function's line range.
	// Computed using the same line-classification logic as raw_metrics.
	SLOC int `json:"sloc" yaml:"sloc"`
}

type ComplexityRequest struct {
	// Input files or directories to analyze
	Paths []string `json:"paths" yaml:"paths"`

	// Output configuration
	OutputFormat OutputFormat `json:"output_format" yaml:"output_format"`
	OutputWriter io.Writer    `json:"-" yaml:"-"`
	OutputPath   string       `json:"output_path" yaml:"output_path"`   // Path to save output file (for HTML format)
	NoOpen       bool         `json:"no_open" yaml:"no_open"`           // Don't auto-open HTML in browser
	ShowDetails  *bool        `json:"show_details" yaml:"show_details"` // nil = unset, non-nil = explicitly set

	// Filtering and sorting
	MinComplexity int          `json:"min_complexity" yaml:"min_complexity"`
	MaxComplexity int          `json:"max_complexity" yaml:"max_complexity"` // 0 means no limit
	SortBy        SortCriteria `json:"sort_by" yaml:"sort_by"`

	// Complexity thresholds
	LowThreshold                 int `json:"low_threshold" yaml:"low_threshold"`
	MediumThreshold              int `json:"medium_threshold" yaml:"medium_threshold"`
	CognitiveComplexityThreshold int `json:"cognitive_complexity_threshold" yaml:"cognitive_complexity_threshold"`
	NestingDepthThreshold        int `json:"nesting_depth_threshold" yaml:"nesting_depth_threshold"`

	// Function SLOC thresholds
	FunctionSLOCWarnThreshold     int `json:"function_sloc_warn_threshold" yaml:"function_sloc_warn_threshold"`
	FunctionSLOCCriticalThreshold int `json:"function_sloc_critical_threshold" yaml:"function_sloc_critical_threshold"`

	// Analysis toggles loaded from configuration when present.
	// Nil means "use the default enabled behavior".
	Enabled         *bool `json:"enabled" yaml:"enabled"`
	ReportUnchanged *bool `json:"report_unchanged" yaml:"report_unchanged"`

	// Configuration
	ConfigPath string `json:"config_path" yaml:"config_path"`

	// Analysis options
	Recursive       *bool    `json:"recursive" yaml:"recursive"` // nil = unset, non-nil = explicitly set
	IncludePatterns []string `json:"include_patterns" yaml:"include_patterns"`
	ExcludePatterns []string `json:"exclude_patterns" yaml:"exclude_patterns"`
}

type ComplexityResponse struct {
	// Functions retains the established module and function population.
	Functions []FunctionComplexity `json:"functions" yaml:"functions"`
	// ClassScopes is an additive collection of executable class-suite results.
	// It uses the same typed metric record without changing function summaries.
	ClassScopes []FunctionComplexity           `json:"class_scopes,omitempty" yaml:"class_scopes,omitempty"`
	ByDirectory DirectoryComplexityMetricsList `json:"by_directory" yaml:"by_directory"`
	Summary     ComplexitySummary              `json:"summary" yaml:"summary"`
	// AnalyzedFunctions is the complete population before presentation filters.
	// It is consumed by app-level aggregations and is not part of public output.
	AnalyzedFunctions []FunctionComplexity `json:"-" yaml:"-"`
	// AnalyzedClassScopes is the complete class-suite population before
	// presentation filters and is not part of public output.
	AnalyzedClassScopes []FunctionComplexity `json:"-" yaml:"-"`
	// ModuleRollups are derived before report filters are applied. They are consumed
	// by the unified analyze command and are not part of standalone complexity output.
	ModuleRollups map[string]ModuleComplexityMetrics `json:"-" yaml:"-"`

	// File-level raw code metrics
	RawMetrics        []RawMetrics       `json:"raw_metrics,omitempty" yaml:"raw_metrics,omitempty"`
	RawMetricsSummary *RawMetricsSummary `json:"raw_metrics_summary,omitempty" yaml:"raw_metrics_summary,omitempty"`

	// Warnings and issues
	Warnings []string          `json:"warnings" yaml:"warnings"`
	Errors   []string          `json:"errors" yaml:"errors"`
	Failures []AnalysisFailure `json:"failures,omitempty" yaml:"failures,omitempty"`

	// Metadata
	GeneratedAt string             `json:"generated_at" yaml:"generated_at"`
	Version     string             `json:"version" yaml:"version"`
	Config      interface{}        `json:"config" yaml:"config"` // Configuration used for analysis
	Request     *ComplexityRequest `json:"request,omitempty"`    // Merged configuration request
}

type ComplexityService interface {
	// Analyze performs complexity analysis on the given request
	Analyze(ctx context.Context, req ComplexityRequest) (*ComplexityResponse, error)

	// AnalyzeFile analyzes a single Python file
	AnalyzeFile(ctx context.Context, filePath string, req ComplexityRequest) (*ComplexityResponse, error)
}

type ComplexitySummary struct {
	// TotalFunctions is the complete analyzed function population used by all
	// aggregate metrics, including the established module pseudo-record.
	// Presentation filters only limit ComplexityResponse.Functions.
	TotalFunctions int `json:"total_functions" yaml:"total_functions"`
	// TotalClassScopes is the complete executable class-suite population.
	// Class maxima are published separately and do not alter function aggregates
	// or health-score semantics.
	TotalClassScopes            int `json:"total_class_scopes" yaml:"total_class_scopes"`
	MaxClassComplexity          int `json:"max_class_complexity" yaml:"max_class_complexity"`
	MaxClassCognitiveComplexity int `json:"max_class_cognitive_complexity" yaml:"max_class_cognitive_complexity"`
	MaxClassNestingDepth        int `json:"max_class_nesting_depth" yaml:"max_class_nesting_depth"`
	HighRiskClassScopes         int `json:"high_risk_class_scopes" yaml:"high_risk_class_scopes"`
	// FunctionsParsed is always equal to TotalFunctions. It is retained only
	// for JSON/YAML schema compatibility and will be removed; consumers should
	// read TotalFunctions. The displayed subset is len(ComplexityResponse.Functions).
	FunctionsParsed            int     `json:"functions_parsed" yaml:"functions_parsed"`
	AverageComplexity          float64 `json:"average_complexity" yaml:"average_complexity"`
	AverageCognitiveComplexity float64 `json:"average_cognitive_complexity" yaml:"average_cognitive_complexity"`
	AverageNestingDepth        float64 `json:"average_nesting_depth" yaml:"average_nesting_depth"`
	MaxComplexity              int     `json:"max_complexity" yaml:"max_complexity"`
	MinComplexity              int     `json:"min_complexity" yaml:"min_complexity"`
	// FilesAnalyzed is the number of files that were successfully parsed and
	// contributed to the metrics above.
	FilesAnalyzed int `json:"files_analyzed" yaml:"files_analyzed"`
	// TotalFiles is the number of files the request covered, parsed or not.
	TotalFiles int `json:"total_files" yaml:"total_files"`
	// SkippedFiles is the number of files dropped because they could not be
	// read or parsed. Their contents are absent from every metric, so a
	// consumer must read this before trusting the aggregates.
	SkippedFiles int `json:"skipped_files" yaml:"skipped_files"`

	// Risk distribution
	LowRiskFunctions    int `json:"low_risk_functions" yaml:"low_risk_functions"`
	MediumRiskFunctions int `json:"medium_risk_functions" yaml:"medium_risk_functions"`
	HighRiskFunctions   int `json:"high_risk_functions" yaml:"high_risk_functions"`

	// Complexity distribution
	ComplexityDistribution map[string]int `json:"complexity_distribution" yaml:"complexity_distribution"`
}

type ConcreteDependencySubtype string

type ConfigurationLoader interface {
	// LoadConfig loads configuration from the specified path
	LoadConfig(path string) (*ComplexityRequest, error)

	// LoadDefaultConfig discovers configuration from targetPath (the analyzed
	// path) and falls back to built-in defaults when none is found
	LoadDefaultConfig(targetPath string) *ComplexityRequest

	// MergeConfig merges CLI flags with configuration file
	MergeConfig(base *ComplexityRequest, override *ComplexityRequest) *ComplexityRequest
}

type ContextBridgeModule struct {
	Module   string   `json:"module" yaml:"module"`
	Connects []string `json:"connects" yaml:"connects"`
	Reason   string   `json:"reason" yaml:"reason"`
}

type CouplingAnalysis struct {
	// Overall coupling metrics
	AverageCoupling       float64     `json:"average_coupling" yaml:"average_coupling"`               // Average coupling across all modules
	CouplingDistribution  map[int]int `json:"coupling_distribution" yaml:"coupling_distribution"`     // Coupling value -> count
	HighlyCoupledModules  []string    `json:"highly_coupled_modules" yaml:"highly_coupled_modules"`   // Modules with high coupling
	LooselyCoupledModules []string    `json:"loosely_coupled_modules" yaml:"loosely_coupled_modules"` // Modules with low coupling

	// Instability analysis
	AverageInstability float64  `json:"average_instability" yaml:"average_instability"` // Average instability
	StableModules      []string `json:"stable_modules" yaml:"stable_modules"`           // Low instability modules
	InstableModules    []string `json:"instable_modules" yaml:"instable_modules"`       // High instability modules

	// Main sequence analysis
	MainSequenceDeviation float64  `json:"main_sequence_deviation" yaml:"main_sequence_deviation"` // Average distance from main sequence
	ZoneOfPain            []string `json:"zone_of_pain" yaml:"zone_of_pain"`                       // Stable + concrete modules
	ZoneOfUselessness     []string `json:"zone_of_uselessness" yaml:"zone_of_uselessness"`         // Unstable + abstract modules
	MainSequence          []string `json:"main_sequence" yaml:"main_sequence"`                     // Well-positioned modules
}

type CustomRule struct {
	Name        string            `json:"name" yaml:"name"`
	Pattern     string            `json:"pattern" yaml:"pattern"`
	Description string            `json:"description" yaml:"description"`
	Severity    ViolationSeverity `json:"severity" yaml:"severity"`
}

type CycleSeverity string

type DIAntipatternConfigurationLoader interface {
	// LoadConfig loads configuration from the specified path
	LoadConfig(path string) (*DIAntipatternRequest, error)

	// LoadDefaultConfig discovers configuration from targetPath (the analyzed
	// path) and falls back to built-in defaults when none is found
	LoadDefaultConfig(targetPath string) *DIAntipatternRequest

	// MergeConfig merges CLI flags with configuration file
	MergeConfig(base *DIAntipatternRequest, override *DIAntipatternRequest) *DIAntipatternRequest
}

type DIAntipatternFinding struct {
	// Type of the anti-pattern
	Type DIAntipatternType `json:"type"`

	// Subtype for hidden dependency and concrete dependency patterns
	Subtype string `json:"subtype,omitempty"`

	// Severity of the finding
	Severity DIAntipatternSeverity `json:"severity"`

	// Class name where the anti-pattern was found
	ClassName string `json:"class_name,omitempty"`

	// Method name where the anti-pattern was found
	MethodName string `json:"method_name,omitempty"`

	// Location in source code
	Location SourceLocation `json:"location"`

	// Human-readable description of the issue
	Description string `json:"description"`

	// Suggestion for fixing the issue
	Suggestion string `json:"suggestion"`

	// Additional details specific to the anti-pattern type
	Details map[string]interface{} `json:"details,omitempty"`
}

type DIAntipatternOutputFormatter interface {
	// Format formats the analysis response according to the specified format
	Format(response *DIAntipatternResponse, format OutputFormat) (string, error)

	// Write writes the formatted output to the writer
	Write(response *DIAntipatternResponse, format OutputFormat, writer io.Writer) error
}

type DIAntipatternRequest struct {
	// Input files or directories to analyze
	Paths []string

	// Output configuration
	OutputFormat OutputFormat
	OutputWriter io.Writer
	OutputPath   string
	NoOpen       bool

	// Analysis options
	Recursive       *bool
	IncludePatterns []string
	ExcludePatterns []string

	// Configuration
	ConfigPath string

	// DI-specific options
	// ConstructorParamThreshold is the maximum allowed constructor parameters (default: 5)
	ConstructorParamThreshold int

	// MinSeverity filters findings by minimum severity level
	MinSeverity DIAntipatternSeverity

	// SortBy specifies the sort order
	SortBy SortCriteria
}

type DIAntipatternResponse struct {
	// Findings contains all detected anti-patterns
	Findings []DIAntipatternFinding `json:"findings"`

	// Summary contains aggregate statistics
	Summary DIAntipatternSummary `json:"summary"`

	// Warnings contains non-fatal issues encountered during analysis
	Warnings []string `json:"warnings,omitempty"`

	// Errors contains errors encountered during analysis
	Errors []string `json:"errors,omitempty"`
	// Diagnostics contains typed file read and parse failures.
	Diagnostics []AnalysisDiagnostic `json:"diagnostics,omitempty"`
	// Failures contains DI calculation failures.
	Failures []AnalysisFailure `json:"failures,omitempty"`

	// Metadata
	GeneratedAt string      `json:"generated_at"`
	Version     string      `json:"version"`
	Config      interface{} `json:"config,omitempty"`
}

type DIAntipatternService interface {
	// Analyze performs DI anti-pattern analysis on the given request
	Analyze(ctx context.Context, req DIAntipatternRequest) (*DIAntipatternResponse, error)

	// AnalyzeFile analyzes a single Python file
	AnalyzeFile(ctx context.Context, filePath string, req DIAntipatternRequest) (*DIAntipatternResponse, error)
}

type DIAntipatternSeverity string

type DIAntipatternSummary struct {
	// TotalFindings is the total number of findings
	TotalFindings int `json:"total_findings"`

	// ByType breaks down findings by anti-pattern type
	ByType map[DIAntipatternType]int `json:"by_type"`

	// BySeverity breaks down findings by severity
	BySeverity map[DIAntipatternSeverity]int `json:"by_severity"`

	// FilesAnalyzed is the number of files analyzed
	FilesAnalyzed int `json:"files_analyzed"`

	// AffectedClasses is the number of classes with at least one finding
	AffectedClasses int `json:"affected_classes"`
}

type DIAntipatternType string

type DeadCodeConfigurationLoader interface {
	// LoadConfig loads dead code configuration from the specified path
	LoadConfig(path string) (*DeadCodeRequest, error)

	// LoadDefaultConfig discovers configuration from targetPath (the analyzed
	// path) and falls back to built-in defaults when none is found
	LoadDefaultConfig(targetPath string) *DeadCodeRequest

	// MergeConfig merges CLI flags with configuration file
	MergeConfig(base *DeadCodeRequest, override *DeadCodeRequest) *DeadCodeRequest
}

type DeadCodeFinding struct {
	// Location information
	Location DeadCodeLocation `json:"location" yaml:"location"`

	// Execution-scope context. FunctionName is retained for public compatibility.
	FunctionName string            `json:"function_name" yaml:"function_name"`
	ScopeKind    AnalysisScopeKind `json:"scope_kind" yaml:"scope_kind"`

	// Dead code details
	Code        string           `json:"code" yaml:"code"`
	Reason      string           `json:"reason" yaml:"reason"`
	Severity    DeadCodeSeverity `json:"severity" yaml:"severity"`
	Description string           `json:"description" yaml:"description"`

	// Context information (surrounding code)
	Context []string `json:"context,omitempty" yaml:"context,omitempty"`

	// Metadata
	BlockID string `json:"block_id,omitempty" yaml:"block_id,omitempty"`
}

type DeadCodeFormatter interface {
	// Format formats the dead code analysis response according to the specified format
	Format(response *DeadCodeResponse, format OutputFormat) (string, error)

	// Write writes the formatted dead code output to the writer
	Write(response *DeadCodeResponse, format OutputFormat, writer io.Writer) error

	// FormatFinding formats a single dead code finding
	FormatFinding(finding DeadCodeFinding, format OutputFormat) (string, error)
}

type DeadCodeLocation struct {
	FilePath    string `json:"file_path" yaml:"file_path"`
	StartLine   int    `json:"start_line" yaml:"start_line"`
	EndLine     int    `json:"end_line" yaml:"end_line"`
	StartColumn int    `json:"start_column" yaml:"start_column"`
	EndColumn   int    `json:"end_column" yaml:"end_column"`
}

type DeadCodeRequest struct {
	// Input files or directories to analyze
	Paths []string `json:"paths" yaml:"paths"`

	// Output configuration
	OutputFormat OutputFormat `json:"output_format" yaml:"output_format"`
	OutputWriter io.Writer    `json:"-" yaml:"-"`
	OutputPath   string       `json:"output_path" yaml:"output_path"`     // Path to save output file (for HTML format)
	NoOpen       bool         `json:"no_open" yaml:"no_open"`             // Don't auto-open HTML in browser
	ShowContext  *bool        `json:"show_context" yaml:"show_context"`   // nil = use default (false), non-nil = explicitly set
	ContextLines int          `json:"context_lines" yaml:"context_lines"` // Number of lines to show around dead code

	// Filtering and sorting
	MinSeverity DeadCodeSeverity     `json:"min_severity" yaml:"min_severity"`
	SortBy      DeadCodeSortCriteria `json:"sort_by" yaml:"sort_by"`

	// Analysis options
	Recursive       *bool    `json:"recursive" yaml:"recursive"` // nil = unset, non-nil = explicitly set
	IncludePatterns []string `json:"include_patterns" yaml:"include_patterns"`
	ExcludePatterns []string `json:"exclude_patterns" yaml:"exclude_patterns"`
	IgnorePatterns  []string `json:"ignore_patterns" yaml:"ignore_patterns"` // Patterns for code to ignore (e.g., comments, debug code)

	// Configuration
	ConfigPath string `json:"config_path" yaml:"config_path"`

	// Dead code specific options
	DetectAfterReturn         *bool `json:"detect_after_return" yaml:"detect_after_return"`                 // nil = use default (true), non-nil = explicitly set
	DetectAfterBreak          *bool `json:"detect_after_break" yaml:"detect_after_break"`                   // nil = use default (true), non-nil = explicitly set
	DetectAfterContinue       *bool `json:"detect_after_continue" yaml:"detect_after_continue"`             // nil = use default (true), non-nil = explicitly set
	DetectAfterRaise          *bool `json:"detect_after_raise" yaml:"detect_after_raise"`                   // nil = use default (true), non-nil = explicitly set
	DetectUnreachableBranches *bool `json:"detect_unreachable_branches" yaml:"detect_unreachable_branches"` // nil = use default (true), non-nil = explicitly set
}

type DeadCodeResponse struct {
	// Analysis results
	Files   []FileDeadCode  `json:"files" yaml:"files"`
	Summary DeadCodeSummary `json:"summary" yaml:"summary"`
	// ModuleRollups are derived before severity filters are applied. They are consumed
	// by the unified analyze command and are not part of standalone dead-code output.
	ModuleRollups map[string]ModuleDeadCodeMetrics `json:"-" yaml:"-"`

	// Warnings and issues
	Warnings []string          `json:"warnings" yaml:"warnings"`
	Errors   []string          `json:"errors" yaml:"errors"`
	Failures []AnalysisFailure `json:"failures,omitempty" yaml:"failures,omitempty"`

	// Metadata
	GeneratedAt string           `json:"generated_at" yaml:"generated_at"`
	Version     string           `json:"version" yaml:"version"`
	Config      interface{}      `json:"config" yaml:"config"`                       // Configuration used for analysis
	Request     *DeadCodeRequest `json:"request,omitempty" yaml:"request,omitempty"` // Merged configuration request
}

type DeadCodeService interface {
	// Analyze performs dead code analysis on the given request
	Analyze(ctx context.Context, req DeadCodeRequest) (*DeadCodeResponse, error)

	// AnalyzeFile analyzes a single Python file for dead code
	AnalyzeFile(ctx context.Context, filePath string, req DeadCodeRequest) (*FileDeadCode, error)

	// AnalyzeFunction analyzes a single function for dead code
	AnalyzeFunction(ctx context.Context, functionCFG interface{}, req DeadCodeRequest) (*FunctionDeadCode, error)
}

type DeadCodeSeverity string

type DeadCodeSortCriteria string

type DeadCodeSummary struct {
	// Overall metrics
	TotalFiles              int `json:"total_files" yaml:"total_files"`
	TotalFunctions          int `json:"total_functions" yaml:"total_functions"`
	TotalFindings           int `json:"total_findings" yaml:"total_findings"`
	FilesWithDeadCode       int `json:"files_with_dead_code" yaml:"files_with_dead_code"`
	FunctionsWithDeadCode   int `json:"functions_with_dead_code" yaml:"functions_with_dead_code"`
	TotalClassScopes        int `json:"total_class_scopes" yaml:"total_class_scopes"`
	ClassScopesWithDeadCode int `json:"class_scopes_with_dead_code" yaml:"class_scopes_with_dead_code"`

	// Severity distribution
	CriticalFindings int `json:"critical_findings" yaml:"critical_findings"`
	WarningFindings  int `json:"warning_findings" yaml:"warning_findings"`
	InfoFindings     int `json:"info_findings" yaml:"info_findings"`

	// Reason distribution
	FindingsByReason map[string]int `json:"findings_by_reason" yaml:"findings_by_reason"`

	// Coverage metrics
	TotalBlocks      int     `json:"total_blocks" yaml:"total_blocks"`
	DeadBlocks       int     `json:"dead_blocks" yaml:"dead_blocks"`
	OverallDeadRatio float64 `json:"overall_dead_ratio" yaml:"overall_dead_ratio"`
}

type DependencyAnalysisResult struct {
	// Dependency graph information
	TotalModules      int      `json:"total_modules" yaml:"total_modules"`           // Total number of modules
	TotalDependencies int      `json:"total_dependencies" yaml:"total_dependencies"` // Total number of dependencies
	ResolvedImports   int      `json:"resolved_imports" yaml:"resolved_imports"`     // Internal imports resolved to analyzed modules
	UnresolvedImports int      `json:"unresolved_imports" yaml:"unresolved_imports"` // Internal imports that could not be resolved
	RootModules       []string `json:"root_modules" yaml:"root_modules"`             // Modules with no dependencies
	LeafModules       []string `json:"leaf_modules" yaml:"leaf_modules"`             // Modules with no dependents

	// Dependency metrics
	ModuleMetrics    map[string]*ModuleDependencyMetrics `json:"module_metrics" yaml:"module_metrics"`       // Per-module metrics
	DependencyMatrix map[string]map[string]bool          `json:"dependency_matrix" yaml:"dependency_matrix"` // Module -> dependencies

	// Circular dependency analysis
	CircularDependencies *CircularDependencyAnalysis `json:"circular_dependencies" yaml:"circular_dependencies"` // Circular dependency results

	// Coupling analysis
	CouplingAnalysis *CouplingAnalysis `json:"coupling_analysis" yaml:"coupling_analysis"` // Detailed coupling analysis

	// Dependency chains
	LongestChains []DependencyPath `json:"longest_chains" yaml:"longest_chains"` // Longest paths through the load-time SCC-condensed dependency graph
	MaxDepth      int              `json:"max_depth" yaml:"max_depth"`           // Edges along the chain LongestChains ranks first
}

type DependencyPath struct {
	From   string   `json:"from" yaml:"from"`     // Starting module
	To     string   `json:"to" yaml:"to"`         // Ending module
	Path   []string `json:"path" yaml:"path"`     // Complete path
	Length int      `json:"length" yaml:"length"` // Path length
}

type DiagnosticCode string

type DirectoryComplexityMetrics struct {
	DirectoryPath         string  `json:"directory_path" yaml:"directory_path"`
	FunctionCount         int     `json:"function_count" yaml:"function_count"`
	AverageComplexity     float64 `json:"average_complexity" yaml:"average_complexity"`
	MaxComplexity         int     `json:"max_complexity" yaml:"max_complexity"`
	HighRiskFunctionCount int     `json:"high_risk_function_count" yaml:"high_risk_function_count"`
	AverageNestingDepth   float64 `json:"average_nesting_depth" yaml:"average_nesting_depth"`
	MaxNestingDepth       int     `json:"max_nesting_depth" yaml:"max_nesting_depth"`
}

type DirectoryComplexityMetricsList []DirectoryComplexityMetrics

type DomainError struct {
	Code    string
	Message string
	Cause   error
}

type ErrorCategorizer interface {
	// Categorize determines the category of an error
	Categorize(err error) *CategorizedError

	// GetRecoverySuggestions returns recovery suggestions for an error category
	GetRecoverySuggestions(category ErrorCategory) []string
}

type ErrorCategory string

type EstimatedEffort string

type ExecutableTask interface {
	// Name returns the name of the task
	Name() string

	// Execute runs the task and returns the result
	Execute(ctx context.Context) (interface{}, error)

	// IsEnabled returns whether the task should be executed
	IsEnabled() bool
}

type FileDeadCode struct {
	// File identification
	FilePath string `json:"file_path" yaml:"file_path"`

	// Functions analyzed
	Functions []FunctionDeadCode `json:"functions" yaml:"functions"`
	// ClassScopes contains executable class-suite results.
	ClassScopes []FunctionDeadCode `json:"class_scopes,omitempty" yaml:"class_scopes,omitempty"`

	// File-level summary
	TotalFindings       int     `json:"total_findings" yaml:"total_findings"`
	TotalFunctions      int     `json:"total_functions" yaml:"total_functions"`
	AffectedFunctions   int     `json:"affected_functions" yaml:"affected_functions"`
	TotalClassScopes    int     `json:"total_class_scopes" yaml:"total_class_scopes"`
	AffectedClassScopes int     `json:"affected_class_scopes" yaml:"affected_class_scopes"`
	DeadCodeRatio       float64 `json:"dead_code_ratio" yaml:"dead_code_ratio"`
}

type FileMockData struct {
	// File identification
	FilePath string `json:"file_path"`

	// Findings
	Findings []MockDataFinding `json:"findings"`

	// File-level summary
	TotalFindings int `json:"total_findings"`
	ErrorCount    int `json:"error_count"`
	WarningCount  int `json:"warning_count"`
	InfoCount     int `json:"info_count"`
}

type FileReader interface {
	// CollectPythonFiles recursively finds all Python files in the given paths
	CollectPythonFiles(paths []string, recursive bool, includePatterns, excludePatterns []string) ([]string, error)

	// ReadFile reads the content of a file
	ReadFile(path string) ([]byte, error)

	// IsValidPythonFile checks if a file is a valid Python file
	IsValidPythonFile(path string) bool

	// FileExists checks if a file exists and returns an error if not
	FileExists(path string) (bool, error)
}

type FunctionComplexity struct {
	// Function identification
	Name        string            `json:"name" yaml:"name"`
	ScopeKind   AnalysisScopeKind `json:"scope_kind" yaml:"scope_kind"`
	FilePath    string            `json:"file_path" yaml:"file_path"`
	StartLine   int               `json:"start_line" yaml:"start_line"`
	StartColumn int               `json:"start_column" yaml:"start_column"`
	EndLine     int               `json:"end_line" yaml:"end_line"`

	// Complexity metrics
	Metrics ComplexityMetrics `json:"metrics" yaml:"metrics"`

	// Risk assessment
	RiskLevel RiskLevel `json:"risk_level" yaml:"risk_level"`
}

type FunctionDeadCode struct {
	// Execution-scope identification
	Name      string            `json:"name" yaml:"name"`
	ScopeKind AnalysisScopeKind `json:"scope_kind" yaml:"scope_kind"`
	FilePath  string            `json:"file_path" yaml:"file_path"`

	// Dead code findings
	Findings []DeadCodeFinding `json:"findings" yaml:"findings"`

	// Function metrics
	TotalBlocks    int     `json:"total_blocks" yaml:"total_blocks"`
	DeadBlocks     int     `json:"dead_blocks" yaml:"dead_blocks"`
	ReachableRatio float64 `json:"reachable_ratio" yaml:"reachable_ratio"`

	// Summary by severity
	CriticalCount int `json:"critical_count" yaml:"critical_count"`
	WarningCount  int `json:"warning_count" yaml:"warning_count"`
	InfoCount     int `json:"info_count" yaml:"info_count"`
}

type HiddenDependencySubtype string

type IssueSeverity string

type IssueType string

type LCOMConfigurationLoader interface {
	// LoadConfig loads configuration from the specified path
	LoadConfig(path string) (*LCOMRequest, error)

	// LoadDefaultConfig discovers configuration from targetPath (the analyzed
	// path) and falls back to built-in defaults when none is found
	LoadDefaultConfig(targetPath string) *LCOMRequest

	// MergeConfig merges CLI flags with configuration file
	MergeConfig(base *LCOMRequest, override *LCOMRequest) *LCOMRequest
}

type LCOMMetrics struct {
	// Core LCOM4 metric - number of connected components in method-variable graph
	LCOM4 int `json:"lcom4" yaml:"lcom4"`

	// Method statistics
	TotalMethods    int `json:"total_methods" yaml:"total_methods"`       // All methods in the class
	ExcludedMethods int `json:"excluded_methods" yaml:"excluded_methods"` // Methods kept out of the graph (@classmethod, @staticmethod, @abstractmethod, constructors)

	// Instance variable statistics
	InstanceVariables int `json:"instance_variables" yaml:"instance_variables"` // Distinct self.xxx variables accessed

	// Connected component details
	MethodGroups [][]string `json:"method_groups" yaml:"method_groups"` // Method names grouped by connected component
}

type LCOMOutputFormatter interface {
	// Format formats the analysis response according to the specified format
	Format(response *LCOMResponse, format OutputFormat) (string, error)

	// Write writes the formatted output to the writer
	Write(response *LCOMResponse, format OutputFormat, writer io.Writer) error
}

type LCOMRequest struct {
	// Input files or directories to analyze
	Paths []string `json:"paths" yaml:"paths"`

	// Output configuration
	OutputFormat OutputFormat `json:"output_format" yaml:"output_format"`
	OutputWriter io.Writer    `json:"-" yaml:"-"`
	OutputPath   string       `json:"output_path" yaml:"output_path"`   // Path to save output file (for HTML format)
	NoOpen       bool         `json:"no_open" yaml:"no_open"`           // Don't auto-open HTML in browser
	ShowDetails  *bool        `json:"show_details" yaml:"show_details"` // nil = unset, non-nil = explicitly set

	// Filtering and sorting
	MinLCOM int          `json:"min_lcom" yaml:"min_lcom"`
	MaxLCOM int          `json:"max_lcom" yaml:"max_lcom"` // 0 means no limit
	SortBy  SortCriteria `json:"sort_by" yaml:"sort_by"`

	// LCOM thresholds for risk assessment
	LowThreshold    int `json:"low_threshold" yaml:"low_threshold"`       // Default: 2 (LCOM4 <= 2 is low risk)
	MediumThreshold int `json:"medium_threshold" yaml:"medium_threshold"` // Default: 5 (LCOM4 3-5 is medium risk)

	// Configuration
	ConfigPath string `json:"config_path" yaml:"config_path"`

	// Analysis options
	Recursive       *bool    `json:"recursive" yaml:"recursive"`
	IncludePatterns []string `json:"include_patterns" yaml:"include_patterns"`
	ExcludePatterns []string `json:"exclude_patterns" yaml:"exclude_patterns"`
}

type LCOMResponse struct {
	// Analysis results
	Classes []ClassCohesion `json:"classes" yaml:"classes"`
	Summary LCOMSummary     `json:"summary" yaml:"summary"`

	// Warnings and issues
	Warnings []string          `json:"warnings" yaml:"warnings"`
	Errors   []string          `json:"errors" yaml:"errors"`
	Failures []AnalysisFailure `json:"failures,omitempty" yaml:"failures,omitempty"`

	// Metadata
	GeneratedAt string      `json:"generated_at" yaml:"generated_at"`
	Version     string      `json:"version" yaml:"version"`
	Config      interface{} `json:"config" yaml:"config"` // Configuration used for analysis
}

type LCOMService interface {
	// Analyze performs LCOM analysis on the given request
	Analyze(ctx context.Context, req LCOMRequest) (*LCOMResponse, error)

	// AnalyzeFile analyzes a single Python file
	AnalyzeFile(ctx context.Context, filePath string, req LCOMRequest) (*LCOMResponse, error)
}

type LCOMSummary struct {
	TotalClasses    int     `json:"total_classes" yaml:"total_classes"`
	AverageLCOM     float64 `json:"average_lcom" yaml:"average_lcom"`
	MaxLCOM         int     `json:"max_lcom" yaml:"max_lcom"`
	MinLCOM         int     `json:"min_lcom" yaml:"min_lcom"`
	ClassesAnalyzed int     `json:"classes_analyzed" yaml:"classes_analyzed"`
	FilesAnalyzed   int     `json:"files_analyzed" yaml:"files_analyzed"`

	// Risk distribution
	LowRiskClasses    int `json:"low_risk_classes" yaml:"low_risk_classes"`
	MediumRiskClasses int `json:"medium_risk_classes" yaml:"medium_risk_classes"`
	HighRiskClasses   int `json:"high_risk_classes" yaml:"high_risk_classes"`

	// LCOM distribution
	LCOMDistribution map[string]int `json:"lcom_distribution" yaml:"lcom_distribution"`

	// Least cohesive classes (top 10)
	LeastCohesiveClasses []ClassCohesion `json:"least_cohesive_classes" yaml:"least_cohesive_classes"`
}

type Layer struct {
	Name        string   `json:"name" yaml:"name"`
	Packages    []string `json:"packages" yaml:"packages"`
	Description string   `json:"description" yaml:"description"`
}

type LayerAnalysis struct {
	LayersAnalyzed    int                       `json:"layers_analyzed" yaml:"layers_analyzed"`       // Number of layers analyzed
	LayerViolations   []LayerViolation          `json:"layer_violations" yaml:"layer_violations"`     // Layer rule violations
	LayerCoupling     map[string]map[string]int `json:"layer_coupling" yaml:"layer_coupling"`         // Layer -> Layer -> dependency count
	LayerCohesion     map[string]float64        `json:"layer_cohesion" yaml:"layer_cohesion"`         // Layer -> cohesion score
	ProblematicLayers []string                  `json:"problematic_layers" yaml:"problematic_layers"` // Layers with violations
}

type LayerRule struct {
	From  string   `json:"from" yaml:"from"`
	Allow []string `json:"allow" yaml:"allow"`
	Deny  []string `json:"deny" yaml:"deny"`
	// Warn lists target layers that are permitted but discouraged: a dependency
	// on one of these emits a warning instead of an error. Used e.g. by the MVC
	// preset for view -> model direct access.
	Warn []string `json:"warn" yaml:"warn"`
}

type LayerViolation struct {
	FromModule  string            `json:"from_module" yaml:"from_module"` // Module causing violation
	ToModule    string            `json:"to_module" yaml:"to_module"`     // Target module
	FromLayer   string            `json:"from_layer" yaml:"from_layer"`   // Source layer
	ToLayer     string            `json:"to_layer" yaml:"to_layer"`       // Target layer
	Rule        string            `json:"rule" yaml:"rule"`               // Rule that was violated
	Severity    ViolationSeverity `json:"severity" yaml:"severity"`       // Severity of violation
	Description string            `json:"description" yaml:"description"` // Description of violation
	Suggestion  string            `json:"suggestion" yaml:"suggestion"`   // Suggested fix
}

type MockDataConfigurationLoader interface {
	// LoadConfig loads mock data configuration from the specified path
	LoadConfig(path string) (*MockDataRequest, error)

	// LoadDefaultConfig discovers configuration from targetPath (the analyzed
	// path) and falls back to built-in defaults when none is found
	LoadDefaultConfig(targetPath string) *MockDataRequest

	// MergeConfig merges CLI flags with configuration file
	MergeConfig(base *MockDataRequest, override *MockDataRequest) *MockDataRequest
}

type MockDataFinding struct {
	// Location information
	Location MockDataLocation `json:"location"`

	// Mock data details
	Value       string           `json:"value"` // The detected mock value
	Type        MockDataType     `json:"type"`  // Type of mock data
	Severity    MockDataSeverity `json:"severity"`
	Description string           `json:"description"` // Why this was flagged
	Rationale   string           `json:"rationale"`   // Detection rationale

	// Context information
	Context      string `json:"context,omitempty"`       // Surrounding code
	VariableName string `json:"variable_name,omitempty"` // Variable name if applicable
}

type MockDataFormatter interface {
	// Format formats the mock data analysis response according to the specified format
	Format(response *MockDataResponse, format OutputFormat) (string, error)

	// Write writes the formatted mock data output to the writer
	Write(response *MockDataResponse, format OutputFormat, writer io.Writer) error
}

type MockDataLocation struct {
	FilePath    string `json:"file_path"`
	StartLine   int    `json:"start_line"`
	EndLine     int    `json:"end_line"`
	StartColumn int    `json:"start_column"`
	EndColumn   int    `json:"end_column"`
}

type MockDataRequest struct {
	// Input files or directories to analyze
	Paths []string

	// Output configuration
	OutputFormat OutputFormat
	OutputWriter io.Writer
	OutputPath   string // Path to save output file (for HTML format)
	NoOpen       bool   // Don't auto-open HTML in browser

	// Filtering and sorting
	MinSeverity MockDataSeverity
	SortBy      MockDataSortCriteria

	// Analysis options
	Recursive       *bool // nil = unset, non-nil = explicitly set
	IncludePatterns []string
	ExcludePatterns []string
	IgnoreTests     *bool // nil = use default (true), non-nil = explicitly set

	// Configuration
	ConfigPath string

	// Mock data specific options
	Keywords       []string       // Keywords to detect (mock, fake, dummy, etc.)
	Domains        []string       // Domains to detect (example.com, etc.)
	IgnorePatterns []string       // Patterns in code to ignore
	EnabledTypes   []MockDataType // Types of mock data to detect (empty = all)
}

type MockDataResponse struct {
	// Analysis results
	Files   []FileMockData  `json:"files"`
	Summary MockDataSummary `json:"summary"`

	// Warnings and issues
	Warnings []string `json:"warnings"`
	Errors   []string `json:"errors"`
	// Diagnostics contains typed file read and parse failures.
	Diagnostics []AnalysisDiagnostic `json:"diagnostics,omitempty"`
	// Failures contains detector execution failures.
	Failures []AnalysisFailure `json:"failures,omitempty"`

	// Metadata
	GeneratedAt string      `json:"generated_at"`
	Version     string      `json:"version"`
	Config      interface{} `json:"config"` // Configuration used for analysis
}

type MockDataService interface {
	// Analyze performs mock data analysis on the given request
	Analyze(ctx context.Context, req MockDataRequest) (*MockDataResponse, error)

	// AnalyzeFile analyzes a single Python file for mock data
	AnalyzeFile(ctx context.Context, filePath string, req MockDataRequest) (*FileMockData, error)
}

type MockDataSeverity string

type MockDataSortCriteria string

type MockDataSummary struct {
	// Overall metrics
	TotalFiles        int `json:"total_files"`
	TotalFindings     int `json:"total_findings"`
	FilesWithMockData int `json:"files_with_mock_data"`

	// Severity distribution
	ErrorFindings   int `json:"error_findings"`
	WarningFindings int `json:"warning_findings"`
	InfoFindings    int `json:"info_findings"`

	// Type distribution
	FindingsByType map[MockDataType]int `json:"findings_by_type"`
}

type MockDataType string

type ModuleComplexityMetrics struct {
	AnalyzedFunctionCount      int     `json:"analyzed_function_count" yaml:"analyzed_function_count"`
	AverageComplexity          float64 `json:"average_complexity" yaml:"average_complexity"`
	AverageCognitiveComplexity float64 `json:"average_cognitive_complexity" yaml:"average_cognitive_complexity"`
	MaxComplexity              int     `json:"max_complexity" yaml:"max_complexity"`
	HighRiskFunctionCount      int     `json:"high_risk_function_count" yaml:"high_risk_function_count"`
	ExceptionHandlerCount      int     `json:"exception_handler_count" yaml:"exception_handler_count"`
}

type ModuleDeadCodeMetrics struct {
	DeadCodeFindingCount int `json:"dead_code_finding_count" yaml:"dead_code_finding_count"`
	DeadCodeBlockCount   int `json:"dead_code_block_count" yaml:"dead_code_block_count"`
}

type ModuleDependencyMetrics struct {
	// Basic information
	ModuleName string `json:"module_name" yaml:"module_name"` // Module name
	Package    string `json:"package" yaml:"package"`         // Package name
	FilePath   string `json:"file_path" yaml:"file_path"`     // File path
	IsPackage  bool   `json:"is_package" yaml:"is_package"`   // True if this is a package

	// Size metrics
	LinesOfCode        int      `json:"lines_of_code" yaml:"lines_of_code"`               // Total lines of code
	FunctionCount      int      `json:"function_count" yaml:"function_count"`             // Number of functions
	ClassCount         int      `json:"class_count" yaml:"class_count"`                   // Number of classes
	AbstractClassCount int      `json:"abstract_class_count" yaml:"abstract_class_count"` // Number of abstract classes
	PublicInterface    []string `json:"public_interface" yaml:"public_interface"`         // Public names exported

	// Coupling metrics (Robert Martin's metrics)
	AfferentCoupling int     `json:"afferent_coupling" yaml:"afferent_coupling"` // Ca - modules that depend on this one
	EfferentCoupling int     `json:"efferent_coupling" yaml:"efferent_coupling"` // Ce - modules this one depends on
	Instability      float64 `json:"instability" yaml:"instability"`             // I = Ce / (Ca + Ce)
	Abstractness     float64 `json:"abstractness" yaml:"abstractness"`           // A - abstractness measure
	Distance         float64 `json:"distance" yaml:"distance"`                   // D - distance from main sequence

	// Quality metrics
	Maintainability float64   `json:"maintainability" yaml:"maintainability"` // Maintainability index (0-100)
	TechnicalDebt   float64   `json:"technical_debt" yaml:"technical_debt"`   // Estimated technical debt in hours
	RiskLevel       RiskLevel `json:"risk_level" yaml:"risk_level"`           // Overall risk assessment

	// Dependencies
	DirectDependencies     []string `json:"direct_dependencies" yaml:"direct_dependencies"`         // Modules this directly depends on
	TransitiveDependencies []string `json:"transitive_dependencies" yaml:"transitive_dependencies"` // All transitive dependencies
	Dependents             []string `json:"dependents" yaml:"dependents"`                           // Modules that depend on this one
}

type ModuleGraphOptions struct {
	IncludeStdLib     bool
	IncludeThirdParty bool
	FollowRelative    bool
}

type ModuleQualityMetrics struct {
	ModuleName              string `json:"module_name,omitempty" yaml:"module_name,omitempty"`
	FilePath                string `json:"file_path" yaml:"file_path"`
	LinesOfCode             int    `json:"lines_of_code" yaml:"lines_of_code"`
	FunctionCount           int    `json:"function_count" yaml:"function_count"`
	ModuleComplexityMetrics `yaml:",inline"`
	ModuleDeadCodeMetrics   `yaml:",inline"`
}

type OutputFormat string

type OutputFormatter interface {
	// Format formats the analysis response according to the specified format
	Format(response *ComplexityResponse, format OutputFormat) (string, error)

	// Write writes the formatted output to the writer
	Write(response *ComplexityResponse, format OutputFormat, writer io.Writer) error
}

type PackageRule struct {
	Package             string   `json:"package" yaml:"package"`
	MaxSize             int      `json:"max_size" yaml:"max_size"`
	MaxCoupling         int      `json:"max_coupling" yaml:"max_coupling"`
	MinCohesion         float64  `json:"min_cohesion" yaml:"min_cohesion"`
	AllowedDependencies []string `json:"allowed_dependencies" yaml:"allowed_dependencies"`
}

type ParallelExecutor interface {
	// Execute runs tasks in parallel with the given configuration
	Execute(ctx context.Context, tasks []ExecutableTask) error

	// SetMaxConcurrency sets the maximum number of concurrent tasks
	SetMaxConcurrency(max int)

	// SetTimeout sets the timeout for all tasks
	SetTimeout(timeout time.Duration)
}

type ProgressManager interface {
	// Initialize sets up progress tracking with the maximum value
	Initialize(maxValue int)

	// Start starts the progress bar
	Start()

	// Complete marks the progress as completed
	Complete(success bool)

	// Update updates the progress
	Update(processed, total int)

	// SetWriter sets the output writer for progress bars
	SetWriter(writer io.Writer)

	// IsInteractive returns true if progress bars should be shown
	IsInteractive() bool

	// Close cleans up any resources
	Close()
}

type PythonFileSelection struct {
	IncludePatterns []string
	ExcludePatterns []string
}

type RawMetrics struct {
	FilePath       string  `json:"file_path" yaml:"file_path"`
	SLOC           int     `json:"sloc" yaml:"sloc"`
	LLOC           int     `json:"lloc" yaml:"lloc"`
	CommentLines   int     `json:"comment_lines" yaml:"comment_lines"`
	DocstringLines int     `json:"docstring_lines" yaml:"docstring_lines"`
	BlankLines     int     `json:"blank_lines" yaml:"blank_lines"`
	TotalLines     int     `json:"total_lines" yaml:"total_lines"`
	CommentRatio   float64 `json:"comment_ratio" yaml:"comment_ratio"`
}

type RawMetricsSummary struct {
	FilesAnalyzed  int     `json:"files_analyzed" yaml:"files_analyzed"`
	SLOC           int     `json:"sloc" yaml:"sloc"`
	LLOC           int     `json:"lloc" yaml:"lloc"`
	CommentLines   int     `json:"comment_lines" yaml:"comment_lines"`
	DocstringLines int     `json:"docstring_lines" yaml:"docstring_lines"`
	BlankLines     int     `json:"blank_lines" yaml:"blank_lines"`
	TotalLines     int     `json:"total_lines" yaml:"total_lines"`
	CommentRatio   float64 `json:"comment_ratio" yaml:"comment_ratio"`
}

type RecommendationCategory string

type RecommendationPriority string

type RecommendationType string

type ReportWriter interface {
	// Write writes formatted content using the provided writeFunc.
	// - If outputPath is non-empty, implementations should create/truncate the file
	//   at that path and pass the file as the writer to writeFunc.
	// - If outputPath is empty, implementations should pass the provided writer to writeFunc.
	// Implementations may emit user-facing status messages (e.g., file paths) and
	// optionally open HTML outputs in a browser when format is OutputFormatHTML and noOpen is false.
	Write(writer io.Writer, outputPath string, format OutputFormat, noOpen bool, writeFunc func(io.Writer) error) error
}

type ResponsibilityAnalysis struct {
	SRPViolations          []SRPViolation      `json:"srp_violations" yaml:"srp_violations"`                   // SRP violations detected
	ModuleResponsibilities map[string][]string `json:"module_responsibilities" yaml:"module_responsibilities"` // Module -> responsibilities
	OverloadedModules      []string            `json:"overloaded_modules" yaml:"overloaded_modules"`           // Modules with too many responsibilities
}

type RiskLevel string

type SRPViolation struct {
	Module           string            `json:"module" yaml:"module"`                     // Module with violation
	Responsibilities []string          `json:"responsibilities" yaml:"responsibilities"` // Multiple responsibilities detected
	Severity         ViolationSeverity `json:"severity" yaml:"severity"`                 // Severity level
	Suggestion       string            `json:"suggestion" yaml:"suggestion"`             // Refactoring suggestion
}

type SortCriteria string

type SourceLocation struct {
	FilePath  string `json:"file_path" yaml:"file_path"`
	StartLine int    `json:"start_line" yaml:"start_line"`
	EndLine   int    `json:"end_line" yaml:"end_line"`
	StartCol  int    `json:"start_col" yaml:"start_col"`
	EndCol    int    `json:"end_col" yaml:"end_col"`
}

type Suggestion struct {
	Category    SuggestionCategory `json:"category"`
	Severity    SuggestionSeverity `json:"severity"`
	Effort      SuggestionEffort   `json:"effort"`
	Title       string             `json:"title"`
	Description string             `json:"description"`
	Steps       []string           `json:"steps,omitempty"`
	FilePath    string             `json:"file_path,omitempty"`
	Function    string             `json:"function,omitempty"`
	ClassName   string             `json:"class_name,omitempty"`
	StartLine   int                `json:"start_line,omitempty"`
	MetricValue string             `json:"metric_value,omitempty"`
	Threshold   string             `json:"threshold,omitempty"`
}

type SuggestionCategory string

type SuggestionEffort string

type SuggestionSeverity string

type SystemAnalysisConfigurationLoader interface {
	// LoadConfig loads configuration from the specified path
	LoadConfig(path string) (*SystemAnalysisRequest, error)

	// LoadDefaultConfig discovers configuration from targetPath (the analyzed
	// path) and falls back to built-in defaults when none is found
	LoadDefaultConfig(targetPath string) *SystemAnalysisRequest

	// MergeConfig merges CLI flags with configuration file
	MergeConfig(base *SystemAnalysisRequest, override *SystemAnalysisRequest) *SystemAnalysisRequest
}

type SystemAnalysisOutputFormatter interface {
	// Format formats the analysis response according to the specified format
	Format(response *SystemAnalysisResponse, format OutputFormat) (string, error)

	// Write writes the formatted output to the writer
	Write(response *SystemAnalysisResponse, format OutputFormat, writer io.Writer) error
}

type SystemAnalysisRequest struct {
	// Input files or directories to analyze
	Paths []string

	// ProjectRoot overrides automatic project-root inference when set.
	ProjectRoot string

	// Output configuration
	OutputFormat OutputFormat
	OutputWriter io.Writer
	OutputPath   string // Path to save output file
	NoOpen       bool   // Don't auto-open HTML in browser

	// Analysis scope
	AnalyzeDependencies *bool // Enable dependency analysis
	AnalyzeArchitecture *bool // Enable architecture validation

	// Configuration
	ConfigPath      string
	Recursive       *bool
	IncludePatterns []string
	ExcludePatterns []string

	// Analysis options
	IncludeStdLib                   *bool             // Include standard library dependencies
	IncludeThirdParty               *bool             // Include third-party dependencies
	FollowRelative                  *bool             // Follow relative imports
	DetectCycles                    *bool             // Detect circular dependencies
	ValidateArchitecture            *bool             // Validate architecture rules
	ValidateCohesion                *bool             // Validate package cohesion
	ValidateResponsibility          *bool             // Validate single responsibility boundaries
	MinCohesion                     float64           // Minimum acceptable package cohesion
	MaxResponsibilities             int               // Maximum inferred responsibilities per module
	CohesionViolationSeverity       ViolationSeverity // Severity for package cohesion violations
	ResponsibilityViolationSeverity ViolationSeverity // Severity for SRP violations

	// Architecture rules (loaded from config or specified directly)
	ArchitectureRules *ArchitectureRules

	// Integration with other analyses
	ComplexityData map[string]int     // Module -> average complexity
	ClonesData     map[string]float64 // Module -> duplication ratio
	DeadCodeData   map[string]int     // Module -> dead code lines
}

type SystemAnalysisResponse struct {
	// Core analysis results
	DependencyAnalysis   *DependencyAnalysisResult   `json:"dependency_analysis" yaml:"dependency_analysis"`     // Module dependency analysis
	ArchitectureAnalysis *ArchitectureAnalysisResult `json:"architecture_analysis" yaml:"architecture_analysis"` // Architecture validation results

	// Summary information
	Summary SystemAnalysisSummary `json:"summary" yaml:"summary"` // High-level summary

	// Issues and recommendations
	Issues          []SystemIssue          `json:"issues" yaml:"issues"`                   // Critical issues found
	Recommendations []SystemRecommendation `json:"recommendations" yaml:"recommendations"` // Improvement recommendations
	Warnings        []string               `json:"warnings" yaml:"warnings"`               // Analysis warnings
	Errors          []string               `json:"errors" yaml:"errors"`                   // Analysis errors
	Failures        []AnalysisFailure      `json:"failures,omitempty" yaml:"failures,omitempty"`

	// Metadata
	GeneratedAt time.Time   `json:"generated_at" yaml:"generated_at"` // When the analysis was generated
	Duration    int64       `json:"duration" yaml:"duration"`         // Analysis duration in milliseconds
	Version     string      `json:"version" yaml:"version"`           // Tool version
	Config      interface{} `json:"config" yaml:"config"`             // Configuration used for analysis
}

type SystemAnalysisService interface {
	// Analyze performs comprehensive system analysis
	Analyze(ctx context.Context, req SystemAnalysisRequest) (*SystemAnalysisResponse, error)

	// AnalyzeDependencies performs dependency analysis only
	AnalyzeDependencies(ctx context.Context, req SystemAnalysisRequest) (*DependencyAnalysisResult, error)

	// AnalyzeArchitecture performs architecture validation only
	AnalyzeArchitecture(ctx context.Context, req SystemAnalysisRequest) (*ArchitectureAnalysisResult, error)
}

type SystemAnalysisSummary struct {
	// System overview
	TotalModules      int    `json:"total_modules" yaml:"total_modules"`           // Total number of modules analyzed
	TotalPackages     int    `json:"total_packages" yaml:"total_packages"`         // Total number of packages
	TotalDependencies int    `json:"total_dependencies" yaml:"total_dependencies"` // Total dependency relationships
	ProjectRoot       string `json:"project_root" yaml:"project_root"`             // Project root directory
	ResolvedImports   int    `json:"resolved_imports" yaml:"resolved_imports"`     // Internal imports resolved to analyzed modules
	UnresolvedImports int    `json:"unresolved_imports" yaml:"unresolved_imports"` // Internal imports that could not be resolved

	// Quality scores (0-100, higher is better)
	OverallQualityScore  float64 `json:"overall_quality_score" yaml:"overall_quality_score"` // Composite quality score
	MaintainabilityScore float64 `json:"maintainability_score" yaml:"maintainability_score"` // Average maintainability index
	ArchitectureScore    float64 `json:"architecture_score" yaml:"architecture_score"`       // Architecture compliance score
	ModularityScore      float64 `json:"modularity_score" yaml:"modularity_score"`           // System modularity score
	TechnicalDebtHours   float64 `json:"technical_debt_hours" yaml:"technical_debt_hours"`   // Total estimated technical debt

	// Key metrics
	AverageCoupling        float64 `json:"average_coupling" yaml:"average_coupling"`               // Average module coupling
	AverageInstability     float64 `json:"average_instability" yaml:"average_instability"`         // Average instability
	CyclicDependencies     int     `json:"cyclic_dependencies" yaml:"cyclic_dependencies"`         // Number of modules in cycles
	ArchitectureViolations int     `json:"architecture_violations" yaml:"architecture_violations"` // Number of architecture rule violations
	HighRiskModules        int     `json:"high_risk_modules" yaml:"high_risk_modules"`             // Number of high-risk modules

	// Recommendations summary
	CriticalIssues           int `json:"critical_issues" yaml:"critical_issues"`                     // Number of critical issues requiring immediate attention
	RefactoringCandidates    int `json:"refactoring_candidates" yaml:"refactoring_candidates"`       // Number of modules needing refactoring
	ArchitectureImprovements int `json:"architecture_improvements" yaml:"architecture_improvements"` // Number of architecture improvements suggested
}

type SystemIssue struct {
	Type        IssueType     `json:"type" yaml:"type"`               // Type of issue
	Severity    IssueSeverity `json:"severity" yaml:"severity"`       // Severity level
	Title       string        `json:"title" yaml:"title"`             // Issue title
	Description string        `json:"description" yaml:"description"` // Detailed description
	Impact      string        `json:"impact" yaml:"impact"`           // Impact description
	Modules     []string      `json:"modules" yaml:"modules"`         // Affected modules
	Suggestion  string        `json:"suggestion" yaml:"suggestion"`   // Remediation suggestion
}

type SystemRecommendation struct {
	Category    RecommendationCategory `json:"category" yaml:"category"`       // Category of recommendation
	Priority    RecommendationPriority `json:"priority" yaml:"priority"`       // Priority level
	Title       string                 `json:"title" yaml:"title"`             // Recommendation title
	Description string                 `json:"description" yaml:"description"` // Detailed description
	Rationale   string                 `json:"rationale" yaml:"rationale"`     // Why this is recommended
	Benefits    []string               `json:"benefits" yaml:"benefits"`       // Expected benefits
	Steps       []string               `json:"steps" yaml:"steps"`             // Implementation steps
	Resources   []string               `json:"resources" yaml:"resources"`     // Additional resources
	Effort      EstimatedEffort        `json:"effort" yaml:"effort"`           // Estimated effort
}

type ViolationSeverity string

type ViolationType string