SourceSage CLI

O que SourceSage CLI faz?

Visão Geral

Use a CLI SourceSage a partir deste checkout de repositório para gerar resumos de repositório para o repositório atual ou outro repositório local.

Prefira o checkout local em vez de assumir que sourcesage está instalado globalmente. Nesta estrutura de repositório, a raiz da ferramenta SourceSage é o diretório que contém este SKILL.md.

Fluxo de Trabalho

1. Resolva a raiz da ferramenta SourceSage e o repositório alvo.

   • Se o usuário não especificou outro repositório, analise o workspace atual.
   • Se o workspace atual não é o repositório SourceSage, execute SourceSage a partir de seu próprio checkout com uv run --directory <raiz-sourcesage> sage ....

2. Escolha o comando mais simples que atenda à solicitação.

   • Resumo do repositório atual: uv run sage
   • Resumo do repositório atual em modo leve: uv run sage --lite
   • Resumo do repositório atual em japonês: uv run sage -l ja
   • Outro repositório com saída padrão dentro desse repositório: uv run --directory <raiz-sourcesage> sage --repo "<repositorio-alvo>"
   • Outro repositório em modo leve: uv run --directory <raiz-sourcesage> sage --repo "<repositorio-alvo>" --lite
   • Outro repositório com diretório de saída explícito: uv run --directory <raiz-sourcesage> sage --repo "<repositorio-alvo>" -o "<diretorio-saida>"
   • Relatório de diff obsoleto: uv run --directory <raiz-sourcesage> sage --repo "<repositorio-alvo>" --diff

3. Verifique os artefatos gerados após cada execução.

   • Resumo do repositório: <diretorio-saida>/.SourceSageAssets/Repository_summary.md
   • Relatório de diff obsoleto: <diretorio-saida>/.SourceSageAssets/RELEASE_REPORT/Report_<ultima-tag>.md
   • Abra o markdown gerado e resuma os resultados importantes em vez de apenas relatar que o comando foi executado.
   • No modo --lite, confirme que o resumo mantém a árvore, informações Git, estatísticas e arquivos README raiz, omitindo a seção ## File Contents.

4. Relate efeitos colaterais e incompatibilidades de comando.

   • Espere que o SourceSage crie <repo>/.SourceSageignore se ele não existir.
   • Trate --ignore-file como a substituição de ignore suportada.
   • Não confie em --use-ignore a menos que a CLI seja atualizada e re-verificada, pois a CLI atual não expõe essa flag.

Notas de Comando

• Prefira uv run sage dentro do repositório SourceSage porque o pyproject.toml define ambos os pontos de entrada sage e sourcesage.
• Prefira uv run --directory <raiz-sourcesage> sage ... fora do repositório SourceSage para que o comando use este checkout sem exigir uma instalação global.
• Recorra a sourcesage ou sage diretamente apenas quando o pacote já estiver instalado e o uv não estiver disponível.
• Use -l ja ou -l en para o idioma de saída.
• Use --lite para exploração inicial quando as regras de ignore ainda não estiverem ajustadas ou quando trechos completos de arquivos tornariam o resumo muito grande.
• Use -o quando o usuário quiser artefatos fora da raiz do repositório.
• Use --repo para analisar outro repositório a partir deste checkout.

Validação

• Execute o comando escolhido em vez de apenas descrevê-lo.
• Confirme que o arquivo markdown esperado existe.
• Leia a saída gerada e reporte o caminho mais um breve resumo do que foi produzido.
• Re-execute o comando exato após alterar quaisquer instruções de execução ou documentos que o mencionem.

Evite

• Não presuma que exemplos do README são autoritativos quando eles diferirem de sourcesage/cli.py.
• Não sobrescreva artefatos existentes silenciosamente quando o usuário pediu um destino específico e ele já contém resultados.
• Não descreva o uso do SourceSage de memória quando você pode inspecionar pyproject.toml e sourcesage/cli.py neste repositório.