mcp-souschef 2.5.3__py3-none-any.whl → 3.0.0__py3-none-any.whl

souschef/core/metrics.py

@@ -0,0 +1,313 @@
+"""Centralized metrics and effort calculation module for consistent time estimations."""
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import NamedTuple
+
+__all__ = [
+    "ComplexityLevel",
+    "EffortMetrics",
+    "convert_days_to_hours",
+    "convert_days_to_weeks",
+    "convert_hours_to_days",
+    "estimate_effort_for_complexity",
+    "get_team_recommendation",
+    "get_timeline_weeks",
+]
+
+
+class ComplexityLevel(str, Enum):
+    """Standard complexity levels used across all components."""
+
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+
+
+@dataclass
+class EffortMetrics:
+    """
+    Centralized container for all effort estimates.
+
+    Provides consistent representations across different formats:
+    - Base unit: person-days (with decimal precision)
+    - Derived: hours, weeks with consistent conversion factors
+    - Ranges: For display purposes, converting days to week ranges
+
+    Ensures all components (migration planning, dependency mapping,
+    validation reports) use the same underlying numbers.
+    """
+
+    estimated_days: float
+    """Base unit: person-days (e.g., 2.5, 5.0, 10.0)"""
+
+    @property
+    def estimated_hours(self) -> float:
+        """Convert days to hours using standard 8-hour workday."""
+        return self.estimated_days * 8
+
+    @property
+    def estimated_weeks_low(self) -> int:
+        """Conservative estimate: assumes optimal parallelization."""
+        return max(1, int(self.estimated_days / 7))
+
+    @property
+    def estimated_weeks_high(self) -> int:
+        """Realistic estimate: assumes sequential/limited parallelization."""
+        return max(1, int(self.estimated_days / 3.5))
+
+    @property
+    def estimated_weeks_range(self) -> str:
+        """Human-readable week range (e.g., '2-4 weeks')."""
+        low = self.estimated_weeks_low
+        high = self.estimated_weeks_high
+        if low == high:
+            return f"{low} week{'s' if low != 1 else ''}"
+        return f"{low}-{high} weeks"
+
+    @property
+    def estimated_days_formatted(self) -> str:
+        """Formatted days with appropriate precision."""
+        if self.estimated_days == int(self.estimated_days):
+            return f"{int(self.estimated_days)} days"
+        return f"{self.estimated_days:.1f} days"
+
+    def __str__(self) -> str:
+        """Return a string representation of effort metrics."""
+        return f"{self.estimated_days_formatted} ({self.estimated_weeks_range})"
+
+
+class TeamRecommendation(NamedTuple):
+    """Team composition and timeline recommendation."""
+
+    team_size: str
+    """e.g., '1 developer + 1 reviewer'"""
+
+    timeline_weeks: int
+    """Recommended timeline in weeks"""
+
+    description: str
+    """Human-readable description of the recommendation"""
+
+
+# Conversion constants - Single source of truth
+HOURS_PER_WORKDAY = 8
+DAYS_PER_WEEK = 7
+
+# Complexity thresholds for automatic categorization
+COMPLEXITY_THRESHOLD_LOW = 30
+COMPLEXITY_THRESHOLD_HIGH = 70
+
+# Effort multiplier per resource (base 1 resource = baseline effort)
+EFFORT_MULTIPLIER_PER_RESOURCE = 0.125  # 0.125 days = 1 hour per resource
+
+
+def convert_days_to_hours(days: float) -> float:
+    """Convert person-days to hours using standard 8-hour workday."""
+    return days * HOURS_PER_WORKDAY
+
+
+def convert_hours_to_days(hours: float) -> float:
+    """Convert hours to person-days using standard 8-hour workday."""
+    return hours / HOURS_PER_WORKDAY
+
+
+def convert_days_to_weeks(days: float, conservative: bool = False) -> int:
+    """
+    Convert days to weeks estimate.
+
+    Args:
+        days: Number of person-days
+        conservative: If True, use realistic estimate (1 engineer, limited
+            parallelization). If False, use optimistic estimate (full
+            parallelization)
+
+    Returns:
+        Number of weeks (integer)
+
+    """
+    weeks = days / 3.5 if conservative else days / DAYS_PER_WEEK
+    return max(1, int(weeks))
+
+
+def estimate_effort_for_complexity(
+    complexity_score: float, resource_count: int = 1
+) -> EffortMetrics:
+    """
+    Estimate effort based on complexity score and resource count.
+
+    Provides consistent effort estimation across all components.
+
+    Formula:
+    - Base effort: resource_count * 0.125 days per recipe/resource
+    - Complexity multiplier: 1.0 + (complexity_score / 100)
+    - Final effort: base_effort * complexity_multiplier
+
+    Args:
+        complexity_score: Score from 0-100 (0=simple, 100=complex)
+        resource_count: Number of resources to migrate (recipes, templates, etc.)
+
+    Returns:
+        EffortMetrics object with all representations
+
+    """
+    base_effort = resource_count * EFFORT_MULTIPLIER_PER_RESOURCE
+    complexity_multiplier = 1.0 + (complexity_score / 100)
+    estimated_days = base_effort * complexity_multiplier
+
+    return EffortMetrics(estimated_days=round(estimated_days, 1))
+
+
+def categorize_complexity(score: float) -> ComplexityLevel:
+    """
+    Categorize complexity score into standard levels.
+
+    Consistent thresholds across all components:
+    - Low: 0-29
+    - Medium: 30-69
+    - High: 70-100
+
+    Args:
+        score: Complexity score from 0-100
+
+    Returns:
+        ComplexityLevel enum value
+
+    """
+    if score < COMPLEXITY_THRESHOLD_LOW:
+        return ComplexityLevel.LOW
+    elif score < COMPLEXITY_THRESHOLD_HIGH:
+        return ComplexityLevel.MEDIUM
+    else:
+        return ComplexityLevel.HIGH
+
+
+def get_team_recommendation(total_effort_days: float) -> TeamRecommendation:
+    """
+    Get team composition and timeline recommendation based on total effort.
+
+    Consistent recommendations across all components.
+
+    Args:
+        total_effort_days: Total person-days of effort
+
+    Returns:
+        TeamRecommendation with team size and timeline
+
+    """
+    if total_effort_days < 20:
+        return TeamRecommendation(
+            team_size="1 developer + 1 reviewer",
+            timeline_weeks=4,
+            description="Single developer with oversight",
+        )
+    elif total_effort_days < 50:
+        return TeamRecommendation(
+            team_size="2 developers + 1 senior reviewer",
+            timeline_weeks=6,
+            description="Small dedicated team",
+        )
+    else:
+        return TeamRecommendation(
+            team_size="3-4 developers + 1 tech lead + 1 architect",
+            timeline_weeks=10,
+            description="Large dedicated migration team",
+        )
+
+
+def get_timeline_weeks(total_effort_days: float, strategy: str = "phased") -> int:
+    """
+    Calculate recommended timeline in weeks based on effort and strategy.
+
+    Consistent timeline calculation across planning, dependency mapping, and reports.
+
+    Args:
+        total_effort_days: Total person-days estimated
+        strategy: Migration strategy ('phased', 'big_bang', 'parallel')
+
+    Returns:
+        Recommended timeline in weeks
+
+    """
+    # Base calculation: distribute effort across team capacity
+    # Assume 3-5 person-days of output per week with normal team capacity
+    base_weeks = max(2, int(total_effort_days / 4.5))
+
+    # Apply strategy adjustments
+    if strategy == "phased":
+        # Phased adds overhead for testing between phases
+        return int(base_weeks * 1.1)
+    elif strategy == "big_bang":
+        # Big bang is faster but riskier
+        return int(base_weeks * 0.9)
+    else:  # parallel
+        # Parallel has some overhead for coordination
+        return int(base_weeks * 1.05)
+
+
+def validate_metrics_consistency(
+    days: float, weeks: str, hours: float, complexity: str
+) -> tuple[bool, list[str]]:
+    """
+    Validate that different metric representations are consistent.
+
+    Used for validation reports to catch contradictions.
+
+    Args:
+        days: Days estimate
+        weeks: Weeks range string (e.g., "2-4 weeks")
+        hours: Hours estimate
+        complexity: Complexity level string
+
+    Returns:
+        Tuple of (is_valid, list_of_errors)
+
+    """
+    errors = []
+
+    # Check hours consistency
+    expected_hours = days * 8
+    if abs(hours - expected_hours) > 1.0:  # Allow 1 hour tolerance
+        errors.append(
+            f"Hours mismatch: {hours:.1f} hours but {days} days = "
+            f"{expected_hours:.1f} hours"
+        )
+
+    # Check weeks consistency (loose check due to range)
+    # Valid formats: "1 week", "1-2 weeks"
+    if "week" not in weeks.lower():
+        errors.append(f"Invalid weeks format: {weeks}")
+    elif "-" in weeks:
+        # Range format: "X-Y weeks"
+        try:
+            parts = weeks.replace(" weeks", "").replace(" week", "").split("-")
+            week_min = int(parts[0].strip())
+            week_max = int(parts[1].strip())
+            expected_weeks = int(days / 3.5)  # Conservative estimate
+
+            if not (week_min <= expected_weeks <= week_max + 1):
+                errors.append(
+                    f"Weeks mismatch: {weeks} but {days} days should be "
+                    f"approximately {expected_weeks} weeks"
+                )
+        except (ValueError, IndexError):
+            errors.append(f"Invalid weeks format: {weeks}")
+    else:
+        # Single week format: "X week" or "X weeks"
+        try:
+            num = int(weeks.replace(" weeks", "").replace(" week", "").strip())
+            expected_weeks = int(days / 3.5)
+            if num != expected_weeks and abs(num - expected_weeks) > 2:
+                errors.append(
+                    f"Weeks mismatch: {weeks} but {days} days should be "
+                    f"approximately {expected_weeks} weeks"
+                )
+        except ValueError:
+            errors.append(f"Invalid weeks format: {weeks}")
+
+    # Check complexity is valid
+    valid_complexities = {level.value for level in ComplexityLevel}
+    if complexity.lower() not in valid_complexities:
+        errors.append(f"Invalid complexity level: {complexity}")
+
+    return len(errors) == 0, errors

