ASCII Tree

ASCII Tree es una herramienta diseñada para solucionar un problema común en la documentación técnica: la representación visual, estructurada y legible de sistemas de archivos.

Como ingeniero, concebí este proyecto para ofrecer una interfaz limpia y veloz que transforma texto plano indentado en diagramas de árbol ASCII, eliminando la necesidad de herramientas de diagramación pesadas o el tedioso dibujo manual de caracteres.

Utilidad y Funcionamiento General

El valor operativo de este proyecto reside en su inmediatez y precisión. En el contexto del desarrollo de software, la escritura de artículos técnicos o la creación de documentación, ilustrar la jerarquía de directorios es una necesidad recurrente.

La herramienta resuelve este problema mediante un flujo de trabajo de tres pasos:

1. Entrada Estructurada: El usuario introduce texto plano, utilizando la indentación (espacios o tabulaciones) para definir los niveles de anidación jerárquica de archivos y carpetas.
2. Procesamiento Determinista: El sistema analiza sintácticamente el texto, filtrando líneas vacías, reconociendo caracteres especiales (como viñetas de Markdown) y construyendo un modelo de datos en árbol en memoria.
3. Renderizado Parametrizado: Un motor de generación procesa este árbol y renderiza una representación ASCII estática. El usuario puede modificar parámetros en tiempo real, como la inclusión de rutas completas (fullpath), caracteres UTF-8 avanzados (fancy), o sufijos de directorios (trailing slash).

Todo esto ocurre localmente en el navegador, ofreciendo respuesta en tiempo real, persistencia local y capacidades de internacionalización, lo que la hace útil tanto para perfiles técnicos como no técnicos.

---

Arquitectura General

El proyecto ha sido estructurado siguiendo principios de Domain-Driven Design (DDD) adaptados al entorno Frontend y la Islands Architecture proporcionada nativamente por Astro.

La razón técnica de este enfoque es aislar completamente la lógica de negocio (el parseo y la generación de árboles) de la capa de interfaz de usuario. Esto asegura que el núcleo de la aplicación sea puramente matemático, testeable y agnóstico del framework visual utilizado.

Separación de Responsabilidades

• Capa de Dominio (src/lib/tree-generator/): Contiene las interfaces (FileStructure), el analizador léxico (parse-input.ts) y el motor de renderizado (generate-tree.ts). Es código TypeScript puro sin dependencias visuales.
• Capa de Aplicación y Estado: La persistencia de estado de la aplicación se gestiona asíncronamente mediante IndexedDB, envuelto por la librería Dexie (src/lib/db.ts). Esto permite restaurar la sesión del usuario instantáneamente entre recargas, delegando la responsabilidad del almacenamiento al cliente (offline-first).
• Capa de Presentación: Utiliza componentes estáticos y dinámicos de Astro (src/components/), manejando la interactividad del editor de texto y los controles de configuración directamente con Vanilla JS embebido, evitando así el overhead de frameworks reactivos como React o Vue para una aplicación de este alcance.
• Sistema de Internacionalización (i18n): Basado en rutas de directorio (folder-based routing) y un diccionario central (src/i18n/ui.ts). Se desacopla la definición de copys de los componentes, inyectando las traducciones en tiempo de compilación.

graph TD
    UI[Capa de Presentación: Componentes Astro]
    State[Gestión de Estado: IndexedDB / Dexie]
    Parser[Parser: Input -> Árbol en Memoria]
    Renderer[Renderer: Árbol -> String ASCII]

    UI --> |Texto y Opciones| Parser
    UI <--> |Sincronización| State
    Parser --> |FileStructure| Renderer
    Renderer --> |Resultado| UI

---

Modelado de Datos y Lógica

El núcleo de la aplicación modela un sistema jerárquico. La entidad principal es FileStructure.

Diagrama de Entidad

classDiagram
    class FileStructure {
        +String name
        +FileStructure[] children
        +Number indentCount
        +FileStructure parent
    }

Flujo de Transformación de Datos

El análisis sintáctico se realiza en dos etapas. Primero, se divide la cadena de entrada en líneas y se utiliza un analizador léxico basado en expresiones regulares para determinar el nivel de indentación y el nombre base de cada nodo, ignorando caracteres superficiales (como guiones de markdown).

Luego, se ejecuta un algoritmo de reconstrucción que mantiene una pila (path) con los nodos actuales, iterando sobre la lista plana y asignando relaciones padre-hijo basándose exclusivamente en diferencias matemáticas de indentCount.

sequenceDiagram
    participant User as Usuario
    participant Editor as UI / Editor
    participant Parser as parseInput()
    participant Renderer as generateTree()
    participant Dexie as IndexedDB

    User->>Editor: Escribe texto indentado
    Editor->>Parser: Envía Raw String
    Parser->>Parser: Transforma a Array de Objetos Planos
    Parser->>Parser: Reconstruye Relaciones (Parent/Children)
    Parser-->>Renderer: Devuelve objeto FileStructure Root
    Renderer->>Renderer: Atraviesa árbol (DFS) + Opciones (Fancy, Root)
    Renderer-->>Editor: Devuelve string final ASCII
    Editor->>Dexie: Persiste Input y Opciones
    Editor->>User: Muestra Diagrama Renderizado

El estado de la aplicación de cara a persistencia y a la generación de URLs compartidas se maneja mediante un modelo plano en Dexie:

erDiagram
    TreeState {
        int id PK
        string content
        boolean fancy
        boolean fullpath
        boolean trailing
        boolean root
    }

Esta abstracción permite compartir el estado exacto del diagrama codificando este objeto en Base64 en la URL.

---

Stack Tecnológico

Las decisiones tecnológicas se han tomado priorizando el rendimiento, la experiencia de desarrollo (DX) y el tipado estricto.

Herramienta	Rol en la Arquitectura	Justificación
Astro v5.2	Framework / Static Site Generator	Proporciona enrutamiento, Islands Architecture y renderizado ultrarrápido al despachar HTML mínimo por defecto.
TypeScript v5.7	Lenguaje Principal	Garantiza la integridad del modelo de datos (FileStructure) y previene errores en el parser en tiempo de compilación.
Dexie.js	Persistencia de Estado	Abstracción limpia sobre IndexedDB para guardar el progreso del usuario de forma asíncrona sin bloquear el hilo principal.
Tailwind CSS v4	Capa de Estilos	Permite un diseño ágil, responsivo y unificado, manejando además variaciones complejas de temas claros/oscuros.
Biome.js	Linter y Formatter	Sustituye a la clásica combinación ESLint+Prettier ofreciendo una ejecución unificada en fracciones de segundo para un código homogéneo.
Vitest	Entorno de Pruebas	Utilizado para validar el determinismo puro y casos límite dentro del parser léxico.

---

La orquestación de estas tecnologías da como resultado una herramienta robusta, con un dominio completamente agnóstico del cliente, envuelta en una arquitectura diseñada para escalar sin sacrificar un solo ciclo de CPU en dependencias innecesarias. Esta separación estricta entre la lógica de procesamiento jerárquico y la representación interactiva asegura que el código sea mantenible a largo plazo.