ADR 0063 – Mentions non liées

Statut : Accepté (2026-10-16, mode autonome)

Item 31 du backlog (jalon 3, vague 2 du document d’idées), pris par le fil « Documentation, puis capture en une ligne ». L’idée vient d’Obsidian : une section du panneau de contexte liste les nœuds dont le texte cite le titre de ce nœud sans [[lien]], avec un bouton « Lier ». Les liens oubliés remontent ainsi.

Décision

Ce qui compte comme mention

• Le titre du nœud, en mots entiers, sans tenir compte des accents ni de la casse : « chaudiere viessmann » cite « Chaudière Viessmann ». « projets maisonnettes » ne cite pas « Projet maison ».
• Dans le corps des autres nœuds hors corbeille, en dehors du code (en ligne et en bloc), des liens et images Markdown et des liens wiki existants (même règles de zones que les #tags, ADR 0011), et jamais dans une adresse (mot qui contient ://, www. ou @), un #tag, ni juste après ! ou \.
• Une occurrence n’est proposée que si sa réécriture produit exactement un lien wiki de plus vers le titre, sans changer les autres liens ni les #tags du corps (vérifié par une nouvelle lecture, comme le renommage, ADR 0009). Dans une ligne de tableau, le séparateur de l’alias s’écrit \|.
• Le titre est recomposé (NFC) ; une occurrence suivie d’un accent décomposé n’est pas coupée.
• Si un homonyme plus ancien porte le même titre, [[Titre]] mènerait à lui (ADR 0009) : rien n’est proposé.
• Un nœud qui a déjà un lien wiki vers celui-ci n’est pas listé, même s’il le cite ailleurs sans lien : il est déjà relié.
• Titres exclus : moins de 3 caractères (« TV », « Re ») et titres inutilisables comme cible de lien wiki (ADR 0009).
• Les titres alternatifs (alias de nœud) ne sont pas cherchés : ils feront l’objet d’une autre idée du document.

API

• GET /api/nodes/{id}/mentions : au plus 50 nœuds, les plus récemment modifiés d’abord, chacun avec un extrait autour de la première mention (before, match tel qu’écrit, after, 60 caractères de contexte, sur une ligne).
• Recherche en deux temps : un préfiltre SQL (unaccent(body) ILIKE '%titre%', 200 candidats au plus, liens wiki existants exclus), puis la confirmation en Java (mots entiers, zones exclues), qui calcule l’extrait.
• POST /api/nodes/{id}/mentions/{sourceId}/link : remplace la première mention du corps de sourceId par [[Titre]], ou [[Titre|texte écrit]] si le texte diffère (casse, accents). L’écriture passe par l’enregistrement ordinaire du corps : index des liens wiki, rétroliens, événement node.updated, sous les verrous de l’index wiki puis du nœud (ordre de l’ADR 0009). La réponse rend le corps d’avant et le corps écrit. 409 si la mention n’y est plus, 400 pour un nœud et lui-même.
• POST /api/nodes/{id}/mentions/{sourceId}/unlink { previousBody, linkedBody } (« Annuler ») : remet le corps d’avant seulement si le corps est encore celui que le lien a écrit, sans toucher au titre ; sinon 409 et rien n’est écrit.

Interface

• Section « Mentions non liées » du panneau de contexte, sous les rétroliens, avec un compteur : titre du nœud qui cite (en lien), extrait avec la mention en gras, bouton « Lier ».
• Après « Lier », la ligne disparaît, le focus passe au « Lier » suivant, les rétroliens se relisent, et l’annonce propose « Annuler » (même après avoir quitté la fiche).
• La section se relit à chaque enregistrement du nœud courant (titre changé : autres mentions).

Alternatives écartées

• Index dédié des mentions, tenu à jour à chaque écriture : il faudrait recalculer tous les corps à chaque renommage ; la recherche à la demande suffit à cette échelle.
• Lier toutes les mentions d’un coup : une mention peut être un homonyme ; on lie une occurrence à la fois, en voyant l’extrait.
• Chercher aussi dans les champs d’aspects : un champ texte n’accueille pas de lien wiki ; seul le corps peut être lié.

Conséquences

• Le préfiltre lit au plus 200 candidats, les plus récemment modifiés ; une mention plus ancienne peut ne pas être listée si beaucoup de candidats sont écartés (code, liens).
• Coût : une requête par ouverture de fiche dont le titre fait 3 caractères ou plus ; le préfiltre lit les corps sans index (acceptable pour un usage personnel, à revoir au-delà de quelques dizaines de milliers de nœuds).