feat: Add detailed JSDoc comments to logging functions and console entry point for improved documentation

Author: tacxou

apps/api/src/_common/functions/get-log-level.ts

@@ -1,5 +1,41 @@
-import { LogLevel } from '@nestjs/common';
+import { LogLevel } from '@nestjs/common'
 
+/**
+ * Retourne un tableau de niveaux de log NestJS basé sur le niveau spécifié.
+ *
+ * Cette fonction implémente une hiérarchie de log cumulative où chaque niveau
+ * inclut automatiquement tous les niveaux plus critiques. Par exemple, le niveau
+ * "warn" inclura également "error" et "fatal".
+ *
+ * @param {string} [logLevel] - Niveau de log souhaité ('fatal', 'error', 'warn', 'info', 'debug', 'verbose')
+ * @returns {LogLevel[]} Tableau des niveaux de log activés pour ce niveau
+ *
+ * @description
+ * Hiérarchie des niveaux (du plus critique au plus verbeux) :
+ * - fatal: Erreurs critiques uniquement
+ * - error: Erreurs (error + fatal)
+ * - warn: Avertissements (warn + error + fatal)
+ * - info: Informations (log + warn + error + fatal)
+ * - debug: Debug (debug + log + warn + error + fatal)
+ * - verbose: Tout (verbose + debug + log + warn + error + fatal)
+ *
+ * Si aucun niveau n'est spécifié ou si le niveau est invalide, retourne 'info' par défaut.
+ *
+ * @example
+ * ```typescript
+ * // Configuration du logger avec niveau warn
+ * const levels = getLogLevel('warn');
+ * // Retourne: ['error', 'fatal', 'warn']
+ *
+ * // Configuration du logger avec niveau debug
+ * const levels = getLogLevel('debug');
+ * // Retourne: ['error', 'fatal', 'warn', 'log', 'debug']
+ *
+ * // Niveau invalide ou non spécifié
+ * const levels = getLogLevel();
+ * // Retourne: ['error', 'fatal', 'warn', 'log'] (niveau 'info' par défaut)
+ * ```
+ */
 export function getLogLevel(logLevel?: string): LogLevel[] {
   const logLevelMap: Record<LogLevel | string, LogLevel[]> = {
     fatal: ['fatal'],
@@ -8,6 +44,36 @@ export function getLogLevel(logLevel?: string): LogLevel[] {
     info: ['error', 'fatal', 'warn', 'log'],
     debug: ['error', 'fatal', 'warn', 'log', 'debug'],
     verbose: ['error', 'fatal', 'warn', 'log', 'debug', 'verbose'],
-  };
-  return logLevelMap[logLevel] || logLevelMap['info'];
+  }
+
+  return logLevelMap[logLevel] || logLevelMap['info']
 }
+
+/**
+ * Niveau de log par défaut pour l'application.
+ *
+ * Correspond au niveau 'info' qui inclut les logs, avertissements, erreurs et fatals.
+ * Ce niveau offre un bon équilibre entre visibilité et performance pour la production.
+ *
+ * @constant
+ * @type {LogLevel[]}
+ * @default ['error', 'fatal', 'warn', 'log']
+ */
+export const DEFAULT_LOG_LEVEL: LogLevel[] = getLogLevel('info')
+
+/**
+ * Niveau de log minimal pour les commandes console.
+ *
+ * Mode silencieux affichant uniquement les erreurs critiques pour éviter
+ * de polluer la sortie des commandes CLI. Utile lors de l'exécution de
+ * scripts ou de tâches automatisées.
+ *
+ * @constant
+ * @type {LogLevel[]}
+ *
+ * @description
+ * Ce niveau est utilisé au démarrage des commandes console pour minimiser
+ * le bruit dans les logs et garder une sortie propre et lisible.
+ * Correspond au niveau 'warn' qui inclut warn, error et fatal.
+ */
+export const CONSOLE_LOG_LEVEL: LogLevel[] = getLogLevel('warn')

apps/api/src/_common/functions/is-cli.ts

@@ -1,13 +1,68 @@
-import { Abstract, DynamicModule, ForwardReference, Provider, Type } from '@nestjs/common'
 import path from 'node:path'
+import { Abstract, DynamicModule, ForwardReference, Provider, Type } from '@nestjs/common'
 
+/**
+ * Vérifie si le point d'entrée actuel est le mode console.
+ *
+ * Détermine si l'application a été lancée via le fichier console.ts ou console.js
+ * en analysant le nom du fichier principal d'exécution.
+ *
+ * @returns {boolean} `true` si l'application est en mode console, `false` sinon
+ *
+ * @description
+ * La détection se fait en vérifiant le nom du fichier d'entrée via :
+ * 1. require.main.filename (module principal)
+ * 2. process.argv[1] (premier argument du processus)
+ */
 export function isConsoleEntrypoint(): boolean {
   const entry =
     (require?.main?.filename ?? process.argv[1] ?? '').toLowerCase()
   const base = path.basename(entry)
   return /^(console)\.(t|j)s$/.test(base)
 }
 
