Codes de retour

Chaque processus gapline sort avec l’un des cinq codes. Les scripts CI devraient brancher sur le code de retour plutôt que de parser stdout — les codes sont stables entre releases.

Table canonique

Code	Nom	Signification
0	SUCCESS	L’opération s’est terminée normalement. Émis aussi quand l’utilisateur a refusé un prompt interactif (pas une erreur — un abort explicite).
1	COMMAND_FAILED	Échec générique : validation avec erreurs, requête --where invalide, champ inconnu dans --set, violation de clé primaire ou étrangère.
2	CONFIG_ERROR	gapline.toml malformé, clé inconnue, type incompatible sur un seuil. Problèmes de config, pas de runtime.
3	INPUT_ERROR	Erreur I/O : fichier flux absent, archive illisible, sortie non-écrivable, permission refusée.
4	NO_CHANGES	L’opération n’a matché personne et rien n’a été écrit. Distinct de SUCCESS pour qu’un script puisse distinguer “update a tourné et changé zéro lignes” de “update a tourné et changé N lignes”.

Émissions par commande

Toutes les commandes n’émettent pas tous les codes. Le tableau suivant résume.

Commande	0	1	2	3	4
validate	✅	✅	✅	✅
read	✅	✅	✅	✅
create	✅	✅	✅	✅
update	✅	✅	✅	✅	✅
delete	✅	✅	✅	✅	✅
run	✅	✅	✅	✅	✅
rules list	✅		✅	✅
completion	✅			✅

Patterns CI

Échouer uniquement sur les erreurs de validation

gapline validate -f gtfs.zip
case $? in
  0) echo "Flux propre." ;;
  1) echo "Flux avec erreurs ERROR." ; exit 1 ;;
  2|3) echo "Problème de setup gapline, à investiguer." ; exit 1 ;;
esac

Distinguer “aucun match” d’un bulk update réussi

gapline update routes -f gtfs.zip --where "route_type=700" --set route_type=3 --confirm
case $? in
  0) echo "Lignes mises à jour." ;;
  4) echo "Rien à mettre à jour — déjà migré." ;;
  *) echo "Update échoué." ; exit 1 ;;
esac

GitHub Actions

- run: gapline validate -f gtfs.zip --min-severity error
  # Le job échoue automatiquement sur code 1+ — pas de branching en plus.

Pourquoi cette découpe

Les cinq codes sont délibérément étroits. Ils sont choisis pour répondre à trois questions qu’un script wrapper se pose habituellement :

1. gapline a-t-il tourné ? (distingue SUCCESS/COMMAND_FAILED/NO_CHANGES de CONFIG_ERROR/INPUT_ERROR)
2. Est-ce le flux ou la config en cause ? (CONFIG_ERROR vs le reste)
3. Quelque chose a-t-il réellement changé ? (NO_CHANGES vs SUCCESS sur les commandes d’écriture)

Tout ce qui est plus fin — “quelle règle a échoué”, “combien d’anomalies” — appartient au rapport structuré (--format json), pas au code de retour.

Voir aussi

• Concepts / Sévérités — comment --min-severity contrôle quand COMMAND_FAILED est émis.
• Guides / Intégration CI — recettes de pipeline.