Revera

La calificación crediticia de los paquetes npm.

Revera te ayuda a decidir si vale la pena instalar un paquete antes de ejecutar npm install. Analiza la calidad del paquete, el mantenimiento, la seguridad, la salud del ecosistema y la confianza del publicador — y ahora propaga el riesgo de forma transitiva a través de todo tu grafo de dependencias — y luego produce un informe de reputación bayesiano y explicable.

Demo

Observa a revera revisar y explicar paquetes en tiempo real.

Inicio rápido

Ejecuta revera al instante sin instalación:

npx revera check react

Ejemplo

Revisar un paquete como request (que fue deprecado en 2020) te advierte de inmediato con razones específicas:

$ revera why request

  ▲ revera EXPLAIN
  ──────────────────────────────────────────────────
  Package:   [email protected]
  Overall:   38/100  Not Recommended

  Score Breakdown

    Maintenance             15/100  ███░░░░░░░░░░░░░░░░░
                           Release cadence, commit activity, issue responsiveness, maintainer count

    Stability               90/100  ██████████████████░░
                           SemVer compliance, major version history, API volatility over time

    Security               100/100  ████████████████████
                           Known CVEs, install scripts, repository transparency

    Package Quality         40/100  ████████░░░░░░░░░░░░
                           README completeness, license, test coverage indicators, exports

    Ecosystem              100/100  ████████████████████
                           Weekly download volume, GitHub stars, community forks

    Documentation           90/100  ██████████████████░░
                           README length, code examples, API references, external docs presence

    Developer Experience    40/100  ████████░░░░░░░░░░░░
                           TypeScript support, ESM compatibility, CLI tooling

    Publisher Trust        100/100  ████████████████████
                           Known malicious releases, protestware history, supply-chain incidents

  Why it scores well
    +  Stable API (v1.0.0+)
    +  Low API volatility
    +  Zero known vulnerabilities
    +  Permissive open-source license
    +  Code examples in README
    +  Structured API documentation
    +  No known publisher trust incidents

  Minor deductions
    -  Last release was 59 months ago
    -  Single maintainer (bus factor of 1)
    -  Missing native type definitions
    -  Legacy CommonJS only
    -  No native typings (bad TypeScript DX)

  Warnings
    !  Last release: 59 months ago. No recent updates detected. This may be normal for mature, stable libraries.
    !  Package has been officially marked as deprecated by the maintainer.

  Verdict
    Request has low confidence. revera recommends looking for alternatives due to security, activity, or stability concerns.

Instalación

Instala de forma global para acceder al ejecutable desde cualquier directorio:

npm install -g @aaravmaloo/revera

Uso

1. Comprobar la reputación de un paquete

Analiza un paquete y obtén un informe resumido de alto nivel:

revera check lodash

Ejecuta en modo sin conexión usando archivos en caché:

revera check express --offline

2. Explicar la calificación de un paquete

Obtén un desglose detallado de la puntuación, las señales positivas y las deducciones:

revera why node-ipc

3. Evaluar y añadir una dependencia

Evalúa los paquetes antes de la instalación y advierte cuando la reputación cae por debajo de tu umbral configurado:

revera add express

Puedes pasar banderas directamente a tu gestor de paquetes:

revera add typescript --save-dev

4. Auditar el espacio de trabajo local

Audita todos los paquetes del proyecto actual (incluye dependencias transitivas) y calcula una puntuación general de salud del proyecto:

revera audit

Audita solo las dependencias de producción:

revera audit --prod

Audita solo las dependencias directas, omitiendo las dependencias transitivas:

revera audit --direct

5. Autenticación de GitHub

Autentícate con GitHub para aumentar los límites de la API (60/hora anónimo frente a 5.000/hora autenticado). Puedes elegir entre OAuth2 mediante navegador o introducir manualmente un Personal Access Token. Una vez autorizado, revera cifra y almacena el token de forma segura en el llavero del sistema operativo (DPAPI en Windows, Keychain en macOS o Secret Service en Linux):

