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