espocrm/custom/docs/tools/VALIDATION_TOOLS.md

# Validierungstools für EspoCRM Custom-Entwicklung

## Installierte Tools

### 1. PHP-CLI (v8.2.29)
**Zweck:** Validierung von PHP-Syntax

**Installation:**
```bash
sudo apt install -y php-cli
```

**Verwendung im Script:**
```bash
php -l /pfad/zur/datei.php
```

**Validiert:**
- PHP-Syntax-Fehler
- Parse-Fehler
- Fehlende Klammern/Semikolons
- Ungültige Funktionsdeklarationen

---

### 2. CSSLint (v1.0.4)
**Zweck:** CSS-Validierung und Best-Practice-Checks

**Installation:**
```bash
sudo apt install -y nodejs npm
sudo npm install -g csslint
```

**Verwendung im Script:**
```bash
csslint --format=compact --quiet /pfad/zur/datei.css
```

**Validiert:**
- CSS-Syntax-Fehler
- Ungültige Properties
- Vendor-Prefix-Probleme
- Performance-Probleme
- Kompatibilitätsprobleme

**Konfiguration:**
Das Script verwendet standardmäßig alle csslint-Regeln. Für custom Rules kann eine `.csslintrc` Datei erstellt werden.

---

### 3. JSHint (v2.13.6)
**Zweck:** JavaScript-Code-Qualität und Syntax-Validierung

**Installation:**
```bash
sudo npm install -g jshint
```

**Verwendung im Script:**
```bash
jshint --config=/dev/null /pfad/zur/datei.js
```

**Validiert:**
- JavaScript-Syntax-Fehler
- Potenzielle Bugs
- Code-Style-Probleme
- Ungültige Variablen-Deklarationen
- Scope-Probleme

**Konfiguration:**
Aktuell nutzt das Script minimale Konfiguration. Für erweiterte Checks kann eine `.jshintrc` Datei erstellt werden:

```json
{
  "esversion": 6,
  "browser": true,
  "jquery": true,
  "unused": true,
  "undef": true
}
```

---

## Integration im Validierungsscript

Das Script `custom/scripts/validate_and_rebuild.py` nutzt diese Tools automatisch:

### Automatische Erkennung
```python
# Prüft ob Tool verfügbar ist
try:
    subprocess.run(['csslint', '--version'], capture_output=True)
    use_csslint = True
except FileNotFoundError:
    use_csslint = False
    # Fallback auf Basis-Validierung
```

### Fallback-Mechanismus
Falls ein Tool nicht verfügbar ist, verwendet das Script eine Basis-Validierung:

- **CSS:** Klammer-Matching, Attribut-Selektoren
- **JavaScript:** Klammer-Matching (rund, eckig, geschweift)
- **PHP:** Übersprungen mit Warnung

---

## Validierungsebenen

### Kritische Fehler (Rebuild wird abgebrochen)
- JSON-Syntax-Fehler
- PHP-Syntax-Fehler
- CSS-Syntax-Fehler (schwerwiegend)
- JavaScript-Syntax-Fehler
- Fehlende Relationship-Definitionen

### Warnungen (Rebuild wird fortgesetzt)
- CSS-Best-Practice-Verletzungen
- Fehlende i18n-Übersetzungen
- Code-Style-Probleme
- Performance-Hinweise

---

## Manuelle Verwendung der Tools

### CSS prüfen
```bash
# Einzelne Datei
csslint client/custom/css/my-styles.css

# Alle CSS-Dateien
find client/custom/css -name "*.css" -exec csslint {} \;

# Mit spezifischen Regeln
csslint --errors=errors,duplicate-properties client/custom/css/
```

### JavaScript prüfen
```bash
# Einzelne Datei
jshint client/custom/src/views/my-view.js

# Alle JS-Dateien
find client/custom/src -name "*.js" -exec jshint {} \;

# Mit Konfiguration
jshint --config .jshintrc client/custom/src/
```

### PHP prüfen
```bash
# Einzelne Datei
php -l custom/Espo/Custom/Classes/MyClass.php

# Alle PHP-Dateien
find custom/Espo -name "*.php" -exec php -l {} \; | grep -v "No syntax errors"
```

---

## Zusätzliche empfohlene Tools (optional)

### 1. ESLint (moderne Alternative zu JSHint)
```bash
sudo npm install -g eslint
eslint --init  # Erstellt .eslintrc Konfiguration
```

### 2. Stylelint (moderne Alternative zu CSSLint)
```bash
sudo npm install -g stylelint stylelint-config-standard
# Benötigt .stylelintrc Konfiguration
```

### 3. PHPStan (statische PHP-Analyse)
```bash
composer require --dev phpstan/phpstan
vendor/bin/phpstan analyse custom/Espo
```

### 4. PHP_CodeSniffer (PHP Code-Style)
```bash
sudo apt install -y php-codesniffer
phpcs --standard=PSR12 custom/Espo/
```

---

## Troubleshooting

### Tool nicht gefunden
```bash
# Prüfe Installation
which csslint
which jshint
which php

# Installiere fehlende Tools
sudo apt update
sudo apt install -y nodejs npm php-cli
sudo npm install -g csslint jshint
```

### Validierung zu streng
Bearbeite das Script und passe die Tool-Parameter an:
```python
# Weniger strikte CSS-Validierung
result = subprocess.run(
    ['csslint', '--format=compact', '--errors=errors', str(css_file)],
    ...
)
```

### Performance-Probleme
Für große Projekte mit vielen Dateien:
```python
# Parallele Validierung mit ThreadPoolExecutor
from concurrent.futures import ThreadPoolExecutor

with ThreadPoolExecutor(max_workers=4) as executor:
    results = executor.map(validate_css_file, css_files)
```

---

## Best Practices

1. **Vor jedem Commit:** Führe Validierung aus
   ```bash
   python3 custom/scripts/validate_and_rebuild.py --dry-run
   ```

2. **Automatisierung:** Integriere in Git pre-commit hook
   ```bash
   # .git/hooks/pre-commit
   #!/bin/bash
   python3 custom/scripts/validate_and_rebuild.py --dry-run
   if [ $? -ne 0 ]; then
       echo "Validierung fehlgeschlagen. Commit abgebrochen."
       exit 1
   fi
   ```

3. **CI/CD Integration:** Nutze in Build-Pipeline
   ```yaml
   # .gitlab-ci.yml / .github/workflows/
   validate:
     script:
       - python3 custom/scripts/validate_and_rebuild.py --dry-run
   ```

4. **IDE Integration:** Konfiguriere Editor für Live-Feedback
   - VSCode: ESLint/Stylelint Extensions
   - PHPStorm: Built-in PHP/JS/CSS Validierung

---

## Maintenance

### Updates der Tools
```bash
# System-Packages
sudo apt update && sudo apt upgrade

# NPM-Packages
sudo npm update -g csslint jshint

# Prüfe Versionen
php --version
csslint --version
jshint --version
```

### Entfernung
```bash
# NPM-Tools
sudo npm uninstall -g csslint jshint

# APT-Packages
sudo apt remove php-cli nodejs npm
sudo apt autoremove
```

---

**Letzte Aktualisierung:** Januar 2026
**Maintainer:** Custom Scripts Team
**Dokumentation:** `custom/scripts/VALIDATION_TOOLS.md`