hamza-ali-shahjahan/hamzaish

/tidy — o estágio de limpeza

Rot se acumula em todo repositório: links que apontam para arquivos movidos/gitignorados, uma chave que escapou em um commit, um asset que nada referencia, uma dependência que resulta em 404 na instalação. Nada disso é visível no dia a dia — aparece no pior momento (um 404 do leitor, um CI falhando, uma chave vazada). /tidy é o estágio onde você encontra e limpa isso de propósito.

Este é um estágio, não uma barreira. As guardas rápidas (check-changelog, check-assets) bloqueiam a cada push; /tidy é a varredura ampla e primeiro-relatório que você executa quando é hora de limpar.

Como executar

bun run tidy                      # o repositório atual → resumo + próximos passos recomendados
bun run tidy <caminho>            # um repositório específico
bun run tidy --all ~/Claude       # todo repositório git dentro de uma pasta → uma tabela agregada
bun run tidy --links              # detalhar uma categoria (--secrets --files --deps)

Ele verifica quatro tipos de rot e mostra a extensão primeiro (uma contagem por categoria) para que você nunca receba uma parede de saída:

	o que captura
🔗 Links	links markdown/HTML para arquivos ausentes, ou que resolvem apenas para um alvo gitignorado (funciona no disco do autor, 404 para todos os outros)
🔑 Segredos	padrões de chave confirmados com alta confiança (AWS, Stripe, GitHub, Google, Slack, blocos de chave privada) — sinalizados para revisão, não julgados automaticamente
🗑 Arquivos mortos	imagens/assets commitados que nada referencia — seguros para podar
📦 Deps	dependências do package.json que não resolvem no npm (a classe @inngest/sdk morta)

O fluxo (relate → recomende → pergunte → corrija)

1. Execute. Apresente a tabela resumo — extensão por categoria, por repositório.
2. Recomende. Destaque quais categorias são importantes e por que (um link quebrado é um 404 do leitor; um segredo sinalizado precisa ser rotacionado; uma dependência não resolvível quebra toda instalação).
3. Pergunte. Deixe o operador escolher o que limpar. Nunca assuma.
4. Corrija com confirmação — planeje, depois aplique. bun run tidy --fix <repo> imprime o plano exato de alteração (quais links quebrados serão desvinculados) sem escrever nada; execute novamente com --apply para fazer essas edições. Assim, você sempre vê cada alteração primeiro. A correção automática é propositalmente restrita: ela apenas desvincula links de texto quebrados/gitignorados ([texto](ruim) → texto). Segredos, dependências, imagens/links HTML e exclusões de arquivo nunca são aplicados automaticamente — eles são listados como manuais com orientação (rotacione uma chave, escolha o pacote correto), porque sua correção envolve julgamento, não uma edição de linha. Faça uma varredura ampla com --all, depois --fix em um repositório de cada vez.

Disciplina

• Relatório primeiro, sempre. O valor é ver o rot antes de tocar em qualquer coisa.
• Não barreie com ele. /tidy é lento (verificações de dependência de rede) e amplo — mantenha-o como um estágio, não um bloqueador de push. As guardas restritas continuam sendo a barreira.
• Segredos são para revisão. Uma correspondência de padrão é um convite para olhar, não um veredito — e, se real, a correção é rotacionar a chave, não apenas deletar a linha.
• Diretórios congelados são ignorados (_archive/, node_modules/) — eles não são seus para limpar.
• O motor é portátil. scripts/tidy.ts é executado em qualquer caminho de repositório — é isso que torna a varredura de 100+ repositórios um único comando.