Integration Standards — extension VS Code pour les templates .njk

Extension maison (France Travail) qui outille les templates Nunjucks (.njk) : elle convertit les composants Fractal en macros, souligne en direct les écarts de convention (comme ESLint / Stylelint) et formate les fichiers. Auto-suffisante : le moteur est embarqué, rien à installer dans les repos analysés.

Fonctionnalités

Au-dessus de tout : un interrupteur transverse — ftIntegrationStandards.enable (maître, coupe tout). Chaque fonctionnalité a ensuite son propre réglage. Voir Réglages.

FT Tokens — coller une variable Figma en variable CSS France Travail

Un intégrateur copie le nom d'une variable depuis Figma (ex. Color/Decorative/blue-weaker) et l'insère dans un .scss/.css sans conversion manuelle. Deux commandes (toujours actives, indépendantes des réglages) lisent le presse-papier, transforment, et insèrent au curseur (en remplaçant la sélection éventuelle) :

• Transformation : minuscules ; chaque run de / ou d'espaces → - ; tirets internes préservés (blue-weaker, spacer-16) ; retrait des - de début/fin ; préfixe --ft-.
• Presse-papier vide / non convertible → rien inséré + message d'info.
• Idempotent : une entrée déjà --ft-… ou var(…) est laissée telle quelle.
• Raccourcis scopés aux langages scss / css / sass / less (la commande reste disponible via la palette partout). Reprend le namespace --ft- du snippet historique .vscode/ft-tokens.code-snippets — mais, contrairement à un snippet, l'extension embarque le raccourci partagé.

Conversion Fractal → macro (opt-in)

