workspace-v1/devtools/scripts/validation/validate-docs-structure.sh

#!/bin/bash
# =============================================================================
# validate-docs-structure.sh
# =============================================================================
# Script de validacion de estructura de documentacion para proyectos NEXUS
#
# Version: 1.0.0
# Sistema: NEXUS v3.4 + SIMCO
# EPIC: EPIC-002 - Documentacion en Todos los Niveles
# TASK: TASK-002-02
#
# Uso: ./validate-docs-structure.sh /path/to/project
#
# Exit codes:
#   0 = Todas las validaciones pasaron (puede haber warnings)
#   1 = Al menos una validacion critica fallo
# =============================================================================

set -e

# Colores para output
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
NC='\033[0m' # No Color

# Contadores
ERRORS=0
WARNINGS=0
PASSED=0

# Funcion para imprimir resultado OK
print_ok() {
    echo -e "${GREEN}[OK]${NC} $1"
    ((PASSED++))
}

# Funcion para imprimir warning
print_warn() {
    echo -e "${YELLOW}[WARN]${NC} $1"
    ((WARNINGS++))
}

# Funcion para imprimir error
print_error() {
    echo -e "${RED}[ERROR]${NC} $1"
    ((ERRORS++))
}

# Funcion para imprimir info
print_info() {
    echo -e "${BLUE}[INFO]${NC} $1"
}

# Funcion para contar archivos en directorio
count_files() {
    local dir="$1"
    if [ -d "$dir" ]; then
        find "$dir" -maxdepth 1 -type f | wc -l
    else
        echo 0
    fi
}

# Validar argumentos
if [ -z "$1" ]; then
    echo "Uso: $0 /path/to/project"
    echo ""
    echo "Ejemplo: $0 /home/isem/workspace-v1/projects/gamilit"
    exit 1
fi

PROJECT_PATH="$1"
DOCS_PATH="${PROJECT_PATH}/docs"

# Verificar que el proyecto existe
if [ ! -d "$PROJECT_PATH" ]; then
    print_error "El directorio del proyecto no existe: $PROJECT_PATH"
    exit 1
fi

echo ""
echo "=============================================="
echo " Validacion de Estructura de Documentacion"
echo "=============================================="
echo ""
echo "Proyecto: $PROJECT_PATH"
echo "Fecha: $(date '+%Y-%m-%d %H:%M:%S')"
echo ""

# =============================================================================
# VALIDACIONES CRITICAS (generan ERROR)
# =============================================================================

echo "--- Validaciones Criticas ---"
echo ""

# 1. Verificar que docs/ existe
if [ -d "$DOCS_PATH" ]; then
    print_ok "Directorio docs/ existe"
else
    print_error "Directorio docs/ NO existe"
    echo ""
    echo "=== Resumen ==="
    echo "El proyecto no tiene directorio docs/. Crear con:"
    echo "  mkdir -p ${DOCS_PATH}"
    exit 1
fi

# 2. Verificar README.md en docs/
if [ -f "${DOCS_PATH}/README.md" ]; then
    print_ok "docs/README.md existe"
else
    print_error "docs/README.md NO existe"
fi

# 3. Verificar _MAP.md en docs/
if [ -f "${DOCS_PATH}/_MAP.md" ]; then
    print_ok "docs/_MAP.md existe"
else
    print_error "docs/_MAP.md NO existe (indice principal)"
fi

echo ""

# =============================================================================
# VALIDACIONES DE ESTRUCTURA RECOMENDADA (generan WARNING)
# =============================================================================

echo "--- Estructura Recomendada ---"
echo ""

# Directorios estandar recomendados
RECOMMENDED_DIRS=(
    "00-vision-general"
    "01-arquitectura"
    "02-definicion-modulos"
    "90-transversal"
    "97-adr"
)

