@nodefony/documentation 10.0.0-alpha.1

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

@@ -0,0 +1,37 @@
+/**
+ * Parseur de frontmatter YAML minimal — **sans dépendance**.
+ *
+ * Un fichier de doc Nodefony commence (optionnellement) par un bloc encadré de
+ * `---` qui porte des métadonnées (`title`, `audience`, `section`, `version`,
+ * `status`, `updated`, `source`, `publish`). On n'embarque PAS `gray-matter` (~plusieurs
+ * deps transitives) pour ça : la doc n'utilise qu'un sous-ensemble plat de YAML
+ * (clé: valeur scalaire ou liste). Ce parseur couvre ce sous-ensemble et reste
+ * volontairement strict/petit.
+ *
+ * Supporté :
+ * - `key: value`                → string (quotes simples/doubles retirées)
+ * - `key: [a, b, c]`            → string[] (liste inline)
+ * - `key:` puis lignes `  - x`  → string[] (liste en bloc)
+ * - lignes vides / commentaires `#` ignorées
+ *
+ * NON supporté (volontaire) : objets imbriqués, multi-lignes `|`/`>`, ancres.
+ * La doc n'en a pas besoin → on ne paie pas la complexité.
+ */
+/** Métadonnées extraites du frontmatter — valeurs scalaires ou listes. */
+export type Frontmatter = Record<string, string | string[]>;
+/** Résultat du parse : `meta` (frontmatter) + `body` (markdown sans le bloc). */
+export interface ParsedDoc {
+    meta: Frontmatter;
+    body: string;
+}
+/**
+ * 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.
+ */
+export declare function parseFrontmatter(raw: string): ParsedDoc;
+/** Lit une clé de frontmatter en string (1er élément si liste), ou `undefined`. */
+export declare function metaString(meta: Frontmatter, key: string): string | undefined;
+/** Lit une clé de frontmatter en string[] (wrappe un scalaire), ou `[]`. */
+export declare function metaList(meta: Frontmatter, key: string): string[];

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

@@ -0,0 +1,55 @@
+/**
+ * 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.
+ */
+/** Options de {@link rewriteInternalLinks}. */
+export interface RewriteLinksOptions {
+    /**
+     * Dossier de la page courante, relatif à la racine du projet (POSIX, sans
+     * fichier). Ex. `src/packages/@nodefony/security/docs`.
+     */
+    fromDir: string;
+    /**
+     * Traduit un chemin de fichier relatif à la racine du projet en slug.
+     * Retourne `undefined` si le fichier n'est pas dans l'index (lien laissé
+     * intact — on ne fabrique jamais un slug qui n'existe pas).
+     */
+    toSlug: (repoRelPath: string) => string | undefined;
+    /**
+     * Suffixe ajouté derrière la cible traduite. Vaut `".md"` par défaut : le
+     * portail reconnaît un lien interne à cette extension, et un slug nu serait
+     * indistinguable d'une URL relative quelconque.
+     *
+     * Un générateur de site statique publie en revanche des URL réelles
+     * (`/modules/security/cors/`) : il passe `""` et `toSlug` rend l'URL. Sans ce
+     * point d'extension, il faudrait recopier la résolution relative ailleurs —
+     * et deux implémentations d'une même règle divergent toujours.
+     */
+    suffix?: string;
+}
+/**
+ * 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.
+ */
+export declare function rewriteInternalLinks(markdown: string, options: RewriteLinksOptions): string;

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

@@ -0,0 +1,64 @@
+/**
+ * Recherche plein texte du corpus de documentation — brique PURE.
+ *
+ * Elle ne lit ni disque ni réseau : on lui passe des pages déjà chargées, elle
+ * rend un classement. C'est ce qui lui permet d'avoir DEUX consommateurs très
+ * différents sans être écrite deux fois :
+ *
+ * - le service {@link DocumentationService.search}, côté serveur, qui lit les
+ *   `.md` du disque à chaque requête ;
+ * - le générateur du site public, qui n'a pas de serveur du tout : il embarque
+ *   un index dans la page et fait tourner CETTE fonction dans le navigateur du
+ *   lecteur (`searchDocs.toString()` — voir `build-docs-site.mjs`).
+ *
+ * D'où la contrainte qui gouverne ce fichier : **`searchDocs` et ses aides sont
+ * auto-suffisantes**. Aucun import, aucune variable de portée supérieure, aucune
+ * syntaxe qui suppose un bundler. Le jour où l'une d'elles capture quelque chose
+ * de son module, le site continue de se construire et la recherche casse chez le
+ * lecteur — sans un mot. Le test de parité (`search-parity.test.ts`) est là pour
+ * ça : il exécute la fonction SÉRIALISÉE, pas la fonction importée.
+ */
+import type { IDocSearchResult } from "../interfaces/IDocumentation.js";
+/** Une page telle que la recherche a besoin de la voir. */
+export interface SearchableDoc {
+    slug: string;
+    title: string;
+    navTitle: string;
+    /** Libellé de la section d'arbre qui porte la page (« Guides », « Cœur »…). */
+    sectionLabel: string;
+    /** Corps de la page, frontmatter retiré. */
+    body: string;
+}
+/**
+ * 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.
+ */
+export declare function foldText(text: string): string;
+/** Termes effectivement cherchés : pliés, dédoublonnés, un caractère écarté. */
+export declare function splitSearchTerms(query: string): string[];
+/**
+ * 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).
+ */
+export declare function extractSearchText(markdown: string): string;
+/**
+ * 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é.
+ */
+export declare function searchDocs(docs: SearchableDoc[], query: string, limit?: number): IDocSearchResult;

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

@@ -0,0 +1,48 @@
+/**
+ * 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.
+ */
+/**
+ * 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.
+ */
+export declare function isSafeSlug(slug: string): boolean;
+/** Source d'un fichier de doc : racine du projet ou un module. */
+export type DocSource = {
+    kind: "root";
+} | {
+    kind: "module";
+    module: string;
+};
+/**
+ * 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.
+ */
+export declare function pathToSlug(source: DocSource, relPath: string): string;