feat: Add detailed JSDoc comments to ExtensionsModule and service setup for improved documentation

Author: tacxou

apps/api/src/extensions/extensions.module.ts

@@ -1,26 +1,97 @@
-import { DynamicModule, Logger, Module, OnModuleInit } from '@nestjs/common'
+import { DynamicModule, Logger, Module, OnApplicationBootstrap, OnModuleInit } from '@nestjs/common'
 import { RouterModule } from '@nestjs/core'
-import { isConsoleEntrypoint } from '~/_common/functions/is-cli'
 import serviceSetup from '~/extensions/extensions.service.setup'
 
+/**
+ * Module de gestion et de chargement des extensions.
+ *
+ * Ce module gère le système de plugins/extensions de l'application, permettant
+ * de charger dynamiquement des modules personnalisés qui enrichissent les
+ * fonctionnalités sans modifier le code source principal. Les extensions sont
+ * chargées au démarrage selon la configuration définie dans list.yml.
+ *
+ * @module ExtensionsModule
+ * @implements {OnModuleInit}
+ * @implements {OnApplicationBootstrap}
+ *
+ * @description
+ * Fonctionnalités du système d'extensions :
+ * - Chargement dynamique des modules d'extension au démarrage
+ * - Isolation des extensions dans leurs propres modules
+ * - Configuration centralisée via list.yml et extension.yml
+ * - Support des extensions côté service (backend) et application (frontend)
+ * - Activation/désactivation des extensions sans suppression
+ * - Routage automatique sous le préfixe '/extensions'
+ *
+ * Comportement selon le contexte :
+ * - **Mode service** : Charge toutes les extensions activées depuis list.yml
+ * - **Mode console** : Ignore le chargement des extensions pour optimiser les performances
+ *
+ * Processus de chargement :
+ * 1. Lecture du fichier list.yml
+ * 2. Filtrage des extensions activées
+ * 3. Chargement de chaque extension.yml
+ * 4. Import dynamique des modules définis
+ * 5. Enregistrement des routes sous '/extensions'
+ */
 @Module({
   imports: [],
 })
