Download the PHP package saviogodinho2002/driftguard without Composer

DriftGuard

Mantém um catálogo PHP curado dos seus models Eloquent sincronizado com o código real, usando um LLM (configurável) num fluxo analyze → revisar → apply. Detecção de mudança via git diff, extração estrutural sempre via reflection real (nunca por prosa da IA), e um passo de revisão humana antes de qualquer escrita.

Por quê

Documentar model manualmente desatualiza. Deixar uma IA reescrever tudo sem revisão arrisca perder curadoria manual. DriftGuard concilia os dois: fatos estruturais (tabela, campos, relações) sempre vêm de reflection — nunca da IA; conhecimento de negócio (descrição, notas, e qualquer campo extra que você definir) é proposto pela IA mas nunca aplicado sem você revisar o diff antes.

Instalação

Configure OPENROUTER_API_KEY no seu .env (o cliente padrão usa OpenRouter + um model Claude — troque em config/driftguard.php ou faça bind de outra implementação de Contracts\AnalysisClient no seu próprio ServiceProvider se quiser outro provedor).

Uso

proposal.php acumula entre chamadas de analyze — se você rodar analyze duas vezes pra models diferentes sem apply no meio, as 2 propostas convivem no mesmo arquivo (model repetido nas 2 rodadas: a mais recente vence). driftguard:apply sempre esvazia proposal.php inteiro depois de aplicar — é o único jeito de limpar uma proposta já resolvida.

driftguard:doctor também avisa (nível WARN, nunca falha o exit code) quando uma entrada de config/models.php não corresponde a nenhum model encontrado em models_path — sinal de que o model foi renomeado, movido ou apagado desde a última análise. O pacote nunca remove essa entrada sozinho (o catálogo é curado à mão, igual qualquer outro campo — ver "Segurança" abaixo); reveja manualmente e decida: se foi rename/move, ajuste models_path/o nome da classe e rode analyze de novo; se o model saiu de vez, apague a entrada à mão em config/models.php.

Se você já analisou tudo por fora (ou só quer marcar "a partir de agora, reanalise o que mudar") sem pagar o custo de rodar --force contra todos os models de novo:

Perguntas pendentes (ask_question) — responda sem editar questions.md à mão:

Introspecção (sem chamar o LLM):

Uso por um agente de IA (CLI headless)

Todo command aceita --json (saída estruturada em vez de tabela/cores):

driftguard:apply --json sem --force nunca aplica — devolve {status: "confirmation_required", diff} e sai com código de erro, pra uma execução headless nunca gravar mudança por engano só por ter esquecido --dry-run.

usage (em analyze --json) é {cost_usd, prompt_tokens, completion_tokens}, somado ao longo de TODAS as chamadas ao LLM da rodada (pode haver mais de 1 por model, quando há request_file/ request_method/correção de scope_class no meio). Cada campo é best-effort: fica null quando o provedor/preset não expõe esse dado — nunca inventado/estimado (ex: cli_harness com preset gemini, que não tem custo em dólar em NENHUM lugar do schema da CLI, confirmado no código-fonte; ver detalhes por preset na seção do cli_harness abaixo). Se TODO campo vier null, é porque nenhuma chamada da rodada reportou nada, não porque o custo foi zero.

Customizando pro seu domínio

Tudo em config/driftguard.php, publicado no seu próprio projeto — edite livremente:

• fields — campos extras do seu domínio (além da base descricao/notas/tabela/campos/relacoes que o pacote já cobre). Tipos: string, enum, array, ou scope_class (gera um arquivo .php de classe de escopo de tenant de verdade, implementando Contracts\TenantScope — nunca guarda código como string pra eval() depois). Duas formas de autoria, misturáveis na mesma lista:

  Rode php artisan driftguard:doctor depois de editar — valida cada FieldSpec (e os demais paths da config) sem chamar o LLM, apontando exatamente qual entrada está malformada.

