Communitygithub.com

xylem

Convierte un repositorio en un mapa visual basado en el código fuente, con vistas de arquitectura, recorridos de usuario, mapa de estado y funciones. Perfecto para visualizar, auditar o explicar la estructura completa de cualquier proyecto.

¿Qué es xylem?

Xylem es una skill para agentes de IA (como Claude Code, Cursor, Codex) que transforma un repositorio de código en un sitio web estático interactivo que mapea fielmente la arquitectura, los flujos de usuario, los estados y las funciones, siempre respaldado por evidencia directa del código fuente (archivo:línea). El resultado son cuatro vistas integradas: Explorar (componentes y conexiones), Recorridos del cliente (animaciones sobre la arquitectura), Mapa de estado (dimensiones y transiciones) y Código (cada función con sus decisiones y llamadas). La key de Xylem es que **no inventa nada**: cada afirmación debe estar verificada en el código. Si no hay evidencia, se marca como `UNVERIFIED` o se omite, garantizando un mapa honesto y auditable. Soporta repositorios en múltiples lenguajes (Python, JavaScript/TypeScript, etc.) y se ejecuta completamente offline, sin enviar datos a servicios externos. El proceso se divide en fases (Censo, Arquitectura, Recorridos, Mapa profundo, Construcción del sitio, Revisión cruzada y Publicación) que deben ejecutarse en orden, cada una con su propia puerta de validación que verifica consistencia, cobertura y ausencia de saltos silenciosos. Es ideal para desarrolladores, arquitectos de software o cualquier persona que necesite "toda la app en una página" para explorar, documentar, auditar o enseñar un sistema complejo.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Iineman2/xylem/tree/HEAD/skills/xylem

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

¿Qué hace xylem?

Convierte un repositorio en un mapa fundamentado en el código fuente. Tiene cuatro vistas, en un sitio estático de dos archivos (index.html y deep-view.json):

VistaMuestra
ExplorarComponentes (las partes del sistema) y las conexiones entre ellos, agrupados en capas
Recorridos del clienteCada recorrido que un usuario puede realizar, animado sobre la arquitectura: peticiones, respuestas y traspasos etiquetados
Mapa de estadoCada dimensión de estado declarada en el ámbito mapeado, sus estados y las transiciones que los recorridos realmente toman
CódigoCada función mapeada como un mosaico en su región, con sus decisiones, llamadas y llamantes, y las rutas de recorrido trazadas a nivel de función

El método importa más que la página. Cada afirmación está vinculada a archivo:línea. Cada conexión es real. Cuando el código no puede resolver algo, el mapa lo indica en lugar de adivinar.

Reglas fundamentales (aplican en cada fase)

  1. Evidencia o nada. Cada componente, unidad, decisión, arista, estado y acción debe citar archivo:línea. Si no puedes citarlo, márcalo como NO_VERIFICADO o déjalo fuera. Esto es una obligación del autor/revisor: las compuertas automatizadas exigen evidencia de la arquitectura y ubicaciones profundas en el código fuente, no cada cita de estado/acción o explicación de su significado.
  2. Asignar IDs; nunca inventar entidades o conexiones. Usa los IDs de posición de archivo del andamio; los IDs creados manualmente también deben ser únicos y estables. Las aristas entre regiones deben usar una conexión de arquitectura declarada. Si falta una, registra un diagram_gap y verifícalo en el código antes de añadirlo, con evidencia.
  3. Las brechas honestas son mejores que los caminos imposibles. Si el resultado de un recorrido no se puede rastrear de manera distinta desde el código fuente, escribe {"unavailable": "<motivo específico>"}. Nunca copies la ruta exitosa en un resultado fallido. Nunca encadenes ramas que no puedan ser ambas verdaderas.
  4. Di lo que es. Los trazados son rutas estáticas del código fuente, no grabaciones de ejecuciones reales. Etiquétalos así en la página.
  5. Solo lectura. Nunca edites el repositorio de destino. Escribe todo en .xylem/ (o en una carpeta que el usuario nombre).
  6. Privacidad. No envíes el contenido del repositorio a ningún servicio externo a menos que el usuario lo solicite. El sitio solo hace solicitudes de mismo origen para sus datos y videos opcionales. No hace solicitudes externas; sírvelo en loopback para uso offline.

Estructura de salida

.xylem/
  census.json        # cada definición encontrada en el código (scripts/census.py)
  architecture.json  # fase 1
  journeys.json      # fase 2
  deep.json          # fase 3 (mapa a nivel de función)
  validation.json    # salida de scripts/validate.py
  reviews/           # informes de revisión cruzada (fase 6)
  site/              # index.html + deep-view.json (+ videos/)   (scripts/build_site.py)

Los formatos de cada archivo están en references/schemas.md. Léelo antes de escribir cualquier JSON.

Fases y compuertas

Realiza las fases en orden. Cada fase termina con una compuerta. No continúes hasta que la compuerta pase, o el usuario acepte una brecha documentada. En un ensayo explícitamente autorizado, conserva los artefactos fallidos y los registros sin cambios y continúa solo dentro del alcance de ese ensayo; etiqueta las salidas posteriores como provisionales. Una aprobación estructural no establece una cobertura semántica completa.

