📋 GLM-Toolkit - Audit & Normes de Développement

Auteur: GLM_Audit
Date: 26 octobre 2025
Version: 1.0.0

---

🎯 Objectif

Ce document présente les recommandations, normes de codage et conventions stylistiques basées sur l'analyse complète de l'environnement de développement de Cheik Kone. Il sert de référence pour maintenir la cohérence et la qualité du code à travers tous les projets.

---

📊 Analyse de l'Écosystème

Projets Identifiés

• 25 projets dans ~/Documents/Projets/Developpement/
• 13 projets avec Git activé
• 9 nouveaux dépôts GitHub créés récemment
• Projets principaux: Accor (4.5GB), Center (451MB), Core (276MB)

Technologies Principales

• Frontend: TypeScript, JavaScript, React, Vue.js
• Backend: NestJS, Node.js, Express
• Mobile: Chrome Extensions, WebXR
• Base de données: SQLite, PostgreSQL
• CI/CD: GitLab CI, GitHub Actions
• Outils: Docker, Nix Darwin, Homebrew

---

🏗️ Architecture Recommandée

Structure Standard des Projets

project-name/
├── 📁 src/                    ← Code source
│   ├── 📁 components/         ← Composants réutilisables
│   ├── 📁 services/           ← Logique métier
│   ├── 📁 utils/              ← Utilitaires
│   ├── 📁 types/              ← Types TypeScript
│   └── 📁 config/             ← Configuration
├── 📁 tests/                  ← Tests unitaires/intégration
├── 📁 docs/                   ← Documentation
├── 📁 scripts/                ← Scripts de build/déploiement
├── 📄 package.json            ← Dépendances npm
├── 📄 tsconfig.json           ← Configuration TypeScript
├── 📄 .eslintrc.js            ← Règles ESLint
├── 📄 .prettierrc             ← Formatage Prettier
├── 📄 .gitignore              ← Fichiers ignorés
└── 📄 README.md               ← Documentation du projet

---

📝 Normes de Codage

1. TypeScript Configuration

tsconfig.json recommandé:

{
  "compilerOptions": {
    "module": "nodenext",
    "moduleResolution": "nodenext",
    "target": "ES2023",
    "strictNullChecks": true,
    "forceConsistentCasingInFileNames": true,
    "noImplicitAny": false,
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "allowSyntheticDefaultImports": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "sourceMap": true,
    "outDir": "./dist",
    "baseUrl": "./",
    "incremental": true
  },
  "exclude": ["node_modules", "dist", "frontend"]
}

2. ESLint Configuration

.eslintrc.js recommandé:

module.exports = {
  root: true,
  parserOptions: {
    ecmaVersion: 2023,
    sourceType: 'module'
  },
  env: {
    browser: true,
    node: true,
    es6: true
  },
  extends: [
    'eslint:recommended',
    '@typescript-eslint/recommended',
    'prettier'
  ],
  rules: {
    'no-console': ['error', { allow: ['warn', 'error'] }],
    'no-debugger': 'error',
    'prefer-const': 'error',
    'no-var': 'error',
    'prefer-arrow-callback': 'error',
    'prefer-template': 'error',
    'object-curly-spacing': ['error', 'always'],
    'quotes': ['error', 'single'],
    'semi': ['error', 'always']
  }
};

3. Prettier Configuration

.prettierrc recommandé:

{
  "singleQuote": true,
  "trailingComma": "all",
  "tabWidth": 2,
  "useTabs": false,
  "printWidth": 80,
  "arrowParens": "avoid",
  "bracketSameLine": false
}

---

📦 Scripts npm Standards

package.json scripts recommandés

{
  "scripts": {
    "dev": "nest start --watch",
    "build": "nest build",
    "start": "node dist/main",
    "test": "jest",
    "test:watch": "jest --watch",
    "test:cov": "jest --coverage",
    "lint": "eslint \"{src,apps,libs,test}/**/*.ts\" --fix",
    "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\"",
    "format:check": "prettier --check \"src/**/*.ts\" \"test/**/*.ts\"",
    "prepare": "husky install"
  }
}

---

🔄 CI/CD Configuration

GitHub Actions Recommandé

.github/workflows/ci.yml:

name: CI/CD Pipeline

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Run linting
        run: npm run lint
      
      - name: Run tests
        run: npm run test:cov
      
      - name: Upload coverage
        uses: codecov/codecov-action@v3

  build:
    needs: test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Build project
        run: npm run build

GitLab CI Recommandé

.gitlab-ci.yml:

stages:
  - lint
  - test
  - build
  - deploy

variables:
  NODE_VERSION: "20"
  CACHE_KEY: "$CI_COMMIT_REF_SLUG"

cache:
  key: ${CACHE_KEY}
  paths:
    - node_modules/

