Pular para o conteúdo principal

Sistema de Validação de Overlaps

O sistema de validação de overlaps é uma ferramenta automatizada que ajuda a manter a qualidade da documentação detectando conteúdo duplicado, inconsistências estruturais e possíveis redundâncias.

Visão Geral​

Este sistema foi desenvolvido para fortalecer nosso hub de conhecimento, garantindo que cada tópico tenha um local único e bem definido, evitando confusão para os usuários e facilitando a manutenção.

Componentes do Sistema​

1. Arquivo de Configuração (
sidebars.json
)​

O arquivo 

sidebars.json
centraliza toda a estrutura de navegação e serve como fonte da verdade para:

  • Estrutura hierárquica: Define como a documentação está organizada
  • Palavras-chave de monitoramento: Identifica termos que podem indicar overlaps
  • Seções críticas: Define quais áreas precisam de atenção especial
  • Regras de validação: Estabelece critérios para organização

2. Script de Validação (
scripts/validate-overlaps.js
)​

Script automatizado que executa verificações abrangentes:

  • Validação de estrutura: Verifica se arquivos existem conforme definido
  • Detecção de palavras-chave: Identifica uso excessivo de termos suspeitos
  • Análise de similaridade: Compara conteúdo entre arquivos
  • Geração de relatórios: Cria relatórios detalhados de problemas encontrados

3. Guidelines no CONTRIBUTING.md​

Diretrizes claras para contribuidores sobre:

  • Como verificar overlaps antes de contribuir
  • Critérios para decidir onde colocar novo conteúdo
  • Processo de revisão pré-merge
  • Ferramentas de verificação disponíveis

Como Usar o Sistema​

Execução Manual​

Para executar a validação manualmente:

# Usando npm
npm run validate-overlaps

# Usando pnpm
pnpm validate-overlaps

# Comando alternativo
pnpm check-overlaps

Integração no Fluxo de Trabalho​

O sistema pode ser integrado em diferentes pontos do fluxo de desenvolvimento:

Pré-commit​

Adicione ao seu 

.git/hooks/pre-commit
:

#!/bin/sh
npm run validate-overlaps
if [ $? -ne 0 ]; then
  echo "❌ Validação de overlaps falhou. Verifique o relatório."
  exit 1
fi

Pull Request​

Configure no seu CI/CD para executar automaticamente em pull requests:

# .github/workflows/validate-overlaps.yml
name: Validate Overlaps
on: [pull_request]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      - run: npm install
      - run: npm run validate-overlaps

Interpretando os Resultados​

Tipos de Problemas Detectados​

1. Problemas de Estrutura​

  • Arquivos ausentes: Arquivos referenciados no 
    sidebars.json
    que não existem
  • Seções mal organizadas: Estrutura que não segue a hierarquia definida

2. Palavras-chave Suspeitas​

  • Uso excessivo: Termos que aparecem muitas vezes e podem indicar redundância
  • Concentração: Palavras-chave agrupadas em poucos arquivos

3. Conteúdo Duplicado​

  • Títulos idênticos: Mesmos títulos em arquivos diferentes
  • Conteúdo similar: Texto com alta similaridade (>70%)

Exemplo de Relatório​

{
  "metadata": {
    "generatedAt": "2024-01-01T10:00:00.000Z",
    "totalIssues": 5,
    "configVersion": "1.0.0"
  },
  "summary": {
    "structure": 2,
    "keyword": 1,
    "content": 1,
    "similarity": 1
  },
  "issues": [
    {
      "type": "structure",
      "message": "Arquivo não encontrado: guia-instalacao",
      "path": "primeiros-passos/guia-instalacao",
      "timestamp": "2024-01-01T10:00:00.000Z"
    }
  ],
  "recommendations": [
    {
      "type": "structure",
      "priority": "high",
      "message": "Corrigir estrutura de arquivos ausentes",
      "count": 2
    }
  ]
}

Configuração Avançada​

Personalizando Palavras-chave​

Edite o arquivo 

