Modelos de Dados

Todos os modelos são dataclasses imutáveis (frozen=True) definidas em src/core/models.py.

MrEvent

Representa um evento de Merge Request recebido do webhook.

@dataclass(frozen=True)
class MrEvent:
    project_id: int        # ID do projeto no GitLab
    mr_iid: int            # IID do Merge Request
    action: Action         # "open" | "update"
    target_branch: str     # Branch destino
    source_branch: str     # Branch origem
    title: str             # Título do MR
    description: str       # Descrição do MR
    base_sha: str          # SHA da base (diff_refs)
    start_sha: str         # SHA inicial (diff_refs)
    head_sha: str          # SHA do HEAD (diff_refs)
    oldrev: Optional[str]  # SHA anterior (apenas action="update")
    newrev: Optional[str]  # SHA novo (apenas action="update")

Regras de seleção

action	Condição	Dados obtidos via
open	Sempre	GET /merge_requests/:id/changes
update	oldrev presente	GET /repository/compare?from=oldrev&to=newrev
update	oldrev ausente	Ignorado (retorna None)

FileDiff

Representa o diff de um único arquivo.

@dataclass(frozen=True)
class FileDiff:
    old_path: str          # Caminho original
    new_path: str          # Caminho atual
    lines: list[DiffLine]  # Linhas parseadas do diff

DiffLine

Uma linha individual do diff.

@dataclass(frozen=True)
class DiffLine:
    new_line: Optional[int]  # Número da linha no novo arquivo (None se deletada)
    old_line: Optional[int]  # Número da linha no arquivo antigo (None se adicionada)
    content: str             # Conteúdo da linha (sem o prefixo +/-)
    is_addition: bool        # True se linha foi adicionada

Exemplo de parsing

Diff de entrada:

@@ -1,3 +1,4 @@
 line one
+line two new
 line three
-line four old
 line five

Resultado:

new_line	old_line	content	is_addition
1	1	line one	false
2	-	line two new	true
3	2	line three	false
-	3	line four old	false
4	4	line five	false

Finding

Um achado/recomendação do LLM.

@dataclass(frozen=True)
class Finding:
    line: int              # Número da linha (new_line) no diff
    severity: Severity     # "high" | "medium" | "low"
    category: Category     # "bug" | "security" | "performance" | "clean_code"
    message: str           # Descrição curta e acionável

Categorias

Categoria	Descrição	Exemplo
bug	Erros lógicos, race conditions, null dereferences	Variável usada antes da inicialização
security	Vulnerabilidades, injeção, exposição de dados	SQL injection, hardcoded secrets
performance	Ineficiências, O(n²), I/O desnecessário	Loop com query N+1
clean_code	Legibilidade, naming, complexity	Função muito longa, nome confuso

Severidade

Nível	Critério
high	Bug crítico, vulnerabilidade de segurança, perda de dados
medium	Performance ruim, código frágil, manutenibilidade
low	Style guide, sugestões opcionais, best practices

Position (dict)

Mapeamento de um Finding para uma posição inline no GitLab Discussions API.

{
    "position_type": "text",
    "base_sha": "...",
    "start_sha": "...",
    "head_sha": "...",
    "old_path": "file.py",
    "new_path": "file.py",
    "new_line": 42
}

Retornado por map_finding_to_position(). Se None, o finding é postado como comentário global (fallback).