@nodefony/documentation 10.0.0-alpha.1

package/dist/nodefony/src/search.js

@@ -0,0 +1,120 @@
+//#region nodefony/src/search.ts
+/**
+* Réduit un texte à sa forme comparable : minuscules, accents retirés.
+*
+* « Sécurité » et « securite » doivent trouver la même chose — personne ne tape
+* les accents dans un champ de recherche.
+*/
+function foldText(text) {
+	return text.toLowerCase().normalize("NFD").replace(/[\u0300-\u036f]/g, "");
+}
+/** Termes effectivement cherchés : pliés, dédoublonnés, un caractère écarté. */
+function splitSearchTerms(query) {
+	return [...new Set(foldText(query).split(/\s+/).filter(Boolean))].filter((t) => t.length > 1);
+}
+/**
+* Prose INDEXABLE d'une page de documentation.
+*
+* Ce qui est retiré ne l'est pas par souci de taille mais de PERTINENCE : un
+* bloc de code fait remonter une page sur `const`, un tableau de compatibilité
+* sur n'importe quel nom de navigateur, et le fil d'Ariane sur le titre de
+* toutes ses voisines. Une recherche qui rend tout ne rend rien.
+*
+* @param markdown - le corps de la page, frontmatter déjà retiré.
+* @returns le texte à indexer, lignes conservées (les extraits s'y resituent).
+*/
+function extractSearchText(markdown) {
+	const out = [];
+	let inABlock = false;
+	for (const brute of markdown.split("\n")) {
+		if (/^\s*```/.test(brute)) {
+			inABlock = !inABlock;
+			continue;
+		}
+		if (inABlock) continue;
+		if (/^\s*(📍|!\[|<!--|<[a-z])/.test(brute)) continue;
+		if (/^\s*\|[\s|:-]+\|\s*$/.test(brute)) continue;
+		out.push(brute.replace(/[ \t]{2,}/g, " "));
+	}
+	return out.join("\n").replace(/\n{3,}/g, "\n\n");
+}
+/**
+* Classe les pages qui portent TOUS les termes, la plus pertinente d'abord.
+*
+* ⚠️ Cette fonction est SÉRIALISÉE et exécutée dans un navigateur (voir l'en-tête
+* du fichier) : elle ne doit rien référencer hors de son propre corps.
+*
+* @param docs - le corpus à balayer.
+* @param query - ce que le lecteur a tapé.
+* @param limit - nombre de résultats rendus (le total retenu est dit à part).
+* @returns le classement, plus ce que la recherche a réellement balayé.
+*/
+function searchDocs(docs, query, limit = 20) {
+	const fold = (text) => text.toLowerCase().normalize("NFD").replace(/[\u0300-\u036f]/g, "");
+	const terms = [...new Set(fold(query).split(/\s+/).filter(Boolean))].filter((t) => t.length > 1);
+	if (!terms.length) return {
+		query,
+		terms,
+		scanned: 0,
+		matched: 0,
+		hits: []
+	};
+	const hits = [];
+	let scanned = 0;
+	for (const doc of docs) {
+		scanned += 1;
+		const foldedTitle = fold(`${doc.title} ${doc.navTitle} ${doc.slug}`);
+		const lines = doc.body.split("\n");
+		const foldedLines = lines.map(fold);
+		const foldedBody = foldedLines.join("\n");
+		if (!terms.every((t) => foldedBody.includes(t) || foldedTitle.includes(t))) continue;
+		let occurrences = 0;
+		for (const t of terms) {
+			let i = foldedBody.indexOf(t);
+			while (i !== -1) {
+				occurrences += 1;
+				i = foldedBody.indexOf(t, i + t.length);
+			}
+		}
+		const excerpts = [];
+		let section;
+		for (let i = 0; i < lines.length && excerpts.length < 3; i += 1) {
+			const brute = lines[i] ?? "";
+			const heading = /^#{2,4}[ \t]+(\S.*)$/.exec(brute);
+			if (heading) {
+				section = heading[1]?.replace(/[*`_]/g, "").trim();
+				continue;
+			}
+			if (/^#\s/.test(brute)) continue;
+			if (/^\s*(📍|!\[|\||<!--|```)/.test(brute)) continue;
+			const folded = foldedLines[i] ?? "";
+			if (!terms.some((t) => folded.includes(t))) continue;
+			const lineText = brute.replace(/\[([^\][]*)\]\([^)[]*\)/g, "$1").replace(/^#{1,6}\s*/, "").replace(/[*`_>]/g, "").replace(/\s+/g, " ").trim();
+			if (lineText.length < 12) continue;
+			excerpts.push({
+				...section ? { section } : {},
+				text: lineText.length > 220 ? `${lineText.slice(0, 217)}…` : lineText
+			});
+		}
+		const inTitle = terms.filter((t) => foldedTitle.includes(t)).length;
+		hits.push({
+			slug: doc.slug,
+			title: doc.title,
+			navTitle: doc.navTitle,
+			sectionLabel: doc.sectionLabel,
+			excerpts,
+			occurrences,
+			score: inTitle * 100 + occurrences
+		});
+	}
+	hits.sort((a, b) => b.score - a.score || a.title.localeCompare(b.title));
+	return {
+		query,
+		terms,
+		scanned,
+		matched: hits.length,
+		hits: hits.slice(0, limit)
+	};
+}
+//#endregion
+export { extractSearchText, foldText, searchDocs, splitSearchTerms };