• context_docs — aponte arquivos .md com regra de negócio que não dá pra inferir só lendo o código (motivo histórico, decisão de produto). Entra como contexto extra pra IA, nunca substitui o que reflection já determina. Se o conteúdo do doc parecer contradizer o que a IA observa no código, ela é instruída a usar ask_question em vez de escolher um lado sozinha (mesma regra vale pra resposta humana anterior via driftguard:answer). Veja o que está resolvido com driftguard:context:list.
• extra_prompt_rules — meta-instrução de formato/convenção específica do seu app (não é conhecimento de negócio por model — isso é context_docs). O prompt base do pacote já instrui a IA (regra 6 do system prompt) a preferir ask_question quando o PRÓPRIO código diverge de si mesmo entre múltiplos arquivos (ex: 2-3 pontos de entrada filtrando/validando de formas diferentes) — não é algo que você precisa lembrar de configurar. extra_prompt_rules continua útil pra reforçar isso com um exemplo concreto do SEU domínio (veja o padrão completo na seção de scope_class abaixo), mas não é o único mecanismo.
• max_snippet_chars — teto de tamanho pra um arquivo (apoio OU o próprio model) acima do qual o pacote tenta extrair só a parte relevante antes de mandar tudo. Pro arquivo de apoio, extrai só os métodos que mencionam o model. Pro arquivo do PRÓPRIO model, tenta extração SEGURA primeiro (mantém todo método público — nunca corta regra de negócio real, só remove overrides do Eloquent puramente boilerplate). Em qualquer um dos dois, se ainda estourar depois de tentar extrair, cai pro conteúdo truncado com aviso — nunca estoura sem avisar.
• max_total_snippet_chars (default 60000) — orçamento combinado somando TODOS os snippets de 1 model (arquivo do model + apoio); se estourar, descarta arquivo de apoio (nunca o do model) começando pelos de menor conteúdo extraído.
• max_supporting_files (default 5) — teto de quantos arquivos de apoio são coletados por model, antes mesmo de montar o contexto.
• --full (flag do driftguard:analyze, não é config) — ignora os 3 limites acima só na rodada atual, mandando tudo inteiro. Não muda quais models entram (isso é --force/--model/diff normal), só quanto conteúdo de cada um. Útil pra uma auditoria pontual ou a 1ª análise cuidadosa de um model crítico, sem precisar mexer na config publicada só por causa dessa rodada.
• request_method — quando um snippet do próprio model (ou de um arquivo de apoio) vem com aviso de "método(s) descartado(s) por orçamento", a IA pode pedir de volta só os métodos específicos que faltaram (os nomes exatos aparecem no aviso) em vez do arquivo inteiro — inclusive vários de uma vez, numa única chamada. Complementa request_file (que pede o arquivo inteiro): use request_method quando só falta método específico, request_file quando falta o arquivo todo (ex: um arquivo que nem chegou a entrar no contexto).
• allowed_base_path — diretório fora do qual a IA não pode ler arquivo via request_file durante a análise (default: raiz do projeto).
• storage_path — default base_path('driftguard') (raiz do projeto), de propósito fora de storage/ — context.json guarda last_commit_hash e perguntas pendentes/respondidas; se ficar de fora do git (storage/ é ignorado por padrão no Laravel), cada dev/agente vê um estado local diferente, sem saber o que outro já analisou ou respondeu. Se realmente quiser esse arquivo fora do git, aponte pra storage_path('app/driftguard') e adicione ao seu .gitignore você mesmo.
• models_path/supporting_paths/model_namespace/output_path — todos os caminhos usados são configuráveis, nada fixo em app/Models.

Provedor alternativo: harness de CLI

Além de OpenRouter (padrão) e bind da sua própria Contracts\AnalysisClient (sempre suportado, veja o comentário em DriftGuardServiceProvider), o pacote traz um 3º caminho: invocar um agente-CLI (Claude Code, Gemini CLI, opencode) como subprocesso, em vez de uma API stateless. A diferença real é que o harness explora o código sozinho (Read/Grep próprios, restritos ao seu projeto) em vez de receber um snippet pré-empacotado pelo orçamento de contexto do driftguard.

O preset claude usa o Claude Code CLI: a saída é um JSON limpo, exatamente no formato pedido, com regras de negócio numeradas e cross-referências que o harness descobre sozinho via Grep (sem precisar que você cite o arquivo relacionado no prompt). gemini/opencode também são suportados (nível de confiança de cada shape explicado nos trade-offs abaixo); se a sua versão usar um shape diferente, sobrescreva qualquer chave em llm.cli_harness (mesmo padrão de override do resto do pacote):

Override com null explícito é respeitado — se você precisar zerar uma flag que um preset já define (ex: forçar 'dir_flag' => null no preset claude porque sua versão da CLI mudou o nome da flag), null de propósito NUNCA é silenciosamente trocado pelo default do preset. Isso vale tanto pra chave que você sobrescreve quanto pras que os próprios presets gemini/opencode já deixam null (sem flag de restrição de diretório equivalente nessas CLIs) — o driftguard nunca injeta uma flag específica de outra CLI (como --add-dir/--allowedTools, do Claude Code CLI) só porque o preset não definiu uma equivalente.

