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

# Development build
cargo build

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

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

# 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

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

# Vorschau (keine Änderungen):
cargo run -- -n ./testverzeichnis
# oder mit installierter Binary:
ntu -n ./testverzeichnis

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

# Mit Verbose-Ausgabe:
cargo run -- -v ./testverzeichnis
# oder:
ntu -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, --dry-run (alias: --no-changes), --force, --exclude, --verbose, --modify-root, --special
  • ArgGroup verhindert gleichzeitige Nutzung von --dry-run 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.

6. Smart Default-Excludes: .git, .svn, node_modules, .cache, __pycache__ werden automatisch ignoriert (ähnlich wie detox).

7. Doppel-Extensions: .tar.gz, .tar.bz2, .tar.xz etc. werden korrekt als Einheit behandelt (nicht nur .gz).

8. Versteckte Dateien: Dateien mit führendem Punkt (.gitignore) bleiben unverändert, der Punkt wird korrekt behandelt.

9. Special Files: Symlinks und Special Files werden standardmäßig übersprungen, außer --special 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)