Aller au contenu
Meubles Morinière

Les choix d’ingénierieÉtudes de cas techniques8 min de lecture

Des tests qui lisent le code à la place du relecteur

Une action serveur sans garde, une écriture qui oublie de périmer son cache, un état écrasé par un geste concurrent. Un test ordinaire ne voit aucune de ces erreurs. Du coup, des règles d’architecture sont devenues des tests qui lisent le code source et bloquent le push.

Le problème

Il y a des règles du projet qu’on ne peut pas vérifier en appelant une fonction.

La première, ce sont les actions serveur. Un fichier "use server" exporte des fonctions, et Next.js les rend appelables par une requête HTTP. Le test le rappelle à ceux qui l’oublient : « Chaque export d’un fichier "use server" est un endpoint POST » (apps/erp/test/admin-guard.regression.test.ts). Donc une action écrite sans sa garde ne vérifie pas elle-même la session de celui qui l’appelle.

La deuxième, c’est le cache. Une action qui change ce que le site affiche doit périmer les pages concernées. Si elle l’oublie, rien ne casse : « la page reste juste vieille » (8100972291).

La troisième, ce sont les états. Une commande passe à « payée » seulement si elle était encore en attente au moment de l’écriture (Données). Une écriture qui pose l’état sans cette condition marche à chaque essai. Elle se trompe le jour où un webhook relivré croise un geste fait au magasin.

Ces erreurs passent le compilateur et les tests du cas nominal. Avant, on les trouvait à la relecture. Sauf qu’avec l’IA, le code avance vite, et la relecture seule ne suffit plus à les attraper (Ma contribution et l’IA).

Les contraintes

  • Le contrôle doit tourner sans moi, à chaque push, et finir vite. Donc il ne peut avoir besoin ni d’une base ni du réseau.
  • Celui qui enfreint la règle, c’est souvent une session qui ne sait pas pourquoi elle existe. Le message d’échec doit donc dire quoi faire.
  • Il y a des exceptions légitimes. La déconnexion agit sans refuser personne, et une action qui ne change rien de visible n’a pas de cache à périmer.
  • Plusieurs règles relient deux fichiers : un tag de cache lu ici et périmé là, une contrainte de la base et son test de refus, une tâche planifiée et sa route.

Les alternatives

  • Relire. C’est ce que ces tests ont remplacé. Le commit du 31 août 2026 le dit : « Trois scans remplacent la relecture » (8100972291).
  • Écrire des règles ESLint sur mesure. ESLint garde déjà les frontières entre les couches (ADR 0006). Mais il juge un fichier à la fois, et plusieurs de ces règles en comparent deux. C’est une question qu’un lecteur se poserait. Aucune trace ne montre qu’elle a été pesée.
  • Passer par le typage, pour que l’erreur ne puisse pas s’écrire. Le projet le fait quand c’est possible. Par exemple, le guide de l’e-mail du matin est typé sur les clés de ses rubriques, donc une rubrique sans guide ne compile pas (MORNING_GUIDES). Mais un type ne dit rien d’une action qu’on a écrite sans passer par lui.
  • Analyser l’arbre syntaxique plutôt que le texte. C’est plus exact, mais plus long à écrire. Un seul de ces tests le fait (apps/erp/test/deferred-block-boundaries.regression.test.ts). Les autres lisent le texte.

La décision

Quand une règle compte et qu’on ne peut pas la prouver en exécutant le code, elle devient un test. Ce test lit le code source du dépôt et échoue à chaque écart. Il porte ses exceptions avec leur raison, il vérifie qu’il a bien lu quelque chose, et son message dit quoi faire.

L’implémentation

Un relevé vide échoue

Un test qui parcourt des fichiers et n’en trouve aucun passe au vert. Du coup, la liste des fichiers vient de git, et elle refuse de servir en dessous d’un plancher. Un préfixe qui ne désigne plus aucun fichier échoue de la même façon (repoFilesUnder). En plus, la plupart des relevés commencent par un cas qui compte ce qu’ils ont trouvé.

repoFilesapps/erp/test/support/repo-files.ts · lignes 9–36
export function repoFiles(): readonly string[] {
	const out = execFileSync(
		"git",
		["ls-files", "--cached", "--others", "--exclude-standard", "-z"],
		{
			cwd: ROOT,
			encoding: "utf8",
			maxBuffer: 64 * 1024 * 1024,
		},
	);

	const listed = out
		.split("\0")
		.filter((path) => path !== "")
		.sort();

	if (listed.length < NOT_VACUOUS_FLOOR) {
		throw new Error(
			`\`git ls-files\` n'a rendu que ${listed.length} fichier(s), sous le plancher ` +
				`de ${NOT_VACUOUS_FLOOR}. Les scans de doctrine qui lisent cette liste seraient ` +
				"tous VERTS sans avoir rien lu. Causes usuelles : un clone partiel " +
				"(`--filter`, `sparse-checkout`), un `cwd` hors du dépôt, ou `git` absent " +
				"du PATH. Le plancher ne se baisse pas : c'est l'énumération qu'il faut réparer.",
		);
	}

	return listed.filter((path) => existsSync(resolve(ROOT, path)));
}

