🦌 AOC Rustdolph

Framework Rust pour Advent of Code - Automatisation du scaffolding, téléchargement des inputs et exécution des solutions.

📋 Table des matières

• Fonctionnalités
• Prérequis
• Installation
• Configuration
• Utilisation
  • Initialiser le workspace
  • Créer un scaffold
  • Résoudre le challenge
  • Exécuter une solution
• Structure du projet
• Raccourcis pratiques
• Contribuer
• Licence

✨ Fonctionnalités

• 🚀 Scaffolding automatique : génération de la structure de projet pour chaque jour
• 📥 Téléchargement automatique : récupère les inputs depuis adventofcode.com
• ⏱️ Benchmarking intégré : mesure automatique du temps d'exécution
• 🧪 Tests prêts à l'emploi : template de tests avec fichier example.txt
• 🔧 CLI intuitive : commandes simples via l'outil mush
• 📦 Workspace Cargo : organisation propre en monorepo

🛠️ Prérequis

• Rust 1.83+ (avec Cargo)
• Un compte sur Advent of Code

📦 Installation

# Cloner le repository
git clone https://github.com/cmoron/aoc-rustdolph.git
cd aoc-rustdolph

# Vérifier que Rust est installé
cargo --version

# (Recommandé) Installer mush globalement pour l'utiliser partout
cargo install --path mush

⚙️ Configuration

Récupérer votre cookie de session

1. Connectez-vous sur adventofcode.com
2. Ouvrez les outils de développement de votre navigateur (F12)
3. Allez dans l'onglet Application > Cookies
4. Copiez la valeur du cookie session

Créer le fichier .env

Créez un fichier .env à la racine du projet :

AOC_SESSION=votre_cookie_de_session_ici

⚠️ Important : Ne commitez jamais votre fichier .env (déjà dans .gitignore)

🎯 Utilisation

1. Initialiser le workspace (optionnel)

💡 Astuce : Installez d'abord mush globalement avec cargo install --path mush pour des commandes plus courtes.

Si le projet n'est pas déjà initialisé :

mush init
# ou : cargo run -p mush -- init

Cela crée :

• Cargo.toml (configuration du workspace)
• .gitignore (fichiers à ignorer)
• .env (template pour le cookie de session)

2. Créer un scaffold pour un jour

# Pour le jour 1 de l'année en cours
mush scaffold -d 1

# Pour une année spécifique
mush scaffold -d 1 -y 2015

# Vous pouvez aussi spécifier n'importe quel jour (1-25)
mush scaffold -d 25 -y 2024

# Sans installation globale :
# cargo run -p mush -- scaffold -d 1

Cette commande génère :

solutions/2024/day01/
├── Cargo.toml
├── input.txt          # ✅ Téléchargé automatiquement
├── example.txt        # À remplir avec l'exemple du challenge
└── src/
    └── main.rs        # Template avec part1(), part2() et tests

3. Résoudre le challenge

Ouvrez solutions/{année}/day{XX}/src/main.rs et implémentez :

fn part1(input: &str) -> String {
    // Votre solution pour la partie 1
    "42".to_string()
}

fn part2(input: &str) -> String {
    // Votre solution pour la partie 2
    "1337".to_string()
}

4. Exécuter la solution

# Mode Debug (compilation rapide, exécution plus lente)
mush run -d 1

# Mode Release (compilation plus lente, exécution ultra-rapide)
mush run -d 1 -r

# Sans installation globale :
# cargo run -p mush -- run -d 1 -r

Sortie typique :

Part 1: 42
Time: 0.0023ms
Part 2: 1337
Time: 0.0156ms

Tester vos solutions

# Depuis la racine
cargo test -p day01-2024

# Ou depuis le répertoire du jour
cd solutions/2024/day01
cargo test

Lancer les tests du framework

Le projet inclut une suite complète de tests unitaires pour l'outil mush :

# Lancer tous les tests
cargo test -p mush

# Lancer les tests avec des détails
cargo test -p mush -- --nocapture

# Lancer un test spécifique
cargo test -p mush test_create_scaffold_structure

Tests couverts :

• ✅ Création de fichiers (create_file)
• ✅ Initialisation du workspace (initialize_workspace)
• ✅ Génération de scaffolds (create_scaffold)
• ✅ Téléchargement d'inputs HTTP avec mocking (fetch_input)
• ✅ Validation de non-écrasement des fichiers existants

📚 Pour plus de détails sur les tests, consultez le Guide des Tests

📁 Structure du projet

aoc-rustdolph/
├── Cargo.toml              # Configuration du workspace
├── .env                    # Cookie de session (à créer)
├── .gitignore
├── LICENSE
├── README.md
├── mush/                   # Outil CLI
│   ├── Cargo.toml
│   └── src/
│       └── main.rs         # Logique de scaffolding et d'exécution
└── solutions/              # Solutions par année
    ├── 2024/
    │   ├── day01/
    │   │   ├── Cargo.toml
    │   │   ├── input.txt
    │   │   ├── example.txt
    │   │   └── src/
    │   │       └── main.rs
    │   └── day02/
    │       └── ...
    └── 2023/
        └── ...

💡 Installation globale (recommandée)

Pour utiliser mush directement sans cargo run -p, installez-le globalement :

# Depuis la racine du projet
cargo install --path mush

# Vérifier l'installation
mush --version

L'exécutable sera installé dans ~/.cargo/bin/ (déjà dans votre PATH si Rust est correctement installé).

Utilisation après installation

# Initialiser un nouveau projet
mush init

# Créer un scaffold
mush scaffold -d 5
mush scaffold -d 1 -y 2023

# Lancer une solution
mush run -d 5
mush run -d 5 -r    # Mode release

Avantages :

• ✅ Commandes plus courtes et idiomatiques
• ✅ Disponible depuis n'importe quel répertoire
• ✅ Pas besoin d'être dans le workspace
• ✅ Mises à jour simples : cargo install --path mush --force

Alternative : Alias shell

Si vous préférez ne pas installer globalement, vous pouvez créer des alias :

# Dans ~/.bashrc ou ~/.zshrc
alias mush='cargo run -p mush --'

🤝 Contribuer

Les contributions sont les bienvenues ! N'hésitez pas à :

• Ouvrir une issue pour signaler un bug
• Proposer une pull request pour ajouter une fonctionnalité
• Améliorer la documentation

📄 Licence

Ce projet est sous licence MIT. Voir le fichier LICENSE pour plus de détails.

---

Bon code ! 🎄✨

Créé avec ❤️ pour faciliter les défis Advent of Code