lint:
  stage: lint
  image: node:${NODE_VERSION}
  script:
    - npm ci
    - npm run lint

test:
  stage: test
  image: node:${NODE_VERSION}
  script:
    - npm ci
    - npm run test:cov
  coverage: '/Lines\s*:\s*(\d+\.\d+)%/'

build:
  stage: build
  image: node:${NODE_VERSION}
  script:
    - npm ci
    - npm run build
  artifacts:
    paths:
      - dist/

---

🎨 Conventions de Nomination

Fichiers et Dossiers

• Components: PascalCase.tsx (ex: UserProfile.tsx)
• Services: camelCase.service.ts (ex: userService.ts)
• Utils: camelCase.util.ts (ex: dateFormatter.util.ts)
• Types: camelCase.types.ts (ex: user.types.ts)
• Constants: UPPER_SNAKE_CASE.ts (ex: API_ENDPOINTS.ts)
• Tests: *.spec.ts ou *.test.ts

Variables et Fonctions

• Variables: camelCase (ex: userName, isActive)
• Fonctions: camelCase (ex: getUserById(), handleSubmit())
• Classes: PascalCase (ex: UserService, DataRepository)
• Interfaces: PascalCase avec préfixe I (ex: IUser, IRepository)
• Types: PascalCase (ex: UserType, ApiResponse)

Constantes

// ✅ Bon
const API_BASE_URL = 'https://api.example.com';
const MAX_RETRY_ATTEMPTS = 3;

// ❌ Éviter
const apiUrl = 'https://api.example.com';
const maxRetry = 3;

---

📋 Conventions de Code

1. Imports

// 1. Node.js imports
import { join } from 'path';
import { readFileSync } from 'fs';

// 2. Third-party imports
import express from 'express';
import { Controller, Get } from '@nestjs/common';

// 3. Internal imports
import { UserService } from './services/user.service';
import { UserEntity } from './entities/user.entity';
import { IUser } from './types/user.types';

2. Déclarations de Fonctions

// ✅ Fonction fléchée pour callbacks
const users = data.map(user => ({
  id: user.id,
  name: user.name
}));

// ✅ Fonction nommée pour logique métier
async function getUserById(id: string): Promise<IUser | null> {
  return await this.userService.findById(id);
}

// ✅ Méthode de classe
class UserService {
  async createUser(userData: CreateUserDto): Promise<IUser> {
    return await this.repository.save(userData);
  }
}

3. Gestion des Erreurs

// ✅ Try-catch avec logging
try {
  const result = await this.processData(data);
  return result;
} catch (error) {
  this.logger.error('Failed to process data', error);
  throw new InternalServerErrorException('Processing failed');
}

// ✅ Validation personnalisée
if (!userData.email) {
  throw new BadRequestException('Email is required');
}

4. Commentaires

/**
 * Calcule le prix total avec taxes incluses
 * @param price - Prix de base
 * @param taxRate - Taux de taxe (défaut: 0.2)
 * @returns Prix total arrondi à 2 décimales
 */
function calculateTotalPrice(price: number, taxRate = 0.2): number {
  return Math.round((price * (1 + taxRate)) * 100) / 100;
}

// TODO: Implémenter la validation des entrées utilisateur
// FIXME: Corriger la gestion des erreurs réseau
// NOTE: Cette fonction sera dépréciée dans la v2.0

---

🔧 Dépendances Recommandées

Dépendances de Développement

{
  "devDependencies": {
    "@types/node": "^20.0.0",
    "@types/jest": "^29.0.0",
    "@typescript-eslint/eslint-plugin": "^6.0.0",
    "@typescript-eslint/parser": "^6.0.0",
    "eslint": "^8.0.0",
    "eslint-config-prettier": "^9.0.0",
    "eslint-plugin-prettier": "^5.0.0",
    "prettier": "^3.0.0",
    "husky": "^8.0.0",
    "lint-staged": "^15.0.0",
    "jest": "^29.0.0",
    "ts-jest": "^29.0.0",
    "typescript": "^5.0.0"
  }
}

Scripts de Pre-commit

package.json:

{
  "lint-staged": {
    "*.{ts,tsx}": [
      "eslint --fix",
      "prettier --write"
    ],
    "*.{json,md,yml,yaml}": [
      "prettier --write"
    ]
  }
}

.husky/pre-commit:

#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

npx lint-staged
npm run test

---

📊 Tests et Qualité

Structure des Tests

tests/
├── 📁 unit/                   ← Tests unitaires
│   ├── 📁 services/
│   ├── 📁 controllers/
│   └── 📁 utils/
├── 📁 integration/            ← Tests d'intégration
├── 📁 e2e/                    ← Tests end-to-end
└── 📄 fixtures/               ← Données de test

Jest Configuration

jest.config.js:

