Fingerprint コマンド

codeknit fingerprint コマンドは、Context-Triggered Piecewise Hashing (CTPH) を使用して、コードベース全体の重複および近似重複コードを検出します。変数名、文字列リテラル、型注釈を正規化して構造的なフィンガープリントを計算することで、ファイル間やプログラミング言語間でも機能します。

機能

codeknit fingerprint は、コードベース内のすべての関数、メソッド、変数、および型を分析し、以下に基づいて正規化された構造的フィンガープリントを計算します：

• 制御フロー（if、for、while、switch）
• 演算（=、+、==、&&、||）
• 呼び出し、戻り値、代入、オブジェクト生成
• try/catch、yield、await、defer などの言語構文

この正規化により、名前変更されたコピー＆ペースト、些細なリファクタリング、および異なる言語での同等のロジックでも、重複として検出できます。

このアルゴリズムは、CTPH（ローリングハッシュの一種）を使用して、近似重複を効率的に検出します。類似したコードは類似したフィンガープリントを生成し、コードがわずかに変更されていてもファジーマッチングが可能です。

基本的な使用方法

codeknit fingerprint ./src

このコマンドは以下を行います：

• ./src 内のすべてのソースファイルを解析
• 構造的フィンガープリントを計算
• 結果を ./skeleton/fingerprints.skt に出力
• 65% から 95% の類似度のマッチを報告（デフォルト範囲）

フラグ

フラグ	デフォルト	説明
-o, --output	./skeleton/fingerprints.skt	出力 .skt ファイルパス
--min-similarity	65	報告する最小類似度（0–100）
--max-similarity	95	報告する最大類似度（0–100）
--show-all	false	生のトークンデータを含む [fingerprints] セクションを含める
--rerank	false	セマンティックエンベディングを使用して CTPH 候補を再ランク付けし、誤検出を排除（要件：ollama serve および ollama pull qwen3-embedding:0.6b）
--model	qwen3-embedding:0.6b	--rerank で使用する Ollama エンベディングモデル
--collect-test	false	テストファイルを分析に含める
--workers	NumCPU	最大同時解析ゴルーチン数（0 = すべての CPU コアを使用）
--verbose	false	処理中の進捗情報を表示

出力形式

出力は .skt ファイルで、以下のセクションを含みます：

[duplicates]（常に存在）

しきい値以上の類似度を持つシンボルのペアをリストします：

[duplicates]
similarity:96%  pkg/user.go::GetUser <-> pkg/admin.go::GetAdmin
similarity:88%  utils/str.go::TrimSpaces <-> lib/text.go::CleanString

各行には以下が表示されます：

• 類似度
• 左シンボル（ファイルパス、スコープ、名前）
• 右シンボル（ファイルパス、スコープ、名前）

[fingerprints]（--show-all 時のみ）

各シンボルの生のフィンガープリントデータを含みます：

[fingerprints]
validateToken  FP:3:a1b2c3...:d4e5f6...  tokens:8e0f1a2b...

フィールド：

• シンボル名
• FP:<version>:<hash1>:<hash2> — CTPH フィンガープリント
• tokens:<hex> — 正規化された本文トークンストリーム

このセクションは、デバッグや下流ツールの構築に役立ちます。

一般的なパターン

# デフォルトスキャン
codeknit fingerprint ./src

# 厳密な重複のみを検出
codeknit fingerprint ./src --min-similarity 100

# 中程度の類似コードを検出（例：同じアルゴリズム、異なる名前）
codeknit fingerprint ./src --min-similarity 50 --max-similarity 80

# セマンティック再ランク付けを使用して誤検出を減らす
# 要件：ollama serve && ollama pull qwen3-embedding:0.6b
codeknit fingerprint ./src --rerank

# 再ランク付けに異なるエンベディングモデルを使用
codeknit fingerprint ./src --rerank --model qwen3-embedding:4b

# 完全なフィンガープリントリストを出力（分析ツール用）
codeknit fingerprint ./src --show-all

# カスタム出力ファイル
codeknit fingerprint ./src -o duplicates.skt

類似度範囲の選択

範囲	ガイダンス
96–100%	厳密またはほぼ厳密な構造的重複。ほぼ確実にコピー＆ペースト。
85–95%	近似重複。通常はコピー＆ペーストに小さな編集を加えたもの（例：変数名の変更、ログの追加）。
65–84%	デフォルト範囲。強い構造的類似度。リファクタリングの良い候補。
50–64%	中程度の類似度。同じアルゴリズムの形状だが、詳細は異なる。手動で確認が必要。
< 50%	通常はノイズ。意味のある重複ではない。

ヒント

• フィンガープリントは構造を測定し、意味を測定しない：高い類似度スコアはコードが「似ている」ことを意味し、「同じことを行う」ことを意味するわけではありません。常に両方のシンボルを確認してください。
• --rerank を使用してノイズを減らす：多くの誤検出が出る場合は、セマンティック再ランク付けを有効にして、エンベディングを使用してマッチをフィルタリングします。
• 短い本文はスキップされる：4 つ未満の正規化トークンを持つシンボル（例：単純なゲッター）はノイズを避けるために無視されます。
• クロス言語マッチングが可能：同等の構造（例：Python 関数と同じロジックを持つ Go 関数）はマッチする可能性がありますが、言語固有のパターンは誤った低類似度マッチを生成することがあります。
• マッチはシグナルであり、判定ではない：各マッチを調査のきっかけとして扱い、自動的な重複の証拠とはしないでください。