Des exceptions écrites, qui doivent fondre

Le relevé des gardes lit chaque fichier d’action. Il exige que chaque export commence par la garde qui refuse. Les exceptions sont dans deux listes. PUBLIC_ACTIONS nomme les actions ouvertes sans session, et aujourd’hui elle est vide. GUARDED_WITHOUT_REFUSAL nomme les deux actions de déconnexion.

Ces listes sont vérifiées dans les deux sens. Si une exception est déclarée et que son fichier a disparu, le test échoue. Si une action déclarée publique appelle maintenant la garde, il échoue aussi, et il demande de retirer sa ligne : « une allowlist qui ne fond pas ment ».

test « chaque export de %s s'ouvre sur la garde qui refuse, ou le fichier est PUBLIC »apps/erp/test/admin-guard.regression.test.ts · lignes 80–86
it.each(actionFiles)(
	"chaque export de %s s'ouvre sur la garde qui refuse, ou le fichier est PUBLIC",
	(relativePath) => {
		const source = readFileSync(resolve(repoRoot, relativePath), "utf8");
		expect(actionFaults(relativePath, source, regimeOf(relativePath))).toEqual([]);
	},
);

Un exemple suivi : les transitions d’état

Le relevé des transitions commence par lire le schéma Prisma. Il y cherche les modèles qui ont une colonne dont le type finit par Status. Du coup, un nouveau modèle à état entre dans le contrôle sans qu’on touche au test.

Ensuite, il relève chaque update, updateMany et upsert sur ces modèles, dans les modules et le code commun de l’ERP, et il applique quatre règles. Une colonne d’état posée dans data doit être attendue dans le where d’un updateMany. Un update simple n’est admis que pour les fichiers de BARE_UPDATE_ALLOWED, chacun avec sa raison écrite, et il ne pose aucune colonne d’état. Un upsert n’est admis que par une deuxième liste, vide aujourd’hui (UPSERT_ALLOWED). Et une écriture en SQL brut sur ces modèles est refusée, parce que le relevé ne saurait pas y lire la condition.

test « %s — une colonne d'état posée dans data est attendue dans le where d'un updateMany »apps/erp/test/state-transitions.regression.test.ts · lignes 179–223
it.each(sites.map((site) => [`${site.path}:${site.line}`, site] as const))(
	"%s — une colonne d'état posée dans data est attendue dans le where d'un updateMany",
	(_label, site) => {
		if (site.method === "upsert") return;
		const data = propertyLiteral(site.call, "data");
		const columns = stateColumns[site.model] ?? [];
		const transitions = columns.filter(
			(column) => data !== undefined && mentionsColumn(data, column),
		);
		if (data === undefined && site.method === "update" && BARE_UPDATE_ALLOWED.has(site.path))
			return;
		if (data === undefined) {
			const outsideWhere = site.call.replace(propertyLiteral(site.call, "where") ?? "", "");
			expect(
				columns.some((column) => mentionsColumn(outsideWhere, column)),
				`${site.path}:${site.line} construit son \`data\` hors littéral : écrire \`data: { … }\` ` +
					"sur place pour que la transition se lise",
			).toBe(false);
			return;
		}
		if (transitions.length === 0) return;

		expect(
			site.method,
			`${site.path}:${site.line} écrit ${transitions.join(", ")} par un \`update\` sec : un ` +
				"écrivain concurrent (webhook relivré, opérateur) se fait écraser. Passer par " +
				"`updateMany` avec l'état attendu dans le `where`, et juger `count`.",
		).toBe("updateMany");

		const where = propertyLiteral(site.call, "where");
		expect(
			where,
			`${site.path}:${site.line} écrit ${transitions.join(", ")} sans \`where\` littéral : ` +
				"la condition de transition doit se lire sur place",
		).toBeDefined();
		for (const column of transitions) {
			expect(
				mentionsColumn(where ?? "", column),
				`${site.path}:${site.line} pose \`${column}\` sans l'attendre dans le \`where\` : c'est ` +
					"un lire-puis-écrire — la transition n'est pas conditionnelle, et deux " +
					"écrivains concurrents la rejouent l'un sur l'autre",
			).toBe(true);
		}
	},
);

Ce relevé impose aussi une façon d’écrire. Il lit le texte de l’appel, donc l’objet data doit être écrit sur place. Si l’appel nomme une colonne d’état et que data n’est pas un objet écrit à cet endroit (une condition, un objet composé), le test refuse. Il demande de l’écrire sur place « pour que la transition se lise ».

Apparier dans les deux sens