souschef/core/path_utils.py

@@ -7,10 +7,8 @@ def _normalize_path(path_str: str) -> Path:
     """
     Normalize a file path for safe filesystem operations.
 
-    This function resolves relative paths and symlinks to absolute paths,
-    preventing path traversal attacks (CWE-23). Note: This MCP server
-    intentionally allows full filesystem access as it runs in the user's
-    local environment with their permissions.
+    This function validates input and resolves relative paths and symlinks
+    to absolute paths, preventing path traversal attacks (CWE-23).
 
     Args:
         path_str: Path string to normalize.
@@ -19,17 +17,22 @@ def _normalize_path(path_str: str) -> Path:
         Resolved absolute Path object.
 
     Raises:
-        ValueError: If the path contains null bytes or is invalid.
+        ValueError: If the path contains null bytes, traversal attempts, or is invalid.
 
     """
+    if not isinstance(path_str, str):
+        raise ValueError(f"Path must be a string, got {type(path_str)}")
+
+    # Reject paths with null bytes
     if "\x00" in path_str:
         raise ValueError(f"Path contains null bytes: {path_str!r}")
 
+    # Reject paths with obvious directory traversal attempts
+    if ".." in path_str:
+        raise ValueError(f"Path contains directory traversal: {path_str!r}")
+
     try:
