# Markdown Parser - Analyseur et Restructurateur de Fichiers Markdown Un outil professionnel écrit en Nim pour l'analyse, l'enrichissement et la restructuration automatisée de fichiers Markdown avec gestion intelligente des métadonnées YAML et intégration IA. ## 📋 Description Technique **Markdown Parser** est une application CLI modulaire conçue pour automatiser la gestion des métadonnées dans les documents Markdown. L'outil analyse récursivement des répertoires, extrait ou génère des métadonnées structurées (titre, description, tags, catégories), et enrichit les fichiers avec des informations normalisées tout en préservant le contenu original. **Cas d'utilisation principaux:** - Normalisation des bibliothèques de documentation Markdown - Enrichissement automatique des métadonnées via IA - Organisation catégorielle basée sur la structure des répertoires - Génération de rapports d'analyse et de qualité - Préparation de contenu pour les systèmes de gestion de connaissances ## 🏗️ Architecture & Stack Technique ### Stack Technologique - **Langage:** Nim 1.6+ (compilation native, performances élevées) - **Gestion de dépendances:** Nimble - **Modules principaux:** - `std/httpclient` pour les appels API IA - `std/json` pour le parsing de configuration - `std/os` pour les opérations fichiers - `zippy` pour la compression ZIP - **Intégration IA:** Compatible LM Studio, OpenAI API, Ollama ### Architecture Modulaire ```mermaid graph TB A[Interface CLI] --> B[Contrôleur Principal] B --> C[Gestionnaire Configuration] B --> D[Orchestrateur Traitement] C --> E[Chargement Config] C --> F[Validation Modèles] D --> G[Pipeline Traitement] G --> H[Extracteur Métadonnées] G --> I[Générateur IA] G --> J[Validateur YAML] G --> K[Écrivain Fichiers] H --> L[Parseur YAML] H --> M[Extracteur Titre] I --> N[Client HTTP] N --> O[API LM Studio] K --> P[Système Fichiers] Q[Configuration JSON] --> C R[Logs Debug] --> S[Système Logging] ``` ### Modules du Projet ``` markdown_parser/ ├── markdown_parser.nim # Point d'entrée CLI et orchestration ├── modules/ │ ├── config.nim # Gestion configuration (JSON, modèles IA) │ ├── metadata.nim # Extraction/génération métadonnées YAML │ ├── fileutils.nim # Opérations fichiers/répertoires │ └── report.nim # Génération rapports de traitement ├── build.nim # Système de build et versionnement ├── version.nim # Gestion des versions (MAJOR.MINOR.PATCH.BUILD) ├── config.json # Configuration utilisateur (API, modèles) └── test_data/ # Données de test et exemples ``` ### Flux de Données 1. **Entrée:** Répertoire source ou liste de fichiers Markdown 2. **Validation:** Vérification des chemins, disponibilité modèle IA 3. **Backup:** Création automatique d'archive ZIP de sauvegarde 4. **Traitement par fichier:** - Extraction métadonnées YAML existantes - Génération IA des métadonnées manquantes (optionnel) - Nettoyage et validation des tags - Attribution automatique de catégorie basée sur le chemin - Mise à jour des dates de création/modification 5. **Sortie:** Fichiers enrichis dans la structure cible + rapport détaillé ## 🚀 Installation et Déploiement ### Prérequis Système - **Nim** version 1.6.0 ou supérieure - **LM Studio** (optionnel) pour l'analyse IA locale - **Git** pour le contrôle de version ### Installation Rapide ```bash # 1. Cloner le dépôt git clone https://github.com/votre-utilisateur/markdown_parser.git cd markdown_parser # 2. Installer les dépendances Nimble nimble install zippy # 3. Configurer l'API IA (optionnel) cp config.example.json config.json # Éditer config.json avec vos paramètres d'API # 4. Compiler avec le système de build nim c build.nim ./build.exe ``` ### Configuration Le fichier `config.json` supporte plusieurs modèles IA: ```json { "debugModeActive": false, "apiUrl": "http://localhost:2222/v1/chat/completions", "apiMonitorUrl": "http://localhost:2222/v1/models", "activeModelName": "gemma-3-4b-it", "models": [ { "name": "gemma-3-4b-it", "systemRole": "system", "systemContent": "Vous êtes un assistant spécialisé dans l'analyse de contenu Markdown...", "userRole": "user", "userContentTemplate": "Analysez ce document Markdown...", "isActive": true } ] } ``` **⚠️ Sécurité:** Ne commitez jamais `config.json` avec des URLs de production ou des clés API. Utilisez des variables d'environnement ou un fichier de configuration externe. ### Compilation Avancée ```bash # Compilation manuelle (debug) nim c markdown_parser.nim # Compilation release optimisée nim c -d:release --opt:speed markdown_parser.nim # Utilisation du système de build intégré ./build.exe # Incrémente le numéro de build ./build.exe minor # Incrémente la version mineure ./build.exe major # Incrémente la version majeure ``` ## 📖 Utilisation ### Commandes de Base ```bash # Afficher l'aide ./markdown_parser --help # Afficher la version ./markdown_parser --version # Traiter un répertoire complet ./markdown_parser --source=./documents --verbose # Traiter des fichiers spécifiques ./markdown_parser --files=doc1.md,doc2.md,doc3.md # Activer l'analyse IA pour générer les métadonnées manquantes ./markdown_parser --source=./docs --analyze --verbose # Mode verbeux avec sauvegarde automatique ./markdown_parser -s=./content -V -a ``` ### Options de la Ligne de Commande | Option | Description | Exemple | |--------|-------------|---------| | `-h, --help` | Affiche le message d'aide | `--help` | | `-v, --version` | Affiche la version du programme | `--version` | | `-V, --verbose` | Mode verbeux (détails du traitement) | `-V` | | `-s, --source=PATH` | Répertoire source à traiter | `-s=./docs` | | `-f, --files=LIST` | Liste de fichiers spécifiques | `-f=file1.md,file2.md` | | `-a, --analyze` | Active l'analyse IA des fichiers sans métadonnées | `--analyze` | ### Format des Métadonnées Générées ```yaml --- Titre: Introduction à la Programmation Nim Description: Guide complet pour débuter avec le langage de programmation Nim tags: - nim - programmation - guide - debutant Date de création: 2025-03-15 Heure de création: 14:30:22 Date de modification: 2025-03-17 Heure de modification: 16:45:10 Auteur: Non spécifié URL: Lang: fr Catégorie: documentation/technique/nim --- ``` ## 🔧 Guide du Développeur ### Structure des Types de Données ```nim type Metadata* = object title*: string description*: string tags*: seq[string] creationDate*: string creationTime*: string modificationDate*: string modificationTime*: string auteur*: string url*: string lang*: string category*: string isNew*: bool AppConfig* = object apiUrl*: string apiMonitorUrl*: string models*: seq[LLMModelConfig] activeModelName*: string debugModeActive*: bool ``` ### Extension du Projet #### Ajouter un Nouveau Format de Sortie 1. Créer un module `modules/exporters.nim` 2. Implémenter l'interface d'exportation: ```nim proc exportToJson(metadata: Metadata): string = return $(%metadata) proc exportToHtml(metadata: Metadata): string = return fmt"""

