HN 日本語サマリー

← 一覧へ戻る
プログラミング

Show HN: 埋め込みモデルで非厳密なコード重複を検出するCLIツール

Show HN: CLI tool for detecting non-exact code duplication with embedding models (github.com)

61 pointsby rkochanowski28 コメント

要約

Rafal-qa氏が開発した「Slopo」は、埋め込みモデルを使用してコードの非厳密な重複を検出する軽量なCLIツールです。特に、コードベースの離れた場所にあり、検出が困難で有害な類似コードに焦点を当てています。Python、TypeScript、Javaなど複数の言語をサポートし、コードの類似性をランク付けしてレポートを生成します。

全文翻訳

Slopo

[画像: Slopoのロゴ]

埋め込みモデルは通常、異なる言葉で書かれていても意味が似ているテキストを見つけるために使用されます。一部のモデルは、ソースコードに対しても同様のことを行うことができます。Slopoは、この技術を使用して検出が最も困難なコード重複を見つけるCLIツールです。

これらのAIモデルが何を検出し、どこに弱点があり、どれが最も効果的かを知るには、Embedding models benchmark for code duplication detection を参照してください。これはこのツールの作者によって書かれたもので、このドキュメントのサンプル設定は、この調査に基づいた最良の結果をもたらすものです。

何ができるか
  • 最近のGit変更とコードベースの他の部分との間で類似したコードを見つける。
  • コードベース全体を分析して類似したコードを見つける。
サポートされている言語

Python, TypeScript, TSX, JavaScript, Java, Kotlin, C, C++, C#, Go, Rust, PHP, Elixir, Ruby, Swift

解決する問題

エージェントは、参照、類似した名前などによって見つかった関連コードを含め、現在作業しているコードベースの一部しか見ることができません。通常、特に小規模なプロジェクトや良好なアーキテクチャの場合、彼らは作業中のものに関連する既存の実装に気づくことができます。

時折、特に大規模なプロジェクトや悪いアーキテクチャの場合、どこかに既に存在するソリューションを見逃し、それを再度実装してしまうことがあります。これはコピー&ペーストではなく、同じ問題に対する類似した実装であり、人間、AI、他のツールにとっては検出が困難です。Slopoは、コードベースのサイズや保守状態に関わらず、コードベース全体で類似したコードを見ることができるようにすることで、この盲点をターゲットにします。

問題は規模とともに増大します。

  1. 小さな変更を確認する際、エージェントは集中した分析を行い、類似した実装を見つけることができます。
  2. 雑然としたコードベースで大規模な変更を行う場合、レビューは信頼性が低下し、コストが増大します。
  3. コードベース全体を分析して類似コードのクラスターを特定することは、エージェントのタスクではありません。

Slopoは2と3を解決します。

追加のメリット

すべてのコード重複が検出困難なものではなく、コーディングエージェントはそれらの多くを検出できます。それでも、Slopoは役立つ場合があります。

AIコストの削減
  • 埋め込みモデルへのAPIアクセスは、AIエージェントで使用されるモデルと比較して、実質的に無料です。
  • エージェントが重複検出済みのレポートを受け取ると、それ自体でトークンを費やす必要がなくなります。

ワークフローの一部をより安価なソリューションに移行すれば、総コストとトークン使用量は削減されるはずです。

精度の向上

コーディングエージェントは、明確に定義された単一のタスクに取り組むときに最も効果を発揮します。Slopoが提供する、集中した指示付きの類似コードクラスターを含むレポートは、まさにそのケースです。エージェントは、コンテキストに適切なデータのみをロードし、注意散漫や誤った方向への逸脱、または重要なことを見落とす可能性を最小限に抑えます。

エージェント統合 - デモ

SlopoはAIコーディングエージェントによって操作でき、エージェントは結果を報告するだけでなく、それらをどうするかについて指示されます。エージェントは、アクション不能な類似性を迅速に破棄するのに役立ち、状況に応じた詳細レベルを提供します。

以下のビデオは、新しい実装が既存の実装と類似している、コミットされていない変更のレビューを示しています。

