Sunwood-ai-labs/SourceSage

CLI de SourceSage

Resumen

Usa la CLI de SourceSage desde el checkout de este repositorio para generar resúmenes del repositorio actual o de otro repositorio local.

Prefiere el checkout local antes que asumir que sourcesage está instalado globalmente. En esta estructura de repositorio, la raíz de la herramienta SourceSage es el directorio que contiene este SKILL.md.

Flujo de trabajo

1. Resuelve la raíz de la herramienta SourceSage y el repositorio de destino.

   • Si el usuario no especificó otro repositorio, analiza el espacio de trabajo actual.
   • Si el espacio de trabajo actual no es el repositorio de SourceSage, ejecuta SourceSage desde su propio checkout con uv run --directory <raíz-sourcesage> sage ....

2. Elige el comando más pequeño que cumpla la solicitud.

   • Resumen del repositorio actual: uv run sage
   • Resumen del repositorio actual en modo ligero: uv run sage --lite
   • Resumen del repositorio actual en japonés: uv run sage -l ja
   • Otro repositorio con salida predeterminada dentro de ese repositorio: uv run --directory <raíz-sourcesage> sage --repo "<repositorio-destino>"
   • Otro repositorio en modo ligero: uv run --directory <raíz-sourcesage> sage --repo "<repositorio-destino>" --lite
   • Otro repositorio con directorio de salida explícito: uv run --directory <raíz-sourcesage> sage --repo "<repositorio-destino>" -o "<dir-salida>"
   • Informe de diff obsoleto: uv run --directory <raíz-sourcesage> sage --repo "<repositorio-destino>" --diff

3. Verifica los artefactos generados después de cada ejecución.

   • Resumen del repositorio: <dir-salida>/.SourceSageAssets/Repository_summary.md
   • Informe de diff obsoleto: <dir-salida>/.SourceSageAssets/RELEASE_REPORT/Report_<última-etiqueta>.md
   • Abre el markdown generado y resume los resultados importantes en lugar de solo informar que el comando se ejecutó.
   • En modo --lite, confirma que el resumen mantiene el árbol, la información de Git, las estadísticas y los archivos README raíz, omitiendo la sección ## File Contents.

4. Reporta efectos secundarios y desajustes de comandos.

   • Espera que SourceSage cree <repo>/.SourceSageignore si no existe.
   • Trata --ignore-file como la anulación de ignorados compatible.
   • No confíes en --use-ignore a menos que la CLI esté actualizada y verificada de nuevo, ya que la CLI actual no expone esa bandera.

Notas de comandos

• Prefiere uv run sage dentro del repositorio de SourceSage porque pyproject.toml define tanto sage como sourcesage como puntos de entrada.
• Prefiere uv run --directory <raíz-sourcesage> sage ... fuera del repositorio de SourceSage para que el comando use este checkout sin requerir una instalación global.
• Recurre a sourcesage o sage directamente solo cuando el paquete ya está instalado y uv no está disponible.
• Usa -l ja o -l en para el idioma de salida.
• Usa --lite para exploración inicial cuando las reglas de ignorado aún no están ajustadas o cuando los extractos completos de archivos harían que el resumen sea demasiado grande.
• Usa -o cuando el usuario quiera artefactos fuera de la raíz del repositorio.
• Usa --repo para analizar otro repositorio desde este checkout.

Validación

• Ejecuta el comando elegido en lugar de solo describirlo.
• Confirma que el archivo markdown esperado existe.
• Lee la salida generada y reporta la ruta junto con un breve resumen de lo que se produjo.
• Vuelve a ejecutar el comando exacto después de cambiar cualquier instrucción de ejecución o documentación que lo mencione.

Evita

• No asumas que los ejemplos de README son autoritativos cuando difieren de sourcesage/cli.py.
• No sobrescribas artefactos existentes en silencio cuando el usuario pidió un destino específico y ya contiene resultados.
• No describas el uso de SourceSage de memoria cuando puedas inspeccionar pyproject.toml y sourcesage/cli.py en este repositorio.