npq

# NPQ-Dokumentation

Dieses Verzeichnis enthält umfassende Dokumentation für das Sicherheits-Audit-Tool NPQ (Node Package Quality).

## Kerndokumentation

### `optional-features.md`
Konfiguration und Verwendung optionaler Sicherheitsfunktionen, einschließlich aktueller Verbesserungen und Fehlerbehebungen.

### `age.marshall.md`
Detaillierte Dokumentation der Age-Marshall-Sicherheitskomponente, die Paketalter und -reife validiert.

## Funktionsdokumentation

Das Verzeichnis `feature/` enthält detaillierte Dokumentation für spezifische Funktionen und Implementierungen:

### Aktuelle Entwicklungen

- **`test-coverage-improvements.md`** - Umfassende Verbesserungen der Testabdeckung, die die Gesamtabdeckung von 84,4 % auf 93,39 % erhöht haben
- **`signature-verification-fix.md`** - Kritische Fehlerbehebung für die Signaturprüfung mit Versionsbereichen (z. B. `@angular/common@^20.2.4`)

### Bestehende Funktionen

- **`auto-continue.md`** - Dokumentation für die Auto-Continue-Funktion, die Paketinstallations-Workflows optimiert
- **`exit-codes.md`** - Referenz für das Exit-Verhalten der Prozesse `npq` und `npq-hero`
- **`json-output.md`** - Versionierte, maschinenlesbare Audit-Ausgabe für CI und Automatisierung
- **`malicious-package.md`** - Dokumentation zur Erkennung bekannter bösartiger Pakete über Snyk/OSV-Daten
- **`pacote-dependency-reduction.md`** - Implementierungsübersicht für die optionale Reduzierung der pacote-Abhängigkeiten

## Dokumentationsstandards

### Struktur
- Jede Funktion erhält eine eigene Markdown-Datei im Verzeichnis `feature/`
- Kernfunktionalität wird auf der obersten Dokumentationsebene dokumentiert
- Technische Implementierungsdetails werden mit Codebeispielen bereitgestellt
- Benutzerorientierte Konfiguration wird mit Verwendungsbeispielen dokumentiert

### Inhaltsrichtlinien
- **Überblick**: Kurze Beschreibung der Funktion/Komponente
- **Technisches Design**: Architektur- und Implementierungsdetails
- **Verwendungsbeispiele**: Praktische Beispiele mit Codeausschnitten
- **Tests**: Informationen zu Abdeckung und Validierung
- **Zukünftige Überlegungen**: Hinweise zu Wartung und Weiterentwicklung

## Marshall-Dokumentation

Marshall-Komponenten sind die zentralen Sicherheitsvalidierungsmodule in NPQ. Jede Marshall-Komponente konzentriert sich auf einen spezifischen Sicherheitsaspekt:

- **Age Marshall** (`age.marshall.md`) - Validierung von Paketalter und -reife
- **Signature Marshall** - Überprüfung der NPM-Registry-Signaturen (siehe `signature-verification-fix.md`)
- **Provenance Marshall** - Verifizierung der Paket-Build-Herkunft
- **Snyk Marshall** - Integration der Schwachstellendatenbank
- **Typosquatting Marshall** - Erkennung von Ähnlichkeiten bei Paketnamen

## Beiträge zur Dokumentation

Beim Hinzufügen neuer Funktionen oder bei wesentlichen Änderungen:

1. **Funktionsdokumentation**: Neue Datei im Verzeichnis `feature/` erstellen
2. **Index aktualisieren**: Eintrag in dieser README hinzufügen
3. **Querverweise**: Verwandte Dokumentationsdateien aktualisieren
4. **Beispiele**: Praktische Verwendungsbeispiele einfügen
5. **Tests**: Testabdeckung und Validierung dokumentieren

## Kurzreferenz

| Thema | Datei | Zweck |
|-------|------|---------|
| Optionale Funktionen | `optional-features.md` | Funktionskonfiguration und aktuelle Verbesserungen |
| Altersvalidierung | `age.marshall.md` | Sicherheitsprüfungen zu Paketalter und -reife |
| Testabdeckung | `feature/test-coverage-improvements.md` | Aktuelle Verbesserungen der Testsuite |
| Signaturprüfung | `feature/signature-verification-fix.md` | Fehlerbehebung und Validierung bei Versionsbereichen |
| Auto-Continue | `feature/auto-continue.md` | Automatisierter Installations-Workflow |
| JSON-Audit-Ausgabe | `feature/json-output.md` | Versionierte maschinenlesbare Audit-Ergebnisse für CI |
| Exit-Codes | `feature/exit-codes.md` | Exit-Verhalten von CLI und Paketmanager-Durchreichung |
| Bösartige Pakete | `feature/malicious-package.md` | Erkennung und Meldung bekannter bösartiger Pakete |
| Abhängigkeitsreduzierung | `feature/pacote-dependency-reduction.md` | Optionale Abhängigkeitsverwaltung |

