Configuration

lucid-lint se configure par un fichier lucid-lint.toml à la racine du projet (facultatif) et par des options en ligne de commande (qui priment sur le fichier).

Forme du fichier

# lucid-lint.toml

[default]
profile = "public"

[rules.sentence-too-long]
max_words = 22

[rules.passive-voice]
max_per_paragraph = 2

Sections

[default]

Réglages par défaut appliqués à toute l’exécution.

[rules.<rule-id>]

Configuration par règle. Les champs disponibles dépendent de la règle. Voir les pages de règles dans la référence des règles.

[scoring]

Paramètres ajustables du modèle hybride de score. Tous les champs sont facultatifs ; un champ absent retombe sur le défaut livré (category_max = 20, category_cap = 15).

[scoring]
category_max = 20
category_cap = 15

[scoring.weights]
sentence-too-long = 3
weasel-words      = 2

La sous-table [scoring.weights] est indexée par identifiant de règle. Les identifiants inconnus sont ignorés ; retirer une règle dans une version future ne casse donc pas les anciens fichiers.

Ordre de priorité

Du plus faible au plus fort :

1. Préréglage du profil (par exemple public)
2. Surcharges de lucid-lint.toml
3. Options en ligne de commande

Une option non passée en ligne de commande retombe sur la valeur TOML ; un champ TOML absent retombe sur le préréglage du profil.

Découverte

lucid-lint remonte depuis le dossier courant jusqu’au premier lucid-lint.toml trouvé, et s’arrête à la frontière du dépôt .git le plus proche. L’option --config <chemin> saute la découverte et charge le fichier indiqué ; un chemin explicite manquant est une erreur, mais un fichier auto-découvert manquant ne l’est pas.

Exclure des chemins

Les gros dépôts de documentation contiennent souvent des sorties générées, des textes vendus avec le projet et des instantanés qui noieraient le linter sous le bruit. Utilisez le champ exclude dans [default] — ou l’option --exclude <GLOB> en ligne de commande — pour les écarter à la découverte, avant l’analyse.

[default]
exclude = [
    "vendor/**",
    "**/fixtures/**",
    "CHANGELOG.md",
]

L’équivalent en ligne de commande :

lucid-lint check --exclude 'vendor/**,**/fixtures/**,CHANGELOG.md' docs

Notes :

• Mise en correspondance. Les motifs glob s’appliquent au chemin relatif à la racine parcourue. Lancer lucid-lint check docs avec exclude = ["drafts/**"] ignore docs/drafts/....
• Élaguer, ne pas visiter. Un dossier qui correspond n’est pas parcouru — les gros arbres exclus ne coûtent rien à traverser.
• Les fichiers nommés explicitement passent quand même. Si vous passez docs/CHANGELOG.md directement en ligne de commande, il est analysé même quand CHANGELOG.md est dans la liste d’exclusion. Si vous le nommez, c’est que vous le voulez.
• Additif. L’option --exclude et le champ TOML exclude se cumulent ; ils ne se remplacent pas. Séparez plusieurs motifs par des virgules dans une option, ou répétez --exclude.

Faire taire des règles globalement

Les documents Markdown acceptent des directives de désactivation en ligne pour faire taire localement, mais le texte brut et l’entrée standard n’ont pas cette porte de sortie. [[ignore]] comble le manque — et fonctionne pareil sur tous les formats d’entrée.

[[ignore]]
rule_id = "unexplained-abbreviation"

[[ignore]]
rule_id = "weasel-words"

Chaque entrée [[ignore]] retire tous les diagnostics dont le rule_id correspond, dans les fichiers Markdown, le texte brut et l’entrée standard. Le filtre s’applique après l’exécution de toutes les règles, mais avant le score, donc le score reflète la vue post-filtre.

Notes :

• Portée globale. Le filtre n’est pas par fichier. Les directives en ligne restent la porte de sortie recommandée pour faire taire ponctuellement en Markdown — utilisez [[ignore]] seulement quand une règle est vraiment bruyante sur tout le projet.
• Identifiants inconnus tolérés. Les entrées qui visent des règles disparues sont retirées sans rien dire, donc retirer une règle dans une version future ne casse pas les anciens fichiers.
• Champs futurs. Un champ reason = "..." sur chaque entrée est suivi par F-suppression-reason-field — quand il arrivera, il sera affiché dans les rapports et exigible par configuration.

