compare

type APIDelta struct {
	Name string
	Kind string
	SigA string
	SigB string
}

type APIDiff struct {
	Common     int
	OnlyACount int
	OnlyBCount int
	ChangedSig int
	OnlyA      []APISymbol
	OnlyB      []APISymbol
	Changed    []APIDelta
}

type APISymbol struct {
	Name      string
	Kind      string
	Signature string
	Package   string
	File      string
}

type ArchMetrics struct {
	PackageCount      int           `json:"packageCount"`
	CommunityCount    int           `json:"communityCount"`
	CrossPkgCallRatio float64       `json:"crossPkgCallRatio"`
	MaxCallDepth      int           `json:"maxCallDepth"`
	InterfaceRatio    float64       `json:"interfaceRatio"`
	GodPackages       []GodPackage  `json:"godPackages,omitempty"`
	CircularDeps      []CircularDep `json:"circularDeps,omitempty"`
	// NotIndexed is set when the code graph has no packages for this repo,
	// meaning code_graph tool was never called with this repo path. Call
	// code_graph with the same repo first to populate the graph.
	NotIndexed bool `json:"notIndexed,omitempty"`
	// Approximate is set when metrics were derived from an in-memory call graph
	// rather than the full Apache AGE graph. MaxCallDepth, InterfaceRatio, and
	// CommunityCount are not computed in the approximate path and must not be
	// presented as real measurements.
	Approximate bool   `json:"approximate,omitempty"`
	Hint        string `json:"hint,omitempty"`
}

type ArchitectureInsight struct {
	Insight string `json:"insight"`
	Source  string `json:"source"`
	Example string `json:"example,omitempty"`
	Benefit string `json:"benefit"`
}

type ChurnStats struct {
	// Commits is the number of commits that touched this file.
	Commits int `json:"commits"`

	// Additions is the total lines added across all commits.
	Additions int `json:"additions"`

	// Deletions is the total lines deleted across all commits.
	Deletions int `json:"deletions"`
}

type CircularDep struct {
	PackageA string `json:"packageA"`
	PackageB string `json:"packageB"`
}

type CompareInput struct {
	RootA       string
	RootB       string
	Query       string
	Opts        SnapshotOpts
	OxCodes     *oxcodes.Client
	EmbedClient *embed.Client    // nil = skip semantic matching
	GraphStore  *codegraph.Store // nil = skip architecture graph analysis
}

type CompareResult struct {
	RepoA           string             `json:"repo_a"`
	RepoB           string             `json:"repo_b"`
	Query           string             `json:"query"`
	MetricsA        RepoMetrics        `json:"metrics_a"`
	MetricsB        RepoMetrics        `json:"metrics_b"`
	Analysis        LLMAnalysis        `json:"analysis"`
	MatchedSymbols  int                `json:"matched_symbols"`
	UnmatchedA      int                `json:"unmatched_a"`
	UnmatchedB      int                `json:"unmatched_b"`
	MatchBreakdown  MatchBreakdown     `json:"match_breakdown"`
	ImportDiff      ImportDiff         `json:"import_diff"`
	DiffStats       *DiffStats         `json:"diff_stats,omitempty"`
	HotspotsA       []HotspotFile      `json:"hotspots_a,omitempty"`
	HotspotsB       []HotspotFile      `json:"hotspots_b,omitempty"`
	RelStatsA       *RelStats          `json:"rel_stats_a,omitempty"`
	RelStatsB       *RelStats          `json:"rel_stats_b,omitempty"`
	QualityA        *QualityIndicators `json:"quality_a,omitempty"`
	QualityB        *QualityIndicators `json:"quality_b,omitempty"`
	FreshnessA      *FreshnessStats    `json:"freshness_a,omitempty"`
	FreshnessB      *FreshnessStats    `json:"freshness_b,omitempty"`
	DataflowA       *DataflowStats     `json:"dataflow_a,omitempty"`
	DataflowB       *DataflowStats     `json:"dataflow_b,omitempty"`
	APIDiffResult   *APIDiff           `json:"api_diff,omitempty"`
	RouteDiffResult *RouteDiff         `json:"route_diff,omitempty"`
	CouplingA       []CoupledPair      `json:"coupling_a,omitempty"`
	CouplingB       []CoupledPair      `json:"coupling_b,omitempty"`
	ArchMetricsA    *ArchMetrics       `json:"arch_metrics_a,omitempty"`
	ArchMetricsB    *ArchMetrics       `json:"arch_metrics_b,omitempty"`
	CrossLangReport *CrossLangReport   `json:"cross_lang_report,omitempty"`
}

