core

type Argument struct {
	Value      string // The argument expression as a string
	IsVariable bool   // Whether this argument is a variable reference
	Position   int    // Position in the argument list (0-indexed)
}

type CallGraph struct {
	// Forward edges: maps fully qualified function name to list of functions it calls
	// Key: caller FQN (e.g., "myapp.views.get_user")
	// Value: list of callee FQNs (e.g., ["myapp.db.query", "myapp.utils.sanitize"])
	Edges map[string][]string

	// Reverse edges: maps fully qualified function name to list of functions that call it
	// Useful for backward slicing and finding all callers of a function
	// Key: callee FQN
	// Value: list of caller FQNs
	ReverseEdges map[string][]string

	// Detailed call site information for each function
	// Key: caller FQN
	// Value: list of all call sites within that function
	CallSites map[string][]CallSite

	// Map from fully qualified name to the actual function node in the graph
	// This allows quick lookup of function metadata (line number, file, etc.)
	Functions map[string]*graph.Node

	// Taint summaries for each function (intra-procedural analysis results)
	// Key: function FQN
	// Value: TaintSummary with taint flow information
	Summaries map[string]*TaintSummary
}

type CallSite struct {
	Target        string     // The name of the function being called (e.g., "eval", "utils.sanitize")
	Location      Location   // Where this call occurs in the source code
	Arguments     []Argument // Arguments passed to the call
	Resolved      bool       // Whether we successfully resolved this call to a definition
	TargetFQN     string     // Fully qualified name after resolution (e.g., "myapp.utils.sanitize")
	FailureReason string     // Why resolution failed (empty if Resolved=true)

	// Phase 2: Type inference metadata
	ResolvedViaTypeInference bool    // Was this resolved using type inference?
	InferredType             string  // The inferred type FQN (e.g., "builtins.str", "test.User")
	TypeConfidence           float32 // Confidence score of the type inference (0.0-1.0)
	TypeSource               string  // How type was inferred (e.g., "literal", "return_type", "class_instantiation")
}

type ClassAttribute struct {
	Name       string                // Attribute name (e.g., "value", "user")
	Type       *TypeInfo             // Inferred type of the attribute
	AssignedIn string                // Method where assigned (e.g., "__init__", "setup")
	Location   *graph.SourceLocation // Source location of the attribute
	Confidence float64               // Confidence in type inference (0.0-1.0)
}

type ClassAttributes struct {
	ClassFQN   string                     // Fully qualified class name (e.g., "myapp.models.User")
	Attributes map[string]*ClassAttribute // Map from attribute name to attribute info
	Methods    []string                   // List of method FQNs in this class
	FilePath   string                     // Source file path where class is defined
}

type DefUseChain struct {
	// Defs maps variable names to all statements that define them.
	// A variable can have multiple definitions across different code paths.
	Defs map[string][]*Statement

	// Uses maps variable names to all statements that use them.
	// A variable can be used in multiple places.
	Uses map[string][]*Statement
}

type DefUseStats struct {
	NumVariables       int // Total unique variables
	NumDefs            int // Total definition sites
	NumUses            int // Total use sites
	MaxDefsPerVariable int // Most definitions for a single variable
	MaxUsesPerVariable int // Most uses for a single variable
	UndefinedVariables int // Variables used but never defined (parameters)
	DeadVariables      int // Variables defined but never used
}

type FrameworkDefinition struct {
	Name        string   // Display name (e.g., "Django")
	Prefixes    []string // Module prefixes to match (e.g., ["django.", "django"])
	Description string   // Human-readable description
	Category    string   // Category: "web", "orm", "testing", "stdlib", etc.
}

type FunctionParam struct {
	Name     string `json:"name"`
	Type     string `json:"type"`
	Required bool   `json:"required"`
}

type ImportMap struct {
	FilePath string            // Absolute path to the file containing these imports
	Imports  map[string]string // Maps alias/name to fully qualified module path
}

