DTLcode — Manuel de référence v1.7-3
Référence fonctionnelle et technique de l'analyseur heuristique de fichiers source.
Objet et portée
DTLcode produit une vue d'ensemble fonctionnelle d'un fichier source inconnu. Il identifie son langage, observe sa structure, relève ses principales interactions et génère une page HTML expliquant à quoi le fichier semble servir et comment il obtient ses résultats.
Le logiciel est destiné à la découverte rapide d'un patrimoine applicatif, à la préparation d'un audit ou d'une documentation et à l'orientation d'un mainteneur avant une analyse détaillée.
Principes structurants
- Prudence : les formulations décrivent un rôle probable et évitent de présenter une déduction comme une certitude.
- Lisibilité : le rapport privilégie des explications simples plutôt qu'une documentation exhaustive du code.
- Observation : les descriptions de sous-routines reposent sur les opérations présentes dans leur corps, sans répéter leur nom.
- Autonomie : la page HTML contient son style et ne dépend d'aucun serveur.
- Déduplication : les listes sont nettoyées, limitées et débarrassées des répétitions.
Architecture
Chaîne d'analyse
La fonction d'orchestration crée un objet AnalysisResult, alimente ses champs par étapes, puis le transmet au générateur HTML. Le cœur ne dépend ni du terminal ni de la boîte de dialogue utilisée pour choisir le fichier.
Organisation des fichiers
DTLcode.py
Implémentation complète : lecture, analyse, inférence fonctionnelle, génération HTML et interface de lancement.
DTLcode.spec
Recette PyInstaller produisant l'exécutable Windows autonome DTLcode.exe.
README_Fr.md / README.md
Présentation courte, exemples et limites dans les deux langues de documentation.
Modèle de résultat
AnalysisResult centralise les faits observés et les déductions. Il contient les métadonnées du fichier, les structures de code, les ressources, les interactions, les avertissements, les éléments d'utilisation et les lignes du tableau des sous-routines.
| Famille | Champs représentatifs | Finalité |
|---|---|---|
| Fichier | chemin, langage, taille, encodage, lignes | Identifier précisément la cible analysée. |
| Structure | variables, constantes, imports, fonctions, classes | Présenter les principaux composants. |
| Comportement | objectif, flux de traitement, entrées, résultats | Expliquer le rôle fonctionnel probable. |
| Intégrations | fichiers, URL, réseau, base de données, commandes | Montrer les dépendances et effets externes observés. |
| Robustesse | gestion d'erreurs, avertissements | Signaler les protections et les limites de l'analyse. |
Référence de l'analyse
Langages et extensions reconnus
| Famille | Extensions |
|---|---|
| Python | .py, .pyw |
| PowerShell | .ps1, .psm1, .psd1 |
| Web | .php, .js, .mjs, .cjs, .ts, .tsx, .jsx, .html, .htm, .css, .scss, .sass |
| Scripts | .bat, .cmd, .sh, .bash, .zsh, .vbs |
| Données | .sql, .json, .yaml, .yml, .xml, .ini, .toml |
| Compilés et autres | .java, .c, .h, .cpp, .cc, .hpp, .cs, .go, .rs, .rb, .pl, .lua |
Une extension inconnue déclenche l'analyse générique et ajoute un avertissement au rapport.
Extraction commune
Des motifs réguliers recherchent les URL, chemins de fichiers, commandes système, accès réseau ou base de données, interactions utilisateur et constructions de gestion d'erreurs. Les commentaires utiles sont extraits selon la syntaxe du langage et limités aux éléments suffisamment significatifs.
Traitement spécialisé de Python
Python bénéficie d'une analyse syntaxique avec le module standard ast. DTLcode relève les imports, classes, fonctions, affectations globales et valeurs simples sans exécuter le programme. Pour les recherches communes, les chaînes littérales et commentaires peuvent être neutralisés afin de réduire les faux positifs.
Description des sous-routines
Le tableau des sous-routines contient un intitulé fonctionnel et une description d'une ou deux phrases. La description ne reprend jamais le nom technique : elle est construite à partir d'opérations observées telles que lecture ou écriture de fichier, analyse syntaxique, recherche de motifs, validation, interaction utilisateur, lancement de commande ou génération HTML.
Lorsque le rôle précis ne peut pas être établi, le rapport décrit sobrement le parcours, les conditions ou la valeur renvoyée. Les petits utilitaires internes sont exclus pour préserver la lisibilité.
Rapport HTML
Rubriques produites
- en-tête avec fichier, chemin, langage, nombre de lignes, taille et encodage ;
- objectif probable et étapes de traitement ;
- tableau accessible des sous-routines principales ;
- interface, ressources, gestion des erreurs et avertissements ;
- syntaxe d'utilisation, paramètres et résultats attendus ;
- note rappelant le caractère heuristique de la synthèse.
La mise en page est responsive, imprimable et lisible sans JavaScript. Les rubriques vides sont omises.
Sécurité du rendu
Tout contenu provenant du fichier analysé est échappé avec html.escape avant insertion. Une balise ou un script présent dans le source apparaît donc comme du texte dans le rapport et ne devient pas du contenu HTML actif.
Interface et codes de retour
Ligne de commande
Sans argument source, une boîte de dialogue Windows permet de choisir le fichier. Sans option de sortie, le rapport est écrit dans DTLcode_report.html, puis ouvert avec l'application associée lorsque le système le permet.
Codes de sortie
| Code | Signification |
|---|---|
| 0 | Rapport créé, version affichée ou sélection de fichier annulée. |
| 1 | Erreur de lecture, d'écriture, de boîte de dialogue ou erreur système. |
| 2 | Le chemin source n'existe pas ou ne désigne pas un fichier. |
Exploitation et maintenance
Encodages de lecture
La lecture essaie successivement UTF-8 avec BOM, UTF-8, Windows-1252 et Latin-1. L'encodage retenu est affiché dans le rapport. La page de sortie est toujours enregistrée en UTF-8.
Construction PyInstaller
La spécification construit un exécutable console monofichier. Conformément aux règles du projet, toute reconstruction doit être précédée d'une incrémentation du correctif de version et de sa propagation dans le code, les métadonnées, les tests et la documentation concernés.
Limites connues
- L'analyse est heuristique : elle ne remplace pas un compilateur, un parseur complet ni une revue humaine.
- Le langage est déduit de l'extension, pas du contenu réel du fichier.
- Le code dynamique, les métaprogrammes et les appels construits à l'exécution sont difficiles à interpréter statiquement.
- Les analyses non Python utilisent principalement des expressions régulières et disposent de moins de contexte syntaxique.
- Au-delà de 5 000 lignes, le rapport reste volontairement synthétique et affiche un avertissement.