Contribuer
Merci de prendre ce temps. ddd-ts-kit se construit en public, et chaque contribution compte : un signalement de bug avec sa reproduction, une coquille, une traduction, un test, un adaptateur, une règle. Cette page dit comment commencer, puis les règles que suit chaque changement.
Votre première contribution
Section intitulée « Votre première contribution »- Choisir un sujet. Les issues étiquetées good first issue ne demandent pas de connaître le checker en profondeur ; celles étiquetées help wanted sont plus grandes. Dites sur l'issue que vous la prenez, pour que deux personnes ne fassent pas le même travail. Pour une idée qui n'a pas encore d'issue, ouvrez d'abord une discussion ou une proposition.
- Installer. Forkez le dépôt, clonez-le, et lancez les commandes ci-dessous : ce sont celles que lance la CI. Node 22.12 ou ultérieur.
- Changer, puis vérifier ce que vous avez touché. Un changement de documentation demande
npm run check:dashes,npm run docs:translationset, s'il contient un exemple de code vérifié,npm run docs:samples; un changement de code demande la construction, les tests et le lint. Chaque package est tenu à 100 % de ses lignes (vitest.config.ts) : le nouveau code vient avec ses specs. Une vérification qu'aucune spec ne peut atteindre est retirée, ou laissée hors de la mesure dans l'enregistrement de décision de la mesure, jamais déplacée sur une ligne déjà exécutée. Les hooks du plugin sont tenus à 100 % de leurs lignes, branches et fonctions (npm run test:plugin) : une branche qu'aucun test n'atteint le fait échouer, et une branche qu'aucune entrée de hook ne peut atteindre est retirée. Le tableau nomme le fichier, pas la branche :node pipeline/monorepo/uncovered-branches.mjs coverage/plugin.lcovnomme chaque branche que le passage n'a pas prise, depuis le lcov qu'il a écrit. - Ouvrir une pull request. Son titre est un sujet de commit conventionnel ; son modèle demande ce qui change, pourquoi, et comment cela a été vérifié. Chaque pull request est relue par le mainteneur.
Les contributions particulièrement bienvenues :
- un adaptateur pour un broker, un ORM, un framework HTTP ou une bibliothèque de validation que le kit ne prend pas encore en charge : il implémente le port et passe la suite de contrat de ce port ;
- des tests pour les branches d'un package qu'aucune spec ne prend encore ;
- la documentation : une page qui vous a paru obscure, un exemple qui manque, une traduction ;
- un retour d'un vrai projet : ce qui a tenu, ce qui a gêné, dans les Discussions.
Vous n'écrivez pas le français ? Dites-le dans la pull request : le mainteneur peut écrire la page française dans la même pull request.
Commandes
Section intitulée « Commandes »npm cinpm run buildnpm testnpm run lintnpm run format:checknode packages/cli/dist/bin.js check --selfnpm run check:dashesnpm run check:paritynpm run docs:translationsnpm run docs:samplesnpm run test:pluginnpm run lint est ESLint avec un cache par contenu (.eslintcache/, 1 à 2 secondes quand rien n'a changé). Le hook de
pre-commit et le job Lint d'une pull request lancent Oxlint à la place (npm run lint:oxlint, avec les types, les
règles du kit chargées comme plugin JS, configuré par .oxlintrc.json) ; le trunk et la nuit lancent ESLint sur tout
l'arbre, qui porte aussi no-unsafe-enum-assignment, et le job d'essai compare les deux. Un changement de
eslint.config.mjs atteint .oxlintrc.json dans le même commit. Vitest garde les modules transformés des sources dans
node_modules/.vitest-cache (actif par défaut, ignoré par git, non conservé par la pipeline) : il rend une deuxième
exécution d'un package environ 40 pour cent plus rapide, et rm -rf node_modules/.vitest-cache le vide.
zero-violation.spec.ts et formatted.spec.ts génèrent chaque pile : ils ne tournent que dans les
tranches de bout en bout (DDD_TS_KIT_E2E=1), ni dans npm test ni dans le hook pre-push.
Les commandes lourdes sur une station de travail
Section intitulée « Les commandes lourdes sur une station de travail »Une exécution de la suite unitaire, de la suite d'intégration ou d'une famille de specs de bout en
bout prend 2,5 à 7 Go, et plusieurs à la fois (plusieurs sessions de code, un hook
pre-push à côté d'une exécution) ont déjà fait redémarrer un poste. Deux choses les bornent :
- Un verrou pour la machine. Les scripts
ci:test:*et l'étape unitaire du hookpre-pushpassent parpipeline/monorepo/heavy-lock.sh, qui tient l'une de deux places (des fichiers de verrou dans$XDG_RUNTIME_DIR,DDD_TS_KIT_HEAVY_SLOTSchange le nombre) : une troisième commande lourde attend une place et le dit, au lieu d'ajouter sa mémoire aux autres. Toute autre commande lourde y passe à la main, une exécution de Stryker sur l'exemple par exemple :bash pipeline/monorepo/heavy-lock.sh npm run test:mutation. Dans un pipeline (CIdéfini), ou sansflock, la commande s'exécute aussitôt. - Deux travailleurs Vitest dans les scripts de bout en bout.
ci:test:e2e,ci:test:e2e:stackset les autres scriptsci:test:*des familles démarrentVITEST_MAX_WORKERS=2: les projets qu'ils génèrent ne prennent pas chacun la moitié des cœurs. DéfinissezVITEST_MAX_WORKERSvous-même pour le changer.
Règles de base
Section intitulée « Règles de base »- docs/ARCHITECTURE.fr.md est le seul document normatif. Un changement de règle commence là, puis atteint le checker, les templates et les skills dans la même pull request. Le test de bout en bout de la CLI (tout générer, puis vérifier) doit rester vert : le générateur et le checker ne sont jamais en désaccord.
- Les membres d'une famille de paquets (les quatre ORM, les brokers, les loggers) sont à
parité : une option, ou une capacité d'un contrat, qu'un membre a, les autres l'ont aussi, ou
pipeline/monorepo/families.mjsdit, membre par membre, pourquoi non.npm run check:parityéchoue sur une asymétrie que personne n'a écrite, et sur une asymétrie écrite qui n'est plus vraie. Un comportement d'un adaptateur est prouvé par le contrat de son port dans@ddd-ts-kit/testing, jamais par une spec d'un seul paquet : une nouvelle option vient avec la capacité du contrat qui la prouve, que chaque membre exécute alors. - Ce que
initet les presets refusent, et ce que les membres d'une famille de flags (les ORM, les conteneurs, les frameworks HTTP, les brokers, les runners...) génèrent différemment, est écrit danspackages/cli/test/support/support-matrix.ts, chaque lignedecidedounot yetavec sa raison.support-matrix.spec.tsessaie chaque flag et chaque paire de flags, et génère chaque membre d'une famille avec toutes les capacités activées : un refus, un TODO de plateforme ou un paquet du kit qu'aucune ligne n'explique échoue, comme une ligne qui ne tient plus. Une lignenot yetest un manque qui reste en vue jusqu'à ce qu'une pull request le comble et retire la ligne. La même spec génère toutes les sortes de fichiers dans un projet multi-tenant sur chaque ORM et lit chaque appel du code généré à une classe ou une fonction du kit dont les options prennent untenant(lu dans les sources des paquets) : un appel sans lui échoue, sauf siTENANT_GAPSdit pourquoi. - Une ligne de ces deux registres rend vert un contrôle qui échouait : c'est donc une décision du
mainteneur, jamais le plus court chemin vers une CI verte. Sa raison dit ce que fait le membre
à la place (une raison trop courte, ou une promesse pour plus tard, échoue), la CI d'une pull
request annote chaque ligne qu'elle ajoute (
pipeline/monorepo/asymmetries.mjs), et dans Claude Code le hook de.claude/settings.jsondemande avant toute modification de ces fichiers, quel que soit le mode de permission. - Une nouvelle règle de vérification vient avec une fixture qui passe et une fixture qui
échoue, une phrase
fixet une entréeexplain. - Avant 1.0, une règle qui prévient un problème est une erreur tout de suite : une nouvelle règle
prend
errorpar défaut (rien dansdefault-severities.tspourddd-ts-kit check,recommended: 'error'pour la règle ESLint), et ce qu'une règle juge de plus aussi. Il n'y a pas d'avertissement d'abord, ni de version où elle deviendrait une erreur plus tard : une règle laissée en avertissement pour adoucir une montée de version est une règle qu'un projet apprend à ignorer. Une règle n'estwarnque lorsque ce qu'elle signale peut être juste et qu'un lecteur tranche (privacy/*, qui lit des noms, outree/documented-paths). Son fichier dechanges/est un changement cassant : il dit ce que la règle signale, la correction, et une ligneTo move:avecddd-ts-kit check --rule <id>pour lister les fichiers à reprendre. Une disposition ou une forme qu'une version antérieure a écrite est signalée de la même façon, en erreur, avec la commande qui la déplace (ddd-ts-kit context-layout,ddd-ts-kit docs) ; le kit ne la lit que pour que cette commande puisse la déplacer. - Un nouveau template compile tel qu'il est généré et ne porte de marqueurs
TODO(domain)que là où une connaissance du métier est nécessaire. - Les packages d'exécution gardent les bibliothèques tierces derrière des dépendances pairs
(peer dependencies) optionnelles et des points d'entrée par sous-chemin.
@ddd-ts-kit/kernelet la CLI n'ont aucune dépendance d'exécution. - Les skills restent courtes : elles disent à un agent quoi lancer et quoi décider, et renvoient à la référence au lieu de la répéter.
- Une page de documentation dit ce que fait le code aujourd'hui : un exemple compile avec les packages actuels, une commande s'exécute telle qu'elle est écrite, et ce qui n'a pas pu être vérifié est dit sur la page. docs/README.fr.md en est l'index.
- L'anglais dans le code, les messages de commit, la CLI et le checker. Chaque page de
documentation a une traduction française à côté d'elle (
X.fr.md), tenue à jour dans la même pull request : voir docs/translation.fr.md pour les conventions, le glossaire, le style des schémas et les exemples de code vérifiés (npm run docs:translationsetnpm run docs:samples, lancés par la CI). - Le site de la documentation (
site/, publié à https://ddd-ts-kit.github.io/ddd-ts-kit/fr/) est construit à partir de ces mêmes pages, qui restent sa seule source.npm run site:devassemble les pages et sert le site surhttp://localhost:4321/ddd-ts-kit/(relancez-le après avoir changé une page) ;npm run site:buildle construit comme la CI, et échoue sur un lien ou une ancre qui ne mène nulle part. Une nouvelle page reçoit sa route danssite/scripts/routes.mjs. La carte qu'affiche un lien partagé est dessinée danssite/src/assets/social-card.svg;npm run social-card --workspace sitela rend danssite/public/social-card.png, versionné. - Ni tiret cadratin ni tiret demi-cadratin, dans aucune langue (
npm run check:dashes, lancé par la CI). - Des commits conventionnels :
<type>(<scope>): <summary>. - Ce qu'une pull request change pour un utilisateur s'écrit dans un fichier à elle,
changes/<what-it-does>.md(changes/README.md), jamais dansCHANGELOG.md; une pull request qui change le plugin (skills, agents, hooks) en a un, laisseversiondeplugin/.claude-plugin/plugin.jsontel quel, et passeclaude plugin validate . --strict. Deux pull requests n'écrivent alors jamais la même ligne : l'une fusionnée laisse les autres fusionnables telles quelles, leurs vérifications toujours valables. Le job de contrôles statiques de la CI le tient (node pipeline/monorepo/changes.mjs --check --base <ref>).
La suite d'évaluation du plugin
Section intitulée « La suite d'évaluation du plugin »Le plugin est une configuration d'agent : des skills, des agents, un hook. Un changement de
formulation peut casser sans bruit ce qu'une skill promet, et aucun test unitaire ne lit une
skill. La suite sous plugin/evals/ est son test de régression, lancée par
claude plugin eval (Claude Code 2.1.269 ou ultérieur) : chaque cas est un prompt soumis à
une session sur un projet de référence, et des évaluateurs qui lisent ce que la session a fait.
Le playbook du cycle de vie AI-native d'Anthropic
demande exactement cela de toute configuration qui pilote un agent.
Un cas est un répertoire de plugin/evals/ :
case.yamlle nomme et nomme son script de préparation,fixture.sh, qui chargeplugin/evals/lib/scheduling-example.sh(l'exemple scheduling copié dans l'espace de travail vide de l'exécution, lenode_modulesde ce dépôt lié pour quenpx ddd-ts-kitsoit la CLI construite, un commit git) et plante ce dont le cas a besoin : une violation, une story, un verrou ;prompt.mdtient le prompt, avecmax_turns,timeout_secondsetallowed_toolsdans son en-tête (Bash,EditetWritesont accordés à l'exécution par--allow-tools) ;graders/*.md, un évaluateur par fichier : les déterministes d'abord (tool_usedavec uninput_match,regexsur le dernier message ou sur un fichier,file_exists), puis un jugellmpour ce que seule une lecture peut dire. Un cas passe quand son score atteint le seuil.
Trois règles tiennent la suite. Chaque régression qu'un utilisateur signale sur une skill, un agent ou le hook devient un cas avant d'être corrigée, nommé d'après la promesse qu'il tient. Chaque exécution a deux bras, avec le plugin et sans lui (la base sans plugin) : un cas que le bras sans plugin passe aussi ne mesure rien, et il est retiré ou affûté jusqu'à distinguer les deux. Un cas reste peu coûteux : un prompt précis, un nombre de tours borné, l'exemple comme projet de référence plutôt qu'un projet à générer.
La suite est désactivée par défaut. Elle dépense des crédits d'API : chaque cas est une
session complète de Claude Code, lancée dans les deux bras et --runs fois (3 par défaut), si
bien que les douze cas font 24 sessions avec --runs 1 et 72 avec le défaut, et qu'une
exécution nocturne de vingt cas ferait soixante sessions par nuit. Rien ne tourne sur une pull
request, à heure fixe, ni dans npm test. Un mainteneur la lance à la main depuis l'onglet
Actions (le workflow agent-evals.yml, workflow_dispatch seulement) une fois le secret
ANTHROPIC_API_KEY ajouté au dépôt ; sans le secret, le job le dit et se termine au vert.
Cette exécution utilise --runs 1, --threshold 0.8 et un plafond de 10 USD, publie le rapport
comme artefact et écrit les scores dans son résumé ; les déclencheurs pull_request et
schedule en commentaire dans le fichier montrent comment l'activer, le coût indiqué à côté.
Pour lancer un cas en local, sur vos propres identifiants, la CLI construite (npm run build) :
claude plugin eval plugin --runs 1 --no-publish --max-cost-usd 5 --case describe-not-tree-walk \ --scaffold --allow-tools Bash Write Edit --trust-plugin --output-dir /tmp/ddd-ts-kit-evals--scaffold lance le fixture.sh du cas (ne le passez jamais pour une suite que vous n'avez pas
lue), --max-cost-usd est un plafond ferme, et --output-dir garde les résultats hors de
l'arbre (plugin/evals/results/, le défaut, est ignoré par git mais lu par
npm run check:dashes). Accorder le shell demande le bac à sable de Claude Code, bubblewrap
et socat sous Linux : sans eux l'exécution est refusée plutôt que lancée sans confinement, et
un cas qui n'accorde aucun outil (deviation-refused) tourne quand même. Un cas, une fois,
pendant que vous l'écrivez : la suite entière est l'exécution du mainteneur. La forme d'un cas se
vérifie sans rien lancer : claude plugin eval n'a pas d'exécution à blanc, donc analysez chaque
case.yaml, l'en-tête de chaque prompt.md et de chaque évaluateur avec un analyseur YAML, et
comparez avec le modèle qu'écrit claude plugin eval init --bare <name>.
Comment un changement atteint main
Section intitulée « Comment un changement atteint main »main est protégée : aucun push direct, aucun push forcé, un historique linéaire. Un
changement arrive par une pull request dont le titre est un sujet de commit conventionnel, est
réduit à un seul commit (squash), et fusionne une fois que le job gate de la CI, la
vérification du titre et l'analyse CodeQL sont passés et que chaque conversation de revue est
résolue. Activez la fusion automatique et passez à autre chose :
gh pr create --fillgh pr merge --auto --squashUne fois ces vérifications passées, la fusion automatique confie la pull request à la file de
fusion (merge queue) de main. La file la réduit en un commit posé sur le tronc et sur les pull
requests entrées avant elle, et relance les mêmes vérifications sur ce commit (l'événement
merge_group) : une pull request verte seule mais qui casse avec une autre n'atteint jamais
main, et personne ne met à jour une branche seulement parce que main a avancé. Un échec dans
la file l'en retire, avec le run qui a échoué.
Une revue par IA commente chaque pull request ouverte depuis une branche de ce dépôt, prête pour la
revue (.github/workflows/pr-review.yml) : PR-Agent, le relecteur open source de Qodo, sur NVIDIA
Nemotron, avec les règles d'AGENTS.md et de .pr_agent.toml. C'est un commentaire, jamais une
vérification requise ni une approbation. Qui peut écrire ici en demande davantage dans un
commentaire : /review de nouveau, /improve pour des suggestions de code (publiées en fils de revue,
qu'il faut alors résoudre avant la fusion), /ask <question>. Une pull request venue d'un fork n'a pas
de revue, la clé étant un secret.
Ce que la CI exécute dépend de la pull request (docs/proposals/generated-project-families.fr.md).
Ouvrez-la en brouillon tant que la branche n'est pas définitive : un brouillon n'exécute que les
vérifications rapides, et la marquer prête exécute toute la CI. Une pull request qui ne change que des
documents, le site, le texte du plugin ou l'exemple ne génère aucun projet ; une qui touche quoi que
ce soit sous packages/ ou pipeline/, ou la configuration racine, génère un ensemble couvrant de 16 stacks où chaque valeur de chaque drapeau apparaît.
Le tronc génère toutes les stacks, installe sur npm et exécute l'alias sur Node 24 ; la nuit et la
pull request d'une release (titre chore(release) ou branche release/*) ajoutent pnpm, Node 22,
les états intermédiaires de la première minute, la porte de couverture sur dix stacks, les paires et
les migrations.
Les workflows épinglent chaque action à un commit, avec sa version en commentaire ; Dependabot
propose les mises à jour. Le job Security échoue sur un avis de gravité high ou critical dans une
dépendance de production (npm run ci:audit). Un avis sans version corrigée qui ne peut pas atteindre
un projet utilisant le kit est inscrit dans pipeline/monorepo/audit-exceptions.json avec sa raison
et une date à un mois au plus : passé cette date, ou dès que l'avis disparaît, le job échoue tant que la
ligne n'est pas retirée ou renouvelée.
L'OpenSSF Scorecard (.github/workflows/scorecard.yml) note la tenue de la chaîne
d'approvisionnement du dépôt, à chaque push sur main et chaque semaine ; sa note est le badge du
README et ses constats sont des alertes d'analyse de code. Ce n'est jamais une porte : une
vérification qui baisse se reprend dans une pull request à part. Une vulnérabilité se signale en privé : voir
SECURITY.fr.md. Conduite : CODE_OF_CONDUCT.fr.md.
Publier une version
Section intitulée « Publier une version »Les packages de packages/ sont publiés ensemble, sous une seule version. Une version
corrective ne casse jamais : --set en refuse une tant qu'un fichier de changes/ contient une
ligne To move: qui demande à un projet d'agir, et nomme la version mineure à poser à la place
(Versions et stabilité).
node pipeline/monorepo/release-version.mjs --set 0.2.0 # chaque manifeste et les versions qu'écrit la CLInpm install --package-lock-only# pull request, fusion, puis sur main :git tag v0.2.0 && git push origin v0.2.0La pull request d'une release (son titre commence par chore(release)) fait tourner les projets
générés sur Prisma et TypeORM installés pour de vrai, comme la nuit (npm run ci:test:stacks-at-night) les stacks qui font se rencontrer chaque paire de valeurs de
capacité (npm run ci:test:pairwise) et la première migration de chaque ORM sur un vrai
PostgreSQL (npm run ci:test:migrations) : la CI d'une autre pull request ne fait que typer les
premiers et laisse les secondes à la nuit. L'étiquette
lance le workflow Release : il les fait tourner une fois de plus et ne publie rien tant que l'un
d'eux est rouge (posez l'étiquette une fois les jobs managers, pairwise et migrations de la pull request de la release
verts, ou un run de la nuit demandé sur main, gh workflow run ci.yml --ref main : l'étiquette pointe sur ce code ; si generated-stacks échoue quand même, rien n'a atteint
npm : corrigez sur main, supprimez l'étiquette, git push --delete origin v0.2.0 && git tag -d v0.2.0, et posez-la sur le commit corrigé avec la même version), puis vérifie que l'étiquette est la version qu'annonce chaque package, construit, vérifie les archives, atteste chaque archive (sa provenance de construction et la nomenclature logicielle de la
release, en CycloneDX, écrite par pipeline/monorepo/sbom.mjs depuis le lockfile), publie chaque
package sur le registre npm avec sa provenance et crée la release GitHub, la nomenclature et la provenance signée des archives jointes. Une version qui a une partie de préversion
(0.2.0-rc.1) est publiée sous l'étiquette next. Une exécution arrêtée à mi-chemin se
relance : ce qui est déjà publié est sauté. Les notes de la release GitHub sont générées à
partir des pull requests fusionnées ; CHANGELOG.md à la racine dit en quelques lignes ce qu'une version change pour un utilisateur :
fixer la version y fond les fichiers de changes/, dans l'ordre où ils ont atteint main, et les
supprime ; le package de la CLI en livre une copie, que les agents lisent dans node_modules. Le
plugin sort avec les packages, sous leur version : la fixer écrit aussi version de
plugin/.claude-plugin/plugin.json et la version que décrivent les skills, dans
plugin/hooks/guard.mjs, pour que chaque agent affiche un seul numéro. Le plugin se numérotait
à part jusque-là, en avance sur les packages : la première version commune est au-dessus de la
sienne, ce que --set tient (il nomme la première version qu'il accepte), et --expect du
workflow de release tient le plugin à l'étiquette. Un correctif urgent du plugin est une
release de correctif du kit, pas une version à lui.
Aucun secret. Le workflow publie par la publication de confiance (trusted publishing,
OIDC) : chaque package désigne release.yml de ce dépôt, dans son environnement npm, comme
son éditeur de confiance, et npm publish échange le jeton d'identité du job contre un jeton
qui ne vit que le temps de cette publication. Le job qui publie garde id-token: write et
environment: npm, n'installe ni ne construit rien (un premier job, sans l'identité, installe,
construit et empaquette, et le job de publication publie ses archives), et a besoin de npm 11.5.1
ou ultérieur, ce qu'il vérifie. Aucun
NPM_TOKEN n'est stocké nulle part.
L'approbation du propriétaire. Le job de publication s'exécute dans l'environnement npm, qui
exige l'approbation du propriétaire du dépôt : un run de Release s'arrête avant de publier
jusqu'à ce que le propriétaire l'approuve dans l'onglet Actions, et rien n'atteint npm sans cette
approbation. Seul un administrateur du dépôt crée une étiquette v* (un ruleset la refuse à
tout autre), si bien qu'une release part d'un administrateur, puis attend le propriétaire.
Les archives qu'un run empaquette sont gardées une semaine : une approbation plus tardive, ou un
run terminé après ce délai, relance tout le workflow. N'approuvez pas un run que vous n'attendiez pas.
Un nouveau package. La confiance se déclare package par package, et seulement pour un
package qui existe sur le registre. Avant la première version publiée qui contient un package
ajouté à packages/, un mainteneur réserve son nom avec une version d'attente 0.0.0,
dépréciée, et déclare le workflow comme son éditeur de confiance ; les vraies versions sont
ensuite publiées par le workflow, avec leur provenance :
mkdir /tmp/reserve && cd /tmp/reservenpm init -y --scope=@ddd-ts-kit && npm pkg set name=<package> version=0.0.0 license=MITnpm publish --access public --tag reservednpm deprecate <package>@0.0.0 "Placeholder that reserves the name: install a released version."npm trust github <package> --file release.yml --repository ddd-ts-kit/ddd-ts-kit --environment npm --allow-publishTant que ce n'est pas fait, la publication échoue sur ce seul package, et l'étape de publication le nomme ; relancer le job en échec après la déclaration le publie et saute les autres.