feat(v2.7.0): treemap interativo, CLI para IA (JSON) e benchmark

AGENTS.md

@@ -34,6 +34,8 @@ para `reperio` (`_log_dir`).
 | `SearchThread` | Busca em largura com workers; troca de conexão, vítimas refeitas na hora, quarentena, rodadas no fim |
 | Cópia | `CopyManager`/`CopyWorker`, blocos de 1 MB, cancelável |
 | Exportação | `export_xlsx/csv/txt` (xlsx escrito com `zipfile`) |
+| Treemap | `space_tree()` (árvore a partir de `aggregate_folder_space`), `squarify()`, `treemap_layout()` (retângulos), `render_treemap_html()`; a interface só desenha o que já está em memória (`SpaceDialog._sp`) |
+| CLI | `_build_parser()` (argparse), `_parse_cli()`, `_run_cli()`: JSON em `_CliOut`; códigos de saída em `EXIT_*`; `--manifesto` é gerado a partir do parser |
 | `App` | Interface tkinter |
 
 ## 4. Regras da interface (não quebre)
@@ -68,3 +70,14 @@ Tcl aborta a suíte.
 Atualize `__version__` (`reperio.py`), o `CHANGELOG.md` e o `CITATION.cff`; depois
 `git tag vX.Y.Z && git push origin vX.Y.Z`. A Release é montada pelo GitHub Actions
 (`.github/workflows/release.yml`).