仕組み

埋め込み(embedding)とは、テキストの意味を表すベクトルです。意味が似ているテキストは、その埋め込みが互いに近くなります。2つのコードスニペットの埋め込みが近い場合、ツールはそれらを類似しているとみなし、したがって、たとえ異なる方法で書かれていても、潜在的な重複とみなします。

非厳密なコード重複の検出に加えて、Slopoはコードベースの遠く離れた場所にあるコード、しばしば異なるモジュールに分散していたり、大きなファイル内に分離されていたりするコードに焦点を当てています。コードが離れているほど、その優先度は高くなります。

結果は、類似性とコードベース内の距離でランク付けされた類似コードのクラスターです。これらは、クラスターが実際の重複であるかどうかを確認できるAIコーディングエージェントの入力として意図されています。

実際のレポート

Example reports from real projects ページには、選択されたオープンソースプロジェクトからの分析結果と説明が含まれています。

これらのプロジェクトを自分で分析して、ツールとその機能に慣れることができます。

埋め込みモデルへのアクセス

ベンチマークによると、2つのAPIプロバイダーが推奨されています。

  1. Jina AI - API経由で利用可能で、ローカルでも使用できるコード特化型モデル
  2. Voyage AI - 一般用途モデルのみ、コード特化型モデルはここでは適していません

Jina AIは、非商用利用のために登録なしで無料トークン付きのAPIキーを提供しています。商用利用の場合は有料オプションがあります。メインページを開くだけで、トークンが生成されます。「You have 10,000,000 tokens left in the API key below.」と表示されるはずです。ただし、無料トークンが常に付与されるわけではありません。これは、IPアドレスまたはその他の対策に基づく不正使用防止メカニズムによるもの(推測であり、公式情報ではありません)である可能性があります。

JinaのAPIは、サーバーがオフラインで起動する必要がある場合があるため、最初の要求が遅延することがあります。後続の要求はより速くなります。

ローカルモデル

テストされたソリューションの1つは、jina-embeddings-v2-base-code を使用した Ollama です。これはCPUでも実行できる小さなモデルですが、使用するハードウェアによってはAPIよりも(大幅に)遅くなる可能性があります。モデルはこちらからプルしてください。

その他のモデル

LiteLLM でサポートされている任意のモデルプロバイダーを設定できます。さらに、OpenAI互換のサーバーもサポートされています。

クイックスタート

モデルを決定したら、残りは迅速です。

インストール
uv tool install slopo

最新バージョンに更新(自動更新や通知はありません)

uv tool upgrade slopo

このコマンドは、Pythonパッケージマネージャーである uv(uvのインストール)を使用して、SlopoをPyPIから分離された仮想環境にインストールします。Pythonを別途取得する必要はありません。

セットアップ

slopo init を実行して、さらに指示を含む設定ファイルテンプレートを作成します。分析対象のコードディレクトリと埋め込みモデルの設定のみが必要です。

モデル設定

注意:提案されている以上の埋め込み次元を使用しないでください。結果は改善されず、ツールのパフォーマンスが低下するだけです。

Jina AI
embedding_model: jina_ai/jina-code-embeddings-0.5b
embedding_dimensions: 256
embedding_params:
  task: code2code.query

無料APIキーで大規模プロジェクトを埋め込み中にレート制限に達した場合、embedding_request_delay: 6 オプションを追加して速度を落としてください。

Voyage AI
embedding_model: voyage/voyage-4-large
embedding_dimensions: 256
ローカルモデル
embedding_model: ollama/unclemusclez/jina-embeddings-v2-base-code
embedding_dimensions: 768
実行

slopo show-config を実行して設定を検証し、すべての設定可能なパラメータを表示します。ほとんどは適切なデフォルト値を持っています。

これで、コードをインデックス化し、埋め込みを計算する準備ができました。

slopo index
slopo embed

レポートを生成するには、インデックス化されたコードベース全体に対して slopo analyze を実行するか、Git変更に対して slopo review を実行します。

Slopoの実行 - まとめ