sidebars.json
para adicionar ou remover palavras-chave:

{
  "overlapDetection": {
    "keywords": [
      "instalação",
      "configuração",
      "autenticação",
      "webhook",
      "api",
      "workflow",
      "dados",
      "integração",
      "credential",
      "trigger",
      "sua-palavra-chave"
    ]
  }
}

Ajustando Sensibilidade​

Modifique o script para ajustar a sensibilidade da detecção:

// Em scripts/validate-overlaps.js
if (similarity > 0.7) { // Ajuste este valor (0.0 a 1.0)
  // Detectar conteúdo similar
}

Adicionando Novas Seções​

Para monitorar novas seções, adicione ao 

sidebars.json
:

{
  "overlapDetection": {
    "sectionsToMonitor": [
      "primeiros-passos",
      "usando-n8n",
      "integracoes",
      "integracoes-br",
      "nova-secao"
    ]
  }
}

Boas Práticas​

Para Contribuidores​

  1. Execute a validação antes de submeter: Use 
    npm run validate-overlaps
  2. Revise o relatório: Corrija problemas antes do PR
  3. Consulte a estrutura: Verifique o 
    sidebars.json
    antes de criar conteúdo
  4. Use links internos: Referencie conteúdo existente ao invés de duplicar

Para Mantenedores​

  1. Execute validações regulares: Configure execução automática
  2. Revise relatórios: Analise problemas encontrados
  3. Atualize configuração: Mantenha 
    sidebars.json
    atualizado
  4. Documente decisões: Registre mudanças na estrutura

Para Revisores​

  1. Verifique o relatório: Use como parte do processo de revisão
  2. Aplique guidelines: Siga as diretrizes do CONTRIBUTING.md
  3. Solicite correções: Peça ajustes quando necessário
  4. Mantenha consistência: Garanta que mudanças seguem a estrutura

Troubleshooting​

Problemas Comuns​

Script não executa​

# Verifique se as dependências estão instaladas
npm install

# Verifique se o arquivo sidebars.json existe
ls sidebars.json

Relatório muito extenso​

  • Ajuste a sensibilidade da detecção
  • Revise as palavras-chave configuradas
  • Considere se o conteúdo realmente precisa ser consolidado

Falsos positivos​

  • Adicione exceções ao script
  • Refine as palavras-chave
  • Ajuste os critérios de similaridade

Logs e Debug​

Para debug detalhado, modifique o script:

// Adicione logs detalhados
console.log('Analisando arquivo:', filePath);
console.log('Similaridade calculada:', similarity);

Integração com Outras Ferramentas​

ESLint​

Configure regras específicas para documentação:

// .eslintrc.js
module.exports = {
  overrides: [
    {
      files: ['docs/**/*.md', 'docs/**/*.mdx'],
      rules: {
        // Regras específicas para documentação
      }
    }
  ]
};

Prettier​

Configure formatação para arquivos markdown:

// .prettierrc
{
  "overrides": [
    {
      "files": "*.md",
      "options": {
        "proseWrap": "always"
      }
    }
  ]
}

Próximos Passos​

Melhorias Planejadas​

  1. Interface web: Dashboard para visualizar relatórios
  2. Integração contínua: Execução automática em CI/CD
  3. Análise semântica: Detecção mais inteligente de similaridade
  4. Sugestões automáticas: Recomendações de consolidação

Contribuindo para o Sistema​

Para contribuir com melhorias no sistema:

  1. Reporte bugs: Use issues do GitHub
  2. Sugira melhorias: Abra discussões
  3. Submeta PRs: Contribua com código
  4. Documente mudanças: Atualize esta documentação

Conclusão​

O sistema de validação de overlaps é uma ferramenta essencial para manter a qualidade da nossa documentação. Ao seguir as diretrizes e usar as ferramentas disponíveis, contribuímos para um hub de conhecimento robusto e bem organizado.

Para dúvidas ou sugestões sobre o sistema, consulte as discussões da comunidade ou abra uma issue no repositório.