README.md

NPQ Documentation

This directory contains comprehensive documentation for the NPQ (Node Package Quality) security auditing tool.

Core Documentation

optional-features.md

Configuration and usage of optional security features, including recent improvements and bug fixes.

age.marshall.md

Detailed documentation of the Age Marshall security component that validates package age and maturity.

Feature Documentation

The feature/ directory contains detailed documentation for specific features and implementations:

Recent Developments

• test-coverage-improvements.md - Comprehensive test coverage enhancements that improved overall coverage from 84.4% to 93.39%
• signature-verification-fix.md - Critical bug fix for signature verification with version ranges (e.g., @angular/common@^20.2.4)

Existing Features

• auto-continue.md - Documentation for the auto-continue feature that streamlines package installation workflows
• custom-registry.md - Authenticated default and scoped npm-compatible registry configuration, routing, and failure behavior
• exit-codes.md - Reference for npq and npq-hero process exit behavior
• expired-domains.md - Evidence levels, external requests, privacy, and limitations for maintainer-domain checks
• malicious-package.md - Documentation for known-malicious package detection through Snyk/OSV data
• pacote-dependency-reduction.md - Implementation summary for optional pacote dependency reduction

Documentation Standards

Structure

• Each feature gets its own markdown file in feature/
• Core functionality documented at the root docs level
• Technical implementation details included with code examples
• User-facing configuration documented with usage examples

Content Guidelines

• Overview: Brief description of the feature/component
• Technical Design: Architecture and implementation details
• Usage Examples: Practical examples with code snippets
• Testing: Coverage and validation information
• Future Considerations: Maintenance and evolution notes

Marshall Documentation

Marshall components are the core security validation modules in NPQ. Each marshall focuses on a specific security concern:

• Age Marshall (age.marshall.md) - Package age and maturity validation
• Signature Marshall - NPM registry signature verification (see signature-verification-fix.md)
• Provenance Marshall - Package build attestation verification
• Snyk Marshall - Vulnerability database integration
• Typosquatting Marshall - Package name similarity detection

Contributing to Documentation

When adding new features or making significant changes:

1. Feature Documentation: Create a new file in feature/ directory
2. Update Index: Add entry to this README
3. Cross-Reference: Update related documentation files
4. Examples: Include practical usage examples
5. Testing: Document test coverage and validation

Quick Reference

Topic	File	Purpose
Optional Features	optional-features.md	Feature configuration and recent improvements
Age Validation	age.marshall.md	Package age and maturity security checks
Test Coverage	feature/test-coverage-improvements.md	Recent test suite enhancements
Signature Verification	feature/signature-verification-fix.md	Version range bug fix and validation
Auto-Continue	feature/auto-continue.md	Automated installation workflow
Custom Registries	feature/custom-registry.md	Authenticated npm-compatible registry configuration and privacy behavior
Exit Codes	feature/exit-codes.md	CLI and package-manager passthrough exit behavior
Expired Domains	feature/expired-domains.md	Maintainer-domain DNS and RDAP evidence, privacy, and limitations
Malicious Packages	feature/malicious-package.md	Known-malicious package detection and reporting
Dependency Reduction	feature/pacote-dependency-reduction.md	Optional dependency management

Project context

• Development - local setup, workflows, and useful commands.
• Testing - test commands, test organization, and verification expectations.
• Architecture - repository structure, package boundaries, and important flows.
• Conventions - coding, documentation, and maintenance conventions.

Design specifications

• Custom registry support - approved design for npm-compatible Artifactory and private registry support.
• Expired-domain maintainer identity warnings - approved design for attributable expired-domain warnings.
• Expired-domain resolved version - design for resolving the exact dependency version for expired-domain checks.

Implementation plans

• Custom registry support - task-by-task implementation plan for issue #429.
• Expired-domain resolved version - implementation plan for exact dependency-version resolution in expired-domain checks.
• Expired-domain maintainer identity warnings - test-first implementation plan for attributable expired-domain warnings.