Skip to content

Commit 800a539

Browse files
marcialwushuCopilot
marcialwushu
and
Copilot
committed
docs: enhance documentation with architecture, database model, and runbook details; add MkDocs workflow for automatic deployment
Co-authored-by: Copilot <copilot@github.com>
1 parent 5a48eed commit 800a539

8 files changed

Lines changed: 544 additions & 39 deletions

File tree

‎.github/workflows/docs-gh-pages.yml‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
name: Docs (MkDocs)
2+
3+
on:
4+
push:
5+
branches: ["main"]
6+
paths:
7+
- "docs/**"
8+
- "mkdocs.yml"
9+
- ".github/workflows/docs-gh-pages.yml"
10+
workflow_dispatch:
11+
12+
permissions:
13+
contents: write
14+
15+
concurrency:
16+
group: docs-gh-pages
17+
cancel-in-progress: true
18+
19+
jobs:
20+
deploy:
21+
runs-on: ubuntu-latest
22+
23+
steps:
24+
- name: Checkout
25+
uses: actions/checkout@v4
26+
27+
- name: Setup Python
28+
uses: actions/setup-python@v5
29+
with:
30+
python-version: "3.12"
31+
cache: "pip"
32+
33+
- name: Install MkDocs
34+
run: |
35+
python -m pip install --upgrade pip
36+
pip install mkdocs mkdocs-material
37+
38+
- name: Build docs
39+
run: mkdocs build --strict
40+
41+
- name: Deploy to gh-pages
42+
env:
43+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
44+
run: mkdocs gh-deploy --force --clean --verbose

‎README.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -225,6 +225,30 @@ LIMIT 1;
225225

226226
---
227227

228+
## Documentação (MkDocs)
229+
230+
Este repositório possui documentação versionada em `docs/` com publicação automática para `gh-pages` via GitHub Actions.
231+
232+
### Rodar localmente
233+
234+
```bash
235+
python -m pip install --upgrade pip
236+
pip install mkdocs mkdocs-material
237+
mkdocs serve
238+
```
239+
240+
Depois acesse `http://127.0.0.1:8000`.
241+
242+
### Publicação automática
243+
244+
- Workflow: `.github/workflows/docs-gh-pages.yml`
245+
- Dispara em push para `main` quando houver alterações em `docs/**` ou `mkdocs.yml`
246+
- Publica no branch `gh-pages` usando `mkdocs gh-deploy`
247+
248+
> Se for a primeira publicação, confirme em **Settings → Pages** que o site usa o branch `gh-pages`.
249+
250+
---
251+
228252
## Licença
229253

230254
Consulte o arquivo de licença do projeto (se aplicável).

