inspector

type Config struct {
	ExcludedDirs    map[string]struct{}
	ExcludePatterns []string
	SupportedOnly   bool
	// AnalyzerWorkers controls per-directory file analysis workers.
	// 0 uses automatic sizing, 1 forces sequential file analysis.
	AnalyzerWorkers int
	// GitChurn enables per-file commit-frequency and hotspot scoring.
	GitChurn bool
}

type DependencyReport struct {
	Nodes            int
	Edges            int
	ExternalImports  int
	MostDependedOn   []DependencyStat // highest fan-in: change here ripples widely
	MostDependencies []DependencyStat // highest fan-out: most fragile
	Cycles           [][]string
}

type DependencyStat struct {
	Node   string
	FanIn  int
	FanOut int
}

type DuplicateBlock struct {
	Tokens     int
	Lines      int
	FirstPath  string
	FirstStart int
	FirstEnd   int
	OtherPath  string
	OtherStart int
	OtherEnd   int
}

type DuplicationReport struct {
	MinTokens       int
	Blocks          []DuplicateBlock
	TotalBlocks     int
	DuplicatedLines int
}

type FileHotspot struct {
	Path            string
	Language        string
	Cyclomatic      int
	Churn           int
	Hotspot         float64
	LineCount       int
	Maintainability float64
}

type FileMetrics struct {
	Language      string
	LineCount     int // physical line count
	CodeLines     int
	CommentLines  int
	BlankLines    int
	ImportCount   int
	VariableCount int
	// TodoCount counts TODO/FIXME/HACK/XXX markers found in comments.
	TodoCount int
	// Cyclomatic is the sum of every function's cyclomatic complexity.
	Cyclomatic int
	// MaxComplexity is the highest single-function cyclomatic complexity.
	MaxComplexity int
	// Halstead holds the file-level Halstead measures.
	Halstead Halstead
	// Maintainability is a 0-100 Maintainability Index for the file.
	Maintainability float64
	// Imports holds the raw import specifiers found in the file, used to build
	// the dependency graph.
	Imports   []string `json:",omitempty"`
	Functions []FunctionInfo
}

type FunctionHotspot struct {
	Path       string
	Name       string
	Line       int
	Cyclomatic int
	Cognitive  int
	LineCount  int
}

type FunctionInfo struct {
	Name      string
	Signature string
	Line      int
	LineCount int

	// Cyclomatic is the McCabe cyclomatic complexity: decision points + 1.
	Cyclomatic int
	// Cognitive is an approximation of SonarSource cognitive complexity; it
	// penalizes nesting and is a better "how hard to understand" proxy.
	Cognitive int
	// MaxNesting is the deepest control-flow nesting level inside the function.
	MaxNesting int
	// Params is the number of declared parameters.
	Params int
	// Maintainability is a 0-100 Maintainability Index for the function
	// (higher is better).
	Maintainability float64
}

type Halstead struct {
	Vocabulary int     // distinct operators + distinct operands
	Length     int     // total operators + total operands
	Volume     float64 // Length * log2(Vocabulary)
	Difficulty float64 // (distinctOperators/2) * (totalOperands/distinctOperands)
	Effort     float64 // Difficulty * Volume
}

type LanguageAnalyzer interface {
	Analyze(source []byte) (*FileMetrics, error)
}

type LanguageConfig struct {
	Name       string           // canonical language name, e.g. "rust"
	Extensions []string         // file extensions including the dot, e.g. []string{".rs"}
	Grammar    *sitter.Language // required tree-sitter grammar
	Hints      *LanguageHints   // optional; augments the heuristic defaults
}

type LanguageHints struct {
	FunctionKinds []string // node kinds that define a function/method
	DecisionKinds []string // node kinds counting +1 cyclomatic
	NestingKinds  []string // node kinds that increase nesting (cognitive/depth)
	ImportKinds   []string // node kinds that are imports (counted)
	NameField     string   // field name for a definition's name (default "name")
	ParamsField   string   // field name for the parameter list (default "parameters")
}

type Options struct {
	// Excludes are file or directory names/glob patterns to skip.
	Excludes []string
	// NoDefaultExcludes disables the built-in excludes (.git, node_modules, ...).
	NoDefaultExcludes bool
	// SupportedOnly prunes unsupported files from the tree.
	SupportedOnly bool
	// Workers controls per-directory analysis workers: 0 = auto, 1 = sequential.
	Workers int
	// TopN caps each ranked list (0 = 10).
	TopN int
	// DupMinTokens is the clone window size (0 = DefaultDuplicationMinTokens).
	DupMinTokens int
	// NoGit disables git churn and hotspot scoring.
	NoGit bool
	// NoDup disables duplicate-code detection.
	NoDup bool
	// NoDeps disables the import dependency graph.
	NoDeps bool
}

type Report struct {
	Root         *TreeNode
	Summary      Summary
	Duplication  *DuplicationReport `json:",omitempty"`
	Dependencies *DependencyReport  `json:",omitempty"`
}

type Summary struct {
	Files              int
	SupportedFiles     int
	TotalLines         int
	TotalCode          int
	TotalComment       int
	TotalBlank         int
	TotalFunctions     int
	TotalTodos         int
	GitChurn           bool
	TopHotspots        []FileHotspot
	MostComplex        []FunctionHotspot
	Longest            []FunctionHotspot
	LowestMaintainable []FileHotspot
}

type TreeNode struct {
	Name     string
	Path     string
	RelPath  string `json:",omitempty"` // path relative to the scan root
	IsDir    bool
	Metrics  *FileMetrics `json:",omitempty"`
	Children []*TreeNode  `json:",omitempty"`
	Warning  string       `json:",omitempty"`

	// Churn is the number of git commits that touched this file.
	Churn int `json:",omitempty"`
	// Hotspot is the refactoring-priority score: complexity * churn.
	Hotspot float64 `json:",omitempty"`
}