chore: adiciona .gitignore e commit.command

2026-08-18 08:25:29 -04:00
parent 68958fde00
commit 8fca456ceb
215 changed files with 65752 additions and 0 deletions
@@ -0,0 +1,84 @@
+# 04 — Testes, Fluxo de Trabalho e Estado Atual
+
+## 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/`).
+- **62 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).