Diagnostiques de rendu

Lorsqu'une charge utile contient une faute de frappe dans une propriété de style, une valeur d'énumération invalide ou une référence à un style indéfini, le moteur de rendu ignore silencieusement l'élément offensant et continue. Le rendu réussit, mais la déclaration cassée est supprimée — invisible sauf si quelqu'un lit les avertissements du journal du moteur.

L'activation optionnelle diagnostics fait surface tous ces événements d'abandon silencieux dans le document rendu lui-même. Le même motif que celui utilisé par l'encodeur de code-barres pour les charges utiles invalides ([barcode error: …] espaces réservés en ligne) — étendu aux propriétés de style, aux ressources manquantes et aux références non résolues.

Exemple en direct

Une fixture avec des fautes de frappe intentionnelles. L'annexe en dernière page liste toutes les propriétés supprimées.

Output

Try in Playground →

Template

Data

Comment l'activer

Ajoutez un bloc diagnostics à la racine du document :

{
  "document": {
    "diagnostics": {
      "showInDocument": "appendix",
      "minLevel": "warning"
    },
    "content": [ ... ]
  }
}

Propriété	Type	Défaut	Description
showInDocument	string	"off"	Comment afficher les diagnostiques : off (comportement d'abandon silencieux actuel, avertissements de journal uniquement), appendix (tableau agrégé à la fin du document), inline (paragraphes marqueurs à la première utilisation de chaque style affecté), both (marqueurs en ligne + annexe).
minLevel	string	"warning"	Gravité minimale à inclure : info (normalisations inoffensives comme le changement de casse), warning (abandons silencieux), error (défaillances critiques capturées et ignorées par le moteur de rendu).

Ce qui est capturé

Chaque site d'abandon silencieux dans le moteur de rendu s'écoule automatiquement à travers cette surface — sans instrumentation par site. Couverture actuelle :

• Fautes de frappe de style — fontsizr: 14 au lieu de fontSize. Capturé comme avertissement.
• Valeurs d'énumération invalides — textAlign: "sideways", strokeLinecap: "wedge". Capturé comme avertissement.
• Références à des styles indéfinis — { "p": "...", "style": "doesNotExist" }. Capturé comme avertissement.
• Ressources manquantes ou non résolues — police, image ou charge utile de code-barres référencée dont le chargement échoue. Capturé comme avertissement ou erreur selon le site.

Le collecteur déduplique par (source, propriété) : un style avec une faute de frappe appliquée à 100 paragraphes produit UNE entrée, pas 100. La gravité est escaladée si la même source signale un problème plus grave plus tard — l'annexe reflète le pire cas.

Format de l'annexe

Lorsque showInDocument est appendix ou both, le moteur de rendu ajoute une section « Diagnostiques de rendu » à la fin du document avec un tableau :

Gravité	Source	Propriété	Message
WARNING	intentionalTypo	fontsizr	Propriété de style non reconnue : 'fontsizr'.
WARNING	intentionalEnum	textAlign	textAlign 'sideways' non pris en charge (prévu : left/center/right/justified).
WARNING	styleThatDoesNotExist	(style)	Style avec la clé 'styleThatDoesNotExist' non trouvé ou sans propriétés.

La gravité est codée par couleur : avertissements en or foncé, erreurs en brique rouge, info en gris ardoise.

Marqueurs en ligne

Lorsque showInDocument est inline ou both, un paragraphe marqueur est émis à la première utilisation de chaque style avec des diagnostiques :

⚠ intentionalTypo: unknown 'fontsizr'; invalid textAlign 'sideways'

Les utilisations suivantes du même style ne réémettent pas (dédupliqué). Le marqueur se positionne dans la position de flux naturelle afin que les auteurs voient OÙ le style cassé a été appliqué.

Niveaux de gravité

Niveau	Quand émis	Exemple
info	Normalisation inoffensive — valeur d'énumération pliée en cas, alias déprécié résolu.	textAlign: "CENTER" accepté et normalisé en "center".
warning	Abandon silencieux — propriété supprimée ou substituée par un repli. Moteur de rendu continué.	Propriété inconnue, énumération invalide, ressource optionnelle manquante.
error	Défaillance critique capturée par le moteur de rendu. Élément ignoré, rendu continué.	Ressource requise manquante, charge utile de code-barres malformée.

Le minLevel par défaut est warning afin que les normalisations au niveau des infos restent silencieuses sauf si elles sont explicitement activées.

La journalisation est préservée

L'activation de diagnostics ne supprime pas les avertissements de journal du moteur existants. Ils continuent de circuler par le biais du ILogger fourni par l'appelant exactement comme auparavant — les diagnostiques sont une surface supplémentaire, pas un remplacement. Le collecteur est alimenté en interceptant les événements de journal au niveau du journaliseur (DiagnosticsCapturingLogger), de sorte que le code du moteur et les appelants externes ne voient aucun changement de comportement.

Recommandé pour

• Environnements de création — rendus IDE/sandbox où les auteurs doivent voir leurs fautes de frappe.
• Validation de pré-production — rendu CI de chaque modèle avec showInDocument: "appendix" et une annexe non vide signalée comme un échec CI.
• Aperçus du portail client — permettre aux auteurs de modèles de déboguer leurs propres définitions sans avoir à plonger dans les journaux.

NON recommandé pour

• Rendus de production pour les clients finaux — l'annexe est une affordance de création, pas du contenu orienté vers les clients. La valeur par défaut off est le bon paramètre pour les documents livrés.

Parité des formats

PDF et DOCX rendent la même forme diagnostics avec la même sortie inline + annexe. Les deux pipelines de rendu partagent le collecteur RenderDiagnostics et DiagnosticsCapturingLogger de Documentors.Core.Diagnostics, puis le moteur de rendu de chaque format compose l'annexe et les marqueurs en ligne via son générateur de contenu natif (ContentElementBuilder pour PDF, ContentBuilder pour DOCX) de sorte que le style correspond au contenu du corps dans les deux sorties.