@nodefony/framework 10.0.0-alpha.1

package/dist/nodefony/src/docsReader.js

@@ -0,0 +1,929 @@
+import { basename, dirname, extname, join } from "node:path";
+import { findProjectRoot, resolveSymbolsFile } from "nodefony";
+import { existsSync } from "node:fs";
+import { promisify } from "node:util";
+import { readFile, readdir, stat } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { execFile, spawn } from "node:child_process";
+//#region nodefony/src/docsReader.ts
+const execFileAsync = promisify(execFile);
+/**
+* Racine de l'APPLICATION servie — jamais le dossier courant du process.
+*
+* Tout ce que ce module lit hors des modules eux-mêmes (`.ai/symbols.json`, les
+* `node_modules` hissés, les docs du core, le dépôt git) vit à la racine de
+* l'application. Or `process.cwd()` est le dossier depuis lequel quelqu'un a
+* TAPÉ la commande : lancer l'application depuis un sous-dossier suffisait à
+* vider les onglets Docs et API du plan d'administration, sans erreur ni trace
+* — un fichier absent est indistinguable d'un module sans documentation.
+*
+* On remonte donc au premier dossier portant `nodefony.config.ts`, avec la même
+* définition de « où commence l'app » que le lanceur, les scaffolds et
+* `nodefony doctor`. Hors projet (dépôt de paquets, test), le dossier courant
+* reste le repli.
+*/
+function appRoot() {
+	return findProjectRoot(process.cwd()) ?? process.cwd();
+}
+/** Slug url-safe — borne le path traversal sur `module/{name}/docs/{slug}`. */
+const SLUG_RE = /^[a-z0-9][a-z0-9._-]*$/i;
+/**
+* Parse un bloc frontmatter YAML minimaliste (clé: valeur scalaires).
+*
+* Volontairement sans dépendance (`gray-matter` etc.) : on ne gère que des
+* scalaires `key: value` entre deux `---`. Les listes inline (`[a, b]`) sont
+* conservées en string brute. Suffisant pour `title/module/status/since/
+* updated/order`. Renvoie `{ data, body }` ; sans fence → `data` vide.
+*/
+function parseFrontmatter(raw) {
+	if (!raw.startsWith("---")) return {
+		data: {},
+		body: raw
+	};
+	const end = raw.indexOf("\n---", 3);
+	if (end === -1) return {
+		data: {},
+		body: raw
+	};
+	const block = raw.slice(3, end);
+	const after = raw.slice(end + 4);
+	const body = after.startsWith("\n") ? after.slice(1) : after;
+	const data = {};
+	for (const line of block.split("\n")) {
+		const trimmed = line.trim();
+		if (!trimmed || trimmed.startsWith("#")) continue;
+		const colon = trimmed.indexOf(":");
+		if (colon === -1) continue;
+		const key = trimmed.slice(0, colon).trim();
+		let value = trimmed.slice(colon + 1).trim();
+		if (value.startsWith("\"") && value.endsWith("\"") || value.startsWith("'") && value.endsWith("'")) value = value.slice(1, -1);
+		if (key === "order") {
+			const n = Number(value);
+			data.order = Number.isFinite(n) ? n : void 0;
+		} else if (key === "last-updated" && data.updated === void 0) data.updated = value;
+		else data[key] = value;
+	}
+	return {
+		data,
+		body
+	};
+}
+/** Premier titre `# H1` du corps markdown, ou `null`. */
+function firstHeading(body) {
+	const m = body.match(/^#\s+(.+)$/m);
+	return m ? m[1].trim() : null;
+}
+/**
+* Date ISO du dernier commit git d'un fichier (détecte la dérive doc↔code).
+*
+* Fallback sur le `mtime` fs si le fichier n'est pas suivi par git ou hors
+* dépôt. Endpoint admin (basse fréquence) → coût d'un `spawn` git acceptable.
+*/
+async function gitLastUpdated(file) {
+	try {
+		const { stdout } = await execFileAsync("git", [
+			"log",
+			"-1",
+			"--format=%cI",
+			"--",
+			file
+		], { cwd: appRoot() });
+		const iso = stdout.trim();
+		if (iso) return iso;
+	} catch {}
+	try {
+		return (await stat(file)).mtime.toISOString();
+	} catch {
+		return null;
+	}
+}
+/** Construit un `DocSummary` à partir du contenu brut d'un `.md`. */
+async function summarize(docsDir, fileName, withGit) {
+	const slug = basename(fileName, extname(fileName));
+	const full = join(docsDir, fileName);
+	const { data, body } = parseFrontmatter(await readFile(full, "utf8"));
+	const title = docTitle(data, body, slug);
+	return {
+		slug,
+		title,
+		navTitle: typeof data.navTitle === "string" && data.navTitle.trim() ? data.navTitle.trim() : title,
+		status: typeof data.status === "string" ? data.status : null,
+		since: typeof data.since === "string" ? data.since : null,
+		updated: typeof data.updated === "string" ? data.updated : null,
+		gitUpdated: withGit ? await gitLastUpdated(full) : null,
+		order: typeof data.order === "number" ? data.order : slug === "index" ? 0 : 100
+	};
+}
+/**
+* Sommaire des docs d'un module : lit les `*.md` de `<modulePath>/docs/`
+* (un niveau, non récursif), parse le frontmatter, trie par `order` puis slug.
+*
+* @param modulePath - chemin disque du module (`Module.path`).
+* @returns liste triée (vide si le dossier `docs/` est absent).
+*/
+async function listModuleDocs(modulePath, withGit = false) {
+	const docsDir = join(modulePath, "docs");
+	let entries;
+	try {
+		entries = await readdir(docsDir);
+	} catch {
+		return [];
+	}
+	const mdFiles = entries.filter((f) => f.toLowerCase().endsWith(".md"));
+	return (await Promise.all(mdFiles.map((f) => summarize(docsDir, f, withGit)))).sort((a, b) => a.order - b.order || a.slug.localeCompare(b.slug));
+}
+/**
+* Comptage rapide des docs (`*.md`) d'un module — readdir seul, sans lire/parser
+* ni `git`. Pour les KPI/overview (`docsCount`) où seul le nombre importe.
+*
+* @param modulePath - chemin disque du module (`Module.path`).
+* @returns nombre de fichiers `.md` dans `<modulePath>/docs/` (0 si absent).
+*/
+async function countModuleDocs(modulePath) {
+	try {
+		return (await readdir(join(modulePath, "docs"))).filter((f) => f.toLowerCase().endsWith(".md")).length;
+	} catch {
+		return 0;
+	}
+}
+/**
+* Lit une doc module par slug : frontmatter + corps markdown brut.
+*
+* Le slug est borné (`SLUG_RE`) avant toute jointure de chemin → pas de path
+* traversal vers l'extérieur de `<modulePath>/docs/`.
+*
+* @returns `null` si slug invalide ou fichier absent.
+*/
+async function readModuleDoc(modulePath, slug) {
+	if (!SLUG_RE.test(slug)) return null;
+	const full = join(modulePath, "docs", `${slug}.md`);
+	let raw;
+	try {
+		raw = await readFile(full, "utf8");
+	} catch {
+		return null;
+	}
+	const { data, body } = parseFrontmatter(raw);
+	return {
+		slug,
+		frontmatter: data,
+		markdown: body,
+		gitUpdated: await gitLastUpdated(full)
+	};
+}
+/**
+* Titre humain d'une doc — frontmatter, sinon premier `# H1`, sinon le slug.
+*
+* Partagé par le sommaire et la recherche : deux lectures du même fichier qui
+* n'en tireraient pas le même titre feraient croire à deux documents.
+*/
+function docTitle(data, body, slug) {
+	return data.title ?? firstHeading(body) ?? (typeof data.topic === "string" ? data.topic : null) ?? slug;
+}
+/** Docs rendues par défaut — au-delà, l'agent relit au lieu de décider. */
+const SEARCH_MAX_DOCS = 20;
+/** Extraits gardés par doc. */
+const SEARCH_MAX_PER_DOC = 3;
+/** Largeur d'un extrait : une ligne de markdown peut faire un paragraphe. */
+const SNIPPET_MAX_CHARS = 240;
+/** Ce que pèse un terme trouvé dans le titre ou le slug, en occurrences. */
+const TITLE_WEIGHT = 5;
+/**
+* Longueur d'une page de référence, en caractères — le pivot de la DENSITÉ.
+*
+* ⚠️ Compter les occurrences BRUTES classe par la taille, pas par la
+* pertinence : un tableau de bord de plusieurs dizaines de milliers de
+* caractères mentionne tout, donc il gagne toutes les recherches — et sortait
+* devant la page qui TRAITE le sujet demandé. Ce qui distingue un document
+* pertinent d'un document long, c'est la densité du terme, pas son total.
+*
+* Un document plus court que ce pivot n'est jamais AVANTAGÉ (le diviseur est
+* planché à 1) : on corrige le biais du volume, on n'en crée pas l'inverse.
+*/
+const DOC_LENGTH_PIVOT = 8e3;
+/**
+* Forme comparable d'un texte : minuscules, sans diacritiques.
+*
+* Un agent tape `securite` et la doc écrit « sécurité » — sans repli, la
+* recherche rend zéro résultat sur un corpus qui traite le sujet en quinze
+* pages, et rien ne dit que c'est l'accent qui a manqué.
+*/
+function fold(text) {
+	return text.normalize("NFD").replace(/[\u0300-\u036f]/g, "").toLowerCase();
+}
+/**
+* Fenêtre lisible autour de la première occurrence d'un terme dans une ligne.
+*
+* Une ligne de markdown n'est pas une ligne d'écran : un paragraphe entier peut
+* tenir sur une seule, et le rendre en entier fait de la recherche un second
+* déversement du corpus.
+*/
+function snippet(line, folded, term) {
+	if (line.length <= SNIPPET_MAX_CHARS) return line.trim();
+	const at = folded.indexOf(term);
+	const start = Math.max(0, at - Math.floor(SNIPPET_MAX_CHARS / 3));
+	const end = Math.min(line.length, start + SNIPPET_MAX_CHARS);
+	return (start > 0 ? "…" : "") + line.slice(start, end).trim() + (end < line.length ? "…" : "");
+}
+/**
+* Cherche un texte dans les docs colocalisées des modules donnés.
+*
+* ⭐ **Pourquoi cette fonction existe** : chez un utilisateur, la documentation
+* des modules vit sous `node_modules/@nodefony/<mod>/docs/` — un dossier que `git`
+* ignore, donc que `rg` et les outils de recherche des agents EXCLUENT par
+* défaut. La doc est livrée et introuvable ; c'est cette porte qui la rend
+* atteignable, sans quoi l'agent réécrit à la main ce qui est déjà écrit.
+*
+* Un document est retenu s'il porte **TOUS** les termes (et non l'un d'eux) :
+* sur un corpus où « session » apparaît partout, un OU rendrait le corpus.
+* La comparaison est faite sans casse ni diacritiques ({@link fold}).
+*
+* Aucun index n'est conservé : le corpus est relu à chaque appel. C'est une
+* opération de développement, rare et explicite — un index en mémoire coûterait
+* en permanence ce qu'il ferait gagner quelques fois, et se périmerait à la
+* première doc éditée.
+*
+* @param targets - modules à balayer (clé + chemin disque)
+* @param query - texte cherché ; les espaces séparent des termes cumulatifs
+* @param options - bornes de rendu (`limit` docs, `perDoc` extraits)
+* @returns les docs retenues, et ce que la recherche a réellement balayé
+*/
+async function searchModuleDocs(targets, query, options = {}) {
+	const terms = fold(query).split(/\s+/).filter((t) => t.length > 0);
+	const limit = options.limit ?? SEARCH_MAX_DOCS;
+	const perDoc = options.perDoc ?? SEARCH_MAX_PER_DOC;
+	if (terms.length === 0) return {
+		terms,
+		scanned: 0,
+		matched: 0,
+		hits: []
+	};
+	const hits = [];
+	let scanned = 0;
+	for (const target of targets) {
+		const docsDir = join(target.path, "docs");
+		let entries;
+		try {
+			entries = await readdir(docsDir);
+		} catch {
+			continue;
+		}
+		for (const fileName of entries) {
+			if (!fileName.toLowerCase().endsWith(".md")) continue;
+			let raw;
+			try {
+				raw = await readFile(join(docsDir, fileName), "utf8");
+			} catch {
+				continue;
+			}
+			scanned += 1;
+			const slug = basename(fileName, extname(fileName));
+			const { data, body } = parseFrontmatter(raw);
+			const title = docTitle(data, body, slug);
+			const foldedTitle = fold(`${title} ${typeof data.navTitle === "string" && data.navTitle.trim() ? data.navTitle.trim() : ""} ${slug}`);
+			const lines = body.split("\n");
+			const foldedLines = lines.map(fold);
+			const foldedBody = fold(body);
+			if (!terms.every((term) => foldedBody.includes(term) || foldedTitle.includes(term))) continue;
+			let occurrences = 0;
+			let score = 0;
+			for (const term of terms) {
+				let at = foldedBody.indexOf(term);
+				while (at !== -1) {
+					occurrences += 1;
+					at = foldedBody.indexOf(term, at + term.length);
+				}
+				if (foldedTitle.includes(term)) score += TITLE_WEIGHT;
+			}
+			score += occurrences / Math.max(1, foldedBody.length / DOC_LENGTH_PIVOT);
+			const candidates = [];
+			for (let i = 0; i < lines.length; i += 1) {
+				const carried = terms.filter((t) => foldedLines[i].includes(t));
+				if (carried.length === 0) continue;
+				candidates.push({
+					lineNumber: i,
+					coverage: carried.length,
+					matchedTerm: carried[0]
+				});
+			}
+			candidates.sort((a, b) => b.coverage - a.coverage || a.lineNumber - b.lineNumber);
+			const matches = candidates.slice(0, perDoc).sort((a, b) => a.lineNumber - b.lineNumber).map((c) => ({
+				line: c.lineNumber + 1,
+				text: snippet(lines[c.lineNumber], foldedLines[c.lineNumber], c.matchedTerm)
+			}));
+			hits.push({
+				module: target.key,
+				slug,
+				title,
+				matches,
+				occurrences,
+				score
+			});
+		}
+	}
+	hits.sort((a, b) => b.score - a.score || a.slug.localeCompare(b.slug));
+	const returned = hits.slice(0, limit);
+	return {
+		terms,
+		scanned,
+		matched: hits.length,
+		hits: returned,
+		...hits.length > returned.length ? { note: `${hits.length} documents portent ces termes, ${returned.length} sont rendus (borne « limit » = ${limit}). Précise les termes, ou rappelle avec limit plus grand.` } : {}
+	};
+}
+/**
+* Symboles TS exportés d'un module + descriptions TSDoc, lus depuis
+* `.ai/symbols.json` (à la racine de l'application, cf {@link appRoot}).
+*
+* 100 % auto-généré (jamais de `.d.ts` manuel) → zéro divergence avec le code.
+* Tab API maigre tant que la couverture TSDoc est faible : c'est volontaire,
+* ça pousse à documenter.
+*
+* @param packageName - nom npm du module (`Module.getModuleName()`, ex
+*   `"@nodefony/http"`) — clé `.module` dans le graphe symbolique.
+* @returns symboles exportés triés par kind puis nom (vide si fichier absent).
+*/
+async function listModuleSymbols(packageName) {
+	const file = resolveSymbolsFile(process.cwd());
+	if (file === null) return [];
+	let parsed;
+	try {
+		parsed = JSON.parse(await readFile(file, "utf8"));
+	} catch {
+		return [];
+	}
+	const symbols = parsed.symbols ?? {};
+	const out = [];
+	for (const sym of Object.values(symbols)) {
+		if (sym.module !== packageName || sym.exported !== true) continue;
+		out.push({
+			name: sym.name ?? "",
+			kind: sym.kind ?? "unknown",
+			file: sym.file ?? "",
+			description: typeof sym.description === "string" ? sym.description : null,
+			extends: sym.extends ?? null,
+			implements: Array.isArray(sym.implements) ? sym.implements : [],
+			decorators: Array.isArray(sym.decorators) ? sym.decorators : []
+		});
+	}
+	return out.sort((a, b) => a.kind.localeCompare(b.kind) || a.name.localeCompare(b.name));
+}
+/** Au-delà, une déclaration cesse d'informer et se met à remplir. */
+const DECLARATION_MAX_CHARS = 12e3;
+/** Garde-fou de balayage : un `dist/types` sain tient en quelques dizaines. */
+const DECLARATION_MAX_FILES = 400;
+/**
+* Fichiers de types d'un module, du plus probable au moins probable.
+*
+* `dist/types/` est ce qu'un utilisateur REÇOIT ; les sources `.ts` ne sont là
+* que dans ce dépôt, où quelques paquets pointent leurs types vers leur
+* `index.ts` (anti-race de build). On regarde donc les deux, dans cet ordre —
+* mais on ne descend jamais dans `node_modules`, dont les types appartiennent à
+* d'autres.
+*/
+async function typeFiles(modulePath) {
+	const found = [];
+	for (const sub of [
+		"dist/types",
+		"nodefony",
+		"src"
+	]) {
+		let entries;
+		try {
+			entries = await readdir(join(modulePath, sub), { recursive: true });
+		} catch {
+			continue;
+		}
+		for (const entry of entries) {
+			if (entry.includes("node_modules")) continue;
+			if (!entry.endsWith(".d.ts") && !entry.endsWith(".ts")) continue;
+			if (entry.endsWith(".test.ts")) continue;
+			found.push(join(sub, entry));
+			if (found.length >= DECLARATION_MAX_FILES) return found;
+		}
+	}
+	return found;
+}
+/**
+* Où commence la déclaration d'un symbole — avec le TSDoc qui la précède.
+*
+* Le commentaire n'est pas un ornement : c'est là que vit le POURQUOI, et il
+* traverse le build (`.d.ts`) là où un `//` inline disparaît. Le rendre avec la
+* signature est ce qui distingue « voici les paramètres » de « voici ce qu'en
+* faire ».
+*/
+function declarationStart(lines, at) {
+	let start = at;
+	if (start > 0 && lines[start - 1].trim().endsWith("*/")) {
+		let i = start - 1;
+		while (i > 0 && !lines[i].trim().startsWith("/**")) i -= 1;
+		if (lines[i].trim().startsWith("/**")) start = i;
+	}
+	return start;
+}
+/**
+* Extrait la déclaration d'un symbole des types LIVRÉS d'un module.
+*
+* ⭐ **Pourquoi cette fonction existe** : le graphe symbolique
+* (`.ai/symbols.json`) dit qu'un symbole existe, ce qu'il étend et la première
+* phrase de sa documentation — mais **pas sa signature**. À « quels arguments
+* prend cette méthode ? », un agent n'a donc aucune réponse : les `.d.ts` qui
+* la portent vivent sous `node_modules`, que git ignore et que les outils de
+* recherche de fichiers excluent. Il devine, et il devine faux.
+*
+* Le nom demandé ne touche JAMAIS un chemin : il sert à filtrer du texte. Les
+* fichiers balayés sont dérivés du module, pas de l'appelant — un paramètre qui
+* entrerait dans un `join` serait une traversée de répertoire offerte.
+*
+* @param modulePath - chemin disque du module (`Module.path`)
+* @param symbolName - nom exact du symbole (`AbstractCrudService`, `IKernel`)
+* @returns la déclaration et son fichier, ou `null` si rien ne la porte
+*/
+async function readSymbolDeclaration(modulePath, symbolName) {
+	if (!/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(symbolName)) return null;
+	const declare = new RegExp(String.raw`^\s*(?:export\s+)?(?:declare\s+)?(?:abstract\s+)?` + String.raw`(?:class|interface|function|const|let|var|type|enum|namespace)\s+` + symbolName + String.raw`\b`);
+	for (const relative of await typeFiles(modulePath)) {
+		let raw;
+		try {
+			raw = await readFile(join(modulePath, relative), "utf8");
+		} catch {
+			continue;
+		}
+		if (!raw.includes(symbolName)) continue;
+		const lines = raw.split("\n");
+		const at = lines.findIndex((line) => declare.test(line));
+		if (at === -1) continue;
+		const start = declarationStart(lines, at);
+		let depth = 0;
+		let opened = false;
+		let end = at;
+		for (let i = at; i < lines.length; i += 1) {
+			for (const ch of lines[i]) if (ch === "{") {
+				depth += 1;
+				opened = true;
+			} else if (ch === "}") depth -= 1;
+			end = i;
+			if (opened && depth <= 0) break;
+			if (!opened && lines[i].trimEnd().endsWith(";")) break;
+		}
+		const declaration = lines.slice(start, end + 1).join("\n");
+		return declaration.length > DECLARATION_MAX_CHARS ? {
+			declarationFile: relative,
+			declaration: declaration.slice(0, DECLARATION_MAX_CHARS),
+			truncated: true
+		} : {
+			declarationFile: relative,
+			declaration,
+			truncated: false
+		};
+	}
+	return null;
+}
+/**
+* Identité du package npm du core (`@nodefony/core`) tel qu'indexé dans
+* `.ai/symbols.json` — le core est référencé sous ce nom logique, **pas** sous
+* son nom npm réel (`nodefony`, héritage JS).
+*/
+const CORE_PACKAGE = "@nodefony/core";
+/**
+* Dépendances d'un module : depuis son `package.json` (dependencies +
+* peerDependencies) avec la version RÉELLEMENT installée (lue dans
+* `node_modules/<dep>/package.json`, local puis hoisté à la racine).
+*/
+async function readDependencies(modulePath) {
+	let pkg = {};
+	try {
+		pkg = JSON.parse(await readFile(join(modulePath, "package.json"), "utf8"));
+	} catch {}
+	const ranges = {
+		...pkg.dependencies,
+		...pkg.peerDependencies
+	};
+	const root = appRoot();
+	const out = [];
+	for (const name of Object.keys(ranges).sort()) {
+		const kind = name === "nodefony" || name.startsWith("@nodefony/") ? "nodefony" : "external";
+		let installed = null;
+		for (const base of [modulePath, root]) try {
+			const dp = JSON.parse(await readFile(join(base, "node_modules", name, "package.json"), "utf8"));
+			if (typeof dp.version === "string") {
+				installed = dp.version;
+				break;
+			}
+		} catch {}
+		out.push({
+			name,
+			kind,
+			range: ranges[name] ?? null,
+			installed
+		});
+	}
+	return out;
+}
+/** Compare deux versions semver (a > b ?) — major.minor.patch numérique. */
+function semverGt(a, b) {
+	const p = (s) => s.replace(/^[^\d]*/, "").split(".").map((n) => parseInt(n, 10) || 0);
+	const pa = p(a);
+	const pb = p(b);
+	for (let i = 0; i < 3; i++) {
+		if ((pa[i] || 0) > (pb[i] || 0)) return true;
+		if ((pa[i] || 0) < (pb[i] || 0)) return false;
+	}
+	return false;
+}
+/**
+* Vérifie les MAJ des deps EXTERNES via le registry npm (`/<pkg>/latest`).
+* Les deps Nodefony (workspaces locaux) sont ignorées. Réseau → on-demand.
+*/
+async function checkOutdated(deps) {
+	const external = deps.filter((d) => d.kind === "external");
+	return Promise.all(external.map(async (d) => {
+		let latest = null;
+		try {
+			const url = `https://registry.npmjs.org/${encodeURIComponent(d.name)}/latest`;
+			const r = await fetch(url, { signal: AbortSignal.timeout(8e3) });
+			if (r.ok) {
+				const j = await r.json();
+				if (typeof j.version === "string") latest = j.version;
+			}
+		} catch {}
+		return {
+			name: d.name,
+			installed: d.installed,
+			latest,
+			outdated: Boolean(latest && d.installed && semverGt(latest, d.installed))
+		};
+	}));
+}
+/** Walk `*.test.ts` (hors node_modules/dist/.coverage) → chemins relatifs triés. */
+async function collectTestFiles(modulePath) {
+	const out = [];
+	const walk = async (dir, depth) => {
+		if (depth > 8) return;
+		let entries;
+		try {
+			entries = await readdir(dir, { withFileTypes: true });
+		} catch {
+			return;
+		}
+		for (const e of entries) {
+			if (e.name === "node_modules" || e.name === "dist" || e.name === ".coverage") continue;
+			const full = join(dir, e.name);
+			if (e.isDirectory()) await walk(full, depth + 1);
+			else if (e.isFile() && e.name.endsWith(".test.ts")) out.push(rel(full, modulePath));
+		}
+	};
+	await walk(modulePath, 0);
+	out.sort();
+	return out;
+}
+/** Est-ce un test unit ? (seul lançable par `vitest run <file>` sans serveur). */
+function isUnitTest(relPath) {
+	return relPath.includes("/unit/") || relPath.includes("tests/unit/");
+}
+/** Catégorie d'un fichier de test, dérivée de son chemin/nom (dossier de suite). */
+function testCategory(relPath) {
+	if (isUnitTest(relPath)) return "unit";
+	if (relPath.includes("/integration/")) return "integration";
+	if (relPath.includes("/e2e/") || relPath.endsWith(".e2e.test.ts")) return "e2e";
+	if (relPath.includes("/load/")) return "load";
+	if (relPath.includes("/websockets/")) return "websockets";
+	if (relPath.includes("/routing/")) return "routing";
+	if (relPath.endsWith("memory.test.ts")) return "memory";
+	return "autre";
+}
+/**
+* Liste les fichiers de test **unit** d'un module (lançables par `vitest run`).
+* Si aucune suite unit, repli sur tous les fichiers. Chemins relatifs au module.
+*/
+async function listTestFiles(modulePath) {
+	const all = await collectTestFiles(modulePath);
+	const unit = all.filter(isUnitTest);
+	return unit.length ? unit : all;
+}
+const TEST_CATEGORY_ORDER = [
+	"unit",
+	"integration",
+	"e2e",
+	"websockets",
+	"routing",
+	"load",
+	"memory",
+	"autre"
+];
+/**
+* Groupe TOUS les fichiers de test d'un module par catégorie (lecture seule pour
+* l'onglet Tests — les non-unit ne sont pas lançables depuis Studio : ils exigent
+* un serveur live / une base, donc `runnable:false`). Donne une vue complète des
+* suites (intégration/e2e/charge/mémoire) qui étaient invisibles auparavant.
+*/
+async function listTestGroups(modulePath) {
+	const all = await collectTestFiles(modulePath);
+	const byCat = /* @__PURE__ */ new Map();
+	for (const f of all) {
+		const c = testCategory(f);
+		let arr = byCat.get(c);
+		if (arr === void 0) {
+			arr = [];
+			byCat.set(c, arr);
+		}
+		arr.push(f);
+	}
+	return [...byCat.entries()].sort(([a], [b]) => TEST_CATEGORY_ORDER.indexOf(a) - TEST_CATEGORY_ORDER.indexOf(b)).map(([category, files]) => ({
+		category,
+		files,
+		runnable: category === "unit"
+	}));
+}
+/**
+* Compose la commande d'un run de tests de module, sans l'exécuter.
+*
+* - 1 fichier (module vitest) → `npx vitest run <file>` : le chemin est un
+*   FILTRE positionnel de vitest. Il ne doit JAMAIS suivre un `--` : vitest
+*   ignore tout ce qui vient après, et la suite ENTIÈRE tourne en silence
+*   (vécu : 18 fichiers joués pour un seul demandé, verdict « vert »). La
+*   défense anti-injection d'argument est la garde de l'appelant (pas de
+*   préfixe `-`, pas de `..`, suffixe `.test.ts` — cf KernelAdminApi).
+* - sinon (module vitest) → run-all, reporters coverage FORCÉS vers
+*   `.coverage` : l'onglet Coverage de Studio apparaît quelle que soit la
+*   config du module (la liste `reporter` dupliquée par module divergeait).
+* - sinon (cœur : monocart, pas de `vitest.config.ts`) → `npm run coverage`.
+*
+* @param modulePath - racine du module (où vit `vitest.config.ts`)
+* @param file - chemin relatif d'UN fichier de test, déjà validé par l'appelant
+* @returns commande, arguments en tableau (spawn sans shell) et libellé du mode
+*/
+function testRunCommand(modulePath, file) {
+	const hasVitest = existsSync(join(modulePath, "vitest.config.ts"));
+	if (file && hasVitest) return {
+		cmd: "npx",
+		args: [
+			"vitest",
+			"run",
+			file
+		],
+		mode: `vitest run ${file}`
+	};
+	if (hasVitest) return {
+		cmd: "npx",
+		args: [
+			"vitest",
+			"run",
+			"--coverage",
+			"--coverage.reporter=text-summary",
+			"--coverage.reporter=json-summary",
+			"--coverage.reporter=lcov",
+			"--coverage.reportsDirectory=.coverage"
+		],
+		mode: "vitest run --coverage (reporters forcés)"
+	};
+	return {
+		cmd: "npm",
+		args: ["run", "coverage"],
+		mode: "npm run coverage (suite complète)"
+	};
+}
+/**
+* Lance les tests d'un module et renvoie un résumé (pass/fail/durée + tail).
+*
+* - 1 fichier (module vitest) → `npx vitest run <file>` (rapide, pass/fail).
+* - sinon → `npm run coverage` (suite complète + refresh coverage ; marche
+*   pour vitest comme pour monocart/core).
+*
+* ⚠️ EXÉCUTE un process — appelé UNIQUEMENT derrière le garde dev-only de
+* l'endpoint (cf KernelAdminApi). spawn sans shell + args en tableau (pas
+* d'injection shell). `file` validé en amont (suffixe .test.ts, pas de `..`).
+*/
+function runModuleTests(modulePath, file) {
+	const { cmd, args, mode } = testRunCommand(modulePath, file);
+	const start = Date.now();
+	return new Promise((resolve) => {
+		let out = "";
+		const cap = (d) => {
+			out += d.toString();
+			if (out.length > 2e5) out = out.slice(-2e5);
+		};
+		let child;
+		try {
+			child = spawn(cmd, args, {
+				cwd: modulePath,
+				env: process.env
+			});
+		} catch (e) {
+			return resolve({
+				ok: false,
+				code: null,
+				passed: 0,
+				failed: 0,
+				durationMs: 0,
+				output: String(e),
+				mode
+			});
+		}
+		child.stdout?.on("data", cap);
+		child.stderr?.on("data", cap);
+		const timer = setTimeout(() => child.kill("SIGKILL"), 18e4);
+		let settled = false;
+		const settle = (result) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			child.stdout?.off("data", cap);
+			child.stderr?.off("data", cap);
+			resolve(result);
+		};
+		child.on("error", (e) => {
+			settle({
+				ok: false,
+				code: null,
+				passed: 0,
+				failed: 0,
+				durationMs: Date.now() - start,
+				output: String(e),
+				mode
+			});
+		});
+		child.on("close", (code) => {
+			const clean = out.replace(/\x1b\[[0-9;]*m/g, "");
+			const passed = Number(clean.match(/Tests\s+(\d+)\s+passed/)?.[1] ?? clean.match(/(\d+)\s+passing/)?.[1] ?? 0);
+			const failed = Number(clean.match(/(\d+)\s+failed/)?.[1] ?? clean.match(/(\d+)\s+failing/)?.[1] ?? 0);
+			settle({
+				ok: code === 0,
+				code,
+				passed,
+				failed,
+				durationMs: Date.now() - start,
+				output: clean.slice(-6e3),
+				mode
+			});
+		});
+	});
+}
+/**
+* Chemin disque racine du package core (`nodefony`).
+*
+* Le core n'est **pas** un module chargé (`kernel.getModules()` n'a pas de clé
+* `core`) : c'est le socle de tous les autres. On résout donc son emplacement
+* pour lire ses docs colocalisées (`<core>/docs/*.md`).
+*
+* Dev self-hosted : `<racine de l'app>/src/nodefony`. Fallback prod :
+* résolution du package npm `nodefony` (remontée jusqu'à son `package.json`).
+*/
+function resolveCorePath() {
+	const devPath = join(appRoot(), "src", "nodefony");
+	if (existsSync(join(devPath, "package.json"))) return devPath;
+	try {
+		let dir = dirname(fileURLToPath(import.meta.resolve("nodefony")));
+		for (let i = 0; i < 6; i++) {
+			if (existsSync(join(dir, "package.json"))) return dir;
+			dir = dirname(dir);
+		}
+	} catch {}
+	return devPath;
+}
+const rel = (abs, modulePath) => abs.startsWith(modulePath) ? abs.slice(modulePath.length).replace(/^\/+/, "") : abs;
+const round2 = (n) => Math.round(n * 100) / 100;
+/** Parse un `coverage-summary.json` (istanbul/vitest : total + par fichier). */
+function parseSummary(json, modulePath) {
+	const total = json.total;
+	if (!total) return null;
+	const pct = (m) => typeof m?.pct === "number" ? m.pct : 0;
+	const files = [];
+	for (const [abs, v] of Object.entries(json)) {
+		if (abs === "total") continue;
+		const m = v;
+		files.push({
+			file: rel(abs, modulePath),
+			lines: pct(m.lines),
+			statements: pct(m.statements),
+			functions: pct(m.functions),
+			branches: pct(m.branches)
+		});
+	}
+	return {
+		available: true,
+		total: {
+			lines: pct(total.lines),
+			statements: pct(total.statements),
+			functions: pct(total.functions),
+			branches: pct(total.branches)
+		},
+		files
+	};
+}
+/** Parse un `lcov.info` (produit par monocart ET vitest) en {total, files}. */
+function parseLcov(text, modulePath) {
+	const files = [];
+	const tot = {
+		lf: 0,
+		lh: 0,
+		fnf: 0,
+		fnh: 0,
+		brf: 0,
+		brh: 0
+	};
+	let cur = null;
+	const num = (s, i) => Number(s.slice(i)) || 0;
+	const pctOf = (h, f) => f > 0 ? round2(h / f * 100) : 100;
+	for (const line of text.split("\n")) if (line.startsWith("SF:")) cur = {
+		p: line.slice(3).trim(),
+		lf: 0,
+		lh: 0,
+		fnf: 0,
+		fnh: 0,
+		brf: 0,
+		brh: 0
+	};
+	else if (!cur) continue;
+	else if (line.startsWith("LF:")) cur.lf = num(line, 3);
+	else if (line.startsWith("LH:")) cur.lh = num(line, 3);
+	else if (line.startsWith("FNF:")) cur.fnf = num(line, 4);
+	else if (line.startsWith("FNH:")) cur.fnh = num(line, 4);
+	else if (line.startsWith("BRF:")) cur.brf = num(line, 4);
+	else if (line.startsWith("BRH:")) cur.brh = num(line, 4);
+	else if (line.startsWith("end_of_record")) {
+		const ln = pctOf(cur.lh, cur.lf);
+		files.push({
+			file: rel(cur.p, modulePath),
+			lines: ln,
+			statements: ln,
+			functions: pctOf(cur.fnh, cur.fnf),
+			branches: pctOf(cur.brh, cur.brf)
+		});
+		tot.lf += cur.lf;
+		tot.lh += cur.lh;
+		tot.fnf += cur.fnf;
+		tot.fnh += cur.fnh;
+		tot.brf += cur.brf;
+		tot.brh += cur.brh;
+		cur = null;
+	}
+	if (!files.length) return null;
+	const ln = pctOf(tot.lh, tot.lf);
+	return {
+		available: true,
+		total: {
+			lines: ln,
+			statements: ln,
+			functions: pctOf(tot.fnh, tot.fnf),
+			branches: pctOf(tot.brh, tot.brf)
+		},
+		files
+	};
+}
+/**
+* Lit le dernier rapport de couverture d'un module dans `<module>/.coverage/`.
+* Préfère `coverage-summary.json` (vitest, a les statements) ; sinon parse
+* `lcov.info` (produit par monocart côté core ET par vitest). Studio AFFICHE ce
+* rapport — il ne lance pas les tests. `available:false` si rien de généré.
+*/
+async function readCoverage(modulePath) {
+	const dir = join(modulePath, ".coverage");
+	let report = null;
+	let usedFile = null;
+	const summaryPath = join(dir, "coverage-summary.json");
+	try {
+		report = parseSummary(JSON.parse(await readFile(summaryPath, "utf8")), modulePath);
+		if (report) usedFile = summaryPath;
+	} catch {}
+	if (!report) {
+		const lcovPath = join(dir, "lcov.info");
+		try {
+			report = parseLcov(await readFile(lcovPath, "utf8"), modulePath);
+			if (report) usedFile = lcovPath;
+		} catch {}
+	}
+	if (!report) return { available: false };
+	report.files.sort((a, b) => a.file.localeCompare(b.file));
+	try {
+		report.generated = usedFile ? (await stat(usedFile)).mtime.toISOString() : null;
+	} catch {
+		report.generated = null;
+	}
+	return report;
+}
+/**
+* Métadonnées du core pour Studio (carte + onglet Vue d'ensemble).
+*
+* `name` est forcé à `@nodefony/core` (cohérent avec `.ai/symbols.json` et le
+* frontmatter `module:`), même si son `package.json` se nomme `nodefony`.
+* `version`/`dependencies` viennent de ce `package.json`.
+*/
+async function readCoreInfo() {
+	const path = resolveCorePath();
+	let version = null;
+	let dependencies = [];
+	try {
+		const pkg = JSON.parse(await readFile(join(path, "package.json"), "utf8"));
+		version = typeof pkg.version === "string" ? pkg.version : null;
+		dependencies = [...Object.keys(pkg.dependencies ?? {}), ...Object.keys(pkg.peerDependencies ?? {})];
+	} catch {}
+	return {
+		path,
+		name: CORE_PACKAGE,
+		version,
+		dependencies
+	};
+}
+//#endregion
+export { CORE_PACKAGE, checkOutdated, countModuleDocs, listModuleDocs, listModuleSymbols, listTestFiles, listTestGroups, parseFrontmatter, readCoreInfo, readCoverage, readDependencies, readModuleDoc, readSymbolDeclaration, resolveCorePath, runModuleTests, searchModuleDocs, testRunCommand };