for dir in "${RECOMMENDED_DIRS[@]}"; do
    dir_path="${DOCS_PATH}/${dir}"
    if [ -d "$dir_path" ]; then
        print_ok "docs/${dir}/ existe"

        # Verificar _MAP.md dentro del directorio
        if [ -f "${dir_path}/_MAP.md" ]; then
            print_ok "docs/${dir}/_MAP.md existe"
        else
            file_count=$(count_files "$dir_path")
            if [ "$file_count" -gt 2 ]; then
                print_warn "docs/${dir}/_MAP.md NO existe (directorio tiene $file_count archivos)"
            else
                print_info "docs/${dir}/_MAP.md no existe (directorio tiene pocos archivos)"
            fi
        fi
    else
        print_info "docs/${dir}/ no existe (opcional)"
    fi
done

echo ""

# =============================================================================
# VALIDACION RECURSIVA DE _MAP.md
# =============================================================================

echo "--- Validacion Recursiva de Indices ---"
echo ""

# Buscar directorios con mas de 2 archivos que no tengan _MAP.md
while IFS= read -r -d '' subdir; do
    # Excluir el directorio docs/ mismo
    if [ "$subdir" != "$DOCS_PATH" ]; then
        file_count=$(count_files "$subdir")
        subdir_name="${subdir#$DOCS_PATH/}"

        if [ "$file_count" -gt 2 ]; then
            if [ ! -f "${subdir}/_MAP.md" ]; then
                print_warn "docs/${subdir_name}/ tiene $file_count archivos pero NO tiene _MAP.md"
            else
                print_ok "docs/${subdir_name}/_MAP.md existe ($file_count archivos)"
            fi
        fi
    fi
done < <(find "$DOCS_PATH" -type d -print0 2>/dev/null)

echo ""

# =============================================================================
# VALIDACIONES ADICIONALES
# =============================================================================

echo "--- Validaciones Adicionales ---"
echo ""

# Verificar si hay archivos huerfanos (no .md) en docs/
orphan_count=$(find "$DOCS_PATH" -type f ! -name "*.md" ! -name "*.yml" ! -name "*.yaml" ! -name ".gitkeep" 2>/dev/null | wc -l)
if [ "$orphan_count" -gt 0 ]; then
    print_warn "Hay $orphan_count archivos no-markdown en docs/"
    find "$DOCS_PATH" -type f ! -name "*.md" ! -name "*.yml" ! -name "*.yaml" ! -name ".gitkeep" 2>/dev/null | head -5 | while read file; do
        echo "         - ${file#$DOCS_PATH/}"
    done
else
    print_ok "Todos los archivos en docs/ son markdown o yaml"
fi

# Verificar si hay directorios vacios
empty_dirs=$(find "$DOCS_PATH" -type d -empty 2>/dev/null | wc -l)
if [ "$empty_dirs" -gt 0 ]; then
    print_warn "Hay $empty_dirs directorios vacios en docs/"
else
    print_ok "No hay directorios vacios"
fi

echo ""

# =============================================================================
# RESUMEN
# =============================================================================

echo "=============================================="
echo " Resumen"
echo "=============================================="
echo ""
echo "Validaciones pasadas: $PASSED"
echo "Warnings: $WARNINGS"
echo "Errores: $ERRORS"
echo ""

# Determinar estado final
if [ "$ERRORS" -gt 0 ]; then
    echo -e "${RED}Estado: FAILED${NC}"
    echo ""
    echo "Acciones requeridas:"
    if [ ! -f "${DOCS_PATH}/README.md" ]; then
        echo "  - Crear docs/README.md con overview del proyecto"
    fi
    if [ ! -f "${DOCS_PATH}/_MAP.md" ]; then
        echo "  - Crear docs/_MAP.md como indice principal"
        echo "    (usar TEMPLATE-MAP.md como base)"
    fi
    exit 1
elif [ "$WARNINGS" -gt 0 ]; then
    echo -e "${YELLOW}Estado: PASS (con warnings)${NC}"
    echo ""
    echo "Recomendaciones:"
    echo "  - Revisar warnings y crear _MAP.md donde sea necesario"
    echo "  - Usar TEMPLATE-MAP.md como base"
    exit 0
else
    echo -e "${GREEN}Estado: PASS${NC}"
    exit 0
fi