repoviz

repoviz は何をしますか？

コードベースをレンダリング可能なダイアグラムURLに変換します。すべてのダイアグラムは単一の https://x-cmd.com/draw URL（フラットでパーセントエンコードされたパラメータ）で表現され、ブラウザ、GitHub README、あらゆるMarkdownビューアでSVGとしてレンダリングされます。デフォルトモードではローカルファイルを書き込みません。ローカルエクスポートは scripts/ を介した明示的なリクエストがあった場合のみ実行されます。

レンダリング ≠ 推測: すべてのノードとエッジにはソースエビデンス（検証済み / 推測 / 不明）が付与されます。出力は検証可能な成果物であり、AIによる単なるスケッチではありません。

ステップ1 — 意図分析とチャートルーティング

ユーザーの意図とリポジトリの形状からダイアグラムタイプを選択します。該当するダイアグラムを構築する前に、一致する references/ ファイルのみを読み取ってください。

ユーザーの意図	ダイアグラム	リファレンス
システム概要、フォルダ階層、マイクロサービス、テクノロジースタック	アーキテクチャマップ (/draw/archmap)	references/architecture.md
リクエストライフサイクル、関数呼び出しチェーン、APIハンドシェイク	シーケンス図 (/draw/seq)	references/flowchart.md
分岐ロジック、アルゴリズム、認証/パイプラインのステージ	フローチャート (/draw/mermaid)	references/flowchart.md
ステートマシン、ステータス、リトライ/ロールバック	ライフサイクル (/draw/lifecycle)	references/flowchart.md
データパイプライン、依存関係/バンドルサイズ、トラフィックルーティング	サンキー (?type=sankey)	references/sankey.md
機能ツリー、モジュール分類	マインドマップ (/draw/mindmap)	references/general-charts.md
ロードマップ、スケジュール、リリース計画	ガント (/draw/gantt)	references/general-charts.md
定量的リポジトリメトリクス（言語別割合、カバレッジ、成長）	データチャート (`?type=pie	hbar
広範な「このリポジトリを可視化して」	マルチダイアグラムスイート: 1つの archmap 概要図 + 1つのサンキー図（データ/依存関係フロー）または seq 図（コアリクエストフロー）	該当する2つのリファレンス

archmap の同系列図（references/architecture.md 参照）: arch2（代替スキン）。データ/振る舞いモデリング: uc、dataflow、erd、class — 文法とライブ例については references/technical-diagrams.md を参照。テールチャート（ツリーマップ、ファネル、グラフなど）: /draw/echarts?d=<url-encoded echarts option JSON>。

スキャンモード — コードを読む前にスキャンスコープを決定します（ユーザーが選択可能。デフォルトは意図から判断）:

モード	スコープ	典型的な出力
quick	マニフェスト、深さ2のツリー、エントリポイント	1つの概要図
architecture	モジュール、サービス、依存関係グラフ	archmap （＋重み付きサンキー図）
deep-dive	呼び出しチェーン、データフロー、ステートマシン	seq / フローチャート / サンキースイート
impact	git diff とベースの差分：変更ファイルとその依存先	変更フロー図
full	上記すべて	リポジトリレポート（スイート + 品質レポート）

impact モードは references/architecture-diff.md（git-diff 差分ワークフロー）を読み込みます。full モードは references/codebase-report.md（標準レポート構造）を読み込みます。同じリポジトリの繰り返しスキャンでは references/incremental-scan.md（オプトインキャッシュプロトコル）を読み込む場合があります。マルチダイアグラムまたはエビデンスに敏感な作業では references/repository-ir.md を読み込みます。

ステップ2 — トークン節約型コードベーススキャン

1. まずルートマニフェストを読み取ります: package.json、go.mod、Cargo.toml、pyproject.toml、docker-compose.yml、および深さ3までのディレクトリツリーと宣言されたエントリポイント。
2. すべてのソースファイルを読んではいけません。エントリポイントファイルとルートテーブルをサンプリングし、コンポーネントをシグナルの高いノードとエッジに要約します。
3. 可能な限り実際の数量からサンキーの重みを導き出します：ファイルサイズ (du -sh)、インポート/参照カウント、またはユーザーが提供するトラフィック/コスト数値。
4. URL長ガードレール: 1つのダイアグラムは約15～20ノード（サンキーの場合は約60リンク）に抑え、URLを読み取り可能に保ち、CDN制限内に収めます。大規模リポジトリの場合は、高レベルの概要図とサブシステムごとの図を1つずつ出力し、単一の巨大な図は決して生成しません。
5. マニフェストと言語スタックを検出し、そのレンズでスキャンします：Go → パッケージ/インターフェース/goroutine；TypeScript → モジュール/インポートグラフ/APIルート；Rust → クレート/トレイト/機能；Python → パッケージ/デコレータ/エントリポイント。
6. スキャンしながらエビデンスを記録します：すべてのノード/エッジには file[:symbol[:lines]] とレベル（検証済み（コードで確認）、推測（構造から導出）、または不明（パターン仮定））が付与されます。ファイルを開かずに「検証済み」とマークしないでください。

ステップ3 — URLの構築

• まず軽量なRepository IRを構築します（スイート用：共有ノードインベントリ、ダイアグラムごとに1つのドキュメント）。エンコード時にIRをURLにマッピングします。スキーマと検証プロトコル：references/repository-ir.md。
• 構築するすべてのURLにはラベルがレンダラーに渡されます。URLを構築、検証、エクスポートする前にステップ4の機密性ルールを適用してください。
• 文法（ノード/エッジ/境界）、エンコードテーブル、実例、およびタイプごとの制限はリファレンスファイルに記載されています。それらに正確に従ってください。すべての例はライブテスト済みです。
• エンコードの要点：スペース %20、+ %2B、& %26、# %23、</> %3C/%3E、改行 %0A；セパレータ ; = , : / @ はそのままにします。Base64は使用しません。
• 一般的な修飾子：title=、scheme=dark|light、t=<style>（タイプごとのファミリーはリファレンスにあり — arch2/seq は t=shadcn で最良の見た目になります；arch2ノードはオプションの6番目 icon フィールドを受け付けます、例 n=api;be;API;ECS;r2c0;aws:ecs）、w=/h=、キャッシュバージョンを固定する v=N、num=all|peak|none（チャート用）。
• PNG出力はGB2312レベルのCJKサブセットを埋め込みます：まれな文字（例 渲）はPNGで豆腐になります。SVGにはそのような制限はありません — 中国語のPNGラベルには一般的な同義語を優先してください。
• 4xxの場合、レスポンスボディは修正例を含むプレーンテキストです。それを読み、問題のあるパラメータを修正して再試行してください。二度推測しないでください。

ステップ4 — 出力の提供

デフォルトモード — ファイル書き込みなし。 ダイアグラムごとに以下の形式で返信します：

### <ダイアグラムタイトル>
![<タイトル>](<draw-url>)
*[インタラクティブプレビュー](<draw-url>)* · [エディタで開く](<explore-url>)

- <箇条書き: ダイアグラムの表示内容 — 階層、クリティカルパス、最も重いフロー>
- <箇条書き: 注目すべき結合 / 単一障害点 / 所有権の境界>

• <explore-url> は /draw?type=X&q → /draw/explore?type=X&q、そして /draw/<name>?q → /draw/explore/<name>?q と書き換えます — これはdrawに組み込まれたインタラクティブエディタです。リンクしてください。再構築しないでください。
• ダイアグラムごとに2～5の簡潔な箇条書き。画像が成果物です。箇条書きは判断を追加します。
• 機密性: レンダリング — L1検証、および export.sh ダウンロード — はダイアグラムのラベル（フローチャートの場合はプログラムテキスト全体）をURLパラメータとして x-cmd.com のレンダラーに送信します。これらはサーバーのアクセスログに表示される可能性があり（パーセントエンコードは暗号化ではありません）、Markdown画像の埋め込みはクライアントやプロキシによって自動フェッチされる可能性があります。ローカルエクスポートはこれを回避しません — レンダリングは依然として x-cmd.com から要求されます。機密性の高いリポジトリの場合は、レンダリング、検証、またはエクスポートの前にユーザーに警告し、明示的な承認を得てください。または、ローカルにインストールされたdraw CLIを使用して完全にオフラインでレンダリングしてください。

スイートを品質レポートで閉じます（実際のカウントのみ — 決して捏造しないこと）：

リポジトリ分析 — <repo> (<scan_mode>, <commit>)
調査済みファイル: N | モジュール: N | 関係: N
エビデンス: 検証済み N · 推測 N · 不明 N
検証: L1 合格|スキップ (プライバシー) · L2 合格 · L3: N 未解決 (以下にフラグ)

L1は自動ではありません — URLをフェッチするため、ダイアグラムがx-cmd.comに送信されます。機密性の高いリポジトリの場合は、ユーザーの明示的な承認がある場合のみ実行してください（ステップ4の機密性ルール）。それ以外の場合は L1 skipped (privacy) と報告します。すべての 不明 をそのダイアグラムの下にフラグします。明示的な「検証」リクエストまたはエクスポート前のチェックの場合：bash scripts/validate.sh <urls...>（L1レンダリング）および bash scripts/validate.sh --ir <ir.json>（L2構造）。L3は、引用されたファイルの再読取りです。

エクスポートモード — ユーザーが明示的に「ローカルに保存」「SVG/PNGをダウンロード」「画像をエクスポート」「ショートリンク」「これをREADMEに入れて」「HTMLレポートを生成」などと言った場合のみ：

bash scripts/export.sh "<draw-url>" "<out.svg|png>"        # 単一ダウンロード
bash scripts/export.sh --batch <manifest.tsv>              # 複数: 行ごとに "<url>\t<out>", # コメント
bash scripts/shorten.sh <type> '<d-schema json>' [title]   # 永続的な /draw/c/<hash> (?type= チャートのみ)
bash scripts/build_html.sh "<title>" "<out.html>" '<json>' # スタンドアロンレポート (+ オプションのevエビデンス)
bash scripts/inject_readme.sh "<README.md>" '<json>'       # repovizマーカー間の図を挿入/更新

• export.sh は curl でダウンロードします（フォールバック：既にローカルにインストールされているCLI — パッケージをフェッチしたりインストールしたりしません）。.png ターゲットは自動で &format=png を取得します（高解像度にするには &scale=2|3 を追加； scheme=dark を渡すと — PNGのデフォルトはライト）。バッチモード：1行につき url<TAB>output、 # コメントは許可されます。いずれかの項目が失敗するとゼロ以外の終了コードを返します。
• shorten.sh はチャート定義（?d= JSONスキーマ）を x-cmd.com にPOSTします — レート制限は約30回/分/IP。 ?type= ファミリーのみがPOSTを受け付けます。ノード/エッジ図（/draw/archmap、/draw/seq、...）は405を返すため、完全なURLを維持してください。返される /draw/c/<hash> はGETでレンダリングされ、永続的です。明示的なユーザーリクエストがあった場合のみ実行してください：保存された定義は永続的であり、リンクを保持している人には公開されます（ステップ4の機密性ルール）。
• build_html.sh は {"title","url","note"[,"ev"]} オブジェクトのJSON配列を受け取ります（url は https://x-cmd.com / https://www.x-cmd.com のdrawレンダリングURLに制限されます； ev はオプションで、エンコードされた "node|file|symbol|lines|level;..." — フィルタリング可能なソースエビデンステーブルをレンダリングします）。ダーク/ライト対応の自己完結型レポートを生成します：サイドバーナビゲーション、ズーム、全画面、URLコピーボタン、PDF印刷対応。すべての値はHTMLエスケープされます。ペイロード例：[{"title":"Architecture","url":"https://x-cmd.com/draw/archmap?...","note":"3 tiers; gateway is the single entry","ev":"api|src/api.ts|createServer|12-40|verified"}]
• inject_readme.sh はべき等です：初回使用時に <!-- repoviz:start --> … <!-- repoviz:end --> ブロック（図ごとにMarkdown画像 + ノート）を追加し、以降の実行ではその場で置き換えます — 図はリポジトリ内の生きたアセットになります。
• エクスポート後、保存されたパスを出力し、チャット用のMarkdownブロックも引き続き出力して、ユーザーが両方を取得できるようにします。

ルール

• ブランドニュートラル：結果をrepovizダイアグラムとして提示し、レンダリングURLの名前を変更したりラップしたりしないでください。
• 1回のスキャン、複数の図：ダイアグラムごとにリポジトリを再読み取りする代わりに、スイート全体でノードインベントリを再利用します。
• 完全性よりも、適切に選択された少数のノードを優先し、詳細は sub キャプションと境界ボックスに折りたたみます。
• エビデンスがなければ存在しないも同然：すべてのノード/エッジは検証済み、推測、または不明としてフラグ付けされます — 決して捏造しないでください。IR/レンダラー分割を維持することで、スイート、レポート、将来のアーキテクチャ差分が1つのインベントリを共有でき、レンダリングは交換可能なアダプターとして機能します。
• URL-as-dataのインクリメンタル編集：既存のrepoviz図はそのURLによって完全に定義されます — その検査にビジョンや画像読み取りツールを決して使用しないでください。MarkdownからURLをデコードし、そのノード/エッジセットを現在のコードと比較し、更新されたURLをその場で発行し、ノードID、ラベル、レイアウト規則を保持します。