type CoupledPair struct {
	FileA     string  `json:"fileA"`
	FileB     string  `json:"fileB"`
	CoChanges int     `json:"coChanges"`
	Ratio     float64 `json:"ratio"` // coChanges / max(changesA, changesB)
}

type CoverageGap struct {
	MissingIn  string `json:"missingIn"`
	Feature    string `json:"feature"`
	LocationB  string `json:"locationB,omitempty"`
	Importance string `json:"importance"`
}

type CrossLangMatch struct {
	NameA      string  `json:"nameA"`
	NameB      string  `json:"nameB"`
	FileA      string  `json:"fileA"`
	FileB      string  `json:"fileB"`
	Similarity float64 `json:"similarity"`
}

type CrossLangReport struct {
	LanguageA       string           `json:"languageA"`
	LanguageB       string           `json:"languageB"`
	SemanticMatches int              `json:"semanticMatches"`
	TopMatches      []CrossLangMatch `json:"topMatches,omitempty"`
}

type DataflowStats struct {
	DeadStores    int `json:"deadStores"`
	UnusedVars    int `json:"unusedVars"`
	TotalFindings int `json:"totalFindings"`
	FilesAnalyzed int `json:"filesAnalyzed"`
}

type DiffStats struct {
	ModifiedWithDiff int `json:"modifiedWithDiff"`
	TotalInserts     int `json:"totalInserts"`
	TotalDeletes     int `json:"totalDeletes"`
	TotalUpdates     int `json:"totalUpdates"`
	TotalMoves       int `json:"totalMoves"`
}

type DiffSummary struct {
	// TotalChanges is the total number of edit actions in the diff script.
	TotalChanges int `json:"totalChanges"`

	// Inserts is the count of insert (single node) and insert-tree actions.
	Inserts int `json:"inserts"`

	// Deletes is the count of delete (single node) and delete-tree actions.
	Deletes int `json:"deletes"`

	// Updates is the count of update (value change) actions.
	Updates int `json:"updates"`

	// Moves is the count of move (reorder) actions.
	Moves int `json:"moves"`

	// Changes is a list of human-readable change descriptions (max maxDiffChanges).
	Changes []string `json:"changes,omitempty"`
}

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

type FreshnessStats struct {
	DepFreshnessRatio float64 `json:"depFreshnessRatio"`
	VulnSecurityRatio float64 `json:"vulnSecurityRatio"`
	TotalDeps         int     `json:"totalDeps"`
	OutdatedDeps      int     `json:"outdatedDeps"`
	VulnDeps          int     `json:"vulnDeps"`
}

type GodPackage struct {
	Name      string `json:"name"`
	Importers int    `json:"importers"`
}

type HotspotFile struct {
	File       string  `json:"file"`
	Score      float64 `json:"score"`
	Churn      int     `json:"churn"`
	Complexity float64 `json:"complexity"`
	Risk       string  `json:"risk"` // "critical", "high", "moderate"
}

type ImportCategory string

type ImportDiff struct {
	CommonCount int      `json:"commonCount"`
	OnlyACount  int      `json:"onlyACount"`
	OnlyBCount  int      `json:"onlyBCount"`
	OnlyA       []string `json:"onlyA,omitempty"`
	OnlyB       []string `json:"onlyB,omitempty"`
	FrameworksA []string `json:"frameworksA,omitempty"`
	FrameworksB []string `json:"frameworksB,omitempty"`
	StdlibA     int      `json:"stdlibA"`
	StdlibB     int      `json:"stdlibB"`
	ExternalA   int      `json:"externalA"`
	ExternalB   int      `json:"externalB"`
}

type LLMAnalysis struct {
	Quality         []QualityAspect       `json:"quality"`
	Gaps            []CoverageGap         `json:"gaps"`
	Architecture    []ArchitectureInsight `json:"architecture"`
	Recommendations []string              `json:"recommendations"`
	Verdict         VerdictResult         `json:"verdict"`
}

type LLMClassifier interface {
	ClassifySymbols(a, b []*parser.Symbol) ([]SymbolMatch, error)
}

type MagicNumberEntry struct {
	Name     string
	File     string
	Line     int
	Count    int
	Language string
}

type MatchBreakdown struct {
	Exact    int `json:"exact"`
	Modified int `json:"modified"`
	Fuzzy    int `json:"fuzzy"`
	Renamed  int `json:"renamed"`
	Semantic int `json:"semantic"`
	Moved    int `json:"moved"`
}

