グラフコマンド
graph サブコマンドを使用して、コードがどのように接続されているかを確認し、構造的な問題を見つけ、どのファイルを最初にリファクタリングするかを決定します。このガイドは、codeknitをインストールし、codeknit parseを実行できることを前提としています。
| タスク | コマンド |
|---|---|
| グラフを視覚的に探索 | codeknit graph show |
| 構造的な問題を見つける | codeknit graph analyze |
| 変更頻度が高く重要なファイルを見つける | codeknit graph hotspots |
コードグラフを可視化
Section titled “コードグラフを可視化”graph show は入力を解析し、自己完結型のHTMLファイルを書き出します。シンボル(関数、クラス、型)はノードです。関係(呼び出し、含む、実装)はエッジです。
codeknit graph show ./myprojectファイルは ./skeleton/codeknit-graph.html に書き出され、デフォルトのブラウザで開きます。
出力パスを選択したり、テストファイルを含めるには:
codeknit graph show ./myproject -o graph.htmlcodeknit graph show ./src --collect-test| フラグ | デフォルト | 目的 |
|---|---|---|
-o, --output |
./skeleton/codeknit-graph.html |
出力HTMLファイルパス |
--collect-test |
false |
テストファイルを含める |
--workers |
0 (NumCPU) |
最大同時解析goroutine数 |
--verbose |
false |
進捗情報を表示 |
未解決の関係を調査
Section titled “未解決の関係を調査”ビューアは解決済みの関係のみを描画します。不確定(unresolved または ambiguous)な関係の数は表示しますが、それらを描画したり、候補リンクを表示したりしません。
個々の不確定なエッジを確認するには、parse を --edges フラグ付きで実行します:
codeknit parse ./src --output-mode inline --edgesJSON出力にするには --format json を追加します。エッジと候補がどのように書き出されるかについては、出力形式リファレンスを参照してください。
構造を分析し問題を見つける
Section titled “構造を分析し問題を見つける”graph analyze は22のグラフアルゴリズムを実行し、LLMが読める .skt レポートを生成します。
codeknit graph analyze ./myprojectレポートは ./skeleton/graph_analysis.skt に書き出されます。直接読むか、関連するソースとともにLLMに渡します。
レポートを調整
Section titled “レポートを調整”閾値を上げると発見が減り、下げると増えます:
codeknit graph analyze ./myproject -o analysis.skt --fan-threshold 15codeknit graph analyze ./myproject --top-n 50codeknit 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 | 再帰的に重要なシンボル |
| 推移的ファンイン | 影響範囲:シンボルに直接または間接的に依存するすべて |
| 変更伝播シミュレーション | シンボルの変更がどの程度広がる可能性があるか |
| 循環パッケージ依存 | パッケージレベルの依存ループ |
| レイヤー違反検出 | レイヤーを間違った方向に横断する依存 |
| エントリポイントからの到達可能性 | エントリポイントが到達しないコード |
| 弱く連結したコンポーネント | 孤立したコードのクラスター |
| 依存重み | パッケージがどの程度強く結合しているか |
| メインシーケンスからの距離 | 抽象度と不安定性のバランスが崩れたパッケージ |
| 散弾銃手術検出 | パッケージ内の多くの場所に触れる変更 |
| 特徴羨望検出 | 自分のパッケージよりも他のパッケージを多く使用するシンボル |
| 安定依存違反 | 安定したパッケージが不安定なパッケージに依存する |
| インターフェース分離違反 | メンバーのほとんどがユーザーによって使用されないインターフェース |
| 包含深度 | 深くネストされたシンボル |
結果を正しく読む
Section titled “結果を正しく読む”これらのルールは、発見をどの程度信頼できるかに影響します:
- 不確定な関係は除外されます。 依存メトリックは解決済みのエッジのみを使用します。レポートは除外した
unresolvedおよびambiguousな関係の数をカウントします。 - ファイルおよびインクルードメタデータは無視されます。
meta/fileおよびmeta/includeシンボルは依存ランキングやデッドコードの発見に影響しません。 - ファンインおよびファンアウトは個別の隣接ノードをカウントします。 包含は依存としてカウントされません。
- 継承深度はすべての基底およびインターフェースをカバーします。 循環階層には深度が割り当てられません。
- 到達可能性は
main、Main、またはinitcallableから始まり、依存エッジをたどります。到達可能なメンバーはそのコンテナを関連付けますが、その兄弟メンバーは関連付けません。スキャンが認識されたエントリポイントを見つけない場合、到達可能性の発見は省略されます。 - コールバックは参照であり、呼び出しではありません。 コールバック引数や返されたcallableは、コールバックが実行されることを証明しません。
- スコアはヒューリスティックです。 変更伝播は最強の依存パスを使用します。そのスコアやレイヤールールは測定された確率やコンパイラ保証ではありません。
発見に安全に対処する
Section titled “発見に安全に対処する”すべての発見をレビューの候補として扱ってください。コードを変更する前に、レポートで名前が挙げられたシンボルを開き、以下を確認してください:
- スキャンしたディレクトリ外の外部呼び出し元。
- 動的ディスパッチ。
- スキャンしなかった依存。
分析は構文ベースであるため、これらのいずれも結論を変える可能性があります。解決ルールと制限については、言語サポートリファレンスの関係解決を参照してください。
履歴を考慮したホットスポットを見つける
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 |
進捗情報を表示 |
JSON出力を読む
Section titled “JSON出力を読む”--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 も記録されます。これらのカウントを使用して、ランキングがどの程度の履歴に基づいているかを確認してください。
スキャンするソースを制御
Section titled “スキャンするソースを制御”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 を使用すると、不完全な分析は出力が書き出される前に停止します。すべてのソース読み取りが失敗した場合は常に失敗します。
正確な保証については、分析信頼性リファレンスを参照してください。
- CLIフラグリファレンス:すべてのコマンドのすべてのフラグ。
- 出力形式リファレンス:
.sktおよびJSON構文。 - 言語サポートリファレンス:抽出および解決の制限。
- パースコマンドガイド:個々のファイルのシンボルとエッジを抽出。