-        # Resolve to absolute path, removing .., ., and resolving symlinks
-        # This is the path normalization function itself that validates input
-        # lgtm[py/path-injection]
-        # codeql[py/path-injection]
+        # Resolve to absolute path, removing ., and resolving symlinks
         return Path(path_str).resolve()
     except (OSError, RuntimeError) as e:
         raise ValueError(f"Invalid path {path_str}: {e}") from e

souschef/core/validation.py

@@ -586,3 +586,56 @@ class ValidationEngine:
             elif result.level == ValidationLevel.INFO:
                 summary["info"] += 1
         return summary
+
+
+def _format_validation_results_summary(
+    conversion_type: str, summary: dict[str, int]
+) -> str:
+    """
+    Format validation results as a summary.
+
+    Args:
+        conversion_type: Type of conversion.
+        summary: Summary of validation results.
+
+    Returns:
+        Formatted summary output.
+
+    """
+    total_issues = summary["errors"] + summary["warnings"] + summary["info"]
+
+    if total_issues == 0:
+        return f"""# Validation Summary for {conversion_type} Conversion
+
+✅ **All validation checks passed!** No issues found.
+
+Errors: 0
+Warnings: 0
+Info: 0
+"""
+
+    # Determine status icon based on error/warning counts
+    if summary["errors"] > 0:
+        status_icon = "❌"
+    elif summary["warnings"] > 0:
+        status_icon = "⚠️"
+    else:
+        status_icon = "ℹ️"
+
+    # Determine status message based on error/warning counts
+    if summary["errors"] > 0:
+        status = "Failed"
+    elif summary["warnings"] > 0:
+        status = "Warning"
+    else:
+        status = "Passed with info"
+
+    return f"""# Validation Summary for {conversion_type} Conversion
+
+{status_icon} **Validation Results:**
+• Errors: {summary["errors"]}
+• Warnings: {summary["warnings"]}
+• Info: {summary["info"]}
+
+**Status:** {status}
+"""

