#!/usr/bin/env bash

#
# Analyze Documentation Coverage
#
# Compares extracted data with existing Documentation/ to identify:
# - Missing documentation
# - Outdated documentation
# - Inconsistencies
#
# Generates: Documentation/ANALYSIS.md
#

set -e

# Colors
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
NC='\033[0m'

# Configuration
PROJECT_DIR="$(pwd)"
DATA_DIR="${PROJECT_DIR}/.claude/docs-extraction/data"
DOC_DIR="${PROJECT_DIR}/Documentation"
ANALYSIS_FILE="${DOC_DIR}/ANALYSIS.md"

# TYPO3 Official Architecture Weights (from typo3-extension-architecture.md)
# BaseWeight for gap priority calculation: Priority = BaseWeight * Severity * UserImpact

# File Type Weights
declare -A BASE_WEIGHTS=(
    ["ext_conf_template"]=10      # User-facing configuration
    ["controller"]=9              # Core application logic
    ["model"]=9                   # Domain entities
    ["tca"]=8                     # Database configuration
    ["ext_emconf"]=8             # Extension metadata
    ["service"]=7                # Business logic
    ["repository"]=6             # Data access
    ["viewhelper"]=5             # Template helpers
    ["utility"]=4                # Helper functions
    ["other"]=3                  # Miscellaneous
)

# Severity Multipliers
SEVERITY_MISSING=3               # Completely undocumented
SEVERITY_OUTDATED=2              # Exists but wrong/incomplete
SEVERITY_INCOMPLETE=1            # Partial documentation

# User Impact Multipliers
IMPACT_USER=3                    # End users, editors
IMPACT_INTEGRATOR=2              # TypoScript, TSconfig
IMPACT_DEVELOPER=1               # API, internal code

# Function to calculate gap priority
# Usage: calculate_priority <base_weight> <severity> <impact>
calculate_priority() {
    local base_weight=$1
    local severity=$2
    local impact=$3
    echo $((base_weight * severity * impact))
}

# Function to determine class type from file path
get_class_type() {
    local file_path=$1
    if [[ "$file_path" == *"Controller"* ]]; then
        echo "controller"
    elif [[ "$file_path" == *"Domain/Model"* ]]; then
        echo "model"
    elif [[ "$file_path" == *"Domain/Repository"* ]]; then
        echo "repository"
    elif [[ "$file_path" == *"Service"* ]]; then
        echo "service"
    elif [[ "$file_path" == *"ViewHelper"* ]]; then
        echo "viewhelper"
    elif [[ "$file_path" == *"Utility"* ]]; then
        echo "utility"
    else
        echo "other"
    fi
}

echo -e "${GREEN}=== Documentation Coverage Analysis ===${NC}"
echo

# Check if Documentation/ exists
if [ ! -d "${DOC_DIR}" ]; then
    echo -e "${YELLOW}No Documentation/ directory found${NC}"
    echo "Run this from a TYPO3 extension root directory"
    exit 1
fi

# Check if extraction data exists
if [ ! -d "${DATA_DIR}" ]; then
    echo -e "${YELLOW}No extraction data found${NC}"
    echo "Run scripts/extract-all.sh first"
    exit 1
fi

echo "Project: ${PROJECT_DIR}"
echo "Documentation: ${DOC_DIR}"
echo "Extraction Data: ${DATA_DIR}"
echo

# Start analysis report
cat > "${ANALYSIS_FILE}" <<'EOF'
# Documentation Analysis Report

**Generated:** $(date -u +"%Y-%m-%d %H:%M:%S UTC")

## Summary

This report compares extracted project data with existing documentation to identify gaps and inconsistencies.

EOF

# Replace the date placeholder
sed -i "s/\$(date -u +\"%Y-%m-%d %H:%M:%S UTC\")/$(date -u +"%Y-%m-%d %H:%M:%S UTC")/g" "${ANALYSIS_FILE}"

# Analyze PHP APIs
echo -e "${BLUE}Analyzing PHP APIs...${NC}"

if [ -f "${DATA_DIR}/php_apis.json" ]; then
    total_classes=$(jq '.classes | length' "${DATA_DIR}/php_apis.json" 2>/dev/null || echo 0)

    # Count documented classes (look for .rst files in API/ or Developer/)
    documented_classes=0
    if [ -d "${DOC_DIR}/API" ] || [ -d "${DOC_DIR}/Developer" ]; then
        documented_classes=$(find "${DOC_DIR}" -name "*.rst" -type f -exec grep -l ".. php:class::" {} \; 2>/dev/null | wc -l)
    fi

    missing_classes=$((total_classes - documented_classes))

    cat >> "${ANALYSIS_FILE}" <<EOF

