Analyser du code Node.js avec SonarQube

Quand on développe une application Node.js, on finit souvent par se concentrer sur la vitesse de livraison. Une fonctionnalité de plus, une route de plus, une intégration de plus, puis encore un petit correctif avant la mise en production. Tout cela est normal, presque inévitable. Mais à force d’avancer vite, on laisse parfois derrière soi une réalité moins confortable : du code difficile à maintenir, des tests incomplets, des vulnérabilités discrètes, des duplications inutiles, des fonctions trop longues et des conventions qui varient d’un fichier à l’autre. C’est précisément là que SonarQube devient un allié précieux. Il ne remplace ni le bon sens du développeur ni la relecture humaine, mais il agit comme un miroir exigeant qui révèle ce que l’on ne voit plus quand on a le nez dans le projet depuis des semaines.

Analyser du code Node.js avec SonarQube, ce n’est pas seulement “faire du qualité gate” pour cocher une case de plus dans un pipeline CI/CD. C’est installer une discipline durable autour du code. C’est donner à l’équipe un langage commun pour parler de dette technique, de sécurité, de lisibilité et de robustesse. C’est aussi offrir à chaque développeur une manière concrète de savoir où concentrer ses efforts. Un rapport SonarQube bien lu peut éviter des heures de débogage, réduire les régressions, et surtout aider une base de code à rester vivante au lieu de devenir une forêt dense où personne n’ose plus toucher à rien.

Dans l’écosystème Node.js, l’intérêt est encore plus grand. Le monde JavaScript et TypeScript évolue vite, les dépendances se multiplient, les patterns sont nombreux, et la tentation d’empiler des abstractions est forte. On peut créer une API Express en quelques minutes, démarrer un service avec Fastify, construire une couche métier avec NestJS, ou orchestrer un worker avec BullMQ, mais sans garde-fous, la qualité peut se dégrader à grande vitesse. SonarQube permet de maintenir le cap, sans transformer l’équipe en machine à faire de la conformité. L’objectif n’est pas de produire un code “parfait” au sens abstrait du terme. L’objectif est de produire un code compréhensible, testable, sécurisé, et suffisamment propre pour durer.

Pourquoi utiliser SonarQube avec Node.js

Node.js est un environnement très efficace pour construire des API, des backends temps réel, des outils CLI et des services distribués. Sa flexibilité est une force, mais elle peut aussi devenir un piège. Dans un projet JavaScript ou TypeScript, il est facile de laisser passer des incohérences de style, des fonctions trop complexes, des variables inutilisées, des branches non couvertes par les tests, ou des zones de sécurité fragiles. Une revue de code humaine peut repérer beaucoup de choses, mais elle ne voit pas tout, et surtout elle ne voit pas toujours de façon constante dans le temps.

SonarQube apporte une approche systématique. Il analyse la qualité du code, détecte les bugs potentiels, les vulnérabilités, les “code smells”, la duplication, les problèmes de maintenabilité, et la couverture de tests si vous l’alimentez avec les bons rapports. Pour Node.js, cela est particulièrement utile car les projets sont souvent composés de petits fichiers dispersés, de fonctions utilitaires, de couches de service, de middlewares, de contrôleurs, de schémas de validation, de modèles de données et de scripts. Un projet peut sembler “simple” en apparence, mais contenir en réalité beaucoup de zones fragiles.

L’avantage de SonarQube, c’est qu’il transforme des impressions vagues en signaux concrets. Au lieu de dire “ce fichier me paraît un peu sale”, vous obtenez des indicateurs précis : complexité cognitive trop élevée, duplication dans plusieurs fichiers, exception non gérée, dépendance dangereuse, test manquant, ligne trop longue, paramètre inutile, promesse mal gérée, ou encore règle de sécurité enfreinte. Cette granularité facilite les priorités. On ne corrige plus “au feeling”, on corrige selon l’impact réel.

Ce que SonarQube détecte dans un projet Node.js