souschef/deployment.py

@@ -21,6 +21,11 @@ from souschef.core.errors import (
     validate_cookbook_structure,
     validate_directory_exists,
 )
+from souschef.core.metrics import (
+    ComplexityLevel,
+    EffortMetrics,
+    categorize_complexity,
+)
 from souschef.core.path_utils import _safe_join
 
 # Maximum length for attribute values in Chef attribute parsing
@@ -51,7 +56,7 @@ def generate_awx_job_template_from_cookbook(
             )
 
         cookbook = validate_cookbook_structure(cookbook_path)
-        cookbook_analysis = _analyze_cookbook_for_awx(cookbook, cookbook_name)
+        cookbook_analysis = _analyse_cookbook_for_awx(cookbook, cookbook_name)
         job_template = _generate_awx_job_template(
             cookbook_analysis, cookbook_name, target_environment, include_survey
         )
@@ -184,7 +189,7 @@ def generate_awx_project_from_cookbooks(
         )
 
         # Analyze all cookbooks
-        cookbooks_analysis = _analyze_cookbooks_directory(cookbooks_path)
+        cookbooks_analysis = _analyse_cookbooks_directory(cookbooks_path)
 
         # Generate project structure
         project_config = _generate_awx_project_config(project_name, scm_type, scm_url)
@@ -329,7 +334,7 @@ def convert_chef_deployment_to_ansible_strategy(
             )
 
         # Analyze Chef deployment pattern
-        pattern_analysis = _analyze_chef_deployment_pattern(cookbook)
+        pattern_analysis = _analyse_chef_deployment_pattern(cookbook)
 
         # Determine best strategy if auto-detect
         if deployment_pattern == "auto":
@@ -626,11 +631,11 @@ def generate_canary_deployment_strategy(
         )
 
 
