ESLint Config AI-SWE

Configuration ESLint optimisée pour les AI Agents SWE avec support TypeScript et multi-framework.

🌟 Features

• 🤖 AI-First: Messages d'erreur enrichis et pédagogiques pour guider les IA
• 🔧 Modulaire: Configurations séparées pour chaque technologie
• 🚀 Performance: Charge uniquement le nécessaire grâce aux flat configs
• 🎯 Auto-détection: Détecte automatiquement le framework utilisé
• 📦 CLI incluse: Outils d'installation et de configuration
• 🛡️ Sécurité des types: Règles strictes pour TypeScript avec justifications

📦 Installation

npm install --save-dev eslint-config-ai-swe

🚀 Utilisation rapide

Avec la CLI (recommandé)

# Détecter le framework et créer la configuration
npx eslint-config-ai-swe setup

# Initialisation complète avec .eslintignore
npx eslint-config-ai-swe init --force

# Détecter le framework du projet
npx eslint-config-ai-swe detect

# Configuration IDE pour VS Code
npx eslint-config-ai-swe ide

# Configuration complète avec IDE
npx eslint-config-ai-swe init --ide

Manuellement

Créez un fichier eslint.config.js:

// eslint.config.js
import aiSwe from 'eslint-config-ai-swe';

export default aiSwe({
  typescript: true,
  react: true, // si vous utilisez React
  ai: true,
});

API Alternative (compatibilité)

L'ancienne API est toujours disponible pour la compatibilité:

// eslint.config.js
import { configs } from 'eslint-config-ai-swe';

export default [
  ...configs.recommended,
  ...configs.react,
];

⚙️ Factory API

La fonction aiSwe() accepte un objet d'options et retourne la configuration ESLint complète.

Options disponibles

aiSwe({
  typescript: boolean,  // Support TypeScript (défaut: true)
  react: boolean,      // Support React (défaut: false)
  vue: boolean,        // Support Vue.js (défaut: false)
  node: boolean,       // Support Node.js (défaut: false)
  svelte: boolean,     // Support Svelte (défaut: false)
  next: boolean,       // Support Next.js (défaut: false)
  ai: boolean,         // Règles IA (défaut: true)
  // Options modernes 2025
  stylistic: boolean,  // Règles stylistiques (défaut: false)
  formatters: boolean, // Support formatters externes (défaut: false)
  strict: boolean,     // Mode strict (défaut: false)
  typeChecked: boolean, // Type-aware linting (défaut: true)
  performance: boolean, // Règles performance (défaut: true)
})

Exemples d'utilisation

// Configuration TypeScript + IA (défaut)
export default aiSwe();

// Projet React avec TypeScript
export default aiSwe({ react: true });

// Projet Node.js sans TypeScript
export default aiSwe({ 
  typescript: false, 
  node: true 
});

// Configuration personnalisée supplémentaire
export default [
  aiSwe({ vue: true }),
  {
    rules: {
      'custom/rule': 'error'
    }
  }
];

⚙️ Configurations disponibles (API classique)

Configurations de base

• basic: Configuration ESLint de base
• recommended: Configuration recommandée (base + typescript + ai)

Configurations par framework

• typescript: Support TypeScript avancé
• react: Support React avec hooks
• vue: Support Vue.js
• svelte: Support Svelte
• next: Support Next.js (optimisé)
• node: Support Node.js

Configurations spécialisées

• ai: Règles IA personnalisées et natives optimisées

🤖 Règles IA incluses

Règles personnalisées

ai-agent/no-explicit-any-with-reason

Niveau: Error

// ❌ Incorrect
function processData(data: any) {
  return data;
}

// ✅ Correct avec justification
// any justification: API externe non typée
function processData(data: any) {
  return data;
}

// ✅ Correct - utiliser unknown
function processData(data: unknown) {
  return JSON.parse(String(data));
}

ai-agent/no-magic-numbers

Niveau: Warning

// ❌ Incorrect
setTimeout(callback, 3000);
const result = value * 3.14;

// ✅ Correct
const TIMEOUT_MS = 3000;
const PI = 3.14;
setTimeout(callback, TIMEOUT_MS);
const result = value * PI;

ai-agent/prefer-descriptive-names

Niveau: Warning

// ❌ Incorrect
const data = [];
function calc() {
  return 0;
}