Custo/tokens por chamada aparecem no analyze --json (chave usage, ver seção --json acima), extraídos de cada preset via cost_field/prompt_tokens_field/completion_tokens_field — o quanto cada CLI realmente expõe e como é lido está detalhado no último item de "Trade-offs" logo abaixo. Custo também continua sendo logado via Log::info('[driftguard] CliHarnessAnalysisClient: custo da chamada', [...]) a cada chamada, útil pra acompanhar em tempo real (storage/logs/laravel.log por padrão) sem esperar a rodada terminar.

Trade-offs a considerar:

• Custo/tempo por chamada pode ser maior que 1 POST HTTP no OpenRouter. O harness gasta turnos explorando o código (Read/Grep) antes de responder, em vez de receber tudo já pronto — isso soma tempo e, se o provedor cobrar por uso, custo por cima do que uma chamada HTTP simples custaria. Em troca, a saída tende a ser mais rica que o que extractSafeParts()/packWithinBudget() conseguem com um orçamento fixo de contexto, já que o harness explora o que precisar, sem teto pré-definido.
• O custo "equivalente de API" só é custo real se o provedor cobrar por uso. Numa assinatura de valor fixo com folga de uso, o custo marginal de rodar isso pode ser ~US$0 — a resposta de "vale a pena" depende do seu plano, não de um número fixo.
• O CLI precisa estar AUTENTICADO no ambiente que roda driftguard:analyze (login prévio ou API key do provedor da CLI) — diferente de só ter uma env var configurada; pode não servir bem pra CI/headless sem uma sessão interativa já estabelecida.
• Rastreio de custo/tokens depende do CLI, e o shape difere bastante entre elas. Claude Code CLI expõe total_cost_usd (plano) e tokens aninhados em usage.* no --output-format json — o único preset validado com uma chamada real de ponta a ponta. Atenção: ela reparte o volume de entrada entre usage.input_tokens (tokens "frescos") e usage.cache_creation_input_tokens/ usage.cache_read_input_tokens, e numa sessão de harness multi-turno quase todo o volume cai nos de cache — por isso o preset soma os 3 (ler só o primeiro reportava 33 tokens de prompt numa rodada real de 7 models). Gemini CLI expõe tokens por model (stats.models.<nome>.tokens.{prompt,candidates}, somados entre models via *) mas não tem custo em dólar em lugar nenhum do schema (cost_field => null é definitivo, não "ainda não" — confirmado lendo o código-fonte da CLI). opencode expõe custo/tokens num evento step_finish (part.cost, part.tokens.{input,output}) DIFERENTE do evento que carrega o texto final (text, part.text) — pode haver mais de 1 step_finish numa resposta só (loop de tool-call interno do harness), somados entre si. Cada *_field aceita um caminho dot-path (ex: 'usage.input_tokens'), com * como segmento curinga pra somar através de uma chave dinâmica (o caso do Gemini, tokens por model); prompt_tokens_field/completion_tokens_field aceitam também uma lista de caminhos, somados entre si (o caso do Claude, volume repartido entre campo fresco e campos de cache). Os shapes de gemini/opencode vêm do código-fonte de cada CLI, não de uma chamada autenticada de ponta a ponta neste pacote — ajuste os *_field em cli_harness se a versão instalada divergir.

Segurança durante a exploração: 3 camadas independentes

O harness explora o código sozinho, então "o que garante que ele não vai escrever/executar algo indevido?" tem uma resposta em camadas — nenhuma sozinha é o bastante:

1. readonly_lock (default true) — trava allowed_base_path contra escrita no sistema de arquivos ANTES de rodar o subprocesso, e restaura o modo original de cada arquivo depois (mesmo se a chamada falhar ou estourar timeout). É a defesa PRINCIPAL: funciona igual pros 3 presets, independente de a CLI alvo ter allowlist de tool própria. storage/, bootstrap/cache/, vendor/, node_modules/ e .git/ nunca são travados, mesmo dentro de allowed_base_path (travar storage/ quebraria log/cache/sessão de requests concorrentes rodando ao mesmo tempo). Não funciona no Windows — chmod() lá não impõe restrição real de diretório (só um atributo cosmético) — nesse caso é desabilitado automaticamente, sem precisar desligar na mão; driftguard:doctor avisa quando isso acontece.
2. --allowedTools/--add-dir — allowlist de tool da própria CLI alvo, quando ela suporta (hoje só o preset claude tem tools_flag confirmado; gemini/opencode não têm equivalente documentado — driftguard:doctor avisa disso também).
3. Denylist de código — Bash/Write/Edit/NotebookEdit nunca entram na allowlist passada pra CLI, mesmo que você configure harness_tools incluindo alguma delas por engano.

