CodeGraph Visual
Documentación
Abrir aplicación
Manual práctico · de cero a diagnóstico

Entiende cualquier codebase
como un sistema.

Abre el índice de CodeGraph, sigue dependencias y convierte una base de código compleja en respuestas visuales. Cada capítulo incluye una demo funcional: los análisis de esta página se ejecutan de verdad sobre un proyecto de ejemplo, y en cobertura y trazas puedes pegar tus propios archivos.

Sin subir el repositorio Índice en solo lectura 9 demos interactivas Reportes exportables
ELIGE TU OBJETIVO

No tienes que leer todo para empezar

Elige la pregunta que necesitas responder y sigue ese recorrido.

01
CONFIGURACIÓN

Primeros pasos

En cinco minutos puedes pasar de una carpeta de código a un grafo navegable. La web lee el índice SQLite que CodeGraph genera; no analiza ni modifica tu repositorio.

1

Crea el índice

Abre una terminal e inicializa CodeGraph apuntando a la raíz del proyecto.

PowerShell
codegraph init C:\ruta\al\proyecto
2

Selecciona la raíz

En la aplicación, pulsa “Abrir proyecto indexado” y elige la carpeta que contiene .codegraph. No selecciones .codegraph directamente.

3

Busca una primera respuesta

Abre un punto de entrada como main, un controlador o una ruta HTTP; después cambia la dirección y la profundidad del grafo.

4

Mantén el mapa al día

Después de cambiar el código, sincroniza el índice y vuelve a abrir el proyecto.

PowerShell
codegraph sync C:\ruta\al\proyecto
Sabes que funcionó cuando…

ves el nombre del proyecto, sus métricas y los puntos de entrada. Si la base está en material_scraper/.codegraph/codegraph.db, debes seleccionar material_scraper.

02
NAVEGACIÓN

La interfaz

1ExploradorBúsqueda, puntos de entrada y filtros.
2LienzoNodos, conexiones, controles y minimapa.
3InspectorMetadatos, acciones, código y resultados.
BuscarEscribe dos o más caracteres para buscar símbolos.
DirecciónCambia entre relaciones entrantes, salientes o ambas.
ProfundidadControla cuántos saltos recorre el vecindario.
CódigoEl inspector resalta las líneas exactas del símbolo.
Selecciona una preguntaPrepara la vista en el lienzoInspecciona o exporta la evidencia
02B
NAVEGACIÓN POR RUTAS

Explorador de archivos

Abre la pestaña Archivos de la barra izquierda para recorrer el proyecto aunque todavía no conozcas el nombre de ningún símbolo.

  • Expande carpetas y subcarpetas como en un editor.
  • Filtra por cualquier parte de la ruta o del nombre del archivo.
  • Selecciona un archivo para listar sus clases, funciones y demás símbolos.
  • Pulsa un símbolo para abrirlo en el grafo y ver su código.

De la carpeta al grafo

El árbol se construye desde el índice local. Los símbolos del archivo se consultan solo cuando lo seleccionas, por lo que funciona también en proyectos grandes.

Ejemplosrc → services → orders.ts → createOrder
03
CONCEPTOS

Qué significa cada relación

RelaciónSignificadoEjemplo
callsUna función invoca otramain → start_pipeline
referencesUn símbolo utiliza o menciona otroOrderService → Order
importsUn archivo o módulo importa otroroutes.py → services.py
instantiatesSe crea una instancia de una clasehandler → Repository
extendsHerencia entre clasesAdminUser → User
implementsImplementación de una interfazSqlRepo → Repository
containsContención estructuralarchivo → clase → método
04
MODO BASE

Explorar símbolos

Selecciona un símbolo para revelar su vecindario. Usa las direcciones para responder preguntas distintas:

  • Entrantes: quién depende del símbolo.
  • Salientes: qué utiliza el símbolo.
  • Ambas: contexto completo.
