Documentación de NPQ

Este directorio contiene documentación exhaustiva para la herramienta de auditoría de seguridad NPQ (Node Package Quality).

Documentación Principal

optional-features.md

Configuración y uso de las funciones de seguridad opcionales, incluyendo mejoras recientes y correcciones de errores.

age.marshall.md

Documentación detallada del componente de seguridad Age Marshall que valida la antigüedad y madurez de los paquetes.

Documentación de Funciones

El directorio feature/ contiene documentación detallada para funciones e implementaciones específicas:

Desarrollos Recientes

• test-coverage-improvements.md - Mejoras exhaustivas de cobertura de pruebas que elevaron la cobertura general del 84.4% al 93.39%
• signature-verification-fix.md - Corrección crítica de errores para la verificación de firmas con rangos de versiones (p. ej., @angular/common@^20.2.4)

Funciones Existentes

• auto-continue.md - Documentación de la función de continuación automática que agiliza los flujos de instalación de paquetes
• exit-codes.md - Referencia para el comportamiento de salida de los procesos npq y npq-hero
• json-output.md - Salida de auditoría versionada y legible por máquina para CI y automatización
• malicious-package.md - Documentación para la detección de paquetes maliciosos conocidos mediante datos de Snyk/OSV
• pacote-dependency-reduction.md - Resumen de implementación para la reducción opcional de dependencias de pacote

Estándares de Documentación

Estructura

• Cada función recibe su propio archivo markdown en feature/
• La funcionalidad principal se documenta en el nivel raíz de docs
• Los detalles técnicos de implementación se incluyen con ejemplos de código
• La configuración orientada al usuario se documenta con ejemplos de uso

Pautas de Contenido

• Resumen: Breve descripción de la función/componente
• Diseño Técnico: Arquitectura y detalles de implementación
• Ejemplos de Uso: Ejemplos prácticos con fragmentos de código
• Pruebas: Información de cobertura y validación
• Consideraciones Futuras: Notas de mantenimiento y evolución

Documentación de Marshall

Los componentes Marshall son los módulos principales de validación de seguridad en NPQ. Cada marshall se centra en una preocupación de seguridad específica:

• Age Marshall (age.marshall.md) - Validación de antigüedad y madurez de paquetes
• Signature Marshall - Verificación de firmas del registro NPM (ver signature-verification-fix.md)
• Provenance Marshall - Verificación de atestación de compilación de paquetes
• Snyk Marshall - Integración con la base de datos de vulnerabilidades
• Typosquatting Marshall - Detección de similitud de nombres de paquetes

Contribución a la Documentación

Al añadir nuevas funciones o realizar cambios significativos:

1. Documentación de Funciones: Cree un nuevo archivo en el directorio feature/
2. Actualizar Índice: Añada una entrada a este README
3. Referencias Cruzadas: Actualice los archivos de documentación relacionados
4. Ejemplos: Incluya ejemplos prácticos de uso
5. Pruebas: Documente la cobertura de pruebas y la validación

Referencia Rápida

Contexto del Proyecto

• Desarrollo - configuración local, flujos de trabajo y comandos útiles.
• Pruebas - comandos de prueba, organización de pruebas y expectativas de verificación.
• Arquitectura - estructura del repositorio, límites de paquetes y flujos importantes.
• Convenciones - convenciones de codificación, documentación y mantenimiento.

Especificaciones de Diseño

• Seguridad de instalación no interactiva - diseño aprobado para instalaciones no TTY con cierre ante fallos con aceptaciones explícitas para automatización y agentes de codificación.

• Seguridad de instalación no interactiva - plan test-first para el enrutamiento de instalaciones no TTY con cierre ante fallos y paso a través de agentes de codificación.

• Lanzamiento de gestor de paquetes sin shell - diseño aprobado para reenviar argumentos del gestor de paquetes sin reconstrucción de comandos shell.

• Soporte de registros personalizados - diseño aprobado para soporte de Artifactory compatible con npm y registros privados.

• Detección JSON para agentes de codificación - diseño aprobado para seleccionar automáticamente el modo de auditoría JSON en entornos de agentes de codificación.

• Salida de auditoría JSON - diseño aprobado para resultados de auditoría versionados, no interactivos y legibles por máquina.

• Advertencias de identidad de mantenedores con dominio caducado - diseño aprobado para advertencias atribuibles de dominios caducados.

• Versión resuelta de dominio caducado - diseño para resolver la versión exacta de la dependencia en comprobaciones de dominios caducados.

Planes de Implementación

• Seguridad de instalación no interactiva - plan test-first para el enrutamiento de instalaciones no TTY con cierre ante fallos y paso a través de agentes de codificación.
• Lanzamiento de gestor de paquetes sin shell - plan test-first para lanzar gestores de paquetes sin reconstrucción de comandos shell.
• Soporte de registros personalizados - plan de implementación tarea por tarea para el problema #429.
• Detección JSON para agentes de codificación - plan de implementación test-first para el problema #426 en npq y npq-hero.
• Salida de auditoría JSON - plan tarea por tarea para salida CLI JSON versionada y solo de auditoría.
• Versión resuelta de dominio caducado - plan de implementación para la resolución exacta de la versión de dependencia en comprobaciones de dominios caducados.
• Advertencias de identidad de mantenedores con dominio caducado - plan de implementación test-first para advertencias atribuibles de dominios caducados.