@nodefony/documentation 10.0.0-alpha.1

package/dist/nodefony/service/DocumentationService.js

@@ -0,0 +1,421 @@
+import { metaList, metaString, parseFrontmatter } from "../src/frontmatter.js";
+import { isSafeSlug } from "../src/slug.js";
+import { scanDocsDir } from "../src/docScanner.js";
+import { rewriteInternalLinks } from "../src/linkResolver.js";
+import { searchDocs, splitSearchTerms } from "../src/search.js";
+import { DocNotFoundError, DocUnsafeSlugError } from "../src/errors/DocumentationError.js";
+import { GitService, Service, stripTrailingSlashes } from "nodefony";
+import { readFile } from "node:fs/promises";
+import { readdirSync, realpathSync, statSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+//#region nodefony/service/DocumentationService.ts
+const serviceName = "documentation";
+/** Personas connues — descriptions affichées par le sélecteur de vue Studio. */
+const AUDIENCES = [
+	{
+		key: "developer",
+		label: "Développeur",
+		desc: "Doc technique : architecture, contrats, API internes."
+	},
+	{
+		key: "devops",
+		label: "DevOps",
+		desc: "Déploiement, cluster, scaling, backplane (fond de panier)."
+	},
+	{
+		key: "supervisor",
+		label: "Superviseur",
+		desc: "Observabilité : santé, métriques temps réel, alertes."
+	},
+	{
+		key: "admin",
+		label: "Admin",
+		desc: "Accès à toute la documentation."
+	}
+];
+const VALID_AUDIENCES = new Set(AUDIENCES.map((a) => a.key));
+const VALID_STATUS = /* @__PURE__ */ new Set([
+	"stable",
+	"draft",
+	"temporary",
+	"experimental",
+	"deprecated"
+]);
+/**
+* Les groupes racine publiés, **dans l'ordre du menu**, avec leur libellé.
+*
+* L'ordre est PÉDAGOGIQUE, jamais alphabétique, et il part du geste : on fait une
+* première fois en étant guidé (tutoriels), on refait seul sur un besoin précis
+* (guides), puis on comprend ce qui se passait dessous (architecture). Un tri
+* alphabétique mettait « ADR » en tête et « Tutoriels » en cinquième position —
+* l'inverse exact du chemin de lecture.
+*
+* ⚠️ **C'est la SEULE définition de ce périmètre.** Le générateur du site public
+* (`scripts/build-docs-site.mjs`) l'importe depuis le `dist` de ce module — il en
+* importait déjà les briques de scan — au lieu d'en tenir une copie. Une copie a
+* existé ici, sous le prétexte d'une frontière de paquets que le script
+* franchissait pourtant déjà ; elle avait commencé à diverger. N'en réintroduire
+* aucune : le portail et le site doivent publier les MÊMES sections, sinon un
+* lecteur trouve dans l'un ce que l'autre lui cache.
+*/
+const ROOT_GROUPS = [
+	{
+		group: "tutoriels",
+		label: "Tutoriels"
+	},
+	{
+		group: "guides",
+		label: "Guides"
+	},
+	{
+		group: "architecture",
+		label: "Architecture"
+	}
+];
+/**
+* Pages de `docs/` (à la racine, hors sous-dossier) publiées dans le menu, dans
+* cet ordre. Le reste de ce dossier est du PILOTAGE — carte des phases, README du
+* corpus, essai sur l'outillage : utile au mainteneur du framework, illisible
+* pour qui construit une application.
+*
+* Comme {@link ROOT_GROUPS}, c'est la seule définition : le site public l'importe.
+*/
+const ROOT_PAGES = [
+	"index",
+	"demarrer",
+	"lexique"
+];
+/** Libellé du groupe qui porte les pages de `docs/` elles-mêmes. */
+const ROOT_PAGES_LABEL = "Pour commencer";
+/**
+* Service de documentation Nodefony — **headless** : produit l'index transverse
+* et le contenu résolu des pages, sans rendre aucun HTML (le front Studio, un
+* générateur statique ou le RAG le consomment).
+*
+* Sources scannées (config `scan`) : le dossier `docs/` racine (transverse) +
+* les `<module>/docs/*.md` co-localisés (ADR-0001) si `includeModules`.
+*
+* Perf/mémoire (règle absolue) : tout est lazy. L'index est construit au 1ᵉʳ
+* accès et caché avec un TTL (`cache.ttlMs`) — le scan FS n'est PAS refait à
+* chaque requête. Le registre de variables `{{ }}` est alloué au 1ᵉʳ
+* `registerVar`. 0 alloc par requête hors la lecture froide d'une page (chemin
+* admin, pas le hot path applicatif).
+*/
+var DocumentationService = class extends Service {
+	module;
+	/** Snapshot caché (index + arbre) — `null` tant qu'aucun scan. */
+	#cache = null;
+	/** Fournisseurs de variables `{{ }}` — `null` tant qu'aucun enregistré. */
+	#vars = null;
+	constructor(module) {
+		super(serviceName, module.container, null, module.options ?? {});
+		this.module = module;
+	}
+	log(pci, severity, msgid, msg) {
+		if (!msgid) msgid = `\x1b[36mDOCUMENTATION\x1b[0m`;
+		return super.log(pci, severity, msgid, msg);
+	}
+	/** Config validée du module (réassignée à `module.options` au onKernelRegister). */
+	#config() {
+		return this.module.options;
+	}
+	/** Racine du projet (où vit `docs/` transverse). */
+	#projectRoot() {
+		return this.kernel?.path ?? process.cwd();
+	}
+	registerVar(name, provider) {
+		if (this.#vars === null) this.#vars = /* @__PURE__ */ new Map();
+		this.#vars.set(name, provider);
+	}
+	invalidate() {
+		this.#cache = null;
+	}
+	async getTree() {
+		return (await this.#ensureCache()).tree;
+	}
+	/**
+	* Cherche `query` dans le corpus — titres ET corps — et rend des EXTRAITS.
+	*
+	* Pourquoi une recherche à part, et pas un filtre de l'arbre : filtrer le menu
+	* ne répond qu'à « quelle page s'appelle ainsi ? ». La question réelle est
+	* « où est-ce expliqué ? », dont la réponse est dans le CORPS des pages. Une
+	* recherche qui ne lit que les titres laisse croire qu'un sujet n'est pas
+	* documenté alors qu'il l'est, dans une page dont le nom ne le dit pas.
+	*
+	* Tout est borné : le nombre de pages rendues, le nombre d'extraits par page,
+	* la longueur d'un extrait. Le total AVANT bornage est rendu à part
+	* (`matched`), pour que « 20 résultats » ne se lise pas comme « il n'y en a
+	* que 20 ».
+	*
+	* @param query - la saisie brute de l'utilisateur.
+	* @param limit - nombre maximal de pages rendues (défaut 20).
+	* @returns les pages retenues, leurs extraits, et ce qui a été balayé.
+	*/
+	async search(query, limit = 20) {
+		if (splitSearchTerms(query).length === 0) return {
+			query,
+			terms: [],
+			scanned: 0,
+			matched: 0,
+			hits: []
+		};
+		const { tree, index } = await this.#ensureCache();
+		const sectionOf = /* @__PURE__ */ new Map();
+		for (const s of tree.sections) for (const p of s.pages) sectionOf.set(p.slug, s.label);
+		const corpus = [];
+		for (const doc of index.values()) {
+			const sectionLabel = sectionOf.get(doc.slug);
+			if (sectionLabel === void 0) continue;
+			let raw;
+			try {
+				raw = await readFile(doc.absPath, "utf8");
+			} catch {
+				continue;
+			}
+			const { body } = parseFrontmatter(raw);
+			corpus.push({
+				slug: doc.slug,
+				title: doc.title,
+				navTitle: doc.navTitle,
+				sectionLabel,
+				body
+			});
+		}
+		return searchDocs(corpus, query, limit);
+	}
+	async getPage(slug) {
+		if (!isSafeSlug(slug)) throw new DocUnsafeSlugError(slug);
+		const { index, byPath } = await this.#ensureCache();
+		const doc = index.get(slug);
+		if (!doc) throw new DocNotFoundError(slug);
+		const raw = await readFile(doc.absPath, "utf8");
+		const { meta, body } = parseFrontmatter(raw);
+		const repoRel = relative(this.#projectRoot(), doc.absPath).replace(/\\/g, "/");
+		const source = metaString(meta, "source") ?? repoRel;
+		return {
+			slug: doc.slug,
+			title: metaString(meta, "title") ?? doc.title,
+			version: metaString(meta, "version") ?? "doc",
+			status: this.#coerceStatus(metaString(meta, "status")),
+			updated: metaString(meta, "updated"),
+			source,
+			sourceUrl: this.#buildSourceUrl(source),
+			markdown: this.#resolveLinks(this.#resolveVars(body), doc, byPath)
+		};
+	}
+	/**
+	* Traduit les liens internes de la page en slugs navigables.
+	*
+	* Les pages se lient par chemin relatif (lisible sur GitHub et dans l'éditeur) ;
+	* le portail navigue par slug. Seul le serveur connaît la table chemin → slug,
+	* donc la traduction se fait ici — sans quoi toute remontée (`../index.md`)
+	* arrive au client comme une ancre morte.
+	*/
+	#resolveLinks(markdown, from, byPath) {
+		const root = this.#projectRoot();
+		const fromDir = relative(root, dirname(from.absPath)).replace(/\\/g, "/");
+		return rewriteInternalLinks(markdown, {
+			fromDir,
+			toSlug: (repoRel) => byPath.get(repoRel)
+		});
+	}
+	/** Sert le cache si frais (TTL), sinon rescanne et reconstruit l'arbre. */
+	async #ensureCache() {
+		const ttl = this.#config().cache.ttlMs;
+		const now = Date.now();
+		if (this.#cache && ttl > 0 && now - this.#cache.at < ttl) return this.#cache;
+		const docs = await this.#scanAll();
+		const index = /* @__PURE__ */ new Map();
+		const byPath = /* @__PURE__ */ new Map();
+		const root = this.#projectRoot();
+		for (const d of docs) {
+			index.set(d.slug, d);
+			byPath.set(relative(root, d.absPath).replace(/\\/g, "/"), d.slug);
+		}
+		const tree = {
+			generatedAt: new Date(now).toISOString(),
+			audiences: [...AUDIENCES],
+			sections: this.#buildSections(docs)
+		};
+		this.#cache = {
+			at: now,
+			tree,
+			index,
+			byPath
+		};
+		return this.#cache;
+	}
+	/** Scanne la racine + (si activé) les `<module>/docs/` de chaque module. */
+	async #scanAll() {
+		const cfg = this.#config();
+		const exclude = cfg.scan.exclude;
+		const root = this.#projectRoot();
+		const out = [];
+		out.push(...await scanDocsDir(join(root, cfg.scan.rootDir), { kind: "root" }, exclude));
+		if (cfg.scan.includeModules) {
+			const modules = this.kernel?.getModules?.() ?? {};
+			const scans = Object.values(modules).filter((m) => m && !m.isApp && m.path).map((m) => scanDocsDir(join(m.path, "docs"), {
+				kind: "module",
+				module: m.name
+			}, exclude));
+			for (const docs of await Promise.all(scans)) out.push(...docs);
+		}
+		if (cfg.scan.includeInstalled) {
+			const seen = new Set(out.filter((d) => d.source.kind === "module").map((d) => d.source.module));
+			for (const [name, dir] of this.#installedDocDirs(root)) {
+				if (seen.has(name)) continue;
+				out.push(...await scanDocsDir(dir, {
+					kind: "module",
+					module: name
+				}, exclude));
+			}
+		}
+		return out;
+	}
+	/**
+	* Dossiers `docs/` des paquets Nodefony **installés** (chargés ou non).
+	*
+	* Un module qu'on n'a pas encore activé est justement celui dont on lit la doc
+	* — sans ça, le portail renvoie dans le vide sur `redis`, `mongoose`… tant
+	* qu'ils ne sont pas dans le manifeste.
+	*
+	* Les chemins sont résolus en **real-path** : en dépôt workspace,
+	* `node_modules/@nodefony/x` est un lien vers `src/packages/@nodefony/x`, et
+	* c'est la source qui doit indexer (sinon les liens entre pages ne se
+	* résolvent pas — deux chemins pour un même fichier).
+	*/
+	#installedDocDirs(root) {
+		const found = /* @__PURE__ */ new Map();
+		const add = (name, dir) => {
+			try {
+				if (!statSync(dir).isDirectory()) return;
+				found.set(name, realpathSync(dir));
+			} catch {}
+		};
+		add("nodefony", join(root, "node_modules/nodefony/docs"));
+		const scope = join(root, "node_modules/@nodefony");
+		let entries = [];
+		try {
+			entries = readdirSync(scope);
+		} catch {
+			return found;
+		}
+		for (const pkg of entries) add(pkg, join(scope, pkg, "docs"));
+		return found;
+	}
+	/** Regroupe les docs scannés en sections (racine par dossier, module par module). */
+	#buildSections(docs) {
+		const rootGroups = /* @__PURE__ */ new Map();
+		const moduleGroups = /* @__PURE__ */ new Map();
+		for (const d of docs) if (d.source.kind === "root") (rootGroups.get(d.group) ?? setGet(rootGroups, d.group)).push(d);
+		else {
+			const key = d.source.module;
+			(moduleGroups.get(key) ?? setGet(moduleGroups, key)).push(d);
+		}
+		const rootDocs = (rootGroups.get("racine") ?? []).filter((d) => ROOT_PAGES.includes(d.relPath.replace(/\.md$/i, "")));
+		const gettingStarted = rootDocs.length ? [{
+			id: "root-pour-commencer",
+			label: ROOT_PAGES_LABEL,
+			pages: ROOT_PAGES.map((n) => rootDocs.find((d) => d.relPath.replace(/\.md$/i, "") === n)).filter((d) => Boolean(d)).map((d) => this.#toPageRef(d))
+		}] : [];
+		const rootSections = ROOT_GROUPS.map(({ group, label }) => {
+			const pages = rootGroups.get(group);
+			return pages?.length ? {
+				id: `root-${group.replace(/\//g, "~")}`,
+				label,
+				pages: this.#orderPages(pages)
+			} : null;
+		}).filter((s) => s !== null);
+		const moduleSections = [...moduleGroups.entries()].sort(([a], [b]) => {
+			if (a === b) return 0;
+			if (a === "nodefony") return -1;
+			if (b === "nodefony") return 1;
+			return a.localeCompare(b);
+		}).map(([mod, pages]) => ({
+			id: `mod-${mod}`,
+			label: mod === "nodefony" ? "Cœur" : mod,
+			module: mod,
+			pages: this.#orderPages(pages)
+		}));
+		return [
+			...gettingStarted,
+			...rootSections,
+			...moduleSections
+		];
+	}
+	/**
+	* Ordonne les pages d'une section : le **hub en premier**, le reste ensuite.
+	*
+	* Un `index.md` trié alphabétiquement atterrit au milieu de ses propres pages
+	* (entre `headers` et `lexique` pour la sécurité) — le point d'entrée devient
+	* alors invisible. Le hub ouvre sa section ; c'est le chemin de lecture normal.
+	*/
+	#orderPages(pages) {
+		const refs = pages.map((p) => this.#toPageRef(p));
+		if (!refs.some((r) => r.isHub)) {
+			const readme = pages.findIndex((p) => /(^|\/)readme\.md$/i.test(p.relPath));
+			if (readme !== -1) refs[readme].isHub = true;
+		}
+		return refs.sort((a, b) => {
+			if (a.isHub !== b.isHub) return a.isHub ? -1 : 1;
+			return a.navTitle.localeCompare(b.navTitle);
+		});
+	}
+	/** Convertit un doc scanné en référence d'arbre (métadonnées seules). */
+	#toPageRef(d) {
+		const audience = metaList(d.meta, "audience").filter((a) => VALID_AUDIENCES.has(a));
+		const isHub = /(^|\/)index\.md$/i.test(d.relPath);
+		const ref = {
+			slug: d.slug,
+			title: d.title,
+			navTitle: d.navTitle,
+			audience,
+			isHub
+		};
+		const version = metaString(d.meta, "version");
+		if (version) ref.version = version;
+		const status = this.#coerceStatus(metaString(d.meta, "status"));
+		if (status) ref.status = status;
+		return ref;
+	}
+	/** Restreint une valeur libre au type `DocStatus` (sinon `undefined`). */
+	#coerceStatus(value) {
+		return value && VALID_STATUS.has(value) ? value : void 0;
+	}
+	/**
+	* Remplace les variables `{{ name }}` par la valeur de leur fournisseur
+	* enregistré. Variable inconnue → laissée telle quelle (signale à l'auteur
+	* qu'il manque un provider, plutôt que de masquer silencieusement).
+	*/
+	#resolveVars(markdown) {
+		if (this.#vars === null || this.#vars.size === 0) return markdown;
+		const vars = this.#vars;
+		return markdown.replace(/\{\{\s*([\w.-]+)\s*\}\}/g, (whole, name) => {
+			const provider = vars.get(name);
+			if (!provider) return whole;
+			try {
+				return provider();
+			} catch {
+				return whole;
+			}
+		});
+	}
+	/**
+	* Construit le lien « Modifier sur GitHub » d'une page à partir d'un chemin
+	* RELATIF au repo. Branche = config explicite, sinon branche git réelle
+	* (`GitService`), sinon `main`. N'expose jamais de chemin FS absolu.
+	*/
+	#buildSourceUrl(repoRelPath) {
+		const repo = this.#config().repo;
+		const branch = repo.branch ?? (GitService.branch(this.#projectRoot()) || "main");
+		return `${stripTrailingSlashes(repo.url)}/${repo.editPathPrefix}/${branch}/${repoRelPath}`;
+	}
+};
+/** Crée et insère une liste vide dans une Map, et la retourne (helper groupBy). */
+function setGet(map, key) {
+	const arr = [];
+	map.set(key, arr);
+	return arr;
+}
+//#endregion
+export { ROOT_GROUPS, ROOT_PAGES, DocumentationService as default };

