A interface do analisador

Todas as interações com o site do Exercism são tratadas automaticamente. Os analisadores têm a única responsabilidade de receber uma solução e devolver um estado e eventuais mensagens.

Execução

• Um analisador deve disponibilizar um script executável. Podes encontrar mais informação no ficheiro docker.md.
• O script recebe três parâmetros:
  • O slug do exercício (por exemplo, two-fer).
  • Um caminho para um diretório que contém o(s) ficheiro(s) submetido(s) (com uma barra no final).
  • Um caminho para um diretório de saída (com uma barra no final). É possível escrever neste diretório.
• O script tem de escrever um ficheiro analysis.json no diretório de saída.
• O script deve escrever um ficheiro tags.json no diretório de saída.

Tempo de execução permitido

O analisador dispõe de 100% dos recursos da máquina durante uma janela de 20 segundos por solução. Ao fim de 20 segundos, o processo é interrompido e assinala uma expiração do tempo.

Formato da saída

analysis.json

O ficheiro analysis.json deve ter a seguinte estrutura:

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

O campo summary é um campo de texto (não markdown) que resume a saída. Pode dizer algo como «A tua solução está quase lá: só há duas pequenas alterações que podes fazer.» ou «O código funciona muito bem, mas há um pouco de linting que é preciso fazer.». Este resumo é apresentado no site, por cima dos comentários.

comments

O campo comments é um array de comentários que apontam para documentos Markdown em exercism/website-copy (vê Escrever comentários de analisadores para mais informação). Cada valor do array é uma string de apontador ou um objeto JSON com o seguinte formato:

comment

A string de apontador para um ficheiro em website-copy.

params (opcional)

Um objeto JSON com os parâmetros que devem ser interpolados durante a renderização. Por exemplo, no ficheiro markdown podes escrever Try %{variable_name} += 1 instead e depois definir params como { "variable_name": "foo"} para substituir %{variable_name} pela variável que o estudante usou.

Quando usares ficheiros parametrizados, certifica-te de que escapas todos os usos de % colocando outro % à frente. Por exemplo, Try aim aim for 100%% of the tests passing.

type (opcional)

São válidos os seguintes valores de type:

• essential: Bloqueamos suavemente os estudantes até terem tratado deste comentário
• actionable: Qualquer comentário que dá uma instrução específica ao utilizador para melhorar a sua solução
• informative: Comentários que dão informação, mas que não esperam necessariamente que os estudantes a usem. Por exemplo, em Ruby, se alguém usa concatenação de strings no TwoFer, também lhe falamos de formatação de strings, mas não sugerimos que seja uma opção melhor.
• celebratory: Comentários que dizem aos utilizadores que fizeram algo bem, seja como comentário geral sobre a solução, seja sobre uma técnica.

Os comentários sem campo type assumem por omissão informative .

Atualmente, no site, fazemos um bloqueio suave nos comentários essential, incentivamos os estudantes a resolver os comentários actionable antes de marcarem o exercício como concluído nos Exercícios de Prática (mas não nos Exercícios de Conceito), e não sugerimos qualquer ação nos comentários informative ou celebratory. No entanto, no futuro podemos optar por adicionar emojis ou indicadores a outros tipos, ou agrupá-los separadamente.

tags.json

O ficheiro tags.json deve ter a seguinte estrutura:

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

tags

O campo tags é um array de strings. Cada tag tem o formato: "<category>:<thing>".

Alguns exemplos:

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

As tags podem ser usadas para identificar que construções, técnicas e paradigmas uma solução usa.

Para mais informação, vê Marcar soluções com tags.

Depuração

O conteúdo de stdout e stderr de cada execução é guardado em ficheiros que podes consultar mais tarde.

Podes escrever um ficheiro analysis.out com informação de depuração que queiras consultar mais tarde.

Leitura adicional

Antes de construíres um analisador, lê as nossas Orientações para analisadores.