Référence d'API — @nodefony/documentation

stable

Documentation › Référence d’API › @nodefony/documentation

Générée depuis les déclarations de types publiées de @nodefony/documentation 10.0.0-beta.5 : exactement ce que reçoit une application qui l’installe. Cette page n’existe dans aucun dépôt — pour la corriger, on corrige le TSDoc du code.

@nodefony/documentation#

import { … } from "@nodefony/documentation" — 39 symboles.

Classes (6)#

DocNotFoundError#

class DocNotFoundError extends DocumentationError

Slug demandé absent de l’allowlist construite par le scan (404 logique).

• constructor(slug: string)

DocUnsafeSlugError#

class DocUnsafeSlugError extends DocumentationError

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.

• constructor(slug: string)

DocumentationController#

class DocumentationController extends Controller

Data plane HTTP de la documentation Nodefony.

• constructor(context: Context)
• tree(): Promise<import("@nodefony/http").Http2Response | import("@nodefony/http").HttpResponse | import("@nodefony/http").WebsocketResponse> — Index transverse : sections → pages, taguées par audience.
• search(q?: string): 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.
• page(slug: string): Promise<import("@nodefony/http").Http2Response | import("@nodefony/http").HttpResponse | import("@nodefony/http").WebsocketResponse> — Contenu d’une page + variables {{ }} résolues côté serveur.

DocumentationError#

class DocumentationError extends nodefonyError

Erreur typée du module @nodefony/documentation.

• readonly docCode: string — Code machine stable (ex.
• constructor(message: string, docCode?: string)

DocumentationService#

class DocumentationService extends Service

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).

• module: Module
• constructor(module: Module)
• log(pci: Pci, severity?: Severity, msgid?: Msgid, msg?: Message): import("nodefony").Pdu — Émet une entrée de log structurée — point d’entrée central pour TOUT log Nodefony.
• registerVar(name: string, provider: DocVarProvider): void
• invalidate(): void
• getTree(): Promise<IDocTree>
• search(query: string, limit?: number): Promise<IDocSearchResult> — Cherche query dans le corpus — titres ET corps — et rend des EXTRAITS.
• getPage(slug: string): Promise<IDocPage>

default#

class Documentation extends Module<IDocumentationConfig>

• static critical: boolean — Module optionnel : un échec de son boot ne tue jamais le process (résilience Ph.3).
• constructor(kernel: Kernel)
• configSchema(): unknown — JSON Schema de la config documentation → data plane admin (config riche Studio).
• onKernelRegister(): Promise<this> — 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 …
• onKernelReady(): Promise<this> — Phase onReady : enregistre les fournisseurs de variables {{ }} built-in sur le service (tous les modules sont alors bootés).

Fonctions (13)#

defineDocumentationConfig#

function defineDocumentationConfig(input?: unknown): IDocumentationConfig

Valide une config partielle et applique les défauts du schéma.

documentationConfigJsonSchema#

function documentationConfigJsonSchema(): unknown

JSON Schema introspectable de la config documentation — destiné au panneau de config Studio (/nodefony/config), noms courts d’environnement compris.

extractSearchText#

function extractSearchText(markdown: string): string

Prose INDEXABLE d’une page de documentation.

foldText#

function foldText(text: string): string

Réduit un texte à sa forme comparable : minuscules, accents retirés.

isSafeSlug#

function isSafeSlug(slug: string): boolean

Valide qu’un slug est sûr à manipuler (avant toute recherche/lecture).

metaList#

function metaList(meta: Frontmatter, key: string): string[]

Lit une clé de frontmatter en string[] (wrappe un scalaire), ou [].

metaString#

function metaString(meta: Frontmatter, key: string): string

Lit une clé de frontmatter en string (1er élément si liste), ou undefined.

parseFrontmatter#

function parseFrontmatter(raw: string): ParsedDoc

Sépare le bloc frontmatter du corps markdown et parse les métadonnées.

pathToSlug#

function pathToSlug(source: DocSource, relPath: string): 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).

rewriteInternalLinks#

function rewriteInternalLinks(markdown: string, options: RewriteLinksOptions): string

Réécrit les liens markdown internes d’une page en slugs navigables.

scanDocsDir#

function scanDocsDir(baseDir: string, source: DocSource, exclude?: readonly string[]): Promise<ScannedDoc[]>

Scanne récursivement un dossier de docs et retourne les fichiers .md trouvés, frontmatter lu, triés par chemin relatif.

searchDocs#

function searchDocs(docs: SearchableDoc[], query: string, limit?: number): IDocSearchResult

Classe les pages qui portent TOUS les termes, la plus pertinente d’abord.

splitSearchTerms#

function splitSearchTerms(query: string): string[]

Termes effectivement cherchés : pliés, dédoublonnés, un caractère écarté.

Constantes (3)#

ROOT_GROUPS#

const ROOT_GROUPS: ReadonlyArray<{ group: string; label: string; }>

Les groupes racine publiés, dans l’ordre du menu, avec leur libellé.

ROOT_PAGES#

const ROOT_PAGES: ReadonlyArray<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.

documentationConfigSchema#

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 …

Interfaces (10)#

IDocAudienceInfo#

interface IDocAudienceInfo

Une persona décrite dans l’index (clé + libellé + description courte).