• Conversion pure : retire le wrapper params: (et dé-indente d'un niveau), remplace {% component %} par {{- ds.macro(…) -}}, et préserve la mise en page de l'auteur (un objet multi-ligne reste multi-ligne). Aucun autre reformatage ; un fichier sans {% component %} reste byte-identique.
• Au save : désactivé par défaut (opt-in) — il faut passer convertOnSave à true et que l'extension soit le formateur des [nunjucks] (voir l'astuce en bas des Réglages).
• À la demande (toujours actif, indépendant des réglages) :
  • Cmd+Alt+D — convertit la sélection dans l'éditeur ;
  • clic droit sur un fichier .njk ou un dossier (dans l'explorateur, section dédiée « Convertir les {% component ... %} en macro DS ») → convertit ce fichier, ou en lot tous les .njk du dossier.
• Intelligence de conversion : camelCase des variantes (@button--icon → ds.buttonIcon), injection des paramètres manquants depuis les *.config.js du design-system, whitelist des macros DS existantes, blacklist des composants non équivalents (ex. @radio), alias de renommage, marqueurs de trim systématiques {{- … -}}. Idempotente.
• Fonctionnalité temporaire de migration (destinée à disparaître une fois la migration finie).

Lint live (activé par défaut)

Analyse en temps réel — au fil de la frappe (debounce 250 ms), à l'ouverture et à la sauvegarde — et souligne. Survoler le souligné affiche le message et le code de règle.

Le niveau de chaque règle traduit l'effort de correction, pas une gravité abstraite :

• 🔴 erreur — casse le build ou le rendu ;

• 🟠 avertissement — le formateur le corrige tout seul (⇧⌥F ou à la sauvegarde) ;

• 🔵 information — demande une décision humaine (refonte, migration à coordonner). Ces règles restent listées dans le panneau Problems mais ne colorent pas le nom du fichier dans l'explorateur : pas de pression sur ce qui ne peut pas être corrigé dans l'immédiat.

• format — littéral d'argument mal formaté, catégorisé pour un message précis, souligné pointé sur le caractère fautif :

  • formatSpacing — espace en trop/manquant autour de :, , ou des accolades ;
  • formatIndent — indentation (4 espaces par niveau) ;
  • formatStructure — mise en ligne (élément unique à condenser / objet à éclater) ;
  • format — écarts mixtes (repli).

• camelCase — clé d'argument de macro non camelCase (jamais auto-renommé : le contrat de la macro prime ; safelist pour les snake_case légitimes).

• missingComma — 🔴 erreur : virgule oubliée entre deux propriétés d'un objet multi-ligne (ex. appel de macro), qui casserait le build Nunjucks.

• orphanTag — 🔴 erreur : balise laissée orpheline, c'est-à-dire encore ouverte quand une balise englobante se ferme (ex. <li><a href="#">Texte</li>). Le navigateur devine alors où l'élément se termine : le balisage suivant est avalé par le mauvais élément, et la mise en page, les sélecteurs CSS et les requêtes DOM cassent silencieusement, différemment selon les navigateurs. (Inspiré de H025 de djlint.) ⚠️ Aucune tolérance pour les « fermetures optionnelles » de HTML (</li>, </p>, </td>, </option>…) : décision d'équipe, toute balise ouverte doit être fermée explicitement — la spec ne les autorise que selon la balise qui suit, ce que personne ne retient et qui rend la relecture ambiguë.

• unmatchedClose — 🔴 erreur : une balise fermante sans ouvrante correspondante à l'intérieur d'un {% block %} (fermeture en trop, ou balise mal nommée — ex. un </a> qui prétend fermer un <button>). Un {% block %} est auto-contenu : ce qui y est fermé doit y avoir été ouvert. En dehors d'un block, rien n'est signalé — un partial peut légitimement fermer un wrapper ouvert dans un autre fichier.

• FT001 — attribut class avec plus de 5 classes. Deux formes : class="a b c d e f" littéral, et une string de 6+ classes dans un | joinClasses.

Reformatage global (activé par défaut)

Reformate le fichier entier via Format Document (⇧⌥F) ou au save (si editor.formatOnSave). Formatage sûr : « espace uniquement » (ne touche jamais au contenu des chaînes ni aux expressions), idempotent. Trois passes :

• formatSource — littéraux d'arguments : collapse des objets/tableaux à ≤ 1 élément, objet-valeur toujours multi-ligne, espacement clé: valeur et , ;
• reflow — structure HTML : contenu inline vs bloc éclaté, jointures des délimiteurs {{ }} / {% %} ;
• normalizeSpacing — espace intérieur (façon WordPress « Space Usage ») : après {{ {{- {% {%-, avant }} -}} %} -%} (ex. {{data.tag}} → {{ data.tag }}), et de chaque côté du pipe de filtre | (x|upper → x | upper). Crochets [ ] selon la règle WP « Array Members » : littéral de tableau et index variable espacés ([ 'a', b ], x[ i ]), index littéral collé (x['bar'], x[0]). Parenthèses ( ) non touchées ;
• reindent — indentation de chaque ligne selon l'imbrication (4 espaces).

Pour utiliser ce formateur par défaut sur les .njk, régler dans les settings du workspace : "[nunjucks]": { "editor.defaultFormatter": "ft-integration.standards" }.

Réglages

Un interrupteur maître, puis un réglage par fonctionnalité.

Désactivation perso sans impacter l'équipe : mettre le réglage à false dans vos User Settings globaux (jamais poussés), pas dans le .vscode/settings.json versionné.

Conversion : par défaut rien ne se passe côté conversion à la sauvegarde (opt-in). Si tu actives convertOnSave, alors seuls les {% component %} sont convertis ; tout le reste du fichier reste byte-identique. Dans tous les cas, la conversion reste disponible à la demande via Cmd+Alt+D et le clic droit sur un fichier .njk ou un dossier.

Configuration des règles

La config est entièrement embarquée dans l'extension et uniforme : il n'y a pas de fichier de config par projet ni par workspace, et rien à paramétrer côté dépôt. Les règles appliquées sont celles décrites ci-dessus ; seuls les réglages du tableau précédent permettent d'activer ou de désactiver une fonctionnalité.

Notes techniques

• Aucune dépendance npm (API vscode uniquement, fournie à l'exécution).
• Débounce 250 ms à la frappe ; analyse aussi à l'ouverture et à la sauvegarde.
• Langage détecté via languageId === 'nunjucks' ou l'extension de fichier .njk.
• Résilience : chaque module du moteur est chargé isolément — un module cassé ne désactive que SA fonctionnalité, l'extension s'active toujours.