gitpr-cli 0.0.16__tar.gz → 0.0.17__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {gitpr_cli-0.0.16/gitpr_cli.egg-info → gitpr_cli-0.0.17}/PKG-INFO +17 -6
- gitpr_cli-0.0.16/PKG-INFO → gitpr_cli-0.0.17/README.md +219 -224
- gitpr_cli-0.0.16/README.md → gitpr_cli-0.0.17/gitpr_cli.egg-info/PKG-INFO +235 -208
- {gitpr_cli-0.0.16 → gitpr_cli-0.0.17}/pyproject.toml +1 -1
- {gitpr_cli-0.0.16 → gitpr_cli-0.0.17}/src/cache.py +1 -2
- {gitpr_cli-0.0.16 → gitpr_cli-0.0.17}/src/main.py +220 -19
- {gitpr_cli-0.0.16 → gitpr_cli-0.0.17}/src/updater.py +1 -1
- {gitpr_cli-0.0.16 → gitpr_cli-0.0.17}/LICENSE +0 -0
- {gitpr_cli-0.0.16 → gitpr_cli-0.0.17}/gitpr_cli.egg-info/SOURCES.txt +0 -0
- {gitpr_cli-0.0.16 → gitpr_cli-0.0.17}/gitpr_cli.egg-info/dependency_links.txt +0 -0
- {gitpr_cli-0.0.16 → gitpr_cli-0.0.17}/gitpr_cli.egg-info/entry_points.txt +0 -0
- {gitpr_cli-0.0.16 → gitpr_cli-0.0.17}/gitpr_cli.egg-info/requires.txt +0 -0
- {gitpr_cli-0.0.16 → gitpr_cli-0.0.17}/gitpr_cli.egg-info/top_level.txt +0 -0
- {gitpr_cli-0.0.16 → gitpr_cli-0.0.17}/setup.cfg +0 -0
- {gitpr_cli-0.0.16 → gitpr_cli-0.0.17}/src/__init__.py +0 -0
- {gitpr_cli-0.0.16 → gitpr_cli-0.0.17}/src/ai_providers.py +0 -0
- {gitpr_cli-0.0.16 → gitpr_cli-0.0.17}/src/blame_engine.py +0 -0
- {gitpr_cli-0.0.16 → gitpr_cli-0.0.17}/src/config.py +0 -0
- {gitpr_cli-0.0.16 → gitpr_cli-0.0.17}/src/core.py +0 -0
- {gitpr_cli-0.0.16 → gitpr_cli-0.0.17}/src/issue_engine.py +0 -0
- {gitpr_cli-0.0.16 → gitpr_cli-0.0.17}/src/linter_engine.py +0 -0
- {gitpr_cli-0.0.16 → gitpr_cli-0.0.17}/src/security.py +0 -0
- {gitpr_cli-0.0.16 → gitpr_cli-0.0.17}/src/tui_issue.py +0 -0
- {gitpr_cli-0.0.16 → gitpr_cli-0.0.17}/tests/test_core.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: gitpr-cli
|
|
3
|
-
Version: 0.0.
|
|
3
|
+
Version: 0.0.17
|
|
4
4
|
Summary: Automação de PRs, Commits e Code Review com IA (Gemini e DeepSeek)
|
|
5
5
|
Author-email: Natan Fiuza <contato@natanfiuza.dev.br>
|
|
6
6
|
Requires-Python: >=3.10
|
|
@@ -125,11 +125,12 @@ Você pode passar as seguintes *flags* para ações específicas:
|
|
|
125
125
|
* `--provider <gemini|deepseek>`: Força a utilização de uma IA específica apenas para esta execução, ignorando o seu padrão guardado no `.env`.
|
|
126
126
|
* `-l` ou `--linter`: Roda **apenas o linter estático local** (sem chamadas de IA). Ideal para usar em pipelines de CI/CD para bloquear código fora do padrão.
|
|
127
127
|
* `-ih` ou `--installhooks`: Instala automaticamente os **Git Hooks locais** (`pre-commit` e `prepare-commit-msg`) no seu repositório.
|
|
128
|
-
* `-s` ou `--skill`: Cria os arquivos de template de contexto da IA (`.gitpr.commit.md`, `.gitpr.pr.md`, `.gitpr.review.md`, `.gitpr.filereview.md`) e do Linter (`.gitpr.linter.yml`) na raiz do projeto.
|
|
128
|
+
* `-s` ou `--skill`: Cria os arquivos de template de contexto da IA (`.gitpr.commit.md`, `.gitpr.pr.md`, `.gitpr.review.md`, `.gitpr.filereview.md`, `.gitpr.issue.md`, `.gitpr.blame.md`) e do Linter (`.gitpr.linter.yml`) na raiz do projeto.
|
|
129
129
|
* `-is` ou `--issue`: Gera automaticamente o rascunho de uma **Issue padronizada** e abre uma interface interativa (TUI) para edição ou envio direto via API REST. Esta funcionalidade possui **3 motores de contexto** dependendo da combinação de comandos:
|
|
130
130
|
* **Issue de Código Novo (`gitpr -is`):** Lê o `git diff` atual. **Por que usar:** Ideal para documentar rapidamente a tarefa que você acabou de programar, antes de commitar.
|
|
131
131
|
* **Issue de Épico/Release (`gitpr -is -ht`):** Lê o histórico completo da branch atual (Git Log + Cache de PRs). **Por que usar:** Ideal para gerar uma documentação consolidada de uma release inteira ou de uma *feature* grande que levou vários dias/commits para ser concluída.
|
|
132
132
|
* **Issue Arqueológica/Dívida Técnica (`gitpr -is -b arquivo:linhas`):** Lê a linha do tempo de uma regra específica. **Por que usar:** Ideal para documentar dívidas técnicas, explicando como um bloco de código legado evoluiu e por que precisa ser refatorado.
|
|
133
|
+
* `-h` ou `--help`: Mostra a ajuda geral com todas as opções. Use em conjunto com outra flag para **ajuda contextual** (ex: `gitpr -h --issue`, `gitpr -h --linter`) com link direto para a documentação detalhada de cada funcionalidade.
|
|
133
134
|
* `-u` ou `--update`: Verifica e instala a versão mais recente do GitPR (Auto-Updater).
|
|
134
135
|
* `-h` ou `--help`: Exibe o menu de ajuda.
|
|
135
136
|
|
|
@@ -172,6 +173,8 @@ Em vez de esconder as instruções da IA no código fonte, o GitPR utiliza arqui
|
|
|
172
173
|
* `.gitpr.pr.md`: Estrutura de tópicos exigida para a descrição do Pull Request.
|
|
173
174
|
* `.gitpr.review.md`: Define o foco de arquitetura (ex: SOLID, Clean Code) para a análise de diffs.
|
|
174
175
|
* `.gitpr.filereview.md`: Define regras rígidas de coesão e acoplamento para auditoria de um ficheiro completo (usado com `--input`).
|
|
176
|
+
* `.gitpr.issue.md`: Define a estrutura e o nível de detalhe exigido para a geração de Issues padronizadas (usado com `--issue`).
|
|
177
|
+
* `.gitpr.blame.md`: Define o foco da análise arqueológica para o rastreamento de código legado (usado com `--blame`).
|
|
175
178
|
|
|
176
179
|
## 📚 Documentação Técnica e Guias Avançados
|
|
177
180
|
|
|
@@ -179,10 +182,18 @@ Para manter este README conciso, detalhamos as implementações mais avançadas
|
|
|
179
182
|
|
|
180
183
|
Se você deseja implementar o GitPR como uma barreira de qualidade automatizada na sua equipe, consulte os guias abaixo:
|
|
181
184
|
|
|
182
|
-
* [**
|
|
183
|
-
* [**
|
|
184
|
-
* [**Geração de Issues e Interface TUI**](docs/issue-tui-help.md): Como utilizar a interface gráfica de terminal (TUI)
|
|
185
|
-
* [**
|
|
185
|
+
* [**Git Hooks Locais (Shift-Left)**](docs/git-hooks-locais.md): Como usar o `gitpr --installhooks` para criar travas na máquina do desenvolvedor e usar a IA para escrever mensagens de commit automaticamente.
|
|
186
|
+
* [**Linter Estático Customizável**](docs/linter-regras-customizadas.md): Como criar regras de validação no `.gitpr.linter.yml` para CI/CD e hooks de pre-commit.
|
|
187
|
+
* [**Geração de Issues e Interface TUI**](docs/issue-tui-help.md): Como utilizar a interface gráfica de terminal (TUI) e os 3 motores de contexto para gerir Issues estruturadas.
|
|
188
|
+
* [**Code Review com IA**](docs/code-review-ia.md): Guia dos modos de revisão (`--review`, `--fullreview`) e auditoria de arquivo (`--input`).
|
|
189
|
+
* [**Mensagens de Commit com IA**](docs/commit-message-ia.md): Como gerar mensagens no padrão Conventional Commits e integrar com Git Hooks.
|
|
190
|
+
* [**Arqueólogo de Código (Git Blame)**](docs/blame-arqueologo.md): Como rastrear a origem de regras de negócio com `git blame` e IA.
|
|
191
|
+
* [**Sistema de Skills e Templates**](docs/skill-template.md): Como customizar o comportamento da IA com arquivos `.gitpr.*.md`.
|
|
192
|
+
* [**Auto-Updater**](docs/auto-update.md): Como funciona a atualização automática (hot-swap) do GitPR.
|
|
193
|
+
* [**Provedores de IA**](docs/providers-ia.md): Configuração e seleção entre Google Gemini e DeepSeek.
|
|
194
|
+
* [**Pull Request (Modo Padrão)**](docs/pr-descricao-padrao.md): Fluxo completo de geração de descrição de PR sem flags.
|
|
195
|
+
* [**Integração com CI/CD (GitHub Actions)**](docs/github-ci-linter.md): Como rodar o GitPR no pipeline para travar o "Merge" de PRs com violações.
|
|
196
|
+
* [**Integração e Segurança do Token GitHub (PAT)**](docs/github-pat-integration.md): Entenda como o GitPR gera issues diretamente no repositório de forma autenticada.
|
|
186
197
|
|
|
187
198
|
## ⚡ Sistema de Cache Local (Economia de Quota)
|
|
188
199
|
|
|
@@ -1,224 +1,219 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
##
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
```bash
|
|
48
|
-
pipenv
|
|
49
|
-
```
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
##
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
1.
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
###
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
gitpr
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
*
|
|
172
|
-
*
|
|
173
|
-
*
|
|
174
|
-
*
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
##
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
**Natan Fiuza** \- [contato@natanfiuza.dev.br](mailto:contato@natanfiuza.dev.br)
|
|
221
|
-
|
|
222
|
-
## **📄 Licença**
|
|
223
|
-
|
|
224
|
-
Este projeto está licenciado sob a **GNU Lesser General Public License v2.1 (LGPL-2.1)**. Consulte o arquivo LICENSE para mais detalhes.
|
|
1
|
+
# **GitPR CLI 🚀**
|
|
2
|
+
|
|
3
|
+
GitPR CLI é uma ferramenta de automação de linha de comando que utiliza a inteligência artificial do **Google Gemini** e do **DeepSeek** para analisar as suas alterações de código (git diff) ou ficheiros completos. A ferramenta gera automaticamente mensagens de commit no padrão *Conventional Commits*, descrições detalhadas para Pull Requests e Code Reviews profundos visando a redução de dívida técnica.
|
|
4
|
+
|
|
5
|
+
## **🛠️ Tecnologias e Bibliotecas Utilizadas**
|
|
6
|
+
|
|
7
|
+
Este projeto foi desenvolvido em Python e utiliza as seguintes bibliotecas principais:
|
|
8
|
+
|
|
9
|
+
* [**Click**](https://click.palletsprojects.com/): Para criar uma interface de linha de comando (CLI) robusta e amigável.
|
|
10
|
+
* [**Google GenAI**](https://pypi.org/project/google-genai/): SDK oficial para integração direta com a API do Gemini.
|
|
11
|
+
* [**OpenAI**](https://pypi.org/project/openai/): Biblioteca utilizada devido à sua total compatibilidade com a poderosa API do **DeepSeek**.
|
|
12
|
+
* [**Python-dotenv**](https://pypi.org/project/python-dotenv/): Para a gestão segura de variáveis de ambiente.
|
|
13
|
+
* [**Pytest**](https://docs.pytest.org/): Para execução de testes unitários de forma simples, colorida e legível no console.
|
|
14
|
+
* [**Cryptography**](https://cryptography.io/): Para garantir que sua `GEMINI_API_KEY` seja armazenada de forma encriptada e segura no disco.
|
|
15
|
+
* [**PyYAML**](https://pyyaml.org/): Utilizado para ler e processar as regras customizadas de análise estática do arquivo `.gitpr.linter.yml`.
|
|
16
|
+
* [**Textual**](https://textual.textualize.io/): Biblioteca poderosa para a criação de Interfaces Gráficas de Terminal (TUI), utilizada no painel interativo de geração e edição de Issues.
|
|
17
|
+
* [**Requests**](https://pypi.org/project/requests/): Biblioteca elegante e robusta para requisições HTTP, utilizada para a comunicação com a API REST do GitHub.
|
|
18
|
+
|
|
19
|
+
----
|
|
20
|
+
|
|
21
|
+
## 📦 Como Compilar o Executável Localmente
|
|
22
|
+
|
|
23
|
+
Se você deseja gerar o seu próprio binário a partir do código-fonte, utilizamos o **PyInstaller**. Certifique-se de estar no diretório raiz do projeto e com o ambiente virtual configurado.
|
|
24
|
+
|
|
25
|
+
1. Instale as dependências de desenvolvimento (caso ainda não tenha feito):
|
|
26
|
+
```bash
|
|
27
|
+
pipenv install --dev
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
2. Execute o comando de build apontando para o nosso ponto de entrada (`run.py`):
|
|
31
|
+
```bash
|
|
32
|
+
pipenv run pyinstaller --noconfirm --onefile --icon=icon.ico --name gitpr run.py
|
|
33
|
+
```
|
|
34
|
+
> **Nota técnica:** A flag `--onefile` garante que todo o Python, bibliotecas e dependências ficam comprimidos num único binário, enquanto `--paths src` ajuda o compilador a encontrar os nossos arquivos `core.py` e `config.py`. 🛠️
|
|
35
|
+
|
|
36
|
+
Após a execução deste comando, o PyInstaller vai criar algumas pastas (`build` e `dist`).
|
|
37
|
+
O seu arquivo final e pronto a usar estará dentro da pasta **`dist/`** com o nome `gitpr` (ou `gitpr.exe` no Windows).
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
----
|
|
41
|
+
|
|
42
|
+
## 🧪 Executando Testes
|
|
43
|
+
|
|
44
|
+
Para garantir que a lógica de captura do Git e a integração com a IA estejam funcionando corretamente, utilizamos testes unitários.
|
|
45
|
+
|
|
46
|
+
1. Instale as dependências de teste (caso ainda não tenha feito):
|
|
47
|
+
```bash
|
|
48
|
+
pipenv install --dev pytest
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
2. Execute os testes com o comando:
|
|
52
|
+
```bash
|
|
53
|
+
pipenv run pytest -v
|
|
54
|
+
```
|
|
55
|
+
O Pytest irá detectar automaticamente os arquivos dentro da pasta `tests/` e apresentará um relatório detalhado da execução.
|
|
56
|
+
|
|
57
|
+
----
|
|
58
|
+
## **⚙️ Instalação e Configuração**
|
|
59
|
+
|
|
60
|
+
### **Usando o Executável (Recomendado)**
|
|
61
|
+
|
|
62
|
+
1. Faça o download do arquivo executável gitpr na aba "Releases" do GitHub.
|
|
63
|
+
2. Mova o executável para uma pasta que esteja no seu PATH (ex: /usr/local/bin no Linux/Mac ou na pasta do seu utilizador no Windows).
|
|
64
|
+
3. Na primeira execução, o assistente irá guiá-lo:
|
|
65
|
+
$ gitpr
|
|
66
|
+
```bash
|
|
67
|
+
🚀 Automação Inteligente de PRs com IA
|
|
68
|
+
|
|
69
|
+
🔧 Primeira execução detetada! Vamos configurar o GitPR CLI.
|
|
70
|
+
|
|
71
|
+
🔑 Insira sua GEMINI_API_KEY:
|
|
72
|
+
|
|
73
|
+
📄 Padrão do nome do arquivo de saída [{branch}_{datetime}_PR_DESC.md]:
|
|
74
|
+
````
|
|
75
|
+
*Nota: A sua configuração será guardada em segurança no arquivo `~/.gitpr/.env`.*
|
|
76
|
+
|
|
77
|
+
> **🔒 Nota sobre Segurança:** O GitPR CLI utiliza criptografia simétrica (Fernet). Sua chave de API é armazenada como um hash no arquivo `.env`, e a chave mestra para desencriptação é gerada automaticamente em `~/.gitpr/secret.key`. **Nunca compartilhe seu arquivo secret.key.**
|
|
78
|
+
|
|
79
|
+
### A partir do Código-Fonte
|
|
80
|
+
|
|
81
|
+
1. Clone o repositório: `git clone https://github.com/natanfiuza/gitpr.git`
|
|
82
|
+
|
|
83
|
+
2. Entre na pasta: `cd gitpr`
|
|
84
|
+
|
|
85
|
+
3. Atualize o ambiente:
|
|
86
|
+
```bash
|
|
87
|
+
pipenv install google-genai openai python-dotenv click cryptography
|
|
88
|
+
```
|
|
89
|
+
4. Execute: pipenv run python src/main.py
|
|
90
|
+
|
|
91
|
+
## **💻 Como Usar**
|
|
92
|
+
|
|
93
|
+
O GitPR possui um comportamento padrão poderoso e diversas opções avançadas para auxiliar no seu dia a dia como desenvolvedor.
|
|
94
|
+
|
|
95
|
+
### **Comportamento Padrão (Pull Request)**
|
|
96
|
+
Basta executar o comando puro no seu terminal:
|
|
97
|
+
```bash
|
|
98
|
+
gitpr
|
|
99
|
+
```
|
|
100
|
+
A ferramenta irá sincronizar com o remoto (`git fetch`), comparar as suas alterações com a branch principal remota (ex: `origin/main`), e gerar um arquivo Markdown (ex: `feature-login_20260421110134_PR_DESC.md`) na raiz do seu projeto com a sugestão completa para o seu Pull Request.
|
|
101
|
+
|
|
102
|
+
### **Opções e Comandos Avançados**
|
|
103
|
+
Você pode passar as seguintes *flags* para ações específicas:
|
|
104
|
+
|
|
105
|
+
* `-c` ou `--commit`: Executa um `git diff` local e exibe **apenas a mensagem de commit** sugerida.
|
|
106
|
+
* `-r` ou `--review`: Realiza um **Code Review** detalhado das alterações locais.
|
|
107
|
+
* `-f` ou `--fullreview`: Realiza um **Code Review completo** analisando todas as alterações desde a branch remota.
|
|
108
|
+
* `-i <arquivo>` ou `--input <arquivo>`: **Auditoria de Ficheiro Completo.** Usado obrigatoriamente em conjunto com `-r` ou `-f`, ele ignora o histórico do git e faz um Code Review do ficheiro inteiro. Excelente para atuar como consultor em refatoração de código legado.
|
|
109
|
+
* `--provider <gemini|deepseek>`: Força a utilização de uma IA específica apenas para esta execução, ignorando o seu padrão guardado no `.env`.
|
|
110
|
+
* `-l` ou `--linter`: Roda **apenas o linter estático local** (sem chamadas de IA). Ideal para usar em pipelines de CI/CD para bloquear código fora do padrão.
|
|
111
|
+
* `-ih` ou `--installhooks`: Instala automaticamente os **Git Hooks locais** (`pre-commit` e `prepare-commit-msg`) no seu repositório.
|
|
112
|
+
* `-s` ou `--skill`: Cria os arquivos de template de contexto da IA (`.gitpr.commit.md`, `.gitpr.pr.md`, `.gitpr.review.md`, `.gitpr.filereview.md`, `.gitpr.issue.md`, `.gitpr.blame.md`) e do Linter (`.gitpr.linter.yml`) na raiz do projeto.
|
|
113
|
+
* `-is` ou `--issue`: Gera automaticamente o rascunho de uma **Issue padronizada** e abre uma interface interativa (TUI) para edição ou envio direto via API REST. Esta funcionalidade possui **3 motores de contexto** dependendo da combinação de comandos:
|
|
114
|
+
* **Issue de Código Novo (`gitpr -is`):** Lê o `git diff` atual. **Por que usar:** Ideal para documentar rapidamente a tarefa que você acabou de programar, antes de commitar.
|
|
115
|
+
* **Issue de Épico/Release (`gitpr -is -ht`):** Lê o histórico completo da branch atual (Git Log + Cache de PRs). **Por que usar:** Ideal para gerar uma documentação consolidada de uma release inteira ou de uma *feature* grande que levou vários dias/commits para ser concluída.
|
|
116
|
+
* **Issue Arqueológica/Dívida Técnica (`gitpr -is -b arquivo:linhas`):** Lê a linha do tempo de uma regra específica. **Por que usar:** Ideal para documentar dívidas técnicas, explicando como um bloco de código legado evoluiu e por que precisa ser refatorado.
|
|
117
|
+
* `-h` ou `--help`: Mostra a ajuda geral com todas as opções. Use em conjunto com outra flag para **ajuda contextual** (ex: `gitpr -h --issue`, `gitpr -h --linter`) com link direto para a documentação detalhada de cada funcionalidade.
|
|
118
|
+
* `-u` ou `--update`: Verifica e instala a versão mais recente do GitPR (Auto-Updater).
|
|
119
|
+
* `-h` ou `--help`: Exibe o menu de ajuda.
|
|
120
|
+
|
|
121
|
+
> **⚙️ Nota Técnica (--hook):** O GitPR possui uma flag oculta `--hook <arquivo>` que é acionada exclusivamente pelo sistema de Git Hooks em background. Ela permite que a IA injete a mensagem sugerida diretamente no arquivo temporário do Git, sem poluir o seu terminal.
|
|
122
|
+
|
|
123
|
+
## 🛡️ Linter Local (Análise Estática)
|
|
124
|
+
|
|
125
|
+
O GitPR CLI permite que você defina regras rígidas que serão validadas instantaneamente durante o `--review` ou `--fullreview`, sem depender da IA. Isso é ideal para evitar que erros comuns (como `console.log` ou IPs de teste) cheguem ao repositório.
|
|
126
|
+
|
|
127
|
+
### Como configurar o `.gitpr.linter.yml`:
|
|
128
|
+
Ao rodar `gitpr --skill`, um modelo será gerado. Você pode configurar regras usando Expressões Regulares (Regex):
|
|
129
|
+
|
|
130
|
+
```yaml
|
|
131
|
+
rules:
|
|
132
|
+
- name: "check-localhost"
|
|
133
|
+
extensions: ["js", "php"] # Extensões que serão validadas
|
|
134
|
+
regex: 'http(s)?://(localhost|127\.0\.0\.1)' # O que procurar
|
|
135
|
+
message: "🚨 Uso de localhost detectado no arquivo {file_name}"
|
|
136
|
+
ignore_comments: true # Ignora se a linha estiver comentada
|
|
137
|
+
ignore_paths: # Pastas ou arquivos ignorados (aceita *)
|
|
138
|
+
- "vendor/*"
|
|
139
|
+
- "node_modules/*"
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
O Linter analisa apenas as **linhas adicionadas** no seu `git diff`, garantindo uma execução focada e extremamente rápida. Se houver violações, elas aparecerão com destaque no topo do seu arquivo de revisão.
|
|
143
|
+
|
|
144
|
+
## 🧠 Arquitetura Multi-Model (Agnóstico de IA)
|
|
145
|
+
|
|
146
|
+
O GitPR não está preso a uma única Inteligência Artificial. Durante a configuração inicial, o utilizador pode escolher o seu motor padrão. Atualmente suportamos:
|
|
147
|
+
* **Google Gemini** (Padrão: `gemini-2.5-flash`)
|
|
148
|
+
* **DeepSeek** (Padrão: `deepseek-chat`)
|
|
149
|
+
|
|
150
|
+
Pode alternar dinamicamente os modelos configurando as variáveis `GEMINI_API_MODEL` ou `DEEPSEEK_API_MODEL` no seu arquivo `~/.gitpr/.env`, ou alternar em tempo real usando a flag `--provider`.
|
|
151
|
+
|
|
152
|
+
## 🎯 Sistema de "Skills" Customizáveis (Prompt Engineering)
|
|
153
|
+
|
|
154
|
+
Em vez de esconder as instruções da IA no código fonte, o GitPR utiliza arquivos Markdown locais que atuam como *System Instructions*. Ao rodar `gitpr -s`, os seguintes arquivos são gerados na raiz do seu projeto para poder customizar a "persona" da IA de acordo com as regras de negócio da sua empresa:
|
|
155
|
+
|
|
156
|
+
* `.gitpr.commit.md`: Regras para geração das mensagens curtas de commit.
|
|
157
|
+
* `.gitpr.pr.md`: Estrutura de tópicos exigida para a descrição do Pull Request.
|
|
158
|
+
* `.gitpr.review.md`: Define o foco de arquitetura (ex: SOLID, Clean Code) para a análise de diffs.
|
|
159
|
+
* `.gitpr.filereview.md`: Define regras rígidas de coesão e acoplamento para auditoria de um ficheiro completo (usado com `--input`).
|
|
160
|
+
* `.gitpr.issue.md`: Define a estrutura e o nível de detalhe exigido para a geração de Issues padronizadas (usado com `--issue`).
|
|
161
|
+
* `.gitpr.blame.md`: Define o foco da análise arqueológica para o rastreamento de código legado (usado com `--blame`).
|
|
162
|
+
|
|
163
|
+
## 📚 Documentação Técnica e Guias Avançados
|
|
164
|
+
|
|
165
|
+
Para manter este README conciso, detalhamos as implementações mais avançadas e focadas em **DevOps** e **Integração Contínua** em documentos separados.
|
|
166
|
+
|
|
167
|
+
Se você deseja implementar o GitPR como uma barreira de qualidade automatizada na sua equipe, consulte os guias abaixo:
|
|
168
|
+
|
|
169
|
+
* [**Git Hooks Locais (Shift-Left)**](docs/git-hooks-locais.md): Como usar o `gitpr --installhooks` para criar travas na máquina do desenvolvedor e usar a IA para escrever mensagens de commit automaticamente.
|
|
170
|
+
* [**Linter Estático Customizável**](docs/linter-regras-customizadas.md): Como criar regras de validação no `.gitpr.linter.yml` para CI/CD e hooks de pre-commit.
|
|
171
|
+
* [**Geração de Issues e Interface TUI**](docs/issue-tui-help.md): Como utilizar a interface gráfica de terminal (TUI) e os 3 motores de contexto para gerir Issues estruturadas.
|
|
172
|
+
* [**Code Review com IA**](docs/code-review-ia.md): Guia dos modos de revisão (`--review`, `--fullreview`) e auditoria de arquivo (`--input`).
|
|
173
|
+
* [**Mensagens de Commit com IA**](docs/commit-message-ia.md): Como gerar mensagens no padrão Conventional Commits e integrar com Git Hooks.
|
|
174
|
+
* [**Arqueólogo de Código (Git Blame)**](docs/blame-arqueologo.md): Como rastrear a origem de regras de negócio com `git blame` e IA.
|
|
175
|
+
* [**Sistema de Skills e Templates**](docs/skill-template.md): Como customizar o comportamento da IA com arquivos `.gitpr.*.md`.
|
|
176
|
+
* [**Auto-Updater**](docs/auto-update.md): Como funciona a atualização automática (hot-swap) do GitPR.
|
|
177
|
+
* [**Provedores de IA**](docs/providers-ia.md): Configuração e seleção entre Google Gemini e DeepSeek.
|
|
178
|
+
* [**Pull Request (Modo Padrão)**](docs/pr-descricao-padrao.md): Fluxo completo de geração de descrição de PR sem flags.
|
|
179
|
+
* [**Integração com CI/CD (GitHub Actions)**](docs/github-ci-linter.md): Como rodar o GitPR no pipeline para travar o "Merge" de PRs com violações.
|
|
180
|
+
* [**Integração e Segurança do Token GitHub (PAT)**](docs/github-pat-integration.md): Entenda como o GitPR gera issues diretamente no repositório de forma autenticada.
|
|
181
|
+
|
|
182
|
+
## ⚡ Sistema de Cache Local (Economia de Quota)
|
|
183
|
+
|
|
184
|
+
O GitPR possui um motor inteligente de cache baseado em **MD5**. Sempre que você rodar um comando (`--review`, `--commit`, etc.), a ferramenta gera um hash exato do seu código atual (diff) e das instruções.
|
|
185
|
+
Se você rodar o mesmo comando novamente sem ter alterado o código, o GitPR intercepta a requisição e devolve o resultado instantaneamente (em milissegundos) a partir da pasta `~/.gitpr/cache/prompts/`, poupando seu tempo e suas cotas da API do Gemini!
|
|
186
|
+
|
|
187
|
+
## 🔄 Auto-Updater (Atualização Over-The-Air)
|
|
188
|
+
|
|
189
|
+
Nunca mais se preocupe em baixar novas versões manualmente. O GitPR possui um Guardião de Conexão e um atualizador embutido:
|
|
190
|
+
* Ele verifica a disponibilidade de rede antes de iniciar para não travar seu fluxo offline.
|
|
191
|
+
* Em cada execução, ele verifica silenciosamente se há um novo release oficial na API do GitHub.
|
|
192
|
+
* Você pode forçar a busca e instalação rodando `gitpr --update` ou `gitpr -u`.
|
|
193
|
+
* A ferramenta utiliza a técnica de *Hot-Swap*, baixando o novo `.exe` e substituindo a versão antiga de forma transparente.
|
|
194
|
+
|
|
195
|
+
## Publicar no PyPi
|
|
196
|
+
|
|
197
|
+
```bash
|
|
198
|
+
pipenv run python -m build
|
|
199
|
+
pipenv run twine upload dist/*
|
|
200
|
+
```
|
|
201
|
+
## **🤝 Como Contribuir**
|
|
202
|
+
|
|
203
|
+
Contribuições são muito bem-vindas! Para contribuir:
|
|
204
|
+
|
|
205
|
+
1. Faça um Fork do projeto.
|
|
206
|
+
2. Crie uma branch para a sua *feature* (git checkout \-b feature/NovaFuncionalidade).
|
|
207
|
+
3. Faça o commit das suas alterações (git commit \-m 'feat: adiciona nova funcionalidade'). Sugestão: Use o próprio GitPR para gerar esta mensagem! 😄
|
|
208
|
+
4. Faça o Push para a branch (git push origin feature/NovaFuncionalidade).
|
|
209
|
+
5. Abra um Pull Request.
|
|
210
|
+
|
|
211
|
+
## **✨ Agradecimentos e Autoria**
|
|
212
|
+
|
|
213
|
+
Projeto idealizado e desenvolvido por:
|
|
214
|
+
|
|
215
|
+
**Natan Fiuza** \- [contato@natanfiuza.dev.br](mailto:contato@natanfiuza.dev.br)
|
|
216
|
+
|
|
217
|
+
## **📄 Licença**
|
|
218
|
+
|
|
219
|
+
Este projeto está licenciado sob a **GNU Lesser General Public License v2.1 (LGPL-2.1)**. Consulte o arquivo LICENSE para mais detalhes.
|