linguistic-semantic-algorithms

pproenca 言語・意味アルゴリズムのベストプラクティス

ソースコードやコミットデータから構造、意味、履歴、リスクのシグナルを抽出する際に、エージェントが活用すべき40のアルゴリズムをまとめたリファレンスです。カテゴリは労力あたりの洞察、つまり、適用の容易さに対してどれだけ自明でない真実を明らかにできるか、の順に並んでいます。最初の2つのカテゴリでは、最も効果の大きい次の問いを扱います。このコードにはどのようなビジネスエンティティが存在するか？ そして この概念は他のどこにすでに存在しているか？ — これらの問いには、grepや直感では答えられません。

適用する場面

次のような場合に、これらのアルゴリズムを活用してください。

• 不慣れなコードベースの概要を把握する場合：インポートグラフにPageRankを適用して中核を特定し、識別子トークンにLDAを適用してビジネステーマを見つけ、変更の結合性をマイニングして隠れたアーキテクチャ上の結合を明らかにします。
• 説明からバグを探す場合：BM25 + 履歴情報による事前確率 + 埋め込みの再ランキングによって、grepよりもはるかに優れたファイル候補リストを順位付けできます。
• 機能のスコープを決める場合：埋め込みの類似度を使って、同様の作業を行った過去のPRを見つけます。TF-IDFと名詞句マイニングを使って、機能の語彙とコードベースのドメインを対応付けます。
• リファクタリングをレビューする場合：ASTレベルのGumTree差分で、テキスト差分では見えない意味的な影響を明らかにします。PDGの同型性によって、「ロジックは同じでコードは異なる」ため、あわせて更新すべき箇所を見つけます。
• リスクを監査する場合：ホットスポット（変更頻度 × 複雑度）、バス係数、欠陥を引き寄せるコードの密度、デッドコード候補を組み合わせることで、注意を向けると効果が得られるコードベースの部分がわかります。
• ドメインエンティティと境界づけられたコンテキストを特定する場合：名詞句マイニング + TF-IDFによる希少語の抽出 + Louvainコミュニティ検出 + クラスターごとの語彙に対するJensen-Shannonダイバージェンスを使います。

優先度別のルールカテゴリ

優先度	カテゴリ	影響	プレフィックス	回答する問い
1	概念・ドメインの抽出	CRITICAL	concept-	このコードにはどのようなビジネスエンティティが存在するか？
2	意味的類似性と機能のマッピング	CRITICAL	sim-	この概念は他のどこにすでに存在しているか？
3	アーキテクチャのトポロジー	HIGH	graph-	このコードベースはどのような構造か？
4	共変更と時間的マイニング	HIGH	mine-	履歴からどのような隠れた結合がわかるか？
5	クローンと重複の検出	MEDIUM-HIGH	clone-	同じことを繰り返している箇所はどこか？
6	バグと機能の特定	MEDIUM-HIGH	local-	説明された内容は、コードのどこにあるか？
7	識別子の言語学的分析	MEDIUM	ling-	他のアルゴリズムが機能するよう、トークンをどのように準備するか？
8	複雑度とリスクの指標	MEDIUM	risk-	危険が集中しているのはどこか？

クイックリファレンス

1. 概念・ドメインの抽出（CRITICAL）

• concept-lda-topic-modeling — 識別子トークンへのLDA適用により、潜在的なビジネステーマを明らかにします
• concept-noun-phrase-mining — 識別子に品詞タグ付けとチャンク化を適用し、エンティティ候補を抽出します
• concept-tfidf-rare-terms — 汎用コーパスに対するIDFで、フレームワーク由来のノイズからドメイン語彙を分離します
• concept-identifier-cooccurrence-network — PMIで重み付けした共起グラフによって、概念的な近傍を明らかにします
• concept-entity-name-resolution — 埋め込み + 編集距離を使って、名前のバリエーション（user/usr/u/userAccount）をクラスタリングします
• concept-bounded-context-detection — Louvain + Jensen-ShannonダイバージェンスでDDDの境界づけられたコンテキストを検出します

2. 意味的類似性と機能マッピング（重要）

• sim-codebert-embeddings — CodeBERT とコサイン類似度を使い、名前変更をまたいでコードを意味的に検索します
• sim-pdg-semantic-clones — プログラム依存グラフの同型性により、タイプ4のクローンを検出します
• sim-cross-pr-feature-mapping — マージ済みPRを一度だけ埋め込み、機能設計時に先例を取得します
• sim-cosine-vsm-files — GPUが利用できない場合に、TF-IDF VSMでファイルの類似性を判定します
• sim-call-pattern-similarity — 呼び出しシーケンスのN-gramから、動作が似たコードを見つけます
• sim-doc-code-alignment — コードとドキュメントを同時に埋め込み、両者のずれを検出します

3. アーキテクチャのトポロジー（高）

• graph-pagerank-core — インポートグラフにPageRankを適用し、コードベースの中核を見つけます
• graph-betweenness-bottlenecks — 媒介中心性により、ボトルネックとなるモジュールを明らかにします
• graph-louvain-modules — Louvainコミュニティ検出により、自然なモジュール境界を明らかにします
• graph-scc-cycle-tangles — TarjanのSCCアルゴリズムにより、循環依存関係の絡まりを明らかにします
• graph-feedback-arcs — Eades-Lin-SmythのFASにより、サイクルを断つ最小の辺集合を選びます

