@jaguilar87/gaia-ops 1.0.0

package/tools/clarify_patterns.py

@@ -0,0 +1,356 @@
+"""
+Ambiguity Detection Patterns
+
+Defines keyword patterns and heuristics for detecting
+ambiguous user prompts that require clarification.
+"""
+
+from typing import List, Dict, Any, Optional
+import re
+
+
+class AmbiguityPattern:
+    """Base class for ambiguity detection patterns."""
+
+    def __init__(self, name: str, keywords: List[str], weight: int):
+        """
+        Args:
+            name: Pattern name (e.g., "service_ambiguity")
+            keywords: Keywords that trigger this pattern
+            weight: Ambiguity weight (0-100)
+        """
+        self.name = name
+        self.keywords = keywords
+        self.weight = weight
+
+    def detect(self, prompt: str, project_context: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+        """
+        Detect ambiguity in prompt.
+
+        Returns:
+            None if no ambiguity, otherwise:
+            {
+                "pattern": str,
+                "detected_keyword": str,
+                "ambiguity_reason": str,
+                "available_options": List[str],
+                "suggested_question": str,
+                "weight": int,
+                "allow_multiple": bool
+            }
+        """
+        raise NotImplementedError
+
+
+class ServiceAmbiguityPattern(AmbiguityPattern):
+    """Detects ambiguous service references."""
+
+    def __init__(self):
+        super().__init__(
+            name="service_ambiguity",
+            keywords=[
+                "the api", "el api", "la api", "api service", "the service",
+                "el servicio", "the app", "la app", "the web", "web service",
+                "the bot", "el bot", "the jobs", "los jobs", "el worker",
+                "check service", "chequea servicio", "deploy service",
+                "service status", "estado del servicio"
+            ],
+            weight=80  # High weight - very ambiguous
+        )
+
+    def detect(self, prompt: str, project_context: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+        prompt_lower = prompt.lower()
+
+        # Check if any keyword matches
+        detected_keyword = None
+        for keyword in self.keywords:
+            if keyword in prompt_lower:
+                detected_keyword = keyword
+                break
+
+        if not detected_keyword:
+            return None
+
+        # Extract available services from project_context
+        services = []
+        services_metadata = {}
+
+        if "sections" in project_context and "application_services" in project_context["sections"]:
+            for svc in project_context["sections"]["application_services"]:
+                service_name = svc.get("name", "unknown")
+                services.append(service_name)
+                services_metadata[service_name] = svc
+
+        # Check if user already specified a service name
+        for service_name in services:
+            if service_name in prompt_lower:
+                # User already specified which service, no ambiguity
+                return None
+
+        # If multiple services, this is ambiguous
+        if len(services) > 1:
+            return {
+                "pattern": self.name,
+                "detected_keyword": detected_keyword,
+                "ambiguity_reason": f"Mencionaste '{detected_keyword}', pero hay {len(services)} servicios en este proyecto.",
+                "available_options": services,
+                "services_metadata": services_metadata,
+                "suggested_question": f"¿Qué servicio quieres {self._infer_action(prompt)}?",
+                "weight": self.weight,
+                "allow_multiple": False
+            }
+
+        return None
+
+    def _infer_action(self, prompt: str) -> str:
+        """Infer user action from prompt for better question phrasing."""
+        prompt_lower = prompt.lower()
+
+        if any(word in prompt_lower for word in ["check", "chequea", "revisar", "status"]):
+            return "revisar"
+        elif any(word in prompt_lower for word in ["deploy", "desplegar", "update", "actualizar"]):
+            return "desplegar"
+        elif any(word in prompt_lower for word in ["fix", "arreglar", "debug"]):
+            return "debuggear"
+        else:
+            return "trabajar con"
+
+
+class NamespaceAmbiguityPattern(AmbiguityPattern):
+    """Detects ambiguous namespace references."""
+
+    def __init__(self):
+        super().__init__(
+            name="namespace_ambiguity",
+            keywords=[
+                "deploy to cluster", "desplegar en cluster", "check cluster",
+                "chequear cluster", "the namespace", "el namespace",
+                "to the cluster", "en el cluster", "in the cluster",
+                "al cluster", "cluster status", "estado del cluster"
+            ],
+            weight=60  # Medium-high weight
+        )
+
+    def detect(self, prompt: str, project_context: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+        prompt_lower = prompt.lower()
+
+        detected_keyword = None
+        for keyword in self.keywords:
+            if keyword in prompt_lower:
+                detected_keyword = keyword
+                break
+
+        if not detected_keyword:
+            return None
+
+        # Extract namespaces
+        namespaces = []
+        namespace_metadata = {}
+
+        if "sections" in project_context and "cluster_details" in project_context["sections"]:
+            cluster_details = project_context["sections"]["cluster_details"]
+            namespaces = cluster_details.get("primary_namespaces", [])
+
+            # Build metadata: count services per namespace
+            if "application_services" in project_context["sections"]:
+                for ns in namespaces:
+                    services_in_ns = [
+                        svc["name"] for svc in project_context["sections"]["application_services"]
+                        if svc.get("namespace") == ns
+                    ]
+                    namespace_metadata[ns] = {
+                        "services": services_in_ns,
+                        "service_count": len(services_in_ns)
+                    }
+
+        if len(namespaces) > 1:
+            return {
+                "pattern": self.name,
+                "detected_keyword": detected_keyword,
+                "ambiguity_reason": f"El cluster tiene {len(namespaces)} namespaces.",
+                "available_options": namespaces,
+                "namespace_metadata": namespace_metadata,
+                "suggested_question": "¿En qué namespace debería trabajar?",
+                "weight": self.weight,
+                "allow_multiple": False
+            }
+
+        return None
+
+
+class EnvironmentAmbiguityPattern(AmbiguityPattern):
+    """Detects environment confusion."""
+
+    def __init__(self):
+        super().__init__(
+            name="environment_ambiguity",
+            keywords=["production", "prod", "staging", "producción"],
+            weight=90  # Very high weight - critical
+        )
+
+    def detect(self, prompt: str, project_context: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+        prompt_lower = prompt.lower()
+
+        detected_keyword = None
+        for keyword in self.keywords:
+            # Use word boundaries to avoid matching "non-prod" when looking for "prod"
+            import re
+            pattern = r'\b' + re.escape(keyword) + r'\b'
+            if re.search(pattern, prompt_lower):
+                # Additional check: don't match "prod" if it's part of "non-prod"
+                if keyword == "prod" or keyword == "production":
+                    # Check if "non-prod" or "nonprod" is in the prompt
+                    if re.search(r'non[-\s]?prod', prompt_lower):
+                        continue  # Skip this keyword, it's part of "non-prod"
+                detected_keyword = keyword
+                break
+
+        if not detected_keyword:
+            return None
+
+        # Check current environment
+        current_env = "unknown"
+        if "sections" in project_context and "project_details" in project_context["sections"]:
+            current_env = project_context["sections"]["project_details"].get("environment", "unknown")
+
+        # If user says "prod" but environment is "non-prod", warn
+        if detected_keyword in ["production", "prod", "producción"] and current_env == "non-prod":
+            return {
+                "pattern": self.name,
+                "detected_keyword": detected_keyword,
+                "ambiguity_reason": f"⚠️ Mencionaste '{detected_keyword}', pero project-context.json muestra environment='{current_env}'.",
+                "available_options": [
+                    f"Continuar en {current_env}",
+                    "Detener (voy a cambiar configuración)",
+                    "Forzar producción (PELIGROSO)"
+                ],
+                "current_environment": current_env,
+                "requested_environment": detected_keyword,
+                "suggested_question": f"Mencionaste '{detected_keyword}', pero el proyecto está configurado como '{current_env}'. ¿Cómo proceder?",
+                "weight": self.weight,
+                "allow_multiple": False
+            }
+
+        return None
+
+
+class ResourceAmbiguityPattern(AmbiguityPattern):
+    """Detects ambiguous infrastructure resource references."""
+
+    def __init__(self):
+        super().__init__(
+            name="resource_ambiguity",
+            keywords=[
+                "the redis", "el redis", "redis instance", "instancia redis",
+                "the database", "la database", "the postgres", "el postgres",
+                "the sql", "cloud sql", "postgres instance", "instancia postgres"
+            ],
+            weight=70  # Medium-high weight
+        )
+
+    def detect(self, prompt: str, project_context: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+        prompt_lower = prompt.lower()
+
+        detected_keyword = None
+        resource_type = None
+        for keyword in self.keywords:
+            if keyword in prompt_lower:
+                detected_keyword = keyword
+                # Infer resource type
+                if "redis" in keyword:
+                    resource_type = "Redis"
+                elif any(db in keyword for db in ["postgres", "sql", "database"]):
+                    resource_type = "Database"
+                break
+
+        if not detected_keyword:
+            return None
+
+        # Extract resources from terraform_infrastructure or application_services
+        resources = []
+        resource_metadata = {}
+
+        # Check terraform infrastructure
+        if "sections" in project_context and "terraform_infrastructure" in project_context["sections"]:
+            infra = project_context["sections"]["terraform_infrastructure"]
+            if "modules" in infra:
+                for module_name, module_info in infra["modules"].items():
+                    # Check if module matches resource type
+                    if resource_type == "Redis" and "redis" in module_name.lower():
+                        resources.append(module_name)
+                        resource_metadata[module_name] = {
+                            "type": module_info.get("resources", "Memorystore Redis"),
+                            "status": module_info.get("status", "unknown"),
+                            "tier": module_info.get("tier", "N/A")
+                        }
+                    elif resource_type == "Database" and any(db in module_name.lower() for db in ["sql", "postgres", "database"]):
+                        resources.append(module_name)
+                        resource_metadata[module_name] = {
+                            "type": module_info.get("resources", "Cloud SQL PostgreSQL"),
+                            "status": module_info.get("status", "unknown"),
+                            "tier": module_info.get("tier", "N/A")
+                        }
+
+        # Also check application_services for Redis/DB references
+        if "sections" in project_context and "application_services" in project_context["sections"]:
+            for svc in project_context["sections"]["application_services"]:
+                service_name = svc.get("name", "")
+                if resource_type and resource_type.lower() in service_name.lower():
+                    if service_name not in resources:
+                        resources.append(service_name)
+                        resource_metadata[service_name] = {
+                            "type": "Application Service",
+                            "status": svc.get("status", "unknown"),
+                            "namespace": svc.get("namespace", "N/A")
+                        }
+
+        if len(resources) > 1:
+            return {
+                "pattern": self.name,
+                "detected_keyword": detected_keyword,
+                "ambiguity_reason": f"Encontré {len(resources)} recursos de {resource_type} en el proyecto.",
+                "available_options": resources,
+                "resource_metadata": resource_metadata,
+                "resource_type": resource_type,
+                "suggested_question": f"¿Qué recurso de {resource_type} quieres usar?",
+                "weight": self.weight,
+                "allow_multiple": False
+            }
+
+        return None
+
+
+# ============================================================================
+# PATTERN REGISTRY
+# ============================================================================
+
+AMBIGUITY_PATTERNS = [
+    ServiceAmbiguityPattern(),
+    NamespaceAmbiguityPattern(),
+    EnvironmentAmbiguityPattern(),
+    ResourceAmbiguityPattern()
+]
+
+
+def detect_all_ambiguities(prompt: str, project_context: Dict[str, Any]) -> List[Dict[str, Any]]:
+    """
+    Run all ambiguity patterns and return detected ambiguities.
+
+    Args:
+        prompt: User prompt to analyze
+        project_context: Loaded project-context.json
+
+    Returns:
+        List of detected ambiguities (sorted by weight, descending)
+    """
+    ambiguities = []
+
+    for pattern in AMBIGUITY_PATTERNS:
+        result = pattern.detect(prompt, project_context)
+        if result:
+            ambiguities.append(result)
+
+    # Sort by weight (highest first)
+    ambiguities.sort(key=lambda x: x["weight"], reverse=True)
+
+    return ambiguities

package/tools/commit_validator.py

@@ -0,0 +1,338 @@
+"""
+Git Commit Message Validator
+
+Validates commit messages against project standards before execution.
+This prevents commits with forbidden footers or incorrect format from
+being pushed to the repository.
+
+Usage:
+    from commit_validator import CommitMessageValidator
+
+    validator = CommitMessageValidator()
+    validation = validator.validate(commit_message)
+
+    if not validation.valid:
+        for error in validation.errors:
+            print(f"Error: {error['message']}")
+        # Do not proceed with commit
+    else:
+        # Safe to commit
+        git commit -m "$commit_message"
+"""
+
+import json
+import os
+import re
+from typing import Dict, List, Any, Optional
+from datetime import datetime
+from dataclasses import dataclass
+
+
+@dataclass
+class ValidationResult:
+    """Result of commit message validation."""
+    valid: bool
+    errors: List[Dict[str, str]]
+    warnings: List[Dict[str, str]] = None
+
+    def __post_init__(self):
+        if self.warnings is None:
+            self.warnings = []
+
+
+class CommitMessageValidator:
+    """
+    Validates git commit messages against project standards.
+
+    Standards are defined in .claude/config/git_standards.json
+    """
+
+    def __init__(self, config_path: Optional[str] = None):
+        """
+        Initialize validator with configuration.
+
+        Args:
+            config_path: Optional path to git_standards.json
+                        If None, uses default location
+        """
+        if config_path is None:
+            # Default path relative to this file
+            base_path = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+            config_path = os.path.join(base_path, 'config', 'git_standards.json')
+
+        self.config_path = config_path
+        self.config = self._load_config()
+        self.standards = self.config.get('commit_message', {})
+        self.enforcement = self.config.get('enforcement', {})
+
+    def _load_config(self) -> Dict[str, Any]:
+        """Load git standards configuration from JSON file."""
+        if not os.path.exists(self.config_path):
+            raise FileNotFoundError(
+                f"Git standards configuration not found at: {self.config_path}"
+            )
+
+        with open(self.config_path, 'r') as f:
+            return json.load(f)
+
+    def validate(self, message: str) -> ValidationResult:
+        """
+        Validate a commit message against all standards.
+
+        Args:
+            message: The commit message to validate
+
+        Returns:
+            ValidationResult with valid status and any errors/warnings
+        """
+        errors = []
+        warnings = []
+
+        # 1. Check for forbidden footers (CRITICAL)
+        footer_errors = self._check_forbidden_footers(message)
+        errors.extend(footer_errors)
+
+        # 2. Check conventional commits format
+        format_errors = self._check_conventional_format(message)
+        errors.extend(format_errors)
+
+        # 3. Check subject line rules
+        subject_errors = self._check_subject_rules(message)
+        errors.extend(subject_errors)
+
+        # 4. Check body rules (warnings only)
+        body_warnings = self._check_body_rules(message)
+        warnings.extend(body_warnings)
+
+        # Log violations if configured
+        if errors and self.enforcement.get('log_violations', False):
+            self._log_violation(message, errors)
+
+        return ValidationResult(
+            valid=len(errors) == 0,
+            errors=errors,
+            warnings=warnings
+        )
+
+    def _check_forbidden_footers(self, message: str) -> List[Dict[str, str]]:
+        """Check for forbidden footers in commit message."""
+        errors = []
+        forbidden = self.standards.get('footer_forbidden', [])
+
+        for forbidden_text in forbidden:
+            if forbidden_text.lower() in message.lower():
+                errors.append({
+                    'type': 'FORBIDDEN_FOOTER',
+                    'message': f"Commit message contains forbidden footer: '{forbidden_text}'",
+                    'fix': f"Remove all occurrences of '{forbidden_text}'",
+                    'severity': 'error'
+                })
+
+        return errors
+
+    def _check_conventional_format(self, message: str) -> List[Dict[str, str]]:
+        """Check if message follows Conventional Commits format."""
+        errors = []
+
+        # Get first line (subject)
+        lines = message.split('\n')
+        subject = lines[0].strip()
+
+        # Pattern: type(scope)?: description
+        # Examples: feat: add feature, fix(api): correct bug
+        allowed_types = '|'.join(self.standards.get('type_allowed', []))
+        pattern = rf'^({allowed_types})(\(.+?\))?: .+$'
+
+        if not re.match(pattern, subject):
+            errors.append({
+                'type': 'INVALID_FORMAT',
+                'message': 'Commit message does not follow Conventional Commits format',
+                'fix': f"Use format: type(scope): description\nAllowed types: {', '.join(self.standards.get('type_allowed', []))}",
+                'severity': 'error',
+                'examples': self.standards.get('examples_valid', [])
+            })
+
+        return errors
+
+    def _check_subject_rules(self, message: str) -> List[Dict[str, str]]:
+        """Check subject line specific rules."""
+        errors = []
+
+        lines = message.split('\n')
+        subject = lines[0].strip()
+
+        # Extract description part (after type and scope)
+        # Example: "feat(scope): description" -> "description"
+        match = re.match(r'^[a-z]+(\(.+?\))?: (.+)$', subject)
+        if match:
+            description = match.group(2)
+
+            # Check max length
+            max_length = self.standards.get('subject_max_length', 72)
+            if len(subject) > max_length:
+                errors.append({
+                    'type': 'SUBJECT_TOO_LONG',
+                    'message': f'Subject line exceeds {max_length} characters (current: {len(subject)})',
+                    'fix': f'Shorten subject to {max_length} characters or less',
+                    'severity': 'error'
+                })
+
+            # Check for period at end
+            rules = self.standards.get('subject_rules', {})
+            if rules.get('no_period_at_end', True) and description.endswith('.'):
+                errors.append({
+                    'type': 'SUBJECT_ENDS_WITH_PERIOD',
+                    'message': 'Subject line should not end with a period',
+                    'fix': 'Remove the period at the end of the subject',
+                    'severity': 'error'
+                })
+
+        return errors
+
+    def _check_body_rules(self, message: str) -> List[Dict[str, str]]:
+        """Check body rules (returns warnings, not errors)."""
+        warnings = []
+
+        lines = message.split('\n')
+
+        # Check if there's a body (more than just subject)
+        if len(lines) <= 1:
+            return warnings
+
+        # Check blank line after subject
+        if len(lines) > 1 and lines[1].strip() != '':
+            warnings.append({
+                'type': 'MISSING_BLANK_LINE',
+                'message': 'Missing blank line between subject and body',
+                'fix': 'Add a blank line after the subject line',
+                'severity': 'warning'
+            })
+
+        # Check body line length
+        max_length = self.standards.get('body_max_line_length', 72)
+        for i, line in enumerate(lines[2:], start=3):  # Skip subject and blank line
+            if len(line) > max_length and not line.startswith('http'):
+                warnings.append({
+                    'type': 'BODY_LINE_TOO_LONG',
+                    'message': f'Body line {i} exceeds {max_length} characters',
+                    'fix': f'Wrap line to {max_length} characters',
+                    'severity': 'warning'
+                })
+
+        return warnings
+
+    def _log_violation(self, message: str, errors: List[Dict[str, str]]):
+        """Log commit message violation for audit trail."""
+        log_path = self.enforcement.get('log_path', '.claude/logs/commit-violations.jsonl')
+
+        # Ensure log directory exists
+        log_dir = os.path.dirname(log_path)
+        if log_dir and not os.path.exists(log_dir):
+            os.makedirs(log_dir, exist_ok=True)
+
+        log_entry = {
+            'timestamp': datetime.now().isoformat(),
+            'message': message[:100] + ('...' if len(message) > 100 else ''),
+            'errors': errors,
+            'error_count': len(errors)
+        }
+
+        with open(log_path, 'a') as f:
+            f.write(json.dumps(log_entry) + '\n')
+
+    def get_examples(self) -> Dict[str, List[str]]:
+        """Get example commit messages (valid and invalid)."""
+        return {
+            'valid': self.standards.get('examples_valid', []),
+            'invalid': self.standards.get('examples_invalid', [])
+        }
+
+    def get_allowed_types(self) -> List[str]:
+        """Get list of allowed commit types."""
+        return self.standards.get('type_allowed', [])
+
+    def format_error_message(self, validation: ValidationResult) -> str:
+        """
+        Format validation errors into human-readable message.
+
+        Args:
+            validation: ValidationResult from validate()
+
+        Returns:
+            Formatted error message string
+        """
+        if validation.valid:
+            return "✅ Commit message is valid"
+
+        lines = ["❌ Commit message validation failed:\n"]
+
+        for error in validation.errors:
+            lines.append(f"  [{error['type']}]")
+            lines.append(f"  {error['message']}")
+            lines.append(f"  Fix: {error['fix']}")
+
+            if 'examples' in error:
+                lines.append(f"  Examples:")
+                for example in error['examples'][:3]:
+                    lines.append(f"    - {example}")
+
+            lines.append("")
+
+        if validation.warnings:
+            lines.append("⚠️  Warnings:")
+            for warning in validation.warnings:
+                lines.append(f"  - {warning['message']}")
+            lines.append("")
+
+        return "\n".join(lines)
+
+
+# Convenience function for quick validation
+def validate_commit_message(message: str) -> ValidationResult:
+    """
+    Quick validation function.
+
+    Args:
+        message: Commit message to validate
+
+    Returns:
+        ValidationResult
+
+    Example:
+        validation = validate_commit_message("feat: add new feature")
+        if not validation.valid:
+            print("Invalid commit message")
+    """
+    validator = CommitMessageValidator()
+    return validator.validate(message)
+
+
+# Function for use in git commit workflow
+def safe_validate_before_commit(message: str) -> bool:
+    """
+    Validate commit message and print errors if invalid.
+
+    This is the primary function that agents should call before git commit.
+
+    Args:
+        message: Commit message to validate
+
+    Returns:
+        True if valid, False if invalid (with errors printed)
+
+    Example:
+        if not safe_validate_before_commit(commit_message):
+            return {"status": "failed", "reason": "commit_validation_failed"}
+
+        # Safe to commit
+        Bash(f'git commit -m "{commit_message}"')
+    """
+    validator = CommitMessageValidator()
+    validation = validator.validate(message)
+
+    if not validation.valid:
+        error_message = validator.format_error_message(validation)
+        print(error_message)
+        return False
+
+    return True