{metadata.title}

{metadata.description}

""" ``` #### Intégrer un Nouveau Fournisseur IA 1. Étendre `modules/config.nim` avec le nouveau modèle 2. Adapter `modules/metadata.nim::analyzeWithAI`: ```nim proc analyzeWithOpenAI(content: string, apiKey: string): AIAnalysisResult = # Implémentation spécifique à OpenAI discard ``` ### Tests et Qualité ```bash # Créer un environnement de test mkdir -p test/source test/target # Générer des fichiers de test echo "# Test Document" > test/source/doc1.md echo "---\nTitre: Test\n---\nContent" > test/source/doc2.md # Exécuter le traitement ./markdown_parser -s=test/source -t=test/target -V # Vérifier les résultats ls -la test/target/ cat test/target/doc1.md ``` ## 🗺️ Roadmap et Évolutions Futures ### Phase 1: Sécurité et Robustesse (Q2 2026) - [ ] Externalisation de la configuration sensible (variables d'environnement) - [ ] Validation renforcée des chemins d'accès (prévention directory traversal) - [ ] Implémentation des timeouts HTTP configurables - [ ] Chiffrement optionnel des sauvegardes ZIP - [ ] Audit de sécurité des dépendances (zippy, httpclient) ### Phase 2: Performance et Évolutivité (Q3 2026) - [ ] Traitement parallèle des fichiers (async/await) - [ ] Cache des résultats d'analyse IA (basé sur hash SHA1) - [ ] Support des gros fichiers (>10MB) avec traitement streamé - [ ] Compression intelligente des sauvegardes (différentielle) - [ ] Métriques de performance intégrées (temps de traitement, taux de succès) ### Phase 3: Nouvelles Fonctionnalités (Q4 2026) - [ ] **Support multi-format de sortie:** JSON, YAML standalone, HTML, XML - [ ] **Interface web de prévisualisation:** Serveur HTTP léger + interface React - [ ] **Système de plugins extensible:** Architecture à base de interfaces - [ ] **Validation par schéma YAML:** Garantie de la qualité des métadonnées - [ ] **Synchronisation avec bases de données:** SQLite, PostgreSQL, Elasticsearch ### Phase 4: Intégration et Écosystème (Q1 2027) - [ ] **API REST complète:** Pour l'intégration avec d'autres outils - [ ] **Intégrations cloud:** AWS S3, Google Drive, GitHub API - [ ] **Workflows automatisés:** Déclencheurs basés sur les événements de fichiers - [ ] **Dashboard d'analyse:** Visualisation des métriques de qualité des documents - [ ] **Export vers systèmes de gestion de contenu:** WordPress, Ghost, Notion ### Fonctionnalités en Cours d'Évaluation - **OCR intégré** pour l'extraction de texte depuis les images/PDF - **Analyse sémantique avancée** pour la suggestion de tags contextuels - **Détection de duplication** de contenu entre documents - **Traduction automatique** des métadonnées (multilangue) - **Générateur de résumés** avec différents niveaux de détail ## 📊 Métriques de Qualité | Indicateur | Valeur Actuelle | Cible | Statut | |------------|----------------|-------|--------| | Couverture de code | 0% | ≥ 80% | ⚠️ À implémenter | | Complexité cyclomatique moyenne | 15.2 | ≤ 10 | 🔄 Amélioration nécessaire | | Temps de traitement/fichier | 2.1s | ≤ 0.5s | 🔄 Optimisation requise | | Taux de duplication | 12% | ≤ 5% | ✅ Acceptable | | Vulnérabilités de sécurité critiques | 3 | 0 | 🚨 Action requise | ## 🤝 Contribution Les contributions sont les bienvenues! Veuillez suivre le processus: 1. Fork du projet 2. Créer une branche (`git checkout -b feature/amélioration`) 3. Commiter les changements (`git commit -am 'Ajout d'une fonctionnalité'`) 4. Pusher la branche (`git push origin feature/amélioration`) 5. Ouvrir une Pull Request ### Standards de Code - Suivre les [conventions Nim](https://nim-lang.org/docs/nep1.html) - Documenter les procédures avec des commentaires de documentation - Inclure des tests pour les nouvelles fonctionnalités - Mettre à jour la documentation correspondante ## 📄 Licence Ce projet est sous licence MIT. Voir le fichier `LICENSE` pour plus de détails. ## 🔗 Ressources - [Documentation Nim](https://nim-lang.org/documentation.html) - [LM Studio API Reference](https://lmstudio.ai/docs) - [YAML Specification](https://yaml.org/spec/) - [Markdown Guide](https://www.markdownguide.org/) ## 📞 Support Pour les questions, problèmes ou suggestions: 1. Consulter les [Issues GitHub](https://github.com/votre-utilisateur/markdown_parser/issues) 2. Vérifier la [documentation technique](docs/) 3. Contacter l'équipe de développement via les discussions GitHub --- *Dernière mise à jour: Avril 2026 | Version: 1.0.0.97*