// ✅ Correct
const userList = [];
function calculateTotal() {
  return 0;
}

Règles natives optimisées pour l'IA

• complexity: Complexité cyclomatique ≤ 8 (plus strict que la norme)
• max-lines-per-function: Maximum 50 lignes par fonction
• max-depth: Maximum 3 niveaux d'imbrication
• max-params: Maximum 4 paramètres par fonction
• id-length: Noms de variables ≥ 2 caractères (exceptions: i, j, k, _, x, y, z)
• no-unused-vars: Variables non utilisées ignorées si préfixées par _

🔄 Workflows Agents IA

Cette configuration est optimisée pour les workflows de développement augmentés par les IA :

Patterns Courants Détectés

1. Génération de Code

• Variables génériques (data, info, temp) → Noms descriptifs
• Fonctions trop longues → Découpage logique
• Complexité excessive → Simplification et modularisation

2. Intégration API

• Utilisation de any → Types précis ou unknown
• Nombres magiques → Constantes nommées
• Gestion d'erreurs complexe → Structure simplifiée

3. Transformation de Données

• Imbrication profonde → Fonctions composables
• Paramètres multiples → Objets de configuration
• Logique répétitive → Fonctions utilitaires

4. Composants React/Vue

• Props non typées → Interfaces TypeScript
• Styles en ligne → CSS modules ou styled-components
• Logique métier complexe → Hooks ou composants séparés

Messages Optimisés pour les IA

Chaque règle fournit des messages structurés avec :

• ACTION: Étapes concrètes pour corriger
• ALTERNATIVE: Solutions de rechange
• EXEMPLE: Code correct illustratif
• BÉNÉFICE: Impact sur la compréhension par les IA

Avantages pour les Agents IA

1. Code Auto-documenté: Les règles encouragent des noms et structures explicites
2. Maintenance Facilitée: Code modulaire et testable
3. Performance Optimale: Algorithmes efficaces et sans complexité inutile
4. Type Safety: Sécurité des types maximale pour meilleure analyse
5. Consistance: Style uniforme à travers tout le projet

🎯 Philosophie de Configuration

Pragmatisme avant réinvention

Cette configuration se concentre sur la valeur ajoutée plutôt que sur la réinvention des règles existantes :

• Règles natives éprouvées : Nous utilisons la règle ESLint native complexity plutôt que de réimplémenter un analyseur de complexité cyclomatique. La règle native est maintenue par l'équipe ESLint, testée par des millions de développeurs, et plus fiable qu'une implémentation maison.

• Configuration IA-optimisée : Notre expertise réside dans le choix des seuils (complexité ≤ 8) et la combinaison de règles pertinentes pour les agents IA, pas dans la réécriture d'algorithmes existants.

• Règles sur mesure à forte valeur : Nous créons uniquement des règles personnalisées lorsqu'elles apportent une réelle innovation, comme no-explicit-any-with-reason qui vérifie la présence de justifications dans les commentaires.

Pourquoi une complexité de 8 ?

Le seuil de complexité cyclomatique de 8 est choisi spécifiquement pour les agents IA :

• Compréhension optimale : Les fonctions avec une complexité ≤ 8 sont plus faciles à comprendre et à maintenir par les IA
• Testabilité : Les fonctions simples sont plus faciles à tester et à déboguer
• Documentation automatique : Les fonctions moins complexes sont auto-documentées
• Performance : Les agents IA peuvent analyser et modifier plus rapidement des fonctions simples

Ce seuil est plus strict que les recommandations traditionnelles (souvent 10-15) car les agents IA bénéficient particulièrement d'un code simple et modulaire.

📋 Exemples par framework

Projet React/Next.js

// eslint.config.js
import aiSwe from 'eslint-config-ai-swe';

export default [
  aiSwe({
    typescript: true,
    react: true,
    next: true,
  }),
  // Configuration supplémentaire pour les hooks complexes
  {
    rules: {
      'react-hooks/exhaustive-deps': 'error',
    }
  }
];

Projet Vue.js

// eslint.config.js
import aiSwe from 'eslint-config-ai-swe';

export default [
  aiSwe({
    typescript: true,
    vue: true,
  }),
  {
    rules: {
      'vue/no-unused-components': 'warn',
    }
  }
];

Projet Node.js

// eslint.config.js
import aiSwe from 'eslint-config-ai-swe';

