コンテンツにスキップ

fingerprint コマンド

codeknit fingerprint は、すべての関数、メソッド、変数、および型の正規化された本文トークンに対してContext-Triggered Piecewise Hash(CTPH)を計算します。変数名、文字列リテラル、および型注釈はハッシュ化前に正規化されます。そのため、名前を変更したコピー&ペーストや他の言語への移植でも一致することがあります。

このガイドでは、重複の検出方法、類似度の範囲の調整方法、偽陽性の削減方法、およびリファクタリングの対象決定方法について説明します。

  • codeknit がインストールされていること。インストールを参照してください。
  • ./src など、スキャンするソースディレクトリがあること。

プロジェクト内の重複を検出する

Section titled “プロジェクト内の重複を検出する”

チェックしたいディレクトリでコマンドを実行します:

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

このコマンドは ./skeleton/fingerprints.skt を書き出し、類似度が65%から95%のペアを報告します。

ファイルを開きます。[duplicates] セクションは常に存在し、最も強い一致が最初に表示されます:

[duplicates]
# similarity range: 65%-95%
similarity:93% pkg/user.go::GetUser <-> pkg/admin.go::GetAdmin
similarity:88% src/auth.ts::validateToken <-> src/session.ts::validateSession
similarity:81% lib/math.py::compute_tax <-> lib/math.py::compute_vat

各行は similarity:<N>% <file>::<symbol> <-> <file>::<symbol> の形式です。範囲内に該当するものがない場合、セクションには # no duplicates found のみが含まれます。

完全な出力文法については、出力形式リファレンスを参照してください。

デフォルトの範囲は95%までなので、100%の一致は除外されます。厳密な一致をリストするには、両方の境界を100に設定します:

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

「厳密」とは、同じシンボルカテゴリ内で完全に正規化されたトークンストリームが同一であることを意味します。ソーステキストが同一であることや、2つのシンボルが同等であることが証明されるわけではありません。

範囲を広げて緩やかな一致を検出する

Section titled “範囲を広げて緩やかな一致を検出する”

最小値を下げて、詳細が異なるがアルゴリズムの形状を共有するコードを含めます:

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

50%未満の結果は通常ノイズです。

セマンティックリランクで偽陽性を削減する

Section titled “セマンティックリランクで偽陽性を削減する”

構造的な結果がノイズの場合、ローカルのOllamaサーバーからの埋め込みで候補をリランクします。

  1. Ollamaを起動し、デフォルトの埋め込みモデルをプルします:

    ターミナルウィンドウ
    ollama serve
    ollama pull qwen3-embedding:0.6b
  2. --rerank フラグを付けてコマンドを実行します:

    ターミナルウィンドウ
    codeknit fingerprint ./src --rerank

別の埋め込みモデルを使用するには、--model を渡します:

ターミナルウィンドウ
codeknit fingerprint ./src --rerank --model qwen3-embedding:4b

リランクはセマンティック候補を追加し、結合スコアでフィルタリングします。偽陽性を削減しますが、すべてを除去するわけではありません。また、構造的に厳密な候補を除外することもあり、類似度の範囲は依然として適用されます。埋め込みは、抽出に使用された同じ解析済みソーススナップショットから計算されます。

生のフィンガープリントを検査する

Section titled “生のフィンガープリントを検査する”

すべてのシンボルのフィンガープリントを確認するには、--show-all を追加します:

ターミナルウィンドウ
codeknit fingerprint ./src --show-all

これにより、[fingerprints] セクションが追加され、ソースファイルごとにグループ化され、シンボルごとに1行表示されます:

[fingerprints]
## src/auth.ts
validateToken FP:3:a1b2c3...:d4e5f6... tokens:8e0f1a2b...

行の形式は <symbol-name> FP:<blocksize>:<hash1>:<hash2> tokens:<hex> です。tokens は正規化されたトークンストリームの16進エンコードです。

レポートを別の場所に書き出す

Section titled “レポートを別の場所に書き出す”
ターミナルウィンドウ
codeknit fingerprint ./src -o duplicates.skt

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

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

テストファイルはデフォルトでスキップされます。--collect-test で含めます:

ターミナルウィンドウ
codeknit fingerprint ./src --collect-test

スキャンを絞り込むには、ソース選択フラグを使用します。シェルがパターンを展開しないように引用符で囲みます:

