eliteforge-sonar-pmd-generator

Sonar PMD ジェネレーター（仕様駆動、エンドツーエンド）

概要

このスキルは、コーディング規約のドキュメントを適用可能な PMD ルールに変換し、実際の SonarQube サーバーのワークフローを通じて検証します。 完了には、仕様の解析、L1/L2/L3/L4 の分類、L1-L2 向けの PMD ルールセット生成、L3 向けの自動化計画、L4 向けのレビュー計画、カスタム sonar-pmd プラグインのパッケージ化、Docker での Sonar 起動、テストプロジェクトのスキャン、サーバー側での検証からなるエンドツーエンドの一連の工程が必要です。

環境変数

• ELITEFORGE_SKILL_SONAR_PMD_HOST［任意］参照用コマンドスニペットに使用する SonarQube のベース URL。スクリプトの引数で上書きできます。
• ELITEFORGE_SKILL_SONAR_PMD_TOKEN［任意］ローカル検証用スニペットに使用する SonarQube API トークン。値を表示しないでください。
• ELITEFORGE_SKILL_SONAR_PMD_PROJECT_KEY［任意］API 証拠スニペットで使用する Sonar プロジェクトキー。
• ELITEFORGE_SKILL_SONAR_PMD_PLUGIN_KEY［任意］API 証拠スニペットで使用するカスタム Sonar プラグインキー。
• ELITEFORGE_SKILL_SONAR_PMD_RULE_REPO_KEY［任意］API 証拠スニペットで使用するカスタムルールリポジトリキー。
• ELITEFORGE_SKILL_SONAR_PMD_PROFILE_KEY［任意］API 証拠スニペットで使用する品質プロファイルキー。

段階的な読み込み

• 実行順序の全体を確認するには、まず references/workflow-playbook.md を読んでください。
• プラグインモジュールを実装またはデバッグするときは、references/plugin-packaging-blueprint.md を読んでください。
• Docker で Sonar を起動してテストスキャンを実行するときは、references/docker-sonar-validation.md を読んでください。
• 検証の証拠を収集するときは、references/sonar-api-evidence-checklist.md を読んでください。
• スキャン後に API ベースですばやくスモーク検証するには、scripts/verify_sonar_plugin.sh を使用してください。

トリガー条件

次の意図が 1 つ以上リクエストに含まれる場合、このスキルを使用してください。

• コーディング仕様を PMD ルールに変換する。
• 仕様の条項を L1/L2/L3/L4 に自動分類する。
• カスタム Sonar PMD プラグイン／プロファイルを構築または拡張する。
• Docker と実際のスキャンを使用して、SonarQube で PMD プラグインの動作を検証する。
• カスタムルールが Sonar に表示され、問題を検出していることを証明する。

必須入力

• 1 つ以上の仕様ファイルのパス。
• 各仕様の対象言語。
• プラグインのワークスペースパス（または作成の許可）。
• テストプロジェクトのパス（または作成の許可）。
• 任意の出力ディレクトリ（デフォルト：pmd-governance/）。
• 任意のプロファイル名（デフォルト：custom-spec-profile）。

分類の契約（必ず従うこと）

• L1：対象言語の PMD 組み込みルールで対応できる。
• L2：対象言語の PMD AST XPath ルールで表現できる。
• L3：PMD では表現できない、または表現すべきではないが、フォーマッター、フック、CI ジョブ、Checkstyle、Semgrep、ArchUnit、ビルドプラグインなどの他の自動化ツールで確実に検出できる。
• L4：ビジネス上の意味、アーキテクチャ上の意図、または不安定なヒューリスティクスに依存するため、人間または AI によるレビューが必要。
• L3 または L4 を、脆弱な PMD XPath 実装に無理に当てはめないでください。

各仕様文について、次の項目を記録してください。

• SPEC-ID
• 元の仕様文
• 対象言語
• レベル（L1/L2/L3/L4）
• 検出対象
• 発動条件
• 例外条件
• 重要度
• 主要ツール
• 実行段階
• 実装計画
• レビュアーノート（L4 では必須）

エンドツーエンドのワークフロー（必須）

1. 仕様の記述を解析し、ID（SPEC-<LANG>-001、...）を割り当てます。
2. すべての記述を自動的にL1/L2/L3/L4に分類します。
3. ガバナンス成果物を生成します。
   • mapping/spec-to-governance.csv
   • rulesets/custom-<lang>-ruleset.xml
   • automation/l3-tooling-plan.md
   • manual-review/l4-review-checklist.md
   • README.md
4. L1-L2のみを対象に、カスタムPMDルールモジュールをビルドします。
   • L1のマッピング済み参照と、L2のカスタムXPath/Javaルールを含めます
   • ルールキーとメッセージには、トレーサビリティを確保するためSPEC-IDを含める必要があります
