gitnexus-guide

GitNexus ガイド

GitNexus のすべての MCP ツール、リソース、ナレッジグラフのスキーマをすばやく確認できます。

まず最初に行うこと

コードの理解、デバッグ、影響分析、リファクタリングに関わるタスクでは、次の手順に従ってください。

1. gitnexus://repo/{name}/context を読みます — コードベースの概要を確認し、インデックスが最新かどうかを確認します
2. タスクに合ったスキルを以下から選び、そのスキルファイルを読みます
3. スキルのワークフローとチェックリストに従います

手順 1 でインデックスが古いという警告が表示された場合は、まずターミナルで node .gitnexus/run.cjs analyze を実行してください。

スキル

タスク	読むスキル
アーキテクチャを理解する／「X はどのように動作しますか？」	gitnexus-exploring
影響範囲を確認する／「X を変更すると何が壊れますか？」	gitnexus-impact-analysis
バグを追跡する／「X が失敗するのはなぜですか？」	gitnexus-debugging
名前変更／抽出／分割／リファクタリング	gitnexus-refactoring
ツール、リソース、スキーマのリファレンス	gitnexus-guide（このファイル）
インデックス、ステータス、クリーン、wiki の CLI コマンド	gitnexus-cli

ツールのリファレンス

ツール	内容
query	プロセスごとにまとめたコードインテリジェンス — 概念に関連する実行フロー
context	シンボルを 360 度から表示 — 分類された参照、関与するプロセス
impact	シンボルの影響範囲 — 確信度とともに、深さ 1／2／3 で何が壊れるかを表示
trace	2 つのシンボル間の最短経路 — 1 回の呼び出しで「A はどのように B に到達しますか？」を確認
detect_changes	Git 差分による影響 — 現在の変更が何に影響するかを表示
rename	確信度タグ付きの編集による、複数ファイルにまたがる一括名前変更
cypher	生のグラフクエリ（最初に gitnexus://repo/{name}/schema を読みます）
explain	保存済みの汚染分析結果 — ソースからシンクへのデータフロー（analyze --pdg が必要）
pdg_query	制御／データ依存関係 — X を制御するもの（CDG）／Y の流れ先（REACHING_DEF）。analyze --pdg が必要
check	循環インポートなどのグラフ不変条件を確認
route_map	API ルートマップ — どのコンポーネント／フックがどのエンドポイントを取得するか、およびそれらを処理するハンドラーファイル
shape_check	レスポンス形状の不一致 — 各ルートが返すキーと、利用側がアクセスするキーを比較（不一致にフラグを付けます）
api_impact	API ルートの変更前レポート — 利用側、ミドルウェア、形状の不一致、リスクレベル
tool_map	MCP／RPC ツールの定義と、それらを処理するファイル
group_list	設定済みの複数リポジトリグループ、または 1 つのグループの設定を一覧表示
group_sync	グループのコントラクトレジストリを再構築（リポジトリ間の HTTP コントラクトリンク）。group.yaml の変更後、またはメンバーの再インデックス後に実行
list_repos	インデックス済みリポジトリを検出（ページネーション対応 — limit／offset）

list_repos のページネーション

list_repos はページネーションに対応しているため、大規模なレジストリでも MCP／LLM のトークン制限によって結果が切り捨てられません。省略可能な limit（デフォルトは 50、最大 200）と offset を受け取り、次を返します。

{
  "repositories": [
    { "name": "...", "path": "...", "indexedAt": "...", "lastCommit": "...", "stats": { } }
  ],
  "pagination": {
    "total": 437,
    "limit": 50,
    "offset": 0,
    "returned": 50,
    "hasMore": true,
    "nextOffset": 50
  }
}

すべてのリポジトリを列挙するには、hasMore が false になるまで、offset に pagination.nextOffset を設定して呼び出し続けます。

list_repos {}               → repos 1–50,    nextOffset 50,  hasMore true
list_repos { offset: 50 }   → repos 51–100,  nextOffset 100, hasMore true
…
list_repos { offset: 400 }  → repos 401–437,                 hasMore false   (done)

注：offset ≥ total の場合、空のページが返されます（total は引き続き報告されます）。範囲外または不正な形式の limit／offset（整数以外、limit が [1, 200] の範囲外、offset < 0）は、明確なエラーとともに拒否されます。limit が最大値を超える場合も拒否され、上限値に黙って切り詰められることはありません。並び順は決定的（小文字化した名前、次にパス）なので、レジストリに変更がない限り、ページネーションによって項目が欠落したり重複したりすることはありません。

テイント検出結果（explain）

explain は gitnexus analyze --pdg によって記録されたテイント検出結果を返します — 手続き内の TAINTED エッジに加え、手続き間テイントフェーズが関数レベルの source→sink チェーンを検出した場合の関数間 TAINT_PATH ホップです。各検出結果には、sink カテゴリ（command-injection、code-injection、path-traversal、sql-injection、xss）、source/sink の行、および各ホップで運ばれる変数を含む順序付きのホップパスが含まれます。

• explain {} — リポジトリ内のすべての検出結果を列挙します（limit で上限が設定され、順序は決定的です）
• explain { target: "src/vuln.ts" } — ファイル内の検出結果（サフィックスパスの一致も受け付けます）
• explain { target: "runUserCommand" } — 関数内の検出結果（context と同様に解決されます。曖昧な名前はランク付けされた候補を返します）

