Add scope graph + bidirectional type checking for SQL analysis

Implement a new SQL analysis system based on two concepts from
programming language theory:

1. Scope graphs (internal/analysis/scope/): Model SQL name resolution
   as path-finding in a labeled graph. Each scope contains declarations
   (columns, tables, aliases) connected by edges (PARENT, ALIAS,
   LATERAL, OUTER). This handles joins, subqueries, CTEs, and aliases
   compositionally — the resolution algorithm doesn't change, only the
   graph structure does.

2. Bidirectional type checking (internal/analysis/typecheck/): Type
   information flows in two directions — synthesis (bottom-up: "what
   type does this expression have?") and checking (top-down: "does this
   match the expected type?"). This naturally handles parameter type
   inference: when $1 appears in `WHERE age > $1`, checking mode infers
   $1's type from the column's type.

3. SQL analyzer (internal/analysis/sqlanalyze/): Combines both systems
   by walking the sqlc AST, building scope graphs from FROM/JOIN/CTE
   clauses, and running bidirectional type checking on expressions.
   Supports SELECT, INSERT, UPDATE, DELETE with parameter inference,
   output column resolution, and engine-specific operator rules for
   PostgreSQL and MySQL.

https://claude.ai/code/session_01VFJemaXKRZ2NfxYkpwXSbD

Author: claude

internal/analysis/scope/resolve.go

@@ -0,0 +1,274 @@
+package scope
+
+import "fmt"
+
+// ResolutionError describes why name resolution failed with full provenance.
+type ResolutionError struct {
+	Name       string
+	Qualifier  string // Table/alias qualifier, if any
+	Kind       ResolutionErrorKind
+	Scope      *Scope   // The scope where resolution was attempted
+	Candidates []string // For ambiguity errors, the competing names
+	Location   int      // Source position of the reference
+}
+
+type ResolutionErrorKind int
+
+const (
+	ErrNotFound ResolutionErrorKind = iota
+	ErrAmbiguous
+	ErrQualifierNotFound // e.g., "u.name" but "u" doesn't exist
+)
+
+func (e *ResolutionError) Error() string {
+	switch e.Kind {
+	case ErrNotFound:
+		if e.Qualifier != "" {
+			return fmt.Sprintf("column %q not found in %q", e.Name, e.Qualifier)
+		}
+		return fmt.Sprintf("column %q does not exist", e.Name)
+	case ErrAmbiguous:
+		return fmt.Sprintf("column reference %q is ambiguous", e.Name)
+	case ErrQualifierNotFound:
+		return fmt.Sprintf("table or alias %q does not exist", e.Qualifier)
+	default:
+		return fmt.Sprintf("resolution error for %q", e.Name)
+	}
+}
+
+// ResolutionPath records the edges traversed during successful resolution.
+// This is the provenance — it tells you exactly how a name was resolved.
+type ResolutionPath struct {
+	Steps []ResolutionStep
+}
+
+type ResolutionStep struct {
+	Edge  *Edge  // nil for the final lookup step
+	Scope *Scope // The scope where this step occurred
+}
+
+// ResolvedName is the result of successful name resolution.
+type ResolvedName struct {
+	Declaration *Declaration
+	Path        ResolutionPath
+}
+
+// Resolve looks up an unqualified column name in this scope.
+// It searches local declarations first, then follows parent edges.
+// Returns an error if the name is not found or is ambiguous.
+func (s *Scope) Resolve(name string) (*ResolvedName, error) {
+	return s.resolve(name, nil, 0)
+}
+
+// ResolveQualified looks up a qualified name like "u.name".
+// First resolves the qualifier (table/alias), then looks up the column
+// in that table's scope.
+func (s *Scope) ResolveQualified(qualifier, name string) (*ResolvedName, error) {
+	// First, find the qualifier (table name or alias)
+	qualScope, err := s.resolveQualifier(qualifier, 0)
+	if err != nil {
+		return nil, &ResolutionError{
+			Name:      name,
+			Qualifier: qualifier,
+			Kind:      ErrQualifierNotFound,
+			Scope:     s,
+		}
+	}
+
+	// Then resolve the column within that scope
+	var matches []*Declaration
+	for _, d := range qualScope.Declarations {
+		if d.Name == name {
+			matches = append(matches, d)
+		}
+	}
+
+	if len(matches) == 0 {
+		return nil, &ResolutionError{
+			Name:      name,
+			Qualifier: qualifier,
+			Kind:      ErrNotFound,
+			Scope:     qualScope,
+		}
+	}
+	if len(matches) > 1 {
+		return nil, &ResolutionError{
+			Name:      name,
+			Qualifier: qualifier,
+			Kind:      ErrAmbiguous,
+			Scope:     qualScope,
+		}
+	}
+
+	return &ResolvedName{
+		Declaration: matches[0],
+		Path: ResolutionPath{
+			Steps: []ResolutionStep{
+				{Scope: s},
+				{Scope: qualScope},
+			},
+		},
+	}, nil
+}
+
+const maxResolutionDepth = 20
+
+// resolve performs recursive name resolution with cycle detection via depth limit.
+func (s *Scope) resolve(name string, visited map[*Scope]bool, depth int) (*ResolvedName, error) {
+	if depth > maxResolutionDepth {
+		return nil, &ResolutionError{Name: name, Kind: ErrNotFound, Scope: s}
+	}
+	if visited == nil {
+		visited = make(map[*Scope]bool)
+	}
+	if visited[s] {
+		return nil, &ResolutionError{Name: name, Kind: ErrNotFound, Scope: s}
+	}
+	visited[s] = true
+
+	// Search local declarations first
+	var matches []*Declaration
+	for _, d := range s.Declarations {
+		if d.Name == name && d.Kind == DeclColumn {
+			matches = append(matches, d)
+		}
+	}
+
+	// Also search table/alias declarations to find columns inside their scopes
+	for _, d := range s.Declarations {
+		if (d.Kind == DeclTable || d.Kind == DeclAlias || d.Kind == DeclCTE) && d.Scope != nil {
+			for _, cd := range d.Scope.Declarations {
+				if cd.Name == name && cd.Kind == DeclColumn {
+					matches = append(matches, cd)
+				}
+			}
+		}
+	}
+
+	if len(matches) == 1 {
+		return &ResolvedName{
+			Declaration: matches[0],
+			Path: ResolutionPath{
+				Steps: []ResolutionStep{{Scope: s}},
+			},
+		}, nil
+	}
+	if len(matches) > 1 {
+		return nil, &ResolutionError{Name: name, Kind: ErrAmbiguous, Scope: s}
+	}
+
+	// Follow parent, lateral, and outer edges
+	for _, edge := range s.Edges {
+		switch edge.Kind {
+		case EdgeParent, EdgeLateral, EdgeOuter:
+			result, err := edge.Target.resolve(name, visited, depth+1)
+			if err == nil {
+				result.Path.Steps = append([]ResolutionStep{{Edge: edge, Scope: s}}, result.Path.Steps...)
+				return result, nil
+			}
+			// Propagate ambiguity errors — don't swallow them
+			if resErr, ok := err.(*ResolutionError); ok && resErr.Kind == ErrAmbiguous {
+				return nil, resErr
+			}
+		}
+	}
+
+	return nil, &ResolutionError{Name: name, Kind: ErrNotFound, Scope: s}
+}
+
+// resolveQualifier finds the scope associated with a table name or alias.
+func (s *Scope) resolveQualifier(qualifier string, depth int) (*Scope, error) {
+	if depth > maxResolutionDepth {
+		return nil, fmt.Errorf("qualifier %q not found", qualifier)
+	}
+
+	// Check alias edges first (higher priority)
+	for _, edge := range s.Edges {
+		if edge.Kind == EdgeAlias && edge.Label == qualifier {
+			return edge.Target, nil
+		}
+	}
+
+	// Check local table/alias declarations
+	for _, d := range s.Declarations {
+		if d.Name == qualifier && (d.Kind == DeclTable || d.Kind == DeclAlias || d.Kind == DeclCTE) && d.Scope != nil {
+			return d.Scope, nil
+		}
+	}
+
+	// Follow parent edges
+	for _, edge := range s.Edges {
+		if edge.Kind == EdgeParent || edge.Kind == EdgeLateral || edge.Kind == EdgeOuter {
+			result, err := edge.Target.resolveQualifier(qualifier, depth+1)
+			if err == nil {
+				return result, nil
+			}
+		}
+	}
+
+	return nil, fmt.Errorf("qualifier %q not found", qualifier)
+}
+
+// ResolveColumnRef resolves a column reference that may have 1, 2, or 3 parts:
+//   - ["name"]           -> unqualified column
+//   - ["alias", "name"]  -> table-qualified column
+//   - ["schema", "table", "name"] -> schema-qualified column (treated as qualifier="table")
+func (s *Scope) ResolveColumnRef(parts []string) (*ResolvedName, error) {
+	switch len(parts) {
+	case 1:
+		return s.Resolve(parts[0])
+	case 2:
+		return s.ResolveQualified(parts[0], parts[1])
+	case 3:
+		// For now, ignore schema and use table.column
+		return s.ResolveQualified(parts[1], parts[2])
+	default:
+		return nil, fmt.Errorf("invalid column reference with %d parts", len(parts))
+	}
+}
+
+// AllColumns returns all column declarations visible from this scope,
+// optionally filtered by a qualifier. This is used for SELECT * expansion.
+func (s *Scope) AllColumns(qualifier string) []*Declaration {
+	if qualifier != "" {
+		qualScope, err := s.resolveQualifier(qualifier, 0)
+		if err != nil {
+			return nil
+		}
+		var cols []*Declaration
+		for _, d := range qualScope.Declarations {
+			if d.Kind == DeclColumn {
+				cols = append(cols, d)
+			}
+		}
+		return cols
+	}
+
+	// Collect from all table/alias declarations in this scope
+	var cols []*Declaration
+	seen := make(map[string]bool)
+
+	var collect func(sc *Scope, depth int)
+	collect = func(sc *Scope, depth int) {
+		if depth > maxResolutionDepth {
+			return
+		}
+		for _, d := range sc.Declarations {
+			if (d.Kind == DeclTable || d.Kind == DeclAlias || d.Kind == DeclCTE) && d.Scope != nil {
+				for _, cd := range d.Scope.Declarations {
+					if cd.Kind == DeclColumn && !seen[d.Name+"."+cd.Name] {
+						seen[d.Name+"."+cd.Name] = true
+						cols = append(cols, cd)
+					}
+				}
+			}
+		}
+		for _, edge := range sc.Edges {
+			if edge.Kind == EdgeParent {
+				collect(edge.Target, depth+1)
+			}
+		}
+	}
+	collect(s, 0)
+	return cols
+}