🇺🇸 EN← PortfólioGitHub ↗
CLI & DEVELOPER TOOLS · GIT AUTOMATION

cogit

Transforma modificações brutas de código em mensagens de commit semânticas, padronizadas e descritivas através de inferência por IA local ou em nuvem.

Runtime
Node.js 18+
Padrão
Conventional Commits 1.0
Privacidade
Filtro Local de Segredos
Latência Típica
< 1.2s por diff

TL;DR Executivo — Resumo da Engenharia

O cogit é uma ferramenta de linha de comando autoral desenvolvida por Alex Santos que elimina a fricção de escrever mensagens de commit manuais ou genéricas. Diferente de geradores ingênuos que enviam o diff inteiro para um LLM, o cogit executa inspeção sintática prévia, higieniza chaves de API e arquivos sensíveis (.env, certs), divide grandes alterações em blocos lógicos coerentes e produz commits estruturados rigorosamente pelo padrão Conventional Commits (tipo, escopo e descrição concisa).

DIAGRAMA & WORKFLOW

Arquitetura de Fluxo do Sistema

Visão macro de como o projeto processa requisições, gerencia dados e entrega valor técnico com máxima eficiência.

Fluxo Lógico & Pipeline de Execução 
+-------------------+      +----------------------+      +----------------------+
|  git diff --staged| ---> | Sanitização de Dados | ---> | Chunking & Heurística|
+-------------------+      | (Ignora .env / keys) |      | (Separação por escopo)|
                           +----------------------+      +----------------------+
                                                                    |
+-------------------+      +----------------------+                 v
| git commit -m "..."<---  |  Seleção TUI / Conf. | <--- +----------------------+
+-------------------+      | (Aprovar / Editar)   |      | Invocação LLM / Prompt|
                           +----------------------+      +----------------------+
ENGENHARIA DETALHADA

Os Pilares Técnicos Fundamentais

Decisões de design, algoritmos e técnicas aplicadas para garantir confiabilidade, segurança e excelência operacional.

01

Análise Sintática de Diffs e Chunking Inteligente

Filtragem seletiva de arquivos irrelevantes e divisão por contexto

Diffs de Git frequentemente contêm ruídos: arquivos gerados como `package-lock.json`, minificados, bundles compilados ou imagens. O cogit inspeciona os caminhos modificados e remove ruídos automaticamente da árvore de contexto. Se o commit envolver múltiplos diretórios desacoplados (por exemplo, `frontend/` e `backend/api`), o cogit propõe commits atômicos distintos para manter o histórico do Git limpo e rastreável.

02

Rigor com a Especificação Conventional Commits

Taxonomia semântica determinística para pipelines de CI/CD

O motor de inferência utiliza templates com poucas amostras (few-shot) para mapear intenções em tipos semânticos canônicos: `feat:` para adições, `fix:` para resolução de bugs, `refactor:` para melhorias sem alteração de comportamento, `perf:` para otimizações e `chore:` para manutenção. Isso permite que pipelines de Release Semântica (Semantic Release) e geradores de CHANGELOG leiam os commits sem interferência humana.

03

Proteção Anti-Vazamento e Privacidade Local-First

Garantia de que dados confidenciais nunca chegam à API de IA

Antes de qualquer requisição externa, o diff passa por um scanner regex de alta sensibilidade que detecta padrões de JWTs, chaves de API da AWS/OpenAI, senhas, certificados PEM e nomes de variáveis sensíveis. Se algum padrão for detectado, o cogit ofusca a linha correspondente ou aborta a execução alertando o desenvolvedor no terminal com status de erro explícito.

04

Interface TUI Interativa e Staging Seletivo por Hunk

Controle total do desenvolvedor antes da confirmação do commit

O cogit não realiza commits cegos. Ele apresenta as sugestões em uma TUI colorida e ergonômica, permitindo ao usuário aceitar com um clique, regenerar a mensagem com parâmetros alternativos, editar manualmente no $EDITOR padrão ou rejeitar partes específicas do diff (staging por hunk interativo).

IMPLEMENTAÇÃO EM CÓDIGO

Código em Prática

Exemplo concreto de uso, configuração e integração técnica.

Terminal — Instalação e Fluxo de Uso do cogit BASH 
# 1. Instalar globalmente via npm ou npx
npm install -g @alexlivre/cogit

# 2. Fazer alterações em seu projeto e adicionar ao staging
git add src/auth/jwt.service.ts src/auth/types.ts

# 3. Executar o cogit para análise instantânea
cogit

# Saída no terminal:
# [cogit] Analisando staged diff (2 arquivos, +42 / -15 linhas)...
# [cogit] Verificação de segurança: 0 segredos detectados.
# 
# Sugestão gerada:
# feat(auth): implement rotating refresh tokens with secure cookie storage
# 
# [Enter] Confirmar commit  |  [e] Editar  |  [r] Regenerar  |  [Esc] Cancelar
DÚVIDAS & DECISÕES

Perguntas Frequentes & Respostas Técnicas

Esclarecimentos detalhados sobre funcionamento, licenças, compatibilidade e privacidade.

O cogit envia todo o meu código para a nuvem?

Não. O cogit apenas avalia o git diff dos arquivos que estão na staging area (git add). Arquivos ignorados pelo .gitignore, binários e segredos detectados são excluídos localmente antes de qualquer requisição.

Posso usar meu próprio modelo ou chave de API local?

Sim. O cogit suporta configuração via arquivo ~/.cogitrc ou variáveis de ambiente, permitindo apontar para Ollama local (ex: llama3, qwen2.5-coder) ou provedores em nuvem como OpenAI e Anthropic.

O que acontece se eu discordar da mensagem sugerida?

O cogit foi desenhado para manter o desenvolvedor no controle. Basta pressionar "e" para abrir seu editor padrão (VS Code, Vim, Nano) com a mensagem pré-preenchida para ajuste manual.

O cogit funciona em repositórios corporativos com regras estritas?

Sim. Você pode definir regras customizadas de prefixo (como tickets Jira PROJ-1234) no arquivo de configuração do repositório.