Semaine 2 – Publication du codemod
#web #emberjs #codemod #docs #embroider #vite #vitest
À l’issue de cette deuxième semaine, nous avons publié la première version de ember-vite-codemod ! Ce codemod permet de construire des applications Ember >=5.12 avec Vite. En plus de toutes les manipulations d’AST, j’ai eu l’occasion d’avoir une vision plus claire de la direction que nous prenons avec cet outil.
Faire ou documenter #
Comme défini la semaine dernière, un codemod est un script qui transforme automatiquement votre code. Pour le dire autrement, imaginons que vous documentiez entièrement la manière dont le code doit être transformé : un codemod est comme un script qui suit automatiquement votre documentation, afin que vos utilisateur·rices n’aient pas à le faire elles·eux-mêmes. Mais tant que la documentation existe, le codemod n’est qu’un bonus avec deux objectifs : faire gagner du temps à vos utilisateur·rices et les protéger d’un sentiment de submersion qui pourrait les décourager d’utiliser votre bibliothèque.
Avec cette idée en tête, c’est à vous de décider ce que votre codemod peut ou ne peut pas faire ; qu’est-ce qui fait partie de son travail ? Qu’est-ce qui doit rester de la responsabilité du·de la développeur·se qui l’exécute ?
Dans le cas d’ember-vite-codemod, un exemple pertinent pourrait être la configuration du linter versus la nouvelle configuration Babel. Un schéma récurrent dans certaines applications Ember anciennes est d’avoir @babel/plugin-proposal-decorators installé et configuré dans le fichier eslint.config.mjs :
requireConfigFile: false,
babelOptions: {
plugins: [
['@babel/plugin-proposal-decorators', { decoratorsBeforeExport: true }],
],
},
Tandis que que dans une nouvelle application Embroider+Vite, la dépendance decorator-transforms est utilisée dans la nouvelle configuration Babel babel.config.cjs. Supposons que le schéma ci-dessus soit présent dans l’application Ember et que vous exécutiez le codemod, alors le linter générera une erreur de parsing : “Cannot use the decorators and decorators-legacy plugin together”.
Mais veut-on faire quelque chose à ce sujet ? La réponse est non. Le but du codemod est de faire en sorte que l’application build avec Vite. La configuration du linter n’est pas liée au build ; c’est la responsabilité du·de la développeur·se, donc on préfère documenter plutôt que faire.
Retour vers Ember 3.28 #
J’ai implémenté la première itération du codemod en utilisant une application Ember 6.2 fraîchement générée. Mais nous voulons que les applications Ember 3.28 puissent également être buildées avec Vite, donc nous avons besoin d’une stratégie pour remonter jusqu’à cette version. Cette partie du travail a été le principal axe de mon collègue Chris Manson ; pour y parvenir, nous avons utilisé des tests et l’intégration continue (CI).
L’idée est que nous avons un job de CI qui exécute un test Vitest appelé all-versions.test.js. Ce test :
- Génère une nouvelle application Ember pour chaque version d’Ember que nous voulons supporter.
- Crée un test d’acceptation afin que, lorsque les tests de l’application s’exécutent, elle builde et visite la page d’accueil.
- Exécute les tests pour vérifier qu’ils passent lorsque l’application est buildée avec Broccoli.
- Exécute le codemod.
- Exécute les tests une fois de plus pour vérifier qu’ils passent toujours, maintenant que l’application doit builder avec Vite.
Toutes les versions que nous voulons supporter sont commentées, et toutes les versions que nous supportons sont exécutées :
const testVersions = [
// ['ember-cli-3.28'],
// ['ember-cli-4.12'],
// ['ember-cli-4.4'],
// ['ember-cli-4.8'],
// // test helpers seems to be broken for most ember versions 😭
// ['ember-cli-5.4', ['@ember/test-helpers@latest']],
// ['ember-cli-5.8', ['@ember/test-helpers@latest']],
['ember-cli-5.12', ['@ember/test-helpers@latest']],
['ember-cli-latest'],
];
Avoir publié la première version du codemod est une grande réussite pour cette semaine. Maintenant que nous prévoyons de communiquer à son sujet, nous pourrions recevoir des retours de la communauté. Il y a également un cas pour lequel nous préférons “faire plutôt que documenter”, à savoir les applications construites avec @embroider/webpack. Ça pourrait être mon objectif la semaine prochaine.