Isso é só a segurança durante a exploração. Depois que o harness responde, a saída passa pelo MESMO portão de revisão que qualquer outro provedor: nunca escreve config/models.php direto (só proposal.php → driftguard:apply --dry-run → confirmação), e um campo scope_class proposto passa pelas mesmas 3 guardas de sempre (ScopeClassWriter::sanitize() → checagem semântica → php -l) antes de virar arquivo .php — o harness nunca escreve arquivo, só propõe uma string.

Por que não chamar a CLI direto, sem passar pelo driftguard? Porque o que o driftguard garante não é "chamar a IA com segurança" (isso as 3 camadas acima resolvem) — é tudo em volta disso, que se perde num claude -p "documenta meus models" avulso: fatos estruturais (tabela/campos/relações) sempre por reflection real, nunca pela IA (mesmo que o harness erre um nome de coluna, reflection sempre vence no merge final); detecção incremental via git diff, só reanalisa o que mudou; e o portão de revisão humana + as guardas de scope_class do parágrafo anterior.

Multi-tenancy: escrevendo uma boa instrução pra scope_class

scope_class é o field mais delicado de instruir bem, porque a resposta certa depende de onde a regra de tenant realmente mora no seu app — e isso varia. Dois princípios ajudam a escrever a instrução:

1. O que já está garantido no contexto, sem precisar pedir. O arquivo do próprio model entra inteiro sempre que cabe no orçamento (max_snippet_chars); acima disso, a extração segura sempre preserva booted()/addGlobalScope, scopes locais (scopeXxx()) e métodos de relação (são públicos — a extração segura nunca corta método público) — então "olhe global scopes, scopes locais, e relações que já implicam tenant (belongsTo(Empresa::class))" a IA já tem material pra fazer sozinha de qualquer forma. Não precisa instruir isso, é estrutural.

2. O que não está garantido — e onde configurar, não instruir. Arquivos de apoio só entram se estiverem em supporting_paths e referenciarem o model (ModelDiscovery::supportingFilesForModel()). Se a lógica de tenant mora num middleware (comum em apps multi-tenant — resolve o tenant antes de qualquer controller/model ser tocado), esse arquivo só entra no contexto se você adicionar o diretório de middlewares em supporting_paths. Isso é "onde procurar" — resolve-se na config, não pedindo pra IA adivinhar ou usar request_file às cegas.

Cuidado com "olhe o controller e replique". Controller filtrando manualmente (->where('empresa_id', $user->empresa_id) espalhado em várias actions) é exatamente o anti-padrão que scope_class existe pra resolver — centralizar a regra numa classe só. Se a instrução mandar "replique o que o controller faz" e existirem 2-3 pontos de entrada (ex: API + painel admin + import em lote) filtrando de formas ligeiramente diferentes — cenário comum em apps multi-tenant que cresceram organicamente, não hipotético —, esse é exatamente o padrão que a regra 6 do prompt base já cobre (preferir ask_question a escolher uma versão em silêncio). A instrução abaixo reforça isso com um exemplo concreto do domínio de tenant — não é o único mecanismo, mas ajuda a IA a citar exatamente esses pontos de entrada divergentes, em vez de uma menção genérica.

Instrução recomendada como ponto de partida (adapte Empresa/empresa_id pro seu domínio):

Perguntas pendentes e o modo rerun

Quando a IA usa ask_question em vez de propor uma atualização, o model fica pendente até alguém responder — php artisan driftguard:answer {model} {resposta} (sem precisar editar questions.md). A próxima driftguard:analyze (sem --force/--model) detecta automaticamente qualquer model com pergunta respondida e o inclui na rodada — a resposta anterior entra no prompt como contexto humano autoritativo, ao lado de context_docs.

Segurança

• Nada é escrito sem um passo de --dry-run/confirmação (driftguard:apply).
• Campo do tipo scope_class roda checagem sintática (php -l) antes de gravar qualquer classe — nunca deixa um arquivo PHP quebrado no disco.
• Se um arquivo de classe gerado foi editado à mão desde a última geração, a próxima rodada detecta (hash) e não sobrescreve silenciosamente — avisa e pula.
• Campo que existe no catálogo mas saiu da sua spec atual (fields) é preservado verbatim na reescrita — nunca apagado silenciosamente.
• request_file/request_method (a IA pedindo outro arquivo/método de código durante a análise) são restritos a allowed_base_path — um path fora da raiz do projeto é recusado explicitamente, nunca lido.

Testando

Testes rodam via Orchestra Testbench, contra models de fixture de um domínio genérico (blog) — sem depender de nenhuma app Laravel real.

Licença

MIT.