Suporte Técnico
Documentação
Entrar
Entre em contato conosco
Vá direto para um resumo gerado por IA desta postagem do blog 
Lembre-se git blame? Em algum momento, alguém vai executá-lo na base de código herdada, e isso vai trazer à tona decisões que você tomou há anos. Essa pessoa ficará perplexa. Talvez o projeto tenha sido repassado para outra pessoa. Talvez você tenha saído da empresa. TALVEZ, talvez, o projeto tenha sido repassado à comunidade para que ela o desenvolvesse. Mas o problema é que ninguém sabe por que você fez o que fez nem quais eram as restrições que você enfrentava. A pergunta que surge é simples: por que você escolheu esse dep em vez de outro?
As decisões que você toma hoje sobre dependências são uma mensagem para quem, no futuro, herdará a base de código. No entanto, essa mensagem raramente é transmitida. Normalmente, é apenas uma linha em package.json com um intervalo de versões como ^2.4.1 e nada que explique como ela chegou lá. É nessa lacuna que grande parte do gerenciamento de dependências de código aberto acaba fracassando discretamente.
Não é um instantâneo
Adicionar um pacote não significa fixar um artefato estático. Você está herdando uma trajetória. Nos bastidores, há muitos elementos em movimento e pessoas envolvidas quando você incorpora a biblioteca mais recente e avançada, e muitos pacotes trazem dependências transitivas mantidas por pessoas das quais você nunca ouviu falar. O comando de instalação não comunica nada disso. Os mantenedores seguem em frente, e o código também. Um pacote fica inativo por meses, e muitas vezes ninguém percebe até que uma vulnerabilidade CVE venha à tona e não haja ninguém disponível para corrigi-la.
O arquivo de bloqueio ajuda a controlar o que é instalado. Ele registra a árvore resolvida, incluindo versões e, no caso de pacotes do Registro, hashes de integridade, mas não explica por que nada disso está lá. A falta dessa explicação vem à tona mais tarde, geralmente no pior momento possível. Alguém está tentando lançar uma correção de segurança e descobre que a dependência que precisa ser atualizada não tem uma versão nova há anos e ainda é compatível com uma versão do Node.js que está fora de suporte há muito tempo. Isso não é nada bom.
Essa é a base de código que você vai entregar algum dia.
Herdado sem contexto
A pessoa que herdar sua base de código não herdará seu processo de raciocínio. Ela receberá apenas as pistas, com muito pouco contexto. A dependência que você escolheu provavelmente foi a decisão certa, considerando o tempo disponível, o prazo e as alternativas que você pesquisou. Tudo fazia sentido naquele momento. Mas sobreviver à transição é outra história. Se ninguém registrou o raciocínio, a próxima pessoa não conseguirá distinguir uma decisão ponderada de um erro fortuito.
Imagine uma dependência fixada em uma versão antiga, com uma mensagem de commit que diz pin, do not bump. Uma mudança radical na API? Um problema de licença? Um vazamento de memória sob carga? Ninguém sabe dizer se o motivo ainda é válido, então o pin permanece, pois alterá-lo parece mais arriscado. Sem o contexto, uma decisão sensata começa a parecer negligência.
Assim, a próxima pessoa ou confia cegamente na sua decisão ou volta a discutir o assunto do zero. Ambas as opções são caras. A primeira corre o risco de perpetuar algo que, sem que se perceba, acabou se tornando uma decisão equivocada. A segunda desperdiça tempo redescobrindo uma conclusão à qual você já havia chegado.
É aí que uma transferência de código-fonte aberto pode se tornar um pouco complicada. Um fork contém o código, o histórico de commits e toda a documentação que foi incluída no repositório. Ele não inclui os rascunhos nos cadernos, as conversas no Slack ou os comentários nos tickets, onde grande parte do raciocínio estava. A pessoa que assume o projeto precisa reconstruir esse contexto da maneira mais difícil ou acaba perdendo-o em meio a uma enxurrada de PRs.
As transferências de responsabilidade também ocorrem nas etapas iniciais. Em 2018, o mantenedor do event-stream, um pacote popular do npm, delegou o acesso de publicação a um voluntário que se ofereceu para ajudar. Em 9 de setembro, de acordo com o relatório de incidentes do npm, o novo mantenedor acrescentou flatmap-stream como uma dependência com o intervalo ^0.1.0. Em 5 de outubro, [email protected] foi distribuído com código ofuscado que só era ativado na versão final da carteira de bitcoins Copay, onde buscava as chaves privadas. Qualquer instalação que resolvesse esse intervalo de endereços a partir do zero, sem um arquivo de bloqueio para fixá-lo 0.1.0, foi detectada a versão maliciosa. Ela permaneceu lá até que um desenvolvedor a sinalizou em 20 de novembro.
A deterioração é silenciosa, mas a documentação não é
As razões por trás de suas escolhas de dependências não envelhecem da mesma forma. Algumas permanecem válidas por uma década. Outras, não. Algumas se deterioram quase imediatamente. A deterioração geralmente não é visível até que alguém comece a investigar, normalmente por causa de uma verificação de segurança, de algo que chega ao fim da vida útil (EOL) ou de uma auditoria. A manutenção de software e a herança do código aberto se assemelham muito à compra de uma casa antiga. Ninguém presta atenção na fundação até que ela comece a ceder.
npm outdated compara as versões instaladas com os intervalos declarados por você e com a versão mais recente, embora apenas para dependências diretas, a menos que você adicione --all. npm view <package> time mostra quando cada versão foi publicada. Nada disso constitui um indicador de qualidade, já que uma biblioteca madura pode passar anos sem lançar uma nova versão e um repositório muito ativo ainda pode ser mal administrado.
O gerenciamento de dependências de código aberto costuma ser descrito como a escolha, a atualização e a proteção de pacotes. Manter a justificativa atualizada também faz parte dessa lista. As equipes que transferem bases de código de maneira adequada deixam um rastro: por que uma dependência foi escolhida, por que uma versão foi fixada e qual é o plano quando algo chega ao fim da vida útil (EOL).
A parte que você controla
Você não pode controlar tudo, especialmente quem vai manter um pacote daqui a seis anos. Você não pode controlar se um projeto do qual você depende será abandonado, mudará de rumo ou sofrerá um fork. O que você pode controlar é a qualidade da documentação do seu processo. Um registro das decisões e do raciocínio por trás delas deixará a próxima pessoa que herdar o código muito satisfeita.
Cada uma dessas três ferramentas responde a uma pergunta diferente. Um ADR (Architecture Decision Record) explica o porquê, geralmente na forma de um pequeno arquivo Markdown em docs/adr/ registrando o contexto, as opções consideradas, a decisão e suas consequências. Uma SBOM (Software Bill of Materials) responde ao “o quê”. Trata-se de um inventário legível por máquina, geralmente no formato SPDX ou CycloneDX, dos componentes de uma determinada compilação, incluindo dependências transitivas quando o gerador as captura. A proveniência responde ao “onde” e ao “como”. Um pacote publicado com Proveniência do npm De um provedor de CI/CD em nuvem compatível, vem um atestado que o vincula ao seu repositório de origem e à compilação. Isso mostra de onde o código veio, mas não que ele seja seguro.
A documentação reflete a intenção. Ela não pode garantir a integridade dos próprios pacotes. Os registros públicos oferecem medidas de segurança, incluindo assinaturas, suporte à proveniência e remoção de pacotes maliciosos, mas muitos pacotes ainda carecem de proveniência, e nenhum desses controles indica se os editores atuais são os mesmos em que você confiou no momento da adoção.
O SecureChain segue um caminho diferente. Ele recompila pacotes de código aberto a partir de código-fonte verificado em ambientes isolados e fortificados, verifica se há malware e os disponibiliza a partir de um repositório cuidadosamente selecionado. Os pacotes vêm com proveniência SLSA Nível 3 para a recompilação e dados do VEX (Vulnerability Exploitability eXchange) indicando quais vulnerabilidades conhecidas os afetam, quais não os afetam e quais foram corrigidas. Dependendo do pacote, eles também incluem uma SBOM (lista de materiais de software) de seus componentes.
Eventualmente, algum componente da sua árvore de código chegará ao fim de vida útil, o ponto em que seus mantenedores deixam de disponibilizar correções de segurança, e é provável que isso aconteça depois que você já tiver saído. O Suporte de Ciclo de Vida Ilimitado (ELS) retroporta correções de segurança para versões em fim de vida que ainda são suportadas, de modo que uma versão coberta que já esteja em produção continue recebendo correções. A equipe que herdar sua base de código não será forçada a escolher entre manter o sistema sem correções ou fazer uma reescrita de emergência sob pressão. Isso lhes dá tempo para tomar uma decisão ponderada sobre a migração, em vez de uma decisão tomada em pânico.
Considerações finais
Cada dependência que você adiciona é um compromisso contínuo que você assume perante quem quer que seja o próximo responsável pela manutenção do projeto. O código sobrevive às equipes, às funções e às empresas. Ao documentar o motivo por trás de suas escolhas de dependências, manter um registro verificável do que você lança e se preparar para o dia em que o suporte do desenvolvedor original chegar ao fim, você dá à base de código que um dia entregará uma chance real de se tornar um ativo, e não uma armadilha.
