La interfaz del analizador

Todas las interacciones con el sitio web de Exercism se gestionan automáticamente. Los analizadores tienen la única responsabilidad de tomar una solución y devolver un estado y los mensajes que correspondan.

Ejecución

• Un analizador debe proporcionar un script ejecutable. Puedes encontrar más información en el archivo docker.md.
• El script recibirá tres parámetros:
  • El slug del ejercicio (por ejemplo, two-fer).
  • Una ruta a un directorio que contiene los archivos enviados (con una barra al final).
  • Una ruta a un directorio de salida (con una barra al final). Este directorio permite escritura.
• El script debe escribir un archivo analysis.json en el directorio de salida.
• El script debería escribir un archivo tags.json en el directorio de salida.

Tiempo de ejecución permitido

El analizador dispone del 100% de los recursos de la máquina durante una ventana de 20 segundos por solución. Después de 20 segundos, el proceso se detiene y reporta un tiempo de espera agotado.

Formato de salida

analysis.json

El archivo analysis.json debe tener la siguiente estructura:

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

El campo summary es un campo de texto (no Markdown) que resume la salida. Podría decir algo como «Tu solución está casi lista: solo hay dos pequeños cambios que puedes hacer» o «El código funciona muy bien, pero hay un poco de linting que conviene hacer». Este resumen se muestra en el sitio web encima de los comentarios.

comments

El campo comments es un array de comentarios que enlazan a documentos Markdown en exercism/website-copy (consulta Escribir comentarios de analizadores para más información). Cada valor del array es una cadena de puntero o un objeto JSON con el siguiente formato:

comment

La cadena de puntero a un archivo en website-copy.

params (opcional)

Un objeto JSON que contiene los params que se deban interpolar durante el renderizado. Por ejemplo, en el archivo Markdown podrías escribir Try %{variable_name} += 1 instead, y luego establecer params en { "variable_name": "foo"} para sustituir %{variable_name} por la variable real que usó el estudiante.

Cuando uses archivos parametrizados, asegúrate de escapar todos los usos de % colocando otro % delante. por ejemplo, Try aim aim for 100%% of the tests passing.

type (opcional)

Los siguientes valores de type son válidos:

• essential: Aplicamos un bloqueo parcial a los estudiantes hasta que hayan atendido este comentario
• actionable: Cualquier comentario que le dé al usuario una instrucción específica para mejorar su solución
• informative: Comentarios que dan información, pero que no esperan necesariamente que los estudiantes la usen. Por ejemplo, en Ruby, si alguien usa concatenación de cadenas en TwoFer, también le hablamos del formato de cadenas, pero no sugerimos que sea una opción mejor.
• celebratory: Comentarios que les dicen a los usuarios que hicieron algo bien, ya sea como comentario general sobre la solución o sobre una técnica.

Los comentarios sin un campo type usan informative de forma predeterminada.

Actualmente en el sitio web, aplicamos un bloqueo parcial con los comentarios essential, animamos a los estudiantes a completar los comentarios actionable antes de marcar un ejercicio de práctica como completado (pero no en los ejercicios de concepto), y no sugerimos ninguna acción con los comentarios informative o celebratory. Sin embargo, en el futuro podríamos agregar emojis o indicadores a otros tipos, o agruparlos por separado.

tags.json

El archivo tags.json debe tener la siguiente estructura:

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

tags

El campo tags es un array de cadenas. Cada etiqueta tiene el formato: "<category>:<thing>".

Algunos ejemplos son:

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

Las etiquetas se pueden usar para identificar qué construcciones, técnicas o paradigmas usa una solución.

Para más información, consulta Etiquetar soluciones.

Depuración

El contenido de stdout y stderr de cada ejecución se guardará en archivos que podrás ver más tarde.

Puedes escribir un archivo analysis.out con información de depuración que quieras ver más tarde.

Lecturas adicionales

Antes de crear un analizador, lee nuestra guía del analizador.