João HenriqueandClaude Opus 5
dcdd73edb5
A documentação descrevia um sistema que não existe mais: 62/73 ferramentas
(são 74), writer.py e models.py como arquivos (viraram pacotes), 1032 testes
(são 1454), models_api.py descrito como "API FastAPI" (é ponte JSON) e o app
SwiftUI ausente por completo — 5.500 linhas que o usuário opera todo dia sem
uma linha de documentação.
Cada arquivo passa a ter uma função específica, com cabeçalho de escopo
dizendo o que cobre e o que NÃO cobre (com a seta para quem cobre). O objetivo
é ler só o necessário: doc fora do assunto custa tempo e processamento sem
entregar nada.
01 arquitetura camadas, duas portas de entrada, regras transversais
02 módulos mapa do engine, incluindo o pipeline de voz
03 server/tools as 74 tools, helpers e como criar uma nova
08 app macOS NOVO — build por swiftc, telas, ponte, etapa 5
09 manutenção NOVO — por onde começar, o que está aberto, sintoma→arquivo
CLAUDE.md ganha a seção "Documentação (MANDATORY)": tabela de roteamento
(qual arquivo abrir para cada tarefa) e a regra de que toda alteração de
código atualiza a doc no mesmo commit, com o mapa de o-que-mexeu → o-que-
atualizar. Doc velha engana mais que doc ausente.
O índice do 05_EXPERIENCIAS subiu para o topo: consultar "isso já quebrou
antes?" custava carregar 1.281 linhas antes de chegar na tabela.
Dívidas levantadas na varredura e registradas em 09 §2: etapa 6 ainda ignora
o phrase_review.json, offset de ~400ms do Whisper, MacApp sem teste, admin/
fora do lint, confirmações visuais pendentes no FCP, submódulo WHISPERX sujo.
Também corrigidos dois links quebrados no Engine/README que apontavam um
nível acima do certo.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
87 lines
4.5 KiB
Markdown
87 lines
4.5 KiB
Markdown
# 04 — Testes, Fluxo de Trabalho e Estado Atual
|
||
|
||
> **Escopo:** Como rodar e escrever testes, e o gate antes de commitar.
|
||
> **Não cobre:** O que testar em cada módulo (→ 02) · checklist de qualidade (→ 06)
|
||
|
||
## 1. Suíte de testes
|
||
|
||
**1032 testes em 24 arquivos** em `tests/`. Rode com `uv run pytest tests/ -v`.
|
||
|
||
| Arquivo | Cobre |
|
||
|---------|-------|
|
||
| `test_models.py` | `TimeValue` (aritmética), `Timecode`, propriedades de Clip, modelos de validação, helpers de Timeline |
|
||
| `test_writer.py` | insert_clip, add_marker (todos os tipos), trim_clip, delete_clip, split_clip, change_speed |
|
||
| `test_server.py` | handlers MCP, parser, dispatch |
|
||
| `test_rough_cut.py` | `RoughCutGenerator` |
|
||
| `test_features_v05.py` | connected clips, roles, timeline diff, reformat, silêncio, export, compatibilidade |
|
||
| `test_features_v06.py` | features da v0.6 |
|
||
| `test_marker_pipeline.py` | `build_marker_element`, batch auto-modes, índices de clip duplicados, `write_fcpxml` |
|
||
| `test_refactored_helpers.py` | `_index_elements`, `_iter_spine_clips`, `_find_spine_clip_at_seconds`, `_resolve_clip_duration`, `_make_asset_clip`, `_format_batch_result`, `serialize_xml` |
|
||
| `test_transcribe.py` | spans de frase/filler, álgebra de merge/invert de intervalos, degradação do Whisper, handlers por transcrição |
|
||
| `test_media_intel.py` | parse de `silencedetect`, mapeamento source→timeline, bounds de parâmetros, integração WAV real (skips sem ffmpeg) |
|
||
| `test_diff.py` | comparação de timelines |
|
||
| `test_export.py` | export Resolve / FCP7 |
|
||
| `test_live.py` | modo live |
|
||
| `test_security.py` | segurança de path / XML |
|
||
| `test_edge_cases.py`, `test_diversity.py`, `test_parser.py`, `test_validation.py`, `test_bundles.py`, `test_dtd_validation.py`, `test_relink.py`, `test_speed_cutting.py`, `test_targeted_gaps.py`, `test_fcpxml_writer.py` | demais suítes |
|
||
|
||
**Fixtures:** `examples/sample.fcpxml` + fixtures XML inline. NOTA: `sample.fcpxml`
|
||
NÃO é DTD-conformante (assets pré-`media-rep`, markers de capítulo no sequence) —
|
||
não o use como fixture de validade DTD. Testes criam arquivos temporários e limpam.
|
||
|
||
**Obs. transcribe/media:** testes exigem deps opcionais (`ffmpeg`, whisper).
|
||
Sem eles, os testes relevantes fazem `skip` — o CI instala.
|
||
|
||
## 2. Fluxo de trabalho padrão (obrigatório)
|
||
|
||
> **Regra do sistema:** sempre após concluir UMA correção de código, o sistema é
|
||
> automaticamente executado/validado.
|
||
|
||
```bash
|
||
./Engine/run_after_fix.sh
|
||
```
|
||
|
||
O que ele faz (e falha via `set -e` se qualquer um não passar):
|
||
|
||
1. `uv run ruff check . --exclude docs/` → **zero erros de lint**.
|
||
2. `uv run pytest tests/ -v` → **toda a suíte passa**.
|
||
|
||
### Equivalente manual (pre-commit)
|
||
```bash
|
||
ruff check . --exclude docs/ # lint — zero erros
|
||
pytest tests/ -v # testes — todos passam
|
||
```
|
||
|
||
O CI roda ambos em todo push para `main`. Se um falhar, o commit ganha X no GitHub.
|
||
Corrija o lint **antes** de commitar.
|
||
|
||
## 3. Como rodar a aplicação
|
||
|
||
```bash
|
||
uv run server.py # Inicia o servidor MCP (stdio)
|
||
uv run python admin/models_gui.py # UI desktop de gestão de modelos (Flet)
|
||
uv run --extra dev pytest tests/ -v # Testes com extra de dev
|
||
```
|
||
|
||
## 4. Estado atual do sistema (resumo "até agora")
|
||
|
||
- **v0.6.35** — núcleo FCPXML completo em Python (`fcpxml/`).
|
||
- **73 ferramentas MCP** em `server.py`, organizadas por dispatch `TOOL_HANDLERS`.
|
||
- **Suporte FCPXML 1.8–1.14** (`.fcpxml` e bundles `.fcpxmld` com sidecars),
|
||
escrita padrão 1.13.
|
||
- **Dual-mode:** XML (principal) + Live (push_to_fcp / list_fcp_libraries via Apple events).
|
||
- **Inteligência de mídia (v0.10):** silêncio via ffmpeg + beats via librosa (lazy).
|
||
- **Transcrição local Whisper** + gestão de modelos (`model_manager.py`, catálogo
|
||
`models.json`, cache HF, cancelamento de download).
|
||
- **UI desktop (Flet):** `admin/models_gui.py` — aba Modelos (download/selecionar/
|
||
remover/config pasta de modelos) e aba Transcrição (projeto FCPXML → transcrição).
|
||
- **API complementar:** `admin/models_api.py`.
|
||
- **Validação DTD:** contra DTDs oficiais do bundle do FCP (v0.10+).
|
||
- **Export cross-NLE:** DaVinci Resolve v1.9 + FCP7 XMEML v5.
|
||
|
||
## 5. Evolução prevista (roadmaps)
|
||
- `docs/CAPABILITY-AUDIT-2026-06.md` — auditoria do ecossistema + roadmap dual-mode.
|
||
- `docs/specs/06_IMPLEMENTATION_ROADMAP.md` — roadmap de implementação.
|
||
- `docs/TRANSCRIPTION-MODELS.md` — fases da gestão de modelos (MCP handlers e
|
||
wiring em `transcribe()` vêm em fase posterior; hoje `model_manager.py` é o
|
||
esqueleto com catálogo e primitivas de cache reais). |