Dans un projet Node.js, SonarQube peut faire ressortir plusieurs catégories de problèmes. Les bugs potentiels concernent par exemple des conditions mal gérées, des accès à des propriétés potentiellement nulles, des usages hasardeux de promesses, des boucles incorrectes ou des chemins d’exécution inattendus. Les vulnérabilités peuvent révéler des injections, des usages risqués de dépendances, des faiblesses dans le traitement des entrées, ou des pratiques dangereuses autour des secrets.

Les code smells, eux, sont souvent les plus utiles au quotidien. Ils ne sont pas nécessairement des bugs, mais ils indiquent un code difficile à comprendre ou à maintenir. Une fonction trop longue, une hiérarchie de conditions trop lourde, une répétition de logique, un nom de variable peu expressif, un couplage trop fort, ou une responsabilité trop étendue dans un seul fichier peuvent sembler supportables sur le moment. Mais avec le temps, ces détails accumulés finissent par coûter très cher.

SonarQube peut aussi travailler avec la couverture de tests. Dans Node.js, c’est particulièrement précieux, parce qu’un code sans tests finit souvent par devenir un terrain glissant. Les tests ne garantissent pas l’absence de bugs, bien sûr, mais ils réduisent la peur de modifier le code. Et quand la peur diminue, l’équipe refactorise plus facilement, les bugs sont corrigés plus vite, et la base de code reste saine plus longtemps.

Installer SonarQube pour commencer simplement

La manière la plus simple de démarrer avec SonarQube est souvent d’utiliser Docker. Cela évite une installation lourde et permet de lancer rapidement un environnement local de test. Pour un projet Node.js, cette approche est souvent idéale au début, car elle permet de valider la configuration avant de l’intégrer dans un pipeline plus vaste.

Voici un exemple de lancement local avec Docker :

docker run -d --name sonarqube \
  -p 9000:9000 \
  sonarqube:lts-community

Une fois le conteneur démarré, vous pouvez accéder à l’interface web sur http://localhost:9000. Le mot de passe par défaut dépend de la version et de l’environnement, mais dans beaucoup de scénarios locaux, vous pourrez commencer avec les identifiants initiaux recommandés par la documentation de votre version. L’idée n’est pas de rester longtemps sur une configuration par défaut, mais de valider d’abord que l’outil fonctionne, puis de sécuriser le tout ensuite.

Dans un contexte professionnel, on préfère souvent séparer les environnements : local pour tester, serveur dédié pour l’équipe, et éventuellement intégration dans un pipeline CI. Cette discipline évite de confondre l’analyse exploratoire avec l’analyse de référence.

Créer un premier projet Node.js analysé par SonarQube

Prenons un cas simple : une API Node.js avec Express. Vous avez quelques routes, quelques services, et un petit ensemble de tests Jest. L’objectif est de brancher SonarQube sur ce projet pour obtenir un rapport utile, pas juste décoratif.

Une structure de projet typique peut ressembler à ceci :

my-node-app/
├── src/
│   ├── app.js
│   ├── routes/
│   │   └── users.js
│   ├── services/
│   │   └── userService.js
│   └── utils/
│       └── validation.js
├── test/
│   └── userService.test.js
├── package.json
├── sonar-project.properties
└── .gitignore

Le fichier sonar-project.properties est souvent le point de départ le plus simple. Il indique à SonarQube le nom du projet, la clé du projet, l’emplacement des sources, et parfois les chemins de tests et les rapports de couverture.

sonar.projectKey=my-node-app
sonar.projectName=My Node App
sonar.projectVersion=1.0.0

sonar.sources=src
sonar.tests=test

sonar.language=js
sonar.sourceEncoding=UTF-8

sonar.javascript.lcov.reportPaths=coverage/lcov.info
sonar.test.inclusions=test/**/*.test.js

La propriété sonar.javascript.lcov.reportPaths est particulièrement importante si vous voulez remonter la couverture de tests. Sans elle, SonarQube peut analyser votre code, mais il ne saura pas facilement quelles lignes sont réellement couvertes par les tests.

Ensuite, vous pouvez lancer l’analyse via le scanner SonarQube. Dans certains cas, vous l’exécuterez globalement via une installation locale, dans d’autres via npx ou un conteneur. L’important est de garder la configuration explicite et reproductible.

