repoviz

¿Qué hace repoviz?

Convierte un código base en URLs de diagrama listas para renderizar. Cada diagrama es una única URL https://x-cmd.com/draw (plana, con parámetros codificados en porcentaje) que renderiza SVG en navegadores, READMEs de GitHub y cualquier visor Markdown. El modo predeterminado no escribe archivos locales; la exportación local solo ocurre bajo petición explícita mediante scripts/.

Los renders son verificables: cada nodo y arista lleva evidencia de origen (verificada / inferida / desconocida). El resultado es un activo verificable, no un boceto de IA.

Paso 1 — Análisis de intención y enrutamiento de gráficos

Selecciona el tipo de diagrama según la intención del usuario y la forma del repositorio. Lee solo los archivos references/ correspondientes antes de construir cada diagrama.

Intención del usuario	Diagrama	Referencia
Vista general del sistema, jerarquía de carpetas, microservicios, stack tecnológico	Mapa de arquitectura (/draw/archmap)	references/architecture.md
Ciclo de vida de solicitudes, cadenas de llamadas a funciones, handshakes de API	Diagrama de secuencia (/draw/seq)	references/flowchart.md
Lógica de ramificación, algoritmos, etapas de autenticación/pipeline	Diagrama de flujo (/draw/mermaid)	references/flowchart.md
Máquinas de estado, estados, reintentos/rollback	Ciclo de vida (/draw/lifecycle)	references/flowchart.md
Pipelines de datos, pesos de dependencias/paquetes, enrutamiento de tráfico	Sankey (?type=sankey)	references/sankey.md
Árboles de características, taxonomía de módulos	Mapa mental (/draw/mindmap)	references/general-charts.md
Hojas de ruta, cronogramas, planes de lanzamiento	Gantt (/draw/gantt)	references/general-charts.md
Métricas cuantitativas del repositorio (división de lenguajes, cobertura, crecimiento)	Gráficos de datos (`?type=pie	hbar
Amplio "visualizar este repositorio"	Suite multi-diagrama: 1 resumen archmap + 1 Sankey (flujo de datos/dependencias) o seq (flujo de solicitudes principal)	las dos referencias correspondientes

Hermanos de misma gramática de archmap (ver references/architecture.md): arch2 (piel alternativa). Modelado de datos/comportamiento: uc, dataflow, erd, class — gramáticas y ejemplos en vivo en references/technical-diagrams.md. Gráficos de cola larga (treemap, funnel, graph, ...): /draw/echarts?d=<url-encoded echarts option JSON>.

Modos de escaneo — define el alcance del escaneo antes de leer el código (el usuario puede elegir; por defecto según la intención):

Modo	Alcance	Salida típica
quick	Manifiestos, árbol hasta profundidad 2, puntos de entrada	1 diagrama de resumen
architecture	Módulos, servicios, grafo de dependencias	archmap (+ Sankey por peso)
deep-dive	Cadenas de llamadas, flujo de datos, máquinas de estado	seq / diagrama de flujo / suite Sankey
impact	git diff vs base: archivos modificados y sus dependientes	Diagrama de flujo de cambios
full	Todo lo anterior	Informe del repositorio (suite + informe de calidad)

El modo impact carga references/architecture-diff.md (flujo de trabajo de delta git diff); el modo full carga references/codebase-report.md (estructura de informe estándar); escaneos repetidos del mismo repositorio pueden cargar references/incremental-scan.md (protocolo de caché opt-in); el trabajo multi-diagrama o sensible a evidencia carga references/repository-ir.md.

Paso 2 — Escaneo del código base con disciplina de tokens

1. Lee primero los manifiestos raíz: package.json, go.mod, Cargo.toml, pyproject.toml, docker-compose.yml, más un árbol de directorios hasta profundidad 3 y los puntos de entrada declarados.
2. Nunca leas cada archivo fuente. Muestrea archivos de punto de entrada y tablas de rutas; resume componentes en nodos y aristas de alta señal.
3. Deriva pesos Sankey de cantidades reales cuando sea posible: tamaños de archivo (du -sh), conteos de importaciones/referencias, o cifras de tráfico/costo que el usuario proporcione.
4. Guardarraíl de longitud de URL: mantén un diagrama en ~15–20 nodos (~60 enlaces para Sankey) para que las URLs sigan siendo legibles y dentro de los límites de CDN. Para repositorios grandes, emite un diagrama de resumen de alto nivel + un diagrama por subsistema, nunca un único mega-diagrama denso.
5. Detecta el lenguaje y stack a partir de los manifiestos y escanea con ese enfoque: Go → paquetes/interfaces/gorutinas; TypeScript → módulos/grafo de importaciones/rutas API; Rust → crates/traits/características; Python → paquetes/decoradores/puntos de entrada.
6. Registra la evidencia a medida que escaneas: cada nodo/arista obtiene file[:symbol[:lines]] y un nivel — verificada (vista en el código), inferida (derivada de la estructura), o desconocida (suposición de patrón). Nunca marques como verificada sin abrir el archivo.

Paso 3 — Construir la URL

• Construye primero el IR ligero del repositorio para suites (un inventario de nodos compartido, un documento por diagrama); mapea IR → URL en tiempo de codificación. Esquema y protocolo de validación: references/repository-ir.md.
• Cada URL que construyas lleva sus etiquetas al renderizador — aplica la regla de confidencialidad del Paso 4 antes de construirla, validarla o exportarla.
• Gramática (nodos/aristas/límites), tabla de codificación, ejemplos prácticos y límites por tipo viven en los archivos de referencia. Síguelos exactamente; cada ejemplo allí está probado en vivo.
• Esenciales de codificación: espacio %20, + %2B, & %26, # %23, </> %3C/%3E, nueva línea %0A; separadores ; = , : / @` se quedan literales. Sin Base64.
• Modificadores comunes: title=, scheme=dark|light, t=<style> (familias por tipo en referencias — arch2/seq se ven mejor con t=shadcn; los nodos arch2 toman un 6º campo opcional icon, ej. n=api;be;API;ECS;r2c0;aws:ecs), w=/h=, v=N para fijar una versión en caché, num=all|peak|none (gráficos).
• La salida PNG incrusta un subconjunto CJK de nivel 1 GB2312: caracteres raros (ej. 渲) se vuelven tofu en PNG. SVG no tiene ese límite — prefiere sinónimos comunes para etiquetas chinas en PNG.
• En un 4xx, el cuerpo de la respuesta es texto plano con un ejemplo de corrección — léelo, arregla el parámetro problemático, reintenta. Nunca adivines dos veces.

Paso 4 — Entrega de la salida

Modo predeterminado — sin escritura de archivos. Responde con, por diagrama:

### <Título del diagrama>
![<título>](<draw-url>)
*[Vista previa interactiva](<draw-url>)* · [Abrir en editor](<explore-url>)

- <viñeta: qué muestra el diagrama — niveles, ruta crítica, flujos más pesados>
- <viñeta: acoplamiento notable / puntos únicos de fallo / límites de propiedad>

• <explore-url> reescribe /draw?type=X&q → /draw/explore?type=X&q y /draw/<name>?q → /draw/explore/<name>?q — el editor interactivo integrado de draw; enlázalo, no lo reconstruyas.
• 2–5 viñetas concisas por diagrama. La imagen es el entregable; las viñetas añaden criterio.
• Confidencialidad: el renderizado — y la validación L1, y las descargas de export.sh — envían las etiquetas del diagrama (para diagramas de flujo, el texto completo del programa) al renderizador de x-cmd.com como parámetros de URL; pueden aparecer en los registros de acceso del servidor (la codificación porcentual no es cifrado), y las inserciones de imagen Markdown pueden ser recuperadas automáticamente por clientes o proxies. La exportación local no evita esto — el render sigue solicitándose desde x-cmd.com. Para repositorios confidenciales, advierte al usuario y obtén aprobación explícita antes de renderizar, validar o exportar — o renderiza completamente sin conexión mediante una CLI de draw instalada localmente.

Cierra una suite con el informe de calidad (solo conteos reales — nunca inventes):

Repository Analysis — <repo> (<scan_mode>, <commit>)
Files inspected: N | Modules: N | Relationships: N
Evidence: verified N · inferred N · unknown N
Validation: L1 pass|skipped (privacy) · L2 pass · L3: N unresolved (flagged below)

L1 no es automático — obtiene la URL, es decir, envía el diagrama a x-cmd.com. Para repositorios confidenciales, ejecútalo solo con la aprobación explícita del usuario (regla de confidencialidad del Paso 4); de lo contrario, informa L1 skipped (privacy). Marca cada unknown debajo de su diagrama. Para solicitudes explícitas de "validar" o verificaciones previas a la exportación: bash scripts/validate.sh <urls...> (renderización L1) y bash scripts/validate.sh --ir <ir.json> (estructura L2). L3 es tu relectura de los archivos citados.

Modo de exportación — solo cuando el usuario dice explícitamente "guardar localmente", "descargar SVG/PNG", "exportar imagen", "enlace corto", "poner esto en mi README" o "generar informe HTML":

bash scripts/export.sh "<draw-url>" "<out.svg|png>"        # descarga única
bash scripts/export.sh --batch <manifest.tsv>              # muchos: "<url>\t<out>" por línea, # comentarios
bash scripts/shorten.sh <type> '<d-schema json>' [title]   # permanente /draw/c/<hash> (solo gráficos ?type=)
bash scripts/build_html.sh "<title>" "<out.html>" '<json>'   # informe independiente (+ evidencia opcional)
bash scripts/inject_readme.sh "<README.md>" '<json>'       # insertar/actualizar diagramas entre marcadores repoviz

• export.sh descarga mediante curl (alternativa: CLIs ya instaladas localmente — nunca obtiene o instala paquetes); los destinos .png obtienen automáticamente &format=png (añade &scale=2|3 para mayor resolución; pasa scheme=dark — PNG por defecto usa claro). Modo por lotes: una url<TAB>salida por línea, se permiten comentarios #; sale con error si algún elemento falla.
• shorten.sh envía por POST la definición del gráfico (el esquema JSON ?d=) a x-cmd.com — límite de tasa ~30/min/IP. Solo la familia ?type= acepta POST; los diagramas de nodos/aristas (/draw/archmap, /draw/seq, ...) devuelven 405 — mantén sus URLs completas. La URL devuelta /draw/c/<hash> renderiza con GET y es permanente. Ejecútalo solo bajo solicitud explícita del usuario: la definición almacenada es permanente y pública para cualquiera que tenga el enlace (regla de confidencialidad del Paso 4).
• build_html.sh toma un array JSON de objetos {"title","url","note"[,"ev"]} (url restringido a URLs de render de draw https://x-cmd.com / https://www.x-cmd.com; ev opcional, codificado como "node|file|symbol|lines|level;..." — renderiza una tabla de evidencia de origen filtrable) y emite un informe responsive oscuro/claro autocontenido: navegación lateral, zoom, pantalla completa, botones de copiar URL, apto para impresión a PDF. Todos los valores están escapados en HTML. Ejemplo de carga útil: [{"title":"Architecture","url":"https://x-cmd.com/draw/archmap?...","note":"3 niveles; gateway es la única entrada","ev":"api|src/api.ts|createServer|12-40|verified"}]
• inject_readme.sh es idempotente: añade un bloque <!-- repoviz:start --> … <!-- repoviz:end --> (imagen Markdown + nota por diagrama) en el primer uso, lo reemplaza en el mismo lugar en ejecuciones posteriores — los diagramas se convierten en activos vivos en el repositorio.
• Después de exportar, imprime la(s) ruta(s) guardada(s) y continúa generando el bloque Markdown para el chat, para que el usuario obtenga ambos.

Reglas

• Neutralidad de marca: presenta los resultados como diagramas repoviz; nunca renombres o envuelvas las URLs de render.
• Un escaneo, muchos diagramas: reutiliza el inventario de nodos en toda la suite en lugar de releer el repositorio por diagrama.
• Prefiere menos nodos bien elegidos sobre la completitud; colapsa detalles en subtítulos sub y cajas de límites.
• Evidencia o no sucedió: cada nodo/arista está verificado, inferido o marcado como desconocido — nunca inventado. Mantén la división IR/renderizador para que las suites, informes y diferencias de arquitectura futuras compartan un inventario; el renderizado sigue siendo un adaptador reemplazable.
• Ediciones incrementales basadas en URL: un diagrama repoviz existente está completamente definido por su URL — nunca uses herramientas de visión o lectura de imágenes para inspeccionarlo. Decodifica la URL del Markdown, compara su conjunto de nodos/aristas con el código actual y emite la URL actualizada en el mismo lugar, preservando ids de nodo, etiquetas y convenciones de diseño.