type MatchType string

type OutlierFunc struct {
	Name  string
	File  string
	Line  int
	Value int
}

type Outliers struct {
	MaxCyclomatic   OutlierFunc
	MaxCognitive    OutlierFunc
	MaxFuncLines    OutlierFunc
	MaxNesting      OutlierFunc
	MaxMagicNumbers OutlierFunc
}

type QualityAspect struct {
	Aspect   string `json:"aspect"`
	Winner   string `json:"winner"`
	Reason   string `json:"reason"`
	SnippetA string `json:"snippetA,omitempty"`
	SnippetB string `json:"snippetB,omitempty"`
}

type QualityIndicators struct {
	TodoCount     int `json:"todo_count"`
	ErrorPatterns int `json:"error_patterns"` // unhandled errors
	PanicCount    int `json:"panic_count"`    // panic() calls
	MagicNumbers  int `json:"magic_numbers"`
}

type Recommendation struct {
	Priority  int
	Potential int // estimated score points recoverable
	Area      string
	Message   string
}

type RelStats struct {
	Total          int `json:"total"`
	Extends        int `json:"extends"`
	Implements     int `json:"implements"`
	Embeds         int `json:"embeds"`
	UniqueSubjects int `json:"uniqueSubjects"`
}

type RepoMetrics struct {
	Files              int     `json:"files"`
	TotalLines         int     `json:"totalLines"`
	AvgFuncLines       float64 `json:"avgFuncLines"`
	MaxFuncLines       int     `json:"maxFuncLines"`
	AvgComplexity      float64 `json:"avgComplexity"`
	MaxComplexity      int     `json:"maxComplexity"`
	TestRatio          float64 `json:"testRatio"`
	DocRatio           float64 `json:"docRatio"`
	ErrorHandlingRatio float64 `json:"errorHandlingRatio"`
	Interfaces         int     `json:"interfaces"`
	ExternalDeps       int     `json:"externalDeps"`
	Grade              string  `json:"grade"`

	// New metrics for smarter scoring.
	AvgCognitiveComplexity float64 `json:"avgCognitiveComplexity"`
	MaxCognitiveComplexity int     `json:"maxCognitiveComplexity"`
	AvgNestingDepth        float64 `json:"avgNestingDepth"`
	MaxNestingDepth        int     `json:"maxNestingDepth"`
	LargeFileRatio         float64 `json:"largeFileRatio"`
	DuplicationRatio       float64 `json:"duplicationRatio"`
	MagicNumberRatio       float64 `json:"magicNumberRatio"`
	AvgParamCount          float64 `json:"avgParamCount"`
	MaxParamCount          int     `json:"maxParamCount"`
	Score                  float64 `json:"score"`
	SemanticDupRatio       float64 `json:"semanticDupRatio,omitempty"`  // fraction of functions in semantic dup groups
	DepFreshnessRatio      float64 `json:"depFreshnessRatio,omitempty"` // fraction of deps that are up-to-date
	VulnSecurityRatio      float64 `json:"vulnSecurityRatio,omitempty"` // fraction of deps with no known vulns
	TotalDeps              int     `json:"totalDeps,omitempty"`         // number of external dependencies scanned; 0 means no manifests found (N/A)
	// DepsScanned is true when a dependency freshness scan was attempted (regardless of
	// whether it found any deps). When false, the dep-freshness and vulnerability
	// sub-scores fall back to the legacy penalty path (same behaviour as before PR #250),
	// so lightweight paths like explore that skip the freshness scan are not affected.
	DepsScanned bool `json:"depsScanned,omitempty"`
	// DeadCodeCandidates is the count of functions with CE dead-code probability >= 0.25.
	// Populated from code_dead_code_scores when code_graph snapshot is available.
	DeadCodeCandidates int      `json:"deadCodeCandidates,omitempty"`
	DeadCodeTopNames   []string `json:"deadCodeTopNames,omitempty"` // up to 3 top candidates
}

