Descrição
codebase-snapshot é uma utilidade projetada para transformar um repositório de código em um conjunto de partes prontas para LLM, aderindo a um orçamento rígido de bytes. Ele aborda os desafios de alimentar grandes repositórios para modelos de linguagem, onde os arquivos podem ser grandes demais e as janelas de contexto pequenas demais. A ferramenta opera de forma determinística, garantindo uma saída consistente em execuções para entradas inalteradas.
Ler mais
A funcionalidade central gira em torno da criação de um diretório `snapshot/` contendo partes em texto simples. Cada parte é limitada por um teto de `maxPartBytes`; arquivos que excedem esse orçamento são truncados com marcadores de omissão explícitos. Para arquivos muito grandes, fornece um excerto de cabeçalho/cauda. Juntamente com as partes de código, gera um arquivo `manifest.json`. Este manifesto atua como um índice abrangente, listando cada arquivo incluído com detalhes como sua camada, tipo, linguagem, parte, hash e um resumo estrutural. Crucialmente, também registra cada arquivo excluído junto com a razão específica para sua omissão, como `gitignore`, `sensitive-file` ou `binary`.
Um recurso chave para manter a integridade do contexto é o comando `validate`. Este comando re-hash o repositório contra a instantânea gerada e sai com um código diferente de zero se algum desvio for detectado. Isso garante que o contexto do LLM permaneça fresco e preciso, evitando que os modelos trabalhem com código desatualizado. A ferramenta é projetada para ser segura por padrão, ignorando arquivos de credenciais, a menos que solicitado explicitamente, redigindo strings em formato secreto e impedindo a exclusão acidental de código-fonte ao se recusar a sobrescrever diretórios que não criou.
codebase-snapshot suporta uma ampla gama de linguagens de programação e frameworks, incluindo TypeScript, JavaScript, Python, Go, Rust, Java/Kotlin, C#/.NET, PHP, Ruby, C/C++, Vue, Svelte, Astro, Next.js, Nuxt, Remix, Angular, Solid, NestJS, Express, Fastify, Koa, Django, FastAPI, Flask, Laravel e Rails, muitas vezes sem exigir configuração. Ele fornece 25 predefinições automáticas que contribuem com camadas, tipos, padrões de ignorar ecossistemas e orçamentos recomendados para partes. Para linguagens que não são TypeScript, gera resumos de importação/exportação/classe/função, rotulando-os como `ast`, `structural` ou `heuristic` para indicar sua confiabilidade.
Além da interação humana, codebase-snapshot é construído para agentes de IA. Ele oferece um contrato legível por máquina e uma habilidade instalável, permitindo que os agentes conduzam todo o processo de forma autônoma. Os agentes podem usar comandos como `generate`, `validate`, `report` e `explain` para gerenciar instantâneas, verificar desvios, auditar segredos e entender inclusões/exclusões de arquivos. A ferramenta também suporta acesso programático à API para integração em sistemas maiores. Sua documentação abrangente cobre instalação, referência CLI, configuração, esquema de saída de instantâneas e guias para usá-la efetivamente com LLMs como ChatGPT, Claude e Cursor.
- CategoriaAssistentes de programação com IA
- Modelo de preçosGrátis
- ImplantaçãoCLI, Programmatic API
- PlataformasNode.js 18+
Recursos principais de codebase-snapshot
Geração de instantâneas determinísticas
Orçamento rígido de bytes para partes
Índice abrangente manifest.json
Validação de desvios com o comando `validate`
Detecção automática para 25 predefinições de projeto
Suporte para múltiplas linguagens de programação e frameworks
Redação de segredos e exclusão de arquivos sensíveis
Contrato legível por máquina para agentes de IA
Habilidade de agente instalável
Acesso programático à API
Relatórios e auditorias detalhadas
Configuração guiada para a primeira execução
Artefatos de saída configuráveis
Processamento limitado por memória para arquivos grandes
Comparação de instantâneas com o comando `diff`
Como usar codebase-snapshot?
Instalar: Use npm, yarn, pnpm ou bun para instalar `codebase-snapshot` globalmente ou como uma dependência do projeto.
Início Rápido: Execute `snapshot` no diretório do seu projeto para uma primeira execução guiada ou geração automática.
Configurar: Use o comando `init` para uma configuração interativa que escreve um arquivo `snapshot.config.ts` auto-documentado.
Gerar Instantânea: Execute `snapshot generate` para criar o diretório de instantânea pronto para LLM.
Validar Instantânea: Execute `snapshot validate` para comparar a instantânea com o repositório atual e verificar desvios.
Explicar Caminhos: Use `snapshot explain <path>` para entender por que um arquivo específico foi incluído, ignorado ou onde ele foi colocado.
Relatórios de Auditoria: Gere `snapshot report` para métricas de saúde, detalhes de camadas e auditorias de segredos.
Casos de uso de codebase-snapshot
- Geração de Contexto LLM
- Análise de Código por Agente de IA
- Automação de Revisão de Código
- Integração de Desenvolvedores
- Gerenciamento de Janelas de Contexto
- Auditoria de Código
- Garantindo Frescor do Contexto
- Comparação entre Repositórios