+
+## 8. CLI e uso por IAs (v2.7)
+
+- A CLI é contrato público: **não renomeie** campos do JSON nem mude códigos de saída sem subir a versão
+  e atualizar `docs/CLI.md`, `docs/IA.md` e o `--manifesto`. Campos novos são sempre aditivos.
+- Com `--json`, **nada** além do JSON vai para o stdout (mensagens vão para o stderr) e o JSON é ASCII.
+- Argumento desconhecido é erro de uso (código 2); a janela só abre sem nenhuma ação.
+- Toda ação nova da CLI precisa de teste em `tests/test_cli_treemap.py` (`run_cli` captura saída e código).
+- O ReperIO **só lê**: nenhuma ação da CLI altera arquivos do usuário; só grava o índice e o que
+  `--exportar`/`--treemap` pedirem.
+- Desempenho: `python tools/benchmark.py C:\ D:\` regenera `docs/BENCHMARK.md`.

BACKLOG.md

@@ -16,6 +16,11 @@ Ideias e próximos passos, em ordem de prioridade. O que já foi entregue está
 | 5 | P3 | M | Executável para **macOS** nas Releases | Hoje o macOS usa o código-fonte |
 | 6 | P3 | M | Troca de conexão no **Linux** (montagens CIFS alternativas) | Hoje o Linux usa o modo de rodadas no fim |
 | 7 | P3 | — | **Assinatura digital** do executável | Elimina o aviso do SmartScreen e reduz bloqueios de antivírus |
+| 8 | P2 | M | **Tamanho em disco vs. lógico:** gravar o atributo "só na nuvem" (OneDrive) e o espaço alocado | Hoje arquivos só-nuvem contam o tamanho lógico (use `--ignorar OneDrive`); `FIND_DATA` já traz o atributo `RECALL_ON_DATA_ACCESS` |
+| 12 | P2 | M | **Consultas em índices grandes:** `--espaco`/`--maiores`/`--extensoes` levam 7 a 10 s com 869 mil arquivos (benchmark); agregar em SQL (índice em `files(size)`, soma por pasta) em vez de em Python | Respostas de IA em < 1 s |
+| 9 | P3 | P | **Duplicados** (`--duplicados`): agrupar por tamanho + nome e confirmar por hash sob demanda | Complementa `--maiores` na limpeza de disco |
+| 10 | P3 | P | `--json` também para a janela de falhas e para `--status` por raiz | Mais autonomia para agentes |
+| 11 | P3 | M | Treemap: **zoom por clique no HTML** (hoje o HTML é estático e aninhado até `--profundidade`) | Navegar sem voltar à janela |
 
 ## Limitações conhecidas
 

CHANGELOG.md

@@ -4,6 +4,42 @@ Todas as mudanças relevantes do projeto. Formato baseado em
 [Keep a Changelog](https://keepachangelog.com/pt-BR/1.1.0/); versões seguem
 [SemVer](https://semver.org/lang/pt-BR/). Próximos passos ficam no [roadmap](BACKLOG.md).
 
+## [2.7.0] — 2026-10-17
+
+### Adicionado
+- **Treemap por tamanho ou por quantidade de arquivos** (opcional):
+  - Em **Espaço por pasta...**, painel interativo **acima da tabela, na mesma janela** (estilo
+    SpaceSniffer; **Ocultar treemap** e **Por: tamanho/quantidade**). Passar o mouse destaca o bloco e
+    mostra uma dica flutuante; clique seleciona e sincroniza com a tabela (nos dois sentidos); duplo
+    clique ou roda do mouse para cima entra na pasta; roda para baixo, botão direito ou Backspace sobe.
+    Desenha só dados já em memória, sem I/O na interface.
+  - **Exportação para HTML autônomo** (`Exportar... → Treemap`, ou `--treemap ARQ.html`): SVG com
+    dicas, alternância entre as duas métricas, tema claro/escuro e tabela dos maiores itens.
+  - Algoritmo *squarified* (`squarify`, `space_tree`, `treemap_layout`), testado quanto a proporção,
+    limites e sobreposição.
+- **CLI para pessoas, scripts e IAs** (`docs/CLI.md`, `docs/IA.md`):
+  - Novas ações: `--maiores N`, `--extensoes [N]`, `--buscar PADRÃO` (com `--ext`, `--tamanho`,
+    `--ordenar`, `--limite`, `--maiusculas`), `--treemap`, `--status` e `--manifesto`.
+  - **`--json`**: um objeto JSON em ASCII no stdout (mensagens vão para o stderr), com estatísticas da
+    varredura (tempo, arquivos/s, pastas lidas, falhas com o motivo) e do processo (pico de RAM).
+  - **`--so-indice`** (nunca varre o disco), `--em PASTA`, `--profundidade`, `--ignorar` em todas as
+    ações, `--silencioso`, `--sem-indice`, `--ajuda`.
+  - **Códigos de saída fixos** (0 ok, 1 erro, 2 uso, 3 pasta/índice ausente, 130 Ctrl+C).
+  - `--manifesto`: descrição da CLI em JSON (argumentos, campos de saída, códigos, exemplos).
+- `tools/benchmark.py` e `docs/BENCHMARK.md`: varredura a frio, reverificação a quente e consultas,
+  medidas pela própria CLI nos discos reais.
+- Consultas novas no índice: `Index.largest_files`, `Index.extension_summary`, `Index.stats`.
+
+### Corrigido
+- **`--ajuda`/`--help` abria a janela** e argumentos desconhecidos (ou com erro de digitação, como
+  `--espacoo`) também: agora são erro de uso (código 2) e a janela nunca abre por engano.
+- A CLI **descartava em silêncio as pastas que não conseguiu ler** (sem permissão, servidor caiu);
+  agora aparecem em `varredura.falhas` e as pastas sem leitura em `pastas_pendentes`/`completo`.
+- A CLI **caía com `UnicodeEncodeError`** ao imprimir nomes de arquivo fora da codificação do console
+  (cp1252/cp850); agora usa substituição segura.
+- A CLI **sempre saía com código 0**, mesmo com pasta inexistente ou raiz inacessível; agora há códigos
+  de saída distintos (3 = pasta inexistente ou sem dados no índice).
+
 ## [2.6.0] — 2026-10-17
 
 ### Adicionado

CITATION.cff

@@ -11,7 +11,7 @@ abstract: >-
 authors:
   - family-names: Gambati
     given-names: Joberth Firmino
-version: 2.6.0
+version: 2.7.0
 date-released: 2026-10-17
 license: MIT
 repository-code: "https://github.com/Yiuky/ReperIO"

README.md

@@ -13,7 +13,7 @@
   <a href="https://www.python.org/"><img src="https://img.shields.io/badge/Python-3.8%2B-3776AB.svg?logo=python&logoColor=white" alt="Python 3.8+"></a>
   <a href="#-requisitos"><img src="https://img.shields.io/badge/Plataforma-Windows%20%7C%20Linux-0078D6.svg" alt="Windows | Linux"></a>
   <a href="#-por-que-sem-dependências"><img src="https://img.shields.io/badge/Depend%C3%AAncias-nenhuma-success.svg" alt="Sem dependências"></a>
-  <a href="CHANGELOG.md"><img src="https://img.shields.io/badge/Versão-v2.6.0-28A745.svg" alt="Versão v2.6.0"></a>
+  <a href="CHANGELOG.md"><img src="https://img.shields.io/badge/Versão-v2.7.0-28A745.svg" alt="Versão v2.7.0"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-green.svg" alt="License MIT"></a>
   <a href="https://github.com/Yiuky/ReperIO/actions/workflows/tests.yml"><img src="https://github.com/Yiuky/ReperIO/actions/workflows/tests.yml/badge.svg" alt="Testes"></a>
 </p>
@@ -149,11 +149,27 @@ padrão ou filtro de tamanho. Na busca seguinte:
 - **Apagar índice** limpa tudo; desmarque **Usar** para ignorá-lo numa busca.
 - Fica em `%LOCALAPPDATA%\reperio\` (Windows) ou `~/.local/state/reperio/` (Linux), ou no caminho
   informado com `--indice <arquivo.sqlite>` (útil para compartilhar um índice na rede).
-- **Modo sem janela (CLI)** para tarefas agendadas e auditoria rápida de disco:
+- **Modo sem janela (CLI)** para tarefas agendadas, auditoria rápida de disco e **uso por IAs**:
   ```bash
   python reperio.py --indexar "\\servidor\dados" --indice "\\servidor\dados\_reperio.sqlite"
   python reperio.py --espaco "C:\Users\voce" --top 25 --exportar espaco.xlsx
