sql

Documentation

Overview

Package sql provides SQL statement-level linting rules and analysis.

This package contains:

• SQLRule interface and RuleDef type for defining rules
• Analyzer for running SQL rules against parsed statements
• AST utilities for rule implementation

Rules are registered via init() functions and stored in the unified registry (pkg/lint). The analyzer retrieves rules from the registry and filters by dialect at runtime.

Example Usage

import (
    "github.com/leapstack-labs/leapsql/pkg/lint"
    "github.com/leapstack-labs/leapsql/pkg/lint/sql"
    _ "github.com/leapstack-labs/leapsql/pkg/lint/sql/rules" // register all rules
)

analyzer := sql.NewAnalyzer(lint.NewConfig(), "duckdb")
diagnostics := analyzer.Analyze(stmt, dialect)

Index

• func Register(rule RuleDef)
• func WrapRuleDef(def RuleDef) lint.SQLRule
• type Analyzer
  • func NewAnalyzer(config *lint.Config, dialect string) *Analyzer
  • func (a *Analyzer) Analyze(stmt any, dialect lint.DialectInfo) []lint.Diagnostic
  • func (a *Analyzer) AnalyzeMultiple(stmts []any, dialect lint.DialectInfo) []lint.Diagnostic
• type CheckFunc
• type RuleDef

Functions

func Register

func Register(rule RuleDef)

Register adds a rule to the registry. Call this from init() functions in rule packages.

func WrapRuleDef

func WrapRuleDef(def RuleDef) lint.SQLRule

WrapRuleDef wraps a RuleDef to implement lint.SQLRule.

Types

type Analyzer

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

Analyzer runs SQL lint rules against parsed statements.

func NewAnalyzer

func NewAnalyzer(config *lint.Config, dialect string) *Analyzer

NewAnalyzer creates a new SQL analyzer with optional configuration.

func (*Analyzer) Analyze

func (a *Analyzer) Analyze(stmt any, dialect lint.DialectInfo) []lint.Diagnostic

Analyze runs all registered SQL rules against the statement. The stmt parameter should be *core.SelectStmt.

func (*Analyzer) AnalyzeMultiple

func (a *Analyzer) AnalyzeMultiple(stmts []any, dialect lint.DialectInfo) []lint.Diagnostic

AnalyzeMultiple runs analysis on multiple statements.

type CheckFunc

type CheckFunc func(stmt any, dialect lint.DialectInfo, opts map[string]any) []lint.Diagnostic

CheckFunc analyzes a statement and returns diagnostics. The stmt parameter is *core.SelectStmt passed as any to avoid import cycles. The opts parameter contains rule-specific options from configuration.

type RuleDef

type RuleDef struct {
	ID          string        // Unique identifier, e.g., "AM01" or "ansi/select-star"
	Name        string        // Human-readable name, e.g., "ambiguous.distinct"
	Group       string        // Category, e.g., "ambiguous", "structure", "convention"
	Description string        // Human-readable description
	Severity    core.Severity // Default severity
	Check       CheckFunc     // The check function
	ConfigKeys  []string      // Configuration keys this rule accepts (for rule-specific options)
	Dialects    []string      // Restrict to specific dialects; nil/empty means all dialects

	// Documentation fields for richer rule documentation
	Rationale   string // Why this rule exists, what problems it prevents
	BadExample  string // Code showing the anti-pattern
	GoodExample string // Code showing the correct pattern
	Fix         string // How to fix violations (when not obvious)
}

RuleDef is a data-driven SQL rule definition. Rules are stateless - all context comes via the Check function parameters. The Check function receives an `any` type that should be *core.SelectStmt. This avoids import cycles between lint -> parser -> dialect -> lint.