type Location struct {
	File   string // Absolute path to the source file
	Line   int    // Line number (1-indexed)
	Column int    // Column number (1-indexed)
}

type Manifest struct {
	SchemaVersion    string            `json:"schema_version"`
	RegistryVersion  string            `json:"registry_version"`
	PythonVersion    PythonVersionInfo `json:"python_version"`
	GeneratedAt      string            `json:"generated_at"`
	GeneratorVersion string            `json:"generator_version"`
	BaseURL          string            `json:"base_url"`
	Modules          []*ModuleEntry    `json:"modules"`
	Statistics       *RegistryStats    `json:"statistics"`
}

type ModuleEntry struct {
	Name      string `json:"name"`
	File      string `json:"file"`
	URL       string `json:"url"`
	SizeBytes int64  `json:"size_bytes"`
	Checksum  string `json:"checksum"`
}

type ModuleRegistry struct {
	// Maps fully qualified module path to absolute file path
	// Key: "myapp.utils.helpers"
	// Value: "/absolute/path/to/myapp/utils/helpers.py"
	Modules map[string]string

	// Maps absolute file path to fully qualified module path (reverse of Modules)
	// Key: "/absolute/path/to/myapp/utils/helpers.py"
	// Value: "myapp.utils.helpers"
	// Used for resolving relative imports
	FileToModule map[string]string

	// Maps short module names to all matching file paths (handles ambiguity)
	// Key: "helpers"
	// Value: ["/path/to/myapp/utils/helpers.py", "/path/to/lib/helpers.py"]
	ShortNames map[string][]string

	// Cache for resolved imports to avoid redundant lookups
	// Key: import string (e.g., "utils.helpers")
	// Value: fully qualified module path
	ResolvedImports map[string]string
}

type PythonVersionInfo struct {
	Major int    `json:"major"`
	Minor int    `json:"minor"`
	Patch int    `json:"patch"`
	Full  string `json:"full"`
}

type RegistryStats struct {
	TotalModules    int `json:"total_modules"`
	TotalFunctions  int `json:"total_functions"`
	TotalClasses    int `json:"total_classes"`
	TotalConstants  int `json:"total_constants"`
	TotalAttributes int `json:"total_attributes"`
}

type Statement struct {
	// Type is the kind of statement (assignment, call, return, etc.)
	Type StatementType

	// LineNumber is the source line number for this statement (1-indexed)
	LineNumber uint32

	// Def is the variable being defined by this statement (if any)
	// For assignments: the left-hand side variable
	// For for loops: the loop variable
	// For with statements: the as variable
	// Empty string if no definition
	Def string

	// Uses is the list of variables used/read by this statement
	// For assignments: variables in the right-hand side expression
	// For calls: variables used in arguments
	// For conditions: variables in the condition expression
	Uses []string

	// CallTarget is the function/method being called (if Type == StatementTypeCall)
	// Format: "function_name" for direct calls, "obj.method" for method calls
	// Empty string for non-call statements
	CallTarget string

	// CallArgs are the argument variables passed to the call (if Type == StatementTypeCall)
	// Only includes variable names, not literals
	CallArgs []string

	// NestedStatements contains statements inside this statement's body
	// Used for if/for/while/with/try blocks
	// Empty for simple statements like assignments
	NestedStatements []*Statement

	// ElseBranch contains statements in the else branch (if applicable)
	// Used for if/try statements
	ElseBranch []*Statement
}

type StatementType string

type StdlibAttribute struct {
	Type        string  `json:"type"`
	BehavesLike string  `json:"behaves_like,omitempty"`
	Confidence  float32 `json:"confidence"`
	Docstring   string  `json:"docstring,omitempty"`
}

type StdlibClass struct {
	Type      string                     `json:"type"`
	Methods   map[string]*StdlibFunction `json:"methods"`
	Docstring string                     `json:"docstring,omitempty"`
}