ターミナルウィンドウ
codeknit fingerprint ./src --include '**/*.ts' --exclude '**/generated/'

その他の選択制御:

  • --max-file-size BYTES は大きなファイルをスキップします。デフォルトは 10485760(10 MiB)です。0 で制限を無効にします。
  • --strict は、スキャンまたは解析が不完全な場合に出力を書き出す前に失敗します。
  • --header-language c|cpp は、曖昧な .h ファイルのパーサーを選択します。言語サポートを参照してください。

スキップされたシンボリックリンク、サイズ超過のファイル、および構文警告はstderrに表示されます。.gitignore やテストフィルタリングを上書きすることはなく、除外は包含より優先されます。正確な保証については、解析信頼性リファレンスを参照してください。

範囲 通常検出されるもの
96-100% 厳密またはほぼ厳密な構造的重複;明らかなコピー&ペースト
85-95% 近似重複;通常は些細な編集があるコピー&ペースト
65-84% デフォルトの範囲;強い構造的類似度、多くはリファクタリング候補
50-64% 詳細が異なるが同じアルゴリズムの形状
50%未満 通常はノイズ

上位2行を確認するには、--max-similarity を 100 に上げます。

リファクタリングの対象を決定する

Section titled “リファクタリングの対象を決定する”
  1. デフォルトの範囲から始め、上位のペアを読みます。
  2. 各ペアの両方のシンボルを開き、比較します。
  3. 一致はシグナルであり、証明ではないと考えます。フィンガープリントは構造的な形状を測定し、識別子名や意図は考慮しません。同じロジックを反復的および再帰的に書いたものはスコアが低く、同じ形状の無関係なコードはスコアが高くなることがあります。
  4. 85–95%の範囲のペアは、通常、統合する最も安全な候補です。65–84%の範囲のペアは、より詳細な検討が必要なことが多いです。
  5. リストがノイズの場合、範囲を絞るか --rerank を追加します。

言語間の一致は同等の構造に対して機能します。言語固有の機能は、偽の低類似度の一致を生むことがあります。

類似度のパーセンテージはヒューリスティックなランキングであり、編集距離ではありません。プロジェクトのラベル付きキャリブレーションフィクスチャは、類似度スコアとは別に精度と再現率を報告します。これは回帰チェックであり、コードに対する精度の推定ではありません。

  • 対象シンボルが500未満の場合、codeknit は同じカテゴリのすべてのペアをスコアリングします。
  • 500以上の場合、完全に厳密な正規化トークングループは常に保持されます。その他のペアは、シンボルごとに近似トップ50の近傍を使用するため、近似重複の結果は不完全になることがあります。
  • 厳密な重複については、上記の100/100コマンドを使用します。これは近似の影響を受けません。
  • 入力とスコアが安定している場合、順序は決定論的です。
症状 原因と対策
# no duplicates found 範囲内にペアがない。--min-similarity を下げるか --max-similarity を上げる。
既知の短い関数が見つからない 正規化されたトークンが4未満のシンボルはスキップされます。
厳密なコピーが見つからない デフォルトの最大値は95%です。--min-similarity 100 --max-similarity 100 を使用します。--rerank を使用すると、セマンティックフィルタによって除外されることもあります。
--rerank が失敗する ollama serve が実行中で、モデルがプルされていることを確認します。
stderrに警告とともに部分的な結果 報告されたファイルを修正するか、--strict を追加して不完全な出力の公開を防ぎます。
フラグ デフォルト 説明
-o, --output ./skeleton/fingerprints.skt 出力 .skt ファイルのパス。
--min-similarity 65 報告する最小類似度(0–100)。
--max-similarity 95 報告する最大類似度(0–100)。
--show-all false 生のトークンデータを含む [fingerprints] セクションも出力します。
--rerank false Ollamaを介してセマンティック埋め込みで候補をリランクします。ollama serve と ollama pull qwen3-embedding:0.6b が必要です。
--model qwen3-embedding:0.6b --rerank とともに使用するOllama埋め込みモデル。
--collect-test false 解析にテストファイルを含めます。
--workers NumCPU 最大同時解析ゴルーチン数。
--verbose false 進捗情報を表示します。

--include、--exclude、--max-file-size、--strict、--header-language など、完全なリストについては、CLIフラグリファレンスを参照してください。