La demo de al lado funciona de verdad: cambia la raíz, la dirección y la profundidad, y pulsa un nodo para inspeccionarlo.
Explorador de símbolosCambia la raíz, la dirección y la profundidad como en la aplicación.
Dirección
11Símbolos
10Relaciones
9Archivos
methodcreateOrderservices/orders.ts:22-72
createOrder(cart: Cart, session: Session): Promise<Order>
  • calls postCheckoutlínea 31
  • calls postOrderlínea 38
  • contains OrderServicelínea 22
  • calls validateCartlínea 27
  • calls processPaymentlínea 41
  • calls savelínea 58
Datos del proyecto de ejemplo “storefront”: 27 símbolos, 50 relaciones, 15 archivos.
05
CAMBIOS SEGUROS

Radio de impacto

Impacto recorre dependencias entrantes hasta cinco niveles, agrupa los símbolos afectados por archivo y señala las pruebas conectadas.

  • Sube los niveles para ver hasta dónde se propaga un cambio.
  • Si no aparece ninguna prueba, el cambio viaja sin red de seguridad.
  • El recuento por archivo indica dónde concentrar la revisión.

Empieza por lo más compartido

Cambiar una utilidad de bajo nivel como query o formatMoney suele afectar más superficie que una ruta HTTP.

Radio de impactoRecorre dependencias entrantes y agrupa lo afectado por archivo.
14Símbolos afectados
9Archivos
2Pruebas conectadas
querydb.ts
saveorders.ts
findByIdorders.ts
withTransactiondb.ts
getOrdersorders.ts
createOrderorders.ts
markOrderPaidorders.ts
processPaymentpayments.ts
refundPaymentpayments.ts
handleReceiptQueuereceipts.ts
postCheckoutcheckout.ts
postOrderorders.ts
retryPaymentpayments.ts
testCreateOrderorders.test.ts
testProcessPaymentpayments.test.ts
services/payments.ts3 símbolos
api/routes/orders.ts2 símbolos
repositories/orders.ts2 símbolos
services/orders.ts2 símbolos
api/routes/checkout.ts1 símbolo
repositories/db.ts1 símbolo
tests/orders.test.ts1 símbolo prueba
tests/payments.test.ts1 símbolo prueba
workers/receipts.ts1 símbolo
Al cambiar query deberías ejecutar tests/orders.test.ts, tests/payments.test.ts antes del merge.
05B
REVISIÓN DE CAMBIOS

Impacto de un diff Git

Pulsa Diff Git, consulta los archivos modificados con git status y marca esas mismas rutas. La aplicación toma todos sus símbolos como raíces y recorre dependencias entrantes.

  • Los nodos azules pertenecen a archivos cambiados.
  • Los nodos naranjas podrían verse afectados por el cambio.
  • El resumen identifica pruebas conectadas al impacto visible.

Revisa antes del merge

Selecciona varios archivos, ajusta de uno a cinco niveles y exporta el resultado como PNG, SVG, JSON o Markdown.

Impacto de un diffMarca los archivos que tocarías, como haría git status antes de un merge.
Archivos cambiados
3Símbolos cambiados
5Posiblemente afectados
2Pruebas conectadas
processPaymentpayments.ts
retryPaymentpayments.ts
refundPaymentpayments.ts
createOrderorders.ts
testProcessPaymentpayments.test.ts
postCheckoutcheckout.ts
postOrderorders.ts
testCreateOrderorders.test.ts
api/routes/checkout.ts1 símbolo
api/routes/orders.ts1 símbolo
services/orders.ts1 símbolo
tests/orders.test.ts1 símbolo prueba
tests/payments.test.ts1 símbolo prueba
Los 3 símbolos de los archivos marcados son las raíces; el resto son dependencias entrantes que podrían romperse.
ANTES DE ABRIR LA APLICACIÓN

Obtén la lista de archivos cambiados

Copia la salida y marca esas mismas rutas en el panel de Diff Git.

Cambios sin confirmar
git status --porcelain
Cambios frente a la rama principal
git diff --name-only main...HEAD
05C
CALIDAD

Cobertura de pruebas