手動CLIコーディングエージェント
Git変更のレビューslopo index + embed + reviewslopo-review スキル
コードベース全体の分析slopo index + embed + analyzeslopo-analyze-ignore および slopo-analyze-one スキル
出力手動レビュー用のクラスター、スコア、コードスニペットを含むMarkdownレポートエージェントが受信するコンパクトなレポート、ユーザーと議論される結果

手動CLI

コードが変更されたら、index と embed を実行してデータを同期してからレポートを取得してください。

プロジェクト全体の分析

slopo analyze は、インデックス化されたコードベース全体にわたるコードのレポートを生成します。

各クラスターにはハッシュがあり、分析中にそれらを破棄するために slopo.ignore.txt に追加できます。

最近の変更のレビュー

slopo review は、Git変更が関与するコードのレポートを生成します。

  • デフォルトの HEAD ベースは --base オプションで設定できます。例えば slopo review --base HEAD~1 です。
  • 未追跡ファイルは、インデックス化されている限り含まれます。
  • 変更されたファイル間、および変更された部分と変更されていない部分の間で類似したコードをターゲットにします。
  • この機能には git のインストールが必要であり、source_dir はGitリポジトリである必要があります。

コーディングエージェントとの統合

Claude CodeおよびCodex用のスキルで統合が行われています - src/slopo/agent/configs

スキルインストール

slopo agent-configs を実行して、Claude CodeおよびCodex用のスキルを含む新しいディレクトリに設定をエクスポートします。

それらを目的の場所にある skill ディレクトリにコピーします。これらは次のいずれかにコピーできます。

  • プロジェクトレベルの設定(プロジェクトディレクトリ内):
slopo-agent-configs/claude-code-skills -> .claude/skills
slopo-agent-configs/codex-skills -> .agents/skills
  • ホームディレクトリまたはその他の場所:使用しているコーディングツールのドキュメントに従ってください。
Slopoの初期化

エージェントはSlopo CLIをバックグラウンドで実行するため、設定、インデックス化、埋め込みが行われている必要があります。まずそれが機能することを確認してください。

エージェントは専用のコマンドを使用し、Markdownレポートを読み取りません。初期化後は、エージェントのみで実行でき、毎回 index/embed する必要はありません。

Slopo設定ファイルの場所

デフォルトでは、slopo コマンドは現在のディレクトリにある slopo.conf.yaml から設定を読み取ります。典型的なセットアップでは、それがプロジェクトのルートディレクトリに存在し、コーディングエージェントもルートディレクトリから実行されることを想定しています。そうでない場合、「Error: Configuration file not found.」というエラーが発生します。

カスタムファイル場所がある場合は、スキルによって呼び出されるコマンドに slopo --config=... オプションを追加できます。

コーディングエージェントとの使用

スキルはユーザーのみが実行するように設定されており、エージェント自体が呼び出すことはできません。例えば、slopo-review スキルはClaude Codeでは /slopo-review、Codexでは $slopo-review で実行されます。

エージェントはコンパクトな形式のレポートと詳細のないエラーのみを確認します。それ以外のすべては slopo.agent.log にログ記録されます。このログには、コマンドを手動で使用したときに表示されるのと同じメッセージと詳細なエラーが含まれています。

Git変更のレビュー

使用法:slopo-review [base]

[base] は、レポートに含める変更のオプションのGitベースです。デフォルトは HEAD(コミットされていない変更)です。

Slopoによって報告された重複がアクション可能か、単なるノイズかを確認します。確認する価値がある場合、重複が何であるか、およびそれが引き起こす問題の簡単な概要を提供します。開発者が興味を持った場合、エージェントは次に何をすべきかを決定するための情報を提供して、さらに詳細な分析を実行します。

コードベース全体の非重複フィルタリング

使用法:slopo-analyze-ignore

コードベース全体にわたるすべての報告された類似コードの浅いチェックです。明らかに実際の重複ではなくノイズである類似コードをフィルタリングします。無視されたコードは無視ファイルに追加されます。すべての作業は開発者の入力なしで行われます。

