コンテンツにスキップ

parse コマンド

codeknit parse はソースファイルを読み込み、そのシンボル(およびオプションでシンボル間の関係)を .skt ファイルまたは JSON として書き出します。このガイドでは、最も遭遇しやすい状況について説明します。すべてのコマンドで共通のフラグの完全なリストについては、CLI フラグリファレンスを参照してください。出力の文法については、出力形式リファレンスを参照してください。

プロジェクトを初めてパースする

Section titled “プロジェクトを初めてパースする”
ターミナルウィンドウ
codeknit parse ./src

codeknit はチャンク化された .skt ファイルを ./skeleton/ に書き出します: map_001.skt、map_002.skt など。すべてを一度に読み込むのではなく、必要なチャンクを選択して開きます。

出力先を変更するには、出力ディレクトリを第2引数として渡します:

ターミナルウィンドウ
codeknit parse ./src ./output

ソースディレクトリ、またはその親ディレクトリを出力ディレクトリとして使用しないでください。

--output-mode でモードを選択します。

モード 使用する状況 結果
directory-flat ほとんどのプロジェクトをパースする場合(デフォルト) map_001.skt、map_002.skt、…
directory-tree 特定のファイルのコード構造を調べたい場合 ソースファイルごとに1つの .skt ファイルを生成し、ソースツリーをミラーリング
inline 単一ファイルをパースする場合、または他のツールにパイプする場合 標準出力に出力。出力ディレクトリは使用しない

ツリーモードでは、ファイル名はソースの拡張子を保持します: src/foo.c は src/foo.c.skt に、src/foo.h は src/foo.h.skt になります。大きなファイルは foo.c_part1.skt、foo.c_part2.skt などに分割されます。

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

プロジェクト全体で inline を使用しないでください。すべてを標準出力に書き出し、ターミナルや LLM のコンテキストウィンドウを溢れさせる可能性があります。

モードの選択について詳しくは、出力モードを参照してください。

同じプロジェクトで再実行する

Section titled “同じプロジェクトで再実行する”

codeknit は、選択した形式の生成済み出力が既に存在するディレクトリへの書き込みを拒否します。これにより、古いチャンクと新しいチャンクが混在するのを防ぎます。以前の出力を置き換えるには、--clean を追加します:

ターミナルウィンドウ
codeknit parse ./src --clean

--clean は事前に何も削除しません。codeknit は新しい出力をステージングディレクトリに生成し、生成が成功した場合にのみ古い生成済みファイルを置き換えます。生成が失敗した場合、またはプロセスが中断された場合、以前の出力が保持されるか、次の実行時に復元されます。codeknit が生成しなかった出力ディレクトリ内のファイルは保持されます。生成されたパスと衝突する場合、実行は失敗します。

JSON モードでは、codeknit.json に同じルールが適用されます。

落とし穴: 混合チャンク。 シンボル ID(S1、S2、…)や関係の結果は、実行ごとやバージョンごとに変更される可能性があります。0.5.0 にアップグレードした後は、--clean を使用して出力全体を再生成してください。異なる実行からのチャンクを組み合わせないでください。

parse をファイルに向けて、inline モードを使用します:

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

明示的に通常のソースファイルを選択した場合、codeknit はそのファイルに対して ignore-file や test-file のフィルタリングをスキップします。インクルード/エクスクルードパターンとサイズ制限は引き続き適用されます。

スクリプト用の JSON を取得する

Section titled “スクリプト用の JSON を取得する”
ターミナルウィンドウ
codeknit parse ./src --output-mode inline --format json --edges

JSON ドキュメントには、トップレベルのフィールド files、symbols、edges(存在しない場合は省略)、errors(存在しない場合は省略)があります。小さな例:

{
"files": ["app.go"],
"symbols": [
{
"id": "app.go::User",
"short_id": "S1",
"name": "User",
"file": "app.go",
"category": "type",
"kind": "struct",
"signature": "type User struct",
"span": [3, 3]
},
{
"id": "app.go::Save",
"short_id": "S2",
"name": "Save",
"file": "app.go",
"category": "callable",
"kind": "function",
"signature": "Save(u: S1)",
"span": [5, 5]
}
],
"edges": [
{
"from": "app.go::Save",
"from_short": "S2",
"to": "app.go::User",
"to_short": "S1",
"kind": "references"
}
]
}

JSON をディスクに書き出すには、--output-mode inline を省略します。ディレクトリモードでは、JSON は codeknit.json に出力されます。JSON は単一のドキュメントであり、行数で分割されません。

デフォルトでは、出力には [symbols] セクションのみが含まれ、トークンを節約します。何が何を呼び出し、含み、継承し、参照するかを知る必要がある場合は、--edges を追加します:

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

Codeknit はコンパイラなしで構文を分析するため、一部の関係は確立できません。各エッジはその確実性を示します:

S8 --references--> S5
S10 --references[unresolved]--> string, bool
S11 --calls[ambiguous]--> Helper [candidates=S12, S15]
  • --kind--> は解決された関係です。
  • --kind[unresolved]--> は codeknit がターゲットを確立できなかったことを意味します。
  • --kind[ambiguous]--> は複数のターゲットが可能であることを意味します。候補の ID は利用可能な場合にリストされます。