export default [
  aiSwe({
    typescript: true,
    node: true,
  }),
  {
    rules: {
      'node/exports-style': ['error', 'module.exports'],
    }
  }
];

Projet TypeScript pur

// eslint.config.js
import aiSwe from 'eslint-config-ai-swe';

export default [
  aiSwe({
    typescript: true,
    ai: true,
  }),
  {
    rules: {
      '@typescript-eslint/no-explicit-any': 'error',
    }
  }
];

🔧 Messages IA explicatifs

Les règles de cette configuration fournissent des messages détaillés avec :

• ACTION: Que faire pour corriger le problème
• ALTERNATIVE: Solutions alternatives
• EXEMPLE: Exemples de code correct
• BÉNÉFICE: Pourquoi c'est important pour les IA

Exemple de message :

AI-SWE CRITICAL: L'utilisation de 'any' annule les avantages de TypeScript.
- ACTION: Spécifiez un type précis ou utilisez 'unknown' avec vérification de type.
- ALTERNATIVE: Si 'any' est inévitable, ajoutez un commentaire justificatif.
- EXEMPLE: // any justification: API externe non typée
- BÉNÉFICE: Préserve la sécurité des types et aide les IA à comprendre le code.

🧪 Tests

# Exécuter tous les tests
npm test

# Tests spécifiques
npm run test:rules
npm run test:framework

🚀 Améliorations Récentes

v1.1.0 - Modernisation Complète

• 🏗️ Factory API: API moderne et intuitive avec fonction aiSwe(options)
• 🎯 Options 2025: Support pour stylistic, formatters, strict, typeChecked, performance
• 🤖 Règles IA Optimisées: Messages explicatifs détaillés pour guider les agents IA
• ⚡ Performance: Configurations modulaires et chargement optimisé
• 🔧 CLI Améliorée: Auto-détection de framework et configuration IDE complète
• 🛡️ Type-Aware Linting: Support Project Service API pour TypeScript
• 📊 Performance Optimizations: Limites de complexité spécifiques pour les agents IA

Focus sur la valeur ajoutée

Le projet combine l'expertise en sélection de règles ESLint avec une approche centrée sur les agents IA, offrant des configurations optimisées pour le développement augmenté.

v1.2.0 - Préparation Production

• 🔧 Dépendances Optionnelles: Gestion intelligente des dépendances (Svelte, etc.)
• 🧪 Tests Compréhensifs: Validation complète des règles IA et des workflows agents
• 📚 Documentation 2025: Mise à jour complète avec exemples et bonnes pratiques
• 🚀 Prêt pour npm: Package prêt pour la distribution et l'utilisation en production

💻 Intégration IDE

VS Code (recommandé)

Pour une expérience optimale, configurez VS Code avec ESLint :

Configuration automatique via CLI

# Créer automatiquement la configuration IDE
npx eslint-config-ai-swe ide

# Ou inclure dans l'initialisation complète
npx eslint-config-ai-swe init --ide

Configuration manuelle

Créez un fichier .vscode/settings.json dans votre projet :

{
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  },
  "editor.formatOnSave": false,
  "editor.defaultFormatter": "dbaeumer.vscode-eslint",
  "eslint.validate": [
    "javascript",
    "javascriptreact",
    "typescript",
    "typescriptreact",
    "vue",
    "svelte",
    "astro",
    "json",
    "jsonc",
    "yaml",
    "toml",
    "markdown",
    "html"
  ],
  "eslint.packageManager": "npm",
  "eslint.run": "onType",
  "eslint.workingDirectories": [
    {
      "mode": "auto"
    }
  ],
  "typescript.preferences.preferTypeOnlyAutoImports": true,
  "typescript.suggest.autoImports": true,
  "editor.quickSuggestions": {
    "strings": true,
    "comments": true,
    "other": true
  },
  "editor.suggest.showStatusBar": true,
  "editor.tabSize": 2,
  "editor.insertSpaces": true,
  "files.associations": {
    "*.config.js": "javascript",
    "*.config.ts": "typescript"
  },
  "search.exclude": {
    "**/node_modules": true,
    "**/dist": true,
    "**/build": true,
    "**/.git": true,
    "**/.cache": true
  },
  "files.watcherExclude": {
    "**/node_modules/**": true,
    "**/dist/**": true,
    "**/build/**": true
  }
}

Extensions nécessaires

Installez l'extension ESLint pour VS Code :