### PHP Classes

- **Total Classes:** ${total_classes}
- **Documented Classes:** ${documented_classes}
- **Missing Documentation:** ${missing_classes}

EOF

    if [ $missing_classes -gt 0 ]; then
        echo "## Missing Class Documentation" >> "${ANALYSIS_FILE}"
        echo >> "${ANALYSIS_FILE}"
        echo "Classes listed by **priority score** (Priority = BaseWeight × Severity × Impact)" >> "${ANALYSIS_FILE}"
        echo >> "${ANALYSIS_FILE}"

        # Create temporary file with priority calculations
        temp_classes=$(mktemp)

        # Extract classes with priority calculations
        jq -r '.classes[] | @json' "${DATA_DIR}/php_apis.json" 2>/dev/null | while IFS= read -r class_json; do
            file_path=$(echo "$class_json" | jq -r '.file')
            class_type=$(get_class_type "$file_path")
            base_weight=${BASE_WEIGHTS[$class_type]}
            priority=$(calculate_priority $base_weight $SEVERITY_MISSING $IMPACT_DEVELOPER)

            echo "$priority|$class_json" >> "$temp_classes"
        done

        # Sort by priority (descending) and output formatted
        sort -t'|' -k1 -rn "$temp_classes" 2>/dev/null | while IFS='|' read -r priority class_json; do
            namespace=$(echo "$class_json" | jq -r '.namespace')
            name=$(echo "$class_json" | jq -r '.name')
            file=$(echo "$class_json" | jq -r '.file')
            desc=$(echo "$class_json" | jq -r '.description')

            cat >> "${ANALYSIS_FILE}" <<CLASSEOF

### ${namespace}\\${name}

- **Priority Score:** ${priority} ⚠️
- **File:** \`${file}\`
- **Type:** ${class_type}
- **Description:** ${desc}
- **Suggested Location:** \`Documentation/API/${name}.rst\`

CLASSEOF
        done

        rm -f "$temp_classes"
    fi

    echo "  Classes: ${documented_classes}/${total_classes} documented"
fi

# Analyze Configuration Options
echo -e "${BLUE}Analyzing Configuration Options...${NC}"

if [ -f "${DATA_DIR}/config_options.json" ]; then
    total_options=$(jq '.config_options | length' "${DATA_DIR}/config_options.json" 2>/dev/null || echo 0)

    # Count documented confval directives
    documented_options=0
    if find "${DOC_DIR}" -name "*.rst" -type f -exec grep -q ".. confval::" {} \; 2>/dev/null; then
        documented_options=$(find "${DOC_DIR}" -name "*.rst" -type f -exec grep ".. confval::" {} \; 2>/dev/null | wc -l)
    fi

    missing_options=$((total_options - documented_options))

    cat >> "${ANALYSIS_FILE}" <<EOF

### Configuration Options

- **Total Options:** ${total_options}
- **Documented Options:** ${documented_options}
- **Missing Documentation:** ${missing_options}

EOF

    if [ $missing_options -gt 0 ]; then
        echo "## Missing Configuration Documentation" >> "${ANALYSIS_FILE}"
        echo >> "${ANALYSIS_FILE}"
        echo "Configuration options listed by **priority score** (Priority = BaseWeight × Severity × Impact)" >> "${ANALYSIS_FILE}"
        echo >> "${ANALYSIS_FILE}"

        # Configuration options are user-facing (HIGH priority)
        base_weight=${BASE_WEIGHTS["ext_conf_template"]}
        priority=$(calculate_priority $base_weight $SEVERITY_MISSING $IMPACT_USER)

        # List undocumented options with priority
        jq -r --arg priority "$priority" '.config_options[] |
               "### " + .key + "\n\n" +
               "- **Priority Score:** " + $priority + " 🚨\n" +
               "- **Type:** " + .type + "\n" +
               "- **Default:** `" + .default + "`\n" +
               "- **Description:** " + .description + "\n" +
               (if .security_warning then "- **⚠️ Security Warning:** " + .security_warning + "\n" else "" end) +
               "- **Suggested Location:** `Documentation/Integration/Configuration.rst`\n\n" +
               "**Template:**\n\n```rst\n" +
               ".. confval:: " + .key + "\n\n" +
               "   :type: " + .type + "\n" +
               "   :Default: " + .default + "\n" +
               "   :Path: $GLOBALS['"'"'TYPO3_CONF_VARS'"'"']['"'"'EXTENSIONS'"'"']['"'"'ext_key'"'"']['"'"'" + .key + "'"'"']\n\n" +
               "   " + .description + "\n" +
               (if .security_warning then "\n   .. warning::\n      " + .security_warning + "\n" else "" end) +
               "```\n"' \
               "${DATA_DIR}/config_options.json" 2>/dev/null >> "${ANALYSIS_FILE}" || true
    fi

    echo "  Options: ${documented_options}/${total_options} documented"