Pulsa Cobertura e importa el reporte generado por tus pruebas. La aplicación relaciona cada línea instrumentada con los rangos de funciones, clases y métodos almacenados en CodeGraph.

  • Acepta LCOV, Cobertura XML y JaCoCo XML.
  • Verde: todas las líneas y ramas instrumentadas del símbolo están cubiertas.
  • Amarillo: tiene una combinación de líneas o ramas cubiertas y ausentes.
  • Rojo: ninguna línea instrumentada dentro del símbolo fue ejecutada.

Del reporte a cada función

Selecciona un nodo para ver porcentaje, líneas, ramas y ubicación. El panel ordena primero los archivos con menor cobertura y permite abrir inmediatamente el símbolo y su código.

Ejemplocheckout() · 62.5% · 5/8 líneas · 2/4 ramas

Los reportes contienen rutas que pueden ser absolutas o relativas. La aplicación intenta emparejarlas por ruta completa y por sufijo; las rutas sin coincidencia aparecen en el inspector.

RECETAS RÁPIDAS

¿Qué archivo debo subir?

Genera el reporte con tu herramienta de pruebas y selecciona el archivo indicado.

Vitest / Jest · coverage/lcov.info
npm run test -- --coverage
pytest · coverage.xml
pytest --cov=. --cov-report=xml
Maven · target/site/jacoco/jacoco.xml
mvn test jacoco:report
Gradle · build/reports/jacoco/test/jacocoTestReport.xml
./gradlew test jacocoTestReport
Resultado esperadoAbres coverage/lcov.infoel grafo se coloreaseleccionas checkout() y ves sus líneas sin cubrir
PRUÉBALO AHORA

Comprueba tu reporte antes de abrir el proyecto

Pega el contenido de tu lcov.info, coverage.xml o jacoco.xml para confirmar que el formato se reconoce y ver cómo se emparejan las rutas.

Analiza un reporte de coberturaPega tu propio LCOV, Cobertura o JaCoCo: se procesa aquí, en tu navegador.
Se emparejan las rutas del reporte con los archivos del proyecto de ejemplo.
Pulsa “Analizar reporte” para ver el resultado símbolo por símbolo.
Ningún dato sale de tu navegador: la lectura y el emparejamiento ocurren en esta página.
06
CONEXIONES

Ruta entre símbolos

Selecciona un origen, busca un destino y la aplicación encuentra el camino más corto. “Solo flujo dirigido” respeta la orientación real; “Cualquier conexión” también permite recorrer relaciones al revés.

Ruta entre símbolosCamino más corto, con o sin respetar la dirección real del flujo.
Modo
3Saltos
15Símbolos visitados
noRelaciones inversas
postCheckoutapi/routes/checkout.tscallscreateOrderservices/orders.tscallssaverepositories/orders.tscallsqueryrepositories/db.ts
Datos del proyecto de ejemplo “storefront”: 27 símbolos, 50 relaciones, 15 archivos.

Prueba a buscar la ruta desde createOrder hasta una prueba: solo aparece con “Cualquier conexión”, porque en el flujo real es la prueba la que llama al código.

07
VISIÓN GLOBAL

Arquitectura y drill-down

Agrupa todo el proyecto por módulo, carpeta, archivo o lenguaje. El grosor de cada conexión representa cuántas dependencias cruzan entre grupos.

Haz doble clic en un bloque para abrir únicamente sus archivos, símbolos y relaciones internas.

Arquitectura y drill-downAgrupa el proyecto completo y abre un bloque para ver su interior.
7Grupos
14Conexiones entre grupos
servicesrepositories5 dependencias · calls, references
serviceslib4 dependencias · calls
testsservices4 dependencias · calls
apiservices3 dependencias · calls, instantiates
apilib3 dependencias · calls
servicesdomain3 dependencias · calls, instantiates
Datos del proyecto de ejemplo “storefront”: 27 símbolos, 50 relaciones, 15 archivos.
07B
ECOSISTEMA

Proyectos múltiples