Surcharges par règle

La configuration TOML est branchée règle par règle, à mesure que chaque Config reçoit son accesseur dédié. Deux règles l’honorent aujourd’hui :

[rules.readability-score]

[rules.readability-score]
formula = "kandel-moles"  # ou "flesch-kincaid", "auto"

Fixe la formule de lisibilité, quelle que soit la langue détectée. auto (défaut) garde la sélection par langue de F-readability-formulas-extra.

[rules.unexplained-abbreviation]

[rules.unexplained-abbreviation]
whitelist = ["WCAG", "ARIA", "ADHD", "LLM"]

Les entrées sont additives par rapport à la base du profil (F31). Utilisez ce champ pour réintroduire des sigles propres au projet — normes d’accessibilité, sigles métier, termes de pratique d’ingénierie — que la base de v0.2 ne livre plus. Chaque entrée fait taire le sigle dans tout le document, comme si vous l’aviez défini en ligne par Expansion (ACRONYME).

[rules."structure.excessive-commas"]

[rules."structure.excessive-commas"]
max_commas = 2

Surcharge le plafond de virgules par phrase (défaut : 4 / 3 / 2 pour dev-doc / public / falc). La valeur doit être un entier positif — 0 ou une valeur négative est refusée au chargement. La surcharge remplace le préréglage du profil ; elle n’est pas additive.

Les tables pour les autres règles se lisent sans erreur, mais n’ont pas d’effet à l’exécution. Étendre cette liste est un changement mécanique par règle, qui se poursuivra pendant le cycle v0.2.x.

Restreindre l’audit avec --severity-floor

--severity-floor est une option de la ligne de commande (pas une clé de configuration) qui écarte les diagnostics en dessous d’une gravité choisie de toutes les sorties — tty, json et sarif — ainsi que du score. Elle accepte info (défaut), warning ou error. Le filtre s’applique après l’exécution de toutes les règles mais avant le calcul du score : les diagnostics écartés ne comptent donc pas dans le score, et la barrière --min-score voit le même ensemble filtré.

lucid-lint check --severity-floor=warning chemin/vers/docs

• info (défaut) — tout garder. Identique au comportement d’avant l’option ; lorsqu’elle est omise, l’option est sans effet.
• warning — écarter les diagnostics info (signaux d’observabilité comme readability.score), garder warning et au-dessus.
• error — ne garder que les diagnostics error.

Exemple concret — un audit ciblé sur le dépôt de quelqu’un d’autre. Vous relisez un dépôt qui ne vous appartient pas et voulez une passe à fort signal : uniquement les diagnostics sur lesquels agir, rien qui ressemblerait à du bruit dans vos notes de relecture. Relevez le seuil à warning et produisez du JSON pour l’outillage :

lucid-lint check --severity-floor=warning --format=json chemin/vers/leur-depot/docs

Comme le seuil s’applique avant le calcul du score, le score que vous rapportez ne reflète que les constats de gravité warning et au-dessus — la ligne readability.score de niveau info ne le gonfle ni ne le diminue jamais. Combinez-le avec --min-score pour verrouiller la relecture sur cette même vue restreinte. Contrairement à [[ignore]], le seuil ne nécessite aucun fichier de configuration : il convient donc parfaitement à un audit ponctuel d’un dépôt dont vous préférez ne pas toucher le lucid-lint.toml.

Les sous-scores par catégorie suivent le seuil actif. Un sous-score de catégorie ne compte que les diagnostics de gravité égale ou supérieure au seuil actif. Sous un seuil relevé, une catégorie peut afficher un sous-score parfait — par exemple 20/20 — simplement parce que ses diagnostics de niveau info ont été filtrés, et non parce que la prose est irréprochable. Un sous-score élevé sous un seuil relevé n’implique donc pas que la catégorie est exempte de problèmes ; revenez au seuil info par défaut pour avoir une vue complète.

Limitation connue — --severity-floor=error masque actuellement tout. Aucune règle de cette version n’émet de diagnostic de niveau error : --severity-floor=error écarte donc tous les constats et rapporte toujours un score de 100. Le niveau error est une gravité légitime réservée à de futures règles ; tant qu’aucune n’émet à ce niveau, error n’est pas un seuil utile.