ChristianLempa_Boilerplates/cli/core/variable.py

from __future__ import annotations

from typing import Any, Dict, List, Optional, Set
from urllib.parse import urlparse
import logging
import re

logger = logging.getLogger(__name__)

TRUE_VALUES = {"true", "1", "yes", "on"}
FALSE_VALUES = {"false", "0", "no", "off"}
EMAIL_REGEX = re.compile(r"^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$")


class Variable:
  """Represents a single templating variable with lightweight validation."""

  def __init__(self, data: dict[str, Any]) -> None:
    """Initialize Variable from a dictionary containing variable specification.
    
    Args:
        data: Dictionary containing variable specification with required 'name' key
              and optional keys: description, type, options, prompt, value, default, section, origin
              
    Raises:
        ValueError: If data is not a dict, missing 'name' key, or has invalid default value
    """
    # Validate input
    if not isinstance(data, dict):
      raise ValueError("Variable data must be a dictionary")
    
    if "name" not in data:
      raise ValueError("Variable data must contain 'name' key")
    
    # Track which fields were explicitly provided in source data
    self._explicit_fields: Set[str] = set(data.keys())
    
    # Initialize fields
    self.name: str = data["name"]
    self.description: Optional[str] = data.get("description") or data.get("display", "")
    self.type: str = data.get("type", "str")
    self.options: Optional[List[Any]] = data.get("options", [])
    self.prompt: Optional[str] = data.get("prompt")
    if "value" in data:
      self.value: Any = data.get("value")
    elif "default" in data:
      self.value: Any = data.get("default")
    else:
      self.value: Any = None
    self.origin: Optional[str] = data.get("origin")
    self.sensitive: bool = data.get("sensitive", False)
    # Optional extra explanation used by interactive prompts
    self.extra: Optional[str] = data.get("extra")
    # Flag indicating this variable should be auto-generated when empty
    self.autogenerated: bool = data.get("autogenerated", False)
    # Flag indicating this variable is required even when section is disabled
    self.required: bool = data.get("required", False)
    # Flag indicating this variable can be empty/optional
    self.optional: bool = data.get("optional", False)
    # Original value before config override (used for display)
    self.original_value: Optional[Any] = data.get("original_value")
    # Variable dependencies - can be string or list of strings in format "var_name=value"
    needs_value = data.get("needs")
    if needs_value:
      if isinstance(needs_value, str):
        self.needs: List[str] = [needs_value]
      elif isinstance(needs_value, list):
        self.needs: List[str] = needs_value
      else:
        raise ValueError(f"Variable '{self.name}' has invalid 'needs' value: must be string or list")
    else:
      self.needs: List[str] = []

    # Validate and convert the default/initial value if present
    if self.value is not None:
      try:
        self.value = self.convert(self.value)
      except ValueError as exc:
        raise ValueError(f"Invalid default for variable '{self.name}': {exc}")


  def convert(self, value: Any) -> Any:
    """Validate and convert a raw value based on the variable type.
    
    This method performs type conversion but does NOT check if the value
    is required. Use validate_and_convert() for full validation including
    required field checks.
    """
    if value is None:
      return None

    # Treat empty strings as None to avoid storing "" for missing values.
    if isinstance(value, str) and value.strip() == "":
      return None

    # Type conversion mapping for cleaner code
    converters = {
      "bool": self._convert_bool,
      "int": self._convert_int, 
      "float": self._convert_float,
      "enum": self._convert_enum,
      "url": self._convert_url,
      "email": self._convert_email,
    }
    
    converter = converters.get(self.type)
    if converter:
      return converter(value)
    
    # Default to string conversion
    return str(value)
  
  def validate_and_convert(self, value: Any, check_required: bool = True) -> Any:
    """Validate and convert a value with comprehensive checks.
    
    This method combines type conversion with validation logic including
    required field checks. It's the recommended method for user input validation.
    
    Args:
        value: The raw value to validate and convert
        check_required: If True, raises ValueError for required fields with empty values
        
    Returns:
        The converted and validated value
        
    Raises:
        ValueError: If validation fails (invalid format, required field empty, etc.)
        
    Examples:
        # Basic validation
        var.validate_and_convert("example@email.com")  # Returns validated email
        
        # Required field validation
        var.validate_and_convert("", check_required=True)  # Raises ValueError if required
        
        # Autogenerated variables - allow empty values
        var.validate_and_convert("", check_required=False)  # Returns None for autogeneration
    """
    # First, convert the value using standard type conversion
    converted = self.convert(value)
    
    # Special handling for autogenerated variables
    # Allow empty values as they will be auto-generated later
    if self.autogenerated and (converted is None or (isinstance(converted, str) and (converted == "" or converted == "*auto"))):
      return None  # Signal that auto-generation should happen
    
    # Allow empty values for optional variables
    if self.optional and (converted is None or (isinstance(converted, str) and converted == "")):
      return None
    
    # Check if this is a required field and the value is empty
    if check_required and self.is_required():
      if converted is None or (isinstance(converted, str) and converted == ""):
        raise ValueError("This field is required and cannot be empty")
    
    return converted

  def _convert_bool(self, value: Any) -> bool:
    """Convert value to boolean."""
    if isinstance(value, bool):
      return value
    if isinstance(value, str):
      lowered = value.strip().lower()
      if lowered in TRUE_VALUES:
        return True
      if lowered in FALSE_VALUES:
        return False
    raise ValueError("value must be a boolean (true/false)")

  def _convert_int(self, value: Any) -> Optional[int]:
    """Convert value to integer."""
    if isinstance(value, int):
      return value
    if isinstance(value, str) and value.strip() == "":
      return None
    try:
      return int(value)
    except (TypeError, ValueError) as exc:
      raise ValueError("value must be an integer") from exc

  def _convert_float(self, value: Any) -> Optional[float]:
    """Convert value to float."""
    if isinstance(value, float):
      return value
    if isinstance(value, str) and value.strip() == "":
      return None
    try:
      return float(value)
    except (TypeError, ValueError) as exc:
      raise ValueError("value must be a float") from exc

  def _convert_enum(self, value: Any) -> Optional[str]:
    if value == "":
      return None
    val = str(value)
    if self.options and val not in self.options:
      raise ValueError(f"value must be one of: {', '.join(self.options)}")
    return val

  def _convert_url(self, value: Any) -> str:
    val = str(value).strip()
    if not val:
      return None
    parsed = urlparse(val)
    if not (parsed.scheme and parsed.netloc):
      raise ValueError("value must be a valid URL (include scheme and host)")
    return val

  def _convert_email(self, value: Any) -> str:
    val = str(value).strip()
    if not val:
      return None
    if not EMAIL_REGEX.fullmatch(val):
      raise ValueError("value must be a valid email address")
    return val

  def to_dict(self) -> Dict[str, Any]:
    """Serialize Variable to a dictionary for storage."""
    result = {}
    
    # Always include type
    if self.type:
      result['type'] = self.type
    
    # Include value/default if not None
    if self.value is not None:
      result['default'] = self.value
    
    # Include string fields if truthy
    for field in ('description', 'prompt', 'extra', 'origin'):
      if value := getattr(self, field):
        result[field] = value
    
    # Include boolean/list fields if truthy (but empty list is OK for options)
    if self.sensitive:
      result['sensitive'] = True
    if self.autogenerated:
      result['autogenerated'] = True
    if self.required:
      result['required'] = True
    if self.optional:
      result['optional'] = True
    if self.options is not None:  # Allow empty list
      result['options'] = self.options
    
    # Store dependencies (single value if only one, list otherwise)
    if self.needs:
      result['needs'] = self.needs[0] if len(self.needs) == 1 else self.needs
    
    return result
  
  def get_display_value(self, mask_sensitive: bool = True, max_length: int = 30, show_none: bool = True) -> str:
    """Get formatted display value with optional masking and truncation.
    
    Args:
        mask_sensitive: If True, mask sensitive values with asterisks
        max_length: Maximum length before truncation (0 = no limit)
        show_none: If True, display "(none)" for None values instead of empty string
        
    Returns:
        Formatted string representation of the value
    """
    if self.value is None or self.value == "":
      # Show (*auto) for autogenerated variables instead of (none)
      if self.autogenerated:
        return "[dim](*auto)[/dim]" if show_none else ""
      return "[dim](none)[/dim]" if show_none else ""
    
    # Mask sensitive values
    if self.sensitive and mask_sensitive:
      return "********"
    
    # Convert to string
    display = str(self.value)
    
    # Truncate if needed
    if max_length > 0 and len(display) > max_length:
      return display[:max_length - 3] + "..."
    
    return display
  
  def get_normalized_default(self) -> Any:
    """Get normalized default value suitable for prompts and display."""
    try:
      typed = self.convert(self.value)
    except Exception:
      typed = self.value
    
    # Autogenerated: return display hint
    if self.autogenerated and not typed:
      return "*auto"
    
    # Type-specific handlers
    if self.type == "enum":
      if not self.options:
        return typed
      return self.options[0] if typed is None or str(typed) not in self.options else str(typed)
    
    if self.type == "bool":
      return typed if isinstance(typed, bool) else (None if typed is None else bool(typed))
    
    if self.type == "int":
      try:
        return int(typed) if typed not in (None, "") else None
      except Exception:
        return None
    
    # Default: return string or None
    return None if typed is None else str(typed)
  
  def get_prompt_text(self) -> str:
    """Get formatted prompt text for interactive input.
    
    Returns:
        Prompt text with optional type hints and descriptions
    """
    prompt_text = self.prompt or self.description or self.name
    
    # Add type hint for semantic types if there's a default
    if self.value is not None and self.type in ["email", "url"]:
      prompt_text += f" ({self.type})"
    
    return prompt_text
  
  def get_validation_hint(self) -> Optional[str]:
    """Get validation hint for prompts (e.g., enum options).
    
    Returns:
        Formatted hint string or None if no hint needed
    """
    hints = []
    
    # Add enum options
    if self.type == "enum" and self.options:
      hints.append(f"Options: {', '.join(self.options)}")
    
    # Add extra help text
    if self.extra:
      hints.append(self.extra)
    
    return " — ".join(hints) if hints else None
  
  def is_required(self) -> bool:
    """Check if this variable requires a value (cannot be empty/None).
    
    A variable is considered required if:
    - It has an explicit 'required: true' flag (highest precedence)
    - OR it doesn't have a default value (value is None)
      AND it's not marked as autogenerated (which can be empty and generated later)
      AND it's not marked as optional (which can be empty)
      AND it's not a boolean type (booleans default to False if not set)
    
    Returns:
        True if the variable must have a non-empty value, False otherwise
    """
    # Optional variables can always be empty
    if self.optional:
      return False
    
    # Explicit required flag takes highest precedence
    if self.required:
      # But autogenerated variables can still be empty (will be generated later)
      if self.autogenerated:
        return False
      return True
    
    # Autogenerated variables can be empty (will be generated later)
    if self.autogenerated:
      return False
    
    # Boolean variables always have a value (True or False)
    if self.type == "bool":
      return False
    
    # Variables with a default value are not required
    if self.value is not None:
      return False
    
    # No default value and not autogenerated = required
    return True
  
  def clone(self, update: Optional[Dict[str, Any]] = None) -> 'Variable':
    """Create a deep copy of the variable with optional field updates.
    
    This is more efficient than converting to dict and back when copying variables.
    
    Args:
        update: Optional dictionary of field updates to apply to the clone
        
    Returns:
        New Variable instance with copied data
        
    Example:
        var2 = var1.clone(update={'origin': 'template'})
    """
    data = {
      'name': self.name,
      'type': self.type,
      'value': self.value,
      'description': self.description,
      'prompt': self.prompt,
      'options': self.options.copy() if self.options else None,
      'origin': self.origin,
      'sensitive': self.sensitive,
      'extra': self.extra,
      'autogenerated': self.autogenerated,
      'required': self.required,
      'optional': self.optional,
      'original_value': self.original_value,
      'needs': self.needs.copy() if self.needs else None,
    }
    
    # Apply updates if provided
    if update:
      data.update(update)
    
    # Create new variable
    cloned = Variable(data)
    
    # Preserve explicit fields from original, and add any update keys
    cloned._explicit_fields = self._explicit_fields.copy()
    if update:
      cloned._explicit_fields.update(update.keys())
    
    return cloned