Spaces:

Daniel251
/

project-document-analyzer

Sleeping

App Files Files Community

project-document-analyzer / README.md

Daniel251

Update README.md

9fa4869 verified 9 months ago

preview code

Raw

History Blame Contribute Delete

14.7 kB

A newer version of the Gradio SDK is available: 6.19.0

Upgrade

metadata

title: Web Project Structure Viewer
emoji: 🔍
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: 5.49.1
app_file: app.py
pinned: false
license: mit

🔍 Web Project Structure Analyzer

Analise a estrutura completa de projetos web de forma automática e inteligente!

Ferramenta desenvolvida para desenvolvedores que precisam visualizar rapidamente a organização de projetos web, seja para documentação, code review, ou simplesmente entender a arquitetura de um projeto.

🎯 O Que Faz?

Esta aplicação analisa a estrutura de projetos web e gera:

🌳 Árvore Visual em formato ASCII art (fácil de copiar/colar)
📊 Estatísticas Detalhadas (arquivos, tamanho, taxa de relevância)
📄 Relatório em Markdown pronto para documentação
🎯 Filtragem Inteligente (ignora arquivos desnecessários automaticamente)
⚡ Análise Instantânea (basta fazer upload do ZIP)

✨ Características Principais

🚀 Simplicidade Total

Upload de arquivo ZIP
Análise automática ao enviar
Interface limpa e intuitiva
Sem configurações complexas

🧹 Filtragem Inteligente

O que é INCLUÍDO:

✅ Código fonte (.py, .js, .jsx, .ts, .tsx, .vue, .php, etc)
✅ Estilos (.css, .scss, .sass, .less)
✅ Markup (.html, .htm)
✅ Configurações críticas (package.json, requirements.txt, Dockerfile)
✅ Documentação (README.md, LICENSE)
✅ Arquivos SQL (.sql)
✅ Configs de ambiente (.env.example, .gitignore)

O que é IGNORADO automaticamente:

🚫 node_modules/ (dependências Node.js)
🚫 .git/ (histórico Git)
🚫 venv/ (ambientes virtuais Python)
🚫 pycache/ (cache Python)
🚫 dist/, build/ (arquivos compilados)
🚫 cache/, logs/, tmp/ (arquivos temporários)
🚫 .vscode/, .idea/ (configs de IDEs)
🚫 Arquivos minificados (.min.js, .min.css)
🚫 Source maps (.map)
🚫 Binários compilados (.pyc, .class, .so)
🚫 Arquivos grandes (>10MB)

📊 Estatísticas Geradas

| Métrica | Descrição |
|---------|-----------|
| 📁 Total de arquivos | Todos os arquivos escaneados |
| ✅ Arquivos relevantes | Apenas código/config importantes |
| 💾 Tamanho total | Tamanho do projeto em MB |
| 🎯 Taxa de relevância | % de arquivos úteis vs total |

🌳 Formato de Árvore

Visualização em ASCII art com ícones:

📁 meu-projeto-react/
├── 📦 package.json
├── 📖 README.md
├── 📁 src/
│   ├── ⚛️ App.jsx
│   ├── 📜 index.js
│   ├── 📁 components/
│   │   ├── ⚛️ Header.jsx
│   │   └── ⚛️ Footer.jsx
│   └── 📁 styles/
│       └── 🎨 main.css
└── 📁 public/
    └── 🌐 index.html

🛠️ Tecnologias e Métodos Utilizados

🐍 Backend (Python)

Framework: Gradio 5.49.1

Interface web moderna e responsiva
Upload de arquivos ZIP
Processamento assíncrono
Componentes interativos

Bibliotecas Padrão:

os - Navegação no sistema de arquivos
pathlib - Manipulação de caminhos
zipfile - Extração de arquivos ZIP
tempfile - Gestão de arquivos temporários
shutil - Operações de arquivos (limpeza)
typing - Type hints para código robusto

🏗️ Arquitetura do Código

1. Classe `WebProjectAnalyzer`

Núcleo da aplicação que implementa toda a lógica de análise.

Atributos principais:

- ignored_dirs: Set[str]          # 40+ pastas a ignorar
- relevant_extensions: Set[str]   # 20+ extensões relevantes
- critical_files: Set[str]        # 50+ arquivos importantes
- ignored_file_patterns: Set[str] # Padrões de arquivos a ignorar

2. Métodos Principais

`should_ignore(name, path, is_dir) -> bool`

Propósito: Determina se um arquivo/diretório deve ser ignorado.

Lógica:

