package.json como raio-X da stack

O que as dependências revelam

Antes de abrir qualquer arquivo de código, o package.json já conta boa parte da história de um projeto. As dependências de produção mostram o framework e as decisões de arquitetura por trás dele: se é uma SPA com uma lib de state management separada, um app full-stack resolvido dentro de um único framework, ou algo montado por peças, sem uma escolha central óbvia.

As versões contam a era. Uma dependência major desatualizada há várias versões diz que o projeto parou de acompanhar o ecossistema em algum momento. E normalmente não por acaso, e sim porque atualizar teria custado caro demais para caber no que estava sendo priorizado na época. Isso não é julgamento sobre quem manteve o projeto; é um dado sobre quanto trabalho existe pela frente antes de mexer em qualquer coisa que dependa dessa versão específica.

devDependencies mostra a disciplina do projeto: existe lint, formatação, teste automatizado, ou o package.json só tem o essencial para rodar? Os scripts revelam o fluxo real de desenvolvimento: se build encadeia várias ferramentas em sequência, isso é uma dívida de complexidade que não está documentada em nenhum outro lugar além desse arquivo.

Nada disso exige rodar o projeto. É leitura de metadado, não de comportamento — mas já reduz bastante a distância entre "não sei nada sobre esse código" e "sei o suficiente para fazer a próxima pergunta certa".

Sinais de alerta

Majors atrasados. Uma dependência central do projeto — o framework, o ORM, o bundler — presa numa major antiga, enquanto o resto do ecossistema já migrou, é o sinal mais direto de dívida técnica acumulada. Quanto maior a distância em majors, maior a chance de a migração exigir mudanças em cascata, não só um bump de versão isolado.

Libs abandonadas. Uma dependência sem release recente, especialmente uma que ocupa um papel estrutural (autenticação, roteamento, data fetching), é um risco silencioso: ela continua funcionando até parar de funcionar — um problema de segurança sem correção, uma incompatibilidade com a versão nova de outra dependência — e nesse momento a decisão de trocar deixa de ser planejada e vira emergencial.

Duplicação de papel. Duas libs resolvendo o mesmo problema — dois clientes HTTP, dois gerenciadores de estado, duas libs de data fetching — geralmente não é uma escolha deliberada. É o rastro de uma migração que começou e não terminou, ou de decisões tomadas em momentos diferentes por pessoas diferentes sem revisar o que já existia no projeto. Cada duplicação desse tipo é peso morto: mais uma API para o time conhecer, sem benefício correspondente.

Nenhum desses sinais, isolado, decide algo. Eles apontam onde a próxima investigação deveria começar. Um trecho hipotético de dependências já deixa isso visível sem precisar abrir nenhum outro arquivo:

{
  "dependencies": {
    "react": "16.8.0",
    "redux": "^4.0.0",
    "zustand": "^4.4.0",
    "axios": "^0.21.0",
    "node-fetch": "^2.6.0"
  }
}

Nesse exemplo ilustrativo, três sinais aparecem juntos: uma major de framework presa várias versões atrás do que o ecossistema já adotou como padrão; duas libs de state management convivendo no mesmo projeto, provavelmente uma migração que parou no meio; e dois clientes HTTP diferentes fazendo o mesmo trabalho. Nenhum desses pontos, sozinho, justifica parar tudo — mas juntos, formam uma lista concreta de perguntas para investigar, em vez de uma sensação vaga de que "a stack está desatualizada".

Do diagnóstico à decisão

Ler o package.json é diagnóstico, não decisão. Ele aponta os pontos de atenção; não diz se vale a pena agir sobre eles agora, nem qual é a melhor forma de agir. Essa segunda parte — decidir se atualiza, troca ou convive com o que está lá — é o tipo de pergunta que se responde melhor com um spike do que com uma reunião: um período curto e definido de antemão para testar, na prática, o que uma major atrasada quebra ao subir, ou como uma lib candidata a substituir a duplicada se comporta integrada ao resto do projeto.

O diagnóstico feito a partir do package.json já entrega metade do trabalho de preparar esse spike: ele define exatamente qual pergunta investigar — essa dependência, essa versão específica — em vez de um "vamos modernizar a stack" genérico demais para caber em qualquer time-box.

Isso também muda a conversa dentro do time. "Precisamos modernizar a stack" é uma afirmação sobre a qual é difícil discordar ou concordar, porque não aponta para nada específico o suficiente para ser testado. "O client HTTP duplicado carrega peso desnecessário no bundle e a lib mais antiga das duas está sem release há muito tempo" é uma afirmação verificável: dá para checar se é verdade, dá para decidir se importa agora ou depois, e dá para transformar num spike com escopo definido, em vez de discutir a stack inteira de uma vez.

Onde o SpikeMe entra

O SpikeMe parte do mesmo princípio — o package.json como ponto de partida — para gerar o diagnóstico inicial de uma stack. A análise roda no navegador; o package.json não é enviado aos servidores, só um resumo do que foi identificado localmente compõe o pedido usado para gerar o documento de spike. Para tentar com o package.json do seu projeto, veja spikeme.io.