--pdg なしでインデックスされたリポジトリは、明確な「テイントレイヤーなし」という注記を返します。注意点: クロージャ/コールバック、プロパティ/フィールド、および暗黙的なフローはモデル化されておらず、手続き間の検出結果は文レベルのパス証明ではなく関数レベルの TAINT_PATH ホップであるため、検出結果がないことは安全性の証明にはなりません。SANITIZES（サニタイザーによる無害化）エッジは cypher を介してクエリできます。

制御依存とデータ依存（pdg_query）

pdg_query は gitnexus analyze --pdg が記録する制御/データ依存レイヤー（CDG + REACHING_DEF、基本ブロック粒度）を読み取ります — explain の制御/データ版に相当します。これは常にアンカーが必要（target のファイルパスまたはシンボルで、context と同様に解決されます）で、2つのモードがあります:

• pdg_query { mode: "controls", target: "..." } — CDG: 「X はどのような条件で実行されるか？」。各エッジは、制御する述語ブロック → 依存ブロックであり、reason に分岐の向き（'T'/'F'）が含まれます。早期の return/throw へのエッジは guard: true とフラグ付けされます（ガード節の発見 — 向きは述語に依存するため、ガードを固定のラベルでフィルタリングしないでください）。
• pdg_query { mode: "flows", target: "...", variable?: "..." } — REACHING_DEF の関数内での def→use エッジ。variable を渡すと1つのバインディングを追跡できます。

--pdg なしでインデックスされたリポジトリは、「PDG レイヤーなし」という注記を返します（またはレイヤーが確認できない場合は「ステータス不明」）。手続き内のみです — 関数間のフローはテイントの領域です（explain）。生の CDG/REACHING_DEF エッジも cypher を介してクエリできます。完全なクエリサーフェスについては gitnexus-pdg-query スキルを参照してください。

2つのシンボル間の最短パス（trace）

trace は「A はどのように B に到達するか？」を1回の呼び出しで回答します — 3〜8 の context/impact ホップを手動で連鎖させる代わりに、CALLS（および HAS_METHOD。これによりクラスを起点とするトレースはそのメソッドまで降りていきます）上の最短の有向パスを返します。

• trace { from: "validateUser", to: "executeQuery" } — 2つのシンボル間の最短パス。
• 一般的な名前は from_uid/to_uid（曖昧さゼロ）または from_file/to_file で曖昧さを解消します。曖昧な名前はランク付けされた候補を返します。
• maxDepth（デフォルト 10、最大 30）が探索の範囲を制限します。includeTests（デフォルト false）はテストファイルのシンボルを通過するトラバーサルを許可します。

順序付きの hops（各要素は { name, filePath, startLine }）と、{ relType, confidence } の整列された edges[] を返すため、呼び出しホップと包含（HAS_METHOD）ホップを区別できます。パスが存在しない場合は、到達可能な最遠のノード（チェーンが途切れる場所）を報告し、先にトラバーサルの上限に達した場合は truncated: true を設定します。すべての結果には status が付きます: ok / no_path / ambiguous / not_found / error。

リポジトリ間（実験的）: repo: "@groupName" を渡すと、グループのメンバーリポジトリ間でトレースできます — パスは1つの ContractLink 境界を越えることがあります（crossings[] にブリッジされたコントラクトを含む CONTRACT_LINK ホップとして報告されます）。to を完全に省略すると、from の送信 HTTP 呼び出しが到達する任意のプロバイダーエンドポイントを追跡します。グループは group_list / group_sync を介して設定します。

リソースリファレンス

ナビゲーション用の軽量な読み取り（約100〜500トークン）：

リソース	内容
gitnexus://repo/{name}/context	統計情報、古さのチェック
gitnexus://repo/{name}/clusters	凝集度スコア付きの全機能領域
gitnexus://repo/{name}/cluster/{clusterName}	領域のメンバー
gitnexus://repo/{name}/processes	すべての実行フロー
gitnexus://repo/{name}/process/{processName}	ステップごとのトレース
gitnexus://repo/{name}/schema	Cypher 用のグラフスキーマ

グラフスキーマ

ノード： File、Folder、Function、Class、Interface、Method、CodeElement、Community、Process、Route、Tool、および言語固有の型（Struct、Enum、Trait、Impl、Namespace、Module、…）、さらに BasicBlock（--pdg のインデックスのみ）。ノードの完全な一覧は gitnexus://repo/{name}/schema にあります。 エッジ（CodeRelation.type 経由）： CALLS、IMPORTS、EXTENDS、IMPLEMENTS、DEFINES、CONTAINS、MEMBER_OF、HAS_METHOD、HAS_PROPERTY、ACCESSES、METHOD_OVERRIDES、METHOD_IMPLEMENTS、STEP_IN_PROCESS、HANDLES_ROUTE、FETCHES、HANDLES_TOOL、ENTRY_POINT_OF、WRAPS、QUERIES、INJECTS、および --pdg 専用の型（CFG、REACHING_DEF、TAINTED、SANITIZES、TAINT_PATH、CDG。デフォルトのインデックスでは行数はゼロです）。

Cypher を記述する前に gitnexus://repo/{name}/schema を読み取ってください。これは、インデックス化されたリポジトリの正式なスキーマです。

MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "myFunc"})
RETURN caller.name, caller.filePath