analysis

type CallGraph struct {
	// Funcs indexes every function in the program by its CanonicalName. A function
	// with an empty one gets a unique "__local<N>" fallback key so it is still
	// analyzed intra-procedurally. This is the ONE name->function index, shared
	// with Analyze (see buildFuncIndex).
	Funcs map[string]*ir.Function

	// Edges maps a caller's CanonicalName to a sorted, de-duplicated list
	// of callee names. Every name appearing in Edges is guaranteed to be a
	// key in Funcs -- calls we could not resolve to a known function
	// (stdlib/external code that was never lowered to gIR, or a dynamic
	// dispatch with no known implementation) are simply dropped, so Edges
	// never dangles. A "__local<N>"-keyed function is not addressable by
	// callers, so it never appears as an Edges key.
	Edges map[string][]string

	// Callees maps each DISTINCT callee name this program calls to how many call
	// SITES name it, including the unresolved ones Edges drops (unlowered stdlib,
	// dynamic dispatch). The engine uses the key set to skip a rule whose sink
	// globs match nothing the program calls, and the counts feed the report's
	// source/sink workload figures; both are collected here rather than by a
	// separate walk because this pass already visits every instruction, and a
	// second walk cost more than the skipping saved.
	Callees map[string]int
}

type Confidence string

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

type Finding struct {
	RuleID     string
	Severity   rules.Severity
	Confidence Confidence
	CWE        string
	Message    string
	Language   string
	Function   string // enclosing function's CanonicalName
	Package    string // enclosing function's package (for user-code scoping; see internal/scan)
	SourcePos  *ir.Position
	SinkPos    *ir.Position
	SinkCallee string

	// RuleSanitizers and RuleSources are the matched rule's sanitizer/source
	// globs, carried onto the finding so the LLM reviewer can adjudicate using the
	// rulepack's OWN vocabulary (which documented sanitizer neutralizes this sink,
	// what the sources are) instead of second-guessing from generic knowledge
	// (LLM-8). Not serialized in reports.
	RuleSanitizers []string
	RuleSources    []string

	// Steps is the ordered taint path from source to sink (inclusive), when it
	// can be reconstructed intra-procedurally by walking the def-use chain. It
	// powers SARIF codeFlows (which GitHub code scanning renders as a data-flow)
	// and richer triage. Empty when only the endpoints are known (e.g. a flow
	// whose middle crossed a function boundary).
	Steps []*ir.Position

	// Suppressed marks a finding that a downstream triage stage (the LLM
	// reviewer) judged a false positive. A suppressed finding is RETAINED, not
	// discarded: it does not count toward the gate, but it stays visible in
	// reports with SuppressedBy/SuppressionReason so a nondeterministic model can
	// never silently erase a finding. Auditability over silent deletion.
	Suppressed        bool
	SuppressedBy      string // what suppressed it, e.g. "llm-review"
	SuppressionReason string // the reviewer's stated justification

	// ReviewConfirmed marks a finding the LLM reviewer adjudicated as a TRUE
	// positive (kept, not suppressed); ReviewNote carries the reviewer's
	// exploitability/reasoning. This surfaces the value of a review on the
	// findings it KEEPS — a confirmed interprocedural finding is higher-priority
	// triage — instead of only recording the ones it drops (LLM-7).
	ReviewConfirmed bool
	ReviewNote      string
}

type Stats struct {
	// Functions is the call-graph node count — distinct canonical function
	// names, which is a smaller set than the raw IR functions when two collapse
	// onto one name.
	Functions int

	// RulesLive is the rules the engine actually seeded, which is only the
	// DATAFLOW rules: canProduceFinding rejects a rule with no sinks, i.e. every
	// `kind: secret` and `kind: dangerous-call` rule — and those are genuinely
	// evaluated, by ScanSecrets and ScanDangerousCalls. Never present it as the
	// number of rules that ran.
	Rules     int
	RulesLive int

	// SourceSites and SinkSites count the CALL SITES whose callee matches some
	// rule's source or sink glob. They are a workload figure, not a bound on
	// findings: a sink match here ignores `#idx` injection-point pinning and
	// every `when:` guard, and a source match sees only callee-glob matches — the
	// seeding that is not a call at all (addHTTPRequestSource,
	// buildReqSourceHosts, request-object provenance) is invisible to it.
	SourceSites int
	SinkSites   int

	Index      time.Duration // function/method index and call graph
	RuleSelect time.Duration // rule compile, the can-produce-a-finding prefilter, and the counts above
	Taint      time.Duration // the parallel per-rule worklist
}