Guide error handling

Error Handling & Intelligente Lösungsvorschläge

Version: 3.1.0 ✅ (Neu)
Status: Vollständig implementiert

---

📋 Übersicht

Der VelinScript Compiler bietet ein umfassendes Fehlerbehandlungssystem mit intelligenten Lösungsvorschlägen für alle Fehlertypen. Dies hilft Entwicklern, Fehler schnell zu identifizieren und zu beheben.

---

🔴 Fehlertypen

1. Parse Errors (Syntax-Fehler)

Tritt auf, wenn die Syntax ungültig ist.

❌ Parse error: Unexpected token at line 5, column 10
💡 Did you mean: 'fn'?
🔧 Lösungsvorschlag: Function declarations use 'fn', not 'function'

Häufige Ursachen:

• Falsche Keywords (function statt fn)
• Fehlende Klammern
• Unvollständige Generics

2. Type Errors (Typ-Fehler)

Tritt auf, wenn Typen nicht kompatibel sind.

❌ Type error: Type mismatch at line 12, column 15
💡 Expected: string
💡 Found: number
🔧 Nutze explizite Typ-Annotationen

Häufige Ursachen:

• Type Mismatch
• Undefined Variable
• Falsche Argument-Anzahl

3. CodeGen Errors (Code-Generierungsfehler)

Tritt auf bei der Code-Generierung für Zielsprache.

❌ Code Generation Error: IR code generation failed
📋 Target: Rust
🔧 Prüfe die IR-Validierung

4. IO Errors (Datei-/IO-Fehler)

Tritt auf bei Datei-Operationen.

❌ IO Error: File not found: test.velin
🔧 Prüfe den Dateipfad

5. Validation Errors (Validierungsfehler)

Tritt auf bei Validierung.

❌ Validation Error: Field is required
📋 Feld: name
🔧 Stelle sicher, dass alle Pflichtfelder vorhanden sind

6. Config Errors (Konfigurationsfehler)

Tritt auf bei ungültiger Konfiguration.

❌ Configuration Error: Invalid JSON
🔧 Prüfe velin.config.json auf Syntax-Fehler

---

💡 Intelligente Lösungsvorschläge

"Did You Mean?" Feature

Der Compiler verwendet Levenshtein-Distanz um ähnliche Befehle/Variablen vorzuschlagen:

❌ Undefined variable: userNmae
💡 Did you mean: 'userName'?

Kontextbezogene Hinweise

Jeder Fehlertyp erhält spezifische Tipps:

// Fehler: Typ mismatch
let x: string = 42;

// ❌ Type error: Type mismatch at line 1, column 15
// 💡 Beispiel für explizite Typ-Annotation:
//    let x: string = "hello";
//    let y: number = 42;

Dokumentations-Links

Der Compiler verlinkt zu relevanten Dokumentationen:

🔧 Lösungsvorschläge:
   - Siehe: docs/language/specification.md
   - Siehe: docs/guides/getting-started.md

---

🛠️ Best Practices für Error Handling

1. Nutze Try-Catch für kritische Operationen

try {
    let data = http.get("https://api.example.com/data");
    process(data);
} catch err {
    log.error("API request failed: " + err.message);
    alert.send("API Error!");
}

2. Validiere User Input früh

@POST("/api/users")
fn createUser(userData: UserInput): Result<User, Error> {
    // Validiere sofort
    if (userData.email == "") {
        return Result.Err("Email erforderlich");
    }
    if (userData.password.length < 12) {
        return Result.Err("Passwort muss mindestens 12 Zeichen lang sein");
    }
    
    // Erstelle User
    let user = User { /* ... */ };
    return Result.Ok(user);
}

3. Nutze sprechende Fehlermeldungen

// ❌ Schlecht
if (count > 100) {
    return Result.Err("Invalid");
}

// ✅ Gut
if (count > 100) {
    return Result.Err("User count exceeds maximum of 100");
}

4. Logge mit Kontext

try {
    process(data);
} catch err {
    log.error("Processing failed", {
        userId: user.id,
        dataSize: data.length,
        error: err.message,
        timestamp: now(),
    });
}

---

📊 Fehlerstatistiken

Der Compiler sammelt Fehlerstatistiken:

✗ Kompilierung fehlgeschlagen mit 2 Fehlern:

❌ Parse error: Unexpected token at line 5, column 10
❌ Type error: Type mismatch at line 12, column 15

⚠️  2 Warnung(en):

⚠️  Warning: Deprecated function
⚠️  Warning: Unused variable

Fehlerstatistiken:
- Parse Errors: 1
- Type Errors: 1
- Warnings: 2

---

🔍 CLI-Integration

velin check mit besseren Fehlern

$ velin check -i main.velin

✗ Kompilierung fehlgeschlagen mit 1 Fehler:

❌ Type error: Type mismatch at line 12, column 15
📁 Datei: main.velin
📍 Position: Zeile 12, Spalte 15

💡 Did you mean: 'length'?
💡 Beispiel für explizite Typ-Annotation:
   let x: number = 42;
   let name: string = "John";

🔧 Lösungsvorschläge:
   - Prüfe die Typen deiner Variablen
   - Nutze explizite Typ-Annotationen bei Unsicherheit
   - Siehe: docs/guides/tutorial-1-basics.md

💡 Tipp: Nutze 'velin check --autofix' für automatische Korrekturen

---

📈 Error-Export

JSON-Format

velin compile -i main.velin --export-errors errors.json

{
  "errors": [
    {
      "type": "Parse",
      "message": "Unexpected token",
      "line": 5,
      "column": 10,
      "suggestion": "Did you mean: 'fn'?"
    }
  ],
  "warnings": [],
  "statistics": {
    "parse_errors": 1,
    "type_errors": 0,
    "warnings": 0
  }
}

HTML-Report

velin compile -i main.velin --export-errors-html report.html

Generiert einen professionellen HTML-Report mit:

• Fehler- und Warning-Kategorisierung
• Statistik-Dashboard
• Responsive Design

---

🎯 Fehler-Filterung

Filter nach Typ

# Nur Parse-Fehler
velin check -i main.velin --filter parse

# Nur kritische Fehler
velin check -i main.velin --filter critical

# Alle Fehler
velin check -i main.velin --filter all

---

🚀 Integration mit Tools

VS Code Extension

Der VelinScript VS Code Extension zeigt Fehler mit Lösungsvorschlägen:

❌ Type error on line 12
💡 Quick Fix: Add type annotation
💡 Did you mean: 'userName'?

CI/CD Pipeline

- name: VelinScript Check
  run: |
    velin check -i src/main.velin \
      --export-errors-html report.html
    if [ -s errors.json ]; then exit 1; fi

---

📚 Weitere Ressourcen

• Language Specification - Sprachspezifikation
• Getting Started - Erste Schritte
• CLI-Reference - CLI-Befehle

---

Erstellt: 2026-02-02
Version: 3.1.0