4. 共同変更と時系列マイニング（高）

• mine-change-coupling — コミット履歴に対する条件付き確率から、隠れた結合関係を明らかにします
• mine-hotspots-churn-complexity — 変更量 × 複雑度で、標準的なホットスポットスコアを算出します（Tornhill）
• mine-bus-factor — ファイルごとの著者のジニ係数から、知識の集中度を明らかにします
• mine-commit-topic-modeling — コミットメッセージにLDAを適用し、四半期ごとのテーマを明らかにします
• mine-bug-fix-density — コミットを分類し、修正密度でファイルを順位付けして、不具合が集中する箇所を見つけます
• mine-codebase-aging — 最終変更からの経過時間と到達可能性に基づき、安定したコードとデッドコードを分類します

5. クローンと重複の検出（中〜高）

• clone-minhash-lsh — MinHash と LSH により、サブリニア時間で近似重複を取得します
• clone-simhash — SimHashの64ビットフィンガープリントにより、O(1)のハミング距離検索を実現します
• clone-suffix-array-cpd — トークンレベルの接尾辞配列（PMD CPD）により、クローンの境界を正確に特定します
• clone-ast-gumtree — GumTreeアルゴリズムにより、細粒度のAST差分を検出します
• clone-zhang-shasha-ted — Zhang-Shashaの木編集距離により、部分木の類似性を正確に判定します

6. バグと機能のローカライズ（中〜高）

• local-tfidf-bug-reports — バグ報告のトークンに対するTF-IDFでソースファイルを順位付けします
• local-bm25-saturation — BM25により、文書長の正規化とTF飽和を処理します
• local-history-prior-localization — IRスコアとバグ履歴の事前確率をベイズ的に統合します
• local-embedding-bug-text — BM25と埋め込みによる2段階の再ランキングで、意味に基づいて対象を特定します

7. 識別子の言語学的分析（MEDIUM）

• ling-camel-snake-split — 分析前に camelCase、snake_case、数字の境界で分割します
• ling-abbreviation-expansion — 辞書とマイニングを使って idx→index、mgr→manager のように展開します
• ling-porter-stemming — Porter ステマーを適用して単数形と複数形を統一します
• ling-pos-tagging-identifiers — 識別子の主要語に品詞タグを付け、名前が不適切な関数やクラスを検出します

8. 複雑度とリスクの指標（MEDIUM）

• risk-cyclomatic-mccabe — 分岐テストの対象範囲を測る McCabe の循環的複雑度
• risk-cognitive-complexity — 可読性のゲートに使う SonarSource Cognitive Complexity
• risk-halstead-volume — 言語に依存しない規模と作業量を測る Halstead 量
• risk-shannon-entropy-naming — トークンごとのエントロピーで、意味が過剰に多義的な名前を検出します

使い方

ユーザーの質問に合ったカテゴリを選び、そのカテゴリから具体的なルールを1つか2つ読みます。ほとんどのルールでは、組み合わせて使える関連ルール（「mine-change-coupling と組み合わせる……」など）を紹介しています。これらを併用するとシグナルが強まるため、精度を高めたい場合は関連ルールも読んでください。

慣れていないリポジトリを調べる場合は、次の手順から始めると最も高い効果が得られます。

1. graph-pagerank-core → 中心性が最も高いファイルを上位20件読む
2. concept-lda-topic-modeling + concept-tfidf-rare-terms → ビジネス上のテーマを特定する
3. mine-hotspots-churn-complexity → バグが集中している箇所を見つける
4. mine-change-coupling → 隠れたアーキテクチャ上の結合を明らかにする

単一タスクのバグ修正や機能開発では、次のパイプラインを使います。

1. local-bm25-saturation（広く候補を検索）→ local-embedding-bug-text（意味的な再ランキング）→ local-history-prior-localization（修正履歴に基づく優先度の引き上げ）
2. sim-cross-pr-feature-mapping で、新機能に関する過去の先例を確認する
3. mine-change-coupling で、過去に同時に変更されることが多かった関連ファイルを見つける

語彙ベースのアルゴリズムを使う前に、必ず ling-camel-snake-split → ling-abbreviation-expansion → ling-porter-stemming の順に識別子トークンを前処理してください。この手順を省略すると、後続のすべてのシグナルの精度が気付かないうちに低下します。

クロス言語解析。 ほとんどのルールのコード例では、簡潔さを優先して Python 標準の ast モジュールを使っています。実際に複数の言語（Go、Rust、Java、TS、C++）を含むリポジトリを扱う場合は、tree-sitter を使ってください。40以上の言語に対応する堅牢なパーサーを、統一された API で利用できます。このスキルの AST ベースのルール（PDG クローン、GumTree、Zhang-Shasha、品詞タグによる主要語の検出、識別子の共起）は、すべて tree-sitter の AST にそのまま適用できます。

リファレンスファイル

ファイル	説明
references/_sections.md	カテゴリの定義と影響度の順序
assets/templates/_template.md	新しいアルゴリズムルールを追加するためのテンプレート
metadata.json	バージョンとリファレンス情報