package/dist/nodefony/src/docScanner.js

@@ -0,0 +1,58 @@
+import { metaString, parseFrontmatter } from "./frontmatter.js";
+import { pathToSlug } from "./slug.js";
+import { readFile, readdir } from "node:fs/promises";
+import { join } from "node:path";
+//#region nodefony/src/docScanner.ts
+/** `01-vue-ensemble.md` → `Vue Ensemble` (retire préfixe numérique + sépare). */
+function humanizeFilename(base) {
+	return base.replace(/\.md$/i, "").replace(/^\d+[-_]/, "").replace(/[-_]/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+}
+/** `true` si un chemin relatif contient un segment exclu (ex. `node_modules`). */
+function isExcluded(relPath, exclude) {
+	return relPath.split(/[/\\]/).some((seg) => exclude.includes(seg));
+}
+/**
+* Scanne récursivement un dossier de docs et retourne les fichiers `.md`
+* trouvés, frontmatter lu, triés par chemin relatif.
+*
+* Best-effort : un dossier absent (`ENOENT`) renvoie `[]` (pas d'erreur) ; un
+* fichier illisible garde son titre humanisé (frontmatter ignoré).
+*
+* @param baseDir - dossier racine à scanner (absolu).
+* @param source - origine taguée sur chaque doc (racine ou module).
+* @param exclude - noms de segments de chemin à ignorer.
+* @returns liste des docs trouvés (vide si dossier absent).
+*/
+async function scanDocsDir(baseDir, source, exclude = []) {
+	let entries;
+	try {
+		entries = await readdir(baseDir, { recursive: true });
+	} catch {
+		return [];
+	}
+	const mdFiles = entries.filter((rel) => rel.toLowerCase().endsWith(".md") && !isExcluded(rel, exclude));
+	return (await Promise.all(mdFiles.map(async (rel) => {
+		const relPosix = rel.replace(/\\/g, "/");
+		const parts = relPosix.split("/");
+		const base = parts[parts.length - 1];
+		const group = parts.slice(0, -1).join("/") || "racine";
+		const absPath = join(baseDir, rel);
+		let meta = {};
+		try {
+			const raw = await readFile(absPath, "utf8");
+			meta = parseFrontmatter(raw).meta;
+		} catch {}
+		return {
+			slug: pathToSlug(source, relPosix),
+			relPath: relPosix,
+			absPath,
+			source,
+			group,
+			meta,
+			title: metaString(meta, "title") ?? humanizeFilename(base),
+			navTitle: metaString(meta, "navTitle") ?? metaString(meta, "title") ?? humanizeFilename(base)
+		};
+	}))).sort((a, b) => a.relPath.localeCompare(b.relPath));
+}
+//#endregion
+export { scanDocsDir };

package/dist/nodefony/src/errors/DocumentationError.js

@@ -0,0 +1,45 @@
+import { nodefonyError } from "nodefony";
+//#region nodefony/src/errors/DocumentationError.ts
+/**
+* Erreur typée du module `@nodefony/documentation`.
+*
+* Étend `nodefonyError` (le wrapper d'erreur du core, renommé pour ne pas
+* entrer en collision avec `globalThis.Error`). Porte un `code` machine stable
+* pour que le data plane distingue les cas sans parser le message (Zero Trust :
+* le message détaillé reste serveur, le client ne voit qu'un code + un message
+* générique).
+*/
+var DocumentationError = class extends nodefonyError {
+	/**
+	* Code machine stable (ex. `DOC_NOT_FOUND`, `DOC_UNSAFE_SLUG`).
+	*
+	* Nommé `docCode` (pas `code`) : `nodefonyError` réserve déjà `code?: number`
+	* (statut HTTP). On ne shadow pas un champ numérique du parent par un string.
+	*/
+	docCode;
+	constructor(message, docCode = "DOC_ERROR") {
+		super(message);
+		this.name = "DocumentationError";
+		this.docCode = docCode;
+	}
+};
+/** Slug demandé absent de l'allowlist construite par le scan (404 logique). */
+var DocNotFoundError = class extends DocumentationError {
+	constructor(slug) {
+		super(`Document inconnu : "${slug}"`, "DOC_NOT_FOUND");
+		this.name = "DocNotFoundError";
+	}
+};
+/**
+* Slug rejeté car potentiellement dangereux (traversée de répertoire, segment
+* `..`, caractère hors charset). Sécurité : on ne touche JAMAIS au FS avec un
+* tel slug.
+*/
+var DocUnsafeSlugError = class extends DocumentationError {
+	constructor(slug) {
+		super(`Slug rejeté (non sûr) : "${slug}"`, "DOC_UNSAFE_SLUG");
+		this.name = "DocUnsafeSlugError";
+	}
+};
+//#endregion
+export { DocNotFoundError, DocUnsafeSlugError, DocumentationError };

package/dist/nodefony/src/frontmatter.js

@@ -0,0 +1,63 @@
+//#region nodefony/src/frontmatter.ts
+/** Retire une paire de quotes simples ou doubles entourant la valeur. */
+function unquote(value) {
+	return value.replace(/^["']|["']$/g, "");
+}
+/** Parse une liste inline `[a, "b", c]` → `["a","b","c"]` (vide → `[]`). */
+function parseInlineList(raw) {
+	const inner = raw.slice(1, -1).trim();
+	if (inner === "") return [];
+	return inner.split(",").map((s) => unquote(s.trim())).filter((s) => s !== "");
+}
+/**
+* Sépare le bloc frontmatter du corps markdown et parse les métadonnées.
+*
+* @param raw - contenu brut du fichier `.md`.
+* @returns `{ meta, body }` — `meta` vide et `body = raw` s'il n'y a pas de bloc.
+*/
+function parseFrontmatter(raw) {
+	const m = /^?\s*---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/.exec(raw);
+	if (!m) return {
+		meta: {},
+		body: raw
+	};
+	const meta = {};
+	const lines = m[1].split(/\r?\n/);
+	for (let i = 0; i < lines.length; i++) {
+		const line = lines[i];
+		if (line.trim() === "" || line.trim().startsWith("#")) continue;
+		const kv = /^([A-Za-z][\w-]*)\s*:\s*(.*)$/.exec(line);
+		if (!kv) continue;
+		const key = kv[1];
+		const value = kv[2].trim();
+		if (value === "") {
+			const items = [];
+			while (i + 1 < lines.length && /^\s*-\s+/.test(lines[i + 1])) items.push(unquote(lines[++i].replace(/^\s*-\s+/, "").trim()));
+			meta[key] = items;
+			continue;
+		}
+		if (value.startsWith("[") && value.endsWith("]")) {
+			meta[key] = parseInlineList(value);
+			continue;
+		}
+		meta[key] = unquote(value);
+	}
+	return {
+		meta,
+		body: m[2]
+	};
+}
+/** Lit une clé de frontmatter en string (1er élément si liste), ou `undefined`. */
+function metaString(meta, key) {
+	const v = meta[key];
+	if (Array.isArray(v)) return v[0];
+	return v;
+}
+/** Lit une clé de frontmatter en string[] (wrappe un scalaire), ou `[]`. */
+function metaList(meta, key) {
+	const v = meta[key];
+	if (v === void 0) return [];
+	return Array.isArray(v) ? v : [v];
+}
+//#endregion
+export { metaList, metaString, parseFrontmatter };

package/dist/nodefony/src/linkResolver.js

@@ -0,0 +1,68 @@
+//#region nodefony/src/linkResolver.ts
+/**
+* Réécriture des liens internes d'une page de doc en **slugs**.
+*
+* Une page vit sur le disque et lie ses voisines par chemin relatif — c'est ce
+* qui la rend lisible sur GitHub et dans un éditeur : `[CORS](cors.md)`,
+* `[Documentation](../../../../../docs/index.md)`. Mais le portail ne navigue
+* pas par chemin : il navigue par **slug** (`mod~security~cors`), parce qu'un
+* slug est une clé d'allowlist et jamais un chemin FS (anti-traversée, cf
+* {@link ../src/slug}).
+*
+* Sans traduction, seuls les liens PLATS fonctionnaient dans Studio : toute
+* remontée (`../index.md`) tombait en ancre HTML morte. La résolution appartient
+* au serveur, seul à connaître la table chemin → slug ; le client n'a aucun
+* moyen de deviner à quel fichier `../../..` correspond.
+*
+* Le lien conserve l'extension `.md` après réécriture (`mod~security~cors.md`) :
+* le rendu markdown reconnaît un lien interne à cette extension, et un slug
+* seul serait indistinguable d'une URL relative quelconque.
+*/
+/**
+* Liens markdown `[texte](cible)` — on ne touche QUE les cibles `.md`.
+* Exclus : URL absolues (`http:`, `mailto:`), ancres pures (`#section`), et
+* tout ce qui n'est pas un fichier markdown.
+*/
+const MD_LINK = /\]\((?!https?:|mailto:|#)([^)\s]{1,512}?\.md)(#[^)\s]{0,512})?\)/gi;
+/**
+* Cible d'un bloc déclaratif : `"href": "../x.md"` dans un JSON de fence typée
+* (`nodefony-cards`…). Même règle que les liens markdown — seules les cibles
+* `.md` internes sont traduites.
+*/
+const JSON_HREF = /"href"\s*:\s*"(?!https?:|mailto:|#)([^"\s]{1,512}?\.md)"/gi;
+/** Résout un chemin relatif POSIX contre le dossier d'une page. */
+function resolveRelative(fromDir, href) {
+	const out = [...href.startsWith("/") ? [] : fromDir.split("/").filter(Boolean)];
+	for (const seg of href.split("/")) {
+		if (seg === "" || seg === ".") continue;
+		if (seg === "..") out.pop();
+		else out.push(seg);
+	}
+	return out.join("/");
+}
+/**
+* Réécrit les liens markdown internes d'une page en slugs navigables.
+*
+* Un lien dont la cible n'est pas indexée est **laissé tel quel** : mieux vaut
+* un lien inerte qu'un slug inventé qui produirait un 404 côté portail.
+*
+* @param markdown - corps de la page (frontmatter déjà retiré).
+* @param options - dossier d'origine + résolution chemin → slug.
+* @returns le markdown avec ses liens internes traduits.
+*/
+function rewriteInternalLinks(markdown, options) {
+	const { fromDir, toSlug, suffix = ".md" } = options;
+	const translate = (href) => {
+		const slug = toSlug(resolveRelative(fromDir, href));
+		return slug ? `${slug}${suffix}` : null;
+	};
+	return markdown.replace(MD_LINK, (whole, href, hash = "") => {
+		const t = translate(href);
+		return t ? `](${t}${hash})` : whole;
+	}).replace(JSON_HREF, (whole, href) => {
+		const t = translate(href);
+		return t ? `"href": "${t}"` : whole;
+	});
+}
+//#endregion
+export { rewriteInternalLinks };