コンテンツにスキップ

グラフコマンド

graph サブコマンドを使用して、コードがどのように接続されているかを確認し、構造的な問題を見つけ、どのファイルを最初にリファクタリングするかを決定します。このガイドは、codeknitをインストールし、codeknit parseを実行できることを前提としています。

タスク コマンド
グラフを視覚的に探索 codeknit graph show
構造的な問題を見つける codeknit graph analyze
変更頻度が高く重要なファイルを見つける codeknit graph hotspots

graph show は入力を解析し、自己完結型のHTMLファイルを書き出します。シンボル(関数、クラス、型)はノードです。関係(呼び出し、含む、実装)はエッジです。

ターミナルウィンドウ
codeknit graph show ./myproject

ファイルは ./skeleton/codeknit-graph.html に書き出され、デフォルトのブラウザで開きます。

出力パスを選択したり、テストファイルを含めるには:

ターミナルウィンドウ
codeknit graph show ./myproject -o graph.html
codeknit graph show ./src --collect-test
フラグ デフォルト 目的
-o, --output ./skeleton/codeknit-graph.html 出力HTMLファイルパス
--collect-test false テストファイルを含める
--workers 0 (NumCPU) 最大同時解析goroutine数
--verbose false 進捗情報を表示

ビューアは解決済みの関係のみを描画します。不確定(unresolved または ambiguous)な関係の数は表示しますが、それらを描画したり、候補リンクを表示したりしません。

個々の不確定なエッジを確認するには、parse を --edges フラグ付きで実行します:

ターミナルウィンドウ
codeknit parse ./src --output-mode inline --edges

JSON出力にするには --format json を追加します。エッジと候補がどのように書き出されるかについては、出力形式リファレンスを参照してください。

graph analyze は22のグラフアルゴリズムを実行し、LLMが読める .skt レポートを生成します。

ターミナルウィンドウ
codeknit graph analyze ./myproject

レポートは ./skeleton/graph_analysis.skt に書き出されます。直接読むか、関連するソースとともにLLMに渡します。

閾値を上げると発見が減り、下げると増えます:

ターミナルウィンドウ
codeknit graph analyze ./myproject -o analysis.skt --fan-threshold 15
codeknit graph analyze ./myproject --top-n 50
codeknit graph analyze ./src --collect-test

--top-n 0 はランク付けされたセクションの上限を解除します。

フラグ デフォルト 目的
-o, --output ./skeleton/graph_analysis.skt 出力 .skt ファイルパス
--collect-test false テストファイルを含める
--workers 0 (NumCPU) 最大同時解析goroutine数
--verbose false 進捗情報を表示
--fan-threshold 10 ハブシンボルとしてフラグを立てる最小ファンインまたはファンアウト
--god-threshold 15 godクラスまたは関数としてフラグを立てる最小contains-エッジ数
--max-inheritance-depth 5 これより深い継承チェーンにフラグを立てる
--top-n 30 ランク付けされたセクションの上限;0 は無制限を意味する
--betweenness-threshold 0.001 報告する最小媒介中心性
--propagation-cutoff 0.05 変更伝播を続ける最小ヒューリスティックスコア

どの発見がどの質問に答えるかを知る

Section titled “どの発見がどの質問に答えるかを知る”
アルゴリズム 見つけるもの
循環依存(TarjanのSCC) 互いに依存し合うシンボルのグループ
ハブ検出 ファンインまたはファンアウトの結合度が高いシンボル
孤立検出 デッドコードの候補
godクラス/関数検出 過剰な数の子を含むシンボル
不安定性メトリック Ce/(Ca+Ce)を使用して脆弱または安定しているシンボルとパッケージ
深い継承チェーン --max-inheritance-depth より深い階層
媒介中心性 多くの依存パスが通るボトルネックスシンボル
接続点 削除するとグラフが分裂する単一障害点
PageRank 再帰的に重要なシンボル
推移的ファンイン 影響範囲:シンボルに直接または間接的に依存するすべて
変更伝播シミュレーション シンボルの変更がどの程度広がる可能性があるか
循環パッケージ依存 パッケージレベルの依存ループ
レイヤー違反検出 レイヤーを間違った方向に横断する依存
エントリポイントからの到達可能性 エントリポイントが到達しないコード
弱く連結したコンポーネント 孤立したコードのクラスター
依存重み パッケージがどの程度強く結合しているか
メインシーケンスからの距離 抽象度と不安定性のバランスが崩れたパッケージ
散弾銃手術検出 パッケージ内の多くの場所に触れる変更
特徴羨望検出 自分のパッケージよりも他のパッケージを多く使用するシンボル
安定依存違反 安定したパッケージが不安定なパッケージに依存する
インターフェース分離違反 メンバーのほとんどがユーザーによって使用されないインターフェース
包含深度 深くネストされたシンボル

