typo3-conformance

TYPO3 拡張機能の適合性チェッカー

TYPO3 のコーディング規約、アーキテクチャパターン、ベストプラクティスに照らして、TYPO3 拡張機能を評価します。

使用する場面

• 拡張機能の品質／TER 対応状況
• スコア付きの適合性レポート
• v12／v13／v14 へのモダナイズ（v14.3 LTS がデフォルト／ゴールドスタンダードです）

委任

テスト -> typo3-testing | ドキュメント -> typo3-docs | OpenSSF -> enterprise-readiness | リリース／TER -> github-release

拡張機能を新しい TYPO3 バージョンに引き上げる場合は、typo3-extension-upgrade に委任し、ここでの作業を終了してください。 実際に、拡張機能を現行 LTS で動作させるよう依頼された際、エージェントはこのスキルを読み込み、適合性チェックを実施して完了と報告しました。ext_tables.php を削除し、非推奨の呼び出しを検索し、strict_types の数を数えましたが、マニフェストには古いバージョンが記載されたままで、新しいバージョンに対するインストールもテストも行われていませんでした。現状の監査はアップグレードではありません。バージョン制約を広げるだけでもアップグレードにはなりません。依頼がバージョンの引き上げなら、目の前にあるものを監査するのではなく、適切な担当に引き継いでください。

依頼がバージョン表記の確認だけで、それらがすでに一致している場合は、その旨を伝えて終了してください。 両方の表記方法でバージョン範囲を示し、比較した箇所を挙げてください。変更は加えないでください。「軽微な所見」や「エラーではない注意点」のセクションも設けないでください。確認依頼への求められていないコメントは指摘事項として受け取られます。何も見つからなかった確認で、ほかに報告することはありません。

composer.json と ext_emconf.php の記載が異なる場合は、両者を一致させる前に、どちらが正しいかを特定してください。 最新の LTS が自動的に正解になるわけではありません。まず根拠を集めてから判断してください。

1. リポジトリ独自のルール -- AGENTS.md、CONTRIBUTING.md、または README で、どちらかのファイルを正としている場合があります。その記述を引用してください。
2. テスト対象 -- CI マトリックスに含まれる TYPO3 バージョン（.github/workflows/、Build/、runTests.sh のデフォルト値）。
3. コードが必要とするもの -- 2 系統のうち片方にしか存在しない API（references/v14-deprecations.md、references/v13-deprecations.md）。
4. 不一致が生じた経緯 -- 履歴がある場合は git log -p -- composer.json ext_emconf.php。

ルールと根拠が一致している場合は、両方のファイルをそのバージョン系統に合わせてください。両者が食い違う場合、つまり正とされるファイルに記載されたバージョン系統が CI マトリックスでテストされていない場合は、ルールに従い、CI やコードを合わせるために対象範囲を広げるのではなく、未テストのバージョン系統を指摘事項として報告してください。変更するのはバージョン表記だけにしてください。具体的には、2 つの宣言と、それらを繰り返しているドキュメントのみです。各ファイルでは、それぞれの表記方法を使用してください（composer.json では ^13.4、ext_emconf.php では 13.4.0-13.4.99 のようにします。ext_emconf.php ではキャレットを使用しないでください。^13.4 || ^14.3 のような Composer の範囲は、1 つの範囲に対応します。references/ext-emconf-validation.md を参照してください）。回答では、判断の根拠となった証拠を明記してください。

対象範囲： 拡張機能のみです。サイト／プロジェクトリポジトリ（type: project + Compose）は、ゴールドチェッカー typo3-14-gold/tools/conformance でスコアを付けてください。

ワークフロー

ステップ 0：コンテキスト

バージョン、タイプ、対象範囲を確認するため、ext_emconf.php と composer.json を読み取ります。

手順 1-11：チェック項目

