Skip to content

Latest commit

 

History

History
284 lines (225 loc) · 9.03 KB

README.md

File metadata and controls

284 lines (225 loc) · 9.03 KB
Raw

Repo Code Empathizer 🔍

📋 Descripción

Repo Code Empathizer es una herramienta de análisis estático que evalúa la "empatía" del código en repositorios. Analiza y compara diferentes métricas de calidad para ayudar a los desarrolladores a crear código más mantenible y comprensible.

✨ Características principales

🔄 Análisis comparativo

  • Compara dos repositorios de GitHub simultáneamente
  • Genera puntuaciones detalladas por categoría
  • Identifica áreas de mejora específicas

📊 Formatos de exportación

  • TXT: Reportes simples y concisos
  • JSON: Datos estructurados para análisis posterior
  • HTML: Visualización interactiva detallada
  • Multi-formato: Exportación simultánea en todos los formatos

🎯 Categorías de análisis

  1. 📝 Nombres Descriptivos

    • Evaluación de claridad
    • Consistencia en nomenclatura

  2. 🔄 Complejidad

    • Análisis ciclomático
    • Niveles de anidación

  3. 📦 Modularidad

    • Cohesión y acoplamiento
    • Organización del código

  4. 📚 Documentación

    • Cobertura de docstrings
    • Calidad de comentarios

  5. ⚠️ Manejo de Errores

    • Tratamiento de excepciones
    • Robustez del código

  6. 🧪 Pruebas

    • Cobertura de tests
    • Calidad de assertions

  7. 🎨 Estilo

    • Consistencia de formato

  8. 🔒 Seguridad

    • Validación de entradas
    • Prácticas seguras

📊 Ejemplos de Análisis

Reporte HTML

Ejemplo de análisis

📊 Métricas y cálculo de empatía

Grupos de KPIs

1. 📝 Nombres

KPI Descripción Cálculo
Descriptividad Claridad de identificadores Análisis de nombres (vars, funcs, clases)
Consistencia Adherencia a convenciones % nombres que siguen estándares

2. 📚 Documentación

KPI Descripción Cálculo
Cobertura docstrings % código documentado funciones_con_docstring / total_funciones
Calidad docs Completitud de documentación Bonus por params, returns y ejemplos

3. 🧩 Modularidad

KPI Descripción Cálculo
Funciones/archivo Densidad de funciones total_funciones / total_archivos
Clases/archivo Densidad de clases total_clases / total_archivos
Cohesión Uso compartido de atributos % métodos que comparten atributos
Acoplamiento Dependencias externas Penalización por imports y vars globales

4. 🔄 Complejidad

KPI Descripción Cálculo
Ciclomática Caminos de ejecución +1 por cada: if, while, for, and, or
Anidación Profundidad de estructuras Penalización por niveles > 3
Longitud funciones Tamaño de funciones Penalización por > 20 líneas

5. ⚠️ Manejo de Errores

KPI Descripción Cálculo
Cobertura Uso de try-except funcs_con_try_except / total_funcs
Especificidad Excepciones específicas Penalización por except genéricos
Densidad Bloques try-except total_try_except / total_funcs

6. 🧪 Pruebas

KPI Descripción Cálculo
Cobertura Funciones con tests funcs_test / total_funcs
Densidad asserts Aserciones por test total_asserts / total_funcs_test
Funciones test Total de pruebas Conteo de funciones test_*

7. 🔒 Seguridad

KPI Descripción Cálculo
Validación entradas Verificación de datos funcs_con_validacion / total_funcs
Funciones peligrosas Uso de eval, exec, etc. Penalización por uso
Total validaciones Cantidad de checks Suma de todas las validaciones

8. 📏 Consistencia

KPI Descripción Cálculo
Nombres Convenciones de naming nombres_consistentes / total_nombres
Espaciado Indentación y formato Análisis con pylint
Longitud líneas Límite de caracteres % líneas < 80 caracteres

🎯 Cálculo de empatía

La puntuación final de empatía se calcula como un promedio ponderado de todas las categorías:

empatia = (
    nombres * 0.15 +
    documentacion * 0.15 +
    modularidad * 0.15 +
    complejidad * 0.15 +
    manejo_errores * 0.10 +
    pruebas * 0.10 +
    seguridad * 0.10 +
    consistencia * 0.10
)

Cada categoría se evalúa en una escala de 0 a 1, donde:

  • 0.0-0.3: Necesita mejora significativa
  • 0.3-0.6: Cumple estándares básicos
  • 0.6-0.8: Buenas prácticas
  • 0.8-1.0: Excelente empatía

📊 Resultados de análisis

Ejemplo de métricas reales

