"""
Gap Analysis Schema

Defines gaps (missing or incomplete specifications) found when analyzing
whether a declaration matches the actual project structure and inferred requirements.
"""

# ============================================================================
# Gap Types
# ============================================================================

schema MissingTaskservGap:
    """
    A required taskserv is missing from the declaration
    """
    taskserv_name: str
    reason: str               # Why this taskserv is needed
    required: bool
    suggested_version?: str


schema MissingFieldGap:
    """
    A configuration field is missing or incomplete
    """
    schema_name: str          # e.g., "TaskservRequirement"
    field_name: str           # e.g., "backup_strategy"
    reason: str
    suggested_value?: str


schema VersionMismatchGap:
    """
    Version is outdated or mismatched
    """
    taskserv_name: str
    current_version: str
    recommended_version: str
    reason: str


schema DependencyGap:
    """
    Taskserv is missing a dependency
    """
    taskserv_name: str
    depends_on: str           # Required taskserv name
    reason: str


# ============================================================================
# Severity and Priority
# ============================================================================

schema Gap:
    """
    A single gap with severity and suggested fix
    """
    kind: str                 # "missing_taskserv", "missing_field", etc.
    severity: "error" | "warning" | "info" = "warning"
    location?: str            # Where in declaration (e.g., "requirements[0]")
    message: str              # Human-readable description
    suggestion?: str          # How to fix it
    context?: {str: str}      # Additional context

    check:
        len(message) > 0, "Gap message required"


# ============================================================================
# Gap Analysis Report
# ============================================================================

schema GapAnalysisReport:
    """
    Complete gap analysis showing what's missing/incomplete
    """
    declaration_name: str
    declaration_version: str
    gaps: [Gap] = []
    total_errors: int = 0
    total_warnings: int = 0
    total_info: int = 0
    completeness_score: float  # 0.0 (empty) to 1.0 (complete)

    check:
        completeness_score >= 0.0 and completeness_score <= 1.0, \
            "Completeness score must be 0.0-1.0"


# ============================================================================
# Gap Fixer (Suggested fixes)
# ============================================================================

schema GapFix:
    """
    A proposed fix for a gap
    """
    gap_id: str
    action: "add" | "update" | "remove" | "skip" = "add"
    value?: str               # New value to set
    reasoning: str            # Why this fix is appropriate

    check:
        len(gap_id) > 0, "Gap ID required"


schema GapFixPlan:
    """
    Plan for fixing multiple gaps
    """
    declaration_name: str
    fixes: [GapFix] = []
    estimated_changes: int
    preservation_strategy?: str  # How to preserve customizations