Motor de puntuación

Raigal asigna a cada repositorio una nota de calidad de 0 a 100. En lugar de limitarse a contar problemas brutos, mide la densidad de incidencias respecto al volumen de archivos. Así se evita que un proyecto grande suspenda únicamente por tener más código.

Fórmula de puntuación

Raigal evalúa las incidencias detectadas por sus seis motores mediante una escala logarítmica normalizada por densidad:

Densidad de deducción = (Suma de deducciones acotadas) / (Archivos fuente efectivos + S)

Puntuación = max(0, redondear(100 - (100 * ln(1 + 5 * Densidad de deducción)) / ln(101 + 5 * Densidad de deducción)))

Donde:

Constante de suavizado (S): Por defecto vale 5 en la configuración (con reserva interna de 10). Evita que un aviso puntual en un proyecto de dos archivos hunda la nota.
Escala de densidad: Multiplicador de 5.0 aplicado sobre la densidad de deducción.
Archivos fuente efectivos: Recuento de archivos de código y pruebas analizados (o archivos cambiados en escaneos de pull requests).

Multiplicadores de severidad y peso de motores

Cada aviso detectado genera una penalización base según su severidad y el motor de procedencia:

Deducción base = Multiplicador de severidad * Peso del motor * Multiplicador de nivel

Multiplicadores de severidad

error: 3.0 (provoca código de salida 1 de inmediato en CI)
warning: 1.0
info: 0.25

Peso de los motores

security: 1.5 (secretos en código, inyecciones, llamadas inseguras, dependencias vulnerables)
architecture: 1.0 (acoplamiento entre capas, importaciones circulares)
ai-slop: 1.0 (excepciones silenciadas, comentarios obvios, aserciones de tipo laxas)
code-quality: 0.8 (código muerto, funciones demasiado complejas, exceso de parámetros)
lint: 0.6 (Oxlint, Ruff, Clippy, Roslynator)
format: 0.3 (espacios en blanco, sangrado, orden de importaciones)

Topes dinámicos por regla

Para evitar que problemas menores repetidos (como 500 comas finales) oculten fallos de seguridad o suspendan un proyecto grande, las reglas se dividen en niveles con topes automáticos:

Nivel de impacto	Multiplicador	Tope base	Ejemplos habituales
`strict`	`1.0x`	Sin tope (`maxPerRule`)	Errores de sintaxis, secretos expuestos, promesas sin gestionar
`standard`	`1.0x`	Sin tope (`maxPerRule`)	Reglas estándar de linter y avisos de compilador
`maintainability`	`0.75x`	24	Complejidad ciclomática, funciones demasiado largas
`mechanical`	`0.5x`	16	Importaciones huérfanas, variables sin referencia
`style`	`0.5x`	8	Discrepancias de formato y espaciado
`advisory`	`0.25x`	8	Avisos informativos, documentación faltante

Escalado según el tamaño del repositorio

El tope máximo de penalización de cada regla escala con el número de archivos:

Escala de tope = max(1, Archivos fuente efectivos / 10)

Tope efectivo = min(maxPerRule, Tope del nivel) * Escala de tope

Ejemplos prácticos

Ejemplo 1: Microservicio (10 archivos, 1 advertencia)

Incidencia: 1 ai-slop/swallowed-exception (warning, severidad 1.0, motor 1.0, nivel strict 1.0).
Cálculo:

Deducción = 1.0
Densidad = 1.0 / (10 + 5) = 1.0 / 15 ≈ 0.0667
Densidad escalada = 0.0667 * 5.0 = 0.3333
Puntuación = 100 - (100 * ln(1.3333) / ln(101.3333)) ≈ 100 - 6.23 = 94 (Healthy)

Ejemplo 2: Monolito (200 archivos, 500 avisos de formato)

Incidencias: 500 comas finales omitidas (format/trailing-comma, info 0.25, motor 0.3, nivel style 0.5, tope 8).
Cálculo:

