쿼리 도움말 파일 테스트하기

쿼리 도움말 파일 테스트 알아보기

쿼리 도움말 파일을 Markdown으로 렌더링하여 테스트함으로써 CodeQL 리포지토리에 업로드하거나 코드 스캔에서 사용하기 전에 유효한지 확인합니다.

쿼리 도움말은 쿼리와 함께 제공되는 설명서로, 쿼리가 작동하는 방식을 설명하고 쿼리가 식별하는 잠재적인 문제에 대한 정보를 제공합니다. 모든 새 쿼리에 대해 쿼리 도움말을 작성하는 것이 좋습니다. 자세한 내용은 CodeQL 리포지토리에서 CodeQL에 기여하기를 참조하세요.

CodeQL CLI에는 쿼리 도움말을 테스트하고 콘텐츠를 Markdown으로 렌더링하여 IDE의 콘텐츠를 쉽게 미리 볼 수 있는 명령이 포함되어 있습니다. 이 명령을 사용하여 CodeQL 리포지토리에 업로드하거나 다른 사용자와 공유하기 전에 쿼리 도움말 파일의 유효성을 검사합니다. CodeQL CLI 2.7.1부터 CodeQL 분석 중에 생성된 SARIF 파일에 Markdown 렌더링된 쿼리 도움말을 포함할 수도 있으므로 코드 스캔 UI에 쿼리 도움말을 표시할 수 있습니다. 자세한 내용은 CodeQL 쿼리를 사용하여 코드 분석을(를) 참조하세요.

필수 조건

• 쿼리 도움말(.qhelp) 파일에는 동일한 기본 이름을 가진 함께 제공되는 쿼리(.ql) 파일이 있어야 합니다.
• 쿼리 도움말 파일은 쿼리 도움말 설명서의 표준 구조와 스타일을 따라야 합니다. 자세한 내용은 CodeQL 리포지토리의 쿼리 도움말 스타일 가이드를 참조하세요.

codeql generate query-help 실행

다음 명령을 실행하여 쿼리 도움말 파일을 테스트할 수 있습니다.

codeql generate query-help <qhelp|query|dir|suite> --format=<format> [--output=<dir|file>]

이 명령의 경우 <qhelp|query|dir|suite>는 .qhelp 파일의 경로, .ql 파일의 경로, 쿼리 및 쿼리 도움말 파일이 포함된 디렉터리의 경로 또는 쿼리 집합의 경로여야 합니다.

쿼리 도움말이 렌더링되는 방법을 정의하는 --format 옵션을 지정해야 합니다. 지금은 쿼리 도움말을 Markdown으로 렌더링하도록 markdown을(를) 지정해야 합니다.

이 --output 옵션은 렌더링된 쿼리 도움말을 저장할 파일 경로를 정의합니다.

• .qhelp 파일이 포함된 디렉터리 또는 하나 이상의 .qhelp 파일을 정의하는 쿼리 모음의 경우 --output 디렉터리를 지정해야 합니다. 출력 디렉터리 내의 파일 이름은 .qhelp 파일 이름에서 파생됩니다.
• 단일 .qhelp 또는 .ql 파일의 경우 --output 옵션을 지정할 수 있습니다. 출력 경로를 지정하지 않으면 렌더링된 쿼리 도움말이 stdout에 기록됩니다.

쿼리 도움말 파일을 테스트할 때 사용할 수 있는 모든 옵션에 대한 전체 내용은 generate query-help을(를) 참조하세요.

결과

명령을 실행하면 CodeQL이(가) 함께 제공되는 .ql 파일이 있는 각 .qhelp 파일의 렌더링을 시도합니다. 단일 파일의 경우 --output 옵션을 지정하지 않으면 렌더링된 콘텐츠가 stdout에 인쇄됩니다. 다른 모든 사용 사례의 경우 렌더링된 콘텐츠는 지정된 출력 경로에 저장됩니다.

기본적으로 CodeQL CLI은(는) 다음과 같은 경우에 경고 메시지를 인쇄합니다.

• 쿼리 도움말 요소에 대한 유효하지 않은 설명이 있고 쿼리 도움말이 유효하지 않습니다.
• 명령에 지정된 .qhelp 파일의 기본 이름이 함께 제공되는 .ql 파일과 동일하지 않습니다.
• 명령에 지정된 .ql 파일의 기본 이름이 함께 제공되는 .qhelp 파일과 동일하지 않습니다.

명령에 --warnings 옵션을 포함하여 CodeQL CLI에 이러한 경고를 처리하는 방법을 알릴 수 있습니다. 자세한 내용은 generate query-help을(를) 참조하세요.

추가 참고 자료

• 쿼리 도움말 파일