5. L3の自動化計画を作成します。
   • ルールを適用できる、最小限で安定したツールを選択します
   • 可能であれば、カスタムスクリプトよりフォーマッターやビルドプラグインを優先します
   • pre-commit、CI、ビルド、MRチェックのいずれで実行するかを明記します
6. L4のレビュー計画を作成します。
   • 人によるレビューのチェックリスト項目を定義します
   • オプションでAIレビュー用のプロンプトまたは評価基準を定義します
7. カスタムSonarプラグインモジュールをビルドします。
   • PMDルールリポジトリを登録します
   • カスタムルールをSonarに読み込みます
   • デフォルトの品質プロファイル（custom-spec-profileまたはユーザー指定の名前）を提供します
8. プラグインJARをパッケージ化し、Sonarのプラグインディレクトリ（extensions/plugins）にデプロイします。
9. カスタムプラグインを読み込んだ状態で、SonarQube CommunityをDockerで起動します。
10. Sonarサーバーの準備が整うまで待機し、トークンとプロジェクトのバインドを初期化します。
11. テストプロジェクトを準備します。

• 実プロジェクトが提供されていればそれを使用し、そうでなければ最小限のプロジェクトをスキャフォールドします
• 違反するコードサンプルと準拠するコードサンプルの両方を含めます

12. Maven Sonarプラグイン（mvn sonar:sonar）を使って実際のスキャンを実行します。
13. SonarのAPI/UIでプラグインの有効性を検証します。

• プロファイルが存在し、有効になっていること
• カスタムルールが一覧表示され、有効になっていること
• ルールキー、ファイル、行に対応付けられた問題が検出されること

14. スキャンの証跡と未解決の課題を報告します。

言語サポートの判定

1. 対象言語がPMDとSonarの統合経路でサポートされているか確認します。
2. PMDでサポートされていない場合：
   • 別の自動化ツールで適用できる候補をL3に分類します
   • 残りの項目をL4に分類します
   • 自動化とレビューの両方の成果物を生成します
   • 代替アナライザーと、任意で汎用的な外部問題のインポートを推奨します

Sonar統合

サーバー側プラグインの実行：

• このスキルではカスタムプラグインの検証が必須となるため、こちらを推奨します。
• スキャンコマンドの例：
  • mvn -DskipTests sonar:sonar -Dsonar.host.url=http://localhost:9000 -Dsonar.token=<token>

Docker検証の基準

コンテナ起動後に行う最低限のチェック：

• Sonarのヘルスエンドポイントが準備完了を示していること。
• プラグインが読み込まれていること（マーケットプレイス／プラグイン一覧、または起動ログで確認）。
• プラグインの品質プロファイルを利用できること。

スキャン後に行う最低限のチェック：

• 違反するサンプルに、カスタムルールによる問題が少なくとも1件表示されること。
• 準拠するサンプルでは、そのカスタムルールが検出されないこと。
• 問題が具体的なファイルと行に対応付けられていること。

譲れないルール

• PMDのレポートを手作業で作成しないでください。検出結果は実際の解析から生成する必要があります。
• L1-L2はPMDルールとカスタムsonar-pmdプラグインに含めます。
• L3項目はPMDに無理に組み込まず、自動化ツール計画に出力する必要があります。
• L4項目は、人またはAIによるレビューワークフローに出力する必要があります。
• Docker上のSonarと実際のスキャンの証跡がなければ、エンドツーエンドの検証は完了していません。
• ユーザーがCIでのゲート設定を明示的に要求しない限り、初回の導入ではビルドをブロックしない設定にしてください。

成果物

• ガバナンス成果物（mapping、ruleset、L3ツール計画、L4レビュー用チェックリスト）。
• カスタムプラグインのソースとパッケージ化済みJAR。
• Dockerの起動コマンドと実行時の証跡。
• テストプロジェクトのスキャンコマンドと結果の概要。
• プロファイルキー、ルールキー、問題の件数、サンプルとなる問題の場所を記載した検証レポート。

トラブルシューティングのチェックリスト

• プラグインが読み込まれない場合：Sonar／プラグイン API の互換性を確認し、再起動ログを確認します。
• プロファイルが見つからない場合：リポジトリキーとプロファイルの登録コードを確認します。
• 問題が検出されない場合：プロファイルの紐付けを確認し、テストコードが実際にルールに違反していることを確認します。
• 誤検知が急増した場合：XPath の対象範囲を絞り、陰性サンプルを追加します。
• スキャン時に認証エラーが発生する場合：トークンと sonar.host.url の整合性を確認します。