> ## Documentation Index
> Fetch the complete documentation index at: https://docs.raigal.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Motor de puntuación

> Puntuación de calidad de 0 a 100, normalización por densidad y bandas de estado.

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:

```text theme={null}
Densidad de deducción = (Suma de deducciones acotadas) / (Archivos fuente efectivos + S)
```

```text theme={null}
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:

```text theme={null}
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:

```text theme={null}
Escala de tope = max(1, Archivos fuente efectivos / 10)
```

```text theme={null}
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**:

```text theme={null}
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**:

```text theme={null}
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) |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.