Documentação do NPQ

Este diretório contém documentação abrangente para a ferramenta de auditoria de segurança NPQ (Node Package Quality).

Documentação Principal

optional-features.md

Configuração e uso de recursos de segurança opcionais, incluindo melhorias recentes e correções de bugs.

age.marshall.md

Documentação detalhada do componente de segurança Age Marshall que valida a idade e a maturidade de pacotes.

Documentação de Recursos

O diretório feature/ contém documentação detalhada para recursos e implementações específicas:

Desenvolvimentos Recentes

• test-coverage-improvements.md - Aprimoramentos abrangentes de cobertura de testes que elevaram a cobertura geral de 84,4% para 93,39%
• signature-verification-fix.md - Correção crítica de bug na verificação de assinaturas com intervalos de versão (ex.: @angular/common@^20.2.4)

Recursos Existentes

• auto-continue.md - Documentação do recurso auto-continue que agiliza os fluxos de instalação de pacotes
• exit-codes.md - Referência para o comportamento de saída dos processos npq e npq-hero
• json-output.md - Saída versionada, legível por máquina e apenas de auditoria, para CI e automação
• malicious-package.md - Documentação para detecção de pacotes conhecidamente maliciosos por meio de dados Snyk/OSV
• pacote-dependency-reduction.md - Resumo da implementação para redução opcional de dependências do pacote

Padrões de Documentação

Estrutura

• Cada recurso tem seu próprio arquivo markdown em feature/
• Funcionalidade principal documentada no nível raiz da documentação
• Detalhes técnicos de implementação incluídos com exemplos de código
• Configuração voltada ao usuário documentada com exemplos de uso

Diretrizes de Conteúdo

• Visão Geral: Breve descrição do recurso/componente
• Design Técnico: Arquitetura e detalhes de implementação
• Exemplos de Uso: Exemplos práticos com trechos de código
• Testes: Informações de cobertura e validação
• Considerações Futuras: Notas de manutenção e evolução

Documentação do Marshall

Os componentes Marshall são os módulos principais de validação de segurança no NPQ. Cada marshall foca em uma preocupação de segurança específica:

• Age Marshall (age.marshall.md) - Validação de idade e maturidade de pacotes
• Signature Marshall - Verificação de assinaturas do registro NPM (veja signature-verification-fix.md)
• Provenance Marshall - Verificação de atestação de build do pacote
• Snyk Marshall - Integração com banco de dados de vulnerabilidades
• Typosquatting Marshall - Detecção de similaridade em nomes de pacotes

Contribuindo com a Documentação

Ao adicionar novos recursos ou fazer mudanças significativas:

1. Documentação do Recurso: Crie um novo arquivo no diretório feature/
2. Atualize o Índice: Adicione uma entrada a este README
3. Referência Cruzada: Atualize os arquivos de documentação relacionados
4. Exemplos: Inclua exemplos práticos de uso
5. Testes: Documente cobertura de testes e validação

Referência Rápida

Contexto do projeto

• Desenvolvimento - configuração local, fluxos de trabalho e comandos úteis.
• Testes - comandos de teste, organização de testes e expectativas de verificação.
• Arquitetura - estrutura do repositório, limites de pacotes e fluxos importantes.
• Convenções - convenções de código, documentação e manutenção.

Especificações de design

• Suporte a registro personalizado - design aprovado para suporte a Artifactory compatível com npm e registros privados.
• Detecção JSON para agentes de codificação - design aprovado para seleção automática do modo de auditoria JSON em ambientes de agentes de codificação.
• Saída de auditoria JSON - design aprovado para resultados de auditoria versionados, não interativos e legíveis por máquina.
• Avisos de identidade de mantenedores com domínio expirado - design aprovado para avisos atribuíveis de domínio expirado.
• Versão resolvida de domínio expirado - design para resolução da versão exata da dependência em verificações de domínio expirado.

Planos de implementação

• Suporte a registro personalizado - plano de implementação tarefa por tarefa para a issue #429.
• Detecção JSON para agentes de codificação - plano de implementação test-first para a issue #426 em npq e npq-hero.
• Saída de auditoria JSON - plano tarefa por tarefa para saída JSON de CLI versionada e apenas de auditoria.
• Versão resolvida de domínio expirado - plano de implementação para resolução exata da versão da dependência em verificações de domínio expirado.
• Avisos de identidade de mantenedores com domínio expirado - plano de implementação test-first para avisos atribuíveis de domínio expirado.