npq

# Documentazione NPQ

Questa directory contiene la documentazione completa per lo strumento di audit di sicurezza NPQ (Node Package Quality).

## Documentazione Principale

### `optional-features.md`
Configurazione e utilizzo delle funzionalità di sicurezza opzionali, inclusi miglioramenti recenti e correzioni di bug.

### `age.marshall.md`  
Documentazione dettagliata del componente di sicurezza Age Marshall che valida l'età e la maturità dei pacchetti.

## Documentazione delle Funzionalità

La directory `feature/` contiene la documentazione dettagliata per funzionalità e implementazioni specifiche:

### Sviluppi Recenti

- **`test-coverage-improvements.md`** - Miglioramenti completi della copertura dei test che hanno portato la copertura complessiva dall'84,4% al 93,39%
- **`signature-verification-fix.md`** - Correzione critica di un bug nella verifica delle firme con intervalli di versioni (es., `@angular/common@^20.2.4`)

### Funzionalità Esistenti  

- **`auto-continue.md`** - Documentazione della funzionalità auto-continue che semplifica i flussi di lavoro di installazione dei pacchetti
- **`exit-codes.md`** - Riferimento per il comportamento di uscita dei processi `npq` e `npq-hero`
- **`json-output.md`** - Output di audit versionato e leggibile da macchina per CI e automazione
- **`malicious-package.md`** - Documentazione per il rilevamento di pacchetti notoriamente dannosi tramite dati Snyk/OSV
- **`pacote-dependency-reduction.md`** - Riepilogo dell'implementazione per la riduzione opzionale delle dipendenze pacote

## Standard di Documentazione

### Struttura
- Ogni funzionalità ha il proprio file markdown nella directory `feature/`
- La funzionalità principale è documentata a livello di root della documentazione  
- I dettagli tecnici di implementazione sono inclusi con esempi di codice
- La configurazione rivolta all'utente è documentata con esempi di utilizzo

### Linee Guida sui Contenuti
- **Panoramica**: Breve descrizione della funzionalità/componente
- **Progettazione Tecnica**: Architettura e dettagli di implementazione
- **Esempi di Utilizzo**: Esempi pratici con frammenti di codice
- **Test**: Informazioni su copertura e validazione
- **Considerazioni Future**: Note su manutenzione ed evoluzione

## Documentazione Marshall

I componenti Marshall sono i moduli principali di validazione della sicurezza in NPQ. Ogni marshall si concentra su una specifica problematica di sicurezza:

- **Age Marshall** (`age.marshall.md`) - Validazione di età e maturità dei pacchetti
- **Signature Marshall** - Verifica delle firme del registro NPM (vedi `signature-verification-fix.md`)
- **Provenance Marshall** - Verifica dell'attestazione di build dei pacchetti
- **Snyk Marshall** - Integrazione con il database delle vulnerabilità
- **Typosquatting Marshall** - Rilevamento di somiglianza nei nomi dei pacchetti

## Contribuire alla Documentazione

Quando si aggiungono nuove funzionalità o si apportano modifiche significative:

1. **Documentazione della Funzionalità**: Creare un nuovo file nella directory `feature/`
2. **Aggiornare l'Indice**: Aggiungere una voce a questo README
3. **Riferimenti Incrociati**: Aggiornare i file di documentazione correlati
4. **Esempi**: Includere esempi pratici di utilizzo
5. **Test**: Documentare la copertura dei test e la validazione

## Riferimento Rapido

| Argomento | File | Scopo |
|-------|------|---------|
| Funzionalità Opzionali | `optional-features.md` | Configurazione delle funzionalità e miglioramenti recenti |
| Validazione Età | `age.marshall.md` | Controlli di sicurezza su età e maturità dei pacchetti |
| Copertura Test | `feature/test-coverage-improvements.md` | Miglioramenti recenti della suite di test |
| Verifica Firma | `feature/signature-verification-fix.md` | Correzione bug intervalli di versioni e validazione |
| Auto-Continue | `feature/auto-continue.md` | Flusso di lavoro di installazione automatizzata |
| Output Audit JSON | `feature/json-output.md` | Risultati di audit versionati e leggibili da macchina per CI |
| Codici di Uscita | `feature/exit-codes.md` | Comportamento di uscita CLI e pass-through del gestore pacchetti |
| Pacchetti Dannosi | `feature/malicious-package.md` | Rilevamento e segnalazione di pacchetti notoriamente dannosi |
| Riduzione Dipendenze | `feature/pacote-dependency-reduction.md` | Gestione opzionale delle dipendenze |

