L'interface de l'analyseur

Toutes les interactions avec le site Exercism sont gérées automatiquement. Les analyseurs ont une seule responsabilité : prendre une solution et renvoyer un statut ainsi que d'éventuels messages.

Exécution

• Un analyseur doit fournir un script exécutable. Tu trouveras plus d'informations dans le fichier docker.md.
• Le script recevra trois paramètres :
  • Le slug de l'exercice (par exemple two-fer).
  • Un chemin vers un répertoire contenant le ou les fichiers soumis (suivi d'une barre oblique).
  • Un chemin vers un répertoire de sortie (suivi d'une barre oblique). Ce répertoire est accessible en écriture.
• Le script doit écrire un fichier analysis.json dans le répertoire de sortie.
• Le script devrait écrire un fichier tags.json dans le répertoire de sortie.

Durée d'exécution autorisée

L'analyseur dispose de 100 % des ressources de la machine pendant une fenêtre de 20 secondes par solution. Au bout de 20 secondes, le processus est arrêté et signale un dépassement de délai.

Format de sortie

analysis.json

Le fichier analysis.json doit être structuré comme suit :

{
  "summary": "This solution looks good but has a few points to address",
  "comments": [
    {
      "comment": "ruby.general.some_parameterised_message",
      "params": { "foo": "param1", "bar": "param2" },
      "type": "essential"
    },
    {
      "comment": "ruby.general.some_unparameterised_message",
      "params": {},
      "type": "actionable"
    },
    {
      "comment": "ruby.general.some_unparameterised_message"
    },
    "ruby.general.some_unparameterised_message"
  ]
}

summary (facultatif)

Le champ summary est un champ texte (et non du markdown) qui résume la sortie. Il pourrait par exemple afficher « Ta solution est presque au bout, il ne reste que deux petits changements à faire. » ou « Le code fonctionne très bien, mais il y a un peu de nettoyage à faire. ». Ce résumé est affiché sur le site au-dessus des commentaires.

comments

Le champ comments est un tableau de commentaires qui pointent vers des documents Markdown dans exercism/website-copy (voir Écrire des commentaires d'analyseur pour plus d'informations). Chaque valeur du tableau est soit une chaîne pointeur, soit un objet JSON au format suivant :

comment

La chaîne pointeur vers un fichier dans website-copy.

params (facultatif)

Un objet JSON contenant les éventuels params à interpoler lors du rendu. Par exemple, dans le fichier markdown, tu peux écrire Try %{variable_name} += 1 instead, puis définir params sur { "variable_name": "foo"} afin de remplacer %{variable_name} par la variable que l'apprenant a réellement utilisée.

Lorsque tu utilises des fichiers paramétrés, pense à échapper tous les % en plaçant un autre % devant. Par exemple, Try aim aim for 100%% of the tests passing.

type (facultatif)

Les valeurs de type suivantes sont valides :

• essential : nous bloquons temporairement les apprenants tant qu'ils n'ont pas traité ce commentaire
• actionable : tout commentaire qui donne à l'utilisateur une instruction précise pour améliorer sa solution
• informative : des commentaires qui apportent une information, sans forcément attendre des apprenants qu'ils l'utilisent. Par exemple, en Ruby, si quelqu'un utilise la concaténation de chaînes dans TwoFer, nous lui parlons aussi du formatage de chaînes, sans suggérer que c'est une meilleure option.
• celebratory : des commentaires qui indiquent aux utilisateurs qu'ils ont bien fait quelque chose, que ce soit en général sur la solution ou sur une technique.

Les commentaires dépourvus de champ type prennent la valeur informative par défaut.

Actuellement sur le site, nous bloquons temporairement sur les commentaires essential, nous encourageons les apprenants à traiter les commentaires actionable avant de marquer un exercice d'entraînement comme terminé (mais pas un exercice d'apprentissage), et nous ne suggérons aucune action pour les commentaires informative ou celebratory. Cependant, à l'avenir, nous pourrions ajouter des emojis ou des indicateurs à d'autres types, ou les regrouper différemment.

tags.json

Le fichier tags.json doit être structuré comme suit :

{
  "tags": [
    "construct:list",
    "paradigm:functional",
    "technique:higher-order-functions",
    "uses:List.unfold"
  ]
}

tags

Le champ tags est un tableau de strings. Chaque tag est formaté ainsi : "<category>:<thing>".

Voici quelques exemples :

• "paradigm:functional"
• "technique:recursion"
• "construct:bitwise-and"
• "uses:DateTime.add_seconds"

Les tags permettent d'identifier les constructions, les techniques ou les paradigmes qu'une solution utilise.

Pour plus d'informations, voir Étiqueter les solutions.

Débogage

Le contenu de stdout et de stderr de chaque exécution est conservé dans des fichiers que l'on peut consulter plus tard.

Tu peux écrire un fichier analysis.out contenant des informations de débogage que tu souhaites consulter plus tard.

Pour aller plus loin

Avant de créer un analyseur, pense à lire notre guide des analyseurs.