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

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 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 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 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 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 Severity string