Table of Contents

• Automatiser l’analyse des fichiers et dossiers pour générer des données structurées
• Considérer le système de fichiers comme une source de données
• Recursive Structure Extraction
• Enforcing Conventions and Constraints
• Generating Usable Output
• Why This Pattern Works

Les projets web modernes accumulent souvent de vastes répertoires d’assets profondément imbriqués. Avec le temps, ces structures de dossiers commencent à encoder des informations utiles — catégories, variations, conventions — mais ces informations restent implicites et difficiles à exploiter de manière programmatique.

Cet article présente une approche pratique pour analyser un système de fichiers, détecter des schémas structurels et les convertir en données JSON structurées pouvant être utilisées par des outils de build, du code à l’exécution ou des pipelines de contenu.

Plutôt que de maintenir manuellement des manifestes d’assets, ce script considère la hiérarchie des dossiers elle-même comme la source de vérité. En parcourant récursivement les dossiers et en appliquant un petit ensemble de règles, il est possible de dériver automatiquement une structure de données propre et prévisible.

À un niveau global, le script:

• Limite le parcours à un ensemble connu de répertoires racines
• Parcourt récursivement les sous-dossiers
• Filtre les fichiers indésirables
• Normalise les noms de fichiers
• Génère un résumé JSON structuré de la hiérarchie des dossiers
• Cette approche s’adapte naturellement à la croissance des assets et évite la duplication de configuration

Le cœur de la solution repose sur une fonction récursive de parcours de répertoires. Chaque dossier est analysé afin de déterminer s’il contient uniquement des fichiers, uniquement des sous-dossiers, ou un mélange des deux :

Les dossiers ne contenant que des fichiers deviennent des tableaux

Les dossiers contenant des sous-dossiers deviennent des objets

Les fichiers peuvent être regroupés sous une clé files lorsqu’ils coexistent avec des dossiers

Cette distinction permet de conserver un JSON compact tout en préservant la signification sémantique.

function getDirectoryStructure(dirPath) {
  const items = fs.readdirSync(dirPath, { withFileTypes: true });

  const files = [];
  const folders = {};

  for (const item of items) {
    const fullPath = path.join(dirPath, item.name);

    if (item.isDirectory()) {
      folders[item.name] = getDirectoryStructure(fullPath);
    } else if (item.isFile()) {
      if (item.name.startsWith('_')) continue;
      if (item.name === 'Credits.txt') continue;
      if (item.name.endsWith(ext)) {
        item.name = item.name.slice(0, -5);
      }
      files.push(item.name);
    }
  }

  if (Object.keys(folders).length === 0) {
    return files;
  }

  if (files.length > 0) {
    folders.files = files;
  }

  return folders;
}

Le script limite volontairement le parcours à un ensemble prédéfini de répertoires racines:

const allowedRootKeys = new Set(["FX", "Objects", "Structure", "Terrain"])

Cette contrainte empêche l’inclusion accidentelle de fichiers non pertinents et impose un contrat d’organisation clair. Les règles de filtrage (comme l’exclusion des fichiers privés ou de métadonnées telles que Credits.txt) affinent davantage la sortie et garantissent que les données générées soient immédiatement exploitables.

Une fois le parcours terminé, la structure résultante est sérialisée en JSON et écrite sur le disque:

fs.writeFile(`./src/scripts/data/${filename}`, data, 'utf8', ...)

Cette sortie peut ensuite être consommée par:

Chargeurs d’assets

Moteurs de jeu

Pipelines de build

Outils d’interface utilisateur

Étapes d’analyse statique ou de validation

Comme le JSON est généré automatiquement, il reste toujours synchronisé avec le système de fichiers sous-jacent.

Cette approche met en évidence une idée plus large : les systèmes de fichiers contiennent déjà des données structurées — il suffit de les formaliser. En automatisant l’analyse et en imposant des règles simples et cohérentes, on peut éliminer les manifestes manuels, réduire les erreurs et rendre les projets de grande taille plus faciles à comprendre et à maintenir.

À mesure que les projets évoluent, ce type d’automatisation transforme une structure implicite en données explicites et fiables — et c’est là que commence la véritable scalabilité.