Die Analyzer-Schnittstelle

Alle Interaktionen mit der Exercism-Website werden automatisch abgewickelt. Analyzer haben die einzige Aufgabe, eine Lösung entgegenzunehmen und einen Status sowie eventuelle Nachrichten zurückzugeben.

Ausführung

  • Ein Analyzer sollte ein ausführbares Skript bereitstellen. Weitere Informationen findest du in der Datei docker.md.
  • Das Skript erhält drei Parameter:
    • Den Slug der Übung (z. B. two-fer).
    • Einen Pfad zu einem Verzeichnis mit den eingereichten Dateien (mit einem abschließenden Schrägstrich).
    • Einen Pfad zu einem Ausgabeverzeichnis (mit einem abschließenden Schrägstrich). Dieses Verzeichnis ist beschreibbar.
  • Das Skript muss eine Datei analysis.json in das Ausgabeverzeichnis schreiben.
  • Das Skript sollte eine Datei tags.json in das Ausgabeverzeichnis schreiben.

Erlaubte Laufzeit

Der Analyzer erhält für einen Zeitraum von 20 Sekunden pro Lösung 100 % der Maschinenressourcen. Nach 20 Sekunden wird der Prozess angehalten und meldet eine Zeitüberschreitung.

Note

Wir empfehlen dir dringend, unser Dokument mit bewährten Methoden zur Performance zu befolgen, um die Wahrscheinlichkeit von Zeitüberschreitungen zu verringern.

Ausgabeformat

analysis.json

Die Datei analysis.json sollte wie folgt aufgebaut sein:

{
  "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 (optional)

Das Feld summary ist ein Textfeld (kein Markdown), das die Ausgabe zusammenfasst. Es könnte zum Beispiel so etwas sagen wie „Deine Lösung ist fast am Ziel, du musst nur noch zwei kleine Änderungen vornehmen.“ oder „Der Code funktioniert großartig, aber es gibt noch ein wenig Linting, das erledigt werden muss.“. Diese Zusammenfassung wird auf der Website über den Kommentaren angezeigt.

comments

Das Feld comments ist ein Array von Kommentaren, die auf Markdown-Dokumente in exercism/website-copy verweisen (siehe Analyzer-Kommentare schreiben für weitere Informationen). Jeder Wert im Array ist entweder ein Pointer-String oder ein JSON-Objekt mit dem folgenden Format:

comment

Der Pointer-String zu einer Datei in website-copy.

params (optional)

Ein JSON-Objekt mit beliebigen Parametern, die beim Rendern interpoliert werden sollen. Zum Beispiel könntest du in der Markdown-Datei Try %{variable_name} += 1 instead schreiben und dann params auf { "variable_name": "foo"} setzen, um %{variable_name} durch die tatsächliche Variable zu ersetzen, die der Lernende verwendet hat.

Wenn du parametrisierte Dateien verwendest, stelle sicher, dass du alle Vorkommen von % maskierst, indem du ein weiteres % davor setzt. z. B. Try aim aim for 100%% of the tests passing.

type (optional)

Die folgenden type-Werte sind gültig:

  • essential: Wir soft-blocken Lernende, bis sie diesen Kommentar bearbeitet haben
  • actionable: Jeder Kommentar, der einem Nutzer eine konkrete Anweisung gibt, seine Lösung zu verbessern
  • informative: Kommentare, die Informationen geben, aber nicht unbedingt erwarten, dass die Lernenden sie verwenden. Wenn in Ruby zum Beispiel jemand bei TwoFer String-Verkettung verwendet, weisen wir auch auf String-Formatierung hin, schlagen sie aber nicht als bessere Option vor.
  • celebratory: Kommentare, die Nutzern sagen, dass sie etwas richtig gemacht haben, sei es als allgemeiner Kommentar zur Lösung oder zu einer Technik.

Kommentare ohne ein type-Feld verwenden standardmäßig informative .

Derzeit soft-blocken wir auf der Website bei essential-Kommentaren, ermutigen Lernende, actionable-Kommentare abzuschließen, bevor sie Praxisübungen als abgeschlossen markieren (aber nicht Konzeptübungen), schlagen aber bei informative- oder celebratory-Kommentaren keine Aktion vor. In Zukunft könnten wir jedoch Emojis oder Indikatoren zu anderen Typen hinzufügen oder sie getrennt gruppieren.

tags.json

Die Datei tags.json sollte wie folgt aufgebaut sein:

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

tags

Das Feld tags ist ein Array von Strings. Jedes Tag hat das Format: "<category>:<thing>".

Einige Beispiele:

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

Tags können verwendet werden, um zu erkennen, welche Konstrukte/Techniken/Paradigmen eine Lösung verwendet.

Weitere Informationen findest du unter Lösungen taggen.

Debugging

Die Inhalte von stdout und stderr aus jedem Lauf werden in Dateien gespeichert, die später angesehen werden können.

Du kannst eine Datei analysis.out schreiben, die Debugging-Informationen enthält, die du später ansehen möchtest.

Weiterführende Informationen

Bevor du einen Analyzer baust, lies bitte unsere Analyzer-Richtlinien.