+/**
+ * Retourne des providers, modules ou imports uniquement en mode console (CLI).
+ *
+ * Cette fonction utilitaire permet de conditionner l'inclusion de modules,
+ * providers ou imports NestJS au contexte d'exécution. Les éléments ne seront
+ * inclus que si l'application est lancée en mode console.
+ *
+ * @template T Type des éléments (Provider, DynamicModule, etc.)
+ * @param {T | T[]} items - Élément(s) à inclure conditionnellement
+ * @returns {T[]} Tableau des éléments si en mode console, tableau vide sinon
+ *
+ * @description
+ * Cas d'usage typiques :
+ * - Charger des modules CLI uniquement en mode console
+ * - Injecter des providers spécifiques aux commandes
+ * - Éviter le chargement de dépendances inutiles en mode serveur
+ *
+ * La fonction normalise toujours le retour en tableau, que l'entrée
+ * soit un élément unique ou un tableau.
+ *
+ * @example
+ * ```typescript
+ * // Dans un module NestJS
+ * @Module({
+ *   imports: [
+ *     CommonModule,
+ *     ...useOnCli([
+ *       CommanderModule,
+ *       InquirerModule,
+ *     ]),
+ *   ],
+ *   providers: [
+ *     AppService,
+ *     ...useOnCli(CliService),
+ *   ],
+ * })
+ * export class AppModule {}
+ *
+ * // En mode console : CommanderModule et InquirerModule sont chargés
+ * // En mode serveur : Ces modules sont ignorés
+ * ```
+ */
 export function useOnCli<
   T = Provider
   | (Type<any> | DynamicModule | Promise<DynamicModule> | ForwardReference<any>)

apps/api/src/console.ts

@@ -1,29 +1,64 @@
-import { CommandFactory } from 'nest-commander';
-import configInstance from '~/config';
-import { getLogLevel } from './_common/functions/get-log-level';
-import { InternalLogger } from './core/logger/internal.logger';
-import { AppModule } from './app.module';
+import { CommandFactory } from 'nest-commander'
+import configInstance from '~/config'
+import { CONSOLE_LOG_LEVEL } from './_common/functions/get-log-level'
+import { AppModule } from './app.module'
+import { InternalLogger } from './core/logger/internal.logger'
 
+/**
+ * Point d'entrée de l'interface en ligne de commande (CLI) de l'application.
+ *
+ * Cette fonction asynchrone auto-exécutée initialise et démarre l'application
+ * en mode console pour exécuter des commandes CLI définies via nest-commander.
+ *
+ * @async
+ * @function
+ * @returns {Promise<void>}
+ *
+ * @description
+ * Processus de démarrage :
+ * 1. Charge la configuration de l'application
+ * 2. Initialise le logger avec un niveau minimal (CONSOLE_LOG_LEVEL)
+ * 3. Log le démarrage de la CLI avec le niveau de log configuré
+ * 4. Crée l'application via CommandFactory sans fermeture automatique
+ * 5. Configure un gestionnaire d'erreurs personnalisé
+ * 6. Ferme proprement l'application après exécution
+ * 7. Gère les erreurs critiques avec code de sortie approprié
+ *
+ * Codes de sortie :
+ * - 0 : Exécution réussie
+ * - 1 : Erreur lors de l'exécution d'une commande
+ * - 255 : Erreur critique lors de l'initialisation
+ *
+ * @example
+ * ```bash
+ * # Exécution d'une commande CLI
+ * yarn run console agents:create
+ *
+ * # La fonction initialise automatiquement l'application
+ * # et exécute la commande spécifiée
+ * ```
+ *
+ * @throws {Error} Erreur fatale capturée et loggée avec code de sortie 255
+ */
 (async () => {
   try {
     const cfg = configInstance();
     const logger = new InternalLogger({
-      logLevel: ['error'],
-      // logLevel: getLogLevel(cfg?.application?.logLevel),
+      logLevel: CONSOLE_LOG_LEVEL, // Silencieux au démarrage des commandes console
       mongoose: cfg?.mongoose,
     });
-    logger.log(`Starting CLI with log level <${cfg?.application?.logLevel || 'info'}>`);
+    logger.log(`Starting CLI with log level <${cfg?.application?.logLevel || 'info'}>`)
     const app = await CommandFactory.runWithoutClosing(AppModule, {
       logger,
       errorHandler: (err) => {
-        console.error(err);
-        process.exit(1);
+        console.error(err)
+        process.exit(1)
       },
-    });
-    await app.close();
+    })
+    await app.close()
   } catch (err) {
-    console.error(err);
-    process.exit(255);
+    console.error(err)
+    process.exit(255)
   }
-  process.exit(0);
-})();
+  process.exit(0)
+})()