Pulsa Proyectos para convertir varios repositorios indexados en un solo mapa. El proyecto abierto se añade primero; después puedes incorporar frontend, backend, workers o librerías seleccionando sus carpetas raíz.

  • Cada bloque resume los archivos, símbolos, lenguajes y paquetes de un repositorio.
  • Las conexiones automáticas comparan los paquetes declarados con dependencias de package.json, pyproject.toml, Cargo.toml y go.mod.
  • Crea conexiones manuales para APIs HTTP, eventos, colas o cualquier integración que no aparezca en un manifiesto.
  • Exporta el ecosistema completo como PNG, SVG, JSON o Markdown.

De repositorios aislados a sistema

Selecciona un bloque para inspeccionar sus métricas y paquetes. Las líneas azules son dependencias detectadas; las amarillas representan relaciones manuales.

Ejemplofrontend → SDK → API → worker → shared-lib

Cada índice se abre temporalmente en el navegador. Al terminar, la aplicación restaura automáticamente el proyecto principal.

07C
INTEGRACIONES

Contratos entre proyectos

En Proyectos, cambia de Dependencias a Contratos. La aplicación revisa localmente los archivos accesibles de cada repositorio y conecta las coincidencias.

  • HTTP: rutas declaradas por routers y llamadas realizadas con fetch o axios.
  • Eventos: nombres compartidos entre productores como emit y consumidores como on.
  • Topics: canales utilizados por operaciones de publicación, suscripción o consumo.
  • Esquemas: mensajes Proto, tipos GraphQL y títulos o identificadores de JSON Schema.

Inspecciona la evidencia

Haz clic en una línea del mapa para ver los dos proyectos, dirección del contrato, archivo, línea y fragmento que produjo la coincidencia.

Ejemplobackend: emit("order.created") → worker: on("order.created")

La detección es heurística: variables construidas dinámicamente, frameworks no reconocidos y generación de código pueden requerir revisión manual. Se omiten carpetas de dependencias y se analizan hasta 1.200 archivos por proyecto.

08
LLAMADAS DIRECTAS

Callers y callees

Callers¿Quién llama a este símbolo?route → create_order
Callees¿Qué funciones utiliza?create_order → save
09
FLUJO

Ruta de ejecución

Parte de una función y sigue exclusivamente llamadas salientes hasta cinco niveles. El informe cuenta símbolos alcanzables, bifurcaciones, finales y ciclos.

Ruta de ejecuciónSolo llamadas salientes, nivel por nivel, hasta cinco saltos.
12Alcanzables
7Bifurcaciones
4Finales
1Ciclos
0
postCheckout
1
createOrderformatMoneylogrequireSession
2
processPaymentsavesendReceiptvalidateCart
3
queryretryPaymentwithTransaction
Ciclo detectado: processPayment → retryPayment → processPayment. Un reintento recursivo entre servicios puede convertirse en una tormenta de llamadas.
Datos del proyecto de ejemplo “storefront”: 27 símbolos, 50 relaciones, 15 archivos.
09B
OPENTELEMETRY

Trazas reales

Pulsa Trazas e importa una exportación OTLP/JSON o JSON Lines. La aplicación agrupa los spans por traceId, conserva sus relaciones padre/hijo y dibuja únicamente el flujo que sí ocurrió.

  • Las líneas verdes representan operaciones ejecutadas; los errores se resaltan en rojo.
  • Los spans se asocian con símbolos usando code.function.name, su nombre y, cuando existe, code.file.path.
  • Una operación sin coincidencia permanece visible como span runtime para no perder partes de la traza.
  • La traza completa se puede exportar como PNG, SVG, JSON o Markdown.

Del request al código

Selecciona cualquier span para ver duración, estado, atributos y su posición relativa en la línea de tiempo. Si se relacionó con el índice, puedes abrir el símbolo y sus líneas de código.

EjemploHTTP GET → controller → service → repository

El JSON se analiza en el navegador y no se envía a ningún servidor. Formato esperado: OTLP/JSON de OpenTelemetry.

EJEMPLO MÍNIMO

Cómo se reconoce una traza

Cada span necesita un identificador de traza, su propio identificador y marcas de tiempo. parentSpanId conecta al hijo con su padre.