これらのルールは、発見をどの程度信頼できるかに影響します:

  • 不確定な関係は除外されます。 依存メトリックは解決済みのエッジのみを使用します。レポートは除外した unresolved および ambiguous な関係の数をカウントします。
  • ファイルおよびインクルードメタデータは無視されます。 meta/file および meta/include シンボルは依存ランキングやデッドコードの発見に影響しません。
  • ファンインおよびファンアウトは個別の隣接ノードをカウントします。 包含は依存としてカウントされません。
  • 継承深度はすべての基底およびインターフェースをカバーします。 循環階層には深度が割り当てられません。
  • 到達可能性は main、Main、または init callableから始まり、依存エッジをたどります。到達可能なメンバーはそのコンテナを関連付けますが、その兄弟メンバーは関連付けません。スキャンが認識されたエントリポイントを見つけない場合、到達可能性の発見は省略されます。
  • コールバックは参照であり、呼び出しではありません。 コールバック引数や返されたcallableは、コールバックが実行されることを証明しません。
  • スコアはヒューリスティックです。 変更伝播は最強の依存パスを使用します。そのスコアやレイヤールールは測定された確率やコンパイラ保証ではありません。

すべての発見をレビューの候補として扱ってください。コードを変更する前に、レポートで名前が挙げられたシンボルを開き、以下を確認してください:

  • スキャンしたディレクトリ外の外部呼び出し元。
  • 動的ディスパッチ。
  • スキャンしなかった依存。

分析は構文ベースであるため、これらのいずれも結論を変える可能性があります。解決ルールと制限については、言語サポートリファレンスの関係解決を参照してください。

履歴を考慮したホットスポットを見つける

Section titled “履歴を考慮したホットスポットを見つける”

graph hotspots は、頻繁に変更され、構造的に重要な位置にあるファイルをランク付けします。また、同じコミットで繰り返し変更されるファイル(時間的結合)も報告します。Gitリポジトリ内のディレクトリで実行します。

ターミナルウィンドウ
codeknit graph hotspots ./myproject

レポートは ./skeleton/hotspots.skt に書き出されます。

これは2つのメトリックグループを組み合わせたものです:

  • 履歴: コミット頻度、追加および削除された行の変更量、および新しさ。
  • 構造: ファイルレベルのPageRank、推移的ファンイン、および媒介中心性。

レポートには、分析された関連コミットの数に基づく信頼レベルが含まれます。信頼性の低いレポートからのランキングは暫定的なものとして扱ってください。

履歴ウィンドウとフィルタを変更

Section titled “履歴ウィンドウとフィルタを変更”
ターミナルウィンドウ
# 2年間を分析し、JSONを書き出す
codeknit graph hotspots ./myproject --since 2y --format json -o hotspots.json
# より大きなコミットを許可し、より強い時間的結合を要求
codeknit graph hotspots . --max-files-per-commit 100 --min-cochanges 5

マージコミットは --include-merges を渡さない限り除外されます。--max-files-per-commit より多くのファイルを変更するコミットはバルクコミットとしてスキップされるため、生成された変更や機械的な変更がランキングを歪めることはありません。

フラグ デフォルト 目的
-o, --output ./skeleton/hotspots.skt 出力ファイルパス
--format skt 出力形式:skt または json
--since 12mo 履歴ウィンドウ(例:180d、12mo、2y)
--max-commits 2000 調査する最大コミット数
--max-files-per-commit 50 これより多くのファイルを変更するコミットを除外
--min-cochanges 3 時間的結合を報告する最小共有コミット数
--top-n 30 セクションごとの最大結果数
--include-merges false 履歴メトリックにマージコミットを含める
--collect-test false テストファイルを含める
--workers 0 (NumCPU) 最大同時解析goroutine数
--verbose false 進捗情報を表示

--format json を使用すると、各ホットスポットには score、history_score、structure_score、recency_score、pagerank、betweenness、commits、churn、transitive_fan_in が含まれます。各時間的結合エントリには left、right、strength、co_changes が含まれます。トップレベルには commits_visited、commits_analyzed、skipped_merges、skipped_bulk_commits も記録されます。これらのカウントを使用して、ランキングがどの程度の履歴に基づいているかを確認してください。

5つのソース処理コマンド(parse、fingerprint、graph show、graph analyze、および graph hotspots)は同じ選択フラグを受け入れます:

フラグ デフォルト 目的
--include GLOB サポートされているすべてのソース 一致するパスを含める;繰り返し可能
--exclude GLOB なし 一致するパスまたはディレクトリを除外;繰り返し可能。除外は包含に優先
--max-file-size BYTES 10485760 (10 MiB) これより大きなファイルをスキップ;0 は制限を無効
--strict false スキャンまたは解析が不完全な場合に出力を書き出す前に失敗

パターンは入力ディレクトリを基準としたgitignoreスタイルのグロブです。シェルが展開しないように引用符で囲んでください。包含は .gitignore ルールやテストフィルタリングを上書きしません。

ターミナルウィンドウ
codeknit graph analyze ./src --include '**/*.go' --exclude '**/generated/' --strict

シンボリックリンクおよび非通常ファイルはスキップされ、報告されます。スキャンおよび解析の問題はstderrに表示されます。--strict がない場合、codeknitは使用可能な部分的な結果を保持するため、レポートを信頼する前にstderrを確認してください。--strict を使用すると、不完全な分析は出力が書き出される前に停止します。すべてのソース読み取りが失敗した場合は常に失敗します。

正確な保証については、分析信頼性リファレンスを参照してください。