Fase 0: Censo (determinista)

python scripts/census.py <repo> --out .xylem/census.json [--exclude dir ...]

Esto inventariza las definiciones nombradas con AST de Python, un caminante de tokens JS/TS de la biblioteca estándar, y expresiones regulares aproximadas para otros lenguajes soportados. scannedFiles incluye archivos fuente sin definiciones. JS/TS cubre arrow functions genéricas, métodos concretos multilínea/computados, firmas de sobrecarga, owners léxicos de funciones/clases, literales regex e interpolaciones de plantillas; las devoluciones de llamada anónimas no son unidades del censo. Es un inventario medido, no una prueba de toda la sintaxis del lenguaje. Cualifícalo con un analizador sintáctico independiente o una muestra del código fuente antes de reclamar completitud. Los porcentajes posteriores describen solo este inventario.

Compuerta: los conteos del censo parecen plausibles en relación con el tamaño del repositorio. Las rutas excluidas están justificadas, por ejemplo código generado o node_modules.

Fase 1: Arquitectura

Lee los puntos de entrada, archivos de compilación, módulos principales y límites de procesos. Luego escribe architecture.json:

  • capas: por ejemplo shell, UI, servidor, dominio, almacenamiento, workers, externos;
  • componentes: cada uno con id, layer, files[], una responsabilidad simple y processType;
  • conexiones: cada una {from, to, label, kind}, donde kind es spawn, ipc, http, file, data o uses;
  • flujos: los principales flujos de extremo a extremo como pasos ordenados de componentes.

Compuerta: python scripts/validate.py .xylem --only architecture pasa. Cada entrada de scannedFiles pertenece a un componente, o tiene una entrada razonada en architecture.meta.fileExclusions. Las rutas y líneas de evidencia deben existir bajo la raíz de evidencia.

Fase 2: Recorridos y estados

Escribe journeys.json. Determínalos a partir de la UI, rutas, comandos CLI, trabajos y rutas de error:

  • stateDimensions: cada máquina de estado independiente;
  • screens: cada pantalla;
  • actions: cada acción de usuario y transición del sistema, con sus resultados, el texto exacto que ve el usuario y el deshacer;
  • journeys: estados iniciales más pasos.

Cada acción lleva un trazado de arquitectura ordenado (alternando componente y conexión). Los recorridos de vuelta usan {"connection": [a, b], "direction": "reply"}. Cuando el siguiente paso no comienza donde terminó el anterior, el paso lleva transition.handoff, con un tipo y una etiqueta: user, timer, queue, continuation, lifecycle o download. Cubre recorridos felices, infelices, de recuperación y marginales.

Compuerta: validate.py --only journeys pasa:

  • cada recorrido se reproduce a través de resultados válidos;
  • cero saltos silenciosos (cada iluminación se alcanza mediante un cable, una respuesta o un traspaso etiquetado);
  • sin estados huérfanos.

Fase 3: Mapa a nivel de función (resolución final)

  1. Genera un mapa borrador a partir del censo:
python scripts/scaffold_deep.py .xylem

Escribe deep.json. El borrador contiene las unidades asignadas del censo, decisiones de Python a partir de AST, y puntos if, while, for, switch y catch entre paréntesis heurísticos de JS/TS. JS/TS no reclama un inventario completo de ternarios, cálculos o decisiones de cortocircuito. Los comentarios, contenidos literales y declaraciones hijas se excluyen de cada cuerpo. Las llamadas genéricas retienen posiciones de llamada distintas. Las aristas de llamada usan source: heuristic y confidence: name-resolved; los nombres no resueltos no son enlaces inventados. Refinar contra el código fuente; la resolución de nombres no es resolución de tipos. 2. Refina el borrador leyendo el código:

  • summary legible para el negocio por unidad, escrito a partir del cuerpo, no del nombre;
  • para cada decisión, una pregunta plain ("¿Es este archivo mayor de 16 MiB?") más el test de código exacto, un kind (branch, calculation, loop o unconditional) y los sucesores correctos. Un return o raise termina la ruta. Las continuaciones normales y de error de un bloque try son separadas, y una excepción pendiente ejecuta finally y luego se propaga. Cuando no estés seguro, marca el sucesor como unresolved; nunca verified;
  • etiquetas risk solo en decisiones que implementan directamente un defecto conocido.
  1. Escribe actionTraces: para cada acción y resultado de recorrido, los eventos de ejecución ordenados {component, unit, event, decision?, line, note?, callsite?, returnTo?, precondition?, boundary?}.
    • event es uno de call, return, branch, async, spawn, ipc, http, file, render, unknown, throw, finally o resume. Consulta los esquemas para marcos de activación, eventos terminales y límites de reproducción admitidos.
    • Comienza en el iniciador real, como un manejador de UI, ruta o trabajo.
    • Sigue llamadas, retornos y límites de proceso. Una negativa debe seguir la ruta de error real de vuelta al usuario. Nunca debe continuar a "guardado" o "éxito".
    • Cuando la ruta no se pueda conocer, emite {"event": "unknown", "note": "..."}, o marca todo el resultado como no disponible.