Un exemple de commande peut ressembler à ceci :

sonar-scanner \
  -Dsonar.projectKey=my-node-app \
  -Dsonar.sources=src \
  -Dsonar.tests=test \
  -Dsonar.javascript.lcov.reportPaths=coverage/lcov.info \
  -Dsonar.host.url=http://localhost:9000 \
  -Dsonar.token=YOUR_SONAR_TOKEN

Dans un environnement réel, le token ne doit jamais être écrit en dur dans le dépôt. Il doit être stocké dans les variables d’environnement ou dans les secrets du service CI.

Exemple de code Node.js avant analyse

Imaginons maintenant un petit service utilisateur. Le code fonctionne, mais il contient plusieurs défauts typiques que SonarQube pourrait signaler.

// src/services/userService.js
const db = require('../db');

async function getUserById(id) {
  if (!id) {
    return null;
  }

  const user = await db.query(`SELECT * FROM users WHERE id = ${id}`);
  return user.rows[0];
}

async function createUser(data) {
  if (!data) {
    throw new Error('No data');
  }

  const name = data.name;
  const email = data.email;
  const age = data.age;

  if (!name || !email) {
    throw new Error('Missing fields');
  }

  return await db.query(
    `INSERT INTO users(name, email, age) VALUES('${name}', '${email}', ${age})`
  );
}

module.exports = {
  getUserById,
  createUser,
};

À première vue, ce fichier paraît simple. Pourtant, plusieurs problèmes sautent aux yeux à l’analyse. La requête SQL est interpolée directement avec des valeurs utilisateur, ce qui ouvre la porte à une injection. Le contrôle d’entrée est minimal. La fonction createUser retourne un await inutilement, ce qui n’apporte rien. Les erreurs sont génériques et peu informatives. Et la logique de validation est limitée à quelques conditions. SonarQube peut faire remonter une partie de ces problèmes, mais l’intérêt réel est surtout de vous forcer à revoir les zones sensibles avec un œil plus critique.

Repenser le code après l’analyse

Corrigeons le service en utilisant des requêtes paramétrées et une validation plus explicite.

// src/services/userService.js
const db = require('../db');

async function getUserById(id) {
  if (!Number.isInteger(id)) {
    throw new TypeError('id must be an integer');
  }

  const result = await db.query('SELECT id, name, email, age FROM users WHERE id = $1', [id]);
  return result.rows[0] || null;
}

async function createUser(data) {
  if (!data || typeof data !== 'object') {
    throw new TypeError('data must be an object');
  }

  const { name, email, age } = data;

  if (typeof name !== 'string' || name.trim() === '') {
    throw new Error('name is required');
  }

  if (typeof email !== 'string' || email.trim() === '') {
    throw new Error('email is required');
  }

  const result = await db.query(
    'INSERT INTO users(name, email, age) VALUES($1, $2, $3) RETURNING id, name, email, age',
    [name.trim(), email.trim(), age ?? null]
  );

  return result.rows[0];
}

module.exports = {
  getUserById,
  createUser,
};

Cette version reste simple, mais elle est déjà bien plus saine. La requête SQL est paramétrée. Les entrées sont validées de manière plus rigoureuse. Les erreurs sont plus explicites. Le code devient aussi plus facile à tester, ce qui a un impact direct sur la qualité globale du projet.

SonarQube ne remplace pas le test, il le valorise

Une idée importante à garder en tête : SonarQube n’écrit pas les tests à votre place. Il vous aide à voir où ils manquent, où ils sont faibles, et où ils ne couvrent pas les zones critiques. Dans Node.js, les tests unitaires sont souvent écrits avec Jest, Mocha, Vitest ou Ava. SonarQube peut intégrer les rapports de couverture produits par ces outils, ce qui donne une vision plus réaliste du projet.

Voici un exemple simple avec Jest :

// test/userService.test.js
const userService = require('../src/services/userService');

