EN: Deterministic disk audit (no AI) from a WinDirStat CSV export. Produces an interactive HTML dashboard with risk-ranked cleanup candidates. UI and reports are in Brazilian Portuguese.
Auditoria de disco determinística (sem IA) a partir de export CSV do WinDirStat. Gera um dashboard HTML interativo com KPIs, gráficos e um plano de ação classificado por risco — tudo em português.
Abrir demo ao vivo → · demo local · changelog
Atenção: a ferramenta apenas recomenda ações. Nenhum arquivo é deletado automaticamente.
No CSV sintético (tests/fixtures/sample.csv, ~250 GB simulados), a análise encontra ~22 GB seguros para limpeza, ~44 GB em “cuidado” e ~43 GB “não tocar” (dados pessoais/sistema) — com justificativa por item (Docker, WSL, modelos LLM, Android, caches, etc.).
Disco cheio é um problema recorrente em máquinas de desenvolvimento (Docker, WSL, caches, node_modules, modelos LLM). Em vez de apagar “no feeling”, este projeto transforma um snapshot do WinDirStat em um relatório acionável: detecta candidatos, classifica risco e explica o porquê.
Demonstra:
- Pipeline de dados tipado (pandas + regras declarativas)
- Pacote Python instalável (
diskaudit) com CLI - UX de relatório (Chart.js, filtros, sort, empty states)
- Engenharia defensiva (validador de CSV, privacidade no
.gitignore, testes + CI)
flowchart LR
A[CSV WinDirStat] --> B[load_csv]
B --> C[analyze]
C --> D[find_candidates]
D --> E[render_html]
E --> F[Dashboard HTML]
- Lê um snapshot do WinDirStat e detecta automaticamente a unidade e o perfil de usuário
- Identifica candidatos a limpeza (Lixeira, Temp, caches, Docker, WSL, jogos, etc.)
- Classifica cada item em Seguro, Cuidado ou Não tocar
- Exibe distribuição por pastas raiz, AppData e padrões conhecidos
- Lista os maiores arquivos, idade por ano e top extensões
- Python 3.10+
- WinDirStat para escanear o disco e exportar CSV
- Navegador moderno (o relatório embute Chart.js — funciona offline)
- Escaneie a unidade no WinDirStat
- Exporte: File → Export → CSV (UTF-8)
- Salve como
disk.csvna raiz deste projeto - Execute:
run.batO script instala dependências, gera disk_report.html e abre no navegador.
pip install -e .
# ou: pip install -r requirements.txt
python scripts/validate_csv.py disk.csv # opcional, recomendado
python disk_audit.py disk.csv
# após install: disk-audit disk.csvAbra disk_report.html manualmente se não usar run.bat.
pip install diskaudit
# ou, a partir do código-fonte:
pip install "git+https://github.com/GuilhermeRoesler/DiskAudit.git"
disk-audit disk.csvReleases publicadas com tags v* disparam o workflow de publicação no PyPI (Trusted Publishing).
# CSV e saída em caminhos customizados
python disk_audit.py "D:\exports\scan.csv" -o "D:\reports\auditoria.html"
# Template customizado (pasta com disk_dashboard_template.html)
python disk_audit.py disk.csv -t diskaudit/templates -o test_report.html
# Regenerar o demo do portfólio
python scripts/generate_demo.py| Argumento | Padrão | Descrição |
|---|---|---|
csv |
disk.csv |
Caminho do CSV exportado |
-o, --output |
disk_report.html |
Arquivo HTML de saída |
-t, --template-dir |
diskaudit/templates |
Pasta com disk_dashboard_template.html |
O export deve conter estas colunas (nomes em português, como no WinDirStat pt-BR):
| Coluna | Descrição |
|---|---|
Nome |
Caminho completo |
Arquivos |
Contagem de arquivos |
Subdiretórios |
Contagem de subpastas |
Tamanho Físico |
Bytes em disco (métrica principal) |
Tamanho Lógico |
Bytes lógicos |
Última Alteração |
Data de modificação |
Colunas extras (ex.: Atributos) são ignoradas.
python scripts/validate_csv.py disk.csvRetorna exit code 0 se OK, 1 se inválido.
| Seção | Conteúdo |
|---|---|
| KPIs | Total em uso, arquivos, % em Users, GB recuperáveis |
| Resumo executivo | Principais oportunidades em linguagem natural |
| Gráficos | Pastas raiz, AppData Local/Roaming, padrões detectados |
| Plano de ação | Candidatos filtráveis por risco, com ação e justificativa |
| Top arquivos | Maiores arquivos individuais |
| Idade por ano | Distribuição temporal dos arquivos |
Ordem sugerida de limpeza: candidatos Seguro → Cuidado (após confirmar que não usa) → revisar Não tocar manualmente.
pip install -e ".[dev]"
python -m unittest discover -s tests -v
ruff check .
mypy
coverage run -m unittest discover -s tests -v
coverage reportA CI no GitHub Actions roda lint (Ruff), type-check (mypy), coverage (Codecov) e testes em Python 3.10 / 3.12 / 3.13. Tags de release v* publicam no PyPI.
diskaudit/ # Pacote instalável
analyze.py # CSV → métricas
candidates.py / rules.py # Plano de ação por risco
rationales.py # Justificativas
render.py + templates/ # Dashboard HTML
static/ # Chart.js vendored
cli.py # Entry point disk-audit
disk_audit.py # Shim de compatibilidade
scripts/validate_csv.py # Validação do CSV
scripts/generate_demo.py # Regenera examples/demo_report.html
run.bat # Atalho Windows
examples/demo_report.html # Demo anonymizada
.cursor/skills/disk-audit/ # Spec canônica (examples, reference)
docs/ # Índice + screenshots
tests/ # Unittest + fixture CSV
.github/workflows/ # CI + Pages + PyPI
Arquivos locais (não versionados): disk.csv, disk_report.html.
O CSV e o relatório contêm caminhos e nomes de arquivos do seu sistema. Ambos estão no .gitignore — não faça commit desses arquivos. O demo em examples/ usa apenas dados sintéticos (TestUser).
- .cursor/skills/disk-audit/examples.md — fluxos, extensão de regras, troubleshooting
- .cursor/skills/disk-audit/reference.md — regras, padrões e rationales
- docs/README.md — índice da documentação + screenshots
- examples/README.md — como regenerar o demo
- CHANGELOG.md — histórico de versões
- CONTRIBUTING.md — como contribuir
- SECURITY.md — relatório de vulnerabilidades
- CODE_OF_CONDUCT.md — código de conduta
MIT © Guilherme Roesler