Repositorios grandes: divide la fase 3 por área de código entre varios agentes, cada uno escribiendo deep-<parte>.json en el mismo formato, luego fusiona con scripts/merge_deep.py. Reconciliar IDs por archivo y línea de definición, nunca por similitud de nombre.

Compuerta: validate.py pasa el conjunto completo:

  • cada definición del censo emitida o excluida explícitamente con una razón; la cobertura emitida y el recuento de exclusiones son contadores separados;
  • cada extremo de arista se resuelve;
  • cada arista entre regiones recorre una conexión;
  • los sucesores de las decisiones se resuelven;
  • las referencias del trazado son válidas;
  • consistencia de selectores: ninguna activación toma elecciones mutuamente excluyentes para valores no modificados. Las escrituras en el código fuente pueden cambiar un valor; una etiqueta de iteración por sí sola no puede restablecer restricciones. La gramática y los límites admitidos están en el esquema. Por ejemplo, x==='a' sí y luego x==='b' sí, o un valor excluido y luego requerido por includes(). Corrige el trazado, o retíralo a unavailable, nombrando el conflicto.

Fase 4: Construir la página

python scripts/build_site.py .xylem

Esto escribe site/index.html y site/deep-view.json. Los videos son opcionales: coloca videos/<idRecorrido>.mp4 más videos/manifest.json dentro de .xylem/ primero (consulta los esquemas). Sirve site/ a través de HTTP para verlo, por ejemplo python -m http.server -d .xylem/site. Una página file:// no puede cargar los datos de la vista Código.

Compuerta: abre la página y verifica cada modo una vez:

  • sin errores en la consola;
  • ancho de teléfono (420 px) sin desplazamiento horizontal;
  • el modo oscuro y el teclado funcionan.

Fase 5: Grabaciones de pantalla reales (opcional)

Si la aplicación tiene una UI que puedas ejecutar localmente, graba los recorridos con Playwright. Un iniciador está en scripts/record_journey.example.mjs. Reglas para las grabaciones:

  • maneja la UI real, sin respuestas simuladas;
  • añade un pie de foto por paso;
  • acelera las esperas inactivas, y subtitula la aceleración;
  • registra atSec por paso en manifest.json;
  • marca las grabaciones parciales como parciales.

El visor sincroniza un video con el mapa, por lo que el video se convierte en el reloj.

Fase 6: Consejo de revisión cruzada

Usa dos revisores independientes cuando sea posible: dos modelos o agentes diferentes, o al menos un contexto nuevo sin acceso al razonamiento del autor. Sigue references/protocol.md:

  • el autor nunca califica su propio trabajo;
  • el revisor recibe archivos y código, nunca las conclusiones del autor;
  • el revisor ejecuta el verificador independiente y muestrea las afirmaciones contra el código fuente: la regla de muestreo única en protocol.md (todos los elementos disponibles por debajo de sus mínimos);
  • los hallazgos van a reviews/<revisor>-<ronda>.md con gravedad, evidencia y una corrección concreta;
  • compuerta de aceptación: un ACCEPT, REJECT o BLOCKED explícito para arquitectura, recorridos, profundo, página/datos y el paquete congelado. Solo los defectos materiales justifican REJECT: una conclusión incorrecta, un camino imposible o una tarea central bloqueada. Los límites declarados, los marcadores honestos de unavailable y la naturaleza estática de los trazados no son motivos de rechazo;
  • usa un presupuesto de revisión acotado; detente con REJECT/BLOCKED y evidencia conservada si no se resuelve. Revisa el artefacto construido exacto, no una descripción del mismo.

Compuerta: todos los artefactos del paquete congelado son aceptados por revisión independiente. Nunca fabriques caminos para cumplir con una cuota de muestreo.

Fase 7: Publicar e informar

Informa al usuario sobre el contenido de la página, con conteos reales:

  • funciones, decisiones, recorridos y resultados trazados;
  • cuántos resultados no están disponibles y por qué;
  • qué fue revisado de forma cruzada.

Informa los límites de manera clara.

Scripts

ScriptPropósito
census.pyCenso de definiciones en múltiples lenguajes (el denominador de cobertura)
scaffold_deep.pyMapa borrador a nivel de función a partir del censo y la arquitectura
merge_deep.pyFusiona mapas parciales; reconcilia IDs por archivo y línea
validate.pyCada compuerta: esquema, referencias, cobertura, saltos silenciosos, sucesores, consistencia de selectores
build_site.pyExporta los datos compactos de la vista Código y construye el sitio de una sola página
record_journey.example.mjsIniciador de Playwright para videos de recorridos en pantalla real

Los scripts de Python requieren Python 3.9+ y solo la biblioteca estándar. Los helpers opcionales .mjs para navegador/grabación requieren un Playwright disponible por separado. La página no usa frameworks ni solicitudes externas.

Skills relacionados