Verifica se o diretório está na lista de ignorados
Sempre mantém arquivos críticos (package.json, etc)
Ignora arquivos ocultos (exceto importantes como .gitignore)
Ignora arquivos temporários (~, #)
Ignora arquivos com padrões indesejados (.min.js, .map)
Ignora arquivos >10MB

`is_relevant_file(name) -> bool`

Propósito: Determina se um arquivo é relevante para exibição.

Critérios:

Arquivos críticos → sempre relevante
Padrões ignorados → não relevante
Extensão na lista de relevantes → relevante

`get_file_icon(filename) -> str`

Propósito: Retorna emoji apropriado para o arquivo.

Mapeamento:

Arquivos específicos (package.json → 📦)
Por extensão (.py → 🐍, .js → 📜)
Padrão (📄)

`extract_zip(zip_path) -> str`

Propósito: Extrai ZIP e retorna diretório raiz.

Lógica:

Cria diretório temporário
Extrai todo o conteúdo do ZIP
Detecta se há pasta raiz única (comum em ZIPs do GitHub)
Retorna caminho correto

`analyze_structure(root_path, max_depth) -> Tuple`

Propósito: Analisa recursivamente a estrutura do projeto.

Algoritmo:

Inicialização: Cria estruturas de dados (output, stats, files)
Função recursiva analyze_directory:
- Lista todos os itens do diretório
- Separa diretórios de arquivos
- Filtra usando should_ignore()
- Atualiza estatísticas
- Renderiza arquivos com ícones
- Renderiza diretórios e recursão
- Controla profundidade máxima
Formatação: Usa caracteres ASCII (├──, └──, │) para árvore
Retorno: (estrutura_texto, estatísticas, lista_arquivos)

`create_structure_report(folder_name, structure, stats) -> str`

Propósito: Gera relatório completo em Markdown.

Conteúdo:

Cabeçalho com nome do projeto
Informações (data, projeto)
Tabela de estatísticas
Estrutura em bloco de código
Legenda de ícones
Rodapé

`process_zip(zip_file, max_depth) -> Tuple`

Propósito: Pipeline completo de processamento.

Fluxo:

Valida arquivo ZIP
Extrai para diretório temporário
Analisa estrutura
Gera relatório
Salva relatório em arquivo temp
Limpa recursos (finally block)
Retorna (relatório, estrutura, arquivo)

3. Função `create_interface()`

Cria a interface Gradio com todos os componentes.

Componentes:

gr.File() - Upload de ZIP
gr.Slider() - Profundidade de análise
gr.Markdown() - Relatório formatado
gr.Textbox() - Estrutura em texto puro
gr.File() - Download do relatório
gr.Button() - Re-análise manual

Eventos:

zip_input.change() - Análise automática ao upload
analyze_btn.click() - Re-análise manual
max_depth.change() - Re-análise ao mudar profundidade

🎨 Design Patterns Utilizados

Singleton Pattern: Classe analyzer instanciada uma vez
Strategy Pattern: Diferentes estratégias de filtragem (extensão, padrão, tamanho)
Template Method: Pipeline consistente em process_zip()
Factory Pattern: get_file_icon() cria ícones baseado em tipo
Observer Pattern: Eventos Gradio reagem a mudanças

⚡ Otimizações

Sets para Lookup: O(1) para verificações de ignorar/relevância
Lazy Evaluation: Apenas calcula tamanho se arquivo é relevante
Early Exit: Para recursão em profundidade máxima
Limpeza de Recursos: finally block garante remoção de temp files
Ordenação: sorted() para output consistente

🔒 Tratamento de Erros

try:
    # Operação principal
except zipfile.BadZipFile:
    # ZIP inválido
except PermissionError:
    # Sem permissão
except Exception as e:
    # Erro genérico com traceback
finally:
    # Limpeza de recursos

🚀 Como Usar

1️⃣ Preparar o Projeto

Opção A: Download do GitHub

Vá no repositório do GitHub
Clique em "Code" → "Download ZIP"
Pronto para upload!

Opção B: Comprimir Localmente

Windows:

Clique direito na pasta → "Enviar para" → "Pasta compactada"

Mac:

Clique direito na pasta → "Comprimir [nome-da-pasta]"

Linux:

zip -r meu-projeto.zip meu-projeto/

Ignorando lixo (recomendado):

# Node.js
zip -r projeto.zip . -x "node_modules/*" ".git/*"

# Python
zip -r projeto.zip . -x "venv/*" ".git/*" "*.pyc"

# Geral
zip -r projeto.zip . -x "node_modules/*" ".git/*" "venv/*" "__pycache__/*"

2️⃣ Upload e Análise

Arraste o arquivo ZIP para a área de upload
OU clique e selecione o arquivo
Aguarde alguns segundos (automático!)
Pronto! Visualize a estrutura

3️⃣ Usar os Resultados

📋 Copiar estrutura: Botão de copiar no campo de texto
💾 Download relatório: Arquivo Markdown completo
🔄 Re-analisar: Ajuste profundidade e clique "Re-Analisar"

📖 Exemplos de Uso

Projeto React

Entrada: meu-app-react.zip

Saída:

📁 meu-app-react/
├── 📦 package.json
├── 📦 package-lock.json
├── 📖 README.md
├── 🚫 .gitignore
├── 📁 src/
│   ├── ⚛️ App.jsx
│   ├── 📜 index.js
│   ├── 🎨 App.css
│   ├── 📁 components/
│   │   ├── ⚛️ Header.jsx
│   │   ├── ⚛️ Footer.jsx
│   │   └── ⚛️ Button.jsx
│   └── 📁 hooks/
│       └── 📜 useAuth.js
├── 📁 public/
│   ├── 🌐 index.html
│   └── 📄 manifest.json
└── 📁 tests/
    └── 📜 App.test.js

Estatísticas:
- Total: 45 arquivos
- Relevantes: 15 arquivos
- Tamanho: 2.3 MB
- Taxa: 33.3%

Projeto Django/Python

Entrada: meu-projeto-django.zip

Saída:

📁 meu-projeto-django/
├── 🐍 manage.py
├── 🐍 requirements.txt
├── 📖 README.md
├── 🔐 .env.example
├── 📁 myproject/
│   ├── 🐍 settings.py
│   ├── 🐍 urls.py
│   ├── 🐍 wsgi.py
│   └── 🐍 asgi.py
├── 📁 apps/
│   ├── 📁 users/
│   │   ├── 🐍 models.py
│   │   ├── 🐍 views.py
│   │   ├── 🐍 admin.py
│   │   └── 🐍 urls.py
│   └── 📁 blog/
│       ├── 🐍 models.py
│       └── 🐍 views.py
├── 📁 templates/
│   └── 🌐 base.html
└── 📁 static/
    ├── 📁 css/
    │   └── 🎨 style.css
    └── 📁 js/
        └── 📜 main.js

Estatísticas:
- Total: 52 arquivos
- Relevantes: 18 arquivos
- Tamanho: 1.8 MB
- Taxa: 34.6%

🎯 Casos de Uso

1. Documentação de Projetos

Adicione a estrutura ao README.md para facilitar navegação.

2. Code Review

Entenda rapidamente a organização antes de revisar código.

3. Onboarding de Desenvolvedores

Ajude novos membros a entenderem a arquitetura.

4. Planejamento de Refatoração

Visualize áreas que precisam reorganização.

5. Auditoria de Projetos

Identifique arquivos desnecessários ou mal organizados.

6. Apresentações Técnicas

Mostre a estrutura em reuniões ou documentações.

🔧 Configurações

Profundidade de Análise

1-2 níveis: Visão geral superficial

📁 projeto/
├── 📦 package.json
├── 📁 src/
└── 📁 public/

3-4 níveis (padrão): Balanceado

📁 projeto/
├── 📦 package.json
├── 📁 src/
│   ├── 📜 index.js
│   └── 📁 components/
│       ├── ⚛️ Header.jsx
│       └── ⚛️ Footer.jsx
└── 📁 public/
    └── 🌐 index.html

5-8 níveis: Análise profunda

📁 projeto/
├── 📦 package.json
├── 📁 src/
│   ├── 📜 index.js
│   └── 📁 components/
│       ├── 📁 layout/
│       │   ├── 📁 header/
│       │   │   ├── ⚛️ Header.jsx
│       │   │   └── 🎨 Header.css
│       │   └── 📁 footer/
│       │       └── ⚛️ Footer.jsx
...

💡 Dicas e Boas Práticas

✅ Faça

✅ Comprima apenas a pasta do projeto (não múltiplas pastas)
✅ Use profundidade 4-5 para projetos médios
✅ Use profundidade 6-8 para projetos grandes
✅ Baixe o relatório Markdown para documentação
✅ Copie a estrutura para README.md do projeto

❌ Evite

❌ Incluir node_modules, venv no ZIP (são ignorados de qualquer forma)
❌ ZIPs muito grandes (>500MB) - remova pastas pesadas antes
❌ Profundidade muito alta em projetos gigantes (lento)

📊 Limitações Conhecidas

⚠️ Arquivos >10MB são automaticamente ignorados
⚠️ Máximo de 8 níveis de profundidade
⚠️ Processamento pode levar tempo em projetos muito grandes
⚠️ Requer arquivo ZIP (não aceita pastas diretas)

🤝 Contribuindo

Este é um projeto open source! Contribuições são bem-vindas:

🐛 Reporte bugs abrindo uma issue
💡 Sugira novos recursos
🔧 Envie pull requests com melhorias
📖 Melhore a documentação

📜 Licença

MIT License - Sinta-se livre para usar em projetos pessoais ou comerciais.

🙋 FAQ

Q: Funciona com qualquer tipo de projeto? A: Sim! React, Vue, Angular, Django, Flask, Node.js, PHP, Ruby, etc.

Q: Os arquivos são armazenados? A: Não! Tudo é processado temporariamente e deletado após a análise.

Q: Posso usar offline? A: Sim! Clone o repositório e rode localmente com gradio app.py.

Q: Quanto tempo demora? A: Projetos pequenos (<100 arquivos): ~2s
Projetos médios (<1000 arquivos): ~10s
Projetos grandes: ~30-60s

Q: Tem limite de tamanho do ZIP? A: Recomendado <100MB. Remova node_modules/venv antes de comprimir.

🔗 Links Úteis

👨‍💻 Desenvolvido com

Python 3.10+
Gradio 5.49.1
❤️ e ☕

⭐ Se este projeto foi útil, considere dar uma estrela!

Última atualização: Outubro 2025