-def analyze_chef_application_patterns(
+def analyse_chef_application_patterns(
     cookbook_path: str, application_type: str = "web_application"
 ) -> str:
     """
-    Analyze cookbook deployment patterns and recommend Ansible strategies.
+    Analyse cookbook deployment patterns and recommend Ansible strategies.
 
     Detects blue/green, canary, rolling, or custom deployment approaches.
     Application type helps tune recommendations for web/database/service workloads.
@@ -647,7 +652,7 @@ def analyze_chef_application_patterns(
             )
 
         # Analyze cookbook for application patterns
-        analysis = _analyze_application_cookbook(cookbook, application_type)
+        analysis = _analyse_application_cookbook(cookbook, application_type)
 
         return f"""# Chef Application Patterns Analysis
 # Cookbook: {cookbook.name}
@@ -685,9 +690,9 @@ def analyze_chef_application_patterns(
 # AWX Helper Functions
 
 
-def _analyze_recipes(cookbook_path: Path) -> list[dict[str, Any]]:
+def _analyse_recipes(cookbook_path: Path) -> list[dict[str, Any]]:
     """
-    Analyze recipes directory for AWX job steps.
+    Analyse recipes directory for AWX job steps.
 
     Args:
         cookbook_path: Path to cookbook root
@@ -710,11 +715,11 @@ def _analyze_recipes(cookbook_path: Path) -> list[dict[str, Any]]:
     return recipes
 
 
-def _analyze_attributes_for_survey(
+def _analyse_attributes_for_survey(
     cookbook_path: Path,
 ) -> tuple[dict[str, Any], list[dict[str, Any]]]:
     """
-    Analyze attributes directory for survey field generation.
+    Analyse attributes directory for survey field generation.
 
     Args:
         cookbook_path: Path to cookbook root
@@ -748,7 +753,7 @@ def _analyze_attributes_for_survey(
     return attributes, survey_fields
 
 
-def _analyze_metadata_dependencies(cookbook_path: Path) -> list[str]:
+def _analyse_metadata_dependencies(cookbook_path: Path) -> list[str]:
     """
     Extract cookbook dependencies from metadata.
 
@@ -795,9 +800,9 @@ def _collect_static_files(cookbook_path: Path) -> tuple[list[str], list[str]]:
     return templates, files
 
 
-def _analyze_cookbook_for_awx(cookbook_path: Path, cookbook_name: str) -> dict:
+def _analyse_cookbook_for_awx(cookbook_path: Path, cookbook_name: str) -> dict:
     """
-    Analyze Chef cookbook structure for AWX job template generation.
+    Analyse Chef cookbook structure for AWX job template generation.
 
     Orchestrates multiple analysis helpers to build comprehensive cookbook metadata.
 
@@ -810,9 +815,9 @@ def _analyze_cookbook_for_awx(cookbook_path: Path, cookbook_name: str) -> dict:
 
     """
     # Analyze each dimension independently
-    recipes = _analyze_recipes(cookbook_path)
-    attributes, survey_fields = _analyze_attributes_for_survey(cookbook_path)
-    dependencies = _analyze_metadata_dependencies(cookbook_path)
+    recipes = _analyse_recipes(cookbook_path)
+    attributes, survey_fields = _analyse_attributes_for_survey(cookbook_path)
+    dependencies = _analyse_metadata_dependencies(cookbook_path)
     templates, files = _collect_static_files(cookbook_path)
 
     # Assemble complete analysis
@@ -1155,8 +1160,8 @@ def _generate_survey_fields_from_attributes(attributes: dict) -> list:
     return survey_fields
 
 
-def _analyze_cookbooks_directory(cookbooks_path: Path) -> dict:
-    """Analyze entire cookbooks directory structure."""
+def _analyse_cookbooks_directory(cookbooks_path: Path) -> dict:
+    """Analyse entire cookbooks directory structure."""
     analysis: dict[str, Any] = {
         "total_cookbooks": 0,
         "cookbooks": {},
@@ -1172,7 +1177,7 @@ def _analyze_cookbooks_directory(cookbooks_path: Path) -> dict:
         cookbook_name = cookbook_dir.name
         analysis["total_cookbooks"] += 1
 
-        cookbook_analysis = _analyze_cookbook_for_awx(cookbook_dir, cookbook_name)
+        cookbook_analysis = _analyse_cookbook_for_awx(cookbook_dir, cookbook_name)
         analysis["cookbooks"][cookbook_name] = cookbook_analysis
 
         # Aggregate stats
@@ -1186,8 +1191,8 @@ def _analyze_cookbooks_directory(cookbooks_path: Path) -> dict:
 # Deployment Strategy Helper Functions
 
 
-def _analyze_chef_deployment_pattern(cookbook_path: Path) -> dict:
-    """Analyze Chef cookbook for deployment patterns."""
+def _analyse_chef_deployment_pattern(cookbook_path: Path) -> dict:
+    """Analyse Chef cookbook for deployment patterns."""
     analysis: dict[str, Any] = {
         "deployment_steps": [],
         "health_checks": [],
@@ -1496,17 +1501,60 @@ def _detect_patterns_from_content(content: str) -> list[str]:
     return patterns
 
 
-def _assess_complexity_from_resource_count(resource_count: int) -> tuple[str, str, str]:
-    """Assess complexity, effort, and risk based on resource count."""
+def _assess_complexity_from_resource_count(
+    resource_count: int,
+) -> tuple[ComplexityLevel, str, str]:
+    """
+    Assess complexity, effort estimate, and risk based on resource count.
+
+    Uses centralized metrics for consistent complexity categorization.
+
+    Args:
+        resource_count: Number of resources in cookbook
+
+    Returns:
+        Tuple of (complexity_level, effort_estimate_weeks, risk_level)
+
+    """
+    # Map resource count to complexity score (0-100 scale)
+    # 50+ resources = high complexity (70-100)
+    # 20-50 resources = medium complexity (30-69)
+    # <20 resources = low complexity (0-29)
     if resource_count > 50:
-        return "high", "4-6 weeks", "high"
-    elif resource_count < 20:
-        return "low", "1-2 weeks", "low"
-    return "medium", "2-3 weeks", "medium"
+        complexity_score = 80
+    elif resource_count > 30:
+        complexity_score = 50
+    elif resource_count >= 20:
+        complexity_score = 40
+    else:
+        complexity_score = 15
+
+    # Use centralized categorization
+    complexity_level = categorize_complexity(complexity_score)
+
+    # Estimate effort based on resource count and complexity
+    # Base: 0.2 days per resource (2.5 hours)
+    base_days = resource_count * 0.2
+    complexity_multiplier = 1 + (complexity_score / 100)
+    estimated_days = round(base_days * complexity_multiplier, 1)
+
+    # Create metrics object for consistent week calculation
+    metrics = EffortMetrics(estimated_days=estimated_days)
+    effort_estimate = metrics.estimated_weeks_range
+
+    # Risk mapping based on complexity level
+    if complexity_level == ComplexityLevel.HIGH:
+        risk_level = "high"
+    elif complexity_level == ComplexityLevel.MEDIUM:
+        risk_level = "medium"
+    else:
+        risk_level = "low"
 
+    return complexity_level, effort_estimate, risk_level
 
-def _analyze_application_cookbook(cookbook_path: Path, app_type: str) -> dict:
-    """Analyze Chef cookbook for application deployment patterns."""
+
+def _analyse_application_cookbook(cookbook_path: Path, app_type: str) -> dict:
+    """Analyse Chef cookbook for application deployment patterns."""
     analysis: dict[str, Any] = {
         "application_type": app_type,
         "deployment_patterns": [],
@@ -1536,10 +1584,14 @@ def _analyze_application_cookbook(cookbook_path: Path, app_type: str) -> dict:
                 # Silently skip malformed files
                 pass
 
-    # Assess complexity
+    # Assess complexity using centralized function
     resource_count = len(analysis["resources"])
-    complexity, effort, risk = _assess_complexity_from_resource_count(resource_count)
-    analysis["complexity"] = complexity
+    complexity_level, effort, risk = _assess_complexity_from_resource_count(
+        resource_count
+    )
+
+    # Convert complexity level enum to string for backward compatibility
+    analysis["complexity"] = complexity_level.value
     analysis["effort_estimate"] = effort
     analysis["risk_level"] = risk
 
@@ -1650,7 +1702,7 @@ def _format_deployment_patterns(analysis: dict) -> str:
 
 def _format_chef_resources_analysis(analysis: dict) -> str:
     """Format Chef resources analysis."""
-    # Check for new format first (from _analyze_application_cookbook)
+    # Check for new format first (from _analyse_application_cookbook)
     resources = analysis.get("resources", [])
     if resources:
         # Count resource types