コンテンツにスキップ

分析の信頼性

これらの動作は、0.5.0 以降の未リリースの Go/CLI の変更点を説明しています。

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、テストフィルタリング、または組み込みの除外を上書きしません。否定パターン(!pattern)はこれらのフラグでは受け入れられません;個別のインクルードおよび除外コントロールを使用してください。

ターミナルウィンドウ
codeknit parse ./src --include '**/*.go' --exclude '**/generated/' --strict
codeknit fingerprint ./src --max-file-size 2097152 --include '**/*.ts'
codeknit parse ./src/app.go --output-mode inline --format json

ディレクトリスキャンは、プロジェクトの場所を基準とした祖先およびネストされた .gitignore ファイルを尊重し、プロセスの作業ディレクトリとは独立しています。最も近い .git ディレクトリまたはワークツリーマーカーがリポジトリの境界を確立します。リポジトリの外部では、祖先の ignore ファイルが依然として適用されます。無視されたディレクトリの下にある選択されたサブディレクトリは無視されたままです。明示的に選択された通常のソースファイルは、ignore およびテストフィルタリングをバイパスしますが、インクルード/除外およびサイズ制限は依然として適用されます。

ソースシンボリックリンク、ディレクトリシンボリックリンク、および非通常のソースはスキップされ、報告されます。読み取りはスキャンルートに限定され、サイズ制限は読み取り中に再度適用されるため、発見後に成長したファイルが制限をバイパスすることはできません。組み込みのディレクトリ除外には、.git、.hg、.svn、node_modules、Python キャッシュ、および一般的な Python 仮想環境が含まれます。テストファイルは、--collect-test が設定されていない限り除外されたままです。

読み取り不可能なディレクトリ/ファイル、ignore ファイルの読み取り失敗、スキップされたシンボリックリンク、サイズ超過のソース、および構文警告は分析を不完全にします。デフォルトでは、使用可能な部分的な結果が保持され、診断が stderr に表示されます。解析 JSON には、errors にパス/理由のレコードが含まれます;SKT には、[errors] がインラインまたは warnings.skt に含まれます。グラフ/フィンガープリントコマンドも stderr に診断を報告します。意図的に無視またはフィルタリングされたファイルは警告ではありません。--strict は、出力の公開前に不完全な結果を拒否します。サポート対象のソースが選択されていない入力、またはすべてのソースの読み取りが失敗した実行は、常に失敗終了します。

TUI は同じシンボリックリンクポリシーと 10 MiB のデフォルトを使用します。そのフォームは、まだ新しい選択および strict フラグを公開していません。

ツリー出力は、完全なソース名に .skt を追加します:src/foo.c は src/foo.c.skt になり、src/foo.h は src/foo.h.skt になります。分割出力は src/foo.c_part1.skt、src/foo.c_part2.skt などを使用します。辞書および診断ファイルは、予約された名前 dict.skt および warnings.skt を保持します。競合する出力パス、大文字小文字のみの衝突を含む、は明確に失敗します。

ツリー SKT には、--max-lines が少なくとも 3 である必要があります。各シンボルチャンクは、[symbols] および ## source-path ヘッダーを繰り返します。エッジのみのチャンクは [edges] を持ちます。すべてのソースチャンクは制限を尊重します;辞書および診断ファイルは個別の補助出力です。フラット SKT はソースブロックをそのまま保持するため、その行制限は分割の目標であり、大きなソースブロックの厳密な制限ではありません。JSON は単一のドキュメントであり、行数で分割されません。

ディレクトリ生成は、兄弟のステージングディレクトリで完了します。--clean がない場合、選択された形式の既存の生成出力があるとエラーが発生します。--clean がある場合、古い .skt ファイル(SKT モード)または codeknit.json(JSON モード)は、生成が成功した後にのみ置き換えられます。無関係なエントリは保持されます;1つとの衝突があるとエラーが発生します。ソースディレクトリまたはその祖先を出力ディレクトリとして使用しないでください。

公開はディレクトリ固有のロックを保持し、以前の出力をバックアップし、置換が失敗した場合に復元します。プロセスがディレクトリのリネームの間に終了した場合、次の呼び出しは何も生成する前にバックアップを復元します。兄弟の .NAME.codeknit.lock ファイルは、将来の公開者を調整するために意図的に残ります;アクティブなロックまたは回復バックアップを削除しないでください。2つのディレクトリリネームの間には短い間隔があるため、中断のないアクセスを必要とする読者は生成と調整する必要があります。これはプロセス障害からの回復を提供しますが、ストレージ障害や電源喪失に対する保証ではありません。

個々のレポートは、宛先を置き換える前に一時的な兄弟に書き込まれ、同期されます。既存のファイルは生成中に切り捨てられません。インラインの stdout は、その消費者が失敗した場合にロールバックできません。

厳密なマッチングは、フィンガープリントの対象となる宣言の中で同じシンボルカテゴリにおける、完全に正規化されたトークンストリームが同一であることを意味します。これは、同一のソーステキストや証明された意味的等価性を意味するものではありません。厳密な候補グループは、ファジー・ハッシュの等価性ではなく、トークンストリーム自体を使用します。

500 未満の対象シンボルでは、構造検出は同じカテゴリのすべてのペアを比較します。500 以上では、すべての厳密なトークンペアは候補検索とは独立に保持され、他のペアはシンボルごとに上位50の構造的近傍を使用します。したがって、近似重複の検索は大規模な入力では網羅的ではありません。検索は依然としてすべてのベクトルをスキャンします;全体のアルゴリズムを準二次にすることはありません。

類似度範囲フィルタリングは依然として適用されます。デフォルトの範囲は65~95%で、100%のマッチを除外します。厳密なマッチを含めるには、以下を使用します:

ターミナルウィンドウ
codeknit fingerprint ./src --min-similarity 100 --max-similarity 100

オプションの --rerank は、意味的候補を追加し、コサイン一致を適用し、結合スコアでフィルタリングします;これにより、構造的に厳密な候補が除外される可能性があります。埋め込みテキストは、抽出に使用されたものと同じ制限されたソーススナップショットから取得されます。安定した入力と固定スコアは、タイを含む決定論的な順序を生成します;モデルの応答自体は外部入力です。

internal/emitter/calibration_test.go は、70%の閾値で小さなラベル付きソースフィクスチャを評価し、類似度スコアとは別に、真陽性、偽陽性、偽陰性、精度、および再現率を報告します。このフィクスチャには、1つの厳密なペア、2つの近似クローンペア、および3つの無関係なペアがあり、500シンボルの境界以下および以上で実行されます。これは回帰チェックであり、現実世界の精度の代表的な推定ではありません。より大規模な多言語キャリブレーションおよびパフォーマンス予算は、ロードマップの作業です。