SourceSage CLI

Que fait SourceSage CLI ?

Présentation

Utilisez l'interface en ligne de commande SourceSage depuis ce dépôt pour générer des résumés de dépôt pour le dépôt courant ou un autre dépôt local.

Privilégiez la version locale du dépôt plutôt que de supposer que sourcesage est installé globalement. Dans cette arborescence, la racine de l'outil SourceSage est le répertoire qui contient ce SKILL.md.

Flux de travail

1. Déterminez la racine de l'outil SourceSage et le dépôt cible.

   • Si l'utilisateur n'a pas spécifié un autre dépôt, analysez l'espace de travail actuel.
   • Si l'espace de travail actuel n'est pas le dépôt SourceSage, exécutez SourceSage depuis son propre répertoire de travail avec uv run --directory <racine-sourcesage> sage ....

2. Choisissez la commande la plus petite qui satisfait la demande.

   • Résumé du dépôt courant : uv run sage
   • Résumé du dépôt courant en mode léger : uv run sage --lite
   • Résumé du dépôt courant en japonais : uv run sage -l ja
   • Autre dépôt avec sortie par défaut dans ce dépôt : uv run --directory <racine-sourcesage> sage --repo "<dépôt-cible>"
   • Autre dépôt en mode léger : uv run --directory <racine-sourcesage> sage --repo "<dépôt-cible>" --lite
   • Autre dépôt avec répertoire de sortie explicite : uv run --directory <racine-sourcesage> sage --repo "<dépôt-cible>" -o "<répertoire-sortie>"
   • Rapport de diff obsolète : uv run --directory <racine-sourcesage> sage --repo "<dépôt-cible>" --diff

3. Vérifiez les artefacts générés après chaque exécution.

   • Résumé du dépôt : <répertoire-sortie>/.SourceSageAssets/Repository_summary.md
   • Rapport de diff obsolète : <répertoire-sortie>/.SourceSageAssets/RELEASE_REPORT/Report_<dernière-balise>.md
   • Ouvrez le Markdown généré et résumez les résultats importants au lieu de seulement signaler que la commande a été exécutée.
   • En mode --lite, confirmez que le résumé conserve l'arborescence, les informations Git, les statistiques et les fichiers README racine tout en omettant la section ## File Contents.

4. Signalez les effets secondaires et les incohérences de commande.

   • Attendez-vous à ce que SourceSage crée <dépôt>/.SourceSageignore s'il n'existe pas.
   • Traitez --ignore-file comme l'option de substitution d'ignorance prise en charge.
   • Ne vous fiez pas à --use-ignore sauf si l'interface en ligne de commande est mise à jour et revérifiée, car l'interface actuelle n'expose pas ce drapeau.

Notes de commande

• Privilégiez uv run sage à l'intérieur du dépôt SourceSage car pyproject.toml définit à la fois les points d'entrée sage et sourcesage.
• Privilégiez uv run --directory <racine-sourcesage> sage ... à l'extérieur du dépôt SourceSage afin que la commande utilise ce répertoire sans nécessiter d'installation globale.
• Repliez-vous sur sourcesage ou sage directement uniquement lorsque le paquet est déjà installé et que uv n'est pas disponible.
• Utilisez -l ja ou -l en pour la langue de sortie.
• Utilisez --lite pour une première exploration lorsque les règles d'ignorance ne sont pas encore paramétrées ou lorsque les extraits de fichiers complets rendraient le résumé trop volumineux.
• Utilisez -o lorsque l'utilisateur souhaite placer les artefacts en dehors de la racine du dépôt.
• Utilisez --repo pour analyser un autre dépôt depuis ce répertoire.

Validation

• Exécutez la commande choisie plutôt que de seulement la décrire.
• Vérifiez que le fichier Markdown attendu existe.
• Lisez la sortie générée et rapportez le chemin ainsi qu'un court résumé de ce qui a été produit.
• Ré-exécutez la commande exacte après avoir modifié des instructions d'exécution ou de la documentation qui la mentionnent.

À éviter

• Ne supposez pas que les exemples des README font autorité lorsqu'ils diffèrent de sourcesage/cli.py.
• N'écrasez pas silencieusement des artefacts existants lorsque l'utilisateur a demandé une destination spécifique et qu'elle contient déjà des résultats.
• Ne décrivez pas l'utilisation de SourceSage de mémoire alors que vous pouvez inspecter pyproject.toml et sourcesage/cli.py dans ce dépôt.