nodefony 7.0.2 → 10.0.0-alpha.2

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

@@ -0,0 +1,731 @@
+import { FAMILIES, TITLES, countFindings, createPalette, isSubrule, preventedChecks, sectionTitle, shouldColorize, skippedChecks, usableWidth, wrap, wrapList } from "./report.js";
+import { defaultDevPorts, probePorts, readRuntimeState } from "../../service/dev/devProcess.js";
+import { Spinner } from "../../cli/progress.js";
+import { checkPackageDeps } from "./packageDeps.js";
+import { checkWiring } from "./wiring.js";
+import { readLastBoots } from "./lastBoot.js";
+import { findProjectRoot } from "../../cli/projectRoot.js";
+import { resolveEnvCascade } from "../../runtime/loadEnv.js";
+import { stripGlobalCliFlags } from "../../cli/globalFlags.js";
+import { checkReadiness } from "./readiness.js";
+import { checkFreshness } from "./freshness.js";
+import { checkSurface } from "./surface.js";
+import { VERIFY_STEPS, checkGuards } from "./guards.js";
+import { readOutdated, runVerifySteps } from "./deep.js";
+import { LIVE_FAMILIES, liveNotRun } from "./live.js";
+import { renderReport } from "./renderReport.js";
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+//#region src/kernel/checks/runDoctor.ts
+/**
+* Exécution STANDALONE de `nodefony doctor` — zéro boot, zéro Kernel.
+*
+* Ce contrôle ne lit que des fichiers : des `package.json` et des sources. Le
+* faire passer par un boot d'application coûtait un démarrage complet (modules
+* instanciés, environnement résolu, journal du Kernel par-dessus le rapport)
+* pour une réponse qui n'en dépend pas — et rendait la commande inutilisable là
+* où elle sert le plus : hors d'une application, ou sur une application qui ne
+* démarre justement plus.
+*
+* Même famille que `status`, `stop`, `create` et `--version`.
+*/
+/**
+* L'environnement que l'APPLICATION verrait, depuis ce poste.
+*
+* `process.env` ne porte que ce que le terminal a posé ; l'application, elle,
+* lit d'abord sa cascade `.env*`. Un diagnostic qui l'ignore accuse ce qu'il
+* n'a pas regardé. La cascade est celle d'ICI (mode runtime et environnement de
+* déploiement du poste) — viser un autre environnement ne fait pas apparaître
+* des fichiers qui ne sont pas sur cette machine.
+*
+* @param root - racine du projet (ou dossier de départ, hors projet).
+* @returns l'environnement effectif ; `process.env` n'est jamais modifié.
+*/
+function appEnvironment(root) {
+	const runtimeEnv = process.env.NODE_ENV ?? "development";
+	const rawAppEnv = process.env.APP_ENV ?? process.env.NF_ENV ?? "";
+	return resolveEnvCascade(process.env, {
+		cwd: root,
+		runtimeEnv,
+		...rawAppEnv && rawAppEnv !== runtimeEnv ? { appEnv: rawAppEnv } : {}
+	});
+}
+/** Dispositions explorées : une application (`modules/`) et ce dépôt. */
+const CANDIDATE_ROOTS = [
+	".",
+	"modules",
+	"src/modules",
+	"src/packages/@nodefony",
+	"src/nodefony"
+];
+/** Dossiers qui CONTIENNENT des cibles, par opposition à en être une. */
+const TARGET_CONTAINERS = [
+	"modules",
+	"src/modules",
+	"src/packages/@nodefony"
+];
+/**
+* Cibles du contrôle de câblage : l'application elle-même, et chaque module.
+*
+* Ce n'est pas la même liste que celle des paquets : un contrôle de dépendances
+* s'intéresse à ce qui porte un `package.json`, un contrôle de câblage à ce qui
+* porte un `nodefony/`. Les confondre ferait chercher des entités à la racine
+* d'un dossier qui n'en contient que des modules.
+*/
+function wiringTargets(cwd) {
+	const targets = [cwd];
+	for (const container of TARGET_CONTAINERS) {
+		const dir = path.join(cwd, container);
+		if (!statSync(dir, { throwIfNoEntry: false })) continue;
+		try {
+			for (const entry of readdirSync(dir, { withFileTypes: true })) if (entry.isDirectory()) targets.push(path.join(dir, entry.name));
+		} catch {}
+	}
+	return targets;
+}
+/**
+* Exceptions déclarées par le projet dans son `package.json` :
+*
+* ```json
+* "nodefony": { "doctor": { "typeCycles": {…}, "typesUnreachable": [...] } }
+* ```
+*
+* Sans cette porte, un projet portant un cycle de types légitime ne peut jamais
+* être vert — et un contrôle qu'on ne peut pas satisfaire est un contrôle qu'on
+* apprend à ignorer.
+*/
+function readExceptions(cwd) {
+	try {
+		const raw = readFileSync(path.join(cwd, "package.json"), "utf8");
+		return JSON.parse(raw).nodefony?.doctor ?? {};
+	} catch {
+		return {};
+	}
+}
+/**
+* Sonde les ports de développement et CONSTATE qui les tient.
+*
+* Le verdict `ownedByUs` vient de `readRuntimeState`, qui invalide de lui-même
+* un état dont le processus est mort : un serveur Nodefony en marche est l'état
+* sain le plus courant, et l'accuser d'occuper « son » port ferait de `check` un
+* outil qu'on apprend à ignorer.
+*
+* @param projectRoot - racine de l'application.
+* @returns le verdict à injecter dans la règle, jamais la mesure elle-même.
+*/
+async function probeLocalPorts(projectRoot) {
+	const ports = defaultDevPorts(projectRoot);
+	return {
+		probed: ports,
+		busy: (await probePorts(ports)).filter((s) => s.listening).map((s) => s.port),
+		ownedByUs: readRuntimeState(projectRoot) !== null
+	};
+}
+/**
+* Les fichiers d'environnement LOCAUX que git suit — CONSTATÉ, jamais déduit.
+*
+* Trois choses peuvent manquer et ne se déduisent d'aucune autre : le binaire
+* `git`, un dépôt, et le droit de lire son index. Le verdict porte donc
+* `supported`, et la règle SAUTE au lieu d'afficher vert — un contrôle de
+* secrets qui se tait sur un dossier non versionné est le pire des deux mondes.
+*
+* `git ls-files` reçoit ses motifs en ARGUMENTS, jamais par un shell : c'est
+* git qui les développe, à l'identique sur les trois plateformes.
+*
+* @param projectRoot - racine de l'application.
+* @returns le verdict à injecter dans la règle.
+*/
+function probeTrackedEnvFiles(projectRoot) {
+	try {
+		return {
+			supported: true,
+			tracked: execFileSync("git", [
+				"ls-files",
+				"-z",
+				"--",
+				".env.local",
+				".env.*.local"
+			], {
+				cwd: projectRoot,
+				encoding: "utf8",
+				stdio: [
+					"ignore",
+					"pipe",
+					"pipe"
+				]
+			}).split("\0").filter(Boolean)
+		};
+	} catch (e) {
+		return {
+			supported: false,
+			tracked: [],
+			reason: `git n'a pas pu dire ce qu'il suit ici — ${e.message.split("\n")[0]} (dossier non versionné, ou binaire git absent)`
+		};
+	}
+}
+/**
+* L'usage, rendu avec le même soin que le rapport.
+*
+* Il se lit dans deux situations opposées : on découvre la commande, ou on
+* vient de se tromper de drapeau. Il porte donc les deux réponses — ce que la
+* commande FAIT, et ce que chaque option change — plus les codes de sortie,
+* qu'aucune autre page ne donne et qu'un script doit connaître.
+*
+* @param p - la peinture en vigueur.
+* @returns le texte complet, retour chariot final compris.
+*/
+function usage(p, width = usableWidth(80)) {
+	const column = 20;
+	const indent = " ".repeat(23);
+	const opt = (flag, quoi) => {
+		const [premiere, ...suite] = wrap(quoi, width - indent.length, "");
+		return `  ${p.action(flag.padEnd(column, " "))} ${premiere ?? ""}\n` + suite.map((l) => `${indent}${l}\n`).join("");
+	};
+	/** Un titre de section, prolongé par son filet — la forme du rapport. */
+	const section = (name) => {
+		const { title, divider } = sectionTitle(name, width);
+		return `\n${p.strong(title)}${p.dim(divider)}\n\n`;
+	};
+	/**
+	* Les exemples : la commande, puis ce qu'elle répond.
+	*
+	* La colonne se DÉRIVE du plus long : figée, elle saute dès qu'un exemple
+	* la dépasse, et l'aide se met à ressembler à une sortie cassée.
+	*/
+	const examples = [
+		["nodefony doctor", "l'état d'ici : build, installation, dépendances, câblage"],
+		["nodefony doctor --live", "et en plus ce que seule l'application démarrée sait : migrations, zones"],
+		["nodefony doctor --env production", "ce qui manquera dans cet environnement — variables requises en production, secrets versionnés"],
+		["nodefony doctor --json | jq .", "le même document, pour un script ou un agent"],
+		["nodefony doctor --cwd modules/blog", "depuis un sous-dossier : la racine de l'application est retrouvée seule"]
+	];
+	const exampleWidth = Math.max(...examples.map(([c]) => c.length));
+	const renderExamples = () => {
+		const inColumns = width - exampleWidth - 4 >= 24;
+		return examples.map(([command, quoi]) => {
+			if (!inColumns) return `  ${p.action(command)}\n` + wrap(quoi, width - 6, "      ").map((l) => p.dim(l) + "\n").join("");
+			const padding = " ".repeat(exampleWidth + 4);
+			const suite = wrap(quoi, width - padding.length, "");
+			return `  ${p.action(command.padEnd(exampleWidth, " "))}  ${p.dim(suite[0] ?? "")}\n` + suite.slice(1).map((l) => `${padding}${p.dim(l)}\n`).join("");
+		}).join("");
+	};
+	const families = wrapList(FAMILIES.filter((f) => !isSubrule(f)).map((f) => TITLES[f]), width - 4);
+	return `\n  ${p.strong("nodefony doctor")}\n` + wrap("ce qui ne va pas dans cette application, et quoi taper", width - 4, "  ").map((l) => p.dim(l) + "\n").join("") + `\n  usage : nodefony doctor [options]\n` + section("CE QU'IL REGARDE") + families.map((l) => `  ${l}\n`).join("") + "\n" + wrap(`Il ne DÉMARRE pas l'application : il lit des fichiers, interroge git sur ce qu'il suit, et sonde les ports du poste. Il répond donc même sur une application qui ne démarre plus — c'est le moment où l'on en a le plus besoin. Les ${LIVE_FAMILIES.length} derniers contrôles font exception : ils exigent un démarrage, et ne jouent qu'avec \`--live\`.`, width - 4, "  ").map((l) => `${l}\n`).join("") + section("OPTIONS") + opt("--json", "le même rapport, exploitable par un script — et AUCUNE progression, sur aucun canal : un harnais qui capture les deux flux (`2>&1`) recevrait sinon du décor au milieu de ses données") + opt("--strict", "un contrôle SAUTÉ fait échouer — armé tout seul quand la variable d'environnement `CI` est posée, ce que fait toute forge") + opt("--no-strict", "tolère un contrôle sauté, y compris sur une forge : une absence VOULUE s'énonce, elle ne se contourne pas en désarmant la commande") + opt("--live", "DEMANDE à l'application : migrations, cohérence des zones (boot console, aucun port ouvert)") + opt("--no-live", "s'en tient aux fichiers, quoi qu'un script demande") + opt("--deep", "tout : LANCE ce que le projet déclare (`typecheck`, `lint`, `test`), interroge npm sur les paquets en retard, et DEMANDE à l'application (implique `--live` ; `--no-live` le refuse). Des dizaines de secondes. N'annonce sa progression que hors `--json`") + opt("--env <e>", "dit ce qui manquera dans CET environnement (`production`, `staging`…) sans y aller") + opt("--cwd <chemin>", "point de départ (la racine de l'app est résolue en remontant)") + section("EXEMPLES") + renderExamples() + section("CODES DE SORTIE") + opt("0", "rien à signaler") + opt("1", "au moins un manquement — ou, en mode strict, un contrôle EMPÊCHÉ") + opt("64", "option inconnue (EX_USAGE)") + "\n" + wrap("Un contrôle qui n'a PAS pu regarder est toujours annoncé : son silence ne vaut jamais quitus. Un contrôle non DEMANDÉ (`--live`) est affiché de même, mais ne pèse pas sur le code de sortie.", width - 4, "  ").map((l) => p.dim(l) + "\n").join("") + "\n";
+}
+/**
+* La sévérité d'un contrôle sauté, décidée hors de la ligne de commande.
+*
+* Un drapeau explicite gagne toujours — dans les deux sens : `--no-strict`
+* existe pour qu'une absence VOULUE puisse s'énoncer en intégration continue,
+* plutôt que de se contourner en désarmant la commande entière.
+*
+* @param mot - `--strict`, `--no-strict`, ou rien.
+* @param env - l'environnement, injecté (une fonction qui lit `process.env` ne
+*   s'éprouve que dans l'environnement où elle tourne).
+* @returns `true` si un contrôle sauté doit peser sur le code de sortie.
+*/
+/**
+* Les MODES d'exécution connus — ceux que le moteur distingue vraiment.
+*
+* La liste des environnements de DÉPLOIEMENT, elle, est ouverte (`staging`,
+* `preprod`, `qa`… sont des chaînes libres, cf `NF_ENV`) : la fermer refuserait
+* des environnements parfaitement légitimes. C'est pourquoi la garde
+* ci-dessous ne refuse PAS l'inconnu — elle refuse ce qui RESSEMBLE à une
+* faute de frappe sur l'un de ces mots.
+*/
+const KNOWN_MODES = [
+	"production",
+	"development",
+	"dev",
+	"prod",
+	"test"
+];
+/**
+* La distance d'édition entre deux mots, bornée.
+*
+* Bornée parce qu'on ne cherche pas à mesurer : on cherche à savoir si deux
+* mots sont à une ou deux frappes l'un de l'autre. Au-delà, la réponse est
+* « non » et le calcul ne sert plus à rien.
+*/
+function editDistance(a, b, max = 3) {
+	if (Math.abs(a.length - b.length) > max) return max + 1;
+	let previous = Array.from({ length: b.length + 1 }, (_, i) => i);
+	for (let i = 1; i <= a.length; i++) {
+		const current = [i];
+		for (let j = 1; j <= b.length; j++) current[j] = Math.min((current[j - 1] ?? 0) + 1, (previous[j] ?? 0) + 1, (previous[j - 1] ?? 0) + (a[i - 1] === b[j - 1] ? 0 : 1));
+		previous = current;
+	}
+	return previous[b.length] ?? max + 1;
+}
+/**
+* Le mode connu dont cet environnement est visiblement une faute de frappe.
+*
+* 🔴 Vécu, et c'est le pire mode de défaillance d'un diagnostic : `doctor --env
+* produntion` rendait un rapport COMPLET et plausible, verdict compris, sur un
+* environnement qui n'existe nulle part — le mot inventé s'affichait tel quel
+* dans chaque phrase. Un outil dont le rôle est de dire la vérité ne doit pas
+* être le seul à ne pas la vérifier sur sa propre entrée.
+*
+* On ne refuse PAS tout inconnu : un environnement de déploiement est une
+* chaîne libre, et refuser `preprod` rendrait l'option inutilisable là où elle
+* sert. On refuse ce qui est à une ou deux frappes d'un mode connu, sans en
+* être un — c'est la signature d'une faute, pas d'un choix.
+*
+* @param env - l'environnement demandé.
+* @returns le mode dont il est probablement une coquille, sinon `null`.
+*/
+function likelyTypo(env) {
+	const lower = env.toLowerCase();
+	if (KNOWN_MODES.includes(lower)) return null;
+	for (const mode of KNOWN_MODES) {
+		const threshold = mode.length <= 5 ? 1 : 2;
+		if (editDistance(lower, mode) <= threshold) return mode;
+	}
+	return null;
+}
+function resolveStrict(word, env) {
+	if (word !== void 0) return word;
+	return Boolean(env.CI);
+}
+/**
+* Parse l'argv après le mot `check` (ou son alias `doctor`).
+*
+* La borne est le mot de commande, pas la position : le fast-path passe
+* `process.argv` entier (`node`, chemin du binaire, `check`, …) tandis que le
+* filet de {@link Check.generate} ne passe que les options. Sans mot de
+* commande, tout l'argv reçu est donc considéré comme des options.
+*/
+function parseDoctorArgv(argv) {
+	const at = argv.findIndex((w) => w === "doctor");
+	const rest = stripGlobalCliFlags(at === -1 ? argv : argv.slice(at + 1));
+	let json = false;
+	let cwd = process.cwd();
+	let strict;
+	let live = false;
+	let deep = false;
+	let liveRefuse = false;
+	let help = false;
+	let targetEnv = null;
+	for (let i = 0; i < rest.length; i++) {
+		const word = rest[i];
+		if (word === "--help" || word === "-h") help = true;
+		else if (word === "--json" || word === "-j") json = true;
+		else if (word === "--strict") strict = true;
+		else if (word === "--no-strict") strict = false;
+		else if (word === "--deep") deep = true;
+		else if (word === "--live") live = true;
+		else if (word === "--no-live") {
+			live = false;
+			liveRefuse = true;
+		} else if (word === "--cwd") cwd = path.resolve(rest[++i] ?? "");
+		else if (word === "--env") {
+			const value = rest[++i];
+			if (value === void 0 || value.startsWith("-")) return { error: "--env attend un environnement (ex. --env production)" };
+			const typo = likelyTypo(value);
+			if (typo) return { error: `environnement inconnu : ${value} — voulais-tu dire ${typo} ? (un environnement de déploiement libre, comme preprod ou qa, est accepté tel quel)` };
+			targetEnv = value;
+		} else return { error: `option inconnue : ${word}` };
+	}
+	return {
+		json,
+		cwd,
+		help,
+		live: live || deep && !liveRefuse,
+		deep,
+		targetEnv,
+		strict: resolveStrict(strict, process.env)
+	};
+}
+/**
+* Collecte le diagnostic — sans rien imprimer.
+*
+* Séparé du rendu pour la même raison que la table des sujets d'`inspect` :
+* dès qu'une deuxième porte existe, une collecte enfouie dans une fonction qui
+* écrit sur la sortie standard oblige à la réécrire, et les deux divergent.
+*
+* ⚠️ **La cible est l'APPLICATION, pas le dossier où l'on a tapé** : on remonte
+* au premier dossier portant `nodefony.config.ts`. Hors projet, le dossier de
+* départ reste la cible, et l'état d'installation n'est pas contrôlé (sans
+* manifeste ni environnement, une sonde accuserait le premier serveur venu).
+*
+* @param start - dossier de départ de la remontée
+* @returns le rapport complet, sans verdict ni code de sortie
+*/
+async function collectDoctorReport(start, targetEnv = null, deepRequested = false, report) {
+	const projectRoot = findProjectRoot(start);
+	const cwd = projectRoot ?? start;
+	const deep = deepRequested && projectRoot ? await (async () => {
+		const steps = await runVerifySteps(projectRoot, VERIFY_STEPS, void 0, report);
+		const { summary, reason } = await readOutdated(projectRoot, void 0, report);
+		return {
+			steps,
+			outdated: summary,
+			outdatedReason: reason
+		};
+	})() : null;
+	const lastBoots = readLastBoots(cwd);
+	const roots = CANDIDATE_ROOTS.map((r) => path.join(cwd, r)).filter((r) => statSync(r, { throwIfNoEntry: false }));
+	const { typeCycles, typesUnreachable, entityDialect } = readExceptions(cwd);
+	const { findings, scanned } = checkPackageDeps({
+		roots,
+		cwd,
+		typeCycles,
+		typesUnreachable
+	});
+	const wiring = checkWiring({
+		roots: wiringTargets(cwd),
+		cwd,
+		projectRoot: cwd
+	});
+	const readiness = projectRoot ? await checkReadiness({
+		projectRoot,
+		probe: await probeLocalPorts(projectRoot),
+		targetEnv,
+		tracked: probeTrackedEnvFiles(projectRoot)
+	}) : {
+		findings: [],
+		catalogUnreadable: false,
+		portsProbed: [],
+		trackedUnknown: null
+	};
+	const surface = checkSurface({
+		roots: wiringTargets(cwd),
+		cwd,
+		...projectRoot ? { projectRoot } : {},
+		env: appEnvironment(cwd),
+		...entityDialect ? { dialectExceptions: entityDialect } : {}
+	});
+	const guards = projectRoot ? checkGuards({ projectRoot }) : {
+		findings: [],
+		armed: 0,
+		armedNames: [],
+		linterUnreadable: true,
+		manifestUnreadable: true
+	};
+	const freshness = projectRoot ? checkFreshness(projectRoot) : {
+		findings: [],
+		notComparable: true
+	};
+	const outsideProject = {
+		ran: false,
+		reason: "aucune application ici (pas de `nodefony.config.ts` en remontant)",
+		short: "hors application",
+		unlock: "lance `nodefony doctor` depuis une application"
+	};
+	return {
+		root: cwd,
+		appName: appName(cwd),
+		scanned,
+		findings,
+		freshness,
+		surface,
+		guards,
+		wiring: {
+			scanned: wiring.scanned,
+			findings: wiring.findings
+		},
+		readiness,
+		deep,
+		lastBoots,
+		exceptions: Object.values(typeCycles ?? {}).flat().length + (typesUnreachable?.length ?? 0),
+		execution: {
+			freshness: !projectRoot ? outsideProject : freshness.notComparable ? {
+				ran: false,
+				reason: "ni sources ni `dist/` à comparer sous cette racine — il n'y a rien à confronter",
+				short: "rien à comparer",
+				unlock: "construis l'application (`npm run build`)"
+			} : { ran: true },
+			readiness: projectRoot ? { ran: true } : outsideProject,
+			envCatalog: !projectRoot ? outsideProject : readiness.catalogUnreadable ? {
+				ran: false,
+				reason: "le catalogue des variables déclarées se lit dans le `dist/` de l'application, qui n'est pas construite : le silence de la règle « variable requise » ne vaut pas quitus",
+				short: "catalogue illisible",
+				unlock: "`npm run build`"
+			} : { ran: true },
+			envTracked: !projectRoot ? outsideProject : readiness.trackedUnknown ? {
+				ran: false,
+				reason: `${readiness.trackedUnknown} : impossible de dire si un fichier .env*.local est versionné`,
+				short: "git muet",
+				unlock: "lance depuis un dépôt git (`git init`)"
+			} : { ran: true },
+			guards: !projectRoot ? outsideProject : guards.manifestUnreadable || guards.linterUnreadable ? {
+				ran: false,
+				reason: "le manifeste ou la configuration du linter n'a pas pu être lu : impossible de dire si les gardes du projet sont armées",
+				short: "config illisible",
+				unlock: "vérifie `package.json` et `.oxlintrc.json`"
+			} : { ran: true },
+			verify: !projectRoot ? outsideProject : deep === null ? {
+				ran: false,
+				reason: "les gardes du projet n'ont pas été LANCÉES — seule leur présence a été constatée",
+				short: "non demandé",
+				onDemand: true,
+				unlock: "nodefony doctor --deep"
+			} : { ran: true },
+			outdated: !projectRoot ? outsideProject : deep === null ? {
+				ran: false,
+				reason: "le registre npm n'a pas été interrogé — c'est du réseau, et il ne se paie que sur demande",
+				short: "non demandé",
+				onDemand: true,
+				unlock: "nodefony doctor --deep"
+			} : deep.outdated === null ? {
+				ran: false,
+				reason: deep.outdatedReason,
+				short: "registre muet",
+				unlock: "réessaie quand le réseau répond"
+			} : { ran: true },
+			surface: surface.scanned > 0 ? { ran: true } : {
+				ran: false,
+				reason: "aucune source TypeScript sous les racines explorées : il n'y a rien où chercher une route ouverte",
+				short: "aucune source",
+				notApplicable: true,
+				unlock: "vérifie la racine visée (`--cwd`)"
+			},
+			dialect: surface.entitiesScanned > 0 ? { ran: true } : {
+				ran: false,
+				reason: "aucune entité Drizzle dans cette application — il n'y a pas de dialecte à confronter",
+				short: "aucune entité",
+				notApplicable: true,
+				unlock: "`nodefony create entity <Nom>`"
+			},
+			deps: !projectRoot ? outsideProject : scanned > 0 ? { ran: true } : {
+				ran: false,
+				reason: "aucun `package.json` sous les racines explorées",
+				short: "aucun paquet",
+				unlock: "vérifie la racine visée (`--cwd`)"
+			},
+			...liveNotRun("l'état de la base, la cohérence des zones et ce qu'un autre environnement retirerait ne se lisent dans aucun fichier : il faut démarrer l'application pour les constater", targetEnv ? `\`nodefony doctor --live --env ${targetEnv}\`` : "`nodefony doctor --live`", true).execution,
+			wiring: !projectRoot ? outsideProject : wiring.scanned > 0 ? { ran: true } : {
+				ran: false,
+				reason: "aucune classe déclarée (`@controller`, `@entity`, `@injectable`) n'a été trouvée : il n'y a rien à confronter au manifeste",
+				short: "aucune classe",
+				notApplicable: true,
+				unlock: "`nodefony create controller <Nom>`"
+			}
+		}
+	};
+}
+/**
+* Nombre total de manquements d'un rapport — le verdict, en un endroit.
+*
+* Délègue à {@link countFindings} : le rendu compte par la même fonction, et
+* le bilan chiffré ne peut donc plus contredire le sommaire qui le surmonte.
+* Ce nom reste parce qu'il a voyagé (le serveur MCP le lit).
+*/
+function countCheckFindings(report) {
+	return countFindings(report);
+}
+/**
+* La ligne d'annonce d'un évènement de l'étage profond, ou `null` s'il n'y a
+* rien à dire.
+*
+* Fonction PURE, pour que ce qui s'affiche pendant une attente de plusieurs
+* minutes s'éprouve sans attendre quoi que ce soit.
+*
+* @param e - l'évènement annoncé par l'étage profond.
+* @param p - la palette (couleur ou non, selon le terminal).
+* @returns la ligne à écrire, sans retour chariot, ou `null`.
+*/
+function progressLine(e, p) {
+	const quoi = e.step === "outdated" ? "npm outdated" : `npm run ${e.step}`;
+	if (e.phase === "start") return p.dim(`  … ${quoi}`);
+	const seconds = e.ms === void 0 ? "" : ` (${(e.ms / 1e3).toFixed(1)} s)`;
+	switch (e.outcome) {
+		case "passed":
+		case "ok": return `  ${p.ok("✓")} ${quoi}${p.dim(seconds)}`;
+		case "failed": return `  ${p.failure("✗")} ${quoi}${p.dim(seconds)}`;
+		case "timeout": return `  ${p.failure("⏱")} ${quoi}${p.dim(`${seconds} — interrompu`)}`;
+		case "unavailable": return `  ${p.warning("—")} ${quoi}${p.dim(`${seconds} — sans réponse`)}`;
+		default: return null;
+	}
+}
+/**
+* Le reporter à donner à l'étage profond — ou `undefined` quand personne ne lit.
+*
+* 🔴 **Deux décisions, et elles ne sont pas cosmétiques.**
+*
+* *Le canal* : la progression part sur la sortie d'ERREUR, jamais sur la sortie
+* standard. Celle-ci porte le RAPPORT, que l'on redirige couramment vers un
+* fichier (`nodefony doctor > diagnostic.txt`) ; une progression éphémère qui
+* s'y glisserait salirait un document qu'on relit plus tard, et rendrait le
+* `--json` inexploitable. C'est aussi la convention des outils qui annoncent
+* leur travail — npm, cargo, docker écrivent tous leur progression sur stderr.
+*
+* *Le silence en `--json`* : rien n'est émis du tout, sur aucun canal. Un agent
+* qui capture les deux flux (`2>&1`, ce que font la plupart des harnais) verrait
+* sinon des lignes de décor tomber au milieu de son JSON. La règle est donc
+* simple à documenter et sans exception : **`--json` n'émet aucune
+* progression**.
+*
+* @param json - `true` si le rapport est demandé en JSON.
+* @param write - où écrire (injecté : une fonction qui touche `process.stderr`
+*   en dur ne s'éprouve que par capture globale, donc mal).
+* @returns le reporter, ou `undefined` s'il ne faut rien annoncer.
+*/
+function reporterProgression(json, write = (l) => process.stderr.write(`${l}\n`), stream = process.stderr) {
+	if (json) return void 0;
+	const p = createPalette(shouldColorize(process.env, Boolean(process.stderr.isTTY)));
+	const spinner = Boolean(stream.isTTY) ? new Spinner({
+		stream,
+		render: (frame, label) => `  ${p.ok(frame)} ${p.dim(label)}`
+	}) : null;
+	return (e) => {
+		const label = e.step === "outdated" ? "npm outdated" : `npm run ${e.step}`;
+		if (spinner !== null) {
+			if (e.phase === "start") spinner.start(label);
+			else spinner.stop(progressLine(e, p) ?? void 0);
+			return;
+		}
+		const line = progressLine(e, p);
+		if (line !== null) write(line);
+	};
+}
+async function runDoctorCommand(argv) {
+	const parsed = parseDoctorArgv(argv);
+	if ("error" in parsed) {
+		const p = createPalette(shouldColorize(process.env, Boolean(process.stderr.isTTY)));
+		const width = usableWidth(process.stderr.columns);
+		for (const l of wrap(`doctor : ${parsed.error}`, width, "  ")) process.stderr.write(`${p.failure(l)}\n`);
+		process.stderr.write(usage(p, usableWidth(process.stderr.columns)));
+		return 64;
+	}
+	if (parsed.help) {
+		process.stdout.write(usage(createPalette(shouldColorize(process.env, Boolean(process.stdout.isTTY))), usableWidth(process.stdout.columns)));
+		return 0;
+	}
+	const debut = Date.now();
+	return renderDoctorReport(await collectDoctorReport(parsed.cwd, parsed.targetEnv, parsed.deep, reporterProgression(parsed.json)), parsed, Date.now() - debut);
+}
+/**
+* Greffe l'étage 2 sur un rapport statique.
+*
+* En UN endroit, parce que la fusion porte une règle : les deux familles de
+* l'étage 2 sont REMPLACÉES, jamais complétées. `collectDoctorReport` les a
+* posées à « non demandé » — les laisser à côté du vrai résultat afficherait
+* deux états pour un seul contrôle, et le sommaire cesserait de dire la vérité.
+*
+* @param report - le rapport statique, tel que la lecture pure l'a produit
+* @param live - ce que l'application démarrée a dit d'elle-même
+* @returns un rapport neuf ; l'entrée n'est pas modifiée
+*/
+function attachLive(report, live) {
+	return {
+		...report,
+		live,
+		execution: {
+			...report.execution,
+			...live.execution
+		}
+	};
+}
+/**
+* Rend le rapport et décide du code de sortie.
+*
+* Séparé de la collecte pour une raison précise : `doctor --live` boote, donc
+* il compose son rapport en DEUX temps (les fichiers, puis l'application) et
+* doit rendre le tout par le même chemin. Deux rendus pour un même document
+* finiraient par diverger — et c'est le rendu qui porte la doctrine du verdict.
+*
+* @param report - le rapport complet, étage 2 greffé ou non
+* @param parsed - la demande, telle que la ligne de commande l'a exprimée
+* @returns le code de sortie : 0 si rien à signaler, 1 sinon
+*/
+function renderDoctorReport(report, parsed, durationMs) {
+	const { json, strict } = parsed;
+	const start = parsed.cwd;
+	const skipped = skippedChecks(report.execution);
+	const empeches = preventedChecks(skipped);
+	const code = () => {
+		if (countCheckFindings(report) > 0) return 1;
+		return strict && empeches.length > 0 ? 1 : 0;
+	};
+	if (json) {
+		process.stdout.write(`${JSON.stringify({
+			...report,
+			skipped,
+			strict
+		}, null, 2)}\n`);
+		return code();
+	}
+	const out = process.stdout;
+	const lines = renderReport(report, {
+		width: usableWidth(out.columns),
+		color: shouldColorize(process.env, Boolean(out.isTTY)),
+		now: Date.now(),
+		launchedFrom: start,
+		strict,
+		targetEnv: parsed.targetEnv,
+		...durationMs === void 0 ? {} : { durationMs }
+	});
+	out.write(`${lines.join("\n")}\n`);
+	return code();
+}
+/**
+* Le nom de l'application, tel que son manifeste le déclare.
+*
+* @param root - racine du projet.
+* @returns `nom@version`, ou une chaîne vide si le manifeste ne dit rien.
+*/
+function appName(root) {
+	try {
+		const pkg = JSON.parse(readFileSync(path.join(root, "package.json"), "utf8"));
+		if (!pkg.name) return "";
+		return pkg.version ? `${pkg.name} ${pkg.version}` : pkg.name;
+	} catch {
+		return "";
+	}
+}
+/**
+* La commande demandée est-elle `doctor` ?
+*
+* L'alias historique `check` a été RETIRÉ : il ne disait pas ce qu'il vérifie,
+* et il entrait en collision de sens avec les scripts `typecheck` et
+* `format:check` d'une application. Aucun paquet `@nodefony/*` n'étant publié
+* (#175), ce nom n'a jamais atteint une application installée.
+*
+* @param requested - le nom de commande lu sur la ligne de commande.
+* @returns `true` pour `doctor`.
+*/
+function isDoctorCommand(requested) {
+	return requested === "doctor";
+}
+/**
+* L'invocation demande-t-elle l'étage 2 — celui qui exige un boot ?
+*
+* Une SEULE implémentation de la règle, parce qu'elle sert à deux endroits qui
+* doivent s'accorder : le fast-path standalone (qui ne se prend PAS quand
+* l'étage 2 est demandé) et le rattrapage d'un boot mort. Écrite deux fois,
+* elle divergerait au premier drapeau ajouté — `--no-live` en est déjà un, que
+* la lecture naïve de `argv` ignorait.
+*
+* @param requested - le nom de commande lu sur la ligne de commande.
+* @param argv - la ligne de commande complète.
+* @returns `true` si l'application doit être démarrée puis interrogée.
+*/
+function wantsLiveDoctor(requested, argv) {
+	if (!isDoctorCommand(requested)) return false;
+	const parsed = parseDoctorArgv([...argv]);
+	return "error" in parsed ? false : parsed.live && !parsed.help;
+}
+/**
+* Rend le rapport de `doctor` alors que l'application vient d'échouer à démarrer.
+*
+* 🔴 C'est le cas POUR lequel la commande existe. `--live` sort du fast-path et
+* demande un boot : sans ce chemin, une application qui ne démarre plus rendait
+* une pile brute et RIEN d'autre — moins que `doctor` nu. L'étage 2 devient
+* alors un état d'exécution lisible (ce qui a manqué, et le geste), et l'étage
+* 1 est rendu comme d'habitude, code de sortie compris.
+*
+* @param argv - la ligne de commande telle qu'elle a été tapée.
+* @param reason - pourquoi l'application n'a pas pu répondre.
+* @param unlock - le geste qui la rendrait interrogeable.
+* @returns le code de sortie du rapport.
+*/
+async function runDoctorWithoutLive(argv, reason, unlock) {
+	const parsed = parseDoctorArgv(argv);
+	if ("error" in parsed || parsed.help) return runDoctorCommand(argv);
+	const start = Date.now();
+	return renderDoctorReport(attachLive(await collectDoctorReport(parsed.cwd, parsed.targetEnv, parsed.deep, reporterProgression(parsed.json)), liveNotRun(reason, unlock)), parsed, Date.now() - start);
+}
+//#endregion
+export { attachLive, collectDoctorReport, countCheckFindings, editDistance, isDoctorCommand, likelyTypo, parseDoctorArgv, progressLine, renderDoctorReport, reporterProgression, resolveStrict, runDoctorCommand, runDoctorWithoutLive, usage, wantsLiveDoctor };