‎docs/architecture.md‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
# Arquitetura
2+
3+
Esta página descreve a arquitetura implementada no código atual do GitDatabase.
4+
5+
## Workspace e crates
6+
7+
O projeto é um workspace Rust com os seguintes crates:
8+
9+
- `gitbase-cli`: interface de linha de comando e orquestração dos fluxos
10+
- `gitbase-db`: conexão com PostgreSQL, migrações e acesso a dados
11+
- `gitbase-git`: leitura de repositórios Git com `gix`
12+
- `gitbase-loader`: pipeline de ingestão/indexação
13+
- `gitbase-uast`: parsing semântico (Go/Rust) via tree-sitter
14+
- `gitbase-pgwire`: servidor compatível com protocolo PostgreSQL
15+
16+
## Comandos da CLI
17+
18+
Comandos disponíveis em `gitbase-cli`:
19+
20+
- `serve`: sobe servidor pgwire
21+
- `sync`: sincroniza metadados Git
22+
- `health`: checa conectividade e migrações
23+
- `hydrate-blobs`: hidrata conteúdo textual dos blobs
24+
- `search-index`: monta/atualiza índice de busca textual
25+
- `uast`: gera cache/projeções de UAST
26+
27+
## Fluxo de dados
28+
29+
```text
30+
Repositórios Git
31+
↓ (gitbase-git)
32+
Metadados (repos/refs/commits/tree/files)
33+
↓ (gitbase-loader + gitbase-db)
34+
PostgreSQL (schema gitbase)
35+
↓
36+
Blobs hidratados + índice de busca + UAST
37+
↓
38+
Consultas SQL / pgwire
39+
```
40+
41+
## Detalhes de implementação relevantes
42+
43+
### 1) Descoberta e leitura Git (`gitbase-git`)
44+
45+
- Usa `gix` para abrir repositórios e caminhar histórico
46+
- Suporta roots com `.git/` e repositórios bare
47+
- Gera snapshots de commit contendo:
48+
- metadados do commit
49+
- entradas de árvore
50+
- arquivos por commit
51+
- Classifica blobs binários por NUL byte e validação UTF-8
52+
53+
### 2) Sincronização (`gitbase-loader::sync_repositories`)
54+
55+
- Faz upsert em:
56+
- `repositories`
57+
- `refs`
58+
- `commits`
59+
- `commit_parents`
60+
- `tree_entries`
61+
- `files`
62+
- Evita retrabalho para commits já persistidos
63+
64+
### 3) Hidratação de blobs (`hydrate_blobs` / `hydrate_missing_blobs`)
65+
66+
- Busca blobs faltantes no banco
67+
- Lê blob no Git de origem
68+
- Regras:
69+
- blob maior que `max_blob_bytes` → marca sem conteúdo
70+
- blob binário → marca sem conteúdo
71+
- blob textual válido → persiste `content`
72+
73+
### 4) Indexação de busca (`index_search`)
74+
75+
- Candidatos vêm de `files` + `blobs`
76+
- Só indexa conteúdo textual UTF-8
77+
- Normaliza NUL (`\0`) para espaço
78+
- Persiste `tsvector` em `code_index`
79+
80+
### 5) Indexação UAST (`index_uast`)
81+
82+
- Suporta linguagens detectadas por extensão:
83+
- `.go`
84+
- `.rs`
85+
- Armazena documento UAST em JSONB (`uast_cache`)
86+
- Projeta funções e imports em tabelas específicas
87+
88+
### 6) Consulta via pgwire (`gitbase-pgwire`)
89+
90+
- Server escuta em `bind` (default `0.0.0.0:5433`)
91+
- Autenticação simples por usuário/senha configuráveis
92+
- Encaminha queries para PostgreSQL real (`sqlx`)
93+
- Em consultas `SELECT`, tenta hidratar blobs referenciados por `blob_hash` antes de executar
94+
95+
## Variáveis de ambiente mais usadas
96+
97+
- `DATABASE_URL`
98+
- `GITBASE_REPO_ROOTS`
99+
- `GITBASE_DB_MAX_CONNECTIONS`
100+
- `GITBASE_BLOB_MAX_BYTES`
101+
- `GITBASE_BLOB_HYDRATE_LIMIT`
102+
- `GITBASE_SEARCH_LIMIT`
103+
- `GITBASE_UAST_LIMIT`
104+
- `GITBASE_BIND_ADDR`
105+
- `GITBASE_PG_USER`
106+
- `GITBASE_PG_PASSWORD`

