Contribuer

Règles d'architecture

Elles sont détaillées dans les pages d'architecture et résumées dans AGENTS.md ; les voici en bref.

1. Les fichiers binaires et les objets Git restent des Uint8Array. Ne jamais convertir le contenu de /workspace/.git/ en texte (vfs.readBinaryFile / writeBinaryFile).
2. Toute écriture passe par le VFS ou le service Git, qui notifient leurs modifications. Ne jamais rafraîchir à la main l'arborescence, le statut Git ou les onglets : les stores le font seuls. Voir Stores et synchronisation.
3. Jamais /workspace en dur : resolveWorkspacePath, getRelativeWorkspacePath (src/utils/path.ts) ou les méthodes de Workspace.
4. Les noyaux Basthon sont utilisés tels quels, toujours isolés. Pas de surcouche des classes Basthon, pas de noyau « legacy », pas de COOP/COEP. Voir Intégration de Basthon.
5. Chaque couche ne dépend que des précédentes : utils, i18n → services → languages → stores → composables → commands → components. Un service n'importe pas de store ; ESLint le vérifie.
6. Décrire une fois : un langage dans src/languages/, une action de l'IDE dans src/commands/catalog.ts, une commande du terminal comme ShellCommand. Ne jamais tester une extension de fichier ailleurs que dans le registre des langages ; pas de gestionnaire de raccourci ad hoc.
7. Pas de dialogue natif (confirm, alert, prompt) : passer par le store dialogs (voir Vue d'ensemble).
8. Aucun texte affiché en dur : tout passe par t(), et une nouvelle clé s'ajoute dans les dix langues (voir Langues de l'interface).
9. Préférences par src/utils/storage.ts, jamais localStorage directement : le stockage peut être absent ou refusé (navigation privée, iframe), et les valeurs lues sont validées.
10. Pas de v-html sur une sortie de programme : tout contenu produit par le code de l'élève s'affiche dans une iframe sandboxée.
11. Accessibilité : motifs WAI-ARIA par les briques communes (BaseDialog, MenuButton, useTreeNavigation, useSeparator, useTabEscape), couleurs de texte par les jetons text-vscode-*. Voir Accessibilité.
12. Options de la page hôte par postMessage, jamais par l'URL ; toute nouvelle fonction Git disparaît quand Git est désactivé. Voir Intégration dans une page hôte.
13. Erreurs typées : une erreur à reconnaître est une classe de src/utils/errors.ts, testée par instanceof, jamais par son message.

Style

• Vue 3 avec <script setup> et TypeScript strict ; stores Pinia en style « setup ». Pas de any (ESLint l'interdit : un avertissement bloque le commit).
• Commentaires en français, sobres : ils disent pourquoi, pas ce que dit déjà le code. Messages destinés aux développeurs (console.warn) en anglais.
• Un composant ou un module trop long se découpe par responsabilité plutôt que par type de code (voir src/stores/editor/, src/services/git/).
• Couleurs et tailles par les classes Tailwind du thème (bg-vscode-*, text-vscode-*), jamais de couleur brute.

Avant de proposer une modification

npm run lint
npm test
npm run build

npm run lint vérifie aussi les frontières entre couches et interdit window.confirm, alert et localStorage. Il ne tolère aucun avertissement (--max-warnings 0), en local comme en CI.

Un hook Git pre-commit (Husky, installé par npm install) lance ESLint sur les fichiers du commit (lint-staged) et refuse le commit à la moindre erreur ou au moindre avertissement. Corriger plutôt que contourner (--no-verify).

Puis vérifier le comportement dans le navigateur (npm run dev), et lancer npm run test:e2e pour tout ce qui touche à l'exécution du code : le faux noyau des tests Vitest ne prouve rien sur le vrai Basthon.

Commits

• Un commit par sujet (commits atomiques), avec un message au format Conventional Commits en français : feat(terminal): …, fix(pwa): …, refactor(git): …, build: …, docs: …, test: …. La portée entre parenthèses nomme le domaine.
• Chaque commit compile et passe le lint ; la documentation qui décrit le changement est dans le même commit.
• Le travail se fait aujourd'hui directement sur main ; c'est le mainteneur qui pousse.

La documentation

Cette documentation vit avec le code. Toute modification qui change l'architecture, un choix technique, une règle, une commande ou l'organisation des dossiers la met à jour dans le même commit :

• une page d'architecture par domaine, avec ses schémas Mermaid (flowchart pour les structures, sequenceDiagram pour les échanges), tenus à jour avec le code ;
• une nouvelle page s'ajoute à la barre latérale de docs/.vitepress/config.ts ;
• une décision structurante s'ajoute aux décisions, une étape marquante à la chronologie, un chantier repéré mais non fait aux pistes ;
• les règles qui s'imposent à tous vont aussi dans AGENTS.md.

Le guide d'utilisation décrit l'application pour les élèves et les enseignants, en français et en anglais (docs/en/guide/, mêmes noms de fichiers, pour que le bouton de langue mène à la même page). Une fonction visible ajoutée ou modifiée (bouton, menu, commande, raccourci, comportement) y est décrite dans le même commit, dans les deux langues ; si l'interface change à l'écran, npm run docs:captures refait ses captures d'écran dans les deux langues (script docs/captures/captures.shots.ts, à compléter pour une nouvelle capture).

Vérifier avec npm run docs:build : le build échoue sur un lien mort (une URL d'exemple s'écrit entre accents graves pour ne pas devenir un lien).

Travailler avec un agent IA

Le projet est développé en grande partie avec des agents IA (Claude Code). Ils lisent :

• AGENTS.md : les règles, l'organisation du code, les commandes ; court et toujours à jour ;
• les skills de .agents/skills/ (.claude/skills en est un lien) : des consignes par domaine, que l'agent charge quand il touche ce domaine.

Skill	Quand
basthon-kernels	exécution du code, noyaux, consoles, python dans le terminal
documentation-contributeurs	toute modification d'architecture ; écrire ou relire cette documentation
tests-organisation	créer, déplacer ou modifier un test
vfs-git-binary-integrity	VFS, isomorphic-git, fichiers binaires, ZIP
codemirror6-architecture	extensions, compartiments et thèmes de CodeMirror
pinia-store-patterns, vue3-typescript-architecture, tailwind-ui-system, vue-quality-testing	stores, composants, styles, tests de composants

Une règle découverte en travaillant (un piège, une convention) va dans la skill concernée ou dans AGENTS.md, pas seulement dans la conversation.