@devix-tecnologia/directus-extension-inframe

# Melhorias Sugeridas para directus-file-zip Este documento lista melhorias identificadas durante a implementação de testes no projeto `directus-extension-inframe` que poderiam beneficiar o projeto `directus-file-zip`. ## 🚀 Melhorias de Alta Prioridade ### 1. Job de Build Separado no CI/CD **Problema**: Atualmente o build só é testado durante o release **Solução**: Adicionar job separado de build no CI ```yaml # .github/workflows/ci.yml e release.yml build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v5 - uses: actions/setup-node@v4 with: node-version: 22.17.0 - uses: pnpm/action-setup@v4 with: version: 10.20.0 run_install: false - run: pnpm install - run: pnpm build ``` **Benefícios**: - Detecta problemas de build antes do release - Feedback mais rápido para desenvolvedores - Evita releases quebrados ### 2. Dependabot com Agrupamento Inteligente **Problema**: Muitos PRs individuais para dependências relacionadas **Solução**: Agrupar dependências por categoria ```yaml # .github/dependabot.yml version: 2 updates: - package-ecosystem: "npm" directory: "/" schedule: interval: "weekly" day: "monday" open-pull-requests-limit: 10 groups: devix-dependencies: patterns: - "@devix-tecnologia/*" directus-dependencies: patterns: - "@directus/*" - "directus" semantic-release: patterns: - "@semantic-release/*" - "semantic-release" eslint-dependencies: patterns: - "eslint*" - "@eslint/*" typescript-dependencies: patterns: - "typescript*" - "@types/*" ``` **Benefícios**: - Reduz número de PRs de dependências - Agrupa atualizações relacionadas - Facilita revisão e merge ### 3. CI em Múltiplas Branches **Problema**: CI só roda na branch `main` **Solução**: Incluir branch `develop` no CI ```yaml # .github/workflows/ci.yml on: push: branches: ['main', 'develop'] pull_request: branches: ['main', 'develop'] ``` **Benefícios**: - Detecta problemas mais cedo no desenvolvimento - Garante qualidade na branch de desenvolvimento - Reduz surpresas no merge para main ## 📊 Melhorias de Média Prioridade ### 4. Coverage de Testes Aprimorado **Problema**: Falta relatórios detalhados de cobertura **Solução**: Configurar coverage com múltiplos formatos ```javascript // vitest.config.js export default defineConfig({ test: { coverage: { provider: 'v8', reporter: ['text', 'json', 'html'], exclude: [ 'node_modules/', 'dist/', 'src/tests/', '**/*.spec.ts', '**/*.test.ts' ] }, }, }); ``` **Scripts adicionais**: ```json { "scripts": { "test:coverage": "vitest run --coverage", "test:watch": "vitest", "test:ui": "vitest --ui" } } ``` **Benefícios**: - Relatórios visuais de cobertura - Identificação de código não testado - Melhora qualidade dos testes ### 5. Documentação Expandida de Testes **Problema**: Falta documentação detalhada sobre execução de testes **Solução**: Criar documentação abrangente ```markdown # docs/TESTING.md ## Estrutura de Testes ## Executando Localmente ## Troubleshooting ## Versões do Directus Testadas ## Adicionando Novos Testes ``` **Estrutura recomendada**: ``` project/ ├── src/ ├── tests/ # Testes separados do código fonte │ ├── setup.ts │ └── *.spec.ts ├── docs/ └── package.json ``` **Arquivo de exemplo**: ```env # .env.example DIRECTUS_VERSION=latest DIRECTUS_PUBLIC_URL=http://localhost:18055 DIRECTUS_ADMIN_EMAIL=admin@example.com DIRECTUS_ADMIN_PASSWORD=admin123 DEBUG_TESTS=false ``` **Benefícios**: - Facilita onboarding de novos desenvolvedores - Reduz tempo de setup - Documenta troubleshooting comum ### 6. Configuração TypeScript para Testes **Problema**: Configuração TypeScript não otimizada para testes **Solução**: Criar configuração específica ```json // tsconfig.test.json { "extends": "./tsconfig.base.json", "compilerOptions": { "types": ["vitest/globals", "node"], "moduleResolution": "node", "allowImportingTsExtensions": false, "resolveJsonModule": true }, "include": [ "src/tests/**/*", "vitest.config.js" ] } ``` **Benefícios**: - Melhor suporte de tipos nos testes - Separação de configurações - IntelliSense aprimorado ## 🔧 Melhorias de Baixa Prioridade ### 7. Refinamentos de ESLint **Problema**: ESLint muito restritivo em arquivos de teste **Solução**: Configurações específicas para testes ```typescript // src/tests/test-logger.ts /* eslint-disable no-console */ export const logger = { // Permite console apenas em logs de teste }; ``` **Configuração ESLint**: ```json { "overrides": [ { "files": ["src/tests/**/*"], "rules": { "no-console": "off", "@typescript-eslint/no-unused-vars": ["error", { "argsIgnorePattern": "^_" }] } } ] } ``` ### 8. Melhor Tratamento de Erros nos Testes **Problema**: Erros esperados geram warnings desnecessários **Solução**: Usar convenção de underscore para erros ignorados ```typescript // Antes } catch (error) { // Silently ignore - gera warning ESLint } // Depois } catch (_error) { // Silently ignore - sem warning } ``` ### 9. Logs de Debug Estruturados **Problema**: Logs de debug não estruturados **Solução**: Sistema de logs melhorado ```typescript export const logger = { currentTest: '', setCurrentTest(test: string) { this.currentTest = test; }, debug(message: string, ...args: any[]) { if (process.env.DEBUG_TESTS) { console.log(`[DEBUG] ${this.currentTest ? `[${this.currentTest}] ` : ''}${message}`, ...args); } }, // ... outros métodos }; ``` ### 10. Workflow de Release Aprimorado **Problema**: Release workflow poderia ser mais robusto **Solução**: Adicionar mais validações ```yaml release: needs: [lint, build, test] # Adicionar dependency do build if: github.event_name == 'push' runs-on: ubuntu-latest steps: - uses: actions/checkout@v5 - uses: actions/setup-node@v4 - uses: pnpm/action-setup@v4 - run: pnpm install - run: pnpm build # Garantir build antes do release - name: Release env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} NPM_TOKEN: ${{ secrets.NPM_TOKEN }} run: npx semantic-release --access public ``` ## 📋 Plano de Implementação ### Fase 1 (Impacto Imediato) - [ ] Adicionar job de build separado - [ ] Configurar dependabot com agrupamento - [ ] Incluir branch develop no CI ### Fase 2 (Melhoria de Qualidade) - [ ] Configurar coverage de testes - [ ] Criar documentação de testes - [ ] Adicionar configuração TypeScript para testes ### Fase 3 (Refinamentos) - [ ] Melhorar configuração ESLint - [ ] Implementar logs estruturados - [ ] Aprimorar workflow de release ## 🎯 Critérios de Sucesso - ✅ Build quebrado detectado antes do release - ✅ Menos PRs de dependências (agrupadas) - ✅ Problemas detectados na branch develop - ✅ Coverage de testes > 80% - ✅ Documentação completa para novos desenvolvedores - ✅ Zero warnings ESLint desnecessários ## 📚 Referências - [Dependabot Configuration](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file) - [GitHub Actions Best Practices](https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions) - [Vitest Coverage](https://vitest.dev/guide/coverage.html) - [TypeScript Project References](https://www.typescriptlang.org/docs/handbook/project-references.html)