fi

# Check Extension Metadata
echo -e "${BLUE}Analyzing Extension Metadata...${NC}"

if [ -f "${DATA_DIR}/extension_meta.json" ]; then
    ext_version=$(jq -r '.metadata.version // "unknown"' "${DATA_DIR}/extension_meta.json" 2>/dev/null)
    ext_title=$(jq -r '.metadata.title // "unknown"' "${DATA_DIR}/extension_meta.json" 2>/dev/null)

    cat >> "${ANALYSIS_FILE}" <<EOF

### Extension Metadata

- **Title:** ${ext_title}
- **Version:** ${ext_version}
- **Location:** Check `Documentation/Index.rst` and `Documentation/Settings.cfg`

**Recommended Actions:**
- Verify version number in Settings.cfg matches ext_emconf.php
- Ensure extension title is documented in Index.rst
- Check TYPO3/PHP version constraints are in Installation requirements

EOF

    echo "  Extension: ${ext_title} v${ext_version}"
fi

# Priority Score Explanation
cat >> "${ANALYSIS_FILE}" <<'EOF'

## Priority Score System

Documentation gaps are ranked using **TYPO3 Official Architecture Weighting**:

```
Priority = BaseWeight × Severity × UserImpact
```

### Base Weights (by file type)
- **Configuration (ext_conf_template.txt):** 10 - User-facing settings
- **Controllers:** 9 - Core application logic
- **Models:** 9 - Domain entities
- **TCA:** 8 - Database configuration
- **Services:** 7 - Business logic
- **Repositories:** 6 - Data access
- **ViewHelpers:** 5 - Template helpers
- **Utilities:** 4 - Helper functions

### Severity Multipliers
- **Missing (3):** No documentation exists
- **Outdated (2):** Documentation exists but incorrect
- **Incomplete (1):** Partial documentation

### User Impact Multipliers
- **End Users (3):** Editors, content creators
- **Integrators (2):** TypoScript, TSconfig users
- **Developers (1):** PHP API users

### Example Calculations
- Missing config option: `10 × 3 × 3 = 90` 🚨 (HIGHEST)
- Missing controller: `9 × 3 × 1 = 27` ⚠️
- Missing utility: `4 × 3 × 1 = 12`

**Reference:** See `references/typo3-extension-architecture.md`

## Recommendations

Items above are **already sorted by priority score**. Focus on highest scores first.

### Immediate Actions (Priority Score ≥50)

1. **Document configuration options** (Score: 90) - Critical for users
2. **Document controllers and models** (Score: 27) - Essential for developers

### Quality Improvements

1. Run validation: `scripts/validate_docs.sh`
2. Render locally: `scripts/render_docs.sh`
3. Fix any rendering warnings or broken cross-references

### Enhancements

1. Add usage examples for all configuration options
2. Add code examples for all API methods
3. Consider adding screenshots for user-facing features

## Next Steps

1. **Review this analysis** - Focus on highest priority scores first
2. **Manual documentation** - Create missing RST files using provided templates
3. **Validate** - `scripts/validate_docs.sh`
4. **Render** - `scripts/render_docs.sh`
5. **Commit** - Add new documentation to version control

---

**Analysis Date:** $(date -u +"%Y-%m-%d %H:%M:%S UTC")
**Extraction Data:** See `.claude/docs-extraction/data/`
**Weighting Source:** TYPO3 Official Extension Architecture

EOF

# Replace date placeholder again
sed -i "s/\$(date -u +\"%Y-%m-%d %H:%M:%S UTC\")/$(date -u +"%Y-%m-%d %H:%M:%S UTC")/g" "${ANALYSIS_FILE}"

echo
echo -e "${GREEN}=== Analysis Complete ===${NC}"
echo
echo "Report generated: ${ANALYSIS_FILE}"
echo
echo -e "${YELLOW}Review the analysis report for documentation gaps and recommendations.${NC}"
echo