アナライザーのインターフェース

Exercismのウェブサイトとのやり取りは、すべて自動で処理されます。アナライザーには、解答を受け取ってステータスとメッセージを返すという、ただ1つの責務があります。

実行

  • アナライザーは、実行可能なスクリプトを提供するようにしてください。詳しくはdocker.mdを参照してください。
  • スクリプトは、次の3つの引数を受け取ります。
    • 演習のスラッグ（例：two-fer）
    • 提出されたファイルが入っているディレクトリへのパス（末尾にスラッシュが付きます）
    • 出力先ディレクトリへのパス（末尾にスラッシュが付きます）。このディレクトリには書き込みができます。
  • スクリプトは、出力ディレクトリにanalysis.jsonファイルを書き出さなければなりません。
  • スクリプトは、出力ディレクトリにtags.jsonファイルを書き出すようにしてください。

実行時間の上限

アナライザーは、解答1件につき20秒間、マシンのリソースを100%利用できます。 20秒が過ぎると、プロセスは停止され、タイムアウトとして報告されます。

Note

タイムアウトの可能性を減らすために、パフォーマンスのベストプラクティスの文書に目を通すことを強くおすすめします。

出力フォーマット

analysis.json

analysis.jsonファイルは、次のような構造にしてください。

{
  "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（任意）

summaryフィールドは、出力を要約するテキスト（Markdownではありません）のフィールドです。 たとえば、"Your solution is nearly there - there's just two small changes you can make."や"The code works great, but there's a little bit of linting that needs doing."といった内容を書きます。 この要約は、ウェブサイト上でコメントの上に表示されます。

comments

commentsフィールドは、exercism/website-copy内のMarkdown文書を参照するコメントの配列です（詳しくはアナライザーのコメントの書き方を参照してください）。 配列の各要素は、ファイルを指す文字列か、次の形式のJSONオブジェクトです。

comment

website-copy内のファイルを指す文字列です。

params（任意）

レンダリング時に埋め込まれるパラメータを格納するJSONオブジェクトです。 たとえば、MarkdownファイルにTry %{variable_name} += 1 insteadと書き、paramsを{ "variable_name": "foo"}に設定すると、%{variable_name}が学習者の使った実際の変数に置き換わります。

パラメータ化されたファイルを使う場合は、%の直前に%をもう1つ置いて、すべての%をエスケープしてください。 例：Try aim aim for 100%% of the tests passing

type（任意）

有効なtypeは次のとおりです。

  • essential：学習者がこのコメントに対応するまで、ソフトブロックします
  • actionable：解答を改善するための具体的な指示を学習者に伝えるコメントです
  • informative：情報を伝えるコメントですが、学習者が必ずしもそれを使うことは想定していません。たとえばRubyで、誰かがTwoFerで文字列連結を使った場合、文字列フォーマットについても伝えますが、そちらのほうが良い選択肢だとは示しません。
  • celebratory：ユーザーがうまくできた点を伝えるコメントです。解答全体についての一般的なコメントの場合もあれば、あるテクニックについてのコメントの場合もあります。

typeフィールドがないコメントは、デフォルトでinformative になります。

現在のウェブサイトでは、essentialのコメントではソフトブロックし、Practice Exercisesでは完了としてマークする前にactionableのコメントに対応するよう学習者に促しますが（Concept Exercisesでは促しません）、informativeやcelebratoryでは何のアクションも求めていません。 ただし、将来的には他のタイプに絵文字やインジケーターを付けたり、別のグループに分けたりする可能性があります。

tags.json

tags.jsonファイルは、次のような構造にしてください。

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

tags

tagsフィールドは文字列の配列です。 各タグは"<category>:<thing>"の形式で書きます。

たとえば、次のようなものです。

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

タグを使うと、その解答がどんな構成要素・テクニック・パラダイムを使っているかを特定できます。

詳しくは、解答へのタグ付けを参照してください。

デバッグ

各実行のstdoutとstderrの内容はファイルに保存され、あとから確認できます。

あとから確認したいデバッグ情報をまとめたanalysis.outファイルを書き出してもかまいません。

参考資料

アナライザーを作る前に、アナライザーガイダンスに目を通してください。