nodefony 7.0.2 → 10.0.0-alpha.2

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

@@ -0,0 +1,364 @@
+import { collectSources } from "./walk.js";
+import { readFileSync, statSync } from "node:fs";
+import path from "node:path";
+//#region src/kernel/checks/surface.ts
+/**
+* `doctor` — la SURFACE OUVERTE, et les entités écrites pour un autre moteur.
+*
+* Deux angles morts, tous deux lisibles sans démarrer, tous deux silencieux
+* aujourd'hui.
+*
+* **La surface ouverte ne se voit nulle part d'un coup.** Une route porte
+* `@BypassFirewall` ou `@Anonymous`, une zone porte `security: false` — chacun
+* est légitime pris isolément, et personne n'a jamais la liste sous les yeux.
+* C'est ainsi qu'une route de mise au point reste ouverte en production. Le
+* remède n'est donc PAS un verdict : c'est un INVENTAIRE. Un contrôle qui crie
+* sur un geste légitime est un contrôle qu'on apprend à passer outre — seul le
+* cas indéfendable (une zone publique qui couvre tout l'espace) devient un
+* manquement.
+*
+* **Une entité écrite pour le mauvais dialecte est ÉCARTÉE EN SILENCE.** Une
+* entité qui importe `drizzle-orm/pg-core` alors que le connecteur est `sqlite`
+* n'est pas une erreur pour l'outil : il la met de côté et écrit une migration
+* sans elle. La table n'est jamais créée, l'application démarre, la route
+* répond 500 au premier usage, et rien dans le code ne montre la cause.
+*
+* ⚠️ Ce module lit des SOURCES, jamais un `dist/` : le contrôle doit répondre y
+* compris sur une application qui ne compile plus — c'est précisément là qu'on
+* le consulte.
+*/
+/** Un import de table Drizzle : `drizzle-orm/pg-core` et ses frères. */
+const DRIZZLE_CORE_RE = /["']drizzle-orm\/(sqlite|pg|mysql)-core["']/gu;
+/** Le dialecte de Nodefony pour un segment d'import Drizzle. */
+const DIALECT_OF_IMPORT = {
+	sqlite: "sqlite",
+	pg: "postgres",
+	mysql: "mysql"
+};
+/**
+* Le caractère du décorateur, COMPOSÉ et non écrit.
+*
+* 🔴 Un contrôle qui cherche une chaîne la contient forcément, et s'accuse
+* lui-même : au premier essai, ce fichier a inventorié deux « routes ouvertes »
+* dans son propre source, et le rendu les affichait au même rang que les
+* vraies. Composer le motif est le seul remède qui ne demande ni exception
+* arbitraire ni exclusion d'un dossier — la chaîne cherchée n'existe nulle part
+* ici, donc rien à excepter.
+*/
+const AT = "@";
+/** `@BypassFirewall`, avec ou sans parenthèses — c'est un DRAPEAU. */
+const BYPASS_RE = new RegExp(`${AT}BypassFirewall\\b`, "gu");
+/** `@Anonymous` — le même mécanisme, dit autrement. */
+const ANONYMOUS_RE = new RegExp(`${AT}Anonymous\\b`, "gu");
+/** `bypassFirewall: true` posé dans les options d'une route. */
+const BYPASS_OPTION_RE = /\bbypassFirewall\s*:\s*true\b/gu;
+/** La déclaration qui SUIT une ouverture — c'est elle qu'on nomme. */
+const MEMBER_AFTER_RE = /\b(?:async\s+)?([A-Za-z_$][\w$]*)\s*\([^)]{0,200}\)\s*[:{]/u;
+/** Une ouverture posée sur la CLASSE ouvre TOUTES ses routes — on le dit. */
+const CLASS_AFTER_RE = /\bclass\s+([A-Za-z_$][\w$]*)/u;
+/**
+* Ce qui fait d'un fichier un porteur de ROUTES.
+*
+* DEUX formes, et il faut les deux : le décorateur, et l'héritage. Les routes
+* d'un contrôleur du framework se posent programmatiquement, sans décorateur —
+* n'accepter que la première ferait disparaître de l'inventaire cinq
+* contrôleurs d'authentification, tous légitimement ouverts, donc exactement
+* ceux qu'on veut voir listés.
+*/
+const CONTROLLER_RE = new RegExp(`${AT}controller\\b|\\bextends\\s+Controller\\b`, "u");
+/** Le bloc `areas: { … }` du manifeste, et lui seul. */
+const AREAS_BLOCK_RE = /\bareas\s*:\s*\{/u;
+/**
+* Des chemins témoins, choisis pour n'avoir AUCUN préfixe commun utile.
+*
+* Un motif qui les accepte tous accepte n'importe quelle requête.
+*/
+const PROBE_PATHS = [
+	"/",
+	"/admin",
+	"/x/y/z",
+	"/nodefony/kernel/api"
+];
+/**
+* Ce motif de zone laisse-t-il passer TOUT l'espace d'URL ?
+*
+* CONSTATÉ, jamais listé : le motif est compilé et éprouvé exactement comme le
+* firewall le fait (`SecuredArea.ts:25` — `new RegExp(pattern, "u")`, non
+* ancré, `test(pathname)`), puis confronté à des chemins sans parenté. Une
+* liste écrite à la main disait le contraire du produit dans les deux sens :
+* elle CONDAMNAIT `^/api`, qui ne couvre que `/api…`, et laissait passer
+* `^/.*`, `.*` et `^`, qui ouvrent réellement tout.
+*
+* @param pattern - le motif tel que le manifeste l'écrit.
+* @returns `true` si aucune route ne peut échapper à cette zone.
+*/
+function coversEverything(pattern) {
+	let re;
+	try {
+		re = new RegExp(pattern, "u");
+	} catch {
+		return false;
+	}
+	return PROBE_PATHS.every((rawPath) => re.test(rawPath));
+}
+/**
+* Les commentaires, ôtés AVANT toute analyse.
+*
+* Sans quoi le contrôle mord sur la documentation : un commentaire qui apprend
+* à ne PAS ouvrir une zone cite forcément le contre-exemple, et toute
+* application fraîche commencerait par un avertissement portant sur du texte
+* explicatif. Un contrôle qui accuse sa propre documentation est un contrôle
+* qu'on désactive.
+*/
+function withoutComments(source) {
+	return source.replace(/\/\*[\s\S]*?\*\//gu, "").replace(/\/\/[^\n]*/gu, "");
+}
+/**
+* Le contenu d'un bloc d'accolades ÉQUILIBRÉES à partir d'une position.
+*
+* Une expression régulière ne sait pas compter les accolades : un bloc `areas`
+* contenant une zone qui contient ses authentificateurs se ferait couper au
+* premier `}` venu, et la moitié des zones deviendrait invisible — un contrôle
+* de surface qui ne voit qu'une partie de la surface est pire qu'aucun.
+*
+* @param source - le texte à lire.
+* @param open - l'index de l'accolade ouvrante.
+* @returns le contenu entre les accolades, vide si elles ne se referment pas.
+*/
+function balancedBlock(source, open) {
+	let depth = 0;
+	for (let i = open; i < source.length; i++) {
+		const c = source[i];
+		if (c === "{") depth++;
+		else if (c === "}") {
+			depth--;
+			if (depth === 0) return source.slice(open + 1, i);
+		}
+	}
+	return "";
+}
+/**
+* Les zones publiques déclarées dans un manifeste.
+*
+* Fonction PURE sur le TEXTE du manifeste : c'est ce qui la rend éprouvable
+* sans écrire de fichier, et ce qui lui permet de répondre sur un manifeste que
+* TypeScript refuserait de compiler.
+*
+* @param manifest - le contenu de `nodefony.config.ts`.
+* @returns une entrée par zone `security: false`, avec son motif.
+*/
+function publicAreas(manifest) {
+	const clean = withoutComments(manifest);
+	const at = clean.search(AREAS_BLOCK_RE);
+	if (at === -1) return [];
+	const block = balancedBlock(clean, clean.indexOf("{", at));
+	const zones = [];
+	let i = 0;
+	while (i < block.length) {
+		const brace = block.indexOf("{", i);
+		if (brace === -1) break;
+		const zone = balancedBlock(block, brace);
+		i = brace + zone.length + 2;
+		if (!/\bsecurity\s*:\s*false\b/u.test(zone)) continue;
+		const pattern = /\bpattern\s*:\s*["'`]([^"'`\n]+)["'`]/u.exec(zone)?.[1];
+		zones.push({ pattern: pattern ?? "(motif non littéral)" });
+	}
+	return zones;
+}
+/**
+* Le dialecte du connecteur, tel qu'on peut le déterminer SANS démarrer.
+*
+* Trois sources, dans l'ordre de précédence du produit : l'infrastructure
+* déclarée gagne (un hébergeur pose l'URL), puis ce que le manifeste écrit,
+* puis le défaut du module. La provenance est RENDUE avec la valeur : un
+* dialecte affirmé sans dire d'où il vient ne se contredit pas.
+*
+* @param manifest - le contenu de `nodefony.config.ts`.
+* @param env - l'environnement dans lequel le diagnostic tourne.
+* @returns le dialecte et sa provenance, `null` si rien ne le dit.
+*/
+function connectorDialect(manifest, env) {
+	const from = env.NF_DATABASE_URL ? "NF_DATABASE_URL" : "DATABASE_URL";
+	const url = env.NF_DATABASE_URL || env.DATABASE_URL;
+	if (url) {
+		const scheme = /^([a-z0-9+]+):/iu.exec(url)?.[1]?.toLowerCase() ?? "";
+		if (scheme.startsWith("postgres")) return {
+			dialect: "postgres",
+			from
+		};
+		if (scheme.startsWith("mysql")) return {
+			dialect: "mysql",
+			from
+		};
+		if (scheme.startsWith("sqlite") || scheme === "file") return {
+			dialect: "sqlite",
+			from
+		};
+	}
+	const written = /\bdialect\s*:\s*["'`](sqlite|postgres|mysql)["'`]/u.exec(withoutComments(manifest))?.[1];
+	if (written) return {
+		dialect: written,
+		from: "nodefony.config.ts"
+	};
+	return {
+		dialect: "sqlite",
+		from: "défaut du connecteur"
+	};
+}
+/** Extensions dans lesquelles une déclaration peut vivre. */
+const SOURCE_EXT = /* @__PURE__ */ new Set([
+	".ts",
+	".mts",
+	".cts"
+]);
+/**
+* Le dossier où les entités sont CHERCHÉES, tel que le producteur le définit.
+*
+* `nodefony/entity/**`, et rien d'autre (`appSchema.ts:71`). Élargir au reste
+* du dépôt ferait accuser ce qui n'est pas une entité : l'adaptateur ORM
+* lui-même importe les trois dialectes, et c'est son travail.
+*/
+const ENTITY_DIR = `${path.sep}nodefony${path.sep}entity${path.sep}`;
+/** Les sources d'une cible, sans jamais entrer dans un `dist/`. */
+function sources(root) {
+	return collectSources(root, {
+		extensions: [...SOURCE_EXT],
+		maxDepth: 8
+	});
+}
+/**
+* Le nom déclaré juste après une ouverture.
+*
+* Une ouverture posée sur la CLASSE ne vaut pas pour une méthode : elle ouvre
+* tout le contrôleur, et l'afficher comme une route unique ferait sous-estimer
+* la surface d'un facteur égal au nombre de ses routes.
+*/
+function openingName(source, at) {
+	const after = source.slice(at, at + 400);
+	const method = MEMBER_AFTER_RE.exec(after)?.[1];
+	const klass = CLASS_AFTER_RE.exec(after)?.[1];
+	const iMethod = method ? after.indexOf(method) : Infinity;
+	const iClass = klass ? after.indexOf(klass) : Infinity;
+	if (klass && iClass < iMethod) return `${klass} (toutes ses routes)`;
+	return method ?? "(déclaration non nommée)";
+}
+/** Relève une famille d'ouvertures dans un fichier. */
+function collectOpenings(source, file, re, kind, out) {
+	re.lastIndex = 0;
+	let m;
+	while ((m = re.exec(source)) !== null) {
+		const what = kind === "bypass-option" ? "" : openingName(source, m.index);
+		out.push({
+			kind,
+			what,
+			file
+		});
+	}
+}
+/**
+* Réécrit un chemin en séparateurs `/`, quelle que soit sa grammaire d'origine.
+*
+* 🔴 **Axiome 2 : normaliser AVANT de filtrer ou comparer.** Une exception de
+* dialecte est un chemin qui VOYAGE — elle vient de la configuration du projet,
+* écrite une fois et lue sur les trois systèmes, donc en `/`. Le chemin auquel
+* on la compare sort de `path.relative` : sous Windows il porte des `\`. Le
+* filtre ne mordait donc jamais là-bas, et une divergence pourtant DÉCLARÉE
+* par le projet était accusée — forge Windows rouge, même passe verte ailleurs.
+*
+* Les DEUX séparateurs sont traités, pas seulement celui du poste : rien ne dit
+* que l'exception n'a pas été écrite avec la grammaire de la machine où elle a
+* été ajoutée.
+*
+* @param rawPath - le chemin à normaliser.
+* @param sep - la grammaire à appliquer ; injectée pour que la règle
+*   s'éprouve avec `path.win32.sep` depuis n'importe quel système — sans elle,
+*   le cas Windows ne serait vérifiable que sous Windows.
+* @returns le même chemin, en `/`.
+*/
+function toPortablePath(rawPath, sep = path.sep) {
+	return rawPath.split(sep).join("/").split("\\").join("/");
+}
+/**
+* Relève la surface ouverte et les entités hors dialecte.
+*
+* @param options - cibles, racine du projet, environnement, exceptions.
+* @returns l'inventaire, les manquements, et ce qui a été parcouru.
+*/
+function checkSurface(options) {
+	const { roots, cwd, projectRoot, env } = options;
+	const exceptions = (options.dialectExceptions ?? []).map((e) => toPortablePath(e));
+	const findings = [];
+	const openings = [];
+	let scanned = 0;
+	let entitiesScanned = 0;
+	const read = (file) => {
+		try {
+			return readFileSync(file, "utf8");
+		} catch {
+			return "";
+		}
+	};
+	const manifestPath = projectRoot ? path.join(projectRoot, "nodefony.config.ts") : "";
+	const manifest = manifestPath ? read(manifestPath) : "";
+	for (const zone of publicAreas(manifest)) {
+		openings.push({
+			kind: "public-area",
+			what: zone.pattern,
+			file: path.relative(cwd, manifestPath)
+		});
+		if (!coversEverything(zone.pattern)) continue;
+		findings.push({
+			kind: "public-area-covers-all",
+			file: path.relative(cwd, manifestPath),
+			message: `la zone "${zone.pattern}" est publique (security: false) et couvre TOUT l'espace : aucune route de l'application n'est protégée, et une route ajoutée demain naîtra publique sans qu'aucun test ne le voie`
+		});
+	}
+	const { dialect, from } = connectorDialect(manifest, env);
+	const seen = /* @__PURE__ */ new Set();
+	for (const root of roots) {
+		if (!statSync(root, { throwIfNoEntry: false })) continue;
+		for (const file of sources(root)) {
+			if (seen.has(file)) continue;
+			seen.add(file);
+			const raw = read(file);
+			if (!raw) continue;
+			scanned++;
+			const relative = path.relative(cwd, file);
+			const clean = withoutComments(raw);
+			if (CONTROLLER_RE.test(clean)) {
+				collectOpenings(clean, relative, BYPASS_RE, "bypass-firewall", openings);
+				collectOpenings(clean, relative, ANONYMOUS_RE, "anonymous", openings);
+				collectOpenings(clean, relative, BYPASS_OPTION_RE, "bypass-option", openings);
+			}
+			if (!file.includes(ENTITY_DIR)) continue;
+			DRIZZLE_CORE_RE.lastIndex = 0;
+			const imported = /* @__PURE__ */ new Set();
+			let m;
+			while ((m = DRIZZLE_CORE_RE.exec(clean)) !== null) {
+				const found = DIALECT_OF_IMPORT[m[1] ?? ""];
+				if (found) imported.add(found);
+			}
+			if (imported.size === 0) continue;
+			entitiesScanned++;
+			if (!dialect) continue;
+			if (imported.has(dialect)) continue;
+			if (exceptions.some((e) => toPortablePath(relative).includes(e))) continue;
+			const wrote = [...imported].join(", ");
+			findings.push({
+				kind: "entity-other-dialect",
+				file: relative,
+				message: `cette entité est écrite pour ${wrote}, alors que le connecteur est ${dialect} (${from}) — l'outil de migration l'ÉCARTE en silence, la table ne sera jamais créée, et la première requête répondra 500`
+			});
+		}
+	}
+	return {
+		findings,
+		openings,
+		scanned,
+		dialect,
+		dialectFrom: from,
+		entitiesScanned
+	};
+}
+//#endregion
+export { balancedBlock, checkSurface, connectorDialect, coversEverything, publicAreas, toPortablePath };

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

@@ -0,0 +1,100 @@
+import { readdirSync, statSync } from "node:fs";
+import path from "node:path";
+//#region src/kernel/checks/walk.ts
+/**
+* Le parcours de fichiers de `doctor` — UNE règle d'exclusion, pour tous les
+* contrôles.
+*
+* 🔴 Elle était écrite QUATRE fois. Ce qu'un contrôle sautait, un autre
+* l'inspectait : `surface` ignorait neuf dossiers, `wiring` et `packageDeps`
+* trois chacun (recopiés à l'identique, donc voués à diverger au premier
+* ajout), et `freshness` exprimait la sienne en motifs de chemin. Elle avait
+* déjà divergé — la fraîcheur du build comptait les fichiers de test, que la
+* surface excluait depuis toujours, et réclamait un `npm run build` après
+* chaque test écrit.
+*
+* Ce qui reste PROPRE à un contrôle s'exprime en paramètre, jamais en seconde
+* liste : un test est de la surface non servie pour l'un, une source non bâtie
+* pour l'autre — c'est la même exclusion, motivée différemment.
+*
+* @module
+*/
+/**
+* Les dossiers dans lesquels aucun contrôle n'entre.
+*
+* Trois familles, et chacune a son motif : ce qui est INSTALLÉ
+* (`node_modules`), ce qui est PRODUIT (`dist`, `coverage`, `.turbo`, `tmp`,
+* `var`), et ce qui n'est ni servi ni publié (`tests`, `test`, `__tests__`).
+* Tout dossier commençant par un point est écarté en plus, par
+* {@link isSkippedDir}.
+*/
+const SKIPPED_DIRS = /* @__PURE__ */ new Set([
+	"node_modules",
+	"dist",
+	"coverage",
+	".turbo",
+	"tmp",
+	"var",
+	"tests",
+	"__tests__"
+]);
+/**
+* Ce dossier est-il hors de portée de tout contrôle ?
+*
+* @param name - le nom du dossier, sans son chemin.
+* @returns `true` s'il ne faut pas y entrer.
+*/
+function isSkippedDir(name) {
+	return SKIPPED_DIRS.has(name) || name.startsWith(".");
+}
+/**
+* Ce fichier est-il un test ?
+*
+* Reconnaît `x.test.ts` et `x.spec.ts`, dans toutes les extensions de source.
+* Un test n'est ni servi, ni publié, ni bâti : aucun contrôle n'a de raison de
+* le compter, et chacun en avait sa propre définition.
+*
+* @param name - le nom du fichier, ou un chemin.
+* @returns `true` s'il s'agit d'un test.
+*/
+function isTestFile(name) {
+	return /\.(test|spec)\.[cm]?tsx?$/u.test(name);
+}
+/**
+* Les fichiers de source d'une cible, tests et dossiers produits exclus.
+*
+* @param root - racine à explorer.
+* @param options - extensions retenues, et ce qui restreint le parcours.
+* @returns les chemins absolus, dans l'ordre du système de fichiers.
+*/
+function collectSources(root, options) {
+	const found = [];
+	const max = options.maxDepth ?? Number.POSITIVE_INFINITY;
+	const walk = (dir, depth) => {
+		if (depth > max) return;
+		let entries;
+		try {
+			entries = readdirSync(dir, { withFileTypes: true });
+		} catch {
+			return;
+		}
+		for (const entry of entries) {
+			if (entry.name.startsWith(".")) continue;
+			const full = path.join(dir, entry.name);
+			if (entry.isDirectory()) {
+				if (!isSkippedDir(entry.name)) walk(full, depth + 1);
+			} else if (options.extensions.includes(path.extname(entry.name)) && !isTestFile(entry.name)) found.push(full);
+		}
+	};
+	if (options.subdirs) {
+		for (const sub of options.subdirs) {
+			const dir = path.join(root, sub);
+			if (statSync(dir, { throwIfNoEntry: false })) walk(dir, 0);
+		}
+		return found;
+	}
+	walk(root, 0);
+	return found;
+}
+//#endregion
+export { SKIPPED_DIRS, collectSources, isSkippedDir, isTestFile };