typo3-conformance-skill

# TYPO3 Extension Conformance Checker

A comprehensive Claude Code skill for evaluating TYPO3 extensions against official TYPO3 coding standards, architecture patterns, and best practices.

## 🔌 Compatibility

This is an **Agent Skill** following the [open standard](https://agentskills.io) originally developed by Anthropic and released for cross-platform use.

**Supported Platforms:**
- ✅ Claude Code (Anthropic)
- ✅ Cursor
- ✅ GitHub Copilot
- ✅ Other skills-compatible AI agents

> Skills are portable packages of procedural knowledge that work across any AI agent supporting the Agent Skills specification.


## Overview

This skill enables systematic evaluation of TYPO3 extensions for conformance to official TYPO3 standards.

### Skill Ecosystem Integration

This conformance checker acts as an **orchestrator** that delegates to specialized skills for deep domain analysis:

**🔧 Testing Analysis: typo3-tests**
- Repository: https://github.com/netresearch/typo3-testing-skill
- Expertise: Deep PHPUnit configuration analysis, test quality patterns, TYPO3 Testing Framework validation
- Integration: Delegated for Testing Standards category (20 points)

**📚 Documentation Analysis: typo3-docs**
- Repository: https://github.com/netresearch/typo3-docs-skill
- Expertise: RST validation, TYPO3 documentation standards, rendering validation with Docker
- Integration: Delegated for Documentation Excellence (bonus category)

**Delegation Benefits:**
- **Depth:** Each skill provides domain expertise beyond surface-level checks
- **Accuracy:** Specialized validation reduces false positives/negatives
- **Modularity:** Skills can be used independently or together
- **Maintainability:** Each skill focuses on single responsibility

**Fallback Strategy:**
- Surface-level checks performed if specialized skills unavailable
- Basic validation ensures conformance reports always generate
- Full accuracy requires all ecosystem skills installed

### Standards Checked

| Standard | Version/Specification |
|----------|----------------------|
| **TYPO3 Core** | 12.4 LTS / 13.x |
| **PHP** | 8.1 / 8.2 / 8.3 / 8.4 |
| **Coding Style** | PSR-12 (Extended Coding Style) |
| **Architecture** | Dependency Injection (PSR-11), PSR-14 Events, PSR-15 Middleware |
| **Testing** | PHPUnit 10+, TYPO3 Testing Framework, Playwright E2E |
| **Documentation** | reStructuredText (RST), TYPO3 Documentation Standards |

### Conformance Areas

- **Extension Architecture** - File structure, naming conventions, required files
- **Coding Guidelines** - PSR-12 compliance, TYPO3-specific code style
- **PHP Architecture** - Dependency injection, services, events, Extbase patterns
- **Testing Standards** - Unit, functional, and Playwright E2E testing requirements
- **Best Practices** - Real-world patterns from Tea extension and core standards

## Features

### Automated Validation Scripts

- ✅ **check-conformance.sh** - Main orchestration script
- 📁 **check-file-structure.sh** - File structure and directory validation
- 📝 **check-coding-standards.sh** - PSR-12 and TYPO3 code style checks
- 🏗️  **check-architecture.sh** - Dependency injection and architecture patterns
- 🧪 **check-testing.sh** - Testing infrastructure and coverage analysis
- 📊 **generate-report.sh** - Comprehensive conformance report generation

### Reference Documentation

**Core Standards:**
- **version-requirements.md** - Official TYPO3 and PHP version compatibility matrix
- **extension-architecture.md** - TYPO3 file structure standards
- **coding-guidelines.md** - PSR-12 and TYPO3 code style guide
- **php-architecture.md** - Dependency injection and architectural patterns
- **testing-standards.md** - Unit, functional, and Playwright E2E testing
- **best-practices.md** - Real-world patterns and project infrastructure

**Advanced Validation Guides:**
- **runtests-validation.md** - Validate Build/Scripts/runTests.sh against Tea extension reference
- **development-environment.md** - Validate DDEV/Docker development environment setup
- **directory-structure.md** - Validate .Build/ vs Build/ directory separation and organization

**Excellence Indicators:**
- **excellence-indicators.md** - Optional quality features for exceptional extensions (0-20 bonus points)
  - Community & Internationalization: Crowdin, issue templates, .gitattributes, README badges
  - Advanced Quality Tooling: Fractor, TYPO3 CodingStandards, StyleCI, Makefile, CI matrix
  - Documentation Excellence: 100+ RST files, modern tooling (guides.xml, screenshots.json)
  - Extension Configuration: ext_conf_template.txt, composer doc scripts, multiple Sets

**Secondary References:**
- **georgringer/news** - Community reference extension demonstrating excellence patterns

### Quality Tool Configuration Templates

Production-ready configuration templates based on [TYPO3 Best Practices (Tea Extension)](https://github.com/TYPO3BestPractices/tea):

- **Build/phpstan/phpstan.neon** - PHPStan Level 10 with advanced security and type safety
- **Build/rector/rector.php** - Automated TYPO3 migrations and refactoring
- **Build/php-cs-fixer/php-cs-fixer.php** - TYPO3 coding standards with parallel execution
- **Build/composer-unused/composer-unused.php** - Dependency health monitoring
- **Build/typoscript-lint/TypoScriptLint.yml** - TypoScript quality enforcement
- **Build/eslint/.eslintrc.json** - JavaScript/TypeScript linting
- **Build/stylelint/.stylelintrc.json** - CSS/SCSS quality checks
- **Build/playwright/** - Playwright E2E and accessibility testing (Node >=22.18)
- **.github/workflows/publish-to-ter.yml** - TER publishing workflow

All templates are available in [`assets/`](assets/) and ready for direct use.

## Advanced Code Quality Tools

### PHPStan Advanced Configuration

PHPStan Level 10 represents the highest level of static analysis available, providing comprehensive type safety, security enforcement, and code quality checks. Level 10 enables bleeding-edge rules for maximum strictness and early adoption of future PHPStan features.

#### Key Features

**Type Coverage Enforcement**

The configuration enforces 100% type coverage for parameters and return types, with 95% coverage for properties. This eliminates ambiguity and enables better IDE support:

```yaml
type_coverage:
  return_type: 100  # Every function must declare return type
  param_type: 100   # Every parameter must have type hint
  property_type: 95 # 95% of class properties must be typed
```

**Cognitive Complexity Limits**

Complexity limits prevent unmaintainable code by enforcing function and class complexity boundaries:

```yaml
cognitive_complexity:
  class: 10      # Maximum complexity score per class
  function: 5    # Maximum complexity score per function
```

Functions exceeding complexity limits should be refactored into smaller, focused methods. This improves testability and reduces bug density.

**Type Perfection Mode**

Advanced type safety features eliminate common type-related issues:

```yaml
type_perfect:
  no_mixed_property: true  # Prevents mixed type pollution
  no_mixed_caller: true    # Enforces concrete types in method calls
  null_over_false: true    # Prefers nullable types over boolean returns
  narrow_param: true       # Uses most specific parameter types
  narrow_return: true      # Uses most specific return types
```

**Security-Focused Disallowed Patterns**

The configuration integrates `spaze/phpstan-disallowed-calls` to prevent security vulnerabilities:

1. **PSR-7 Enforcement**: Disallows superglobals ($_GET, $_POST, $_SERVER, etc.), enforcing PSR-7 ServerRequestInterface usage
2. **Debug Function Prevention**: Blocks var_dump(), debug(), dd() to prevent information disclosure
3. **Legacy API Prevention**: Disallows deprecated functions like header() in favor of PSR-7 responses

Example violation and fix:

```php
// ❌ PHPStan Error: Use PSR-7 ServerRequestInterface instead
public function processForm(): void
{
    $username = $_POST['username'];
}

// ✅ Correct PSR-7 Implementatio

[truncated…]