-export class ExtensionsModule implements OnModuleInit {
+export class ExtensionsModule implements OnModuleInit, OnApplicationBootstrap {
+  /**
+   * Hook de cycle de vie appelé après l'initialisation du module.
+   *
+   * Enregistre un message de log confirmant que toutes les extensions
+   * ont été initialisées avec succès.
+   *
+   * @async
+   * @returns {Promise<void>}
+   */
   public async onModuleInit(): Promise<void> {
-    Logger.log('All extensions is initialized', 'ExtensionsModule')
+    Logger.log('All extensions is initialized', ExtensionsModule.name)
   }
 
-  public static async register(): Promise<DynamicModule> {
-    if (isConsoleEntrypoint) {
-      Logger.verbose('Console entrypoint detected, skipping extensions registration', 'ExtensionsModule')
-      return {
-        module: this,
-        imports: [],
-      }
-    }
+  /**
+   * Hook de cycle de vie appelé après le démarrage complet de l'application.
+   *
+   * Enregistre un message de log confirmant que toutes les extensions
+   * ont été enregistrées et sont prêtes à être utilisées.
+   *
+   * @async
+   * @returns {Promise<void>}
+   */
+  public async onApplicationBootstrap(): Promise<void> {
+    Logger.log('Extensions registered !', ExtensionsModule.name)
+  }
 
-    Logger.debug('Registering extensions', 'ExtensionsModule')
+  /**
+   * Enregistre le module Extensions en mode dynamique avec chargement des extensions.
+   *
+   * Cette méthode asynchrone charge dynamiquement toutes les extensions activées
+   * depuis le fichier de configuration list.yml et configure le routage automatique.
+   *
+   * @static
+   * @async
+   * @returns {Promise<DynamicModule>} Le module configuré avec les extensions chargées
+   *
+   * @description
+   * Processus détaillé :
+   * 1. Vérifie si l'application est lancée en mode console
+   *    - Si oui : Ignore le chargement des extensions (retour module vide)
+   *    - Si non : Continue le chargement
+   * 2. Appelle serviceSetup() qui :
+   *    - Lit le fichier list.yml
+   *    - Charge chaque extension activée
+   *    - Import dynamiquement les modules
+   * 3. Configure le RouterModule pour préfixer toutes les routes par '/extensions'
+   * 4. Retourne le module dynamique avec toutes les extensions importées
+   *
+   * Logging :
+   * - Mode console : Log verbose indiquant que les extensions sont ignorées
+   * - Mode service : Log debug au début du chargement
+   * - Fin d'initialisation : Log info via onModuleInit()
+   */
+  public static async register(): Promise<DynamicModule> {
     const modules = await serviceSetup()
 
     return {

apps/api/src/extensions/extensions.service.setup.ts

@@ -8,11 +8,42 @@ import { validateOrReject } from 'class-validator'
 import * as process from 'process'
 import { DynamicModule, Logger } from '@nestjs/common'
 
+/**
+ * Liste des modules d'extension chargés dynamiquement.
+ * @type {DynamicModule[]}
+ */
 const serviceList: DynamicModule[] = []
 
+/**
+ * Nom du fichier de configuration d'une extension.
+ * @constant {string}
+ */
 export const EXTENSION_FILE_INFO = 'extension.yml'
+
+/**
+ * Chemin vers le fichier de liste des extensions.
+ * @constant {string}
+ */
 export const EXTENSIONS_FILE_PATH = join(process.cwd(), '/extensions/list.yml')
 
+/**
+ * Parse et valide le fichier de liste des extensions.
+ *
+ * Lit le fichier list.yml, le valide selon le schéma ExtensionsFileV1
+ * et retourne la liste des extensions configurées.
+ *
+ * @async
+ * @returns {Promise<ExtensionsListV1[]>} Liste des extensions avec leur configuration
+ * @throws {Error} Si le fichier est invalide ou ne respecte pas le schéma
+ *
+ * @description
+ * Processus de validation :
+ * 1. Lecture du fichier list.yml
+ * 2. Parsing YAML en objet JavaScript
+ * 3. Transformation en instance de classe avec class-transformer
+ * 4. Validation du schéma avec class-validator
+ * 5. Retour de la liste des extensions si valide
+ */
 export async function parseExtensionsList(): Promise<ExtensionsListV1[]> {
   const data = readFileSync(EXTENSIONS_FILE_PATH, 'utf8')
   const yml = parse(data)
@@ -30,13 +61,66 @@ export async function parseExtensionsList(): Promise<ExtensionsListV1[]> {
   return yml.list
 }
 
+/**
+ * Parse et valide le fichier de configuration d'une extension.
+ *
+ * Lit le fichier extension.yml d'une extension spécifique et le valide
+ * selon le schéma ExtensionFileV1.
+ *
+ * @async
+ * @param {string} path - Chemin vers le répertoire de l'extension
+ * @returns {Promise<ExtensionFileV1>} Configuration complète de l'extension
+ * @throws {Error} Si le fichier n'existe pas ou est invalide
+ *
+ * @description
+ * Cette fonction :
+ * 1. Lit le fichier extension.yml dans le répertoire spécifié
+ * 2. Parse le contenu YAML
+ * 3. Transforme en instance ExtensionFileV1
+ * 4. Retourne la configuration validée
+ */
 export async function extensionParseFile(path: string): Promise<ExtensionFileV1> {
   Logger.log('Extension file found, validating...', 'extensionParseFile')
   const data = readFileSync(`${path}/${EXTENSION_FILE_INFO}`, 'utf8')
   const yml = parse(data)
   return plainToInstance(ExtensionFileV1, yml)
 }
 
+/**
+ * Fonction principale de configuration et chargement des extensions.
+ *
+ * Cette fonction asynchrone charge toutes les extensions activées depuis
+ * le fichier list.yml et retourne les modules prêts à être importés par NestJS.
+ *
+ * @async
+ * @default
+ * @returns {Promise<DynamicModule[]>} Liste des modules d'extension chargés
+ *
+ * @description
+ * Processus de chargement complet :
+ * 1. Vérifie l'existence du fichier list.yml
+ * 2. Parse et valide la liste des extensions
+ * 3. Pour chaque extension activée :
+ *    a. Lit et valide son fichier extension.yml
+ *    b. Vérifie qu'elle a une cible service définie
+ *    c. Import dynamiquement le module depuis le chemin spécifié
+ *    d. Récupère le module principal (par défaut 'ExtensionModule')
+ *    e. Ajoute le module à la liste
+ * 4. Retourne tous les modules chargés
+ *
+ * Gestion des erreurs :
+ * - Extension désactivée : Log et skip
+ * - Pas de cible service : Warning et skip
+ * - Module principal introuvable : Warning et skip
+ * - Erreur de chargement : Error log avec trace
+ * - Erreur critique : Exit du processus avec code 1
+ *
+ * Logging détaillé :
+ * - Info : Fichier trouvé, validation en cours
+ * - Info : Extension activée avec succès
+ * - Warning : Extension désactivée ou configuration incomplète
+ * - Error : Échec de chargement avec stack trace
+ */
 export default async function (): Promise<DynamicModule[]> {
   try {
     if (existsSync(EXTENSIONS_FILE_PATH)) {