npq

# 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

| Tópico | Arquivo | Finalidade |
|-------|------|---------|
| Recursos Opcionais | `optional-features.md` | Configuração de recursos e melhorias recentes |
| Validação de Idade | `age.marshall.md` | Verificações de segurança de idade e maturidade de pacotes |
| Cobertura de Testes | `feature/test-coverage-improvements.md` | Aprimoramentos recentes do conjunto de testes |
| Verificação de Assinatura | `feature/signature-verification-fix.md` | Correção de bug em faixa de versão e validação |
| Continuação Automática | `feature/auto-continue.md` | Fluxo de instalação automatizada |
| Saída de Auditoria JSON | `feature/json-output.md` | Resultados de auditoria versionados e legíveis por máquina para CI |
| Códigos de Saída | `feature/exit-codes.md` | Comportamento de saída da CLI e do repasse do gerenciador de pacotes |
| Pacotes Maliciosos | `feature/malicious-package.md` | Detecção e relato de pacotes conhecidamente maliciosos |
| Redução de Dependências | `feature/pacote-dependency-reduction.md` | Gerenciamento opcional de dependências |

## Contexto do Projeto

- [Desenvolvimento](https://github.com/lirantal/npq/blob/main/development.md) - configuração local, fluxos de trabalho e comandos úteis.
- [Testes](https://github.com/lirantal/npq/blob/main/testing.md) - comandos de teste, organização de testes e expectativas de verificação.
- [Arquitetura](https://github.com/lirantal/npq/blob/main/architecture.md) - estrutura do repositório, limites de pacotes e fluxos importantes.
- [Convenções](https://github.com/lirantal/npq/blob/main/conventions.md) - convenções de codificação, documentação e manutenção.

## Especificações de Design

- [Segurança de instalação não interativa](https://github.com/lirantal/npq/blob/main/superpowers/specs/2026-08-24-non-interactive-install-safety-design.md) - 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](https://github.com/lirantal/npq/blob/main/superpowers/plans/2026-08-24-non-interactive-install-safety.md) - 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](https://github.com/lirantal/npq/blob/main/superpowers/specs/2026-08-15-package-manager-shell-free-launching-design.md) - design aprovado para repassar argumentos do gerenciador de pacotes sem reconstrução de comandos shell.
- [Suporte a registro personalizado](https://github.com/lirantal/npq/blob/main/superpowers/specs/2026-07-11-custom-registry-support-design.md) - design aprovado para suporte a Artifactory compatível com npm e registros privados.
- [Detecção JSON para agentes de codificação](https://github.com/lirantal/npq/blob/main/superpowers/specs/2026-08-09-coding-agent-json-detection-design.md) - design aprovado para seleção automática do modo de auditoria JSON em ambientes de agentes de codificação.
- [Saída de auditoria JSON](https://github.com/lirantal/npq/blob/main/superpowers/specs/2026-08-09-json-output-design.md) - 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](https://github.com/lirantal/npq/blob/main/superpowers/specs/2026-07-17-expired-domain-maintainer-identities-design.md) - design aprovado para avisos atribuíveis de domínio expirado.
- [Versão resolvida de domínio expirado](https://github.com/lirantal/npq/blob/main/superpowers/specs/2026-07-17-expired-domain-resolved-version-design.md) - 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](https://github.com/lirantal/npq/blob/main/superpowers/plans/2026-08-24-non-interactive-install-safety.md) - 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](https://github.com/lirantal/npq/blob/main/superpowers/plans/2026-08-15-package-manager-shell-free-launching.md) - plano test-first para lançar gerenciadores de pacotes sem reconstrução de comandos shell.
- [Suporte a registro personalizado](https://github.com/lirantal/npq/blob/main/superpowers/plans/2026-07-11-custom-registry-support.md) - plano de implementação tarefa por tarefa para a issue #429.
- [Detecção JSON para agentes de codificação](https://github.com/lirantal/npq/blob/main/superpowers/plans/2026-08-09-coding-agent-json-detection.md) - plano de implementação test-first para a issue #426 em `npq` e `npq-hero`.
- [Saída de auditoria JSON](https://github.com/lirantal/npq/blob/main/superpowers/plans/2026-08-09-json-audit-output.md) - plano tarefa por tarefa para saída JSON de CLI exclusiva para auditoria e versionada.
- [Versão resolvida de domínio expirado](https://github.com/lirantal/npq/blob/main/superpowers/plans/2026-07-17-expired-domain-resolved-version.md) - 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](https://github.com/lirantal/npq/blob/main/superpowers/plans/2026-07-17-expired-domain-maintainer-identities.md) - plano de implementação test-first para avisos atribuíveis de domínio expirado.