Deducciones brutas = 500 * 0.25 * 0.3 * 0.5 = 18.75
Escala de tope = 200 / 10 = 20
Tope efectivo = 8 * 20 = 160
Deducciones acotadas = min(18.75, 160) = 18.75
Densidad = 18.75 / (200 + 5) = 18.75 / 205 ≈ 0.0915
Densidad escalada = 0.0915 * 5.0 = 0.4573
Puntuación = 100 - (100 * ln(1.4573) / ln(101.4573)) ≈ 100 - 8.15 = 92 (Healthy)

Umbrales y bandas de estado

Raigal utiliza exclusivamente notas numéricas de 0 a 100. No se emplean letras (A - F).

Etiquetas en la CLI

Al ejecutar raigal scan o raigal ci, la terminal muestra el estado según los límites configurados:

Rango de nota	Etiqueta en CLI	Salida en CI
`75 - 100`	`Healthy`	`0` (Aprobado)
`50 - 74`	`Needs Work`	`0` (o `1` si cae por debajo de `ci.failBelow`)
`< 50`	`Critical`	`1` (Falla el control de calidad)

En CI, raigal ci devuelve código de salida 1 si la nota es menor que ci.failBelow (por defecto: 70) o si se detecta algún error.

Bandas de salud en el panel web

La interfaz de Raigal Cloud (app.raigal.dev) agrupa los proyectos en cuatro bandas visuales:

Rango de nota	Banda en el panel	Color
`90 - 100`	`Excellent`	Verde lima
`75 - 89`	`Good / Healthy`	Verde esmeralda
`50 - 74`	`Needs Work`	Ámbar / amarillo
`< 50`	`Critical`	Rojo

Veredictos del control de calidad (3 estados)

Las comprobaciones en pull requests devuelven uno de tres veredictos:

Veredicto	Criterio	Resultado en GitHub
`PASSED`	Nota >= 70 (o `ci.failBelow`), 0 errores, 0 advertencias	`success` (Aprobado limpio)
`PASSED (WITH WARNINGS)`	Nota >= 70, 0 errores, advertencias presentes	`neutral` (Aprobado informativo, no bloquea el merge)
`FAILED / BLOCKED`	Nota < 70, código de salida distinto de 0 o errores presentes	`failure` (Bloquea la fusión)

Primeros pasos

Conceptos clave

Referencia de la CLI

Automatización y CI/CD

Plataforma cloud

Motor de puntuación

Fórmula de puntuación

Multiplicadores de severidad y peso de motores

Multiplicadores de severidad

Peso de los motores

Topes dinámicos por regla

Escalado según el tamaño del repositorio

Ejemplos prácticos

Ejemplo 1: Microservicio (10 archivos, 1 advertencia)

Ejemplo 2: Monolito (200 archivos, 500 avisos de formato)

Umbrales y bandas de estado

Etiquetas en la CLI

Bandas de salud en el panel web

Veredictos del control de calidad (3 estados)

​Fórmula de puntuación

​Multiplicadores de severidad y peso de motores

​Multiplicadores de severidad

​Peso de los motores

​Topes dinámicos por regla

​Escalado según el tamaño del repositorio

​Ejemplos prácticos

​Ejemplo 1: Microservicio (10 archivos, 1 advertencia)

​Ejemplo 2: Monolito (200 archivos, 500 avisos de formato)

​Umbrales y bandas de estado

​Etiquetas en la CLI

​Bandas de salud en el panel web

​Veredictos del control de calidad (3 estados)

Fórmula de puntuación

Multiplicadores de severidad y peso de motores

Multiplicadores de severidad

Peso de los motores

Topes dinámicos por regla

Escalado según el tamaño del repositorio

Ejemplos prácticos

Ejemplo 1: Microservicio (10 archivos, 1 advertencia)

Ejemplo 2: Monolito (200 archivos, 500 avisos de formato)

Umbrales y bandas de estado

Etiquetas en la CLI

Bandas de salud en el panel web

Veredictos del control de calidad (3 estados)