‎docs/database.md‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
# Banco de dados
2+
3+
Esta página descreve o modelo de dados criado pelas migrations atuais.
4+
5+
## Extensões e schema
6+
7+
- Extensão: `pg_trgm`
8+
- Schema principal: `gitbase`
9+
10+
## Tabelas principais
11+
12+
### Metadados Git
13+
14+
- `gitbase.repositories`
15+
- `gitbase.refs`
16+
- `gitbase.commits`
17+
- `gitbase.commit_parents`
18+
- `gitbase.tree_entries`
19+
- `gitbase.files`
20+
21+
### Cache de blobs
22+
23+
- `gitbase.blobs`
24+
25+
### Busca textual
26+
27+
- `gitbase.code_index`
28+
29+
### UAST
30+
31+
- `gitbase.uast_cache`
32+
- `gitbase.uast_functions`
33+
- `gitbase.uast_imports`
34+
35+
## Índices relevantes
36+
37+
- `files_path_trgm_idx` (GIN trigram em `files.path`)
38+
- `code_index_search_vector_gin` (GIN em `search_vector`)
39+
- `code_index_language_idx`
40+
- índices auxiliares de join por repositório/commit
41+
42+
## Função de busca
43+
44+
A migration cria:
45+
46+
- `gitbase.search_code(pattern TEXT, lang TEXT DEFAULT NULL)`
47+
48+
Retorno:
49+
50+
- `repository_id`
51+
- `commit_hash`
52+
- `path`
53+
- `blob_hash`
54+
- `language`
55+
- `score`
56+
57+
Implementação usa `websearch_to_tsquery('simple', pattern)` e `ts_rank_cd(...)`.
58+
59+
## Views de projeção UAST
60+
61+
- `gitbase.functions`
62+
- `gitbase.imports`
63+
64+
As views fazem join entre projeções UAST e `files` por `blob_hash` para expor contexto de repositório/commit/path.
65+
66+
## Consultas úteis
67+
68+
### 1) Quantidade de repositórios sincronizados
69+
70+
```sql
71+
SELECT COUNT(*) AS repos
72+
FROM gitbase.repositories;
73+
```
74+
75+
### 2) Estado de hidratação de blobs
76+
77+
```sql
78+
SELECT
79+
COUNT(*) FILTER (WHERE content IS NOT NULL) AS hydrated,
80+
COUNT(*) FILTER (WHERE content IS NULL) AS without_content,
81+
COUNT(*) AS total
82+
FROM gitbase.blobs;
83+
```
84+
85+
### 3) Cobertura do índice de busca
86+
87+
```sql
88+
SELECT
89+
COUNT(*) AS indexed_blobs,
90+
COUNT(DISTINCT language) AS languages
91+
FROM gitbase.code_index;
92+
```
93+
94+
### 4) Buscar código
95+
96+
```sql
97+
SELECT repository_id, path, language, score
98+
FROM gitbase.search_code('http client', NULL)
99+
LIMIT 20;
100+
```
101+
102+
### 5) Funções parseadas (UAST)
103+
104+
```sql
105+
SELECT repository_id, path, name, start_line, end_line
106+
FROM gitbase.functions
107+
ORDER BY repository_id, path, start_line
108+
LIMIT 100;
109+
```
110+
111+
## Observações operacionais
112+
113+
- `files` é versionada por commit (mesmo path pode aparecer várias vezes)
114+
- `code_index` indexa por `blob_hash` (um blob pode estar em múltiplos commits)
115+
- UAST depende de blob textual hidratado e linguagem suportada

‎docs/index.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# GitDatabase
2+
3+
Bem-vindo à documentação do **GitDatabase**.
4+
5+
O projeto indexa repositórios Git em PostgreSQL para consultas analíticas, busca de código e exploração via protocolo PostgreSQL (pgwire).
6+
7+
## Visão geral
8+
9+
O fluxo principal do sistema é:
10+
11+
1. Descobrir repositórios Git e sincronizar metadados (`sync`)
12+
2. Hidratar blobs textuais no cache (`hydrate-blobs`)
13+
3. Indexar busca textual (`search-index`)
14+
4. (Opcional) Gerar estrutura semântica UAST (`uast`)
15+
5. Consultar via SQL/pgwire (`serve`)
16+
17+
## Entradas e saídas principais
18+
19+
- **Entrada**: diretórios com repositórios Git (working tree ou bare)
20+
- **Persistência**: schema `gitbase` no PostgreSQL
21+
- **Saída**:
22+
- Tabelas e views SQL para análises
23+
- Função `gitbase.search_code(pattern, lang)` para busca full-text
24+
- Endpoint pgwire para ferramentas compatíveis com Postgres
25+
26+
## Navegação da documentação
27+
28+
- [Arquitetura](./architecture.md): componentes, fluxo e responsabilidades dos crates
29+
- [Banco de dados](./database.md): tabelas, índices, função de busca e views
30+
- [Pilot](./pilot.md): execução ponta a ponta para validação rápida
31+
- [Runbook](./runbook.md): operação diária, manutenção e troubleshooting

0 commit comments

Comments
 (0)