OTLP/JSON simplificado
{
  "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
  "spanId": "00f067aa0ba902b7",
  "parentSpanId": "",
  "name": "HTTP GET /orders",
  "startTimeUnixNano": "1710000000000000000",
  "endTimeUnixNano": "1710000000180000000"
}
LABORATORIO DE TRAZAS

Analiza una traza completa aquí mismo

La traza de ejemplo incluye un pago que falla y su reintento. Cambia al flamegraph, revisa el tiempo propio y selecciona el span rojo para ver la ruta de fallo.

Analiza una traza realPega una exportación OTLP/JSON y obtén flamegraph, cuellos de botella y ruta de fallo.
Acepta OTLP/JSON y JSON Lines, igual que la aplicación.
Pulsa “Analizar traza” para construir el flamegraph.
El JSON se analiza en esta página; nada se envía a un servidor.
09C
RENDIMIENTO

Flamegraph

Después de importar una traza, cambia de Grafo a Flamegraph. El ancho de cada bloque representa cuánto duró el span y cada fila muestra un nivel más profundo de llamadas.

  • Tiempo total: duración completa del span, incluyendo sus operaciones hijas.
  • Tiempo propio: tiempo consumido por el span sin contar intervalos ejecutados por sus hijos.
  • Haz clic para inspeccionar un span y doble clic para ampliar únicamente esa rama.
  • Los spans con error aparecen en rojo y los servicios tienen colores distintos.

Encuentra el trabajo costoso

El panel “Mayor tiempo propio” ordena las operaciones que realmente consumen más tiempo. Esto evita confundir una función lenta con otra que solamente espera a una consulta hija.

Ejemplorequest 900 ms → service 820 ms → SQL 760 ms

Si el bloque de service dura 820 ms pero su tiempo propio es 60 ms, el cuello de botella está probablemente en sus spans hijos. Compruébalo en el laboratorio de trazas: processPayment dura 312 ms pero casi todo el tiempo lo consume su reintento.

09D
DIAGNÓSTICO RUNTIME

Ruta de fallo

Selecciona un span rojo y pulsa Fallo. El lienzo elimina el ruido y conserva únicamente la cadena de padres, el span que falló y todos sus hijos.

  • Padres: explican cómo llegó la petición hasta el error.
  • Hijos: muestran reintentos u operaciones iniciadas después del fallo.
  • Código asociado: abre las líneas del símbolo relacionado sin abandonar la ruta.
  • Dependencias afectadas: añade hasta dos niveles de símbolos que dependen del código que falló.

Del error al radio de impacto

Los nodos ámbar son padres, el rojo es el error, los morados son hijos, el cian representa el código asociado y los naranjas son dependencias potencialmente afectadas.

EjemploHTTP POST → checkout → payment ✕ → retry

La parte runtime proviene de la traza. Las dependencias afectadas son un cálculo estático de CodeGraph y deben interpretarse como riesgo potencial, no como ejecución confirmada. Selecciona el span rojo en el laboratorio de trazas para ver una ruta de fallo real.

10
DIAGNÓSTICO

Detección de problemas

Analiza el índice completo y presenta cuatro señales:

  • Funciones privadas posiblemente sin uso.
  • Abre un ciclo para recorrer todos sus símbolos y relaciones en el lienzo.
  • Abre un archivo acoplado para inspeccionar qué archivos y símbolos lo conectan.
  • Nodos con demasiados vecinos.
La reflexión y las llamadas dinámicas pueden producir falsos positivos. Usa el icono de ojo para ocultarlos; la decisión queda guardada localmente por proyecto y puede restaurarse.
Detección de problemasSeñales calculadas sobre el proyecto de ejemplo, no ejemplos inventados.
1Ciclos
6Archivos acoplados
8 vecinosUmbral de hub
3Sin uso
processPayment → retryPayment2 símbolos · relaciones calls
El ciclo entre processPayment y retryPayment y el hub de log existen de verdad en los datos de ejemplo.
10A
ONBOARDING Y REVISIONES

Modo presentación