type RepoSnapshot struct {
	// Name is the repository name or slug.
	Name string `json:"name"`

	// Root is the absolute local path to the repository.
	Root string `json:"root"`

	// FocusMode is "content" when the fallback content filter was used
	// instead of path-based focus. Empty means path-based or no focus.
	FocusMode string `json:"focusMode,omitempty"`

	// Language is the dominant programming language.
	Language string `json:"language"`

	// Symbols is all symbols extracted from the repository.
	Symbols []*parser.Symbol `json:"symbols,omitempty"`

	// Imports is the flat list of all unique import paths used.
	Imports []string `json:"imports,omitempty"`

	// Files holds per-file metadata.
	Files []SnapshotFile `json:"files,omitempty"`

	// FileCount is the total number of source files.
	FileCount int `json:"fileCount"`

	// TotalLines is the approximate total lines of code.
	TotalLines int `json:"totalLines"`

	// Rels holds type relationships extracted from the repository.
	Rels []parser.TypeRelationship `json:"rels,omitempty"`

	// Partial is true when one or more ingested files could not be read during
	// snapshotting (e.g. the source tree was deleted out from under the walk, or
	// a per-file context cancellation cut the parse short). When set, the derived
	// metrics (Files, TotalLines, TestRatio, Symbols) under-count the real repo
	// and MUST NOT be presented as a complete result. See DroppedReadError /
	// DroppedCtxCancel for the per-reason breakdown.
	Partial bool `json:"partial,omitempty"`

	// DroppedReadError counts files that were enumerated by ingest but failed
	// os.ReadFile at parse time (vanished file / permission flip / truncated
	// tree). This is the dominant signal of a use-after-delete race on a shared
	// clone dir.
	DroppedReadError int `json:"droppedReadError,omitempty"`

	// DroppedCtxCancel counts files skipped because the snapshot context was
	// cancelled before the parse worker reached them (timeout / caller abort).
	DroppedCtxCancel int `json:"droppedCtxCancel,omitempty"`
}

type RouteDiff struct {
	Common     int            `json:"common"`
	OnlyACount int            `json:"onlyACount"`
	OnlyBCount int            `json:"onlyBCount"`
	OnlyA      []routes.Route `json:"onlyA,omitempty"`
	OnlyB      []routes.Route `json:"onlyB,omitempty"`
}

type SARIFArtifact struct {
	URI string `json:"uri"`
}

type SARIFDriver struct {
	Name    string      `json:"name"`
	Version string      `json:"version"`
	Rules   []SARIFRule `json:"rules,omitempty"`
}

type SARIFLocation struct {
	PhysicalLocation SARIFPhysical `json:"physicalLocation"`
}

type SARIFMessage struct {
	Text string `json:"text"`
}

type SARIFPhysical struct {
	ArtifactLocation SARIFArtifact `json:"artifactLocation"`
	Region           *SARIFRegion  `json:"region,omitempty"`
}

type SARIFRegion struct {
	StartLine int `json:"startLine"`
}

type SARIFReport struct {
	Schema  string     `json:"$schema"`
	Version string     `json:"version"`
	Runs    []SARIFRun `json:"runs"`
}

type SARIFResult struct {
	RuleID    string          `json:"ruleId"`
	Level     string          `json:"level"` // "error", "warning", "note"
	Message   SARIFMessage    `json:"message"`
	Locations []SARIFLocation `json:"locations,omitempty"`
}

type SARIFRule struct {
	ID               string           `json:"id"`
	ShortDescription SARIFMessage     `json:"shortDescription"`
	DefaultConfig    *SARIFRuleConfig `json:"defaultConfiguration,omitempty"`
}

type SARIFRuleConfig struct {
	Level string `json:"level"` // "error", "warning", "note"
}

type SARIFRun struct {
	Tool    SARIFTool     `json:"tool"`
	Results []SARIFResult `json:"results"`
}

type SARIFTool struct {
	Driver SARIFDriver `json:"driver"`
}

type SnapshotFile struct {
	RelPath  string           `json:"relPath"`
	Language string           `json:"language"`
	Lines    int              `json:"lines"`
	Symbols  []*parser.Symbol `json:"symbols,omitempty"`
	Imports  []string         `json:"imports,omitempty"`
}

type SnapshotOpts struct {
	// Focus limits ingestion to files under this subdirectory or matching this
	// glob pattern. Empty means process the entire repository.
	Focus string

	// Language limits ingestion to files of this programming language.
	// Empty means accept all supported languages.
	Language string
}

type SymbolMatch struct {
	SymbolA   *parser.Symbol `json:"symbolA,omitempty"`
	SymbolB   *parser.Symbol `json:"symbolB,omitempty"`
	MatchType MatchType      `json:"matchType"`
	Category  string         `json:"category"`
	Score     float64        `json:"score"`
	Diff      *DiffSummary   `json:"diff,omitempty"`
}

type VerdictResult struct {
	CanReplace string   `json:"canReplace"` // "yes", "partial", "no"
	Reason     string   `json:"reason"`
	Blockers   []string `json:"blockers,omitempty"`
}