describe('userService', () => {
  test('getUserById should throw when id is invalid', async () => {
    await expect(userService.getUserById('abc')).rejects.toThrow(TypeError);
  });

  test('createUser should throw when name is missing', async () => {
    await expect(
      userService.createUser({ email: 'test@example.com', age: 25 })
    ).rejects.toThrow('name is required');
  });
});

Pour générer un rapport exploitable par SonarQube, vous pouvez configurer Jest afin de produire un fichier lcov.info.

{
  "scripts": {
    "test": "jest",
    "test:coverage": "jest --coverage"
  }
}

Puis, après exécution :

npm run test:coverage

Le répertoire coverage/ contiendra généralement le fichier dont SonarQube a besoin. Cette étape semble parfois secondaire, mais elle est essentielle. Une analyse de qualité sans visibilité sur les tests donne une image incomplète. Une couverture remontée correctement vous permet de mesurer non seulement ce qui est écrit, mais ce qui est réellement protégé par des tests.

Comprendre les indicateurs de SonarQube

L’interface de SonarQube peut paraître impressionnante au début. Il y a des scores, des catégories, des tendances, des issues, des hotspots de sécurité, des duplications, des lignes de code, de la dette technique, et parfois l’impression qu’il faut presque suivre un cours pour lire le tableau de bord. En réalité, quelques indicateurs suffisent pour commencer à en tirer beaucoup de valeur.

Le premier est souvent la note de sécurité et de fiabilité. Elle indique si votre code présente des risques concrets susceptibles d’induire des bugs ou des failles. Le second est la maintenabilité, qui reflète la quantité de travail estimée pour ramener le code à un niveau acceptable selon les règles du moteur d’analyse. Le troisième est la couverture de tests, qui donne un aperçu de la proportion du code exécuté par les tests. Le quatrième est la duplication, car des morceaux de code répétés sont souvent le signe qu’une abstraction manque.

Il ne faut cependant pas lire ces chiffres comme des vérités absolues. Une couverture à 95 % n’est pas automatiquement synonyme de qualité. Une dette technique faible ne garantit pas que le code est clair pour un nouvel arrivant. SonarQube est un instrument d’aide à la décision, pas un juge final. Le plus utile est souvent de suivre l’évolution dans le temps. Si le projet s’améliore après chaque sprint, l’outil a rempli son rôle.

Travailler avec la dette technique sans démoraliser l’équipe

Le terme “dette technique” peut faire peur. Il est parfois utilisé comme un reproche, parfois comme une excuse, et parfois comme un mot fourre-tout pour désigner tout ce qui ne va pas. SonarQube aide justement à rendre ce concept plus concret. Au lieu d’une dette abstraite et culpabilisante, il affiche des issues avec un niveau de priorité, une explication et un effort estimé.

C’est important psychologiquement. Dans une équipe, si l’outil devient un instrument de sanction, il sera mal accueilli. Si, au contraire, il sert à mettre en lumière des améliorations réalistes, il sera utilisé avec plus de sérénité. Un bon usage de SonarQube consiste à traiter les nouveaux problèmes dès qu’ils apparaissent, puis à corriger progressivement les anciens lorsqu’on touche aux zones concernées. Cette stratégie évite les grands chantiers interminables qui paralysent les équipes.

Une approche raisonnable consiste à établir une règle simple : aucun nouveau code ne doit aggraver la dette. Ainsi, même si l’historique contient des zones imparfaites, le projet ne continue pas de se dégrader. C’est souvent là que SonarQube montre le plus de valeur au quotidien.

Intégrer SonarQube dans le workflow GitHub Actions

Une fois l’analyse locale validée, la suite logique est de l’intégrer dans l’automatisation. GitHub Actions est un choix courant pour les projets Node.js, car il permet d’exécuter les tests, la couverture et l’analyse SonarQube à chaque push ou pull request.

Voici un exemple de workflow :

name: CI

on:
  push:
    branches:
      - main
  pull_request:

jobs:
  test-and-analyze:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Run tests with coverage
        run: npm run test:coverage

      - name: SonarQube Scan
        uses: SonarSource/sonarqube-scan-action@v2
        env:
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
          SONAR_HOST_URL: ${{ secrets.SONAR_HOST_URL }}