module.exports = {
  preset: 'ts-jest',
  testEnvironment: 'node',
  roots: ['<rootDir>/src', '<rootDir>/test'],
  testMatch: ['**/__tests__/**/*.ts', '**/?(*.)+(spec|test).ts'],
  transform: {
    '^.+\\.ts$': 'ts-jest',
  },
  collectCoverageFrom: [
    'src/**/*.ts',
    '!src/**/*.d.ts',
    '!src/**/*.spec.ts',
    '!src/**/*.test.ts'
  ],
  coverageDirectory: 'coverage',
  coverageReporters: ['text', 'lcov', 'html'],
  coverageThreshold: {
    global: {
      branches: 80,
      functions: 80,
      lines: 80,
      statements: 80
    }
  }
};

---

🔐 Sécurité

Variables d'Environnement

.env.example:

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/dbname

# API
API_PORT=3000
API_SECRET_KEY=your-secret-key-here

# External Services
REDIS_URL=redis://localhost:6379
JWT_SECRET=your-jwt-secret

# Development
NODE_ENV=development
LOG_LEVEL=debug

.gitignore Recommandé

# Dependencies
node_modules/
npm-debug.log*
yarn-debug.log*
yarn-error.log*

# Build outputs
dist/
build/
*.tsbuildinfo

# Environment variables
.env
.env.local
.env.development.local
.env.test.local
.env.production.local

# IDE
.vscode/
.idea/
*.swp
*.swo

# OS
.DS_Store
Thumbs.db

# Logs
logs/
*.log

# Coverage
coverage/

# Temporary files
tmp/
temp/

---

📚 Documentation

Structure README.md

# Project Name

## Description
Brève description du projet et de ses objectifs.

## Installation
Instructions pour installer et configurer le projet.

## Usage
Exemples d'utilisation et commandes disponibles.

## API Documentation
Lien vers la documentation API (Swagger/Postman).

## Contributing
Guidelines pour contribuer au projet.

## License
Type de licence du projet.

Documentation de Code

/**
 * Service de gestion des utilisateurs
 * 
 * @class UserService
 * @description Gère les opérations CRUD sur les utilisateurs
 * @author Cheik Kone
 * @since 1.0.0
 */
@Injectable()
export class UserService {
  /**
   * Crée un nouvel utilisateur
   * 
   * @param {CreateUserDto} userData - Données de l'utilisateur à créer
   * @returns {Promise<IUser>} Utilisateur créé
   * @throws {BadRequestException} Si les données sont invalides
   * @example
   * ```typescript
   * const user = await userService.createUser({
   *   email: 'user@example.com',
   *   name: 'John Doe'
   * });
   * ```
   */
  async createUser(userData: CreateUserDto): Promise<IUser> {
    // Implementation
  }
}

---

🚀 Bonnes Pratiques

1. Performance

• Utiliser async/await au lieu de callbacks
• Implémenter le caching pour les requêtes fréquentes
• Optimiser les bundles avec lazy loading
• Surveiller les performances avec des outils appropriés

2. Sécurité

• Valider toutes les entrées utilisateur
• Utiliser HTTPS en production
• Implémenter rate limiting
• Ne jamais exposer de secrets dans le code

3. Maintenabilité

• Écrire du code auto-documenté
• Suivre le principe DRY (Don't Repeat Yourself)
• Utiliser des design patterns appropriés
• Maintenir une couverture de tests > 80%

4. Collaboration

• Utiliser des branches feature pour les nouvelles fonctionnalités
• Écrire des messages de commit clairs
• Faire des revues de code systématiques
• Documenter les décisions importantes

---

📋 Checklist de Qualité

Avant de Committer

• Code linté avec ESLint
• Code formaté avec Prettier
• Tests passants (unitaires + intégration)
• Couverture de tests > 80%
• Documentation mise à jour
• Secrets non exposés

Avant de Déployer

• Tests end-to-end passants
• Performance testée
• Sécurité validée
• Documentation complète
• Rollback plan préparé

---

🔗 Ressources Utiles

Outils Recommandés

• IDE: Cursor, VS Code, Claude Code
• Terminal: iTerm2, Tabby
• Version Control: Git + GitHub/GitLab
• Package Manager: npm, yarn, pnpm
• Container: Docker
• Monitoring: PM2, New Relic

Liens Externes

• TypeScript Documentation
• NestJS Documentation
• ESLint Rules
• Prettier Options
• Jest Configuration

---

📞 Support

Pour toute question sur ces normes et recommandations :

• Auteur: GLM_Audit
• Email: support@littech.com
• Repository: GitHub - LitTech/GLM-Toolkit

---

Dernière mise à jour: 26 octobre 2025
Version: 1.0.0
Prochaine révision: Q1 2026

---

Ce document est vivant et évolue avec les meilleures pratiques du développement logiciel. N'hésitez pas à proposer des améliorations via des Pull Requests.