Pular para conteúdo

005-code-quality-tooling

Metadado Valor
Status ✅ Aceito
Data 12-02-2026
Decisores JGustavoCN
Contexto Developer Experience (DX) & Tooling

Resumo Executivo

Padronização das ferramentas de linting e configurações do editor (VS Code) via repositório. A decisão foca na eliminação de "falsos positivos" gerados por funcionalidades avançadas do MkDocs (tags Python em YAML e HTML em Markdown), priorizando uma experiência de desenvolvimento limpa.

1. Contexto e Problema

O projeto DataProfiler utiliza recursos avançados do ecossistema MkDocs que conflitam com as regras padrão de validação da maioria dos IDEs:

  • Tags Customizadas em YAML: O arquivo mkdocs.yml utiliza construtores específicos do Python (ex: !!python/name:...) para carregar extensões. Validadores de YAML padrão interpretam isso como erro de sintaxe.
  • HTML em Markdown: Para tabelas complexas (ex: SLA e Status), utiliza-se HTML inline (<span>, br). O linter padrão de Markdown (markdownlint) bloqueia essa prática (Erro MD033).

O resultado é um ambiente de desenvolvimento poluído visualmente com dezenas de erros falsos, dessensibilizando a equipa para problemas reais de código.

2. Drivers da Decisão (Requisitos)

  • Zero Falsos Positivos: O IDE não deve apontar erro em código que é válido para o compilador do MkDocs.
  • Configuração como Código: As regras de linting e ajustes do editor devem ser versionadas no Git para garantir consistência entre todos os desenvolvedores.
  • Permissividade Controlada: Deve-se permitir exceções às regras estritas quando necessário para a documentação visual.

3. Opções Consideradas

Opção A: Conformidade Estrita (Remover Funcionalidades)

Remover todo o HTML inline e as tags Python do mkdocs.yml.

Prós

  • Conformidade total com os padrões da indústria (YAML/Markdown puros).
  • Compatibilidade com qualquer editor de texto sem configuração extra.

Contras

  • Perda de funcionalidades críticas (ícones em tabelas, emojis customizados).
  • Empobrecimento visual da documentação.

Opção B: Configuração Local (Manual)

Instruir cada desenvolvedor a configurar o seu VS Code manualmente para ignorar os erros.

Prós

  • Não polui o repositório com arquivos de configuração de IDE.

Contras

  • Síndrome de "Funciona na minha máquina".
  • Processo de onboarding lento e propenso a erro humano.

Opção C: Configuração via Repositório (Workspace Settings) - ESCOLHIDA

Commitar as pastas .vscode/ e arquivos de configuração de linters (.markdownlint.json) diretamente no repositório.

Prós

  • Ambiente padronizado automaticamente ao clonar o projeto.
  • Regras de exceção explícitas e documentadas.

Contras

  • Acopla o projeto preferencialmente ao VS Code.

4. Decisão

Foi selecionada a Opção C (Configuração via Repositório).

Justificativa Técnica

A prioridade é a Experiência do Desenvolvedor (DX). Aceita-se o trade-off de reduzir a rigidez da validação YAML em troca de um ambiente limpo e funcional. A complexidade do MkDocs exige configurações que fogem ao padrão, e essas exceções devem ser geridas centralmente.

graph TD
    A["VS Code (User)"] --> B{".vscode/settings.json"}
    B -->|"yaml.validate: false"| C["Ignora Tags Python"]
    A --> D{".markdownlint.json"}
    D -->|"MD033: false"| E["Permite HTML Inline"]
    C --> F["Ambiente Limpo"]
    E --> F

5. Consequências (Trade-offs)

Tipo Descrição
✅ Positivo Onboarding imediato: ao abrir o projeto, as regras já são aplicadas.
✅ Positivo Possibilidade de usar tabelas HTML coloridas sem alertas de erro.
⚠ Negativo A validação de sintaxe YAML foi desligada globalmente no workspace; erros reais de indentação podem passar despercebidos até o momento do build.

6. Implementação Técnica

6.1. Linter de Markdown (.markdownlint.json)

Criação de arquivo na raiz para permitir tags HTML específicas de estilização.

{
  "default": true,
  "MD013": false,
  "MD033": {
    "allowed_elements": [
      "span",
      "div",
      "br",
      "font",
      "table",
      "tbody",
      "tr",
      "td",
      "th",
      "details",
      "summary",
      "figcaption",
      "h4",
      "h3",
      "h1",
      "ul",
      "li",
      "h2",
      "figure",
      "strong",
      "p",
      "hr",
      "code",
      "a"
    ]
  },
  "MD041": false,
  "MD046": false,
  "MD024": {
    "siblings_only": true
  }
}

6.2. Configuração do Workspace (.vscode/settings.json)

Força o VS Code a ignorar a validação nativa de YAML para evitar conflitos com construtores Python.

{
  "yaml.validate": false,
  "yaml.schemaStore.enable": false,
  "files.associations": {
    "*.yml": "yaml",
    "*.yaml": "yaml"
  },
  "editor.formatOnSave": true
}