ASCII Tree

O ASCII Tree é uma ferramenta projetada para resolver um problema comum na documentação técnica: a representação visual, estruturada e legível de sistemas de arquivos.

Como engenheiro, concebi este projeto para oferecer uma interface limpa e rápida que transforma texto simples indentado em diagramas de árvore ASCII, eliminando a necessidade de ferramentas pesadas de diagramação ou o desenho manual e tedioso de caracteres.

Utilidade e Funcionamento Geral

O valor operacional deste projeto está em sua imediatez e precisão. No contexto do desenvolvimento de software, da redação de artigos técnicos ou da criação de documentação, ilustrar a hierarquia de diretórios é uma necessidade recorrente.

A ferramenta resolve esse problema por meio de um fluxo de trabalho em três etapas:

1. Entrada Estruturada: O usuário insere texto simples, usando indentação (espaços ou tabulações) para definir os níveis hierárquicos de aninhamento de arquivos e pastas.
2. Processamento Determinístico: O sistema analisa sintaticamente o texto, filtrando linhas vazias, reconhecendo caracteres especiais (como marcadores de Markdown) e construindo um modelo de dados em árvore na memória.
3. Renderização Parametrizada: Um motor de geração processa essa árvore e renderiza uma representação ASCII estática. O usuário pode modificar parâmetros em tempo real, como incluir caminhos completos (fullpath), caracteres UTF-8 avançados (fancy) ou sufixos de diretório (trailing slash).

Tudo isso ocorre localmente no navegador, oferecendo respostas em tempo real, persistência local e recursos de internacionalização, o que a torna útil tanto para perfis técnicos quanto não técnicos.

---

Arquitetura Geral

O projeto foi estruturado seguindo os princípios de Domain-Driven Design (DDD) adaptados ao ambiente Frontend e a Islands Architecture fornecida nativamente pelo Astro.

A razão técnica dessa abordagem é isolar completamente a lógica de negócio (análise sintática e geração da árvore) da camada de interface do usuário. Isso garante que o núcleo da aplicação permaneça puramente matemático, testável e agnóstico ao framework visual utilizado.

Separação de Responsabilidades

• Camada de Domínio (src/lib/tree-generator/): Contém as interfaces (FileStructure), o analisador léxico (parse-input.ts) e o motor de renderização (generate-tree.ts). É código TypeScript puro, sem dependências visuais.
• Camada de Aplicação e Estado: A persistência do estado da aplicação é gerenciada de forma assíncrona com IndexedDB, encapsulado pela biblioteca Dexie (src/lib/db.ts). Isso permite restaurar a sessão do usuário instantaneamente entre recarregamentos, delegando a responsabilidade de armazenamento ao cliente (offline-first).
• Camada de Apresentação: Utiliza componentes Astro estáticos e dinâmicos (src/components/), gerenciando a interatividade do editor de texto e os controles de configuração diretamente com Vanilla JS embutido, evitando assim a sobrecarga de frameworks reativos como React ou Vue em uma aplicação deste escopo.
• Sistema de Internacionalização (i18n): Baseado em roteamento por pastas e em um dicionário central (src/i18n/ui.ts). Desacopla as definições de texto dos componentes, injetando as traduções em tempo de compilação.

graph TD
    UI[Camada de Apresentação: Componentes Astro]
    State[Gerenciamento de Estado: IndexedDB / Dexie]
    Parser[Parser: Input -> Árvore em Memória]
    Renderer[Renderer: Árvore -> String ASCII]

    UI --> |Texto e Opções| Parser
    UI <--> |Sincronização| State
    Parser --> |FileStructure| Renderer
    Renderer --> |Resultado| UI

---

Modelagem de Dados e Lógica

O núcleo da aplicação modela um sistema hierárquico. A entidade principal é FileStructure.

Diagrama de Entidade

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

Fluxo de Transformação de Dados

A análise sintática é realizada em duas etapas. Primeiro, a string de entrada é dividida em linhas e um analisador léxico baseado em expressões regulares determina o nível de indentação e o nome base de cada nó, ignorando caracteres superficiais (como hífens de markdown).

Em seguida, executa-se um algoritmo de reconstrução que mantém uma pilha (path) dos nós atuais, percorre a lista plana e atribui as relações pai-filho com base exclusivamente nas diferenças matemáticas de indentCount.

sequenceDiagram
    participant User as Usuário
    participant Editor as UI / Editor
    participant Parser as parseInput()
    participant Renderer as generateTree()
    participant Dexie as IndexedDB

    User->>Editor: Digita texto indentado
    Editor->>Parser: Envia String bruta
    Parser->>Parser: Transforma em Array de Objetos Planos
    Parser->>Parser: Reconstrói Relações (Pai/Filhos)
    Parser-->>Renderer: Retorna objeto raiz FileStructure
    Renderer->>Renderer: Percorre a árvore (DFS) + Opções (Fancy, Root)
    Renderer-->>Editor: Retorna string ASCII final
    Editor->>Dexie: Persiste Input e Opções
    Editor->>User: Exibe o Diagrama Renderizado

O estado da aplicação para persistência e URLs de compartilhamento é tratado por meio de um modelo plano no Dexie:

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

Essa abstração permite compartilhar o estado exato do diagrama codificando esse objeto em Base64 na URL.

---

Stack Tecnológico

As decisões tecnológicas foram tomadas priorizando desempenho, experiência do desenvolvedor (DX) e tipagem estrita.

Ferramenta	Papel na Arquitetura	Justificativa
Astro v5.2	Framework / Gerador de Sites Estáticos	Fornece roteamento, Islands Architecture e renderização rápida, enviando HTML mínimo por padrão.
TypeScript v5.7	Linguagem Principal	Garante a integridade do modelo de dados (FileStructure) e previne erros do parser em tempo de compilação.
Dexie.js	Persistência de Estado	Abstração limpa sobre o IndexedDB para salvar o progresso do usuário de forma assíncrona, sem bloquear a thread principal.
Tailwind CSS v4	Camada de Estilos	Permite um design ágil, responsivo e unificado, além de gerenciar variações complexas de tema claro/escuro.
Biome.js	Linter e Formatador	Substitui a combinação clássica ESLint+Prettier, oferecendo execução unificada em frações de segundo para um código homogêneo.
Vitest	Ambiente de Testes	Utilizado para validar o determinismo puro e os casos-limite do parser léxico.

---

A orquestração dessas tecnologias resulta em uma ferramenta robusta, com um domínio completamente agnóstico ao cliente, inserido em uma arquitetura projetada para escalar sem dependências desnecessárias. Essa separação estrita entre a lógica de processamento hierárquico e a representação interativa garante a manutenibilidade do código a longo prazo.