분석기 인터페이스

Exercism 웹사이트와의 모든 상호작용은 자동으로 처리돼요. 분석기는 풀이를 받아 상태와 메시지를 반환하는 단 하나의 책임만 가져요.

실행

  • 분석기는 실행 가능한 스크립트를 제공해야 해요. 자세한 내용은 docker.md 파일에서 확인할 수 있어요.
  • 스크립트는 세 개의 매개변수를 받아요:
    • 연습 문제의 슬러그 (예: two-fer).
    • 제출된 파일이 들어 있는 디렉터리 경로 (끝에 슬래시가 붙어 있어요).
    • 출력 디렉터리 경로 (끝에 슬래시가 붙어 있어요). 이 디렉터리에는 쓸 수 있어요.
  • 스크립트는 출력 디렉터리에 analysis.json 파일을 반드시 써야 해요.
  • 스크립트는 출력 디렉터리에 tags.json 파일을 쓰는 게 좋아요.

허용 실행 시간

분석기는 풀이 하나당 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 필드는 출력을 요약하는 텍스트(마크다운 아님) 필드예요. "풀이가 거의 다 됐어요. 작은 변경 두 가지만 하면 돼요."라든가 "코드는 훌륭하게 동작하는데, 린팅을 조금 손봐야 해요." 같은 내용을 담을 수 있어요. 이 요약은 웹사이트에서 코멘트 위에 표시돼요.

comments

comments 필드는 exercism/website-copy의 마크다운 문서를 가리키는 코멘트 배열이에요 (자세한 내용은 분석기 코멘트 작성하기를 참고해요). 배열의 각 값은 포인터 문자열이거나 다음과 같은 형식의 JSON 객체예요:

comment

website-copy에 있는 파일을 가리키는 포인터 문자열이에요.

params (선택 사항)

렌더링할 때 보간해야 하는 매개변수를 담은 JSON 객체예요. 예를 들어 마크다운 파일에 Try %{variable_name} += 1 instead라고 쓰고, params를 { "variable_name": "foo"}로 설정하면 학생이 실제로 사용한 변수로 %{variable_name}을 치환할 수 있어요.

매개변수를 사용하는 파일에서는 % 앞에 %를 하나 더 붙여서 모든 %를 이스케이프해야 해요. 예: Try aim aim for 100%% of the tests passing.

type (선택 사항)

다음 type 값들이 유효해요:

  • essential: 학생이 이 코멘트를 처리할 때까지 소프트 차단해요
  • actionable: 사용자가 풀이를 개선할 수 있도록 구체적인 지침을 주는 코멘트예요
  • informative: 정보를 주지만 학생이 꼭 활용할 거라고 기대하지는 않는 코멘트예요. 예를 들어 Ruby에서 누군가 TwoFer에 문자열 연결을 사용하면 문자열 포매팅에 대해서도 알려주지만, 그것이 더 나은 선택이라고 제안하지는 않아요.
  • celebratory: 사용자가 무언가를 제대로 했다고 알려주는 코멘트예요. 풀이 전반에 대한 코멘트일 수도 있고, 특정 기법에 대한 코멘트일 수도 있어요.

type 필드가 없는 코멘트는 기본값이 informative 예요.

현재 웹사이트에서는 essential 코멘트에 소프트 차단을 하고, actionable 코멘트는 실습 문제에서 완료로 표시하기 전에 학생이 처리하도록 권장하지만(개념 문제에서는 아님), 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 파일을 작성해도 돼요.

더 읽어보기

분석기를 만들기 전에 분석기 가이드를 읽어보세요.