候補は可能性のあるターゲットであり、確認された依存関係ではありません。既知のエンドポイントは ShortID を使用します。一致するシンボルがない未解決のターゲットは、ソースファイルを基準とした名前として表示される場合があります。

JSON では、不確実なエッジは resolution("unresolved" または "ambiguous")と、利用可能な場合は candidates を完全なシンボル ID として持ちます。to_short は省略されます。

C および C++ では、#include ディレクティブは meta/file および meta/include シンボルになり、そのエッジは ShortID を持ちます。これにより、ディレクティブが記録されます。これは codeknit がヘッダーを見つけたことを意味しません。

グラフメトリクスは不確実なエッジを除外し、除外された数を報告します。HTML グラフビューアは不確実な関係の数を表示し、それらを描画しません。個々の不確実なエッジを検査するには、parse で --edges を使用します。これらのレポートについては、グラフコマンドを参照してください。

エッジの文法については、出力形式リファレンスにあります。解決ルールと制限については、言語サポートリファレンスにあります。

繰り返しトークンを圧縮するには、--minify を追加します:

ターミナルウィンドウ
codeknit parse ./src --minify

これにより、dict.skt(またはインラインの [dict] セクション)に辞書が書き込まれます。d0 や d1 などのコードを読む際に辞書の値に置き換えます。関係の種類もエンコードされますが、[unresolved] などの解決ラベルは読みやすいままです。

チャンクサイズを制御するには、--max-lines(デフォルト 500)を使用します:

  • directory-flat モードでは、これは目標値です。ソースブロックは分割されないため、チャンクは1ブロック分超える可能性があります。
  • directory-tree モードでは、各ソースチャンクのハードリミットです。最小値は 3 です。各チャンクは [symbols] と ## source-path ヘッダーを繰り返します。

.h と名付けられた C++ ヘッダーをパースする

Section titled “.h と名付けられた C++ ヘッダーをパースする”

Codeknit はデフォルトで .h ファイルを C としてパースします。この拡張子を持つ C++ ヘッダーの場合は、--header-language cpp を設定します:

ターミナルウィンドウ
codeknit parse ./src --header-language cpp

このフラグは .h ファイルにのみ影響します。.hpp や .hxx と名付けられたファイルは既に C++ としてパースされ、他の拡張子は通常のパーサーを保持します。

スキャンするファイルを制御する

Section titled “スキャンするファイルを制御する”

5つのソース処理コマンドはすべて、以下のフラグを受け入れます。これらは CLI フラグリファレンスに完全にリストされています。

ターミナルウィンドウ
codeknit parse ./src --include '**/*.go' --exclude '**/generated/' --strict
  • --include GLOB と --exclude GLOB は、入力ディレクトリを基準とした gitignore スタイルのパターンで、繰り返し可能です。シェルが展開しないように引用符で囲んでください。除外が優先されます。インクルードは .gitignore、テストファイルのフィルタリング、または組み込みの除外を上書きしません。
  • --max-file-size BYTES は、それより大きなファイルをスキップします。デフォルトは 10485760(10 MiB)です。0 は制限を無効にします。
  • --strict は、スキャンまたはパースが不完全な場合に出力を書き込む前に失敗します。デフォルトは false です。

Codeknit はシンボリックリンクと通常のファイルでないものをスキップし、報告します。祖先の .gitignore ルールは、作業ディレクトリに依存せずに適用されます。

落とし穴: 部分的な結果。 読み取り不可能なパス、サイズ超過のファイル、スキップされたシンボリックリンク、および構文警告は分析を不完全にします。--strict を使用しない場合、codeknit は使用可能な結果を保持し、問題を報告します:

  • stderr に、
  • JSON の errors フィールドに、または
  • SKT の [errors] セクション(インライン、またはディレクトリモードの warnings.skt)に。

サポートされているソースが選択されていない入力、または読み取りに失敗したすべてのソースを含む実行は、常に失敗します。正確な保証については、分析の信頼性を参照してください。

これらのフラグは parse に固有のものです。共通のフラグについては、CLI フラグリファレンスを参照してください。

フラグ デフォルト 説明
--output-mode directory-flat 出力モード: inline、directory-flat、または directory-tree。
--format skt 出力形式: skt または json。
--header-language c .h ファイルのパーサー: c または cpp。他の拡張子は変更されません。
--max-lines 500 フラット出力の行目標; 各ツリー ソースチャンクのハードリミット(最小 3)。
--collect-test false テストファイルを含める。
--minify false 辞書ベースの圧縮を使用する。
--edges false [edges] セクションを含める(デフォルトではトークンを節約するためオフ)。
--clean false 生成が成功した場合にのみ、以前の生成済み出力を置き換える。
--workers NumCPU 最大同時パースゴルーチン数。
--verbose false 進捗情報を表示する。
  • ほとんどのプロジェクトでは directory-flat を使用し、必要なチャンクのみを読み込みます。
  • トークンを節約するために、大規模なコードベースでは --minify を使用します。
  • 関係データが必要な場合にのみ --edges を渡します。
  • 特定の言語の抽出に依存する前に、テスト済み機能マトリックスと既知の制限を確認してください。