1. メタデータ -- キー、TYPO3 バージョン、タイプ。TER、docs.typo3.org、README、GitHub 全体でタイトルと説明を統一（references/extension-naming.md）
2. 構成 -- composer.json、ext_emconf.php、Classes/、Configuration/、Resources/
3. コーディング -- strict_types、PSR-12、PHP 8.4 の明示的な nullable、PHP 8.5 の float から int への変換
4. 禁止事項 -- $GLOBALS を使用しない。サービスに GeneralUtility::makeInstance() を使用しない
5. アーキテクチャ -- コンストラクター DI、Services.yaml、PSR-14 イベント（try/catch）、PSR-3 ロギング（コンテナーで構築されるサービスにコンストラクター注入された LoggerInterface、または LoggerAware+NullLogger）、ファクトリーのフォールバック
6. バックエンド -- ES6、Modal API、CSRF、CSP（v13+）
7. テスト -- PHPUnit、Playwright E2E、カバレッジ >70%
8. プラクティス -- DDEV、runTests.sh、CI/CD
9. TER -- 公開ワークフロー、アップロード時のコメント
10. 監査 -- PHPStan のベースライン、TCA の searchFields、XLIFF、キャッシュの has()+get()、クエリプロパティ、複数バージョン向けアダプター
11. v14 対応 -- ext_tables.php/HashService/マジックファインダーを使用しない。Fluid VHs は strict にする。XLF は 2 スペース。references/v14-deprecations.md を参照してください。

手順 12：検証

修正後に再実行します。スコアの変化を記録してください。

クイック grep レシピ

grep -rL 'strict_types' Classes/ --include='*.php'
grep -rn '\$GLOBALS' Classes/ --include='*.php'
grep -rn 'GeneralUtility::makeInstance' Classes/ --include='*.php'
grep -rPn '\(\s*[A-Za-z\\]+\s+\$\w+\s*=\s*null' Classes/ --include='*.php' | grep -v '?'  # PHP 8.4 implicit nullable
grep -rn '->has(' Classes/ --include='*.php'                          # cache has()+get() anti-pattern
grep -l 'strict_types' ext_emconf.php                                 # ext_emconf must NOT have strict_types
grep -rn '(int)\s*\$' Classes/ --include='*.php'                      # PHP 8.5 implicit float-to-int
grep -rn 'data-toggle\|data-dismiss\|data-ride' Resources/ --include='*.html'  # Bootstrap 4 in Fluid
grep -rn 'HashService\|GeneralUtility::hmac(\|->findBy[A-Z]\|->findOneBy[A-Z]\|->countBy[A-Z]' Classes/ --include='*.php'  # v14 removals
[ -f ext_tables.php ] && echo "WARN: ext_tables.php deprecated (#109438)"   # v14.3 deprecation

スコアリング

基本スコア（0-100）： アーキテクチャ（20）+ ガイドライン（20）+ PHP（20）+ テスト（20）+ プラクティス（20）。優秀ボーナスは最大 22 点です。重大な問題がある場合は、スコアにかかわらずブロックされます。

範囲	レベル	対応
90+	優秀	本番／TER 対応
80-89	良好	軽微な修正
70-79	許容可能	リリース前に修正
50-69	要対応	大幅な作業が必要
<50	重大	デプロイをブロック

参考資料

references/ を参照してください。

• アーキテクチャとコード： extension-architecture.md、directory-structure.md、php-architecture.md、coding-guidelines.md、best-practices.md、hooks-and-events.md
• 検証： composer-validation.md、extension-naming.md、ext-emconf-validation.md、ext-files-validation.md、runtests-validation.md、version-requirements.md、testing-standards.md
• 複数バージョン対応： dual-version-compatibility.md、v13-v14-dual-compatibility.md、multi-version-dependency-compatibility.md、v13-deprecations.md、v14-deprecations.md
• プラクティスとバックエンド： development-environment.md、backend-module-v13.md、ter-publishing.md、report-template.md、excellence-indicators.md、localization-coverage.md、crowdin-integration.md

アセットテンプレートは assets/Build/ にあります：PHPStan、PHP-CS-Fixer、Rector、ESLint、Stylelint、TypoScript lint。