{
  "nombres": {
    "descriptividad": 0.81          // Qué tan descriptivos son los nombres (0-1)
  },
  "documentacion": {
    "cobertura_docstrings": 0.25    // % de código documentado
  },
  "modularidad": {
    "funciones_por_archivo": 2.6,    // Promedio de funciones/archivo
    "clases_por_archivo": 0.0,       // Promedio de clases/archivo
    "cohesion_promedio": 0.0,        // Qué tan cohesionadas están las clases
    "acoplamiento_promedio": 0.4     // Nivel de dependencias entre módulos
  },
  "complejidad": {
    "complejidad_ciclomatica": 0.58, // Complejidad del código (mejor cerca de 1)
    "max_nivel_anidacion": 0.0,      // Profundidad máxima de anidación
    "longitud_promedio_funciones": 0.85 // Tamaño apropiado de funciones
  },
  "manejo_errores": {
    "cobertura_manejo_errores": 0.0,   // % código con manejo de errores
    "especificidad_excepciones": 0.0,   // Uso de excepciones específicas
    "densidad_try_except": 0.0          // Cantidad de bloques try-except
  },
  "pruebas": {
    "cobertura_pruebas": 0.0,          // % código cubierto por tests
    "densidad_asserts": 0.0,           // Cantidad de aserciones por test
    "funciones_test": 0.0              // Número de funciones de prueba
  },
  "seguridad": {
    "validacion_entradas": 0.0,        // Validación de inputs
    "uso_funciones_peligrosas": 1.2,   // Evita funciones inseguras
    "total_validaciones": 0.0          // Total de validaciones implementadas
  },
  "consistencia_estilo": {
    "consistencia_nombres": 0.67,      // Adherencia a convenciones de nombres
    "espaciado_consistente": 0.38,     // Formato consistente
    "longitud_lineas_consistente": 0.77 // Líneas de longitud apropiada
  }
}

📈 Interpretación de resultados

Escala de evaluación

  • 🔴 0.0-0.3: Necesita mejora urgente
  • 🟡 0.3-0.6: Cumple estándares mínimos
  • 🟢 0.6-0.8: Buenas prácticas
  • 🌟 0.8-1.0: Excelente implementación

Puntos destacados

  • Nombres: Excelente descriptividad (0.81)
  • Documentación: Necesita mejora significativa (0.25)
  • Modularidad: Buen balance de funciones por archivo (2.6)
  • Complejidad: Mantenible y legible (0.58)
  • Seguridad: Excelente evitación de funciones peligrosas (1.2)
  • Consistencia: Buena adherencia a estándares de código (0.77)

Áreas de mejora

  1. 📚 Aumentar cobertura de documentación
  2. ⚠️ Implementar manejo de errores
  3. 🧪 Añadir pruebas unitarias
  4. 🔒 Mejorar validación de entradas

🎯 Puntuación final de empatía

La puntuación se calcula ponderando cada categoría:

empatia_final = (
    nombres * 0.15 +              # 0.81 * 0.15 = 0.122
    documentacion * 0.15 +        # 0.25 * 0.15 = 0.038
    modularidad * 0.15 +          # 0.40 * 0.15 = 0.060
    complejidad * 0.15 +          # 0.58 * 0.15 = 0.087
    manejo_errores * 0.10 +       # 0.00 * 0.10 = 0.000
    pruebas * 0.10 +              # 0.00 * 0.10 = 0.000
    seguridad * 0.10 +            # 1.20 * 0.10 = 0.120
    consistencia * 0.10           # 0.77 * 0.10 = 0.077
)                                 # Total = 0.504 (Cumple estándares básicos)

🚀 Inicio Rápido

Prerrequisitos

  • Python 3.8+
  • Git
  • Token de GitHub con permisos de lectura

Instalación

# Clonar repositorio
git clone https://github.com/686f6c61/code-empathizer.git
cd code-empathizer

# Configurar entorno virtual
python3 -m venv venv
source venv/bin/activate  # Linux/Mac
.\venv\Scripts\activate   # Windows

# Instalar dependencias
pip install -r requirements.txt

# Configurar token
cp .env.example .env
# Editar .env y añadir: GITHUB_TOKEN=tu_token_aquí

Uso Básico

python3 src/main.py

📁 Estructura del Proyecto

code-empathizer/
├── src/
│   ├── exporter/           # Carpeta de informes en TXT,JSON y HTML  
│   ├── main.py             # Punto de entrada
│   ├── github_utils.py     # Utilidades GitHub
│   ├── analyzers.py        # Analizadores
│   └── exporters.py        # Exportadores
├── REPO.txt/               # Repositorios para seleccionar
├── requirements.txt        # Dependencias
└── .env                    # Configuración

📜 Licencia

Distribuido bajo la Licencia MIT. Ver LICENSE para más información.

👥 Autores

  • @686f6c61 - Desarrollo inicial - GitHub