analyzer

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

type FallbackParser struct{}

type Parser interface {
	Parse(sql string) (*Statement, error)
}

type Profile struct {
	// Disabled rules are not constructed or run.
	Disabled map[string]bool
	// Only, when non-empty, is a whitelist: only these rules run.
	Only map[string]bool
	// Severity overrides a rule's reported severity.
	Severity map[string]Severity
	// Settings holds per-rule tunables.
	Settings map[string]Settings
	// RawQuery, when true, disables Result.Query redaction (literals are
	// left in the reported SQL). Default (false) redacts — see
	// Analyzer.WithRawQuery.
	RawQuery bool
}

type Result struct {
	RuleName string
	Severity Severity
	// Query is the offending SQL as surfaced to reporters. By default it is
	// redacted (string/numeric literals replaced with "?") so literal values
	// never reach a log sink; an Analyzer built WithRawQuery leaves it raw.
	Query string
	// Fingerprint is the redacted, whitespace-collapsed, list-folded query
	// identity (see analyzer.Fingerprint). It is always set, never carries
	// PII, and is safe as a metric label or log key.
	Fingerprint string
	Message     string
	Suggestion  string
	File        string // populated only in static analysis mode
	Line        int    // populated only in static analysis mode
}

type Rule func(s *Statement) (Result, bool)

type RuleSpec struct {
	Name            string
	DefaultSeverity Severity
	// Factory builds the rule for the statement path. It is nil for findings
	// the Analyzer does not produce itself — middleware's `slow-query` and
	// `n-plus-one`, and the plan rules `explain` derives from a query plan.
	// Those register so they are addressable by name like any other rule;
	// their owners ask the Analyzer for the resolved decision before they
	// emit. A nil Factory is never called.
	Factory func(Settings) Rule
}

type Settings map[string]any

type Severity int

type Statement struct {
	// Raw is the original, untouched SQL string. Reported back to users.
	Raw string

	// Kind is the statement's top-level kind.
	Kind StmtKind

	// HasWhere reports whether the statement has a WHERE clause.
	HasWhere bool

	// HasLimit reports whether the statement has a LIMIT clause.
	HasLimit bool

	// HasOrderBy reports whether the statement has an ORDER BY clause.
	HasOrderBy bool

	// HasFrom reports whether a SELECT has a FROM clause. Distinguishes
	// "SELECT * FROM t" from "SELECT 1" / "SELECT version()".
	HasFrom bool

	// SelectStar reports an unqualified "SELECT *" / "SELECT t.*" of columns.
	// It is false for aggregate forms like COUNT(*).
	SelectStar bool

	// SelectDistinct reports a select-level DISTINCT (SELECT DISTINCT ...,
	// incl. Postgres DISTINCT ON and MySQL DISTINCTROW). It is false for an
	// aggregate-level DISTINCT such as COUNT(DISTINCT col), which is unrelated.
	// The dialect parsers compute it from the AST; the fallback approximates it
	// lexically.
	SelectDistinct bool

	// InsertColumnsListed reports whether an INSERT names its target columns
	// explicitly, or has no columns to name. The second case is what keeps
	// PostgreSQL's INSERT INTO t DEFAULT VALUES and MySQL's
	// INSERT INTO t SET col = ... out of insert-without-columns: neither binds
	// caller-supplied values by position, so no schema change can shift them.
	// A parser filling this from an AST must account for both — reading it as
	// "the column list is non-empty" alone reports DEFAULT VALUES.
	// Only meaningful when Kind == StmtInsert.
	InsertColumnsListed bool

	// LeadingWildcardLike reports a LIKE pattern beginning with a wildcard
	// (e.g. LIKE '%foo'), which prevents index use.
	LeadingWildcardLike bool

	// NonSargablePredicate reports a function or cast applied to a column on
	// the column side of a WHERE comparison (e.g. WHERE LOWER(email) = ...),
	// which prevents the use of an ordinary index on that column. Like the
	// LIKE fields, this is a literal/text-level heuristic the real parsers'
	// ASTs discard, so it is computed by the fallback lexer and preserved by
	// the dialect parsers rather than recomputed structurally.
	NonSargablePredicate bool

	// AddNotNullNoDefault reports an ALTER TABLE that adds a NOT NULL column
	// with no DEFAULT (e.g. ALTER TABLE t ADD COLUMN c int NOT NULL), which
	// fails or forces a table rewrite on a populated table. Like the other
	// text-level fields above, it is computed by the fallback lexer and
	// preserved by the dialect parsers.
	AddNotNullNoDefault bool

	// ImplicitCommaJoin reports a FROM clause that lists multiple tables
	// separated by top-level commas (FROM a, b) instead of explicit JOIN
	// syntax — the old-style join that silently produces a cartesian product
	// when its join condition is forgotten. Computed by the fallback lexer and
	// preserved (not recomputed from the AST) by the dialect parsers, so it
	// stays a best-effort heuristic even when Exact is true.
	ImplicitCommaJoin bool

	// CartesianJoin reports a multi-table FROM (comma join, CROSS JOIN, or a
	// bare JOIN) with no join condition (ON/USING/NATURAL) and no top-level
	// WHERE filter — an unconditioned cartesian product. It is the high-
	// confidence subset of ImplicitCommaJoin and also covers CROSS/bare JOIN.
	// Like ImplicitCommaJoin, it is a fallback-lexer heuristic preserved by the
	// dialect parsers, so it stays best-effort even when Exact is true.
	CartesianJoin bool

	// MaxInListLen is the largest element count among the statement's IN (...)
	// value lists (IN (SELECT ...) subqueries are excluded). It powers the
	// in-list-too-large rule's max-length threshold. Zero means no value-list
	// IN was found. Like the other counts, rules read it, never raw SQL. It is a
	// fallback-lexer heuristic preserved by the dialect parsers (the AST discards
	// the literal list it counts), so it stays best-effort even when Exact is true.
	MaxInListLen int

	// OffsetValue is the largest literal OFFSET seen (standard OFFSET n or
	// MySQL's LIMIT offset, count), powering the large-offset rule. Zero means
	// no offset, OFFSET 0, or a parameterized offset (OFFSET $1 / ?), which
	// cannot be evaluated statically and is therefore never flagged. The dialect
	// parsers read it from the AST's limit clause; the fallback scans for it.
	OffsetValue int

	// LeadingWildcardTermLen is the length of the longest searchable term
	// (the literal with surrounding % wildcards trimmed) across all
	// leading-wildcard LIKE patterns in the statement. It powers the
	// leading-wildcard rule's min-length setting. Zero means "unknown"
	// (e.g. produced by a real parser that did not compute it); rules must
	// treat zero as unknown and not as "short", to avoid false negatives.
	LeadingWildcardTermLen int

	// Exact is true when the Statement was produced by a real SQL parser
	// (structural analysis), false when produced by the regex fallback
	// (best-effort). Rules may use this to suppress lower-confidence findings.
	//
	// "Exact" covers the structural facts the dialect parsers derive from the
	// AST: Kind, HasWhere/HasLimit/HasOrderBy/HasFrom, SelectStar,
	// SelectDistinct, OffsetValue, and InsertColumnsListed. A few facts stay
	// lexical heuristics even when Exact is true — MaxInListLen,
	// ImplicitCommaJoin, CartesianJoin, and the literal/text-level fields
	// (LeadingWildcard*, NonSargablePredicate, AddNotNullNoDefault) — because
	// they read literal values the AST discards or are intentionally text-level.
	// Each such field documents this.
	Exact bool
}

type StmtKind int