dataface 0.1.2__py3-none-any.whl

dataface/core/compile/normalize_variables.py

@@ -0,0 +1,489 @@
+"""Variable normalization, validation, and dependency analysis."""
+
+import re
+from typing import Any
+
+from dataface.core.compile.errors import CompilationError
+from dataface.core.compile.jinja import extract_variable_dependencies
+from dataface.core.compile.models.chart.compiled import (
+    Chart,
+)
+from dataface.core.compile.models.face.compiled import Face, Layout
+from dataface.core.compile.models.query.compiled import AnyQuery, SqlQuery
+from dataface.core.compile.models.variable.authored import (
+    Variable,
+    VariableInputType,
+)
+
+_QUERY_NAME_RE = re.compile(r"^(?:queries\.)?[a-zA-Z_][a-zA-Z0-9_]*$")
+
+
+def _detect_variable_input_type(var: Variable) -> VariableInputType:
+    """Infer the input type for a variable from its authored fields.
+
+    When input is "auto" (the default), examines options, default, min/max/step,
+    hidden, and column fields to determine the appropriate input type.
+    If input is explicitly set to something other than "auto", returns it unchanged.
+
+    Returns:
+        The resolved VariableInputType string.
+    """
+    if var.input != "auto":
+        return var.input
+
+    has_options = var.options and (var.options.static or var.options.query)
+    has_slider_fields = (
+        var.min is not None or var.max is not None or var.step is not None
+    )
+
+    # List default (with or without options) → multiselect
+    if isinstance(var.default, list):
+        return "multiselect"
+
+    # Slider fields → slider
+    if has_slider_fields:
+        return "slider"
+
+    # Bool default → checkbox
+    if isinstance(var.default, bool):
+        return "checkbox"
+
+    # Options present → select
+    if has_options:
+        return "select"
+
+    # Column binding → select
+    if var.column:
+        return "select"
+
+    # Not visible (hidden) with no other signals → text
+    if not var.visible:
+        return "text"
+
+    # No signals → text (generic fallback)
+    return "text"
+
+
+def _promote_inline_option_queries(
+    variables: dict[str, Variable],
+    query_registry: dict[str, AnyQuery],
+    default_source: str | None = None,
+) -> None:
+    """Convert inline SQL in variable options.query to named queries.
+
+    When a variable defines options.query with raw SQL instead of a query
+    name reference, this creates a synthetic SqlQuery in the registry and
+    replaces options.query with the synthetic name.
+
+    Modifies both variables and query_registry in place.
+
+    Args:
+        variables: Dict of variable definitions to process
+        query_registry: Query registry to add synthetic queries to
+        default_source: Default source for queries without explicit source
+    """
+    for var_name, var in variables.items():
+        if not var.options or not var.options.query:
+            continue
+
+        query_ref = var.options.query.strip()
+        if not query_ref or _QUERY_NAME_RE.match(query_ref):
+            continue
+
+        synthetic_name = f"_var_{var_name}_options"
+        query_registry[synthetic_name] = SqlQuery(
+            sql=query_ref,
+            source=default_source,
+        )
+        var.options.query = synthetic_name
+
+
+def _build_variable_registry(face: Face) -> dict[str, Variable]:
+    """Build global variable registry by traversing compiled face tree.
+
+    Collects all variables from the entire face tree (root and nested faces).
+    Validates that variable names are unique across the entire tree.
+
+    Args:
+        face: Root Face to traverse
+
+    Returns:
+        Dict mapping variable name to Variable object (all variables from entire tree)
+
+    Raises:
+        CompilationError: If duplicate variable names found
+    """
+    registry: dict[str, Variable] = {}
+    _collect_variables_recursive(face, registry)
+    return registry
+
+
+def _collect_variables_recursive(face: Face, registry: dict[str, Variable]) -> None:
+    """Recursively collect variables from face and nested faces.
+
+    Args:
+        face: Face to collect variables from
+        registry: Registry dict to add variables to
+
+    Raises:
+        CompilationError: If duplicate variable names found
+    """
+    # Add variables from this face
+    if face.variables:
+        for var_name, var in face.variables.items():
+            if var_name in registry:
+                raise CompilationError(
+                    f"Duplicate variable name '{var_name}'. Variable names must be unique "
+                    "within a file (and those that are imported)."
+                )
+            registry[var_name] = var
+
+    # Recursively collect from nested faces in layout
+    if face.layout.items:
+        for item in face.layout.items:
+            if item.type == "face" and item.face:
+                _collect_variables_recursive(item.face, registry)
+
+
+def _validate_variable_references(face: Face) -> list[str]:
+    """Validate that all referenced variables are defined.
+
+    Checks that all variables referenced in queries and charts exist in
+    the variable registry. Returns warnings for any undefined references.
+
+    Args:
+        face: Root Face with variable_registry set
+
+    Returns:
+        List of warning messages for undefined variable references
+    """
+    warnings: list[str] = []
+    defined_vars = (
+        set(face.variable_registry.keys()) if face.variable_registry else set()
+    )
+
+    # Collect all referenced variables from charts
+    _collect_referenced_vars_recursive(face, defined_vars, warnings)
+
+    return warnings
+
+
+def _collect_referenced_vars_recursive(
+    face: Face,
+    defined_vars: set,
+    warnings: list[str],
+) -> None:
+    """Recursively check variable references in face and nested faces.
+
+    Args:
+        face: Face to check
+        defined_vars: Set of defined variable names
+        warnings: List to append warnings to
+    """
+    # Check charts in this face
+    for chart_name, chart in face.charts.items():
+        for var_name in chart.variable_dependencies:
+            if var_name not in defined_vars:
+                warnings.append(
+                    f"Chart '{chart_name}' references undefined variable '{var_name}'"
+                )
+
+    # Check queries in this face
+    for query_name, query in face.queries.items():
+        for var_name in query.variable_dependencies:
+            if var_name not in defined_vars:
+                warnings.append(
+                    f"Query '{query_name}' references undefined variable '{var_name}'"
+                )
+
+    # Recursively check nested faces
+    if face.layout.items:
+        for item in face.layout.items:
+            if item.type == "face" and item.face:
+                _collect_referenced_vars_recursive(item.face, defined_vars, warnings)
+
+
+def _generate_layout_variables(layout: Layout) -> dict[str, Variable]:
+    """Generate hidden variables for tabs and details in this layout only.
+
+    Tabs get a hidden select variable (slug values).
+    Details get a hidden checkbox variable (boolean).
+
+    Only generates variables for the current layout level — nested faces
+    handle their own variables during their own normalize_face() call.
+
+    Returns:
+        Dict of variable_name → Variable for all auto-generated variables.
+    """
+    from dataface.core.compile.models.variable.authored import VariableOptions
+
+    variables: dict[str, Variable] = {}
+
+    # Tabs: generate a select variable
+    if layout.type == "tabs" and layout.tab_variable and layout.tab_slugs:
+        variables[layout.tab_variable] = Variable(
+            input="select",
+            visible=False,
+            default=layout.tab_slugs[layout.default_tab or 0],
+            options=VariableOptions(
+                static=[*layout.tab_slugs],
+            ),
+        )
+
+    # Walk direct child items for details variables only.
+    # Don't recurse into nested faces — they already ran normalize_face()
+    # which called _generate_layout_variables() for their own layouts.
+    for item in layout.items:
+        if item.details_variable:
+            default = False
+            if item.face and item.face.meta:
+                default = item.face.meta.get("details_expanded_default", False)
+            variables[item.details_variable] = Variable(
+                input="checkbox",
+                visible=False,
+                default=default,
+            )
+
+    return variables
+
+
+# Type validators: input_type -> (type_check_fn, expected_type_desc)
+# text/select/input/textarea/radio accept any scalar type (no validation needed)
+_TYPE_VALIDATORS: dict[str, tuple[type | tuple[type, ...], str]] = {
+    "number": ((int, float), "a number"),
+    "slider": ((int, float), "a number"),
+    "range": ((int, float), "a number"),
+    "checkbox": (bool, "a boolean"),
+    "multiselect": (list, "a list"),
+    "date": (str, "a string"),
+    "datepicker": (str, "a string"),
+}
+
+
+def _validate_variable_value(var_name: str, var: Variable, value: Any) -> None:
+    """Validate a variable value against its input type.
+
+    Called at compile time to validate default values. Uses data-driven
+    validation via _TYPE_VALIDATORS dict.
+
+    Args:
+        var_name: Variable name (for error messages)
+        var: Variable definition with input type
+        value: Value to validate
+
+    Raises:
+        CompilationError: If value doesn't match expected type/format
+    """
+    if value is None:
+        return
+
+    input_type = var.input
+
+    # Special case: daterange needs structural validation (2-element list)
+    if input_type == "daterange":
+        if not isinstance(value, (list, tuple)) or len(value) != 2:
+            raise CompilationError(
+                f"Variable '{var_name}': daterange default must be [start, end], "
+                f"got {type(value).__name__}"
+            )
+        for i, v in enumerate(value):
+            if v is not None and not isinstance(v, str):
+                raise CompilationError(
+                    f"Variable '{var_name}': daterange[{i}] must be string, "
+                    f"got {type(v).__name__}"
+                )
+        return
+
+    # Standard type validation from dict
+    if input_type in _TYPE_VALIDATORS:
+        expected_type, desc = _TYPE_VALIDATORS[input_type]
+        if not isinstance(value, expected_type):
+            raise CompilationError(
+                f"Variable '{var_name}': {input_type} default must be {desc}, "
+                f"got {type(value).__name__}"
+            )
+
+    # Slider/range: additional min/max bounds check
+    if input_type in ("slider", "range"):
+        if var.min is not None and value < var.min:
+            raise CompilationError(
+                f"Variable '{var_name}': {input_type} default {value} < min {var.min}"
+            )
+        if var.max is not None and value > var.max:
+            raise CompilationError(
+                f"Variable '{var_name}': {input_type} default {value} > max {var.max}"
+            )
+
+
+def _compute_variable_dependencies(
+    variables: dict[str, Variable],
+    query_registry: dict[str, AnyQuery],
+) -> None:
+    """Compute variable dependencies for cascading dropdowns.
+
+    Analyzes each variable's options query SQL to find Jinja references
+    to other variables. Updates the variable_dependencies field in-place.
+
+    Also detects circular dependencies and raises an error if found.
+
+    Args:
+        variables: Dict of variable definitions to analyze
+        query_registry: Query registry to look up options queries
+
+    Raises:
+        CompilationError: If circular variable dependencies detected
+
+    Example:
+        If variable 'state' has options.query = 'state_options' and the
+        state_options query SQL contains {{ filter('country', country) }},
+        then state.variable_dependencies will be {'country'}.
+    """
+    # Build dependency graph
+    dep_graph: dict[str, set] = {}
+
+    for var_name, var in variables.items():
+        deps: set = set()
+
+        # Get the options query name
+        options_query_name = var.get_option_query()
+        if options_query_name and options_query_name in query_registry:
+            query = query_registry[options_query_name]
+
+            # Extract variable dependencies from query SQL and setup_sql
+            if hasattr(query, "sql") and query.sql:
+                sql_deps = extract_variable_dependencies(query.sql)
+                # Filter to only include variables that actually exist
+                deps = sql_deps & set(variables.keys())
+            if hasattr(query, "setup_sql") and query.setup_sql:
+                setup_deps = extract_variable_dependencies(query.setup_sql)
+                deps |= setup_deps & set(variables.keys())
+
+            # Also check query filters
+            if hasattr(query, "filters") and query.filters:
+                for filter_value in query.filters.values():
+                    if isinstance(filter_value, str):
+                        filter_deps = extract_variable_dependencies(filter_value)
+                        deps |= filter_deps & set(variables.keys())
+
+        # Also extract deps from disabled Jinja expressions so the UI
+        # re-evaluates disabled state when any referenced variable changes.
+        if isinstance(var.disabled, str):
+            disabled_deps = extract_variable_dependencies(var.disabled)
+            deps |= disabled_deps & set(variables.keys())
+
+        # Remove self-reference (a variable can't depend on itself)
+        deps.discard(var_name)
+
+        # Update the variable's dependencies
+        var.variable_dependencies = deps
+        dep_graph[var_name] = deps
+
+    # Check for circular dependencies
+    _detect_circular_variable_deps(dep_graph)
+
+
+def _detect_circular_variable_deps(dep_graph: dict[str, set]) -> None:
+    """Detect circular dependencies in variable dependency graph.
+
+    Uses depth-first search to find cycles.
+
+    Args:
+        dep_graph: Dict mapping variable name to set of dependencies
+
+    Raises:
+        CompilationError: If circular dependency found
+    """
+    visited: set = set()
+    rec_stack: set = set()
+
+    def dfs(node: str, path: list[str]) -> None:
+        if node in rec_stack:
+            # Found a cycle - build the cycle path for error message
+            cycle_start = path.index(node)
+            cycle = path[cycle_start:] + [node]
+            raise CompilationError(
+                f"Circular variable dependency detected: {' → '.join(cycle)}. "
+                "Variables cannot depend on each other in a cycle. "
+                "Check the options queries for these variables."
+            )
+
+        if node in visited:
+            return
+
+        visited.add(node)
+        rec_stack.add(node)
+
+        for dep in dep_graph.get(node, set()):
+            if dep in dep_graph:  # Only follow known variables
+                dfs(dep, path + [node])
+
+        rec_stack.remove(node)
+
+    for var_name in dep_graph:
+        dfs(var_name, [])
+
+
+def get_transitive_variable_dependencies(
+    variable_name: str,
+    variables: dict[str, Variable],
+) -> set:
+    """Get all transitive dependencies for a variable.
+
+    If variable A depends on B, and B depends on C, then A's transitive
+    dependencies are {B, C}.
+
+    Args:
+        variable_name: Variable to get dependencies for
+        variables: Dict of all variables
+
+    Returns:
+        Set of all variable names that this variable depends on (directly or transitively)
+    """
+    result: set = set()
+    visited: set = set()
+
+    def collect_deps(var_name: str) -> None:
+        if var_name in visited:
+            return
+        visited.add(var_name)
+
+        var = variables.get(var_name)
+        if not var:
+            return
+
+        for dep in var.variable_dependencies:
+            result.add(dep)
+            collect_deps(dep)
+
+    collect_deps(variable_name)
+    return result
+
+
+def _expand_chart_variable_dependencies(
+    charts: dict[str, "Chart"],
+    variables: dict[str, Variable],
+) -> None:
+    """Expand chart variable dependencies to include transitive dependencies.
+
+    If a chart depends on variable A, and A depends on B (cascading dropdown),
+    then the chart should also track dependency on B so the UI knows to
+    re-render when B changes.
+
+    Modifies charts in place.
+
+    Args:
+        charts: Dict of compiled charts
+        variables: Dict of variables with computed dependencies
+    """
+    for chart in charts.values():
+        expanded_deps: set = set()
+
+        # For each variable the chart directly depends on
+        for var_name in chart.variable_dependencies:
+            expanded_deps.add(var_name)
+            # Add all transitive dependencies of that variable
+            transitive = get_transitive_variable_dependencies(var_name, variables)
+            expanded_deps |= transitive
+
+        # Update chart's variable dependencies
+        chart.variable_dependencies = expanded_deps