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 maturidade dos 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 faixas de versão (ex.: @angular/common@^20.2.4)

Recursos Existentes

• auto-continue.md - Documentação do recurso de continuação automática que otimiza 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 e legível por máquina, exclusiva para auditoria, voltada a 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 recebe seu próprio arquivo markdown em feature/
• Funcionalidade principal documentada no nível raiz de docs
• 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: Detalhes de arquitetura e 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 Marshall

Os componentes Marshall são os módulos principais de validação de segurança no NPQ. Cada marshall concentra-se 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 assinatura do registro NPM (ver signature-verification-fix.md)
• Provenance Marshall - Verificação de atestação de build de pacotes
• 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 alterações significativas:

1. Documentação do Recurso: Crie um novo arquivo no diretório feature/
2. Atualizar Índice: Adicione uma entrada neste README
3. Referência Cruzada: Atualize os arquivos de documentação relacionados
4. Exemplos: Inclua exemplos práticos de uso
5. Testes: Documente a cobertura de testes e a 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 codificação, documentação e manutenção.

Especificações de Design

• Segurança de instalação não interativa - design aprovado para instalações não-TTY com falha segura, com aceites explícitos para automação e agentes de codificação.

• Segurança de instalação não interativa - plano test-first para roteamento de instalação não-TTY com falha segura e repasse para agentes de codificação.

• Lançamento de gerenciador de pacotes sem shell - design aprovado para repassar argumentos do gerenciador de pacotes sem reconstrução de comandos shell.

• 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 resolver a versão exata da dependência em verificações de domínio expirado.

Planos de Implementação

• Segurança de instalação não interativa - plano test-first para roteamento de instalação não-TTY com falha segura e repasse para agentes de codificação.
• Lançamento de gerenciador de pacotes sem shell - plano test-first para lançar gerenciadores de pacotes sem reconstrução de comandos shell.
• 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 exclusiva para auditoria e versionada.
• 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.