Ce workflow exécute d’abord les tests, puis lance l’analyse. C’est une séquence logique : il faut produire les données de couverture avant que SonarQube puisse les lire. Le token et l’URL du serveur sont stockés dans les secrets GitHub. C’est une bonne pratique simple mais indispensable.

Dans une équipe mature, on ajoute souvent une étape de “quality gate” qui bloque la fusion si les critères définis ne sont pas atteints. Cela peut sembler rigide au début, mais c’est ce qui empêche le niveau global du projet de se détériorer peu à peu.

Exemple d’un code plus complexe que nécessaire

SonarQube est très bon pour détecter les fonctions trop longues ou trop complexes. Ce type de problème apparaît fréquemment dans les projets Node.js, surtout quand une fonction accumule validation, transformation, accès base de données, journalisation et formatage de réponse.

Prenons un exemple volontairement excessif :

function processOrder(order) {
  if (!order) {
    throw new Error('Order is required');
  }

  if (!order.items) {
    throw new Error('Order items are required');
  }

  if (order.items.length === 0) {
    throw new Error('Order must contain at least one item');
  }

  let total = 0;
  for (let i = 0; i < order.items.length; i++) {
    const item = order.items[i];

    if (!item.price) {
      throw new Error('Item price is missing');
    }

    if (!item.quantity) {
      throw new Error('Item quantity is missing');
    }

    total += item.price * item.quantity;
  }

  if (total > 1000) {
    console.log('Large order detected');
  }

  if (order.customer && order.customer.vip) {
    total = total * 0.9;
  }

  return {
    total,
    currency: order.currency || 'EUR',
    processedAt: new Date().toISOString(),
  };
}

Cette fonction marche peut-être, mais elle devient rapidement difficile à lire, à tester et à modifier. SonarQube peut signaler une complexité trop élevée, ce qui est souvent un excellent indice qu’il faut découper la logique. Une meilleure version serait de séparer la validation, le calcul du total et la mise en forme finale.

function validateOrder(order) {
  if (!order) throw new Error('Order is required');
  if (!Array.isArray(order.items) || order.items.length === 0) {
    throw new Error('Order must contain at least one item');
  }
}

function calculateTotal(items) {
  return items.reduce((sum, item) => {
    if (typeof item.price !== 'number') throw new Error('Item price is missing');
    if (typeof item.quantity !== 'number') throw new Error('Item quantity is missing');
    return sum + item.price * item.quantity;
  }, 0);
}

function processOrder(order) {
  validateOrder(order);

  const baseTotal = calculateTotal(order.items);
  const vipDiscount = order.customer?.vip ? 0.9 : 1;
  const total = baseTotal * vipDiscount;

  return {
    total,
    currency: order.currency || 'EUR',
    processedAt: new Date().toISOString(),
  };
}

Cette version a non seulement une meilleure lisibilité, mais elle facilite aussi les tests unitaires. Chaque responsabilité devient plus claire. Et quand un futur développeur tombe sur ce code, il n’a pas besoin de reconstruire l’intention de l’auteur à travers un bloc unique trop dense.

Sécurité : un bénéfice souvent sous-estimé

Quand on parle de SonarQube, beaucoup de développeurs pensent d’abord à la propreté du code et à la dette technique. C’est logique, mais un autre aspect est parfois encore plus important : la sécurité. Dans les applications Node.js, les problèmes de sécurité viennent souvent de traitements d’entrées insuffisants, de dépendances vulnérables, de secrets exposés, d’appels système risqués ou de manipulations de chaînes non maîtrisées.

Par exemple, l’utilisation de eval est presque toujours une mauvaise idée :

function runExpression(expression) {
  return eval(expression);
}

Ce genre de code peut déclencher des alertes de sécurité évidentes. Même si le cas d’usage semble anodin, ce type de pratique ouvre souvent la porte à des comportements imprévisibles. Une alternative plus sûre consiste à utiliser un parseur dédié, une bibliothèque spécialisée ou une logique métier explicite.

