callgraph

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 AttributeAssignment struct {
	AttributeName string       // Name of the attribute (e.g., "value", "user")
	RightSide     *sitter.Node // AST node of the right-hand side expression
	Node          *sitter.Node // Full assignment node
}

type AttributeRegistry struct {
	Classes map[string]*ClassAttributes // Map from class FQN to class attributes
	// contains filtered or unexported fields
}

type BasicBlock struct {
	// ID uniquely identifies this block within the CFG
	ID string

	// Type categorizes the block for analysis purposes
	Type BlockType

	// StartLine is the first line of code in this block (1-indexed)
	StartLine int

	// EndLine is the last line of code in this block (1-indexed)
	EndLine int

	// Instructions contains the call sites within this block.
	// Call sites represent function/method invocations that occur
	// during execution of this block.
	Instructions []CallSite

	// Successors are the blocks that can execute after this block.
	// For normal blocks: single successor
	// For conditional blocks: two successors (true/false branches)
	// For switch blocks: multiple successors (one per case)
	// For exit blocks: empty (no successors)
	Successors []string

	// Predecessors are the blocks that can execute before this block.
	// Used for backward analysis and dominance calculations.
	Predecessors []string

	// Condition stores the condition expression for conditional blocks.
	// Empty for non-conditional blocks.
	// Examples: "x > 0", "user.is_admin()", "data is not None"
	Condition string

	// Dominators are the blocks that always execute before this block
	// on any path from entry. Used for security analysis to determine
	// if sanitization always occurs before usage.
	Dominators []string
}

type BlockType string

type BuiltinMethod struct {
	Name       string    // Method name (e.g., "upper", "append")
	ReturnType *TypeInfo // Return type of the method
}

type BuiltinRegistry struct {
	Types map[string]*BuiltinType // Type FQN -> builtin type info
}

type BuiltinType struct {
	FQN     string                    // Fully qualified name (e.g., "builtins.str")
	Methods map[string]*BuiltinMethod // Method name -> method info
}

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
}

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 ChainStep struct {
	Expression string    // The full expression for this step (e.g., "create_builder()")
	MethodName string    // Just the method/function name (e.g., "create_builder")
	IsCall     bool      // True if this step is a function call (has parentheses)
	Type       *TypeInfo // Resolved type after this step
}

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
	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 ControlFlowGraph struct {
	// FunctionFQN is the fully qualified name of the function this CFG represents
	FunctionFQN string

	// Blocks maps block IDs to BasicBlock objects
	Blocks map[string]*BasicBlock

	// EntryBlockID identifies the entry block
	EntryBlockID string

	// ExitBlockID identifies the exit block
	ExitBlockID string

	// CallGraph reference for resolving inter-procedural flows
	CallGraph *CallGraph
}

type FailureStats struct {
	TotalAttempts          int
	NotSelfPrefix          int
	DeepChains             int // 3+ levels
	ClassNotFound          int
	AttributeNotFound      int
	MethodNotInBuiltins    int
	CustomClassUnsupported int

	// Pattern samples for analysis
	DeepChainSamples         []string
	AttributeNotFoundSamples []string
	CustomClassSamples       []string
}

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 FunctionScope struct {
	FunctionFQN string                      // Fully qualified name of the function
	Variables   map[string]*VariableBinding // Variable name -> binding
	ReturnType  *TypeInfo                   // Inferred return type of the function
}

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 ImportMapCache struct {
	// contains filtered or unexported fields
}

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 ORMPattern struct {
	Name        string   // Pattern name (e.g., "Django ORM")
	MethodNames []string // Common ORM method names
	Description string   // Human-readable description
}

type Pattern struct {
	ID          string      // Unique identifier (e.g., "SQL-INJECTION-001")
	Name        string      // Human-readable name
	Description string      // What this pattern detects
	Type        PatternType // Pattern category
	Severity    Severity    // Risk level

	// Sources are function names that introduce tainted data
	Sources []string

	// Sinks are function names that consume tainted data dangerously
	Sinks []string

	// Sanitizers are function names that clean tainted data
	Sanitizers []string

	// DangerousFunctions for PatternTypeDangerousFunction
	DangerousFunctions []string

	CWE   string // Common Weakness Enumeration
	OWASP string // OWASP Top 10 category
}

type PatternMatch struct {
	PatternID   string   // Pattern identifier
	PatternName string   // Human-readable name
	Description string   // What was detected
	Severity    Severity // Risk level
	CWE         string   // CWE identifier
	OWASP       string   // OWASP category

	// Vulnerability location details
	SourceFQN  string // Fully qualified name of the source function
	SourceCall string // The actual dangerous call (e.g., "input", "request.GET")
	SourceFile string // File path where source is located
	SourceLine uint32 // Line number of source function
	SourceCode string // Code snippet of source function

	SinkFQN  string // Fully qualified name of the sink function
	SinkCall string // The actual dangerous call (e.g., "eval", "exec")
	SinkFile string // File path where sink is located
	SinkLine uint32 // Line number of sink function
	SinkCode string // Code snippet of sink function

	DataFlowPath []string // Complete path from source to sink (FQNs)
}

type PatternMatchDetails struct {
	Matched      bool
	SourceFQN    string   // Fully qualified name of function containing the source call
	SourceCall   string   // The actual dangerous call (e.g., "input", "request.GET")
	SinkFQN      string   // Fully qualified name of function containing the sink call
	SinkCall     string   // The actual dangerous call (e.g., "eval", "exec")
	DataFlowPath []string // Complete path from source to sink
}

type PatternRegistry struct {
	Patterns       map[string]*Pattern        // Pattern ID -> Pattern
	PatternsByType map[PatternType][]*Pattern // Type -> Patterns
}

type PatternType 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 ReturnStatement struct {
	FunctionFQN string
	ReturnType  *TypeInfo
	Location    Location
}

type Severity 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 StdlibRegistryLoader struct {
	RegistryPath string // Path to registries directory (e.g., "registries/python3.14/stdlib/v1")
}

type TypeInferenceEngine struct {
	Scopes         map[string]*FunctionScope // Function FQN -> scope
	ReturnTypes    map[string]*TypeInfo      // Function FQN -> return type
	Builtins       *BuiltinRegistry          // Builtin types registry
	Registry       *ModuleRegistry           // Module registry reference
	Attributes     *AttributeRegistry        // Class attributes registry (Phase 3 Task 12)
	StdlibRegistry *StdlibRegistry           // Python stdlib registry (PR #2)
}

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")
}

type VariableBinding struct {
	VarName      string    // Variable name
	Type         *TypeInfo // Inferred type information
	AssignedFrom string    // FQN of function that assigned this value (if from function call)
	Location     Location  // Source location of the assignment
}