package/dist/nodefony/src/slug.js

@@ -0,0 +1,62 @@
+//#region nodefony/src/slug.ts
+/**
+* Sécurité et encodage des slugs de documentation.
+*
+* Le data plane LIT des fichiers `.md` sur disque → surface de **traversée de
+* répertoire** (path traversal). Règle de sécurité (cf
+* `feedback_security_rfc_rigor`) :
+*
+*  1. Le slug n'est JAMAIS concaténé brut dans un chemin FS. Le service garde,
+*     pour chaque fichier scanné, son chemin absolu RÉEL ; servir une page =
+*     retrouver l'entrée par **égalité de slug** dans la liste scannée, puis
+*     lire le chemin connu. Le slug est une CLÉ d'allowlist, pas un chemin.
+*  2. {@link isSafeSlug} est une garde **défense-en-profondeur** : on rejette
+*     tout slug suspect (segment `..`, séparateur de chemin, octet nul,
+*     caractère de contrôle) AVANT même de chercher dans l'allowlist.
+*
+* Schéma de slug (URL-safe, un seul segment de route) :
+*  - doc racine `docs/guides/session-storage.md` → `root~guides~session-storage`
+*  - doc module `<module>/docs/index.md`         → `mod~<module>~index`
+*
+* Le `/` du chemin devient `~` (le slug doit tenir dans UN segment de route
+* `/api/page/{slug}`). On NE reconstruit jamais le chemin depuis le slug.
+*/
+/** Caractères autorisés dans un slug : alphanum + `_` `-` `.` `~`. */
+const SAFE_SLUG = /^[A-Za-z0-9_.~-]+$/;
+/** Longueur maximale d'un slug (borne anti-abus, large mais finie). */
+const MAX_SLUG_LENGTH = 512;
+/**
+* Valide qu'un slug est sûr à manipuler (avant toute recherche/lecture).
+*
+* Rejette : chaîne vide, trop longue, segment `..`, présence de `/` `\` `\0`,
+* tout caractère hors charset autorisé.
+*
+* @param slug - slug brut reçu du client (déjà URL-décodé par le framework).
+* @returns `true` si le slug est sûr, `false` sinon.
+*/
+function isSafeSlug(slug) {
+	if (typeof slug !== "string") return false;
+	if (slug.length === 0 || slug.length > MAX_SLUG_LENGTH) return false;
+	if (slug.includes("\0")) return false;
+	if (!SAFE_SLUG.test(slug)) return false;
+	if (slug.split("~").some((seg) => seg === "..")) return false;
+	return true;
+}
+/**
+* Construit le slug d'un fichier à partir de sa source et de son chemin
+* relatif (POSIX, sans `.md`). Inverse jamais utilisé (slug = clé, pas chemin).
+*
+* @param source - racine ou module propriétaire.
+* @param relPath - chemin relatif POSIX du `.md` (séparateur `/`).
+* @returns slug URL-safe.
+*/
+function pathToSlug(source, relPath) {
+	const clean = relPath.replace(/\\/g, "/").replace(/\.md$/i, "").replace(/\//g, "~");
+	return source.kind === "root" ? `root~${clean}` : `mod~${sanitizeSegment(source.module)}~${clean}`;
+}
+/** Normalise un nom de module en segment de slug sûr (`@nodefony/x` → `x`). */
+function sanitizeSegment(name) {
+	return name.replace(/^@[^/]+\//, "").replace(/[^A-Za-z0-9_.-]/g, "-");
+}
+//#endregion
+export { isSafeSlug, pathToSlug };

package/dist/types/index.d.ts

@@ -0,0 +1,58 @@
+/**
+ * @nodefony/documentation — Data plane de documentation transverse de Nodefony.
+ *
+ * Module **headless** (back pur) : il indexe la documentation co-localisée
+ * (`docs/` racine transverse + `<module>/docs/*.md`, ADR-0001), résout les
+ * variables dynamiques `{{ }}` côté serveur, et expose le tout sous
+ * `/nodefony/documentation/api/*`. Il ne rend AUCUN HTML — le front Studio (et,
+ * demain, un générateur de site statique ou le RAG P12) consomme ce data plane.
+ *
+ * Pourquoi un module dédié (et pas un simple controller Studio) : la doc porte
+ * de l'**état** (index scanné, cache TTL, registre de providers `{{ }}`) → un
+ * cycle de vie propre, hors hot path request (tout lazy). Cf
+ * [[project_doc_portal_faisabilite]].
+ *
+ * Voir aussi : CLAUDE.md (décisions figées), MEMORY.md (internals IA),
+ * README.md (usage humain), docs/ (doc vulgarisée surfacée dans Studio).
+ */
+import { Kernel, Module } from "nodefony";
+import type { DocumentationConfig, DocumentationConfigInput } from "./nodefony/config/config.js";
+import DocumentationService from "./nodefony/service/DocumentationService.js";
+import DocumentationController from "./nodefony/controller/DocumentationController.js";
+declare module "nodefony" {
+    interface NodefonyModuleConfig {
+        "@nodefony/documentation": DocumentationConfigInput;
+    }
+}
+declare class Documentation extends Module<DocumentationConfig> {
+    /** Module optionnel : un échec de son boot ne tue jamais le process (résilience Ph.3). */
+    static critical: boolean;
+    constructor(kernel: Kernel);
+    /** JSON Schema de la config documentation → data plane admin (config riche Studio). */
+    configSchema(): unknown;
+    /**
+     * Phase `onRegister` : valide la config (défauts + override `module-documentation`
+     * + env) via `defineDocumentationConfig`, puis la ré-assigne à `this.options`
+     * AVANT l'instanciation du `@services` (phase `onBoot`). Plante propre avec
+     * messages clairs si la config est invalide (convention Zod figée 2026-05-28).
+     */
+    onKernelRegister(): Promise<this>;
+    /**
+     * Phase `onReady` : enregistre les fournisseurs de variables `{{ }}` built-in
+     * sur le service (tous les modules sont alors bootés). Sources SÛRES seulement
+     * (version, identité git) — jamais de secret ni de chemin FS absolu.
+     */
+    onKernelReady(): Promise<this>;
+}
+export default Documentation;
+export { DocumentationService, DocumentationController };
+export { ROOT_GROUPS, ROOT_PAGES, } from "./nodefony/service/DocumentationService.js";
+export { defineDocumentationConfig, documentationConfigJsonSchema, } from "./nodefony/config/defineModuleConfig.js";
+export { documentationConfigSchema, type DocumentationConfig, } from "./nodefony/config/config.js";
+export { parseFrontmatter, metaString, metaList, type Frontmatter, type ParsedDoc, } from "./nodefony/src/frontmatter.js";
+export { scanDocsDir, type ScannedDoc } from "./nodefony/src/docScanner.js";
+export { isSafeSlug, pathToSlug, type DocSource } from "./nodefony/src/slug.js";
+export { searchDocs, extractSearchText, foldText, splitSearchTerms, type SearchableDoc, } from "./nodefony/src/search.js";
+export { rewriteInternalLinks, type RewriteLinksOptions, } from "./nodefony/src/linkResolver.js";
+export { DocumentationError, DocNotFoundError, DocUnsafeSlugError, } from "./nodefony/src/errors/DocumentationError.js";
+export type { DocAudience, DocStatus, DocVarProvider, IDocAudienceInfo, IDocPageRef, IDocSection, IDocTree, IDocPage, IDocumentationService, } from "./nodefony/interfaces/IDocumentation.js";

package/dist/types/nodefony/config/config.d.ts

@@ -0,0 +1,37 @@
+import { z } from "zod";
+export declare const documentationConfigSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    scan: z.ZodDefault<z.ZodObject<{
+        rootDir: z.ZodDefault<z.ZodString>;
+        includeModules: z.ZodDefault<z.ZodBoolean>;
+        includeInstalled: z.ZodDefault<z.ZodBoolean>;
+        exclude: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    repo: z.ZodDefault<z.ZodObject<{
+        url: z.ZodDefault<z.ZodString>;
+        branch: z.ZodOptional<z.ZodString>;
+        editPathPrefix: z.ZodDefault<z.ZodEnum<{
+            blob: "blob";
+            edit: "edit";
+            tree: "tree";
+        }>>;
+    }, z.core.$strict>>;
+    cache: z.ZodDefault<z.ZodObject<{
+        ttlMs: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/** Type de sortie (config normalisée + défauts appliqués). */
+export type DocumentationConfig = z.infer<typeof documentationConfigSchema>;
+/**
+ * Type d'ENTRÉE (ce que l'utilisateur écrit dans `use()`, avant application des
+ * défauts) — tout y est optionnel. C'est CE type qui augmente le registre
+ * `NodefonyModuleConfig`, jamais la sortie : exiger la forme normalisée
+ * obligerait l'app à réécrire chaque défaut.
+ */
+export type DocumentationConfigInput = z.input<typeof documentationConfigSchema>;
+/**
+ * Défauts du module, matérialisés depuis le schéma (source unique). Toujours
+ * valides par construction ; passés au `super(..., config)` du Module class.
+ */
+declare const config: DocumentationConfig;
+export default config;

package/dist/types/nodefony/config/defineModuleConfig.d.ts

@@ -0,0 +1,17 @@
+import { type DocumentationConfig } from "./config.js";
+/**
+ * Valide une config partielle (défauts du schéma) PUIS applique la surcharge par
+ * variables d'environnement (précédence max).
+ *
+ * @param input - config partielle (depuis `module.options.documentation`)
+ * @returns config validée, défauts appliqués, env mergé
+ * @throws ZodError si l'input viole le schéma
+ */
+export declare function defineDocumentationConfig(input?: unknown): DocumentationConfig;
+/**
+ * JSON Schema introspectable de la config documentation — destiné au panneau de
+ * config Studio (`/nodefony/config`). N'inclut PAS la surcharge ENV (appliquée
+ * hors schéma, dans le builder).
+ */
+export declare function documentationConfigJsonSchema(): unknown;
+export { documentationConfigSchema } from "./config.js";

package/dist/types/nodefony/controller/DocumentationController.d.ts

@@ -0,0 +1,33 @@
+import { Controller } from "@nodefony/framework";
+import { Context } from "@nodefony/http";
+/**
+ * Data plane HTTP de la documentation Nodefony.
+ *
+ * Expose l'index transverse et le contenu des pages sous
+ * `/nodefony/documentation/api/*` (convention figée : un module admin sert
+ * toujours `/nodefony/<module>/api/*`, jamais une route mono-segment).
+ *
+ * **Mince par design** : toute la logique (scan, cache, allowlist, résolution
+ * `{{ }}`) vit dans `DocumentationService` (singleton stateful). Le controller
+ * est réinstancié par requête → il ne porte aucun état, il délègue.
+ *
+ * Sécurité (Zero Trust) : un slug invalide/inconnu renvoie un message
+ * **générique** au client ; le détail (slug, raison) est loggé côté serveur.
+ * La garde anti-traversée est dans le service ({@link isSafeSlug}).
+ */
+declare class DocumentationController extends Controller {
+    #private;
+    constructor(context: Context);
+    /** Index transverse : sections → pages, taguées par audience. */
+    tree(): Promise<import("@nodefony/http").Http2Response | import("@nodefony/http").HttpResponse | import("@nodefony/http").WebsocketResponse>;
+    /**
+     * Cherche dans le corpus — titres ET corps — et rend des extraits situés.
+     *
+     * Filtrer l'arbre ne répondait qu'à « quelle page s'appelle ainsi ? » ; la
+     * question posée est « où est-ce expliqué ? ».
+     */
+    search(q?: string): Promise<import("@nodefony/http").Http2Response | import("@nodefony/http").HttpResponse | import("@nodefony/http").WebsocketResponse>;
+    /** Contenu d'une page + variables `{{ }}` résolues côté serveur. */
+    page(slug: string): Promise<import("@nodefony/http").Http2Response | import("@nodefony/http").HttpResponse | import("@nodefony/http").WebsocketResponse>;
+}
+export default DocumentationController;

package/dist/types/nodefony/interfaces/IDocumentation.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Interfaces publiques du data plane de documentation.
+ *
+ * Contrat exposé par `/nodefony/documentation/api/*` et consommé par le front
+ * Studio (et, demain, par un générateur de site statique ou le RAG P12). Le
+ * module est **headless** : il produit ces shapes, il ne rend aucun HTML.
+ */
+/** Persona métier ciblée par une page (RBAC P6 — aujourd'hui filtre de vue). */
+export type DocAudience = "developer" | "devops" | "supervisor" | "admin";
+/** Statut de maturité d'une page (issu du frontmatter `status`). */
+export type DocStatus = "stable" | "draft" | "temporary" | "experimental" | "deprecated";
+/** Une persona décrite dans l'index (clé + libellé + description courte). */
+export interface IDocAudienceInfo {
+    key: DocAudience;
+    label: string;
+    desc: string;
+}
+/** Entrée d'une page dans l'arbre (métadonnées seules, sans le markdown). */
+export interface IDocPageRef {
+    /** Identifiant URL-safe unique (sert de clé d'allowlist anti-traversée). */
+    slug: string;
+    /** Titre lisible (frontmatter `title`, sinon dérivé du nom de fichier). */
+    title: string;
+    /**
+     * Libellé COURT pour la navigation (frontmatter `navTitle`, repli sur
+     * {@link title}). Le menu est une colonne étroite, le titre est écrit pour être
+     * lu en tête d'article : sans ce champ, l'arbre affiche des phrases et la
+     * recherche ne trouve pas le mot qu'on VOIT à l'écran.
+     */
+    navTitle: string;
+    /** Personas autorisées (frontmatter `audience`). Vide = toutes. */
+    audience: DocAudience[];
+    /** Version de la page (frontmatter `version`, ou `"doc"`). */
+    version?: string;
+    /** Statut de maturité (frontmatter `status`). */
+    status?: DocStatus;
+    /** `true` si la page est annoncée mais pas encore rédigée. */
+    wip?: boolean;
+    /**
+     * `true` si la page est le **hub** de sa section (`index.md`) : son point
+     * d'entrée, à présenter en premier et non comme une page parmi les autres.
+     */
+    isHub?: boolean;
+}
+/** Une section de l'index transverse : un groupe ordonné de pages. */
+export interface IDocSection {
+    /** Identifiant stable de la section (URL-safe). */
+    id: string;
+    /** Libellé affiché. */
+    label: string;
+    /** Module propriétaire (`@nodefony/x`) si la section vient d'un module. */
+    module?: string;
+    /** Pages de la section. */
+    pages: IDocPageRef[];
+}
+/** Index transverse complet renvoyé par `GET …/api/tree`. */
+export interface IDocTree {
+    /** Date ISO de génération de l'index (cache invalidé après TTL). */
+    generatedAt: string;
+    /** Personas connues (pour le sélecteur de vue / RBAC). */
+    audiences: IDocAudienceInfo[];
+    /** Sections de l'index. */
+    sections: IDocSection[];
+}
+/** Contenu complet d'une page renvoyé par `GET …/api/page/{slug}`. */
+export interface IDocPage {
+    slug: string;
+    title: string;
+    version?: string;
+    status?: DocStatus;
+    /** Date de dernière modif (frontmatter `updated` ou dernier commit git). */
+    updated?: string;
+    /** Chemin source relatif au repo (pour traçabilité). */
+    source?: string;
+    /** URL « Modifier sur GitHub » assemblée serveur (jamais de chemin FS). */
+    sourceUrl?: string;
+    /** Markdown SANS le bloc frontmatter, variables `{{ }}` résolues. */
+    markdown: string;
+}
+/**
+ * Fournisseur d'une variable dynamique `{{ name }}` résolue côté serveur.
+ *
+ * Doit retourner une valeur **sûre** (publique, dérivée) : version, compteur,
+ * nom de symbole — JAMAIS un secret ni un chemin FS absolu. Synchrone par
+ * design (résolution dans le hot path froid de lecture d'une page).
+ */
+export type DocVarProvider = () => string;
+/** Service public du module documentation (consommé par le controller). */
+export interface IDocumentationService {
+    /** Construit (ou sert depuis le cache) l'index transverse des docs. */
+    getTree(): Promise<IDocTree>;
+    /**
+     * Charge une page par slug (validé contre l'allowlist du scan), résout son
+     * frontmatter et ses variables `{{ }}`.
+     *
+     * @throws DocNotFoundError si le slug est inconnu
+     * @throws DocUnsafeSlugError si le slug est rejeté par la garde de sécurité
+     */
+    getPage(slug: string): Promise<IDocPage>;
+    /**
+     * Cherche dans les titres ET le corps des pages, et rend des extraits situés.
+     *
+     * @param query - la saisie brute ; les termes d'un caractère sont ignorés.
+     * @param limit - nombre maximal de pages rendues (défaut 20).
+     */
+    search(query: string, limit?: number): Promise<IDocSearchResult>;
+    /** Enregistre un fournisseur de variable `{{ name }}` (résolution serveur). */
+    registerVar(name: string, provider: DocVarProvider): void;
+    /** Invalide le cache de l'index (force un rescan au prochain `getTree`). */
+    invalidate(): void;
+}
+/** Un extrait de texte où les termes cherchés apparaissent. */
+export interface IDocSearchExcerpt {
+    /** Le titre de section (`##`) sous lequel l'extrait a été trouvé, s'il y en a un. */
+    section?: string;
+    /** Le texte de l'extrait, borné — les termes y sont encadrés par `\u0000`. */
+    text: string;
+}
+/** Une page retenue par la recherche. */
+export interface IDocSearchHit {
+    slug: string;
+    title: string;
+    navTitle: string;
+    /** Libellé de la section d'arbre qui porte la page (« Guides », « Cœur »…). */
+    sectionLabel: string;
+    /** Extraits, dans l'ordre du document — bornés. */
+    excerpts: IDocSearchExcerpt[];
+    /** Occurrences TOTALES dans la page ; les extraits, eux, sont bornés. */
+    occurrences: number;
+    /** Pertinence décroissante : un terme dans le titre pèse plus que dans le corps. */
+    score: number;
+}
+/** Réponse de `/documentation/api/search`. */
+export interface IDocSearchResult {
+    /** La requête telle que reçue. */
+    query: string;
+    /** Les termes effectivement cherchés (pliés, vides retirés). */
+    terms: string[];
+    /** Pages lues pour répondre — dit ce que la recherche a réellement balayé. */
+    scanned: number;
+    /** Pages retenues AVANT bornage — un total de 40 avec 20 rendus se dit. */
+    matched: number;
+    hits: IDocSearchHit[];
+}

package/dist/types/nodefony/interfaces/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Barrel des interfaces publiques de `@nodefony/documentation`.
+ * Réexporté par `index.ts` racine via `export type { ... }`.
+ */
+export type { DocAudience, DocStatus, DocVarProvider, IDocAudienceInfo, IDocPageRef, IDocSection, IDocTree, IDocPage, IDocumentationService, } from "./IDocumentation.js";

package/dist/types/nodefony/service/DocumentationService.d.ts

@@ -0,0 +1,78 @@
+import { Module, Service, type Message, type Msgid, type Pci, type Severity } from "nodefony";
+import type { DocumentationConfig } from "../config/config.js";
+import type { DocVarProvider, IDocPage, IDocSearchResult, IDocTree } from "../interfaces/IDocumentation.js";
+/**
+ * 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.
+ */
+export declare const ROOT_GROUPS: ReadonlyArray<{
+    group: string;
+    label: string;
+}>;
+/**
+ * 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.
+ */
+export declare const ROOT_PAGES: ReadonlyArray<string>;
+/**
+ * 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).
+ */
+declare class DocumentationService extends Service {
+    #private;
+    module: Module;
+    constructor(module: Module);
+    log(pci: Pci, severity?: Severity, msgid?: Msgid, msg?: Message): import("nodefony").Pdu;
+    registerVar(name: string, provider: DocVarProvider): void;
+    invalidate(): void;
+    getTree(): Promise<IDocTree>;
+    /**
+     * 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é.
+     */
+    search(query: string, limit?: number): Promise<IDocSearchResult>;
+    getPage(slug: string): Promise<IDocPage>;
+}
+export default DocumentationService;
+export type { DocumentationConfig };

package/dist/types/nodefony/src/docScanner.d.ts

@@ -0,0 +1,47 @@
+import { type Frontmatter } from "./frontmatter.js";
+import { type DocSource } from "./slug.js";
+/**
+ * Un fichier `.md` découvert par le scan, avec son chemin RÉEL et ses
+ * métadonnées. Le `absPath` est la seule source de vérité pour lire le fichier
+ * (jamais reconstruit depuis le slug → 0 traversée de répertoire).
+ */
+export interface ScannedDoc {
+    /** Clé d'allowlist URL-safe (cf {@link pathToSlug}). */
+    slug: string;
+    /** Chemin relatif POSIX au dossier de base scanné. */
+    relPath: string;
+    /** Chemin absolu RÉEL du fichier (pour la lecture). */
+    absPath: string;
+    /** Origine (racine du projet ou module). */
+    source: DocSource;
+    /** Chemin du dossier parent (POSIX) — sert à regrouper en sections. */
+    group: string;
+    /** Frontmatter parsé (title/audience/section/version/status/updated/source). */
+    meta: Frontmatter;
+    /** Titre résolu (frontmatter `title`, sinon nom de fichier humanisé). */
+    title: string;
+    /**
+     * Libellé de NAVIGATION — court, destiné aux menus et fils d'Ariane.
+     *
+     * Un titre d'article porte le sens et souvent un sous-titre ; la colonne de
+     * navigation, elle, fait quelques centimètres et ne tronque rien. Les deux
+     * usages n'ont donc pas la même contrainte, d'où deux champs.
+     *
+     * Résolu depuis le frontmatter `navTitle`, avec repli sur {@link title} :
+     * une page qui n'en déclare pas garde exactement le comportement d'avant.
+     */
+    navTitle: string;
+}
+/**
+ * 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).
+ */
+export declare function scanDocsDir(baseDir: string, source: DocSource, exclude?: readonly string[]): Promise<ScannedDoc[]>;

package/dist/types/nodefony/src/errors/DocumentationError.d.ts

@@ -0,0 +1,32 @@
+import { nodefonyError } from "nodefony";
+/**
+ * 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).
+ */
+export declare class DocumentationError 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.
+     */
+    readonly docCode: string;
+    constructor(message: string, docCode?: string);
+}
+/** Slug demandé absent de l'allowlist construite par le scan (404 logique). */
+export declare class DocNotFoundError extends DocumentationError {
+    constructor(slug: string);
+}
+/**
+ * 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.
+ */
+export declare class DocUnsafeSlugError extends DocumentationError {
+    constructor(slug: string);
+}