Dir2md + Spicy: un escáner de repositorios que genera de una vez contexto Markdown/JSONL para LLM y reportes de seguridad
(github.com/flamehaven01)Hola. Hace unos tres meses presenté Dir2md por primera vez.
Desde entonces, al aplicarlo a diversos proyectos, quedaron en evidencia ciertas limitaciones estructurales, así que rehice por completo el algoritmo, la seguridad y todo el pipeline de salida.
❔¿Qué es Dir2md?
Dir2md es una herramienta que convierte estructuras de directorios complejas en contexto Markdown y JSONL compatible con IA, con muestreo inteligente, enmascaramiento de seguridad y control de presupuesto de tokens. Organiza automáticamente el repositorio en una forma optimizada para el desarrollo asistido por IA.
🔧 Qué cambió — resultado de una renovación completa durante 3 meses
1) Rediseño del motor de optimización para IA
- Incorporación de muestreo inteligente de head/tail por archivo
- Refinamiento de la lógica de asignación automática del presupuesto de tokens
- Reorganización de la estructura de selección prioritaria de archivos importantes
- Construcción de un pipeline de salida múltiple para Markdown, JSON, JSONL y manifest
2) Incorporación de Spicy (analizador de seguridad y riesgo)
- Integración de un escáner de riesgos incorporado que se activa por defecto al ejecutarse
- Aplicación de un sistema de severidad de 5 niveles, de ok a critical
- Cálculo de una puntuación de riesgo de 0 a 100 por repositorio
- Salida de una Actionable Risk Table con archivo/línea/categoría/guía de respuesta
3) Refuerzo del motor de enmascaramiento de seguridad
- Enmascaramiento automático de patrones clave como API keys, JWT, OAuth, DB URL y PEM
- Incorporación de expresiones regulares personalizadas y función de carga de archivos de patrones
4) Incorporación de deduplicación basada en SimHash
- Eliminación de archivos similares y artefactos de build
- Minimización del desperdicio de tokens duplicados en el contexto de entrada para LLM
5) Expansión del sistema de presets
- Configuración de cuatro modos:
raw,pro,ai,fast - El modo
aiincluye presupuesto de 6000 tokens + ranking de archivos basado en consultas
🌶️ ¿Qué es Spicy?
En una frase, Spicy es “un revisor automático como un desarrollador senior de mirada severa que nunca ha sido indulgente con la seguridad”.
Dir2md no es solo una herramienta para “documentar directorios”, sino que también realiza de una vez las revisiones de seguridad y calidad que son imprescindibles antes de pasar un repositorio a una IA.
1) Detección de información sensible
- Detección de patrones que pueden derivar en incidentes reales, como API Key, OAuth Client Secret, JWT, DB URL y claves PEM
2) Análisis de cifrado débil y uso de seguridad vulnerable
- Detección de código con problemas de seguridad, como algoritmos vulnerables y manejo inseguro de claves
3) Diagnóstico de posibles inyecciones
- Detección de patrones similares a SQL/Command/Code Injection
4) Exposición de datos por logs o debug
- Detección de código/configuraciones que imprimen información sensible
5) Problemas de control de acceso
- Análisis de patrones con fallas relacionadas con autenticación y permisos
- También detecta señales de riesgo de configuración mencionadas en el README
📊 Resultados medidos en 9 repositorios internos de producción
Después del rediseño de Dir2md + Spicy, estos son los valores reales medidos hasta ayer:
- Promedio de 2.4 detecciones de información sensible de nivel high/critical por repositorio
- API keys, claves privadas PEM, DB URL, bearer token, etc.
- Reducción promedio del 68% en el tamaño del contexto
- 128k → ~41k tokens (se conservaron todos los archivos significativos)
- Tiempo de revisión de seguridad: de 3.5 horas antes → 11 segundos
- Secretos filtrados a prompts de LLM desde la adopción: 0 casos
Este resultado corresponde al rendimiento en un entorno operativo real cuando se combinan muestreo inteligente · deduplicación con SimHash · análisis de riesgo con Spicy · motor de enmascaramiento.
⭐ Si te fue útil para tu proyecto
Dir2md + Spicy es open source.
La mayoría de las funciones que ves ahora pudieron evolucionar gracias al feedback de los usuarios y a las estrellas (⭐). Muchas gracias nuevamente.
- 👉 ¡Un GitHub Star ayuda muchísimo!
- 👉 Las propuestas de bugs e ideas también son siempre bienvenidas.
2 comentarios
📌 Resumen de las principales actualizaciones desde dir2md v1.1.2
v1.2.1 (parches de seguridad/confiabilidad)
vulture) → bloqueo del vector de RCEdefaults.json+ incorporación de un sistema de prioridadesv1.2.0 (autooptimización inteligente)
Pipeline de reducción de tokens del 60~70% que funciona sin configuración
Corrección automática de errores tipográficos + expansión de búsqueda al usar
--queryGran reducción de flags con un diseño centrado en presets (raw/fast/pro/ai)
Implementado sin dependencias externas de NLP/LLM
v1.1.3
👉 En resumen, desde la serie 1.2.x es un lanzamiento enfocado en “menos configuración y más seguridad, determinismo y compatibilidad con IA”.
(se mantiene la compatibilidad hacia atrás, sin cambios incompatibles en el CLI)
Fuente: CHANGELOG
🚂 ¡Lanzamiento de dir2md 1.1.2!
Esta actualización parece pequeña por fuera, pero reúne solo cambios que impactan directamente la estabilidad en uso real.
🛡 Security
🔸Precompilación de las expresiones regulares de enmascarado básico/avanzado → reduce el riesgo de ReDoS
🔸Los archivos de más de 1 MB se omiten antes de leerse y solo se deja registro en el manifest
⚙️ Performance
🔸Se aplicó una caché LRU (2048) a la estimación de tokens → mejora de velocidad en repositorios grandes
🔸Incluso las cadenas vacías se tratan como mínimo 1 token → elimina la ambigüedad de “0 tokens”
🧩 UX / Behavior
🔸Los archivos omitidos dejan un hash/resumen de marcador de posición para mayor transparencia
🔸Si falla la compilación de patrones de enmascarado personalizados, se ignoran tras una advertencia (evita fallos silenciosos)
✅ Tests
🔸22 passed, 2 skipped
Aunque es una versión pequeña, corrimos todas las pruebas.
El objetivo de esta versión es uno solo:
“¿Se puede ejecutar todos los días en CI y sobre código real de producción?”
Ahora estamos un paso más cerca.
https://github.com/flamehaven01/Dir2md/releases/tag/v1.1.2