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 haya.

Ejecución

• Un analizador debería 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). Se puede escribir en este directorio.
• 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 recibe el 100 % de los recursos de la máquina durante una ventana de 20 segundos por solución. Pasados 20 segundos, el proceso se detiene y se notifica un tiempo de espera agotado.

Formato de salida

analysis.json

El archivo analysis.json debería 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 tienes que hacer dos pequeños cambios» o «El código funciona muy bien, pero hay que hacer un poco de linting». Este resumen se muestra en el sitio web encima de los comentarios.

comments

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

comment

El string de puntero a un archivo de website-copy.

params (opcional)

Un objeto JSON que contiene los parámetros 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 ha usado el estudiante.

Cuando uses archivos con parámetros, 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 type son válidos:

• essential: bloquearemos parcialmente a los estudiantes hasta que hayan atendido este comentario
• actionable: cualquier comentario que da una instrucción concreta al usuario 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 strings en TwoFer, también le hablamos del formateo de strings, pero no sugerimos que sea una opción mejor.
• celebratory: comentarios que dicen a los usuarios que han hecho algo bien, ya sea como comentario general sobre la solución o sobre una técnica.

Los comentarios sin campo type tienen el valor informative por defecto.

Actualmente, en el sitio web aplicamos un bloqueo parcial en los comentarios essential, animamos a los estudiantes a completar los comentarios actionable antes de marcar el ejercicio como completado en los ejercicios de práctica (pero no en los ejercicios de concepto), y no sugerimos ninguna acción en los comentarios informative o celebratory. No obstante, en el futuro es posible que añadamos emojis o indicadores a otros tipos, o que los agrupemos por separado.

tags.json

El archivo tags.json debería tener la siguiente estructura:

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

tags

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

Algunos ejemplos:

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

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

Para más información, consulta Cómo etiquetar soluciones.

Depuración

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

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

Lecturas adicionales

Antes de crear un analizador, lee nuestra Guía de analizadores.