Dir2md + Spicy: o scanner de repositórios que gera de uma vez contexto em Markdown/JSONL para LLMs e relatórios de segurança
(github.com/flamehaven01)Olá. Cerca de três meses atrás, apresentei o Dir2md pela primeira vez.
Desde então, ao aplicá-lo em vários projetos, algumas limitações estruturais ficaram evidentes, e por isso reorganizei completamente os algoritmos, a segurança e todo o pipeline de saída.
❔O que é o Dir2md
O Dir2md é uma ferramenta que converte estruturas complexas de diretórios em contexto Markdown·JSONL amigável para IA, com smart sampling, mascaramento de segurança e controle de orçamento de tokens. Ele organiza automaticamente o repositório em um formato otimizado para desenvolvimento assistido por IA.
🔧 O que mudou — resultado de uma reformulação completa ao longo de 3 meses
1) Redesenho do motor de otimização para IA
- Introdução de smart sampling de head/tail por arquivo
- Refinamento da lógica de distribuição automática de orçamento de tokens
- Reorganização da estrutura de seleção prioritária de arquivos importantes
- Criação de um pipeline de saída múltipla para Markdown, JSON, JSONL e manifest
2) Introdução do Spicy (analisador de segurança e risco)
- Inclusão de um scanner de risco embutido ativado por padrão na execução
- Aplicação de um sistema de 5 níveis de severidade, de ok até critical
- Cálculo de uma pontuação de risco de 0 a 100 por repositório
- Geração de uma Actionable Risk Table com arquivo/linha/categoria/guia de resposta
3) Reforço do motor de mascaramento de segurança
- Mascaramento automático de padrões importantes como API keys, JWT, OAuth, DB URL e PEM
- Introdução de regex personalizadas e da função de carregamento de arquivos de padrões
4) Introdução de deduplicação baseada em SimHash
- Remoção de arquivos semelhantes e artefatos de build
- Minimização do desperdício de tokens duplicados no contexto de entrada para LLMs
5) Expansão do sistema de presets
- Configuração de quatro modos:
raw,pro,ai,fast - O modo
aiinclui orçamento de 6000 tokens + ranking de arquivos baseado em consulta
🌶️ O que é o Spicy?
Em uma frase, o Spicy é “um revisor automático com olhar afiado de um desenvolvedor sênior que nunca foi tolerante com segurança”.
O Dir2md não é apenas uma ferramenta para “documentar diretórios”; ele também executa de uma vez as verificações de segurança e qualidade que são indispensáveis antes de enviar um repositório para uma IA.
1) Detecção de informações sensíveis
- Detecta padrões que podem levar a incidentes reais, como API Key, OAuth Client Secret, JWT, DB URL e chaves PEM
2) Análise de criptografia fraca e uso inseguro de segurança
- Detecta código com problemas de segurança, como algoritmos vulneráveis e tratamento inseguro de chaves
3) Diagnóstico de possibilidade de injeção
- Detecta padrões semelhantes a SQL/Command/Code Injection
4) Exposição de dados por logs e debug
- Detecta código/configurações que imprimem informações sensíveis
5) Problemas de controle de acesso
- Analisa padrões com brechas relacionadas a autenticação e permissões
- Também detecta sinais de risco de configuração mencionados no README
📊 Resultados reais medidos com base em 9 repositórios internos de produção
Após o redesenho do Dir2md + Spicy, os números reais medidos até ontem são os seguintes:
- Média de 2,4 detecções de informações sensíveis de nível high·critical por repositório
- API keys, chaves privadas PEM, DB URL, bearer token etc.
- Redução média de 68% no tamanho do contexto
- 128k → ~41k tokens (mantendo todos os arquivos significativos)
- Tempo de revisão de segurança: de 3,5 horas para 11 segundos
- Número de segredos vazados em prompts de LLM desde a adoção: 0
Este resultado reflete o desempenho em ambiente real de operação quando smart sampling · deduplicação com SimHash · análise de risco do Spicy · motor de mascaramento são combinados.
⭐ Se o projeto ajudou você
Dir2md + Spicy é open source.
A maior parte dos recursos que você está vendo agora pôde evoluir graças ao feedback dos usuários e às estrelas (⭐). Mais uma vez, muito obrigado.
- 👉 Uma estrela no GitHub faz uma grande diferença!
- 👉 Sugestões de bugs e ideias também são sempre bem-vindas.
2 comentários
📌 Resumo das principais atualizações desde o dir2md v1.1.2
v1.2.1 (patches de segurança/confiabilidade)
vulture) → bloqueio de vetor de RCEdefaults.json+ introdução de sistema de prioridadev1.2.0 (auto-otimização inteligente)
Pipeline com redução de 60~70% de tokens que funciona sem configuração
Correção automática de typos + expansão de busca ao usar
--queryGrande redução de flags com design centrado em presets (raw/fast/pro/ai)
Implementado sem dependências externas de NLP/LLM
v1.1.3
👉 Em resumo, a partir da 1.2.x, é um release focado em “menos configuração, mais segurança, determinismo e compatibilidade com IA”.
(Compatibilidade retroativa mantida, sem breaking changes na CLI)
Fonte: CHANGELOG
🚂 Lançamento do dir2md 1.1.2!
Esta atualização parece pequena por fora, mas reúne apenas mudanças que impactam diretamente a estabilidade no uso real.
🛡 Security
🔸Pré-compilação das regex de mascaramento padrão/avançado → redução do risco de ReDoS
🔸Arquivos com mais de 1MB agora são ignorados antes da leitura, deixando apenas o registro no manifest
⚙️ Performance
🔸Aplicação de cache LRU (2048) na estimativa de tokens → melhora de velocidade em repositórios grandes
🔸Até strings vazias agora contam como no mínimo 1 token → elimina a ambiguidade de “0 token”
🧩 UX / Behavior
🔸Arquivos ignorados deixam um hash/resumo placeholder, aumentando a transparência
🔸Padrões de mascaramento personalizados agora emitem aviso e são ignorados se a compilação falhar (evita falhas silenciosas)
✅ Tests
🔸22 passed, 2 skipped
É um lançamento pequeno, mas todos os testes foram executados.
O objetivo desta versão é um só:
“Dá para rodar isso todos os dias no CI e em código real de produção?”
Agora estamos um passo mais perto disso.
https://github.com/flamehaven01/Dir2md/releases/tag/v1.1.2