コードベース全体の1つの重複レビュー

使用法:slopo-analyze-one [cluster hash]

[cluster hash] は、analyze コマンドで生成されたMarkdownレポートで見つけることができるオプションのハッシュです。デフォルトでは、最も高いスコアを持つ、レビューされていない最初の類似コードクラスターを選択します。

1つのクラスターを分析し、開発者が次に何をすべきか(無視、後でメモ、または今すぐリファクタリング)を決定するのをガイドします。

ワークフロー:まず slopo-analyze-ignore でノイズをフィルタリングし、次に slopo-analyze-one で残りをレビューします。

設定

slopo --help および slopo show-config を実行して、いつでも自分で探索できます。

ほとんどの設定は設定ファイルで行われますが、2つの例外があります。

  1. 設定ファイルの場所は --config オプションで上書きできます。
  2. APIキーは、現在のディレクトリにある .env ファイルからも読み取られる SLOPO_EMBEDDING_API_KEY 環境変数で設定できます。

一部のパラメータは、最初のインデックス作成後に変更できないことに注意してください。 slopo.db を削除し、最初からインデックス作成/埋め込みを行う必要があります:source_dir、embedding_model、embedding_dimensions、body_node_count_threshold、block_node_count_threshold。

すべての設定可能パラメータ
  • source_dir: インデックス化するコードを含むソースディレクトリ。絶対パスまたは相対パス。
  • source_dir_exclude: インデックス化から除外する.gitignoreスタイルのパターン。Gitと同じ方法で一致します。例:
source_dir_exclude:
  - "test/"
  - "*.test.ts"
  • include_file_extensions: オプションで含めるファイルタイプのリスト。設定されていない場合、サポートされているすべてのファイルが含まれます。source_dir_exclude による除外が優先されます。例:
include_file_extensions:
  - .ts
  - .py
  • db_file: ツールデータを含むSQLiteデータベースファイル。
  • report_dir: 分析レポートの出力ディレクトリ。
  • ignore_file: 無視されたクラスターを含むテキストファイル。
  • agent_log_file: コーディングエージェントによって実行されたコマンドのログファイル。
  • embedding_model: LiteLLM形式の埋め込みモデル名。
  • embedding_dimensions: 使用されるモデルと互換性のある埋め込み次元。この値は、受信した埋め込み次元を検証するためにも使用されます。
  • embedding_api_key: 埋め込みプロバイダーのAPIキー。または環境変数で設定します。ローカルモデルの場合はオプションで、設定する必要はありません。
  • embedding_params: LiteLLMおよび埋め込みAPIに渡される追加のプロパティ。APIプロバイダーがサポートするものはすべて有効です。例:
embedding_params:
  api_base: http://example.com:123
  task: code2code.query
  • embedding_batch_size および embedding_batch_chars: 埋め込みAPIへのリクエストはパフォーマンスのためにバッチ処理されます。ほとんどの場合、デフォルトで問題ありません。
  • embedding_request_delay: 各バッチリクエスト後の遅延(秒)。デフォルトでは遅延なし。レート制限に達した場合は増やしてください。
  • analyze_similarity_threshold および review_similarity_threshold: 埋め込み間の最小コサイン類似度を制御します。
  • analyze_rerank_threshold および review_rerank_threshold: コードベース内の距離を反映したブーストを適用した後の最小類似度を制御します。
  • body_node_count_threshold および block_node_count_threshold: 関数本体またはコードブロック内のASTノードの最小数。

コードの単位への分割方法

コード単位とは、埋め込みを使用して他の単位と比較される、抽出されたコード片です。ソースコードをチャンク化する方法は、結果に大きな影響を与えます。

コード単位は2つのグループに分けられます。

  1. 言語に依存する関数ライクな構造:関数、メソッド、無名関数、クロージャなど。これは、ある構造に含まれるコード片です。「function」と呼ばれます。
  2. 条件分岐、ループ、例外処理などの構造内のコードブロック。これは関数または他のブロックの一部であり、制御フロー構文で囲まれています。「block」と呼ばれます。