Construye un recorrido con las vistas que ya preparaste en el grafo. Cada paso conserva sus nodos, relaciones, título y explicación, incluso si después cambias de modo.

  • Pulsa Presentar en la barra superior para abrir el editor.
  • Prepara una vista —arquitectura, impacto, ruta, contratos o diagnóstico— y añádela al recorrido.
  • Reordena o elimina pasos antes de comenzar.
  • Durante la reproducción usa los botones, las flechas del teclado o la barra espaciadora.

Cuenta una historia con el sistema

La reproducción oculta los paneles de trabajo, centra cada vista y muestra solamente la explicación y los controles de avance.

Ejemplo1. Arquitectura → 2. Request → 3. Impacto → 4. Pruebas

Los recorridos se guardan únicamente en el almacenamiento local del navegador para cada proyecto. Puedes descargarlos como JSON para conservar una copia.

10C
IA OPCIONAL

Asistente de arquitectura

Pulsa Asistente después de preparar un subgrafo. El proveedor recibe una descripción estructurada de los nodos y relaciones visibles, nunca el contenido del código fuente.

  • Genera resúmenes, explicaciones de flujo, riesgos visibles y preguntas para revisiones.
  • Introduce en la web una API key y un modelo de un proveedor compatible con Responses API.
  • Las respuestas deben referenciar símbolos y archivos del contexto para poder verificarlas.
  • Las solicitudes usan store: false; la clave se conserva únicamente en memoria durante la sesión.

Pregunta sobre lo que estás viendo

El contexto cambia con el modo actual: arquitectura, impacto, callers, rutas, contratos, cobertura, trazas o problemas.

Ejemplos“Resume este flujo” · “¿Dónde hay acoplamiento?”

Las claves de API no deben exponerse en aplicaciones públicas. Esta opción está pensada para el uso local y personal de CodeGraph Visual. Para equipos o un despliegue compartido, conecta el proveedor mediante un backend seguro.

COMPRENDERExplica el flujo desde la ruta HTTP hasta la persistencia. Cita los símbolos en orden.
REVISARSeñala dependencias circulares o hubs visibles y explica por qué aumentan el riesgo.
ONBOARDINGResume este subgrafo para una persona nueva y propón tres preguntas de comprobación.
10B
COMPARTIR RESULTADOS

Exportar reportes

Después de generar un impacto, una ruta, la arquitectura, cobertura, un diagnóstico o una traza, pulsa Exportar sobre el lienzo. El archivo se construye y descarga localmente.

PNGImagen de alta resolución para presentaciones y tickets.
SVGReporte vectorial que conserva nitidez al ampliarlo.
JSONDatos completos para automatizaciones y otros sistemas.
MarkdownResumen con métricas y tablas listo para documentación.

Los reportes incluyen nombres, rutas, relaciones y métricas, pero no incluyen el contenido del código fuente.

11
DATOS

Privacidad y límites

Procesamiento localSQLite WebAssembly consulta la base dentro del navegador.
Sin servidorNo hay cuentas, API ni almacenamiento remoto.
Permiso temporalDebes volver a elegir la carpeta en una nueva sesión.
Solo lecturaLa aplicación nunca modifica tu repositorio ni el índice.
Límites de visualizaciónVecindarios: 200 nodos / 500 relacionesDrill-down: 200 símbolos / 500 relacionesRutas: hasta 8 saltosEjecución e impacto: hasta 5 niveles
12
AYUDA

Errores frecuentes

No encontramos .codegraph/codegraph.db

Selecciona la raíz del proyecto y confirma que ejecutaste codegraph init.

El código mostrado está desactualizado

Ejecuta codegraph sync, cierra el proyecto en la web y vuelve a abrirlo.

No aparecen callers, rutas o ejecución

El índice no encontró relaciones calls para ese símbolo. Puede ocurrir con dispatch dinámico, reflexión o lenguajes parcialmente soportados.

El navegador perdió acceso a los archivos

Por seguridad, Chrome y Edge pueden revocar el permiso al recargar. Cierra el proyecto y selecciona nuevamente la carpeta.

El reporte de cobertura carga, pero no coincide con ningún archivo

Revisa las rutas guardadas en el reporte. Genera la cobertura desde la raíz del repositorio o configura la herramienta para usar rutas relativas que coincidan con el índice.