ntu/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Projekt-Übersicht

**NameToUnix** ist ein Rust-CLI-Tool zum Bereinigen von Datei- und Verzeichnisnamen gemäß Linux-Konventionen. Es ersetzt Leerzeichen, Sonderzeichen und deutsche Umlaute und arbeitet rekursiv durch Verzeichnisbäume.

Dies ist das erste Rust-Projekt des Autors - Code-Verbesserungen sollten klar und didaktisch begründet werden.

## Build & Test

```bash
# Development build
cargo build

# Release build (optimiert, für Distribution)
cargo build --release

# Binary liegt dann unter:
# target/release/NameToUnix

# Tests ausführen
cargo test

# Tests mit Ausgabe
cargo test -- --nocapture

# Linting
cargo clippy

# Formatierung prüfen
cargo fmt --check

# Formatierung anwenden
cargo fmt
```

## Lokales Testen

```bash
# Test-Verzeichnisbaum mit skurrilen Dateinamen erstellen
cd test
./create_test_tree.sh

# Vorschau (keine Änderungen):
cargo run -- -n ./testverzeichnis

# Mit Änderungen:
cargo run -- ./testverzeichnis

# Mit Verbose-Ausgabe:
cargo run -- -v ./testverzeichnis
```

## Code-Architektur

Das Projekt ist in Module aufgeteilt:

- **`main.rs`**: Entry Point
  - Initialisiert Logger (`env_logger`)
  - Parsed CLI-Argumente mit `clap`
  - Lädt Konfiguration aus bis zu 3 Orten (Prioritätsreihenfolge: lokal > user > global)
  - Sammelt alle Datei-/Verzeichniseinträge via `walkdir`
  - Sortiert nach Tiefe (tiefste zuerst), um Parent-Verzeichnisse nicht zu früh umzubenennen
  - Zeigt optional Fortschrittsbalken (`indicatif`) bei >50 Einträgen

- **`cli.rs`**: Command-Line Interface
  - Definiert `Cli`-Struct mit `clap::Parser`
  - Argumente: `paths`, `--quiet`, `--no-changes`, `--force`, `--exclude`, `--verbose`, `--modify-root`
  - `ArgGroup` verhindert gleichzeitige Nutzung von `--no-changes` und `--force`

- **`config.rs`**: Konfigurationsmanagement
  - `Config`-Struct mit `HashMap<String, String>` für benutzerdefinierte Ersetzungen
  - Lädt TOML-Dateien aus 3 Orten (in dieser Reihenfolge):
    1. `/etc/NameToUnix/config.toml` (System-global)
    2. `~/.config/NameToUnix/config.toml` (User-spezifisch)
    3. `./.NameToUnix.conf` (Arbeitsverzeichnis, höchste Priorität)
  - Spätere Configs überschreiben frühere (`extend`)

- **`sanitizer.rs`**: Kern-Logik der Dateinamen-Bereinigung
  - `clean_filename()`: Hauptfunktion
    - Trennt Stamm und Extension
    - Schützt spezielle Identifikatoren (`C++`, `C#`) via Platzhalter
    - Wendet zuerst Config-Replacements an, dann hardcoded Replacements
    - Ersetzt Emojis und hochgestellte Zeichen durch `_`
    - Entfernt ungültige Zeichen via Regex (`[^\w.\-]`)
    - Normalisiert Punkt/Unterstrich-Kombinationen
    - Trimmt führende Unterstriche (behält aber führenden Punkt)
    - Stellt Platzhalter wieder her
  - `is_excluded()`: Prüft Glob-Patterns
  - `is_safe_rename()`: Sicherheitscheck vor Umbenennung (prüft ob Ziel existiert ohne `--force`)

## Konfigurationsdatei-Logik

- TOML-Format mit Sektion `[replacements]`
- **Wichtig**: Hardcoded-Transformationen (z.B. Apostroph-Entfernung, Umlaut-Ersetzung) sind immer vorrangig und nicht deaktivierbar
- Config-Replacements werden **vor** den hardcoded Replacements angewendet
- Lokale Configs überschreiben User-Configs überschreiben System-Configs

## Besonderheiten

1. **Tiefenbasierte Sortierung**: Umbenennung erfolgt von den tiefsten Verzeichnissen/Dateien nach oben, um Konflikte zu vermeiden (Parent-Verzeichnisse dürfen nicht vor ihren Kindern umbenannt werden).

2. **Platzhalter für Spezialfälle**: `C++`, `c++`, `C#`, `c#` werden temporär durch Token (`CPLUSPLUS`, etc.) geschützt, damit `+` und `#` nicht durch Unterstriche ersetzt werden.

3. **Emoji-Erkennung**: Nutzt das `emojis`-Crate zur Emoji-Erkennung und Unicode-Segmentation für grapheme-korrekte Verarbeitung.

4. **Performance-Optimierung**: Regex-Patterns sind als `static Lazy<Regex>` definiert (via `once_cell`) für wiederholte Nutzung ohne Re-Compilation.

5. **Root-Directory-Schutz**: Standardmäßig wird das Root-Verzeichnis (depth 0) nicht umbenannt, außer `--modify-root` ist gesetzt.

## Verwendete Dependencies

- `clap` mit derive-Feature für CLI-Parsing
- `walkdir` für rekursives Traversieren
- `glob` für Exclude-Pattern
- `serde` + `toml` für Config-Dateien
- `anyhow` für Error-Handling
- `log` + `env_logger` für Logging
- `indicatif` für Progress-Bars
- `regex` für Pattern-Matching
- `unicode-segmentation` für korrekte grapheme-basierte String-Verarbeitung
- `emojis` für Emoji-Erkennung
- `once_cell` für lazy-static Regex-Patterns
- `dirs` zum Finden des User-Home-Verzeichnisses

## Wichtige Hinweise für Code-Änderungen

- Die Reihenfolge der Transformationen in `clean_filename()` ist wichtig und sollte nicht ohne Tests geändert werden
- Hardcoded Replacements sind bewusst nicht über Config deaktivierbar (Design-Entscheidung)
- Tests sollten mit dem `create_test_tree.sh`-Skript durchgeführt werden
- Bei Regex-Änderungen: Performance-Impact beachten (werden für jede Datei ausgeführt)