ターゲット言語のテストをtests/indexing/parsing/langで確認すると、どのような構造が抽出されるかを確認できます。fixtures ディレクトリには、テストと比較できるサンプルコードが含まれています。

コード単位は自然に重複し、深い構造も含まれ、すべてのレベルが含まれます。それらは、最も一致するバリアントのみを保持することによって重複排除されます。

関数シグネチャとブロックヘッダーは、比較される部分から除外されます。これらは「context」と呼ばれ、読みやすさのためにMarkdownレポートにのみ含まれます。

すべてのコメントは削除されます。

小さすぎるコード単位はスキップされます。これは *_node_count_threshold オプションで制御されます。デフォルトでは、block は function よりもはるかに高いしきい値を持っています。ASTノードが実際のコードにどのようにマッピングされるかのアイデアを得るには、テストの body_node_count を確認してください。

ポータビリティ

analyze で生成されたレポートのハッシュは、プラットフォーム間で安定するように意図されており、slopo.ignore.txt はGitにコミットされ、チーム全体で使用されることを目的としています。ハッシュは、クラスター内のコード単位が変更されたり、移動されたりすると変更されることに注意してください。

source_dir をプロジェクトルートからの相対パスで指定した slopo.conf.yaml はコミットでき、チーム全体で使用できます。

クラスター内のコード単位の順序はプラットフォーム間で異なる場合がありますが、結果は同じであるはずであり、レポートはコミットを意図していません。埋め込みモデルは毎回まったく同じ浮動小数点数を返さないため、結果がわずかに異なるエッジケースが発生する可能性があります。

ツールのデータベース slopo.db は各開発者にローカルであり、ポータブルではありません。

ランキングしきい値

analyze と review は別々のしきい値を持っています。デフォルトでは、

  • analyze は、あまりにも多くのクラスターを報告するのを避けるために、わずかに高いです。
  • review は、レポートが小さく、より焦点を絞っているため、わずかに低いです。

類似コード単位は2つのパスでフィルタリングされ、それぞれ独自の構成可能なしきい値があります。パイプラインは次のとおりです。

  1. *_similarity_threshold は、埋め込みが十分に類似していないコード単位ペアをフィルタリングします。計算された値は、-1 から 1 の範囲のコサイン類似度であり、1 は同一を意味します。
  2. 類似したペアはクラスターにグループ化されます。
  3. クラスター内の単位は、距離のブーストを適用した後に再ランク付けされます。ブーストは、ペアのもう一方のファイルに到達するために必要なディレクトリホップ数(最大15%)に基づいて計算されます。それらが同じファイル内にある場合、ブーストは行数(最大10%)に基づいて計算されます。*_rerank_threshold は、最もスコアの高いペアが十分に高くないクラスターをフィルタリングします。

適切なツールか?

このツールは、技術的な決定を下すことができる少なくとも最小限の経験を持つ開発者を対象としています。これは魔法のようなコード修正ツールではありません。

Slopoは1つの狭い問題を解決することを目指しています。他のツールが見逃す重複コード、つまり異なる方法で実装された類似のロジックを検出することに焦点を当てています。これには独自のトレードオフがあります。

  • 埋め込みモデルとの作業は、使用の複雑さを増します。
  • 重複ではない、非常に類似したコードを報告する可能性があります。

当然、厳密なコピーやわずかに変更されたクローンも検出できます。もしこれだけが必要な場合は、それらのツールの方が適しています。それらは決定的であり、高速であり、より成熟しており、埋め込みモデルを含む一連の作業を必要としません。

すべてのプロジェクトがSlopoから同等に恩恵を受けるわけではありません。より大規模な、または保守状態の悪いプロジェクトはより多くの恩恵を受けるかもしれませんが、他のプロジェクトがそうでないという意味ではありません。

貢献

プルリクエストは受け付けられず、このリポジトリでは無効になっています。

フィードバックや、アイデア、ユースケース、ワークフロー、問題点に関する人間同士の議論など、その他の貢献は歓迎されます。