VS Code Extension - Busca Semântica Integrada

# Clone do repositório GitHub
git clone https://github.com/kaffyn/vectora-vscode.git
cd vectora-vscode

# Instale dependências
npm install

# Link simbólico para ~/.vscode/extensions (opcional)
ln -s $(pwd) ~/.vscode/extensions/vectora-vscode

# Na paleta de comandos (Cmd/Ctrl+Shift+P), digite:
> Vectora: Show Metrics

# Se funcionar: extension está ativa e conectada

# No terminal do seu projeto
cd ~/seu-projeto

# Inicialize Vectora
vectora init --name "Meu Projeto" --type codebase

# Resultado: arquivo .vectora/config.json criado

# Abra o projeto em VS Code
code ~/seu-projeto

# A extension detecta .vectora/config.json automaticamente
# E começa a indexar (pode levar alguns minutos)

# Na raiz do projeto, crie .env
cat > .env << 'EOF'
GEMINI_API_KEY=sk-proj-xxxxx
VOYAGE_API_KEY=sv_xxxxx
VECTORA_NAMESPACE=seu-namespace
VECTORA_EMBEDDING_MODEL=voyage-code-3
EOF

# A extension lê automaticamente
# Dica: adicione .env ao .gitignore!
echo ".env" >> .gitignore

# Terminal (macOS/Linux)
export GEMINI_API_KEY="sk-proj-xxxxx"
export VOYAGE_API_KEY="sv_xxxxx"

# PowerShell (Windows)
$env:GEMINI_API_KEY = "sk-proj-xxxxx"
$env:VOYAGE_API_KEY = "sv_xxxxx"

# Depois abra VS Code naquele terminal
code ~/seu-projeto

# No VS Code, abra a paleta de comandos:
Cmd/Ctrl + Shift + P

# Digite: Vectora: Show Metrics

# Esperado: aparecer painel com:
# Connection: Connected
# Index size: X chunks
# Last update: agora mesmo

┌──────────────────────────────────┐
│ Vectora │
├──────────────────────────────────┤
│ Indexed Files │
│ ├─ src/ (2,847 chunks) │
│ │ ├─ auth/ (145 chunks) │
│ │ ├─ handlers/ (312 chunks) │
│ │ └─ utils/ (89 chunks) │
│ ├─ docs/ (312 chunks) │
│ └─ tests/ (156 chunks) │
│ │
│ Search │
│ ┌──────────────────────────────┐ │
│ │ [Search query...] │ │ ← Live search
│ └──────────────────────────────┘ │
│ Strategy: ◉ Semantic ○ Structural│
│ Top K: [5] ▲▼ │
│ │
│ Stats │
│ ├─ Precision: 0.86 │
│ ├─ Latency: 145ms │
│ ├─ Indexed: 3,315 chunks │
│ ├─ Last updated: 2 min ago │
│ └─ Status: Healthy │
│ │
│ Settings │
│ └─ Configure... │
└──────────────────────────────────┘

Vectora: Search Context
├─ Abre painel de busca interativo
├─ Digita pergunta natural
└─ Mostra resultados em tempo real

Vectora: Analyze Dependencies
├─ Posicione cursor em símbolo
├─ Mostra quem chama + quem é chamado
└─ Análise de impacto automática

Vectora: Find Tests
├─ Busca testes relacionados à query
├─ Filtra por nome, descrição, tipo
└─ Jump-to-test com um clique

Vectora: Find Similar Code
├─ Encontra código similar ao selecionado
├─ Compara patterns
└─ Sugere refatoração

Vectora: Index Status
├─ Mostra progresso de indexação
├─ Tempo estimado restante
└─ Erros de indexação (se houver)

Vectora: Show Metrics
├─ Painel com estatísticas completas
├─ Gráficos de performance
└─ Taxa de cache hit

Vectora: Configure
├─ Abre settings da extension
├─ API keys, namespace, estratégia
└─ Salva em settings.json

// Hover aqui
function getUserById(id: string) {
  // Info aparece:
  //
  // getUserById(id): Promise<User>
  //
  // Definido em: src/services/user.ts:45
  //
  // Similar:
  // • getUser (85% match)
  // • fetchUser (72% match)
  // • getActiveUser (68% match)
  //
  // Usado em 24 arquivos
}

[Referências (24)] [Definição] [Teste] [Semelhantes] [Ir para Implementação]

