documentcodeai

Gere documentação técnica profissional do seu projeto automaticamente com IA local (Ollama), pronta para GitHub Pages.

documentcodeai transforma seu código em:

• site de documentação navegável por módulos
• overview técnico do projeto
• diagrama de arquitetura Mermaid
• páginas de responsabilidades/dependências por pasta
• SDD em Markdown (opcional)

Ideal para onboarding, handoff entre times, auditoria técnica e redução de documentação manual.

Por que usar

• Economiza horas de documentação repetitiva.
• Baseado no código real do repositório (não em template genérico).
• Funciona com IA local via Ollama (sem depender de API externa).
• Suporta geração incremental com Git (mais rápido no dia a dia).
• Permite personalizar tom/estilo com prompt (--spec).

O que você recebe

Saída padrão em docs/:

docs/
  index.html                 # overview + stack + diagrama
  src/
    index.html               # documentação do módulo src
    api/
      index.html             # documentação do submódulo api
  sdd.md                     # opcional (com --generate-md)
  .sdd-meta.json             # metadados para incremental

Quick Start (1 minuto)

1. Instale o pacote:

npm install -g documentcodeai

2. Gere documentação do projeto atual:

documentai generate . --language pt-BR

3. Abra docs/index.html.

Instalação

Global (CLI)

npm install -g documentcodeai

Comando disponível:

documentai --help

Como dependência (SDK)

npm install documentcodeai

Requisitos

• Node.js 18+
• Ollama instalado (o SDK tenta iniciar o serviço automaticamente quando usa endpoint local)
• Pelo menos 1 modelo disponível localmente (ou download durante execução interativa)

Exemplo de modelo:

ollama pull llama3.2

Uso da CLI

Comando principal:

documentai generate <path-do-projeto> [opcoes]

Alias (comando padrão):

documentai <path-do-projeto> [opcoes]

Exemplos por cenário

Documentar projeto com defaults:

documentai generate .

Documentar em português:

documentai generate . --language pt-BR

Fixar modelo e evitar prompt interativo:

documentai generate . --model llama3.2

Salvar em pasta customizada:

documentai generate . --output site-docs

Gerar também SDD em Markdown:

documentai generate . --generate-md

Incluir testes na análise:

documentai generate . --include-tests

Forçar regeneração completa:

documentai generate . --force-generate-all

Aplicar instrução editorial customizada:

documentai generate . --spec "Escreva em pt-BR e destaque segurança"

Ou usando arquivo:

documentai generate . --spec ./minha-spec.md

Opções da CLI

• -o, --output <dir>: diretório de saída (padrão: docs)
• -m, --model <model>: modelo Ollama
• -u, --base-url <url>: URL da API compatível (padrão: http://localhost:11434/v1)
• --include-tests: inclui arquivos de teste
• --spec <prompt|file>: prompt inline ou arquivo .md
• --force-generate-all: regenera tudo ignorando incremental
• --language <lang>: idioma da documentação (padrão: en)
• --generate-md: gera sdd.md além do site HTML

Como o SDK funciona (pipeline)

1. Escaneia o repositório e classifica arquivos (source, config, infra, schema, docs, test, ci).
2. Resume arquivos prioritários (até 120) para montar contexto técnico.
3. Detecta módulos por árvore de diretórios.
4. Calcula diff incremental via Git.
5. Gera conteúdo com IA local:
   • overview
   • diagrama Mermaid
   • páginas por módulo
6. Renderiza HTML e opcionalmente sdd.md.
7. Salva .sdd-meta.json para próximas execuções.

Geração incremental (performance)

Por padrão, o documentcodeai tenta regenerar apenas o que mudou:

• lê commit salvo em .sdd-meta.json
• compara com HEAD
• atualiza somente módulos impactados
• overview e diagrama são sempre atualizados

Use --force-generate-all quando quiser rebuild completo.

Uso programático (SDK)

import { generate } from 'documentcodeai'

await generate('/caminho/do/projeto', {
  model: 'llama3.2',
  baseUrl: 'http://localhost:11434/v1',
  output: 'docs',
  includeTests: false,
  language: 'pt-BR',
  generateMd: true,
  spec: 'Foque em arquitetura e decisões técnicas'
}, (progress) => {
  console.log(progress.phase, progress.percent, progress.message)
})

Publicar no GitHub Pages

Fluxo comum:

documentai generate . --language pt-BR --generate-md

git add docs
git commit -m "docs: atualiza documentação gerada"
git push

Depois, habilite o GitHub Pages nas configurações do repositório apontando para a pasta/branch correta.

Troubleshooting

Ollama não está rodando

ollama serve

Obs.: o SDK já tenta iniciar automaticamente. Esse comando é fallback quando o auto-start falha no ambiente.

Modelo não encontrado localmente

ollama pull llama3.2

Nada mudou na geração incremental

Se aparecer "Nothing changed", é comportamento esperado quando não há diff relevante. Para regenerar tudo:

documentai generate . --force-generate-all

Boas práticas

• Mantenha README e arquivos de config atualizados para melhorar a qualidade do overview.
• Em CI/CD, sempre informe --model para evitar prompt interativo.
• Use --spec para padronizar estilo e foco da documentação no time.
• Rode --force-generate-all antes de releases importantes.

Limitações atuais

• Arquivos grandes são truncados para análise.
• A sumarização prioriza até 120 arquivos para manter desempenho.
• Sem histórico Git utilizável, a execução tende a regenerar mais conteúdo.

Licença

MIT