## Projektkontext

- [Entwicklung](https://github.com/lirantal/npq/blob/main/development.md) - lokale Einrichtung, Workflows und nützliche Befehle.
- [Tests](https://github.com/lirantal/npq/blob/main/testing.md) - Testbefehle, Testorganisation und Verifikationserwartungen.
- [Architektur](https://github.com/lirantal/npq/blob/main/architecture.md) - Repository-Struktur, Paketgrenzen und wichtige Abläufe.
- [Konventionen](https://github.com/lirantal/npq/blob/main/conventions.md) - Kodierungs-, Dokumentations- und Wartungskonventionen.

## Designspezifikationen

- [Sicherheit bei nicht-interaktiven Installationen](https://github.com/lirantal/npq/blob/main/superpowers/specs/2026-08-24-non-interactive-install-safety-design.md) - genehmigtes Design für Fail-Closed-Non-TTY-Installationen mit expliziten Opt-ins für Automatisierung und Coding-Agenten.

- [Sicherheit bei nicht-interaktiven Installationen](https://github.com/lirantal/npq/blob/main/superpowers/plans/2026-08-24-non-interactive-install-safety.md) - Test-First-Plan für Fail-Closed-Non-TTY-Installationsrouting und Coding-Agent-Durchreichung.
- [Shell-freies Starten von Paketmanagern](https://github.com/lirantal/npq/blob/main/superpowers/specs/2026-08-15-package-manager-shell-free-launching-design.md) - genehmigtes Design für die Weiterleitung von Paketmanager-Argumenten ohne Shell-Befehlsrekonstruktion.
- [Unterstützung benutzerdefinierter Registries](https://github.com/lirantal/npq/blob/main/superpowers/specs/2026-07-11-custom-registry-support-design.md) - genehmigtes Design für npm-kompatible Artifactory- und private Registry-Unterstützung.
- [JSON-Erkennung für Coding-Agenten](https://github.com/lirantal/npq/blob/main/superpowers/specs/2026-08-09-coding-agent-json-detection-design.md) - genehmigtes Design für die automatische Auswahl des JSON-Audit-Modus in Coding-Agent-Umgebungen.
- [JSON-Audit-Ausgabe](https://github.com/lirantal/npq/blob/main/superpowers/specs/2026-08-09-json-output-design.md) - genehmigtes Design für versionierte, nicht-interaktive maschinenlesbare Audit-Ergebnisse.
- [Warnungen zu abgelaufenen Domains von Maintainern](https://github.com/lirantal/npq/blob/main/superpowers/specs/2026-07-17-expired-domain-maintainer-identities-design.md) - genehmigtes Design für zurechenbare Warnungen zu abgelaufenen Domains.
- [Aufgelöste Version bei abgelaufenen Domains](https://github.com/lirantal/npq/blob/main/superpowers/specs/2026-07-17-expired-domain-resolved-version-design.md) - Design zur Auflösung der exakten Abhängigkeitsversion für Prüfungen abgelaufener Domains.

## Implementierungspläne

- [Sicherheit bei nicht-interaktiven Installationen](https://github.com/lirantal/npq/blob/main/superpowers/plans/2026-08-24-non-interactive-install-safety.md) - Test-First-Plan für Fail-Closed-Non-TTY-Installationsrouting und Coding-Agent-Durchreichung.
- [Shell-freies Starten von Paketmanagern](https://github.com/lirantal/npq/blob/main/superpowers/plans/2026-08-15-package-manager-shell-free-launching.md) - Test-First-Plan zum Starten von Paketmanagern ohne Shell-Befehlsrekonstruktion.
- [Unterstützung benutzerdefinierter Registries](https://github.com/lirantal/npq/blob/main/superpowers/plans/2026-07-11-custom-registry-support.md) - Schritt-für-Schritt-Implementierungsplan für Issue #429.
- [JSON-Erkennung für Coding-Agenten](https://github.com/lirantal/npq/blob/main/superpowers/plans/2026-08-09-coding-agent-json-detection.md) - Test-First-Implementierungsplan für Issue #426 in `npq` und `npq-hero`.
- [JSON-Audit-Ausgabe](https://github.com/lirantal/npq/blob/main/superpowers/plans/2026-08-09-json-audit-output.md) - Schritt-für-Schritt-Plan für versionierte, reine Audit-JSON-CLI-Ausgabe.
- [Aufgelöste Version bei abgelaufenen Domains](https://github.com/lirantal/npq/blob/main/superpowers/plans/2026-07-17-expired-domain-resolved-version.md) - Implementierungsplan für die exakte Auflösung der Abhängigkeitsversion bei Prüfungen abgelaufener Domains.
- [Warnungen zu abgelaufenen Domains von Maintainern](https://github.com/lirantal/npq/blob/main/superpowers/plans/2026-07-17-expired-domain-maintainer-identities.md) - Test-First-Implementierungsplan für zurechenbare Warnungen zu abgelaufenen Domains.