# 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

| Tema | Archivo | Propósito |
|------|---------|-----------|
| Funciones Opcionales | `optional-features.md` | Configuración de funciones y mejoras recientes |
| Validación de Antigüedad | `age.marshall.md` | Comprobaciones de seguridad de antigüedad y madurez de paquetes |
| Cobertura de Pruebas | `feature/test-coverage-improvements.md` | Mejoras recientes del conjunto de pruebas |
| Verificación de Firmas | `feature/signature-verification-fix.md` | Corrección de errores de rangos de versiones y validación |
| Continuación Automática | `feature/auto-continue.md` | Flujo de instalación automatizado |
| Salida de Auditoría JSON | `feature/json-output.md` | Resultados de auditoría versionados y legibles por máquina para CI |
| Códigos de Salida | `feature/exit-codes.md` | Comportamiento de salida de CLI y paso a través del gestor de paquetes |
| Paquetes Maliciosos | `feature/malicious-package.md` | Detección y notificación de paquetes maliciosos conocidos |
| Reducción de Dependencias | `feature/pacote-dependency-reduction.md` | Gestión opcional de dependencias |

## Contexto del Proyecto

- [Desarrollo](https://github.com/lirantal/npq/blob/main/development.md) - configuración local, flujos de trabajo y comandos útiles.
- [Pruebas](https://github.com/lirantal/npq/blob/main/testing.md) - comandos de prueba, organización de pruebas y expectativas de verificación.
- [Arquitectura](https://github.com/lirantal/npq/blob/main/architecture.md) - estructura del repositorio, límites de paquetes y flujos importantes.
- [Convenciones](https://github.com/lirantal/npq/blob/main/conventions.md) - convenciones de codificación, documentación y mantenimiento.

## Especificaciones de Diseño

- [Seguridad de instalación no interactiva](https://github.com/lirantal/npq/blob/main/superpowers/specs/2026-08-24-non-interactive-install-safety-design.md) - 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](https://github.com/lirantal/npq/blob/main/superpowers/plans/2026-08-24-non-interactive-install-safety.md) - 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](https://github.com/lirantal/npq/blob/main/superpowers/specs/2026-08-15-package-manager-shell-free-launching-design.md) - diseño aprobado para reenviar argumentos del gestor de paquetes sin reconstrucción de comandos shell.
- [Soporte de registros personalizados](https://github.com/lirantal/npq/blob/main/superpowers/specs/2026-07-11-custom-registry-support-design.md) - diseño aprobado para soporte de Artifactory compatible con npm y registros privados.
- [Detección JSON para agentes de codificación](https://github.com/lirantal/npq/blob/main/superpowers/specs/2026-08-09-coding-agent-json-detection-design.md) - 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](https://github.com/lirantal/npq/blob/main/superpowers/specs/2026-08-09-json-output-design.md) - diseño aprobado para resultados de auditoría versionados, no interactivos y legibles por máquina.
- [Advertencias de identidad de mantenedores con dominio caducado](https://github.com/lirantal/npq/blob/main/superpowers/specs/2026-07-17-expired-domain-maintainer-identities-design.md) - diseño aprobado para advertencias atribuibles de dominios caducados.
- [Versión resuelta de dominio caducado](https://github.com/lirantal/npq/blob/main/superpowers/specs/2026-07-17-expired-domain-resolved-version-design.md) - 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](https://github.com/lirantal/npq/blob/main/superpowers/plans/2026-08-24-non-interactive-install-safety.md) - 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](https://github.com/lirantal/npq/blob/main/superpowers/plans/2026-08-15-package-manager-shell-free-launching.md) - plan test-first para lanzar gestores de paquetes sin reconstrucción de comandos shell.
- [Soporte de registros personalizados](https://github.com/lirantal/npq/blob/main/superpowers/plans/2026-07-11-custom-registry-support.md) - plan de implementación tarea por tarea para el problema #429.
- [Detección JSON para agentes de codificación](https://github.com/lirantal/npq/blob/main/superpowers/plans/2026-08-09-coding-agent-json-detection.md) - plan de implementación test-first para el problema #426 en `npq` y `npq-hero`.
- [Salida de auditoría JSON](https://github.com/lirantal/npq/blob/main/superpowers/plans/2026-08-09-json-audit-output.md) - plan tarea por tarea para salida CLI JSON versionada y solo de auditoría.
- [Versión resuelta de dominio caducado](https://github.com/lirantal/npq/blob/main/superpowers/plans/2026-07-17-expired-domain-resolved-version.md) - 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](https://github.com/lirantal/npq/blob/main/superpowers/plans/2026-07-17-expired-domain-maintainer-identities.md) - plan de implementación test-first para advertencias atribuibles de dominios caducados.
npq

Más Populares