function validateToken(token: string) {
  // ...
}

Vectora: Connected | 3,315 chunks | Precision: 0.86 | Last: 2m ago

1. Pressione Cmd/Ctrl + Shift + P (Command Palette)
   → Mostra: caixa de entrada vazia com ">" no topo

2. Digite: "Vectora: Search Context"
   → Autocomplete mostra opção Vectora

3. Pressione Enter
   → Abre painel de busca (direita da sidebar)

4. Digite: "Como faz validação de tokens?"
   → Em tempo real: mostra resultados conforme digita

5. Resultados aparecem em 120-250ms
   ┌─────────────────────────────────┐
   │ Vectora Results (8 chunks) │
   ├─────────────────────────────────┤
   │ src/auth/jwt.ts:45 │ ← Clique para ir
   │ validateToken() { ... │
   │ precision: 0.92 | latency 240ms│
   │ │
   │ src/auth/guards.ts:12 │
   │ VerifyJWT middleware { ... │
   │ precision: 0.88 | latency 240ms│
   │ │
   │ src/auth/types.ts:3 │
   │ interface JWTPayload { ... │
   │ precision: 0.76 │
   │ │
   │ [Mostrar mais] │
   └─────────────────────────────────┘

1. Posicione cursor em: getUserById
2. Pressione Cmd/Ctrl + Shift + H (Find References)
3. VS Code mostra painel "Find All References":

   ┌─────────────────────────────────┐
   │ 62 References to getUserById │
   ├─────────────────────────────────┤
   │ DIRECT CALLS (47) │
   │ • src/routes/user.ts:23 │
   │ • src/middleware/auth.ts:34 │
   │ • src/services/profile.ts:12 │
   │ │
   │ INDIRECT via getUserData (12) │
   │ • src/handlers/index.ts:5 │
   │ • src/cache/service.ts:99 │
   │ │
   │ TESTS (3) │
   │ • src/__tests__/user.test.ts:45 │
   │ │
   │ [Expandir com Vectora] ← Novo │
   └─────────────────────────────────┘

Referências semelhantes não encontradas por AST:
• getUserByEmail() [85% similar]
• fetchUser() [72% similar]
• getActiveUser() [68% similar]

1. Abra arquivo modificado: auth/jwt.ts
2. Cmd/Ctrl + Alt + F (Find Changes in Context)
3. Painel mostra:

   ┌────────────────────────────────────┐
   │ Vectora: Changes & Impact │
   ├────────────────────────────────────┤
   │ LINHAS MODIFICADAS │
   │ L45: function validateToken │
   │ L52: if (!token.verified) │
   │ │
   │ ARQUIVOS QUE USAM ESSAS FUNÇÕES │
   │ • src/guards/auth.guard.ts (5) │
   │ • src/routes/api.ts (3) │
   │ • src/middleware/verify.ts (8) │
   │ │
   │ TESTES RELACIONADOS │
   │ • auth.guard.test.ts │
   │ • jwt.validation.test.ts │
   │ │
   │ ALERT: 16 dependências │
   │ Recomenda rodar testes completos │
   └────────────────────────────────────┘

{
  // === BÁSICO ===
  "vectora.enabled": true,
  "vectora.namespace": "seu-namespace",

  // === INDEXAÇÃO ===
  "vectora.autoIndex": true,
  "vectora.indexOnSave": true,
  "vectora.indexOnStartup": true,
  "vectora.trustFolder": "./src", // Pasta principal do código

  // === BUSCA & PERFORMANCE ===
  "vectora.searchStrategy": "semantic", // ou "structural"
  "vectora.maxResults": 10,
  "vectora.searchTimeout": 2000, // ms
  "vectora.maxTokens": 4096, // Máximo de tokens para contexto

  // === UI ===
  "vectora.showMetrics": true,
  "vectora.sidebarPosition": "right", // ou "left"
  "vectora.showCodeLens": true,
  "vectora.showStatusBar": true,

  // === PRIVACIDADE & DEBUG ===
  "vectora.debugMode": false,
  "vectora.sendTelemetry": true,
  "vectora.useLocalEmbeddings": false // Para máxima privacidade
}

{
  "project": {
    "name": "Meu Projeto",
    "type": "codebase",
    "version": "0.1.0"
  },

  "indexing": {
    "include_patterns": ["**/*.ts", "**/*.tsx", "**/*.js"],
    "exclude_patterns": ["node_modules/**", "dist/**", ".git/**", "*.test.ts"],
    "incremental": true,
    "watch_mode": true
  },

  "embedding": {
    "model": "voyage-code-3",
    "provider": "voyage-ai",
    "batch_size": 100
  },

  "database": {
    "type": "sqlite",
    "path": ".vectora/index.db"
  }
}

# API Keys (NÃO commit)
GEMINI_API_KEY=sk-proj-xxxxx
VOYAGE_API_KEY=sv_xxxxx

# Servidor remoto (se não local)
VECTORA_SERVER_URL=https://seu-servidor.com

# Debug (apenas desenvolvimento)
VECTORA_LOG_LEVEL=debug
VECTORA_LOG_FILE=.vectora/debug.log

{
  "key": "ctrl+shift+v",
  "command": "vectora.toggleSidebar"
},
{
  "key": "ctrl+shift+f",
  "command": "vectora.search"
},
{
  "key": "ctrl+alt+d",
  "command": "vectora.analyzeDependencies"
},
{
  "key": "ctrl+alt+t",
  "command": "vectora.findTests"
}

{
  "indexing": {
    "exclude_patterns": ["node_modules/**", "dist/**", ".git/**", "build/**", "*.test.ts", "**/*.min.js", "coverage/**"]
  }
}

{
  // Rápido: AST structural matching (~50ms)
  "vectora.searchStrategy": "structural",

  // Preciso: Semantic vector search (~300ms)
  "vectora.searchStrategy": "semantic",

  // Híbrido: Estrutural + semântico (~400ms)
  "vectora.searchStrategy": "hybrid"
}

Cmd/Ctrl + Shift + X → Procure "Vectora" → Clique em "Enable"

# No terminal integrado
which vectora
# Se não encontra:
npm install -g @kaffyn/vectora

# Ou adicionar ao PATH em settings.json
"vectora.commandPath": "/usr/local/bin/vectora"

{
  "vectora.trustFolder": "./src",
  "vectora.searchStrategy": "structural"
}

{
  "vectora.autoIndex": false,
  "vectora.indexOnSave": false
}

# Verificar saúde da extension
Cmd/Ctrl+Shift+P → Vectora: Show Metrics

# Esperado:
# Memory: <150MB
# Index size: 10,000 chunks
# Average latency: <200ms
# Cache hit rate: >70%

# Full reindex (lento, ~5-10min para projetos grandes)
Cmd/Ctrl+Shift+P → Vectora: Reindex Full

# Incremental (rápido, ~1-2 min)
# Acontece automaticamente ao salvar

{
  // Apenas TypeScript
  "vectora.includePatterns": ["**/*.ts", "**/*.tsx"],
  "vectora.excludePatterns": ["**/*.test.ts", "**/*.spec.ts"]
}

{
  "vectora.embeddingProvider": "local",
  "vectora.embeddingModel": "all-MiniLM-L6-v2",
  "vectora.useLocalEmbeddings": true
}

Primeira busca: "Como validar?" → 350ms
Segunda busca idêntica: 45ms (cache hit)
= 8x mais rápido!

# Monitor contínuo (developer tools)
Cmd/Ctrl+Shift+P → Developer: Toggle Developer Tools
# Vá para Performance tab

# Esperado:
# Memory: <150MB
# Heap: <100MB
# CPU: <5% idle

# 1. Abra settings.json
Cmd/Ctrl+, → search "vectora.debugMode"

# 2. Ative debug
"vectora.debugMode": true,
"vectora.logLevel": "debug"

# 3. Veja logs
Cmd/Ctrl+Shift+P → Vectora: Show Logs

# 4. Busque por pattern (erro, warning, info)
# Analise timestamps e correlacione com ações

# 1. Disable no VS Code
Cmd/Ctrl+Shift+X → Find "Vectora"
→ Click "Disable"

# 2. Reload window
Cmd/Ctrl+Shift+P → Developer: Reload Window

# 3. Re-enable quando pronto
→ Click "Enable"

# 1. Deletar índice local
rm -rf .vectora/index.db

# 2. Deletar cache
rm -rf .vectora/cache

# 3. Full reindex
Cmd/Ctrl+Shift+P → Vectora: Reindex Full

# 4. Aguarde conclusão (pode levar tempo)