ripple-sql 0.1.0__py3-none-any.whl

ripple/engine/validation.py

@@ -0,0 +1,158 @@
+"""Column lineage validation and trust scoring.
+
+This module provides validation functions for lineage correctness:
+- Trust level mapping from confidence scores
+- UNION column validation (positional vs semantic matching)
+- SELECT column name extraction
+
+Trust Levels:
+- verified: 1.0 confidence - warehouse-qualified or exact match
+- high_confidence: 0.8-0.99 - strong evidence
+- moderate: 0.5-0.79 - heuristic match
+- review_required: <0.5 - ambiguity or collision detected
+"""
+
+import logging
+from typing import TYPE_CHECKING
+
+from ripple.engine.safe_gen import safe_sql
+from ripple.engine.types import TrustLevel
+
+if TYPE_CHECKING:
+    from sqlglot import exp
+
+logger = logging.getLogger(__name__)
+
+
+def get_trust_level(confidence: float) -> TrustLevel:
+    """Map confidence score to trust level.
+
+    Args:
+        confidence: Confidence score (0.0-1.0)
+
+    Returns:
+        Trust level string for API response
+    """
+    if confidence >= 1.0:
+        return "verified"
+    elif confidence >= 0.8:
+        return "high_confidence"
+    elif confidence >= 0.5:
+        return "moderate"
+    return "review_required"
+
+
+def get_select_column_names(
+    select_node: "exp.Select",
+    dialect: str,
+) -> list[str]:
+    """Extract column names/aliases from a SELECT node.
+
+    Args:
+        select_node: SQLGlot Select expression
+        dialect: SQL dialect for generating SQL strings
+
+    Returns:
+        List of column names in order they appear
+    """
+    from sqlglot import exp
+
+    names = []
+    for select_expr in select_node.selects:
+        if isinstance(select_expr, exp.Alias):
+            names.append(select_expr.alias)
+        elif isinstance(select_expr, exp.Column):
+            names.append(select_expr.name)
+        elif isinstance(select_expr, exp.Star):
+            names.append("*")
+        else:
+            # Computed expression without alias - use SQL representation
+            sql = safe_sql(select_expr, dialect)
+            names.append(sql if sql is not None and len(sql) < 50 else f"expr_{len(names)}")
+    return names
+
+
+def validate_union_columns(
+    union_expr: "exp.Expression",
+    dialect: str,
+) -> tuple[bool, list[dict]]:
+    """Validate that UNION branches have matching column names.
+
+    SQL standard UNION uses positional matching, but column name mismatches
+    often indicate bugs. This function detects when UNION branches have
+    different column names at the same position.
+
+    Args:
+        union_expr: SQLGlot Union/Except/Intersect expression
+        dialect: SQL dialect
+
+    Returns:
+        Tuple of (is_valid, mismatches)
+        - is_valid: True if all column names match across branches
+        - mismatches: List of mismatch details if any found
+    """
+    from sqlglot import exp
+
+    branches: list[list[str]] = []
+
+    def collect_branches(node: exp.Expression) -> None:
+        """Recursively collect SELECT branches from set operations."""
+        if isinstance(node, (exp.Union, exp.Except, exp.Intersect)):
+            collect_branches(node.left)
+            collect_branches(node.right)
+        elif isinstance(node, exp.Select):
+            cols = get_select_column_names(node, dialect)
+            branches.append(cols)
+
+    collect_branches(union_expr)
+
+    if len(branches) < 2:
+        return True, []
+
+    first_branch = branches[0]
+    mismatches = []
+
+    for branch_idx, branch in enumerate(branches[1:], start=2):
+        # Check column count first
+        if len(branch) != len(first_branch):
+            mismatches.append(
+                {
+                    "branch": branch_idx,
+                    "warning_type": "union_column_count_mismatch",
+                    "expected_count": len(first_branch),
+                    "actual_count": len(branch),
+                    "warning": f"Branch {branch_idx} has {len(branch)} columns, expected {len(first_branch)}",
+                }
+            )
+            continue
+
+        # Check column names
+        for pos, (expected, actual) in enumerate(zip(first_branch, branch, strict=False), start=1):
+            # Skip if either is * (can't validate)
+            if expected == "*" or actual == "*":
+                # Log warning for SELECT * in UNION
+                logger.warning(
+                    f"UNION branch {branch_idx} uses SELECT * at position {pos} - "
+                    "cannot validate column names"
+                )
+                continue
+
+            if expected.lower() != actual.lower():
+                mismatches.append(
+                    {
+                        "branch": branch_idx,
+                        "position": pos,
+                        "expected": expected,
+                        "actual": actual,
+                        "warning_type": "union_column_name_mismatch",
+                        "warning": f"Column name mismatch at position {pos}: '{expected}' vs '{actual}'",
+                    }
+                )
+
+    return len(mismatches) == 0, mismatches
+
+
+# Underscore-prefixed aliases
+_get_trust_level = get_trust_level
+_validate_union_columns = validate_union_columns
+_get_select_column_names = get_select_column_names