CRAG — Code Review & Analysis Gateway

Gateway de revisão e análise de código que combina heurísticas estáticas, vetores semânticos e LLMs sob demanda.

Destaques

• 🔍 Pipeline estático primeiro: parsing com Tree-sitter, métricas, heurísticas de segurança e normalização de scores.
• 🤖 Orquestração de LLMs: suporte nativo a Ollama (local) e OpenRouter (cloud), com modo automático, prioridade local ou totalmente offline.
• 🧭 Contexto via vetorização: detecção automática de diretórios de regras de negócio, indexação com VectorStore e busca semântica para priorizar arquivos críticos.
• 🧮 Governança de custo: orçamento diário de LLM, seleção baseada em score, agrupamento inteligente por tokens/arquivos e fallback confiável.
• 🧱 Injeção de dependências: providers, persistência, reporters, estratégias de prompt e agragadores plugáveis.
• 🔐 Persistência auditável: artefatos versionados (.analyzer_cache/) com logs estruturados, redaction de segredos e isolamento por projectId.

Instalação

Como biblioteca

npm install @cragjs/core

Como CLI global

npm install -g @cragjs/core

Desenvolvimento local

git clone https://github.com/juliumnix/crag.git
cd crag
npm install
npm run build

Guia Rápido

Análise estática (local-only)

import { randomUUID } from 'crypto';
import {
  Analyzer,
  LocalFileSystemAdapter,
  JsonReporter,
  AnalysisRequest,
} from 'crag';

const analyzer = new Analyzer();
const request: AnalysisRequest = {
  id: randomUUID(),
  inputPaths: ['src'],
  config: {
    localOnly: true,
    outputFormat: 'json',
    includeMetrics: true,
    redactSecrets: true,
  },
};

const result = await analyzer.analyze(request);
console.log(result);

Análise híbrida com Ollama

import { randomUUID } from 'crypto';
import {
  Analyzer,
  OllamaAdapter,
  LocalFileSystemAdapter,
  JsonReporter,
  AnalysisRequest,
} from 'crag';

const llm = new OllamaAdapter();
const persistence = new LocalFileSystemAdapter();
const reporter = new JsonReporter();
const analyzer = new Analyzer(llm, persistence, reporter);

const request: AnalysisRequest = {
  id: randomUUID(),
  inputPaths: ['src'],
  config: {
    localOnly: false,
    outputFormat: 'json',
    includeMetrics: true,
    redactSecrets: true,
    projectId: 'my-repo',
    dailyLLMBudget: 10,
  },
  businessRules: 'Priorizar fluxo de checkout e regras de pagamento.',
  outputLanguage: 'pt',
};

const result = await analyzer.analyze(request);
console.log(result.summary.score);

CLI

Após instalar globalmente:

crag src apps/api \
  --provider ollama \
  --model llama3 \
  --business-rules "Checkout e antifraude" \
  --daily-llm-budget 8 \
  --project-id ecommerce-app

Ou, se instalado localmente:

npm run build
node dist/cli/index.js src --local-only --clear-cache

Principais opções:

• --provider-mode (auto, local-only, local-priority)
• --max-llm-files, --llm-score-threshold
• --daily-llm-budget
• --grouping-* (tokens/arquivos/estratégia)
• --business-rules ou --business-rules-file
• --project-id, --clear-cache, --ignore-cache
• --output-language, --output (salva JSON em arquivo)
• --debug-json (habilita logs JSON estruturados ultraverbose)

Configuração Essencial

AnalysisConfig (src/core/models/AnalysisRequest.ts):

• localOnly: força execução apenas com heurísticas locais.
• provider (opcional), model, providerMode: controle fino dos adapters registrados (OllamaAdapter, OpenRouterAdapter, StubLLMProvider).
• maxLLMFiles, llmScoreThreshold, excludeTestFiles: funil de seleção para o estágio cognitivo.
• dailyLLMBudget: limita chamadas remotas (contabilizadas por grupo).
• llmGrouping: estrategia para agrupar arquivos antes do prompt.
• projectId, ignoreCache, clearCache: isolamento de cache e limpeza pre-run.

AnalysisRequest extras:

• businessRules: texto livre usado para vetorização e priorização de arquivos.
• businessRulesFile: caminho para arquivo (.txt, .md, .yaml, etc.) que contém as regras de negócio.
• outputLanguage: idioma preferido do relatório final (en, pt, es).
• promptMetadata: objeto arbitrário repassado ao builder de prompts.

Componentes

Pipeline

• Analyzer: orquestra parsing, métricas, heurísticas, prompts e normalização.
• PromptBuilder / ResponseParser: convertem arquivos em prompts e mapeiam respostas em Finding.
• Normalizer: consolida scores (finding → chunk → file → summary).

Ferramentas

• TreeSitterTool: quebra arquivos .ts/.tsx/.js/.jsx em chunks com metadata AST.
• ASTAnalyzer: heurísticas estáticas (imports arriscados, debt, smells).
• MetricsCollector: métricas de complexidade (linhas, Halstead, ciclomática).
• FileImportAnalyzer: mapeia dependências para enriquecer prompts.
• PathDetector: usa LLM (ou fallback) para descobrir diretórios com regras de negócio.
• VectorStore: gera vetores simples, persiste e realiza busca semântica por similaridade.

Adapters

• LLM: OllamaAdapter, OpenRouterAdapter, StubLLMProvider.
• Persistência: LocalFileSystemAdapter (artefatos JSON versionados).
• Reporter: JsonReporter (único no MVP, arquitetura pronta para Markdown/HTML/SARIF).

Utilidades

• logger (Pino) com redaction ({REDACTED:TYPE}).
• schema (CURRENT_SCHEMA_VERSION, compatibilidade de artefatos).
• projectId utilitário para isolamento em monorepos.

Artefatos & Cache

• Cache padrão: .analyzer_cache/<projectId>/.
• Artefatos persistidos: chunks.json, prompt.json, response.json, result.json, metrics.json, vectors/vectors.json.
• Logs estruturados registram toda operação de persistência (timestamp, requestId, status).

Estrutura do Projeto

src/
├── adapters/
│   ├── llm/                # Ollama, OpenRouter, Stub
│   ├── persistence/        # LocalFileSystemAdapter
│   └── reporters/          # JsonReporter
├── cli/                    # Entrada de linha de comando
├── core/
│   ├── interfaces/         # Contratos principais
│   ├── models/             # DTOs e configs
│   ├── pipeline/           # Analyzer, PromptBuilder, Normalizer, ResponseParser
│   └── errors.ts
├── tools/
│   ├── ASTAnalyzer.ts
│   ├── FileImportAnalyzer.ts
│   ├── MetricsCollector.ts
│   ├── PathDetector.ts
│   ├── TreeSitterTool.ts
│   └── VectorStore.ts
├── utils/                  # logger, redaction, schema, language, projectId
└── index.ts                # Barrel exports

tests/
├── contract/               # Testes de contrato
├── integration/            # Pipeline e modo local
└── unit/                   # Cobertura unitária de adapters/tools/utils

Desenvolvimento

• npm run build — compila para dist/.
• npm test — executa Jest.
• npm run lint — regras ESLint.
• npm run format — Prettier.
• Exemplos: examples/*.ts (usar ts-node ou compilar antes).

Próximos Passos

• Expandir reporters (Markdown, HTML, SARIF).
• Incremental analysis (detecção de arquivos inalterados).
• Integração com provedores adicionais (Azure, Vertex, Bedrock).

Licença

MIT