A interface do analisador

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

Execução

• Um Analyzer deve fornecer um script executável. Você pode encontrar mais informações no arquivo docker.md.
• O script receberá três parâmetros:
  • O slug do exercício (por exemplo, two-fer).
  • Um caminho para um diretório contendo o(s) arquivo(s) enviado(s) (com uma barra no final).
  • Um caminho para um diretório de saída (com uma barra no final). Esse diretório é gravável.
• O script deve escrever um arquivo analysis.json no diretório de saída.
• O script deve escrever um arquivo tags.json no diretório de saída.

Tempo de execução permitido

O analyzer recebe 100% dos recursos da máquina em uma janela de 20 segundos por solução. Depois de 20 segundos, o processo é interrompido e reporta um time-out.

Formato de saída

analysis.json

O arquivo analysis.json deve seguir esta 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. Ele pode dizer algo como "Sua solução está quase pronta: faltam só duas pequenas mudanças que você pode fazer." ou "O código funciona muito bem, mas há um pouco de linting a ser feito.". Esse resumo é exibido no site acima dos comentários.

comments

O campo comments é um array de comentários que apontam para documentos Markdown no exercism/website-copy (veja Escrevendo comentários de Analyzer para mais informações). Cada valor no array é uma string de ponteiro ou um objeto JSON com o seguinte formato:

comment

A string de ponteiro para um arquivo em website-copy.

params (opcional)

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

Ao usar arquivos parametrizados, certifique-se de escapar todos os usos de % colocando outro % na frente dele. Por exemplo, Try aim aim for 100%% of the tests passing.

type (opcional)

Os seguintes valores de type são válidos:

• essential: Vamos aplicar um soft-block nos estudantes até que tenham resolvido este comentário
• actionable: Qualquer comentário que dá uma instrução específica ao usuário para melhorar a solução dele
• informative: Comentários que dão informação, mas que não necessariamente esperam que os estudantes a usem. Por exemplo, em Ruby, se alguém usa concatenação de strings no TwoFer, nós também falamos sobre formatação de strings, mas não sugerimos que seja uma opção melhor.
• celebratory: Comentários que dizem aos usuários que eles fizeram algo certo, seja como um comentário geral sobre a solução ou sobre uma técnica.

Comentários sem um campo type usam informative por padrão.

Atualmente, no site, aplicamos um soft-block em comentários essential, incentivamos os estudantes a resolver os comentários actionable antes de marcar como concluído nos Practice Exercises (mas não nos Concept Exercises), mas não sugerimos nenhuma ação para informative ou celebratory. No entanto, no futuro podemos optar por adicionar emojis ou indicadores a outros tipos, ou agrupá-los separadamente.

tags.json

O arquivo tags.json deve seguir esta 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 quais construções, técnicas ou paradigmas uma solução usa.

Para mais informações, veja Marcando soluções.

Depuração

O conteúdo de stdout e stderr de cada execução será gravado em arquivos que podem ser vistos depois.

Você pode escrever um arquivo analysis.out contendo informações de depuração que você queira ver depois.

Leitura adicional

Antes de construir um analyzer, leia nossas Orientações para Analyzers.