• key: DocAudience
• label: string
• desc: string

IDocPage#

interface IDocPage

Contenu complet d’une page renvoyé par GET …/api/page/{slug}.

• slug: string
• title: string
• version?: string
• status?: DocStatus
• updated?: string — Date de dernière modif (frontmatter updated ou dernier commit git).
• source?: string — Chemin source relatif au repo (pour traçabilité).
• sourceUrl?: string — URL « Modifier sur GitHub » assemblée serveur (jamais de chemin FS).
• markdown: string — Markdown SANS le bloc frontmatter, variables {{ }} résolues.

IDocPageRef#

interface IDocPageRef

Entrée d’une page dans l’arbre (métadonnées seules, sans le markdown).

• slug: string — Identifiant URL-safe unique (sert de clé d’allowlist anti-traversée).
• title: string — Titre lisible (frontmatter title, sinon dérivé du nom de fichier).
• navTitle: string — Libellé COURT pour la navigation (frontmatter navTitle, repli sur title).
• audience: DocAudience[] — Personas autorisées (frontmatter audience).
• version?: string — Version de la page (frontmatter version, ou "doc").
• status?: DocStatus — Statut de maturité (frontmatter status).
• wip?: boolean — true si la page est annoncée mais pas encore rédigée.
• isHub?: 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.

IDocSection#

interface IDocSection

Une section de l’index transverse : un groupe ordonné de pages.

• id: string — Identifiant stable de la section (URL-safe).
• label: string — Libellé affiché.
• module?: string — Module propriétaire (@nodefony/x) si la section vient d’un module.
• pages: IDocPageRef[] — Pages de la section.

IDocTree#

interface IDocTree

Index transverse complet renvoyé par GET …/api/tree.

• generatedAt: string — Date ISO de génération de l’index (cache invalidé après TTL).
• audiences: IDocAudienceInfo[] — Personas connues (pour le sélecteur de vue / RBAC).
• sections: IDocSection[] — Sections de l’index.

IDocumentationService#

interface IDocumentationService

Service public du module documentation (consommé par le controller).

• getTree(): Promise<IDocTree> — Construit (ou sert depuis le cache) l’index transverse des docs.
• getPage(slug: string): Promise<IDocPage> — Charge une page par slug (validé contre l’allowlist du scan), résout son frontmatter et ses variables {{ }}.
• search(query: string, limit?: number): Promise<IDocSearchResult> — Cherche dans les titres ET le corps des pages, et rend des extraits situés.
• registerVar(name: string, provider: DocVarProvider): void — Enregistre un fournisseur de variable {{ name }} (résolution serveur).
• invalidate(): void — Invalide le cache de l’index (force un rescan au prochain getTree).

ParsedDoc#

interface ParsedDoc

Résultat du parse : meta (frontmatter) + body (markdown sans le bloc).

• meta: Frontmatter
• body: string

RewriteLinksOptions#

interface RewriteLinksOptions

Options de rewriteInternalLinks.

• fromDir: string — Dossier de la page courante, relatif à la racine du projet (POSIX, sans fichier).
• toSlug: (repoRelPath: string) => string — Traduit un chemin de fichier relatif à la racine du projet en slug.
• suffix?: string — Suffixe ajouté derrière la cible traduite.

ScannedDoc#

interface ScannedDoc

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).

• slug: string — Clé d’allowlist URL-safe (cf pathToSlug).
• relPath: string — Chemin relatif POSIX au dossier de base scanné.
• absPath: string — Chemin absolu RÉEL du fichier (pour la lecture).
• source: DocSource — Origine (racine du projet ou module).
• group: string — Chemin du dossier parent (POSIX) — sert à regrouper en sections.
• meta: Frontmatter — Frontmatter parsé (title/audience/section/version/status/updated/source).
• title: string — Titre résolu (frontmatter title, sinon nom de fichier humanisé).
• navTitle: string — Libellé de NAVIGATION — court, destiné aux menus et fils d’Ariane.

SearchableDoc#

interface SearchableDoc

Une page telle que la recherche a besoin de la voir.

• slug: string
• title: string
• navTitle: string
• sectionLabel: string — Libellé de la section d’arbre qui porte la page (« Guides », « Cœur »…).
• body: string — Corps de la page, frontmatter retiré.

Types (7)#

DocAudience#

type DocAudience = "developer" | "devops" | "supervisor" | "admin"

Persona métier ciblée par une page (RBAC P6 — aujourd’hui filtre de vue).

DocSource#

type DocSource = { kind: "root"; } | { kind: "module"; module: string; }

Source d’un fichier de doc : racine du projet ou un module.

DocStatus#

type DocStatus = "stable" | "draft" | "temporary" | "experimental" | "deprecated"

Statut de maturité d’une page (issu du frontmatter status).

DocVarProvider#

type DocVarProvider = () => string

Fournisseur d’une variable dynamique {{ name }} résolue côté serveur.

Frontmatter#

type Frontmatter = Record<string, string | string[]>

Métadonnées extraites du frontmatter — valeurs scalaires ou listes.

IDocumentationConfig#

type IDocumentationConfig = z.infer<typeof documentationConfigSchema>

Type de sortie (config normalisée + défauts appliqués).

IDocumentationConfigInput#

type IDocumentationConfigInput = z.input<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.

← Toutes les références d’API