+  python reperio.py --maiores 20 --em D:\ --so-indice          # 20 maiores arquivos, sem tocar o disco
+  python reperio.py --buscar "*.iso" --em D:\ --tamanho "> 1 GB" --json
+  python reperio.py --espaco D:\ --treemap mapa.html            # mapa visual em HTML
   ```
+  `--json` entrega **um objeto JSON** estável no stdout, `--so-indice` garante respostas instantâneas,
+  `--manifesto` descreve a CLI em JSON e os códigos de saída são fixos. Referência em
+  [docs/CLI.md](docs/CLI.md); guia para agentes em [docs/IA.md](docs/IA.md); números medidos em
+  [docs/BENCHMARK.md](docs/BENCHMARK.md).
+
+### 🗺️ Treemap interativo
+
+Em **Espaço por pasta...**, um painel de **treemap fica acima da tabela, na mesma janela** (estilo
+SpaceSniffer): a **área dos blocos é proporcional ao tamanho ou à quantidade de arquivos** (botão
+**Por: tamanho / quantidade**; **Ocultar treemap** esconde o painel). Passe o mouse para ver os detalhes,
+clique para selecionar (a tabela acompanha), **roda do mouse** ou duplo clique para entrar numa pasta,
+botão direito para subir. **Exportar... → Treemap
+(página HTML)** ou `--treemap mapa.html` gera uma página autônoma (sem internet, tema claro/escuro).
 
 ## 🛡️ Confiável em redes lentas e instáveis
 
@@ -278,7 +294,9 @@ listagem rápida via `ctypes` (Windows) e Excel escrito com `zipfile`.
 ```
 reperio.py            aplicativo completo, arquivo único (busca, índice, conexões, exportação, interface)
 iniciar.bat / .sh     lançadores: Python da máquina, senão o executável
-tests/                testes automatizados (unittest; cenários de rede simulados)
+tests/                testes automatizados (unittest; cenários de rede simulados, CLI e treemap)
+docs/                 CLI.md, IA.md (uso por agentes) e BENCHMARK.md
+tools/benchmark.py    mede varredura e consultas pela CLI (discos C:/D:)
 tools/build.py        gera o executável (PyInstaller) e o .zip de distribuição
 tools/screenshot.py   gera a imagem do README com dados de demonstração
 tools/make_logo.ps1   gera o logo; tools/make_icon.py monta o ícone .ico
