Ingerir uma árvore de código-fonte

Uma árvore de código-fonte é a melhor coisa que você pode dar para o pipeline de conhecimento ler. É código real que usa a tecnologia, então o que o pipeline encontra ali é o que as pessoas de fato fazem com ela. A documentação buscada na web é o plano B, para uma tecnologia que não tem código para você apontar.

Esta página é para quem vai identificar componentes de conhecimento (knowledge components) a partir de um projeto no próprio disco. Ela cobre a flag --source e o bundle que ela monta. Para páginas de documentação em vez de código, veja Buscar documentação de uma URL.

Não existe um comando de ingestão

A ingestão é uma flag, não um passo que você roda sozinho. Você passa --source <path> para um comando que precisa de algo para ler, e esse comando monta o bundle da árvore antes de fazer qualquer outra coisa. Estes comandos aceitam a flag:

• os três comandos de identificação — veja Identificar componentes de conhecimento
• o /fito-create-or-update-technology, que redige as descrições de uma tecnologia a partir do que lê — veja Provisionar uma tecnologia

Antes de começar

• Uma sessão do pi em um diretório de trabalho seu, com o Fito instalado nele. O bundle é escrito dentro desse diretório, e o Fito se recusa a escrevê-lo dentro do próprio pacote. Veja Preparar um diretório de trabalho.
• O projeto, no seu disco. Um clone basta — o bundle lê a árvore de trabalho e nunca o histórico do git.
• Para um comando de identificação, a tecnologia (technology) e a linha principal dela já provisionadas no Fito.

Montar o bundle de uma árvore

1. Na sua sessão do pi, passe --source para um comando de identificação:

   /fito-identify-domain-concepts Javalin --technology javalin --technology-version 7 --source ~/code/my-javalin-app

   Troque ~/code/my-javalin-app pelo caminho do seu projeto. Um caminho relativo é resolvido a partir do seu diretório de trabalho.

2. Deixe o comando rodar. Ele monta o bundle primeiro e depois o entrega ao identificador como a coisa a ler. A flag vence o --fetch: quando um bundle é montado, o comando não busca nada na web.

Confirme que deu certo: o bundler imprime uma linha com a contagem e o destino, e uma terceira linha quando deixou arquivos de fora:

✓ Bundled <n> files (<bytes> bytes) from <source-path>
  into <working-dir>/output/1-ingest/source_bundle
  <k> skipped (binary / oversized / symlink) — see bundle.json

O que o bundle guarda

O bundle fica em ./output/1-ingest/source_bundle/ e tem duas partes:

• files/ — uma cópia de cada arquivo que entrou, no mesmo caminho relativo que tinha no seu projeto. O identificador lê, busca e lista essa pasta como se fosse a árvore real.
• bundle.json — o caminho de origem, a hora da montagem, cada arquivo incluído com o tamanho, e cada arquivo pulado com o motivo.

Cinco tipos de coisa ficam de fora:

Fica de fora	Regra	Aparece no bundle.json
Diretórios de ferramentas	.git, .hg, .svn, node_modules, build, dist, target, coverage, .gradle, .idea, .vscode, .next, .svelte-kit, .venv, venv, __pycache__, o output do próprio pipeline e as pastas de autoria de caso .case e .authoring	Não
Lockfiles e ruído	package-lock.json, yarn.lock, pnpm-lock.yaml, bun.lockb, .DS_Store	Não
Arquivos binários	Um byte NUL nos primeiros 8 KiB	Sim, como binary
Arquivos grandes	Acima de 256 KiB	Sim, como too large (… bytes > 262144 cap)
Links simbólicos	Nunca seguidos	Sim, como symlink (not followed)

Um arquivo central grande não é lido

O limite de tamanho vale para todo arquivo, inclusive o que mais importa. Um projeto cuja classe principal é um único arquivo de 300 KiB perde esse arquivo, e o identificador nunca o vê. Procure o pulo no bundle.json e complemente com documentação buscada quando o arquivo perdido for justamente o que explica a tecnologia.

Montar de novo para o próximo comando

Cada comando de identificação com --source remonta o bundle do zero e substitui o anterior inteiro. Isso é barato, e é o jeito mais simples de rodar os três comandos de identificação sobre a mesma árvore: passe o mesmo --source para cada um.

Deixar o --source de fora não reaproveita o bundle. Sem ele, um comando de identificação lê o --docs, e o --docs tem como padrão a pasta da documentação buscada, ./output/1-ingest/extracted_links_content/. Para reaproveitar um bundle sem remontá-lo, aponte o --docs para ele:

/fito-identify-usage-scenarios Javalin --technology javalin --technology-version 7 --docs ./output/1-ingest/source_bundle/

Ingerir um caso que você está criando

Quando você trabalha dentro de um checkout de caso — um diretório com .case/manifest.yaml —, um comando de identificação que não recebeu nem --source, nem --docs, nem --fetch verifica se o checkout é seu para criar. Se for, ele oferece seguir com --source ., e você responde.

A verificação é uma pergunta sobre a origem do checkout:

• Autoria — o próprio repositório do caso, uma árvore sem remote origin, um origin fora do GitHub, ou um fork de um repositório que o Fito não registrou.
• Não é autoria — um fork no GitHub de um caso publicado e registrado no Fito. É exatamente o que o /fito-case-open cria para quem aprende, então nenhuma oferta é feita.

A verificação precisa do git, de um gh autenticado e de um servidor Fito alcançável. Quando ela não consegue decidir — gh ausente, servidor fora do ar —, não faz oferta, e o comando segue sem --source.

Nunca faça commit da pasta output/

Rodar o pipeline dentro de uma árvore de caso deixa ali um output/ não rastreado, e o pi deixa um .pi/ não rastreado. A publicação tolera os dois enquanto continuarem fora do git. Faça commit de qualquer um deles e a publicação recusa, porque os levaria a todo mundo que abrir o caso.

Quando o bundler recusa

Cada recusa para a execução antes de qualquer escrita.

Mensagem	O que significa	O que fazer
the output directory is inside the Fito TUI package and will not be written	Sua sessão do pi está rodando no diretório do pacote do Fito	Vá para um diretório de trabalho seu
The output directory exists and holds content that is not a previous bundle … Fito will not overwrite it.	Há algo que não é um bundle em ./output/1-ingest/source_bundle/	Mova ou remova esse conteúdo
source path is not a directory: <path>	O caminho do --source está errado, ou é um arquivo	Corrija o caminho
no ingestible files found under <path>	Todo arquivo foi excluído ou pulado	Confira o caminho; leia a tabela acima
the output directory must not equal or contain the source tree	A origem está dentro do próprio destino do bundle	Aponte o --source para outro lugar

Se o pacote do Fito estiver instalado sem a skill de ingestão, o comando de identificação avisa e recorre à documentação buscada:

The `fito-source-ingestion` skill is not available yet — falling back to
fetched documentation (`--docs` / `--fetch`).

O que vem a seguir

• Identificar componentes de conhecimento — rode os três comandos de identificação sobre o bundle.
• Buscar documentação de uma URL — complemente uma árvore cujos arquivos principais eram grandes demais para o bundle.