nodefony 7.0.2 → 10.0.0-alpha.2

package/dist/node/kernel/checks/report.js

@@ -0,0 +1,421 @@
+import clc from "../../colors.js";
+//#region src/kernel/checks/report.ts
+/**
+* Mise en forme du rapport de `nodefony doctor` — la partie qu'un HUMAIN lit.
+*
+* Un diagnostic se lit en panne, souvent vite, parfois par quelqu'un qui ne
+* connaît pas le projet. Une liste de croix en vrac oblige à tout parcourir
+* pour savoir s'il y a un problème, lequel, et par où commencer. La forme
+* porte donc trois choses, dans cet ordre : **où** l'on regarde, **l'état de
+* chaque famille de contrôles** d'un coup d'œil, puis le **détail** — et
+* seulement pour ce qui ne va pas.
+*
+* Les fonctions de ce module sont PURES : la largeur du terminal et les
+* couleurs sont injectées. C'est ce qui les rend éprouvables — une fonction
+* qui lit `process.stdout.columns` ne s'éprouve que dans le terminal où elle
+* tourne, c'est-à-dire jamais en intégration continue.
+*/
+/**
+* Le nom lisible de chaque famille.
+*
+* Une table unique évite qu'un titre affiché dans le sommaire diffère de celui
+* de la section « non contrôlé » — deux libellés pour un même contrôle, et le
+* lecteur croit qu'il y en a deux.
+*/
+const TITLES = {
+	freshness: "Fraîcheur du build",
+	readiness: "Prêt à démarrer",
+	envCatalog: "Variables déclarées",
+	envTracked: "Secrets hors de git",
+	deps: "Dépendances",
+	wiring: "Câblage",
+	surface: "Surface ouverte",
+	dialect: "Entités et dialecte",
+	guards: "Gardes du projet",
+	migrations: "Migrations de schéma",
+	firewall: "Cohérence du firewall",
+	gating: "Écart avec l'environnement visé",
+	verify: "Gardes du projet, LANCÉES",
+	outdated: "Paquets en retard"
+};
+/**
+* L'ordre de lecture des familles — celui du sommaire ET du détail.
+*
+* L'ordre n'est pas cosmétique : la fraîcheur d'abord, parce qu'un build en
+* retard rend faux tout ce qui suit ; puis ce qui empêche de démarrer, qui
+* explique souvent le reste.
+*/
+const FAMILIES = [
+	"freshness",
+	"readiness",
+	"envCatalog",
+	"envTracked",
+	"deps",
+	"wiring",
+	"surface",
+	"dialect",
+	"guards",
+	"migrations",
+	"firewall",
+	"gating",
+	"verify",
+	"outdated"
+];
+/**
+* Les SOUS-RÈGLES de `readiness` — des contrôles à part entière, mais qui ne
+* sont pas des familles.
+*
+* Elles ont besoin de leur propre état d'exécution (leur silence peut ne rien
+* prouver : catalogue illisible, pas de dépôt git), sans quoi elles seraient
+* affichées en vert alors qu'elles n'ont rien regardé. Mais les compter comme
+* familles gonflerait le bilan de contrôles que le sommaire n'affiche pas.
+*
+* Une seule liste, dont TOUT le reste se dérive : quand la deuxième sous-règle
+* est arrivée, la condition `f !== "envCatalog"` était écrite en dur à trois
+* endroits — le compteur du bilan, le filtre du sommaire, et le dédoublonnage
+* des contrôles sautés.
+*/
+const SUBRULES = ["envCatalog", "envTracked"];
+/** `true` si cette famille est une sous-règle de `readiness`. */
+function isSubrule(family) {
+	return SUBRULES.includes(family);
+}
+/**
+* Les familles qui COMPTENT dans un bilan.
+*
+* Les sous-règles en sont exclues : ce sont des RÈGLES de `readiness`, pas des
+* familles à part — les compter donnerait un total qui ne colle pas aux lignes
+* affichées. Dérivée de {@link FAMILIES} et non réécrite : la liste avait été
+* recopiée en dur dans le compteur du bilan, et une famille ajoutée n'y entrait
+* pas.
+*/
+const COUNTED_FAMILIES = FAMILIES.filter((f) => !isSubrule(f));
+/**
+* Parmi les contrôles sautés, ceux qui CONDAMNENT en mode strict.
+*
+* Un contrôle EMPÊCHÉ (on n'a pas pu regarder) est un manquement de couverture.
+* Deux cas ne le sont pas, et pour la même raison : le contrôle NON DEMANDÉ
+* (l'étage 2, qui exige un démarrage) et le contrôle SANS OBJET (il a regardé,
+* il n'y avait rien — aucune entité, aucun ORM, aucun module de sécurité).
+*
+* Les confondre faisait échouer `doctor` dans toute chaîne automatisée — `CI`
+* arme `--strict` d'office. D'abord pour l'étage 2, tant qu'on n'ajoutait pas
+* un boot complet à la commande ; puis, plus grave, pour toute application
+* NEUVE, qui n'a par construction ni entité ni base.
+*
+* Une seule implémentation, parce que le RENDU et le CODE DE SORTIE doivent
+* dire la même chose : un bandeau qui annonce un échec que la commande ne
+* produit pas apprend à ne plus croire le bandeau.
+*
+* @param skipped - les contrôles sautés, tels que `skippedChecks` les rend
+* @returns ceux qui pèsent sur le code de sortie en mode strict
+*/
+function preventedChecks(skipped) {
+	return skipped.filter((s) => !s.onDemand && !s.notApplicable);
+}
+/**
+* Les contrôles qui n'ont PAS eu lieu, dans l'ordre de lecture du rapport.
+*
+* Fonction pure sur l'état d'exécution : c'est elle qui alimente à la fois le
+* rendu humain, le JSON et le code de sortie en mode strict. Les trois doivent
+* dire la même chose — un rapport humain qui tait ce que le JSON porte est
+* exactement le défaut que ce contrôle vient réparer.
+*
+* @param execution - l'état d'exécution de chaque famille.
+* @returns un élément par contrôle sauté, vide si tout a été regardé.
+*/
+function skippedChecks(execution) {
+	const skipped = [];
+	for (const family of FAMILIES) {
+		const state = execution[family] ?? {
+			ran: false,
+			reason: "ce rapport ne porte aucun état d'exécution pour cette famille — il a probablement été produit par une autre version",
+			short: "état absent"
+		};
+		if (state.ran) continue;
+		if (isSubrule(family) && !execution.readiness?.ran) continue;
+		skipped.push({
+			family,
+			title: TITLES[family],
+			...state.onDemand ? { onDemand: true } : {},
+			...state.notApplicable ? { notApplicable: true } : {},
+			reason: state.reason ?? "raison non précisée",
+			unlock: state.unlock
+		});
+	}
+	return skipped;
+}
+/** Sans couleur, chaque rôle rend le texte tel quel. */
+const PLAIN = (t) => t;
+/**
+* La peinture en vigueur pour ce rendu.
+*
+* @param color - `true` pour émettre des séquences ANSI.
+* @returns une palette : réelle, ou entièrement transparente.
+*/
+function createPalette(color) {
+	if (!color) return {
+		strong: PLAIN,
+		dim: PLAIN,
+		ok: PLAIN,
+		warning: PLAIN,
+		failure: PLAIN,
+		action: PLAIN
+	};
+	return {
+		strong: (t) => clc.bold(t),
+		dim: (t) => clc.blackBright(t),
+		ok: (t) => clc.green(t),
+		warning: (t) => clc.yellow(t),
+		failure: (t) => clc.red(t),
+		action: (t) => clc.cyan(t)
+	};
+}
+/**
+* Faut-il colorer cette sortie ?
+*
+* Un rapport de diagnostic finit souvent dans un fichier ou un journal
+* d'intégration continue, où les séquences ANSI ne colorent rien et rendent le
+* texte illisible (`[33m` partout). La convention `NO_COLOR` est respectée
+* telle qu'elle est spécifiée : c'est sa PRÉSENCE qui compte, pas sa valeur.
+*
+* @param env - l'environnement, injecté.
+* @param isTerminal - `process.stdout.isTTY`, injecté.
+* @returns `true` s'il faut émettre des couleurs.
+*/
+function shouldColorize(env, isTerminal) {
+	if (env.NO_COLOR !== void 0 && env.NO_COLOR !== "") return false;
+	if (env.FORCE_COLOR !== void 0 && env.FORCE_COLOR !== "0") return true;
+	return isTerminal;
+}
+/**
+* Découpe une phrase en unités INSÉCABLES pour le repli.
+*
+* Les messages de diagnostic portent des commandes entre accents graves
+* (`` `npm run build` ``), qui contiennent des espaces. Couper dessus laisserait
+* un accent grave orphelin en fin de ligne, et le lecteur ne saurait plus où
+* commence la commande à taper.
+*
+* @param text - la phrase.
+* @returns les unités, accents graves compris.
+*/
+function unbreakableUnits(text) {
+	const units = [];
+	let current = "";
+	let inCode = false;
+	for (const c of text) {
+		if (c === "`") {
+			inCode = !inCode;
+			current += c;
+			continue;
+		}
+		if (!inCode && /\s/u.test(c)) {
+			if (current !== "") units.push(current);
+			current = "";
+			continue;
+		}
+		current += c;
+	}
+	if (current !== "") units.push(current);
+	return units;
+}
+/**
+* Met en valeur ce qui est entre accents graves — une commande, un chemin.
+*
+* Sans couleur, les accents graves RESTENT : ils portent eux-mêmes
+* l'information « ceci se tape tel quel », et un journal de CI en a autant
+* besoin qu'un terminal. Avec couleur, ils s'effacent au profit de la teinte —
+* deux façons de dire la même chose, jamais les deux à la fois.
+*
+* @param text - la phrase, avec ses accents graves.
+* @param palette - la peinture en vigueur.
+* @param color - `true` si la palette colore réellement.
+* @returns la phrase prête à écrire.
+*/
+function highlightCode(text, palette, color) {
+	if (!color) return text;
+	return text.replace(/`([^`]*)`/gu, (_, code) => palette.strong(code));
+}
+/**
+* Le nombre total de manquements d'un rapport — le verdict, en UN endroit.
+*
+* @param report - le rapport, étage 2 greffé ou non
+* @returns la somme de toutes les familles, l'étage 2 compris
+*/
+function countFindings(report) {
+	return report.findings.length + report.wiring.findings.length + report.readiness.findings.length + report.freshness.findings.length + report.surface.findings.length + report.guards.findings.length + (report.live?.findings.filter((f) => f.kind !== "service-lost").length ?? 0);
+}
+/** Bornes de largeur : en deçà ça se chevauche, au-delà l'œil se perd. */
+const WIDTH_MIN = 48;
+const WIDTH_MAX = 96;
+/**
+* La largeur de rendu, bornée.
+*
+* @param columns - largeur annoncée par le terminal, ou `undefined` quand la
+*   sortie n'en est pas un (redirection, journal de CI).
+* @returns une largeur toujours utilisable.
+*/
+function usableWidth(columns) {
+	if (!columns || !Number.isFinite(columns)) return 80;
+	return Math.max(WIDTH_MIN, Math.min(WIDTH_MAX, Math.floor(columns)));
+}
+/** Le symbole d'un état — la seule chose qui reste quand la couleur est ôtée. */
+function stateSymbol(state) {
+	switch (state) {
+		case "ok": return "✓";
+		case "echec": return "✗";
+		case "avertissement": return "!";
+		case "non-controle": return "—";
+	}
+}
+/**
+* Une ligne de sommaire alignée : `  ✓  Titre········· détail`.
+*
+* L'alignement se calcule sur le titre le PLUS LONG du lot, jamais sur une
+* constante : une colonne figée déborde le jour où l'on ajoute « Fraîcheur du
+* build », et le rendu se met à sauter d'une ligne à l'autre.
+*
+* @param line - la famille à rendre.
+* @param titleWidth - largeur de la colonne des titres.
+* @param width - largeur totale disponible.
+* @returns la ligne, sans retour chariot ni couleur.
+*/
+function summaryLine(line, titleWidth, width) {
+	const prefixe = `    ${stateSymbol(line.state)}  ${line.title} `;
+	const detailColumn = 7 + titleWidth + 3;
+	const debut = prefixe + (detailColumn > prefixe.length ? `${POINT_DE_CONDUITE.repeat(detailColumn - prefixe.length - 1)} ` : "");
+	const remainder = width - debut.length;
+	return `${debut}${remainder > 3 && line.detail.length > remainder ? `${line.detail.slice(0, remainder - 1)}…` : line.detail}`.trimEnd();
+}
+/** Le point qui relie un titre à son détail dans le sommaire. */
+const POINT_DE_CONDUITE = "·";
+/**
+* Un titre de section, prolongé par un filet jusqu'au bord.
+*
+* Le rendu séparait ses sections par un filet PLEIN, posé sur sa propre ligne
+* au-dessus du titre : trois lignes de décor pour annoncer une section, et le
+* titre y flottait sans lui appartenir. Prolonger le titre coûte une ligne au
+* lieu de trois, et dit à quoi le filet se rapporte.
+*
+* @param title - le titre, déjà en majuscules.
+* @param width - largeur utile.
+* @returns la ligne, sans couleur (l'appelant teinte le titre et le filet).
+*/
+function sectionTitle(title, width) {
+	const pose = `  ${title} `;
+	const remaining = Math.max(0, width - pose.length - 2);
+	return {
+		title: `  ${title} `,
+		divider: "─".repeat(remaining)
+	};
+}
+/**
+* Enveloppe un texte à la largeur donnée, en coupant aux espaces.
+*
+* Un message de diagnostic porte une phrase entière — chemin, cause, geste.
+* Laissée au terminal, elle se replie sans indentation et le geste se retrouve
+* collé à la marge, illisible au milieu du reste.
+*
+* @param text - la phrase à replier.
+* @param width - largeur maximale d'une ligne, indentation comprise.
+* @param indent - le blanc posé devant chaque ligne.
+* @returns les lignes, prêtes à être écrites.
+*/
+function wrap(text, width, indent) {
+	const usable = Math.max(20, width - indent.length);
+	const lines = [];
+	let current = "";
+	for (const word of unbreakableUnits(text)) if (current === "") current = word;
+	else if (current.length + 1 + word.length <= usable) current += ` ${word}`;
+	else {
+		lines.push(indent + current);
+		current = word;
+	}
+	if (current !== "") lines.push(indent + current);
+	return lines;
+}
+/**
+* Sépare le CONSTAT du GESTE dans un message qui porte les deux.
+*
+* Les contrôles écrivent « … → `npm run build` » : la flèche est le signe
+* qu'un geste suit. Le rendre sur sa propre ligne le rend trouvable sans lire
+* la phrase — c'est la seule chose que le lecteur cherche vraiment quand il
+* est pressé.
+*
+* @param message - le message d'un contrôle.
+* @returns le constat, et le geste s'il y en a un.
+*/
+function splitAction(message) {
+	const i = message.lastIndexOf("→");
+	if (i === -1) return { finding: message.trim() };
+	const action = message.slice(i + 1).trim();
+	const finding = message.slice(0, i).trim().replace(/[.,;:]$/u, "");
+	return action === "" ? { finding: message.trim() } : {
+		finding,
+		action
+	};
+}
+/**
+* Une durée en secondes, rendue lisible.
+*
+* « plus récent de 6359 s » demande un calcul mental au moment où le lecteur
+* en a le moins envie. Ce n'est pas une précision qu'on perd : personne ne
+* décide rien sur la seconde près à cette échelle.
+*
+* @param seconds - l'écart mesuré.
+* @returns « 12 s », « 4 min », « 1 h 46 », « 3 j ».
+*/
+function formatDuration(seconds) {
+	const s = Math.max(0, Math.round(seconds));
+	if (s < 90) return `${s} s`;
+	const minutes = Math.round(s / 60);
+	if (minutes < 90) return `${minutes} min`;
+	const hours = Math.floor(s / 3600);
+	if (hours < 48) {
+		const remainder = Math.round(s % 3600 / 60);
+		return remainder === 0 ? `${hours} h` : `${hours} h ${String(remainder).padStart(2, "0")}`;
+	}
+	return `${Math.round(s / 86400)} j`;
+}
+/**
+* Accorde un nom avec son nombre — « 1 contrôle passé », « 2 contrôles passés ».
+*
+* Les parenthèses de repli (« contrôle(s) passé(s) ») sont le signe d'un
+* rapport écrit pour la machine ; celui-ci est lu par quelqu'un.
+*
+* @param n - la quantité.
+* @param singular - la forme au singulier.
+* @param plural - la forme au pluriel, si elle ne s'obtient pas par un « s ».
+* @returns « 3 écarts ».
+*/
+function pluralize(n, singular, plural) {
+	return `${n} ${n > 1 ? plural ?? `${singular}s` : singular}`;
+}
+/**
+* Replie une énumération par UNITÉS, jamais au milieu d'un élément.
+*
+* 🔴 Un repli aux espaces met le séparateur en tête de ligne : `\s` avale
+* l'espace insécable qui entoure le point médian, et la ligne suivante commence
+* par « · ». Cette fonction ne coupe qu'ENTRE deux éléments.
+*
+* @param items - les éléments à énumérer.
+* @param width - largeur utile d'une ligne.
+* @returns les lignes, séparateur « · » compris.
+*/
+function wrapList(items, width) {
+	const lines = [];
+	let current = "";
+	for (const item of items) {
+		const attempt = current ? `${current} · ${item}` : item;
+		if (attempt.length <= width || !current) {
+			current = attempt;
+			continue;
+		}
+		lines.push(current);
+		current = item;
+	}
+	if (current) lines.push(current);
+	return lines;
+}
+//#endregion
+export { COUNTED_FAMILIES, FAMILIES, SUBRULES, TITLES, countFindings, createPalette, formatDuration, highlightCode, isSubrule, pluralize, preventedChecks, sectionTitle, shouldColorize, skippedChecks, splitAction, stateSymbol, summaryLine, unbreakableUnits, usableWidth, wrap, wrapList };