fallow similar-code

  • fallow
  • TypeScript
  • 静的解析

fallow dupes は、コピーされた後に名前が変更されたコードを検出する。あるファイルには for ループ、別のファイルには reduce があるといった、異なるスタイルで記述された同一の計算は検出されない。fallow similar-code がその隙間を埋めている。各関数をローカル埋め込みモデルでベクトルに変換し、ベクトルが近接しているペアを列挙する1。fallowの記事では、その他のコマンドについて解説している。

dupesが見落とすもの

テストプロジェクトには、カートの合計を計算する関数が3つある。orderTotal は cartTotal の変数名を変更したものである。invoiceAmount は reduce で同じ値を計算する。

export function cartTotal(items: readonly Item[]): number {
  let total = 0;
  for (const item of items) {
    total += item.price * item.quantity;
  }
  return total;
}

export function orderTotal(entries: readonly Item[]): number {
  let sum = 0;
  for (const entry of entries) {
    sum += entry.price * entry.quantity;
  }
  return sum;
}

export const invoiceAmount = (lines: readonly Item[]): number =>
  lines.reduce((sum, line) => sum + line.quantity * line.price, 0);

fallow 3.43.1 では、結果は以下の通りだった。小さな関数がマッチするように、--min-tokens 20 --min-lines 3 を指定してdupesを実行した。

ペアdupes --mode milddupes --mode semanticsimilar-code スコア
cartTotal と orderTotal見つからない見つかった0.83
orderTotal と invoiceAmount見つからない見つからない0.76
cartTotal と invoiceAmount見つからない見つからない0.72

dupesのデフォルトモードでは、名前を残したままトークン列を比較するため、名前を変更するだけでコピーは非表示になる。セマンティックモードは名前やリテラルを置き換えるため、名称変更されたコピーを検出する。トークンの順序が異なるため、どちらのモードでも reduce のバージョンが見つからない。similar-code のみがそのペアにスコアを付与する。

スコアは判定ではない

similar-code のデフォルトの閾値は 0.8 なので、デフォルト設定では reduce ペアは表示されない。上記の結果は --threshold 0.5 の場合である。候補リストの前に、コマンドは「モデルスコアはコサイン類似度であり、確率やリファクタリング判定ではない」と出力し、各候補を未検証としてラベル付けする。ドキュメントでは、作業分担について「固定されたローカルモデルがそれらを見つけ、人間が判断する」と一行で説明されている1。

モデルは Apache-2.0 ライセンスの jinaai/jina-embeddings-v2-base-code で、1 つのリビジョンに固定されている。明示的な同意を得て一度だけダウンロードするセットアップの後、解析はオフラインで実行され、ソースコードはマシンの外に出ない1。モデルファイルはユーザーキャッシュで310 MBを占めた。

判定は別文書に記載すること

判断には3つのステップがある。まず、fallow similar-code inspect <candidate_id> --candidates similar-code.json で、両方の関数のソースコードが表示される。出力は「Decide candidate_worthy, behaviorally_equivalent, and refactor_safe separately」という言葉で締めくくられている。

src/invoice.ts:3  invoiceAmount
(lines: readonly Item[]): number =>
  lines.reduce(
    (sum, line) => sum + line.quantity * line.price,
    0,
  )

src/cart.ts:6  cartTotal
function cartTotal(items: readonly Item[]): number {
  let total = 0;
  for (const item of items) {
    total += item.price * item.quantity;
  }
  return total;
}

判定結果は候補リストではなく、別のJSONドキュメントに記載されている。各判定には3つの独立した軸と結果がある。refactor_safe: true には behaviorally_equivalent: true が必要であり、さらにそれには candidate_worthy: true が必要となる2。結果は、same-responsibility、related-but-distinct、intentional-duplication、unrelated、および needs-human-review のいずれかとなる。意図的な重複は想定される回答の1つだ。

{
  "schema_version": "1",
  "verdicts": [
    {
      "candidate_id": "similar-code:candidate:v1:ba7f6fe4…",
      "review_key": "similar-code:review:v1:…",
      "candidate_worthy": true,
      "behaviorally_equivalent": true,
      "refactor_safe": true,
      "outcome": "same-responsibility",
      "rationale": "Both multiply price by quantity and sum the lines."
    }
  ]
}

fallow similar-code review は、いずれのファイルも変更することなく、候補と判定結果を結合する。3つの候補のうち2つに判定がある場合、3つ目は needs-human-review と報告される。--require-verdict-for-each-candidate を付けると、"a verdict is required for every candidate" と出して失敗する。

src/invoice.ts:3 invoiceAmount
  <-> src/cart.ts:6 cartTotal
  Match: unverified
  Outcome: needs-human-review
  Rationale: no safely matched verdict

Reviewed: 3 candidates, 2 matched verdicts, 1 unmatched candidate

変更のないコードで再度ディスカバリを実行したところ、候補の candidate_id と review_key は変わらなかった。つまり、リポジトリに保存された判定ファイルは、次回の実行時に同一のペアを判定し、判定なしの候補として現れるのは新規または変更されたペアのみとなる。

ビルドを停止するチェックからは除外される

fallowは、引数なしの解析、auditの合否判定、SARIF、エディタの診断機能、および自動修正からsimilar-codeを除外している3。その終了コードは候補に対して失敗しない。この設計は上記の判定リストに合致している。スコア0.83は、忘れられたコピーか、あるいは個別に変更すべき2つの関数のいずれかであり、両方を読まなければどちらであるか判別できない。similar-codeは、候補を読み込み判定を記録する通常のレビューに適しており、dupesはビルドを失敗させるチェックとして残っている。

モノレポ上の数値

2,643ファイル、約18万行からなるTypeScriptのモノレポで、4コアのLinuxコンテナにおいて、similar-codeは1,414個の関数をベクトルに変換した。1回目の実行は4分18秒、2回目はベクトルキャッシュ付きで2秒かかった。デフォルトの閾値では、65件の候補が返された。実行は1,000,000回の比較という制限で停止し、約2,770万組をスキップしたため、「部分的」とマークされた。最後まで実行して初めて、空の結果が確定的になる2。

スコア1.0の最有力候補は、別々のファイルにある同一の7行関数2つで、同じオブジェクトを構築するものだった。デフォルトモードの fallow dupes は、それらの関数が最小値の 50 トークンを下回っていたため、リポジトリにクローンが報告されなかった。

出典

  1. TypeScriptで意味的に類似した関数を探す。fallowドキュメント。https://fallow.tools/docs/analysis/similar-code/ ↩ ↩2 ↩3

  2. Semantic Similar-Code Workflow。fallowスキルのリファレンス。fallow 3.43.1 npm パッケージ (skills/fallow/references/similar-code.md) 内。 ↩ ↩2

  3. fallow CHANGELOG. https://github.com/fallow-rs/fallow/blob/main/CHANGELOG.md ↩