@gilbert_oliveira/commit-wizard 1.2.2 → 2.0.1

package/README.md

@@ -1,310 +1,473 @@
 # 🧙‍♂️ Commit Wizard
 
-[![npm version](https://badge.fury.io/js/%40gilbert_oliveira%2Fcommit-wizard.svg)](https://badge.fury.io/js/%40gilbert_oliveira%2Fcommit-wizard)
-[![CI/CD](https://github.com/gilbert-oliveira/commit-wizard/actions/workflows/ci.yml/badge.svg)](https://github.com/gilbert-oliveira/commit-wizard/actions/workflows/ci.yml)
-[![codecov](https://codecov.io/gh/gilbert-oliveira/commit-wizard/branch/main/graph/badge.svg?token=M74AR75FFD)](https://codecov.io/gh/gilbert-oliveira/commit-wizard)
+> **Gere mensagens de commit inteligentes usando IA**
+
+[![CI/CD](https://github.com/gilbert-oliveira/commit-wizard/workflows/CI%2FCD/badge.svg)](https://github.com/gilbert-oliveira/commit-wizard/actions)
+[![Codecov](https://codecov.io/gh/gilbert-oliveira/commit-wizard/branch/main/graph/badge.svg)](https://codecov.io/gh/gilbert-oliveira/commit-wizard)
+[![npm version](https://img.shields.io/npm/v/@gilbert-oliveira/commit-wizard.svg)](https://www.npmjs.com/package/@gilbert-oliveira/commit-wizard)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Gere mensagens de commit convencionais automaticamente com base nas alterações no código usando a API da OpenAI.
+Um CLI desenvolvido com Bun.js que analisa suas mudanças no Git e gera mensagens de commit personalizadas usando a API da OpenAI.
+
+## 📊 Status do Projeto
+
+- **✅ Core Functionality**: 100% completo
+- **✅ Smart Split**: 100% completo (cache implementado)
+- **✅ Testes**: 100% cobertura
+- **✅ Documentação**: 100% completa
+- **🔄 Distribuição**: 90% (CI/CD configurado, aguardando publicação)
+- **🚧 Interface Avançada**: 30% (edição de grupos em desenvolvimento)
 
 ## ✨ Funcionalidades
 
-- 🤖 **Geração inteligente de commits** usando GPT-4o/GPT-4o Mini
-- 🎯 **Multi-commit inteligente** - divide mudanças por contexto 🆕
-- 📝 **Convenção de Conventional Commits** automática
-- 🌍 **Suporte multilíngue** (Português e Inglês)
-- ⚙️ **Configuração flexível** (local e global)
-- 📊 **Análise de complexidade** do diff
-- 🚀 **Auto commit** opcional
-- 😀 **Emojis** opcionais nas mensagens
-- 🔄 **Regeneração** de mensagens
-- 📋 **Cópia para clipboard**
-- 🎯 **Detecção de breaking changes**
-- 🧪 **Cobertura de testes** completa (63 testes)
+### 🧠 **Geração Inteligente**
+
+- **Commit único**: Analisa todas as mudanças e gera uma mensagem coesa
+- **Smart Split**: IA agrupa arquivos relacionados em commits lógicos separados
+- **Split Manual**: Divisão manual por arquivo para controle total
+
+### ⚙️ **Configuração Flexível**
+
+- Arquivo `.commit-wizardrc` para personalização
+- Suporte a configuração global e local
+- Múltiplos modelos OpenAI (GPT-4o, GPT-3.5, etc.)
+- Estilos de commit: Conventional, Simple, Detailed
+
+### 🎨 **Interface Rica**
+
+- Interface interativa com opções de edição
+- Preview de mensagens antes do commit
+- Copiar para clipboard
+- Modos silencioso e automático
+
+### 🎯 **Smart Split Avançado**
+
+- Análise de contexto das mudanças
+- Agrupamento por funcionalidade, correção, refatoração
+- **Cache inteligente** para análises similares
+- **Interface de edição** (em desenvolvimento):
+  - ✏️ Renomear grupos
+  - 📁 Reorganizar arquivos entre grupos
+  - ➕ Criar novos grupos
+  - 🔗 Mesclar grupos existentes
+  - 🗑️ Excluir grupos vazios
+
+---
 
 ## 🚀 Instalação
 
-### Global (Recomendado)
+### Pré-requisitos
+
+- [Bun](https://bun.sh/) instalado
+- Chave da API OpenAI
+
+### Instalação Global
+
 ```bash
-npm install -g @gilbert_oliveira/commit-wizard
+bun install -g @gilbert_oliveira/commit-wizard
 ```
 
-### Local
+### Uso via npx (sem instalação)
+
 ```bash
-npm install @gilbert_oliveira/commit-wizard
+npx @gilbert_oliveira/commit-wizard
 ```
 
-## ⚙️ Configuração
+---
+
+## ⚡ Uso Rápido
+
+### 1. Configure sua chave OpenAI
+
+```bash
+export OPENAI_API_KEY="sua-chave-aqui"
+```
+
+### 2. Faça suas mudanças e adicione ao staging
+
+```bash
+git add .
+```
 
-### 1. API Key da OpenAI
-Defina sua chave da OpenAI como variável de ambiente:
+### 3. Execute o commit wizard
 
 ```bash
-export OPENAI_API_KEY=sk-...
+commit-wizard
 ```
 
-Adicione isso no seu `.bashrc`, `.zshrc` ou arquivo de ambiente equivalente.
+---
+
+## 📋 Comandos CLI
 
-### 2. Configuração do Wizard
-Execute o comando de configuração para personalizar o comportamento:
+### Modo Básico
 
 ```bash
-commit-wizard --config
+commit-wizard                    # Modo interativo padrão
+commit-wizard --yes              # Aceitar automaticamente
+commit-wizard --silent           # Modo silencioso
+commit-wizard --auto             # Automático (--yes + --silent)
+commit-wizard --dry-run          # Visualizar sem commitar
 ```
 
-Ou crie um arquivo `.commit-wizard.json` no seu projeto ou diretório home:
+### Split de Commits
+
+```bash
+commit-wizard --split            # Split manual por arquivo
+commit-wizard --smart-split      # Smart Split com IA
+commit-wizard --smart-split --yes # Smart Split automático
+```
+
+### Ajuda e Informações
+
+```bash
+commit-wizard --help             # Mostrar ajuda
+commit-wizard --version          # Mostrar versão
+```
+
+---
+
+## ⚙️ Configuração
+
+### Arquivo `.commit-wizardrc`
+
+Crie um arquivo `.commit-wizardrc` no seu projeto ou no diretório home:
 
 ```json
 {
-  "model": "gpt-4o",
-  "temperature": 0.2,
-  "maxTokens": 1000,
   "language": "pt",
+  "commitStyle": "conventional",
   "autoCommit": false,
-  "excludePatterns": ["*.lock*", "*.log", "node_modules/**"],
-  "includeEmoji": true
+  "splitCommits": true,
+  "openai": {
+    "model": "gpt-4o",
+    "maxTokens": 200,
+    "temperature": 0.7,
+    "timeout": 30000,
+    "retries": 2
+  },
+  "prompt": {
+    "includeFileNames": true,
+    "includeDiffStats": true,
+    "customInstructions": "",
+    "maxDiffSize": 8000
+  },
+  "smartSplit": {
+    "enabled": true,
+    "minGroupSize": 1,
+    "maxGroups": 5,
+    "autoEdit": false,
+    "confidenceThreshold": 0.7,
+    "preferredGroupTypes": ["feat", "fix", "refactor", "test", "docs"]
+  },
+  "ui": {
+    "theme": "auto",
+    "showProgress": true,
+    "animateProgress": true,
+    "compactMode": false
+  },
+  "cache": {
+    "enabled": true,        // ✅ Cache inteligente implementado
+    "ttl": 60,             // Tempo de vida em minutos
+    "maxSize": 100         // Máximo de entradas no cache
+  },
+  "advanced": {
+    "maxFileSize": 1024,
+    "excludePatterns": ["*.log", "*.tmp", "node_modules/**", ".git/**"],
+    "includePatterns": [],
+    "enableDebug": false,
+    "logLevel": "info"
+  }
 }
 ```
 
-## 🧠 Como Funciona
+### Gerar Configuração Exemplo
+
+```bash
+commit-wizard --init   # Cria .commit-wizardrc exemplo
+```
+
+---
+
+## 🧠 Smart Split - Funcionalidade Destacada
+
+O Smart Split usa IA para analisar o contexto das suas mudanças e criar commits organizados logicamente.
 
-1. **Análise**: Lê os arquivos staged (`git diff --cached`)
-2. **Processamento**: Divide diff grandes em chunks menores
-3. **IA**: Envia para OpenAI com prompts otimizados
-4. **Geração**: Cria mensagem seguindo Conventional Commits
-5. **Interação**: Permite edição, regeneração ou cópia
-6. **Commit**: Executa git commit com a mensagem final
+### Como Funciona
 
-## 📝 Exemplos de Uso
+1. **Análise de Contexto**: IA analisa arquivos e diffs
+2. **Agrupamento Inteligente**: Agrupa por funcionalidade/correção
+3. **Interface de Edição**: Personaliza grupos antes do commit
+
+### Exemplo de Uso
 
-### Uso Básico
 ```bash
-# Adicione arquivos ao stage
-git add .
+# Você modificou:
+# src/auth/login.ts
+# src/auth/register.ts
+# src/components/LoginForm.tsx
+# tests/auth.test.ts
+# docs/authentication.md
+
+commit-wizard --smart-split
+```
 
-# Execute o wizard
-commit-wizard
+**Resultado:**
+
+```
+🧠 Análise de Contexto
+✅ 3 grupo(s) identificado(s):
+
+1. **Sistema de Autenticação**
+   📄 src/auth/login.ts, src/auth/register.ts
+   💡 Implementação do core de autenticação
+   🎯 Confiança: 95%
+
+2. **Interface de Autenticação**
+   📄 src/components/LoginForm.tsx
+   💡 Componentes de UI para autenticação
+   🎯 Confiança: 90%
+
+3. **Documentação e Testes**
+   📄 tests/auth.test.ts, docs/authentication.md
+   💡 Testes e documentação relacionada
+   🎯 Confiança: 85%
+
+? O que você gostaria de fazer?
+  ✅ Prosseguir com esta organização
+  ✏️ Editar grupos
+  ✋ Fazer split manual
+  ❌ Cancelar
 ```
 
-### Comandos Disponíveis
-```bash
-commit-wizard                 # Gerar commit normal (um único commit)
-commit-wizard --split         # Multi-commit por contexto 🆕
-commit-wizard --config        # Configurar o wizard
-commit-wizard --info          # Ver informações do sistema
-commit-wizard --help          # Mostrar ajuda
+### Interface de Edição
+
+> **🚧 Em desenvolvimento** - A interface de edição de grupos será implementada em breve
+
+Quando implementada, você poderá:
+
+- **📝 Renomear grupos** - Alterar nome e descrição
+- **📁 Reorganizar arquivos** - Mover entre grupos
+- **➕ Criar novos grupos** - Grupos personalizados
+- **🔗 Mesclar grupos** - Combinar grupos existentes
+- **🗑️ Excluir grupos** - Remover grupos vazios
+
+---
+
+## 🎨 Estilos de Commit
+
+### Conventional (Padrão)
+
 ```
+feat(auth): implement user login system
 
-### 🎯 Multi-Commit Inteligente 🆕
+- Add login validation
+- Create session management
+- Add password encryption
+```
 
-O Commit Wizard agora pode **dividir automaticamente** suas mudanças em **múltiplos commits** organizados por contexto:
+### Simple
 
-```bash
-git add .
-commit-wizard --split
+```
+Add user login functionality
 ```
 
-**Como funciona:**
-- 🧠 **Análise inteligente** dos arquivos alterados
-- 📂 **Agrupamento por contexto**: testes, docs, features, fixes, etc.
-- 🎯 **Priorização automática**: bugs primeiro, depois testes, docs, features
-- ✨ **Commits bem organizados** com mensagens específicas para cada grupo
+### Detailed
 
-**Exemplo de saída:**
 ```
-🎯 Multi-Commit Inteligente
-📋 3 commits propostos:
+Implement comprehensive user authentication system
+
+This commit introduces a new authentication module that includes:
+- User login validation with email/password
+- Session management with JWT tokens
+- Password encryption using bcrypt
+- Error handling for invalid credentials
+
+Files modified:
+- src/auth/login.ts: Core login logic
+- src/auth/session.ts: Session management
+- tests/auth.test.ts: Unit tests
+```
 
-1. 🐛 fix: corrige validação de entrada
-   Arquivos (2): src/auth.ts, src/validators.ts
+---
 
-2. 🧪 test: adiciona testes para autenticação  
-   Arquivos (1): tests/auth.test.ts
+## 🔧 Variáveis de Ambiente
 
-3. 📚 docs: atualiza documentação da API
-   Arquivos (1): README.md
+```bash
+# Obrigatório
+export OPENAI_API_KEY="sua-chave-aqui"
 
-✔ Deseja prosseguir com estes commits? Yes
+# Opcionais
+export COMMIT_WIZARD_DEBUG="true"      # Ativar debug
+export COMMIT_WIZARD_DRY_RUN="true"    # Sempre dry-run
+```
 
-[1/3] Processando: 🐛 fix
-✅ Commit 1: 🐛 fix: corrige validação de entrada em auth.ts
+---
 
-[2/3] Processando: 🧪 test  
-✅ Commit 2: 🧪 test: adiciona testes abrangentes para auth
+## 📊 Exemplos Práticos
 
-[3/3] Processando: 📚 docs
-✅ Commit 3: 📚 docs: atualiza documentação da API
+### Commit Único Simples
 
-🎉 Multi-commit concluído!
-• Commits realizados: 3/3
-✨ Histórico organizado com sucesso!
-```
+```bash
+# Modificou apenas README.md
+git add README.md
+commit-wizard
 
-**Tipos de contexto detectados:**
-- 🐛 **fix** - Correções de bugs (prioridade 1)
-- 🧪 **test** - Testes (prioridade 2)  
-- 📚 **docs** - Documentação (prioridade 3)
-- 🔧 **chore** - Configurações (prioridade 4)
-- 💄 **style** - Formatação (prioridade 5)
-- ♻️ **refactor** - Refatoração (prioridade 6)
-- ✨ **feat** - Novas funcionalidades (prioridade 7)
-- 🔄 **ci** - CI/CD (prioridade 8)
-
-### Exemplo de Output
+# Resultado: "docs: update project documentation"
 ```
-📈 Análise do Diff:
-• Arquivos alterados: 3
-• Linhas adicionadas: +45
-• Linhas removidas: -12
-• Tokens estimados: 850
-• Complexidade: 🟡 Moderada
-
-✨ Mensagem de commit gerada:
-feat(auth): adiciona autenticação OAuth2 com Google
-
-💰 Tokens utilizados: 1,234 (prompt: 987, resposta: 247)
-
-O que deseja fazer com a mensagem de commit?
-❯ 📌 Confirmar e commitar
-  📝 Editar a mensagem antes de commitar
-  🔄 Regenerar mensagem
-  📋 Copiar para clipboard
-  🚫 Cancelar o commit
+
+### Smart Split para Feature Complexa
+
+```bash
+# Implementou sistema completo de autenticação
+git add src/auth/ src/components/auth/ tests/auth/ docs/auth.md
+
+commit-wizard --smart-split
+
+# Resultado: 3 commits organizados por contexto
+# 1. feat(auth): implement core authentication system
+# 2. feat(ui): add authentication components
+# 3. test(auth): add comprehensive auth tests
 ```
 
-## 🛠 Modelos Suportados
+### Cache Inteligente
 
-- **GPT-4o** (padrão) - Mais recente e eficiente
-- **GPT-4o Mini** - Mais rápido e econômico
-- **GPT-4 Turbo** - Versão anterior robusta
-- **GPT-3.5 Turbo** - Opção econômica
+O Commit Wizard usa cache inteligente para otimizar performance:
 
-## 🧪 Scripts de Desenvolvimento
+- **Cache de análises**: Evita chamadas repetidas à OpenAI
+- **Hash MD5**: Identifica análises similares automaticamente
+- **TTL configurável**: Invalida cache antigo automaticamente
+- **Limpeza automática**: Remove entradas antigas quando necessário
+
+### Split Manual para Controle Total
 
 ```bash
-npm run build         # Compilar TypeScript
-npm run dev           # Modo desenvolvimento
-npm run test          # Executar testes
-npm run test:watch    # Testes em modo watch
-npm run test:coverage # Testes com cobertura
-npm run lint          # Verificar lint
-npm run lint:fix      # Corrigir lint automaticamente
-npm run format        # Formatar código
-npm run format:check  # Verificar formatação
-npm run clean         # Limpar arquivos build
+# Múltiplas mudanças não relacionadas
+git add .
+commit-wizard --split
+
+# Você escolhe arquivo por arquivo
+# Resultado: commits separados para cada mudança
 ```
 
-## 📊 Conventional Commits Suportados
+---
 
-O wizard gera mensagens seguindo a [especificação Conventional Commits](https://www.conventionalcommits.org/):
+## 🧪 Desenvolvimento e Testes
 
-- `feat:` - Novas funcionalidades
-- `fix:` - Correções de bugs
-- `docs:` - Mudanças na documentação
-- `style:` - Formatação, ponto e vírgula, etc.
-- `refactor:` - Mudanças que não alteram funcionalidade
-- `perf:` - Melhorias de performance
-- `test:` - Adição ou correção de testes
-- `chore:` - Mudanças em ferramentas, configs, etc.
-- `ci:` - Mudanças no CI/CD
+### Executar Testes
 
-### Breaking Changes
-Para alterações que quebram compatibilidade:
+```bash
+bun test                    # Todos os testes
+bun test src/__tests__      # Testes unitários
+bun test tests/             # Testes de integração
 ```
-feat!(auth): reestruturar API de login
 
-BREAKING CHANGE: A API de login foi alterada e não é compatível com versões anteriores.
+### Desenvolvimento Local
+
+```bash
+git clone https://github.com/gilbert-oliveira/commit-wizard
+cd commit-wizard
+bun install
+bun run dev
 ```
 
-## 🎯 Configurações Avançadas
+### Build
 
-### Padrões de Exclusão
-Customize quais arquivos ignorar:
-```json
-{
-  "excludePatterns": [
-    "*.lock*",
-    "*.log",
-    "node_modules/**",
-    "dist/**",
-    "coverage/**"
-  ]
-}
+```bash
+bun run build
 ```
 
-### Auto Commit
-Para fluxos automatizados:
-```json
-{
-  "autoCommit": true
-}
+---
+
+## 🤝 Contribuição
+
+1. Fork o projeto
+2. Crie uma branch para sua feature (`git checkout -b feature/nova-feature`)
+3. Commit suas mudanças (`git commit -m 'feat: add nova feature'`)
+4. Push para a branch (`git push origin feature/nova-feature`)
+5. Abra um Pull Request
+
+---
+
+## 🐛 Troubleshooting
+
+### Erro: "Chave da OpenAI não encontrada"
+
+```bash
+export OPENAI_API_KEY="sua-chave-aqui"
+```
+
+### Erro: "Não é um repositório Git"
+
+```bash
+git init
 ```
 
-### Multilíngue
-Suporte para português e inglês:
+### Commits muito grandes/pequenos
+
+Ajuste no `.commit-wizardrc`:
+
 ```json
 {
-  "language": "en"
+  "openai": {
+    "maxTokens": 300 // Para commits maiores
+  },
+  "prompt": {
+    "maxDiffSize": 16000 // Para diffs maiores
+  }
 }
 ```
 
-## 🚨 Tratamento de Erros
+### Smart Split não cria grupos
 
-O wizard trata graciosamente:
-- ❌ API key não configurada
-- ❌ Não é repositório Git
-- ❌ Sem arquivos staged
-- ❌ Erros da API OpenAI
-- ❌ Problemas de conectividade
-- ❌ Arquivos de configuração inválidos
+- Verifique conexão com internet
+- Confirme que há arquivos staged
+- Tente com menos arquivos primeiro
 
-## 💡 Dicas de Uso
+---
 
-1. **Stage seletivo**: Use `git add -p` para adicionar mudanças específicas
-2. **Configuração por projeto**: Crie `.commit-wizard.json` no projeto
-3. **Temperatura baixa**: Use 0.1-0.3 para mensagens mais consistentes
-4. **Exclude patterns**: Configure para ignorar arquivos irrelevantes
-5. **Auto commit**: Ative apenas em ambientes confiáveis
+## 📝 Licença
 
-## 🤝 Contribuindo
+MIT © [Gilbert Oliveira](https://github.com/gilbert-oliveira)
 
-1. Fork o projeto
-2. Crie uma branch para sua feature (`git checkout -b feature/AmazingFeature`)
-3. Commit suas mudanças (`git commit -m 'feat: add some AmazingFeature'`)
-4. Push para a branch (`git push origin feature/AmazingFeature`)
-5. Abra um Pull Request
+---
 
-### Executando Localmente
-```bash
-git clone https://github.com/gilbert-oliveira/commit-wizard.git
-cd commit-wizard
-npm install
-npm run build
-npm link
-```
+## 🔗 Links Úteis
+
+- [Documentação da OpenAI](https://platform.openai.com/docs)
+- [Conventional Commits](https://www.conventionalcommits.org/)
+- [Bun.js](https://bun.sh/)
+
+---
+
+## 🎯 Roadmap
+
+### ✅ Concluído Recentemente
+
+- [x] **Cache inteligente de análises** - Sistema de cache em memória com TTL configurável
+- [x] **Configuração avançada** - 40+ opções de configuração organizadas
+- [x] **Testes de integração** - Cobertura end-to-end completa
+- [x] **Documentação completa** - README profissional com exemplos práticos
+- [x] **CI/CD Pipeline** - Workflows automatizados para testes e build
 
-## 📈 Roadmap
+### 🚧 Em Desenvolvimento
 
-- [ ] Suporte a outros provedores de IA (Claude, Gemini)
-- [ ] Integração com GitHub Actions
-- [ ] Plugin para VS Code
-- [ ] Templates de commit customizáveis
-- [ ] Integração com Conventional Changelog
-- [ ] Suporte a monorepos
-- [ ] Cache de respostas IA
+- [ ] **Interface de edição de grupos** - Editar grupos do Smart Split antes do commit
+- [ ] **Tema escuro** - Suporte a tema escuro na interface
 
-## 📄 Licença
+### 📋 Próximas Funcionalidades
 
-Este projeto está licenciado sob a licença MIT. Veja o arquivo [LICENSE](LICENSE) para mais detalhes.
+- [ ] **Plugins personalizados** - Sistema extensível de plugins
+- [ ] **Integração com VS Code** - Extensão para VS Code
+- [ ] **Templates de commit customizados** - Templates personalizáveis
+- [ ] **Análise de impacto das mudanças** - Estimativa de impacto
 
-## 🙏 Agradecimentos
+### 🎨 Melhorias Planejadas
 
-- [OpenAI](https://openai.com/) pela API GPT
-- [Conventional Commits](https://www.conventionalcommits.org/) pela especificação
-- Comunidade open source pelas bibliotecas utilizadas
+- [ ] **Suporte a mais idiomas** - Interface multilíngue
+- [ ] **Interface gráfica opcional** - GUI para usuários não-CLI
+- [ ] **Hooks personalizáveis** - Hooks para CI/CD
+- [ ] **Animações e UX** - Interface mais fluida
 
 ---
 
-<div align="center">
-  <sub>Feito com 💜 por <a href="https://github.com/gilbert-oliveira">Gilbert de Oliveira Santos</a></sub>
-</div>
+**💡 Dica:** Use `commit-wizard --smart-split` para organizar automaticamente seus commits e manter um histórico Git limpo e profissional!