Severities and fix levelsSévérités et niveaux de fix
How bad an issue is, who can fix it, and what is counted in the exit status.La gravité d'un problème, qui peut le corriger, et ce qui compte dans le code de sortie.
In one sentence: every issue has a severity (how bad it is) and a fix level (who may fix it): the first decides if the run fails, the second what --fix is allowed to change.
Definition: two independent attributes per rule, read from the rule table (xstyle --list-rules): Severity ∈ {Unforgivable, Major, Minor, Negligible, Mandatory} drives the counters, --severity and --fail-on; FixMode ∈ {Auto, Force, Dangerous, Ask, Manual} drives which fixes --fix applies.
En une phrase : chaque problème a une sévérité (sa gravité) et un niveau de fix (qui a le droit de le corriger) : la première décide si le lancement échoue, le second ce que --fix peut changer.
Définition : deux attributs indépendants par règle, lus dans la table des règles (xstyle --list-rules) : Severity ∈ {Unforgivable, Major, Minor, Negligible, Mandatory} pilote les compteurs, --severity et --fail-on ; FixMode ∈ {Auto, Force, Dangerous, Ask, Manual} pilote les corrections que --fix applique.
1. The ideaL'idée
Think of a teacher correcting a copy. Some mistakes cost the grade (a wrong answer), some only cost a point (a missing accent). And some the teacher fixes in red, while others are only circled: you must rewrite them yourself. xstyle does the same: the severity is the cost of the mistake, the fix level says if xstyle writes the correction or only circles it.
Severity and fix level are orthogonal: CPP-USING-NAMESPACE is unforgivable and manual, G-TRAILING is minor and auto. The severity filters the report (-s) and the exit status (--fail-on); the fix level filters what --fix touches (--force, --dangerous-force) and can filter the report too (-m).
Pense à un prof qui corrige une copie. Certaines fautes coûtent la note (une mauvaise réponse), d'autres un point (un accent oublié). Et certaines, le prof les corrige en rouge, d'autres il les entoure seulement : à toi de les réécrire. xstyle fait pareil : la sévérité est le coût de la faute, le niveau de fix dit si xstyle écrit la correction ou l'entoure seulement.
Sévérité et niveau de fix sont orthogonaux : CPP-USING-NAMESPACE est unforgivable et manual, G-TRAILING est minor et auto. La sévérité filtre le rapport (-s) et le code de sortie (--fail-on) ; le niveau de fix filtre ce que --fix touche (--force, --dangerous-force) et peut filtrer le rapport aussi (-m).
2. The severity scaleL'échelle des sévérités
| Severity | Letter in --rtk | Example |
|---|---|---|
unforgivable | U | CPP-USING-NAMESPACE: using namespace |
major | M | CPP-NULL: NULL instead of nullptr |
minor | m | G-TRAILING: trailing whitespace |
negligible | n | G-EOF-NEWLINE: no newline at the end of the file |
-s major shows only the two worst levels. --fail-on major makes the run fail only when one of them is left.
-s <level> is the minimal severity reported (default negligible); -F / --fail-on <level> the minimal severity that makes the exit status 1 (default negligible: any issue). Both are cumulative upwards: major includes unforgivable.
| Sévérité | Lettre dans --rtk | Exemple |
|---|---|---|
unforgivable | U | CPP-USING-NAMESPACE : using namespace |
major | M | CPP-NULL : NULL au lieu de nullptr |
minor | m | G-TRAILING : espaces en fin de ligne |
negligible | n | G-EOF-NEWLINE : pas de retour à la ligne en fin de fichier |
-s major n'affiche que les deux pires niveaux. --fail-on major ne fait échouer le lancement que s'il en reste un.
-s <niveau> est la sévérité minimale affichée (par défaut negligible) ; -F / --fail-on <niveau> la sévérité minimale qui met le code de sortie à 1 (par défaut negligible : n'importe quel problème). Les deux incluent les niveaux au-dessus : major comprend unforgivable.
3. The mandatory rule R34La règle obligatoire R34
R34 is the only rule of the severity mandatory, outside the scale: Rule 34: if it exists, there is porn of it. No exceptions. It is a reminder, not a style rule.
| R34 | |
|---|---|
| Displayed | once per run, with a link to the article; a ! R34 ... line in --rtk |
| Counted | never: not in the totals, the exit status, --fail-on nor the hook |
| Hidden by | the integer 34 or r34 (any case) in a checked file, a file R34.md in the directory of the run, --r34, XSTYLE_R34=1 |
| Fix | xstyle --fix --force writes R34.md (never replaces an existing one) |
R34 est la seule règle de sévérité mandatory, hors de l'échelle : Rule 34: if it exists, there is porn of it. No exceptions. C'est un rappel, pas une règle de style.
| R34 | |
|---|---|
| Affichée | une fois par lancement, avec un lien vers l'article ; une ligne ! R34 ... en --rtk |
| Comptée | jamais : ni dans les totaux, ni le code de sortie, ni --fail-on, ni le hook |
| Masquée par | l'entier 34 ou r34 (toute casse) dans un fichier vérifié, un fichier R34.md dans le dossier du lancement, --r34, XSTYLE_R34=1 |
| Correction | xstyle --fix --force écrit R34.md (ne remplace jamais un fichier existant) |
4. Fix levelsNiveaux de fix
| Tag | Fixed by | Meaning |
|---|---|---|
[auto-fix] | --fix | safe, the behavior can't change: spaces, includes order, nullptr... |
[force-fix] | --fix --force | can change the behavior: set -euo pipefail, encoding="utf-8", a comment replaced |
[danger-fix] | --fix --dangerous-force | guessed, can be wrong: Python types from the usage, static_cast of a C pointer cast |
[ask-fix] | --fix + a question | the missing file header: banner and description asked per file (--header answers) |
[manual] | by hand | a decision a tool can't take: a type, a name, a rewrite with libutils |
Start with --fix only. Look at what --force would do with -n (nothing is written), then decide.
--dangerous-force implies --force. Without a terminal (CI) the [ask-fix] header is skipped unless --header none|default|<text> is given. -m auto,force,dangerous,ask,manual keeps only these levels in the display, the counters, the report and --fix (xstyle --fix --force -m auto applies only the safe fixes).
| Tag | Corrigé par | Sens |
|---|---|---|
[auto-fix] | --fix | sûr, le comportement ne peut pas changer : espaces, ordre des includes, nullptr... |
[force-fix] | --fix --force | peut changer le comportement : set -euo pipefail, encoding="utf-8", un commentaire remplacé |
[danger-fix] | --fix --dangerous-force | deviné, peut être faux : types Python tirés de l'usage, static_cast d'un cast de pointeur C |
[ask-fix] | --fix + une question | l'en-tête de fichier manquant : bannière et description demandées par fichier (--header répond) |
[manual] | à la main | une décision qu'un outil ne peut pas prendre : un type, un nom, une réécriture avec libutils |
Commence par --fix seul. Regarde ce que ferait --force avec -n (rien n'est écrit), puis décide.
--dangerous-force implique --force. Sans terminal (CI), l'en-tête [ask-fix] est sauté sauf si --header none|default|<texte> est donné. -m auto,force,dangerous,ask,manual ne garde que ces niveaux dans l'affichage, les compteurs, le rapport et --fix (xstyle --fix --force -m auto n'applique que les corrections sûres).
5. PitfallsPièges
-shides issues but does not change the exit status: use--fail-onfor that.-snever hides R34;-c/-i/-mselect it like any other rule.- A
[force-fix]can change what a script does:set -euo pipefailstops it at the first failing command.
-smasque des problèmes mais ne change pas le code de sortie : c'est le rôle de--fail-on.-sne masque jamais R34 ;-c/-i/-mla sélectionnent comme toute autre règle.- Un
[force-fix]peut changer ce que fait un script :set -euo pipefaill'arrête à la première commande en échec.
6. Check yourselfVérifie-toi
Does xstyle -s major exit with 0 when only minor issues are left?
No: -s only hides them, the exit status still counts them. --fail-on major gives 0.
Which flag applies the guessed Python type hints?
--fix --dangerous-force: they are [danger-fix].
Can R34 make a pre-commit hook refuse a commit?
No, a mandatory rule is never counted.
xstyle -s major sort-il avec 0 quand il ne reste que des problèmes minor ?
Non : -s les masque seulement, le code de sortie les compte encore. --fail-on major donne 0.
Quel flag applique les types Python devinés ?
--fix --dangerous-force : ce sont des [danger-fix].
R34 peut-elle faire refuser un commit par le hook pre-commit ?
Non, une règle obligatoire n'est jamais comptée.
7. GlossaryGlossaire
| Term | Meaning |
|---|---|
| Severity | how bad an issue is, from negligible to unforgivable |
| Fix level | who may fix it: --fix, --force, --dangerous-force, a question, or you |
--fail-on | the severity from which the exit status is 1 |
| Mandatory | displayed, never counted (only R34) |
Source: include/xstyle/XStyleType.hpp (Severity, FixMode) and src/xstyle/Rules.cpp of the repository.
| Terme | Sens |
|---|---|
| Sévérité | la gravité d'un problème, de negligible à unforgivable |
| Niveau de fix | qui peut le corriger : --fix, --force, --dangerous-force, une question, ou toi |
--fail-on | la sévérité à partir de laquelle le code de sortie vaut 1 |
| Obligatoire | affichée, jamais comptée (seulement R34) |
Source : include/xstyle/XStyleType.hpp (Severity, FixMode) et src/xstyle/Rules.cpp du dépôt.