revera login

6. Ajustes de la CLI

Gestiona los ajustes locales guardados en ~/.revera/config.json:

revera config
revera config set minScoreThreshold 75
revera config get minScoreThreshold

7. Doctor del sistema

Verifica la configuración del entorno, el estado de la API y las latencias de conexión de red:

revera doctor

8. Control de caché

Inspecciona o limpia la caché local de metadatos:

revera cache
revera cache clear

9. Comprobación de actualizaciones

Verifica si estás ejecutando la última versión del motor de revera:

revera update

Comparación

Motor de puntuación (v2)

Revera v2 reemplazó el antiguo modelo plano de suma ponderada por un pipeline bayesiano de DAG en cuatro etapas.

Etapa 1 — Grafo de dependencias (DAG)

Todas las dependencias del proyecto se resuelven en un grafo acíclico dirigido. Cada nodo realiza un seguimiento de su conjunto completo de dependientes transitivos para que las etapas posteriores puedan calcular radios de impacto precisos.

lodash ──► your-app
express ──► your-app
axios ──► some-lib ──► your-app   ← transitive

Etapa 2 — Puntuación por paquete (posteriores beta bayesianos)

Cada una de las 8 categorías de puntuación parte de un prior específico por arquetipo (framework, cli, types-only, utility) en lugar de una línea base plana no informada. Las señales observadas actualizan una distribución Beta posterior; es decir, un tiempo de espera agotado o la falta de datos amplían el intervalo creíble en lugar de asumir silenciosamente que está "limpio".

La puntuación final por paquete es un agregado ponderado por confianza de los posteriores de cada categoría (ponderación por varianza inversa), que produce tanto una estimación puntual como un intervalo creíble del 95%.

Etapa 3 — Comprobaciones de veto

Tres anulaciones estrictas omiten por completo la puntuación bayesiana y hacen fallar a un paquete de inmediato:

Etapa 4 — Propagación de riesgo transitivo

Una vez calculadas las puntuaciones por paquete, el riesgo se propaga de abajo hacia arriba a través del DAG (orden topológico, primero las hojas):

• Si el effectiveRisk de una dependencia supera un umbral, el riesgo de su paquete padre se fija en un mínimo de 0.8 (marcado como contaminado).
• El radio de impacto de cada nodo = effectiveRisk × transitive_dependent_count.
• El peor subcamino se rastrea y se muestra en la salida de auditoría para que sepas exactamente qué cadena de dependencias causó la marca.

Etapa 5 — Síntesis del informe

El informe de auditoría final combina las puntuaciones intrínsecas, la contaminación heredada, los intervalos creíbles y los radios de impacto en una única salida clasificada. La puntuación general del espacio de trabajo es un promedio ponderado por radio de impacto.

Bases de datos de vulnerabilidades

Revera consulta tres bases de datos de vulnerabilidades independientes en paralelo en cada comprobación. Los resultados se combinan y se deduplican por alias CVE/GHSA antes de usarse en la puntuación.

Si una fuente agota el tiempo de espera o da error, las demás continúan de forma independiente. El VulnResult expone qué fuentes respondieron (sources) y cuáles fallaron (failedSources) para que el puntuador bayesiano pueda ampliar el intervalo de incertidumbre adecuadamente en lugar de asumir que está limpio.

Arquitectura y estructura

.github/              # CI configurations
docs/                 # Architecture specs and algorithm diagrams
src/
  ├── commands/       # CLI command handlers (check, why, add, audit, config, cache, update)
  ├── engine/
  │   ├── dag.ts          # DAG construction + topological sort + blast-radius computation
  │   ├── propagation.ts  # Bottom-up transitive risk propagation
  │   ├── scoring.ts      # Bayesian Beta posteriors, archetype priors, veto checks
  │   ├── vuln.ts         # Multi-source vuln aggregator (OSV + GitHub + npm)
  │   ├── trust.ts        # Publisher trust incident database
  │   ├── typosquat.ts    # Edit-distance typosquat detection
  │   ├── npm.ts          # npm registry + download stats fetcher
  │   └── github.ts       # GitHub repo stats + README fetcher
  ├── ui/             # Console view templates (reporter formatters, theme styles)
  └── utils/          # Filesystem helpers (caching, configuration, package managers)
