ADR-017 : Type `slug` et module URL-slug canonique¶

Statut¶

Acceptée

Décision-cadre de la Phase 2 de la roadmap beta.13.
Implémentée par SLUG-CORE-001 (module), SLUG-VALIDATION-001, SLUG-SQL-CRUD-001, SLUG-ROUTING-001.

Contexte¶

Les URLs publiques générées par Forge restent faibles sans slug (/articles/42 plutôt que /articles/premier-contact).
Le slug est nécessaire pour les pages publiques, catalogues, blogs : URLs lisibles, partageables, SEO-friendly.

L'audit de l'existant (BETA13-EXISTING-AUDIT-001) révèle un terrain partiellement défriché mais incohérent :

cli/public_page._slugify, un validateur strict (kebab-case, [a-z0-9-]) qui rejette les accents (ValueError sur « Écrire ») ; ce n'est pas un générateur.
1 seul usage.
cli/entities/migrations.slugify_migration_name, un transformeur snake_case (_) pour les noms de fichiers de migration : concept différent d'une URL slug (format et finalité distincts).
type slug déjà reconnu dans le contrat d'entité (cli/entities/validation.py) + SlugField dans le CRUD, sans logique de génération.

Trois objets « slug » coexistent donc, avec des contrats divergents, risque de duplication (charte §11) si on ajoute naïvement une 4ᵉ fonction.

Décision¶

D1 : Deux concepts distincts, nommés clairement¶

URL slug (kebab-case -, pour les URLs publiques) → un seul module canonique core/http/slug.py.
Nom de fichier de migration (snake_case _) → reste slugify_migration_name, séparé.
Ce n'est pas une URL slug ; un commentaire le précise pour éviter toute fusion future.

D2 : Module canonique `core/http/slug.py` (runtime, stdlib seul)¶

Deux fonctions publiques, dépendances stdlib uniquement (unicodedata, re), respect du runtime minimal (charte) :

def slugify(text: str, *, max_length: int = 180) -> str
def is_valid_slug(value: str, *, max_length: int = 180) -> bool

slugify transforme n'importe quel texte en URL slug : translittération des accents via unicodedata.normalize("NFKD", …) (« Écrire avec Forge ! » → ecrire-avec-forge), minuscules, tout caractère non [a-z0-9] → -, tirets compactés, bordures retirées, longueur bornée.
Ne lève que si le résultat est vide (entrée sans aucun caractère exploitable).
is_valid_slug valide un slug existant : path-safe (rejette /, \, ..), correspond à [a-z0-9]+(?:-[a-z0-9]+)*, longueur ≤ max_length.

Le runtime (contrôleurs/modèles générés) et le CLI (codegen) importent ce même module.
cli/public_page._slugify est remplacé par core.http.slug (§11 : une seule implémentation URL-slug).

D3 : Le type `slug` dans le contrat d'entité¶

slug est un type de champ de premier rang du contrat d'entité JSON (au même titre que string, email…), validé par le contrat (ADR-013) :

{ "name": "slug", "type": "slug", "required": true, "unique": true }

Sémantique : identifiant URL-safe d'une ressource.
La génération SQL produit VARCHAR(180) + contrainte UNIQUE visible (charte « SQL visible »).

D4 : Unicité : rejet des doublons (pas de suffixe auto en b13)¶

Le CRUD généré refuse un slug en doublon avec une erreur claire.
Le suffixe automatique (mon-article-2) introduit une complexité de concurrence (race sur insert) non justifiée en dernière beta → reporté après 1.0.

D5 : Périmètre b13¶

Inclus : module canonique, validation, type d'entité, génération SQL/CRUD, routing public par slug (SLUG-ROUTING-001).
Exclus (post-1.0) : suffixe auto, slug_history, redirections 301, sitemap, slugs multilingues.

Conséquences¶

public_page._slugify change de comportement : il translittère les accents au lieu de les rejeter (plus utile), ses tests sont ajustés.
slugify_migration_name est inchangé mais documenté comme distinct.
Le contrat d'entité gagne un type de premier rang slug → garde-fou de complétude (§10) : SQL, validation, CRUD, doc cohérents.
Nouveau module runtime core/http/slug.py testé indépendamment.

Alternatives considérées¶

Fusionner les 3 « slug » en une fonction.
Écarté : slugify_migration_name produit du snake_case pour des noms de fichiers, pas des URLs, fusionner casserait les migrations.
Les deux concepts restent séparés (D1).

Option « slug » comme simple drapeau sur un champ string ({"type": "string", "slug": true}).
Écarté au profit d'un type dédié (D3) : plus explicite pour les générateurs, les tests et la doc, conforme à « une seule façon » (§11).

Dépendance externe (python-slugify, unidecode).
Écarté : unicodedata (stdlib) suffit pour la translittération NFKD ; le runtime minimal de Forge n'accueille pas de dépendance pour ça.

Suffixe automatique -2/-3 dès b13.
Écarté : race conditions sur insert concurrent, complexité non justifiée en dernière beta (D4).

Liens¶

Charte : §10 (contrat de complétude), §11 (une seule façon), « SQL visible », runtime minimal.
ADR-013, politique du contrat d'entité (nullable/required).
Roadmap beta.13, Phase 2.

ADR-017 : Type slug et module URL-slug canonique¶