perf

type CallContext struct {
	// LoopDepth is the nesting depth of loop forms at the call site.
	LoopDepth int
	// InLoop is true when LoopDepth > 0.
	InLoop bool
}

type CallEdge struct {
	// Caller is the qualified name of the calling function.
	Caller string
	// Callee is the qualified name of the called function.
	Callee string
	// Source is the location of the call expression.
	Source *token.Location
	// Context describes the loop nesting at the call site.
	Context CallContext
	// IsExpensive is true if the callee matches an expensive function pattern.
	IsExpensive bool
}

type CallGraph struct {
	// Functions maps qualified function names to their summaries.
	Functions map[string]*FunctionSummary
	// Edges is the complete set of call edges.
	Edges []CallEdge
}

type Config struct {
	// ExpensiveFunctions are glob patterns matching function names considered
	// expensive (e.g., "db-*", "http-*"). Calls to these functions receive
	// an additional cost penalty.
	ExpensiveFunctions []string `yaml:"expensive_functions"`

	// ExpensiveCost is the extra cost added per call to an expensive function.
	ExpensiveCost int `yaml:"expensive_cost"`

	// LoopKeywords are symbols that introduce loop iteration in ELPS
	// (e.g., "dotimes", "map", "foldl"). Embedders may append
	// domain-specific iteration forms via config.
	LoopKeywords []string `yaml:"loop_keywords"`

	// LoopMultiplier is the assumed number of iterations per loop level.
	// Used to amplify costs inside loops.
	LoopMultiplier int `yaml:"loop_multiplier"`

	// MaxScore is the PERF001 threshold: functions with TotalScore above
	// this value are flagged as hot paths.
	MaxScore int `yaml:"max_score"`

	// MaxAcceptableOrder is the PERF002 warning threshold: functions with
	// ScalingOrder >= this value receive a warning.
	MaxAcceptableOrder int `yaml:"max_acceptable_order"`

	// ScalingErrorThreshold is the PERF002 error threshold: functions with
	// ScalingOrder >= this value receive an error.
	ScalingErrorThreshold int `yaml:"scaling_error_threshold"`

	// MaxRecursionOrder caps the scaling order assigned to recursive functions.
	MaxRecursionOrder int `yaml:"max_recursion_order"`

	// FunctionCosts provides per-function cost overrides. Keys are function
	// names (exact match), values are the base cost for a single call.
	// Overrides the default cost of 1. Embedders use this to assign
	// domain-specific weights (e.g., {"statedb:put": 100}).
	FunctionCosts map[string]int `yaml:"function_costs"`

	// SuppressionPrefix is the comment text that disables analysis for a
	// function. Defaults to "elps-analyze-disable". Embedders can
	// override this (e.g., "substrate-analyze-disable").
	SuppressionPrefix string `yaml:"suppression_prefix"`

	// AmplificationCausesScaling enables N+1 detection mode. When true,
	// calling an expensive function inside a loop adds +1 to the caller's
	// scaling order beyond the loop depth contribution. This surfaces the
	// classic N+1 query pattern more aggressively.
	AmplificationCausesScaling bool `yaml:"amplification_causes_scaling"`

	// Rules filters which rules to run. When empty, all rules run.
	// Valid values: "PERF001", "PERF002", "PERF003", "PERF004", "UNKNOWN001".
	Rules []string `yaml:"rules"`

	// ExcludeFiles are file glob patterns excluded from CLI-oriented analysis
	// workflows. The analyzer core remains file-agnostic.
	ExcludeFiles []string `yaml:"exclude_files"`

	// IncludeTests opts back into including *_test.lisp files in CLI-oriented
	// analysis workflows.
	IncludeTests bool `yaml:"include_tests"`
}

type FunctionSummary struct {
	// Name is the qualified function name (package:name or just name).
	Name string
	// Source is the location of the function definition.
	Source *token.Location
	// File is the source file containing this function.
	File string
	// LocalCost is the base cost of the function body (before propagation).
	LocalCost int
	// MaxLoopDepth is the deepest loop nesting found in the function body.
	MaxLoopDepth int
	// Calls are the outgoing call edges from this function.
	Calls []CallEdge
	// SuppressAll is true if the function has a bare elps-analyze-disable comment.
	SuppressAll bool
	// SuppressedRules contains rule IDs suppressed for this function.
	SuppressedRules map[RuleID]bool
}

type Issue struct {
	// Rule identifies which performance rule triggered.
	Rule RuleID
	// Severity indicates the severity level.
	Severity Severity
	// Message is a human-readable description of the issue.
	Message string
	// Function is the function where the issue was detected.
	Function string
	// Source is the source location of the issue.
	Source *token.Location
	// File is the source file.
	File string
	// Details provides additional context (e.g., cycle members, call chain).
	Details []string
	// Fingerprint is a stable identifier for this issue across runs,
	// derived from sha256(file:function:rule)[:16].
	Fingerprint string
	// Trace is the call chain that explains why this issue was raised.
	// For PERF001/PERF002, it shows the hot path from caller to expensive leaf.
	// For PERF003, it shows the loop context.
	Trace []TraceEntry
}

type Result struct {
	// Solved contains the propagated scores for each function.
	Solved []*SolvedFunction
	// Issues contains all performance diagnostics.
	Issues []Issue
	// Graph is the call graph used for analysis.
	Graph *CallGraph
}

type RuleID string

type Severity int

type SolvedFunction struct {
	// Name is the qualified function name.
	Name string
	// Source is the location of the function definition.
	Source *token.Location
	// File is the source file.
	File string
	// LocalCost is the base cost before propagation.
	LocalCost int
	// TotalScore is the propagated cost including callee contributions.
	TotalScore int
	// ScalingOrder is the propagated loop amplification factor.
	// 0 = O(1), 1 = O(N), 2 = O(N²), etc.
	ScalingOrder int
	// InCycle is true if this function participates in a recursive cycle.
	InCycle bool
}

type TraceEntry struct {
	// Function is the function name at this step.
	Function string
	// Source is the source location.
	Source *token.Location
	// Note describes what happens at this step (e.g., "calls db-put in loop (depth 1)").
	Note string
}