alessandrocampos224/laravel-feature-docs

Package Laravel para gerar documentação técnica e funcional a partir de mudanças reais do código via git diff.

O que o package entrega

• Comando Artisan docs:update-from-diff
• Pipeline desacoplado por contratos (diff, classificação, contexto, IA, geração, escrita)
• Dois documentos Markdown por feature:
• docs/technical/<feature-slug>.md
• docs/client/<feature-slug>.md
• Metadata rastreável em JSON:
• docs/.meta/<feature-slug>.json
• Atualização seletiva de docs existentes com prompt dedicado
• Config publicável e implementações sobrescrevíveis via container

Instalação

composer require alessandrocampos224/laravel-feature-docs

Publique config e prompts:

php artisan vendor:publish --tag=feature-docs-config
php artisan vendor:publish --tag=feature-docs-prompts

Configuração

Arquivo config/feature-docs.php contém os grupos:

• git
• paths
• features
• ai
• generation

Provider de IA default no v1: openai (obrigatório configurar chave).

Variáveis principais:

• FEATURE_DOCS_AI_PROVIDER=openai
• FEATURE_DOCS_AI_MODEL=gpt-5
• FEATURE_DOCS_OPENAI_API_KEY=...
• FEATURE_DOCS_OPENAI_BASE_URL=https://api.openai.com/v1

Comando principal

php artisan docs:update-from-diff
php artisan docs:update-from-diff --base=origin/main --head=HEAD
php artisan docs:update-from-diff --stage=staged
php artisan docs:update-from-diff --files="app/Services/ProductService.php,routes/web.php"
php artisan docs:update-from-diff --feature=produtos/preco-promocional
php artisan docs:update-from-diff --only=technical
php artisan docs:update-from-diff --format=json
php artisan docs:update-from-diff --dry-run

Assinatura:

protected $signature = 'docs:update-from-diff
    {--base= : Git base reference}
    {--head=HEAD : Git head reference}
    {--stage= : unstaged|staged|all}
    {--feature= : Force feature slug}
    {--files= : Comma separated list of files}
    {--only= : technical|client|all}
    {--format=markdown : markdown|json}
    {--dry-run : Preview without writing files}';

Pipeline implementado

1. Descobre escopo de comparação
2. Lê diff do Git
3. Converte alterações em DTOs
4. Classifica impacto por heurística
5. Resolve feature_slug
6. Monta contexto consolidado
7. Carrega prompts versionados do disco
8. Gera docs técnica e cliente via IA
9. Atualiza docs existentes quando houver
10. Salva Markdown e metadata JSON
11. Retorna resumo no console (markdown ou json)

Contratos públicos

• DiffReader
• ChangeClassifier
• FeatureResolver
• ContextBuilder
• PromptRepository
• AiClient
• DocGenerator
• DocWriter

Todos podem ser sobrescritos com bind no container do Laravel.

Estrutura de prompts

PromptRepository suporta nomes canônicos e fallback para variantes com acento.

Arquivos esperados:

• prompt-base.md
• prompt-de-classificacao-de-mudanca.md (fallback para prompt-de-classificação-de-mudança.md)
• prompt-de-doc-tecnica.md
• prompt-de-doc-cliente.md
• prompt-de-atualizacao-de-doc-existente.md (fallback para prompt-de-atualização-de-doc-existente.md)

Testes

Stack:

• Pest
• Orchestra Testbench

Rodar:

composer test

Cobertura base:

• leitura de diff
• classificação heurística
• resolução de feature
• carregamento de prompts
• geração de paths e escrita
• dry-run
• criação de docs novas
• atualização de docs existentes

Compatibilidade

• Laravel 10, 11, 12 e 13
• PHP 8.2+

Extensão futura

O núcleo não depende de Filament. Um plugin Filament pode ser criado depois para exibição e busca visual das docs geradas.