## Contesto del Progetto

- [Sviluppo](https://github.com/lirantal/npq/blob/main/development.md) - configurazione locale, flussi di lavoro e comandi utili.
- [Test](https://github.com/lirantal/npq/blob/main/testing.md) - comandi di test, organizzazione dei test e aspettative di verifica.
- [Architettura](https://github.com/lirantal/npq/blob/main/architecture.md) - struttura del repository, confini dei pacchetti e flussi importanti.
- [Convenzioni](https://github.com/lirantal/npq/blob/main/conventions.md) - convenzioni di codifica, documentazione e manutenzione.

## Specifiche di Progettazione

- [Sicurezza installazione non interattiva](https://github.com/lirantal/npq/blob/main/superpowers/specs/2026-08-24-non-interactive-install-safety-design.md) - progettazione approvata per installazioni non-TTY fail-closed con opt-in espliciti per automazione e agenti di codifica.

- [Sicurezza installazione non interattiva](https://github.com/lirantal/npq/blob/main/superpowers/plans/2026-08-24-non-interactive-install-safety.md) - piano test-first per il routing di installazioni non-TTY fail-closed e pass-through per agenti di codifica.
- [Avvio del gestore pacchetti senza shell](https://github.com/lirantal/npq/blob/main/superpowers/specs/2026-08-15-package-manager-shell-free-launching-design.md) - progettazione approvata per l'inoltro degli argomenti del gestore pacchetti senza ricostruzione dei comandi shell.
- [Supporto registri personalizzati](https://github.com/lirantal/npq/blob/main/superpowers/specs/2026-07-11-custom-registry-support-design.md) - progettazione approvata per il supporto di Artifactory compatibile con npm e registri privati.
- [Rilevamento JSON per agenti di codifica](https://github.com/lirantal/npq/blob/main/superpowers/specs/2026-08-09-coding-agent-json-detection-design.md) - progettazione approvata per la selezione automatica della modalità di audit JSON in ambienti con agenti di codifica.
- [Output audit JSON](https://github.com/lirantal/npq/blob/main/superpowers/specs/2026-08-09-json-output-design.md) - progettazione approvata per risultati di audit versionati, non interattivi e leggibili da macchina.
- [Avvisi identità manutentori con dominio scaduto](https://github.com/lirantal/npq/blob/main/superpowers/specs/2026-07-17-expired-domain-maintainer-identities-design.md) - progettazione approvata per avvisi attribuibili su domini scaduti.
- [Versione risolta con dominio scaduto](https://github.com/lirantal/npq/blob/main/superpowers/specs/2026-07-17-expired-domain-resolved-version-design.md) - progettazione per la risoluzione della versione esatta della dipendenza per i controlli sui domini scaduti.

## Piani di Implementazione

- [Sicurezza installazione non interattiva](https://github.com/lirantal/npq/blob/main/superpowers/plans/2026-08-24-non-interactive-install-safety.md) - piano test-first per il routing di installazioni non-TTY fail-closed e pass-through per agenti di codifica.
- [Avvio del gestore pacchetti senza shell](https://github.com/lirantal/npq/blob/main/superpowers/plans/2026-08-15-package-manager-shell-free-launching.md) - piano test-first per l'avvio dei gestori pacchetti senza ricostruzione dei comandi shell.
- [Supporto registri personalizzati](https://github.com/lirantal/npq/blob/main/superpowers/plans/2026-07-11-custom-registry-support.md) - piano di implementazione attività per attività per l'issue #429.
- [Rilevamento JSON per agenti di codifica](https://github.com/lirantal/npq/blob/main/superpowers/plans/2026-08-09-coding-agent-json-detection.md) - piano di implementazione test-first per l'issue #426 su `npq` e `npq-hero`.
- [Output audit JSON](https://github.com/lirantal/npq/blob/main/superpowers/plans/2026-08-09-json-audit-output.md) - piano attività per attività per l'output CLI JSON versionato e solo audit.
- [Versione risolta con dominio scaduto](https://github.com/lirantal/npq/blob/main/superpowers/plans/2026-07-17-expired-domain-resolved-version.md) - piano di implementazione per la risoluzione esatta della versione della dipendenza nei controlli sui domini scaduti.
- [Avvisi identità manutentori con dominio scaduto](https://github.com/lirantal/npq/blob/main/superpowers/plans/2026-07-17-expired-domain-maintainer-identities.md) - piano di implementazione test-first per avvisi attribuibili su domini scaduti.