¿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):
| Vista | Muestra |
|---|---|
| Explorar | Componentes (las partes del sistema) y las conexiones entre ellos, agrupados en capas |
| Recorridos del cliente | Cada recorrido que un usuario puede realizar, animado sobre la arquitectura: peticiones, respuestas y traspasos etiquetados |
| Mapa de estado | Cada dimensión de estado declarada en el ámbito mapeado, sus estados y las transiciones que los recorridos realmente toman |
| Código | Cada 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)
- Evidencia o nada. Cada componente, unidad, decisión, arista, estado y acción debe citar
archivo:línea. Si no puedes citarlo, márcalo comoNO_VERIFICADOo 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. - 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_gapy verifícalo en el código antes de añadirlo, con evidencia. - 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. - 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.
- Solo lectura. Nunca edites el repositorio de destino. Escribe todo en
.xylem/(o en una carpeta que el usuario nombre). - 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 yprocessType; - conexiones: cada una
{from, to, label, kind}, dondekindes 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)
- 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:
summarylegible 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 eltestde código exacto, unkind(branch, calculation, loop o unconditional) y los sucesores correctos. Unreturnoraisetermina la ruta. Las continuaciones normales y de error de un bloque try son separadas, y una excepción pendiente ejecutafinallyy luego se propaga. Cuando no estés seguro, marca el sucesor comounresolved; nuncaverified; - etiquetas
risksolo en decisiones que implementan directamente un defecto conocido.
- 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?}.eventes 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 luegox==='b'sí, o un valor excluido y luego requerido porincludes(). Corrige el trazado, o retíralo aunavailable, 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
atSecpor paso enmanifest.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>.mdcon 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
unavailabley 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
| Script | Propósito |
|---|---|
census.py | Censo de definiciones en múltiples lenguajes (el denominador de cobertura) |
scaffold_deep.py | Mapa borrador a nivel de función a partir del censo y la arquitectura |
merge_deep.py | Fusiona mapas parciales; reconcilia IDs por archivo y línea |
validate.py | Cada compuerta: esquema, referencias, cobertura, saltos silenciosos, sucesores, consistencia de selectores |
build_site.py | Exporta los datos compactos de la vista Código y construye el sitio de una sola página |
record_journey.example.mjs | Iniciador 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.