tests/                # Unit test suites
benchmarker/          # Large-scale benchmark suite (100k+ packages)

Pruebas de rendimiento

Revera incluye una suite de pruebas de rendimiento a gran escala en benchmarker/ que evalúa más de 100 000 paquetes npm en paralelo y produce un único informe legible en GitHub.

Ejecutar una prueba de rendimiento

cd benchmarker
npm install
npm run fetch-dataset          # one-time: pulls ~100k packages into datasets/npm.jsonl
./benchmark.sh --workers 16   # runs the full suite

Cada ejecución produce un directorio de salida autocontenido con:

Última prueba de rendimiento (algoritmo v2, conjunto de datos inicial)

La prueba de rendimiento v1 se ejecutó antes de que se implementaran los controles de veto de v2. Las cifras de malicious/typosquat por etiqueta reflejan el algoritmo heredado. Una nueva ejecución completa de v2 se publicará en la próxima versión.

Hoja de ruta

• Puntuación de reputación de paquetes
• Informes de puntuación explicables
• Auditoría de proyectos directa y transitiva
• Comprobaciones de incidentes de confianza del publicador
• Avisos de typosquat por Levenshtein
• Puntuación bayesiana con posteriores Beta (v2)
• Propagación de riesgo transitivo en DAG (v2)
• Agregación de vulnerabilidades de múltiples fuentes (OSV + GitHub + npm)
• Informes de pruebas de rendimiento legibles en GitHub (BENCHMARK.md)
• Comandos de comparación de múltiples paquetes
• Acción oficial de GitHub para comprobaciones de CI
• Extensión oficial de VS Code
• Soporte nativo de pnpm
• Soporte nativo de Yarn

Preguntas frecuentes

¿Cómo evito los límites de tasa de la API de GitHub?

Sin un token, las consultas anónimas están limitadas a 60 solicitudes por hora. Puedes configurar un Personal Access Token en tu configuración:

revera config set githubToken ghp_YOUR_TOKEN

¿Qué ocurre si estoy sin conexión?

Revera recurre al uso de archivos de caché. Puedes ejecutar comandos explícitamente en modo sin conexión con la bandera --offline. Si una fuente de vulnerabilidades no está disponible, el puntuador bayesiano amplía el intervalo creíble de ese paquete en lugar de asumir que está limpio.

¿El comando add modifica mi proyecto?

Revera actúa como un envoltorio de shell. Ejecuta el instalador de paquetes real después de la evaluación.

¿Qué es un paquete "contaminado" en la salida de auditoría?

Un paquete se marca como contaminado cuando una de sus dependencias transitivas activó un veto u obtuvo una puntuación críticamente baja. La salida de auditoría muestra el peor subcamino para que puedas rastrear la cadena exacta de dependencias que causó la marca.

¿Cómo se deduplican las vulnerabilidades entre tres bases de datos?

Cada vulnerabilidad se identifica por su ID de CVE, ID de GHSA o ID de aviso npm. Cuando la misma vulnerabilidad aparece en varias fuentes, se fusiona en una única entrada canónica. Los datos de OSV tienen prioridad para los campos de texto (resumen, detalles); se conservan la calificación de severidad más alta y el rango de versiones parcheadas más completo de todas las fuentes.

Contribuciones

Revisa la Guía de contribución para comenzar con la configuración, las reglas de estilo y las pautas para PR.

Descargo de responsabilidad

Revera proporciona una puntuación de reputación basada en señales observables del proyecto y datos históricos. Está pensada para ayudar en decisiones de ingeniería y no debe tratarse como una auditoría de seguridad definitiva.

Licencia

Revera se distribuye bajo la Licencia MIT.