Files

T

João HenriqueandClaude Opus 5 dcdd73edb5 docs: varredura geral, documentação por função e regra de atualização

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>

2026-08-19 22:51:33 -04:00

4.5 KiB

Raw Blame History

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.

./Engine/run_after_fix.sh

O que ele faz (e falha via set -e se qualquer um não passar):

uv run ruff check . --exclude docs/ → zero erros de lint.
uv run pytest tests/ -v → toda a suíte passa.

Equivalente manual (pre-commit)

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

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).

4.5 KiB Raw Blame History Unescape Escape