Plusieurs relevés comparent deux listes et refusent ce qui manque d’un côté ou de l’autre.

  • Chaque action de l’ERP est dans l’une de deux listes : celles qui périment un cache, et celles qui n’en périment aucun, avec leur motif. Le relevé vérifie que les deux listes couvrent toutes les actions du dépôt, parce qu’une invalidation en trop coûte autant qu’une invalidation oubliée (apps/erp/test/cache-invalidation.regression.test.ts). Un deuxième relevé vérifie que chaque tag lu est périmé par au moins une écriture (apps/erp/test/silent-failure-harness/cache-tag-pairing.test.ts).
  • Chaque contrainte CHECK des migrations a son cas de refus dans la suite jouée sur Postgres (Qualité).
  • Chaque lecture d’anomalie est branchée dans la veille, et la veille ne branche que des lectures qui existent (Une veille qui dit ce qu’elle n’a pas pu lire).
  • Chaque requête du site a son droit dans la liste du rôle Postgres (Le site n’a que les droits qu’il lui faut).

Le contrôle du contrôle

Un motif mal écrit ne trouve rien et laisse tout passer. Du coup, les relevés essaient leurs motifs sur des exemples : un cas conforme, et les erreurs qu’ils doivent voir.

test « le motif voit l'absence de l'ordre (garde-fou du garde-fou) »apps/erp/test/variant-lock-order.regression.test.ts · lignes 54–58
it("le motif voit l'absence de l'ordre (garde-fou du garde-fou)", () => {
	expect(ORDERED_ITEMS.test(`items: { orderBy: { variantId: "asc" }, select: {} }`)).toBe(true);
	expect(ORDERED_ITEMS.test(`items: { select: { variantId: true } }`)).toBe(false);
	expect(ORDERED_ITEMS.test(`items: { orderBy: { variantId: "desc" } }`)).toBe(false);
});

Quand un relevé tombe sur une forme qu’il ne sait pas lire, il échoue. Le relevé des gardes refuse un export dont il ne reconnaît pas la forme. Il demande de l’écrire autrement, ou de lui apprendre cette forme. Celui des transitions lève une erreur sur un appel dont il ne retrouve pas la fin.

À chaque push

Le hook pre-push lance tous ces tests pour l’ERP puis pour le site, dans le worktree du commit poussé (vitest run test/ regression, .husky/pre-push). Ils n’ont besoin ni d’une base ni du réseau (Contrôles Git).

Les résultats

tests de régression, dont la plupart lisent le code source et refusent tout écart à une règle
92
apps/*/test/*.regression.test.ts
Mesuré dans le dépôt à chaque build de cette documentation.

Ce chiffre, c’est le nombre de fichiers *.regression.test.ts. Ils ne lisent pas tous le code source. Au 16 novembre 2026, sur les 92 fichiers des deux applications, 72 lisent des fichiers du dépôt. Les 20 autres exécutent le code pour figer un bug corrigé, par exemple une facture rendue en PDF dont on relit le texte. Pour les compter, j’ai cherché dans chaque fichier les fonctions qui lisent le dépôt (readFileSync, readRepoFile, repoFiles, serverActionFiles).

Le relevé des gardes date du 30 août 2026 (7203bc1fe8), et ceux du cache du lendemain (8100972291).

Le dernier échec date du 16 novembre 2026. Une nouvelle action, qui ordonne la vitrine de l’accueil, périmait bien le catalogue. Mais elle n’était pas dans la liste du relevé, donc le test échouait. La correction fait une ligne (8386b0ad1e). L’exemple montre aussi ce que la règle coûte : il faut inscrire chaque nouvelle action à la main dans l’une des deux listes.

Une consigne écrite pour les sessions peut devenir un de ces tests. « Chaque bloc différé a son ReadFailureBoundary », c’est une règle de chargement que j’ai demandée le 22 octobre 2026 dans AGENTS.md. Et deferred-block-boundaries.regression.test.ts vérifie que chaque RevealSuspense est bien sous le sien.

Les limites

  • Ces tests lisent du texte avec des motifs. Il faut donc écrire le code dans la forme qu’ils savent lire, et une tournure nouvelle les fait échouer alors qu’il n’y a pas d’erreur. Dans l’autre sens, un motif trop étroit laisse passer une erreur à laquelle personne n’avait pensé, parce que le contrôle du contrôle n’essaie que les cas prévus.
  • Le relevé des transitions a un trou connu. Si le data d’un updateMany est construit entièrement dans une variable, plus haut dans le service, l’appel ne nomme aucune colonne d’état. Du coup, il passe sans être jugé.
  • Un relevé prouve qu’un appel est là. Il ne prouve pas que la garde refuse correctement, ni que le bon tag est périmé pour la bonne raison. Il faut toujours des tests de comportement à côté.
  • Le relevé de l’ordre des verrous ne surveille que trois écritures nommées, le tunnel de commande, le comptage en lot et la vente au magasin. Une nouvelle écriture qui verrouille des déclinaisons lui échappe (Données).
  • Les listes se maintiennent à la main. Et ces tests, c’est aussi du code à relire quand une règle change (Un ERP trop lourd à maintenir).
  • Ils ne servent que si la porte les lance. git push --no-verify les saute (Ce qui n’est pas couvert).

Sur cette page