Sunwood-ai-labs/SourceSage

SourceSage CLI

概要

このリポジトリのチェックアウトからSourceSage CLIを使用して、現在のリポジトリまたは他のローカルリポジトリのリポジトリサマリを生成します。

sourcesageがグローバルにインストールされていると仮定するよりも、ローカルチェックアウトを優先します。このリポジトリのレイアウトでは、SourceSageツールのルートはこのSKILL.mdを含むディレクトリです。

ワークフロー

1. SourceSageツールのルートとターゲットリポジトリを解決します。

   • ユーザーが別のリポジトリを指定しなかった場合、現在のワークスペースを解析します。
   • 現在のワークスペースがSourceSageリポジトリでない場合、独自のチェックアウトからuv run --directory <sourcesage-root> sage ...でSourceSageを実行します。

2. リクエストを満たす最小のコマンドを選択します。

   • 現在のリポジトリサマリ: uv run sage
   • 現在のリポジトリサマリ（ライトモード）: uv run sage --lite
   • 現在のリポジトリサマリ（日本語）: uv run sage -l ja
   • 別のリポジトリ（デフォルト出力先はそのリポジトリ内）: uv run --directory <sourcesage-root> sage --repo "<target-repo>"
   • 別のリポジトリ（ライトモード）: uv run --directory <sourcesage-root> sage --repo "<target-repo>" --lite
   • 別のリポジトリ（明示的な出力ディレクトリ）: uv run --directory <sourcesage-root> sage --repo "<target-repo>" -o "<output-dir>"
   • 非推奨の差分レポート: uv run --directory <sourcesage-root> sage --repo "<target-repo>" --diff

3. 実行後に生成されたアーティファクトを確認します。

   • リポジトリサマリ: <output-dir>/.SourceSageAssets/Repository_summary.md
   • 非推奨の差分レポート: <output-dir>/.SourceSageAssets/RELEASE_REPORT/Report_<latest-tag>.md
   • 生成されたMarkdownを開き、コマンドが実行されたことだけを報告するのではなく、重要な結果を要約します。
   • --liteモードでは、サマリがツリー、Git情報、統計、ルートのREADMEファイルを保持し、## File Contentsセクションを省略していることを確認します。

4. 副作用とコマンドの不一致を報告します。

   • SourceSageは、存在しない場合に<repo>/.SourceSageignoreを作成することが予想されます。
   • --ignore-fileをサポートされている無視オーバーライドとして扱います。
   • CLIが更新され再検証されるまで、--use-ignoreに依存しないでください。現在のCLIはそのフラグを公開していないためです。

コマンドに関する注意

• pyproject.tomlがsageとsourcesageの両方のエントリポイントを定義しているため、SourceSageリポジトリ内ではuv run sageを優先します。
• SourceSageリポジトリ外ではuv run --directory <sourcesage-root> sage ...を優先します。これにより、グローバルインストールを必要とせずにこのチェックアウトを使用できます。
• パッケージがすでにインストールされており、uvが利用できない場合にのみ、直接sourcesageまたはsageにフォールバックします。
• 出力言語には-l jaまたは-l enを使用します。
• 無視ルールがまだ調整されていない場合や、完全なファイルの抜粋でサマリが大きくなりすぎる場合の初回探索には--liteを使用します。
• ユーザーがリポジトリルート外にアーティファクトを希望する場合は-oを使用します。
• このチェックアウトから別のリポジトリを解析するには--repoを使用します。

検証

• コマンドを説明するだけでなく、選択したコマンドを実行します。
• 期待されるMarkdownファイルが存在することを確認します。
• 生成された出力を読み、パスと生成された内容の簡単な要約を報告します。
• 実行手順やそれを参照するドキュメントを変更した後は、正確なコマンドを再実行します。

回避すること

• READMEの例がsourcesage/cli.pyと異なる場合、それらを信頼できるものとして仮定しないでください。
• ユーザーが特定の出力先を指定し、すでに結果が存在する場合に、既存のアーティファクトを静かに上書きしないでください。
• このリポジトリ内のpyproject.tomlとsourcesage/cli.pyを確認できるのに、記憶からSourceSageの使用方法を説明しないでください。