De la même manière, le traitement des secrets doit rester rigoureux. Un fichier .env ne doit pas être committé par erreur. Un jeton API ne doit jamais être affiché dans les logs. Une variable sensible ne doit pas être sérialisée dans une réponse HTTP. SonarQube ne remplacera pas une vraie politique de sécurité, mais il peut aider à détecter des pratiques dangereuses avant qu’elles ne deviennent des incidents.

Cas pratique : analyser une API Express

Prenons un exemple un peu plus concret avec Express. Supposons que vous ayez une route de création d’utilisateur.

// src/routes/users.js
const express = require('express');
const router = express.Router();
const userService = require('../services/userService');

router.post('/', async (req, res) => {
  try {
    const user = await userService.createUser(req.body);
    res.status(201).json(user);
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

module.exports = router;

Ce code fonctionne, mais SonarQube peut pointer plusieurs pistes d’amélioration. La gestion des erreurs est trop générique : tout retourne un 500, même si l’erreur vient d’une validation de l’entrée utilisateur. La route dépend directement du corps brut sans schéma de validation. Et le message d’erreur est renvoyé tel quel, ce qui peut parfois exposer trop d’informations.

Une version plus robuste pourrait ressembler à ceci :

const express = require('express');
const router = express.Router();
const userService = require('../services/userService');

router.post('/', async (req, res, next) => {
  try {
    const user = await userService.createUser(req.body);
    return res.status(201).json(user);
  } catch (error) {
    return next(error);
  }
});

module.exports = router;

Puis, dans un middleware global :

function errorHandler(err, req, res, next) {
  if (err instanceof TypeError) {
    return res.status(400).json({ error: err.message });
  }

  return res.status(500).json({ error: 'Internal Server Error' });
}

module.exports = errorHandler;

Cette séparation des responsabilités améliore la maintenabilité, et SonarQube aura moins de raisons de signaler une gestion d’erreur confuse ou répétée. On retrouve ici une logique simple : le contrôleur orchestre, le service traite, et le middleware centralise la stratégie d’erreur.

Comment interpréter les “code smells” sans tomber dans l’obsession

Un des pièges les plus courants avec SonarQube est de vouloir tout corriger immédiatement. C’est compréhensible, surtout quand on découvre l’outil pour la première fois. Les scores rouges attirent l’œil, les issues s’accumulent, et l’on se sent presque obligé d’éteindre tous les voyants. Mais un projet réel demande du discernement.

Un “code smell” ne signifie pas toujours qu’il faut réécrire le fichier. Parfois, le contexte justifie la forme actuelle. Parfois, le coût du changement dépasse l’intérêt immédiat. Parfois encore, le code n’est pas idéal mais suffisamment stable pour être laissé en paix jusqu’à la prochaine modification. SonarQube devient véritablement utile quand on l’utilise pour guider des améliorations pragmatiques, pas quand on le transforme en machine à générer de l’anxiété.

L’expérience montre qu’une stratégie efficace consiste à corriger les nouvelles issues au fil de l’eau, puis à planifier les plus anciennes dans les moments où l’on touche déjà la zone concernée. En d’autres termes, on améliore le code par opportunité, pas par culte de la perfection.

SonarQube et TypeScript : un duo très solide

Dans un projet Node.js moderne, TypeScript est souvent présent. C’est une très bonne nouvelle pour SonarQube, car le typage réduit déjà une partie des erreurs et aide à structurer le code. SonarQube complète cette discipline en ajoutant une vision de maintenabilité, de duplication et de sécurité.

Voici un exemple TypeScript plus expressif :

interface CreateUserInput {
  name: string;
  email: string;
  age?: number;
}

interface User {
  id: number;
  name: string;
  email: string;
  age: number | null;
}

async function createUser(input: CreateUserInput): Promise<User> {
  if (!input.name.trim()) {
    throw new Error('name is required');
  }

  if (!input.email.trim()) {
    throw new Error('email is required');
  }

  return {
    id: Date.now(),
    name: input.name.trim(),
    email: input.email.trim(),
    age: input.age ?? null,
  };
}

SonarQube apprécie souvent les structures claires, les types explicites et la réduction des ambiguïtés. Cela ne veut pas dire qu’un projet TypeScript sera automatiquement impeccable, loin de là. Mais les types bien utilisés rendent les analyses plus pertinentes et limitent une partie du bruit. Il devient plus simple d’identifier les vrais problèmes au lieu de se battre contre des erreurs triviales.

Monorepo, microservices et projets plus larges

Dans les projets plus avancés, Node.js est souvent utilisé au sein d’un monorepo ou d’une architecture de microservices. Dans ce cas, SonarQube reste pertinent, mais la configuration devient plus importante. Il faut décider si l’on analyse chaque service séparément ou l’ensemble du dépôt. Il faut aussi gérer les rapports de couverture par sous-projet, les exclusions éventuelles, les chemins de sources, et parfois les conventions spécifiques à chaque package.

Par exemple, un monorepo peut contenir :

apps/
  api/
  worker/
  webhooks/
packages/
  shared/
  config/

Chaque sous-projet peut avoir son propre sonar-project.properties, ou bien l’on peut centraliser l’analyse avec des chemins précis. Il n’existe pas une seule bonne réponse. Tout dépend de la taille de l’équipe, de la fréquence des déploiements et de l’autonomie de chaque service. L’important est que l’analyse reste lisible. Une configuration trop complexe finit souvent par être abandonnée, ce qui serait dommage.

Gérer les exclusions intelligemment

Dans tout projet Node.js, il existe des fichiers que l’on ne veut pas analyser de la même manière que le code métier. Les fichiers générés, les artefacts de build, les bundles, les dépendances tierces et certains scripts temporaires peuvent brouiller les résultats. SonarQube permet d’exclure ce qui doit l’être.

Exemple :

sonar.exclusions=dist/**,coverage/**,node_modules/**,**/*.min.js
sonar.test.exclusions=test/helpers/**

Ces exclusions doivent rester raisonnables. Exclure trop de choses vide l’analyse de sa substance. Exclure trop peu génère du bruit et fatigue l’équipe. Le bon équilibre est souvent celui qui permet à SonarQube de se concentrer sur votre code métier réel, pas sur ce qui est produit automatiquement ou importé tel quel.

Une stratégie réaliste pour adopter SonarQube dans une équipe

L’erreur la plus fréquente est de vouloir imposer SonarQube du jour au lendemain comme un tribunal. Une adoption plus douce fonctionne mieux. D’abord, lancez l’analyse sans bloquer la livraison. Ensuite, laissez l’équipe regarder les rapports et discuter des issues les plus importantes. Puis, fixez quelques règles simples : ne pas introduire de nouvelles vulnérabilités, réduire les duplications évidentes, et éviter les fonctions trop lourdes dans les nouveaux développements.

Avec le temps, vous pouvez ajouter des seuils plus stricts. Mais il est rarement utile de commencer par une barre trop haute. Une équipe qui comprend l’outil l’adoptera mieux qu’une équipe à qui l’on impose des contraintes qu’elle ne perçoit pas comme utiles.

Le véritable objectif n’est pas de fabriquer des rapports jolis. C’est de créer une culture où l’on prend au sérieux la qualité du code sans ralentir inutilement le travail. SonarQube aide justement à trouver cet équilibre fragile entre exigence et pragmatisme.

Exemple d’intégration npm complète

Voici une configuration package.json plus complète pour un projet Node.js utilisant tests, couverture et analyse :

{
  "name": "my-node-app",
  "version": "1.0.0",
  "private": true,
  "scripts": {
    "start": "node src/app.js",
    "test": "jest",
    "test:coverage": "jest --coverage",
    "lint": "eslint src test",
    "sonar": "sonar-scanner"
  },
  "devDependencies": {
    "eslint": "^9.0.0",
    "jest": "^29.0.0",
    "sonar-scanner": "^3.1.0"
  }
}

Cette approche centralise les commandes et rend l’analyse plus simple à lancer localement. Un développeur peut exécuter les tests, produire la couverture, puis déclencher l’analyse sans mémoriser une suite interminable de commandes différentes. Plus le workflow est fluide, plus l’outil sera utilisé régulièrement.

Quelques erreurs fréquentes à éviter

Dans la pratique, plusieurs erreurs reviennent souvent. La première est de lancer SonarQube sans couverture de tests, puis de s’étonner que le résultat soit incomplet. La deuxième est d’analyser les fichiers générés ou les dépendances externes, ce qui ajoute du bruit inutile. La troisième est de ne pas relier l’analyse à la CI, ce qui transforme l’outil en exercice ponctuel vite oublié. La quatrième est de considérer que les issues de SonarQube sont des ordres absolus, sans lecture humaine.

Une autre erreur est d’ignorer les problèmes les plus simples parce qu’ils semblent “cosmétiques”. Des noms de variables flous, des fonctions trop longues, des blocs dupliqués ou des retours incohérents sont souvent les premiers signes d’une dette qui s’installe. Dans un projet Node.js, ces détails finissent par peser lourd, surtout quand plusieurs personnes interviennent sur la même base de code.

Enfin, il ne faut pas confondre vitesse d’analyse et valeur d’analyse. Un scan rapide mais mal configuré ne vaut pas grand-chose. Une analyse bien alimentée, avec des tests et une configuration claire, apporte beaucoup plus de valeur, même si elle demande un peu plus de soin au départ.

Faire vivre la qualité au quotidien

L’un des aspects les plus intéressants de SonarQube, c’est qu’il peut transformer la manière dont une équipe parle du code. Au lieu de dire vaguement “il faudrait nettoyer un peu”, on peut dire “cette fonction a une complexité trop élevée”, “ce module est dupliqué dans trois endroits”, ou “cette route n’est pas couverte par les tests”. Les discussions deviennent plus concrètes. Les arbitrages aussi.

Et puis, il y a un effet presque psychologique : voir le projet progresser visuellement motive. Quand les issues diminuent, quand la couverture grimpe, quand les hotspots de sécurité sont traités, on sent que le code devient plus solide. Ce sentiment est précieux. Il aide l’équipe à faire de la qualité non pas une contrainte abstraite, mais une habitude de travail.

Un exemple de pipeline plus complet

Pour finir cette partie pratique, voici un exemple de pipeline un peu plus réaliste, avec installation, tests, couverture et analyse :

name: Node.js CI

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

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Use Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install
        run: npm ci

      - name: Lint
        run: npm run lint

      - name: Test with coverage
        run: npm run test:coverage

      - name: SonarQube analysis
        uses: SonarSource/sonarqube-scan-action@v2
        env:
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
          SONAR_HOST_URL: ${{ secrets.SONAR_HOST_URL }}

Ce pipeline a une logique simple et saine. Il installe les dépendances, vérifie le style et la qualité statique, lance les tests avec couverture, puis déclenche l’analyse SonarQube. C’est exactement le genre de chaîne qui permet de détecter les problèmes tôt, avant qu’ils ne se retrouvent en production ou dans une branche difficile à fusionner.

En résumé pratique

Analyser du code Node.js avec SonarQube, c’est donner au projet un système de contrôle de santé régulier. L’outil détecte les bugs potentiels, les vulnérabilités, les zones trop complexes, les duplications, les problèmes de couverture et une partie de la dette technique. Dans un projet Node.js, où la flexibilité peut rapidement devenir source de désordre, cela apporte une vraie stabilité.

Le point le plus important reste la manière de l’utiliser. SonarQube fonctionne très bien quand il est intégré au quotidien, configuré avec soin, alimenté par de bons tests et utilisé comme un guide, pas comme une punition. Il devient alors un partenaire silencieux mais efficace, capable d’améliorer la qualité sans ralentir le travail de manière excessive.

Pour une équipe de développement, c’est souvent le genre d’outil qu’on sous-estime au début, puis qu’on finit par considérer comme indispensable une fois qu’on a vu ce qu’il permet d’éviter. Et dans un projet Node.js, où les changements rapides sont la norme, ce genre de garde-fou fait souvent toute la différence entre un code qui dure et un code qui s’épuise.