@@ -296,9 +314,9 @@ python -m unittest discover -s tests -v          # Windows
 xvfb-run -a python3 -m unittest discover -s tests -v   # Linux sem tela
 ```
 
-68 testes, incluindo a simulação dos cenários vistos em servidor real: pasta que trava a conexão,
+95 testes, incluindo a simulação dos cenários vistos em servidor real: pasta que trava a conexão,
 vítimas refeitas na hora, cascata entre conexões, pastas grandes que não são travamento, nomes
-inválidos de servidores Samba antigos, filtros de tamanho/exclusão, análise de espaço por pasta e
+inválidos de servidores Samba antigos, filtros de tamanho/exclusão, análise de espaço por pasta, treemap, CLI/JSON e
 exportação com datas corrompidas. O GitHub Actions roda a suíte em Windows e Linux, com Python 3.8 e
 3.13, a cada push.
 

docs/BENCHMARK.md

@@ -0,0 +1,67 @@
+# Benchmark do ReperIO
+
+Gerado por `tools/benchmark.py` em 2026-10-17 19:31.
+
+- Máquina: Windows-11-10.0.26200-SP0
+- Python 3.13.14 · ReperIO v2.7.0 · 12 CPUs lógicas
+
+## C:\
+
+Disco: 299.1 GB no total, 168.4 GB usados, 130.8 GB livres.
+Pastas ignoradas: `OneDrive`.
+Indexado: **869.367 arquivos, 164.91 GB**; índice SQLite de 185.1 MB (há pastas sem leitura).
+
+| Etapa | Tempo (s) | Detalhe | Pico de RAM (MB) |
+|---|---:|---|---:|
+| Varredura a frio (índice vazio) | 85.4 | 869.363 arq. · 263636 pastas · 11182.2 arq./s; 531 pasta(s) não lidas | 410.8 |
+| Reverificação a quente (índice pronto) | 49.73 | 264167 pastas conferidas · 563 relidas | 365.5 |
+| `--espaco` (2 níveis) | 7.42 | — | 361.7 |
+| `--maiores 20` | 8.8 | — | 361.7 |
+| `--extensoes 20` | 9.81 | — | 361.7 |
+| `--buscar *.zip` | 9.38 | 116 encontrados | 361.8 |
+| `--treemap` (HTML) | 7.21 | HTML 229.5 KB | 361.7 |
+
+## D:\
+
+Disco: 176.8 GB no total, 141.3 GB usados, 35.5 GB livres.
+Indexado: **19.600 arquivos, 141.18 GB**; índice SQLite de 1.0 MB (há pastas sem leitura).
+
+| Etapa | Tempo (s) | Detalhe | Pico de RAM (MB) |
+|---|---:|---|---:|
+| Varredura a frio (índice vazio) | 0.76 | 19.600 arq. · 91 pastas · 35455.9 arq./s; 1 pasta(s) não lidas | 47.5 |
+| Reverificação a quente (índice pronto) | 0.96 | 92 pastas conferidas · 1 relidas | 44.2 |
+| `--espaco` (2 níveis) | 0.16 | — | 41.9 |
+| `--maiores 20` | 0.18 | — | 42.0 |
+| `--extensoes 20` | 0.2 | — | 42.4 |
+| `--buscar *.zip` | 0.2 | 2 encontrados | 41.9 |
+| `--treemap` (HTML) | 0.19 | HTML 18.9 KB | 42.0 |
+
+## %USERPROFILE%\OneDrive
+
+Disco: 299.1 GB no total, 168.4 GB usados, 130.8 GB livres.
+Indexado: **182.073 arquivos, 653.26 GB**; índice SQLite de 15.6 MB.
+
+| Etapa | Tempo (s) | Detalhe | Pico de RAM (MB) |
+|---|---:|---|---:|
+| Varredura a frio (índice vazio) | 6.92 | 182.073 arq. · 14698 pastas · 29096.6 arq./s | 84.6 |
+| Reverificação a quente (índice pronto) | 5.37 | 14698 pastas conferidas · 0 relidas | 98.9 |
+| `--espaco` (2 níveis) | 0.65 | — | 60.5 |
+| `--maiores 20` | 0.67 | — | 60.9 |
+| `--extensoes 20` | 0.9 | — | 62.8 |
+| `--buscar *.zip` | 1.07 | 148 encontrados | 60.8 |
+| `--treemap` (HTML) | 0.68 | HTML 125.2 KB | 61.5 |
+
+Tempo = relógio de parede do processo inteiro (inclui iniciar o Python). O cache do sistema operacional pode estar aquecido, então a varredura "a frio" mede o ReperIO, não o disco puro.
+
+## Leitura dos resultados
+
+- **Pastas "não lidas"** são acesso negado a pastas do sistema (`System Volume Information`, `$Recycle.Bin`
+  de outros usuários, `PerfLogs`) quando a CLI roda sem administrador. Aparecem em `varredura.falhas` e não
+  afetam o restante; o total inclui apenas o que o usuário pode ler.
+- **D:** poucos arquivos grandes (19,6 mil arquivos, 141 GB): o custo é por pasta/arquivo, não por byte.
+- **Consultas em C: levam 7 a 10 s** com 869 mil arquivos (a de `D:` leva 0,2 s). A causa provável é a
+  agregação em Python linha a linha (não medida em separado); é o ponto a otimizar (ver BACKLOG).
+- A reverificação "a quente" de C: (50 s) confere a data de cada uma das 264 mil pastas no disco; é bem mais
+  barata que a varredura a frio e só relê as pastas alteradas (563).
+- A pasta OneDrive soma 653 GB lógicos em 182 mil arquivos, mas esse tamanho é lógico (arquivos só-nuvem não ocupam o disco local): por isso o
+  `C:` foi medido com `--ignorar OneDrive`.