type StdlibConstant struct {
	Type             string  `json:"type"`
	Value            string  `json:"value"`
	Confidence       float32 `json:"confidence"`
	PlatformSpecific bool    `json:"platform_specific,omitempty"`
}

type StdlibFunction struct {
	ReturnType string           `json:"return_type"`
	Confidence float32          `json:"confidence"`
	Params     []*FunctionParam `json:"params"`
	Source     string           `json:"source"`
	Docstring  string           `json:"docstring,omitempty"`
}

type StdlibModule struct {
	Module        string                      `json:"module"`
	PythonVersion string                      `json:"python_version"`
	GeneratedAt   string                      `json:"generated_at"`
	Functions     map[string]*StdlibFunction  `json:"functions"`
	Classes       map[string]*StdlibClass     `json:"classes"`
	Constants     map[string]*StdlibConstant  `json:"constants"`
	Attributes    map[string]*StdlibAttribute `json:"attributes"`
}

type StdlibRegistry struct {
	Modules  map[string]*StdlibModule
	Manifest *Manifest
}

type TaintInfo struct {
	// SourceLine is the line number where taint originated (1-indexed)
	SourceLine uint32

	// SourceVar is the variable name at the taint source
	SourceVar string

	// SinkLine is the line number where tainted data reaches a dangerous sink (1-indexed)
	SinkLine uint32

	// SinkVar is the variable name at the sink
	SinkVar string

	// SinkCall is the dangerous function/method call at the sink
	// Examples: "execute", "eval", "os.system"
	SinkCall string

	// PropagationPath is the list of variables through which taint propagated
	// Example: ["user_input", "data", "query"] shows user_input -> data -> query
	PropagationPath []string

	// Confidence is a score from 0.0 to 1.0 indicating detection confidence
	// 1.0 = high confidence (direct flow)
	// 0.7 = medium confidence (through stdlib function)
	// 0.5 = low confidence (through third-party library)
	// 0.0 = no taint detected
	Confidence float64

	// Sanitized indicates if a sanitizer was detected in the propagation path
	// If true, the taint was neutralized and should not trigger a finding
	Sanitized bool

	// SanitizerLine is the line number where sanitization occurred (if Sanitized == true)
	SanitizerLine uint32

	// SanitizerCall is the sanitizer function that was called
	// Examples: "escape_html", "quote_sql", "validate_email"
	SanitizerCall string
}

type TaintSummary struct {
	// FunctionFQN is the fully qualified name of the analyzed function
	// Format: "module.Class.method" or "module.function"
	FunctionFQN string

	// TaintedVars maps variable names to their taint information
	// If a variable is not in this map, it is considered untainted
	// Multiple TaintInfo entries indicate multiple taint paths to the same variable
	TaintedVars map[string][]*TaintInfo

	// Detections is a list of all taint flows that reached a dangerous sink
	// These represent potential security vulnerabilities
	Detections []*TaintInfo

	// TaintedParams tracks which function parameters are tainted (by parameter name)
	// Used for inter-procedural analysis
	TaintedParams []string

	// TaintedReturn indicates if the function's return value is tainted
	TaintedReturn bool

	// ReturnTaintInfo provides details if TaintedReturn is true
	ReturnTaintInfo *TaintInfo

	// AnalysisError indicates if the analysis failed for this function
	// If true, the summary is incomplete
	AnalysisError bool

	// ErrorMessage contains the error description if AnalysisError is true
	ErrorMessage string
}

type TypeInfo struct {
	TypeFQN    string  // Fully qualified type name (e.g., "builtins.str", "myapp.models.User")
	Confidence float32 // Confidence level from 0.0 to 1.0 (1.0 = certain, 0.5 = heuristic, 0.0 = unknown)
	Source     string  // How the type was inferred (e.g., "literal", "assignment", "annotation")
}