Voici skott, le nouveau Madge

J’ai le plaisir de partager un projet sur lequel je travaille depuis plusieurs mois : skott.

skott est un outil qui génère un graphe de dépendances à partir de vos projets JavaScript / TypeScript / Node.js (y compris les modules TSX/JSX et ES6/CommonJS) et vous aide à découvrir les dépendances circulaires, les coûts d’import, la taille des fichiers, et bien plus encore.

Les dépendances natives de Node.js et/ou les dépendances tierces npm peuvent également être ajoutées au graphe. L’objectif principal est de reproduire l’architecture de votre application au niveau des fichiers.

Installation et utilisation

$ npm install skott

skott fournit une API pour parcourir le graphe du projet, rechercher en profondeur les dépendances circulaires, trouver les parents ou les enfants d’un ensemble de nœuds donné, et plus encore.

Voici un aperçu rapide de l’API :

import skott from "skott";

const {
  getStructure,
  findCircularDependencies,
  findParentsOf,
  findLeaves
} = await skott({
  /**
   * Le point d'entrée du projet. Doit être un module CommonJS ou ES6.
   * Pour l'instant, les fichiers TypeScript ne sont pas pris en charge
   * comme points d'entrée.
   */
  entrypoint: "dist/index.js",
  /**
   * Définit la profondeur maximale pour la recherche de dépendances circulaires.
   * Cela peut être utile pour des raisons de performance. Vaut POSITIVE_INFINITY
   * par défaut.
   */
  circularMaxDepth: 5,
  /**
   * Indique si le répertoire de base du point d'entrée doit être inclus dans
   * tous les chemins de fichiers relatifs. Pour le `dist/index.js` ci-dessus,
   * le chemin racine serait considéré comme `./`, donc `dist/` n'apparaîtrait
   * dans aucun chemin de fichier.
   */
  includeBaseDir: false
});

skott peut aussi être utilisé via la CLI.

Visualisation web

Avec le mode d’affichage webapp skott --displayMode=webapp, skott génère le graphe et ouvre automatiquement une application web interactive dans laquelle vous pouvez le visualiser plus précisément.

L'application web skott affichant le graphe de dépendances d'un projet sous forme de réseau 2D de nœuds et d'arêtes.

Comme illustré ci-dessus, on peut voir tous les nœuds créés à partir des fichiers de votre projet, et les arêtes représentent simplement les liens entre ces fichiers. Les dépendances circulaires, les dépendances tierces et les dépendances natives peuvent être affichées à la demande afin d’adapter la quantité d’informations montrées d’un seul coup.

Visualisation console

Parfois, vous ne voulez pas ouvrir une interface web. Pour cela, vous pouvez utiliser un autre mode d’affichage qui rend une UI dans la console. Voici un aperçu rapide du graphe généré pour la bibliothèque fastify :

La CLI skott affichant le graphe de dépendances de fastify dans le terminal.

On peut aussi suivre davantage de dépendances (par exemple les dépendances tierces npm) en fournissant l’option --trackThirdPartyDependencies :

La CLI skott affichant le graphe de fastify avec les dépendances tierces incluses.

Les dépendances natives de Node.js peuvent également être suivies avec l’option --trackBuiltinDependencies.

Affichage en arborescence de fichiers

Plusieurs modes d’affichage sont disponibles depuis la CLI, dont le file-tree, qui reconstruit une arborescence de fichiers à partir du graphe de manière bien plus concise :

L'affichage file-tree de la CLI skott reconstruisant l'arborescence du projet à partir du graphe.

Génération de fichiers statiques

En plus des différents modes d’affichage, skott peut aussi créer des fichiers statiques reflétant le graphe de votre projet, notamment .json, .svg, .md (via Mermaid) et .png.

Voici un exemple créant un fichier statique à partir de skott lui-même :

$ skott dist/index.js --staticFile=svg

Un graphe SVG statique généré par skott à partir de son propre code source.

Pour les projets de taille moyenne à grande, vous voudrez probablement utiliser le mode d’affichage webapp.

Dépendances circulaires

skott vous aide aussi à trouver les dépendances circulaires de manière très efficace. Vous pouvez même fournir une profondeur maximale pour éviter les recherches profondes qui pourraient être coûteuses.

Si vous n’êtes pas sûr de comprendre pourquoi les dépendances circulaires peuvent être problématiques, j’ai écrit une section, Why you should care about circular dependencies and dead code, dans la documentation racine de skott.

skott mettant en évidence les nœuds impliqués dans des dépendances circulaires.

Certaines options peuvent également être fournies pour configurer le code de sortie utilisé lorsque des dépendances circulaires sont rencontrées (vaut 1 par défaut, ce qui signifie une sortie en erreur).

skott est rapide

On peut facilement comparer skott avec madge, car skott couvre déjà la plupart des fonctionnalités que madge expose pour un projet Node.js.

J’ai lancé quelques benchmarks sur le temps nécessaire pour construire les graphes de dépendances de bibliothèques populaires avec les deux outils. Voici les résultats.

Webpack (+560 fichiers)

webpack est un module bundler statique pour les applications JavaScript modernes, probablement l’un des projets Node.js open source les plus lourds que je connaisse.

avec skott, cela prend 503 ms

Benchmark Webpack avec skott : 503 ms.

avec madge, cela prend 2,5 secondes

Benchmark Webpack avec madge : 2,5 secondes.

N.B. la différence du nombre de fichiers entre skott et madge vient uniquement des fichiers .json que skott ignore dans le graphe (ainsi que d’autres fichiers comme les binaires).

Knex.js (+60 fichiers)

knex.js est un query builder SQL flexible et portable.

avec skott, cela prend 60 ms

Benchmark Knex avec skott : 60 ms.

avec madge, cela prend 450 ms

Benchmark Knex avec madge : 450 ms.

Pour construire l’intégralité du graphe de knex.js avec encore plus de métadonnées, skott est 7,5× plus rapide.

Fastify.js (30 fichiers)

fastify.js est un framework web rapide et à faible surcharge pour Node.js.

avec skott, cela prend 50 ms

Benchmark Fastify avec skott : 50 ms.

avec madge, cela prend 350 ms

Benchmark Fastify avec madge : 350 ms.

Dans ce cas, skott est 7× plus rapide que madge.

skott est extensible

skott a pour ambition d’offrir des fonctionnalités extensibles à n’importe quel langage, à condition d’implémenter au passage des parsers spécifiques. J’ai commencé uniquement par JavaScript, puis j’ai progressivement ajouté le support de TypeScript et de TSX/JSX. Pourquoi ne pas amener d’autres langages sur la table également ?

La suite

Cet article est le premier chapitre de l’aventure de la construction de skott. La série se poursuit sous le capot :

Ce qu’il faut pour construire un outil d’analyse statique : parsers, AST et comment le code source est analysé.
Le Test-Driven Development et l’injection de dépendances sont la voie : comment tout le pipeline a été rendu entièrement testable.

skott est open source, les issues, retours et contributions sont les bienvenus sur GitHub.