• ESLint : dbaeumer.vscode-eslint
• TypeScript (si utilisé) : ms-vscode.vscode-typescript-next

Configuration recommandée

• Auto-fix on save : Les erreurs ESLint sont corrigées automatiquement à la sauvegarde
• Type-aware linting : Analyse TypeScript avec compréhension des types
• Multi-framework : Support pour React, Vue, Svelte, Next.js, etc.
• Performance optimisée : Linting en temps réel sans ralentir l'éditeur

Autres éditeurs

WebStorm/IntelliJ IDEA

1. Allez dans Settings/Preferences → Languages & Frameworks → JavaScript → Code Quality Tools → ESLint
2. Cochez Enable ESLint
3. Configurez le chemin vers votre fichier de configuration

Vim/Neovim

Avec ALE :

let g:ale_linters = {
  \ 'javascript': ['eslint'],
  \ 'typescript': ['eslint'],
  \ 'vue': ['eslint']
  \}
let g:ale_fixers = {
  \ 'javascript': ['eslint'],
  \ 'typescript': ['eslint'],
  \ 'vue': ['eslint']
  \}

Emacs

Avec flycheck :

(require 'flycheck)
(add-hook 'js-mode-hook 'flycheck-mode)
(add-hook 'typescript-mode-hook 'flycheck-mode)

🔧 Dépannage

Problèmes courants

Erreur "Plugin not found"

Si vous rencontrez des erreurs comme Cannot find module 'eslint-plugin-react' :

# Installez les dépendances manquantes
npm install --save-dev eslint-plugin-react eslint-plugin-react-hooks

# Ou utilisez la CLI avec installation automatique
npx eslint-config-ai-swe setup --install-deps

Erreur "tsconfigRootDir must be an absolute path"

Cette erreur se produit lorsqu'aucun fichier tsconfig.json n'est trouvé :

# Créez un fichier tsconfig.json minimal
echo '{"compilerOptions": {"target": "ES2020", "module": "ESNext"}}' > tsconfig.json

# Ou désactivez le linting type-aware
export default aiSwe({
  typescript: true,
  typeChecked: false,
});

Erreur "Maximum call stack size exceeded"

Cela peut être causé par des conflits de règles stylistiques :

// Désactivez les règles stylistiques pour les fichiers complexes
export default aiSwe({
  stylistic: false,
});

Dépendances optionnelles

Certaines fonctionnalités nécessitent des plugins optionnels :

# Pour React
npm install --save-dev eslint-plugin-react eslint-plugin-react-hooks

# Pour Vue
npm install --save-dev eslint-plugin-vue

# Pour Svelte
npm install --save-dev eslint-plugin-svelte

Performance

Si le linting est lent :

1. Désactivez typeChecked: true si vous n'avez pas besoin du linting avancé
2. Utilisez performance: false pour désactiver les règles de performance strictes
3. Assurez-vous d'avoir un tsconfig.json à la racine du projet

Configuration IDE

Pour VS Code :

1. Installez l'extension ESLint
2. Utilisez npx eslint-config-ai-swe ide pour générer la configuration
3. Redémarrez VS Code

Messages d'avertissement

Les avertissements sont normaux et indiquent :

• Plugins manquants (le système fonctionne en mode dégradé)
• Fichiers de configuration manquants
• Dépendances optionnelles non installées

Ces avertissements n'empêchent pas le fonctionnement du linter.

📝 Développement

Structure du projet

src/
├── configs/          # Configurations modulaires
├── factory.js        # Factory function principale
├── plugins/          # Règles IA personnalisées
├── utils/            # Utilitaires (détection de framework)
├── index.js          # Point d'entrée principal
└── cli.js            # Interface en ligne de commande

test/
├── fixtures/         # Données de test pour l'intégration
├── ai-rules.test.js  # Tests des règles IA
├── cli.test.js       # Tests du CLI et framework detector
└── integration.test.js # Tests d'intégration

.vscode/
└── settings.json     # Configuration IDE de référence

Contribuer

1. Fork le projet
2. Créer une branche feature
3. Commit vos changements
4. Push vers la branche
5. Ouvrir une Pull Request

Voir CONTRIBUTING.md pour plus de détails.

📄 License

MIT

🤝 Contributing

Les contributions sont bienvenues ! N'hésitez pas à ouvrir des issues ou des pull requests.