Code Quality

Code Qualityは、技術的負債になる前に保守性の問題を特定します。コードレビュー中に自動的に行われるフィードバックにより、チームはより良いコードを書くことができます。検出結果はマージリクエストに直接表示されるため、最もコスト効率よく修正できるタイミングで問題を把握できます。

Code Qualityは複数のプログラミング言語に対応しており、一般的なLinter、スタイルチェッカー、複雑性アナライザーと統合できます。既存のツールをCode Qualityワークフローに組み込むことで、結果の表示方法を標準化しながら、チーム独自の設定を維持できます。

プランごとの機能

次の表に示すように、利用できる機能はGitLabのプランによって異なります:

コードをスキャンして品質違反を検出する

Code Qualityは、多くのスキャンツールからの結果のインポートをサポートするオープンシステムです。違反を見つけて表示するには、以下の手順を実行します:

• スキャンツールを直接使用して、結果をインポートする。（推奨）
• 組み込みのCI/CDテンプレートを使用してスキャンを有効にする。このテンプレートでは、一般的なオープンソースツールをラップするCodeClimateエンジンを使用しています。（非推奨）

1つのパイプラインで、複数のツールから結果をキャプチャできます。たとえば、コードをスキャンするコードLinterと、ドキュメントをスキャンする言語Linterを一緒に実行したり、スタンドアロンツールとCodeClimateベースのスキャンを組み合わせて使用したりできます。Code Qualityはすべてのレポートを統合するため、結果を表示する際にすべてのレポートを確認できます。

CI/CDジョブからCode Qualityの結果をインポートする

多くの開発チームではすでに、Linter、スタイルチェッカー、その他のツールをCI/CDパイプラインで使用し、コーディング標準の違反を自動的に検出しています。これらのツールをCode Qualityと統合することで、検出結果を簡単に確認して修正できるようになります。

お使いのツールにドキュメント化された統合が存在するかを確認するには、一般的なツールをCode Qualityと統合するを参照してください。

別のツールをCode Qualityと統合するには、以下を実行します:

1. CI/CDパイプラインにツールを追加します。
2. レポートをファイルとして出力するようにツールを設定します。
   • このファイルは特定のJSON形式を使用する必要があります。
   • 多くのツールはこの出力形式をネイティブにサポートしています。これらのツールでは、この形式を「CodeClimateレポート」や「GitLab Code Qualityレポート」、または類似の名称で呼ぶことがあります。
   • 他のツールでは、カスタムJSON形式またはテンプレートを使用してJSON出力を生成できることがあります。レポート形式の必須フィールドは少ないため、この出力タイプを使用してCode Quality向けのレポートを作成できる場合があります。
3. このファイルに対応するcodequalityレポートアーティファクトを宣言します。

これで、パイプラインを実行すると、品質ツールの結果が処理および表示されます。

組み込みのCode Quality CI/CDテンプレートを使用する（非推奨）

Code Qualityには、組み込みのCI/CDテンプレートCode-Quality.gitlab-ci.yamlも含まれています。このテンプレートは、オープンソースのCodeClimateスキャンエンジンに基づいてスキャンを実行します。

CodeClimateエンジンは以下を実行します:

• サポート対象の言語セットの基本的な保守性チェック。
• ソースコードを分析するための、オープンソーススキャナーをラップした設定可能なプラグインのセット。

詳細については、CodeClimateベースのCode Qualityスキャンを設定するを参照してください。

CodeClimateベースのスキャンから移行する

CodeClimateエンジンは、カスタマイズ可能な分析プラグインのセットを使用します。一部はデフォルトで有効になっていますが、それ以外は明示的に有効にする必要があります。組み込みのプラグインを置き換えるために、次の統合を利用できます:

Code Qualityの結果を表示する

Code Qualityの結果は次の場所に表示されます:

• マージリクエストウィジェット
• マージリクエストの変更ビュー
• パイプラインの詳細ビュー
• プロジェクトの品質ビュー

マージリクエストウィジェット

ターゲットブランチに比較用のレポートがある場合、Code Qualityの分析結果がマージリクエストウィジェット領域に表示されます。マージリクエストウィジェットには、マージリクエストで行われた変更によって発生したCode Qualityの検出結果と解決事項が表示されます。同一のフィンガープリントを持つ複数のCode Qualityの検出結果は、マージリクエストのウィジェットでは単一のエントリとして表示されます。個々の検出結果は、パイプラインの詳細ビューで参照できる完全なレポートで確認できます。

マージリクエストの変更ビュー

Code Qualityの結果は、マージリクエストの変更ビューに表示されます。Code Qualityの問題を含む行は、ガターの横に記号でマークされます。記号を選択すると問題のリストが表示され、問題を選択するとその詳細が表示されます。

パイプラインの詳細ビュー

パイプラインによって生成されたCode Qualityの違反の完全なリストは、パイプラインの詳細ページのCode Qualityタブに表示されます。パイプラインの詳細ビューには、パイプラインが実行されたブランチで検出されたすべてのCode Qualityの検出結果が表示されます。

プロジェクトの品質ビュー

プロジェクトの品質ビューに、コード品質の検出結果の概要が表示されます。このビューは分析 > CI/CD分析で確認できます。また、特定のプロジェクトに対してproject_quality_summary_page機能フラグを有効にする必要があります。

Code Qualityのレポート形式

次の形式でレポートを出力できる任意のツールから、Code Qualityの結果をインポートできます。この形式は、CodeClimateレポート形式の一種で、フィールド数が少なくなっています。

Code Qualityレポートアーティファクトとして提供するファイルには、単一のJSON配列を含める必要があります。その配列内の各オブジェクトには、少なくとも次のプロパティが必要です:

この形式は、次の点でCodeClimateレポート形式と異なります:

• CodeClimateレポート形式は、より多くのプロパティをサポートしていますが、Code Qualityは前述のフィールドのみを処理します。
• GitLabパーサーは、先頭にバイトオーダーマーク（BOM）があるファイルを処理できません。

以下に、準拠した形式のレポートの例を示します:

[
  {
    "description": "'unused' is assigned a value but never used.",
    "check_name": "no-unused-vars",
    "fingerprint": "7815696ecbf1c96e6894b779456d330e",
    "severity": "minor",
    "location": {
      "path": "lib/index.js",
      "lines": {
        "begin": 42
      }
    }
  }
]

一般的なツールをCode Qualityと統合する

多くのツールは、結果をCode Qualityと統合するために必要なレポート形式をネイティブにサポートしています。これらのツールでは、この形式を「CodeClimateレポート」や「GitLab Code Qualityレポート」、または類似の名称で呼ぶことがあります。

その他のツールは、カスタムテンプレートまたは形式の仕様を指定することで、JSON出力を生成するように設定できます。レポート形式の必須フィールドは少ないため、この出力タイプを使用してCode Quality向けのレポートを作成できる場合があります。

CI/CDパイプラインですでにツールを使用している場合は、既存のジョブを調整してCode Qualityレポートを追加することが推奨されます。既存のジョブを調整することで、デベロッパーを混乱させたり、パイプラインの実行時間を長くしたりする可能性のある別のジョブを実行せずに済みます。

ツールをまだ使用していない場合は、CI/CDジョブを一から作成するか、CI/CDカタログのコンポーネントを使用してツールを導入できます。

コードスキャンツール

ESLint

CI/CDパイプラインにすでにESLintジョブがある場合は、その出力をCode Qualityに送信するためにレポートを追加する必要があります。出力を統合するには、以下を実行します:

1. プロジェクトに開発依存関係としてeslint-formatter-gitlabを追加します。
2. ESLintの実行に使用するコマンドに--format gitlabオプションを追加します。
3. レポートファイルの場所を指すcodequalityレポートアーティファクトを宣言します。
   • デフォルトでは、フォーマッターはCI/CD設定を読み取り、レポートを保存するファイル名を推測します。フォーマッターがアーティファクトの宣言で使用したファイル名を推測できない場合は、CI/CD変数ESLINT_CODE_QUALITY_REPORTに、アーティファクトに指定したファイル名（gl-code-quality-report.jsonなど）を指定します。

ESLint CI/CDコンポーネントを使用または調整してスキャンを実行し、その出力をCode Qualityと統合することもできます。

Stylelint

CI/CDパイプラインにすでにStylelintジョブがある場合は、その出力をCode Qualityに送信するためにレポートを追加する必要があります。出力を統合するには、以下を実行します:

1. プロジェクトに開発依存関係として@studiometa/stylelint-formatter-gitlabを追加します。
2. Stylelintの実行に使用するコマンドに--custom-formatter=@studiometa/stylelint-formatter-gitlabオプションを追加します。
3. レポートファイルの場所を指すcodequalityレポートアーティファクトを宣言します。
   • デフォルトでは、フォーマッターはCI/CD設定を読み取り、レポートを保存するファイル名を推測します。フォーマッターがアーティファクトの宣言で使用したファイル名を推測できない場合は、CI/CD変数STYLELINT_CODE_QUALITY_REPORTに、アーティファクトに指定したファイル名（gl-code-quality-report.jsonなど）を指定します。

詳細およびCI/CDジョブ定義の例については、@studiometa/stylelint-formatter-gitlabのドキュメントを参照してください。

MyPy

CI/CDパイプラインにすでにMyPyジョブがある場合は、その出力をCode Qualityに送信するためにレポートを追加する必要があります。出力を統合するには、以下を実行します:

1. プロジェクトに依存関係としてmypy-gitlab-code-qualityをインストールします。

2. mypyコマンドを変更して、その出力をファイルに送信します。

3. ジョブscriptにステップを追加し、mypy-gitlab-code-qualityを使用してファイルを必要な形式に再処理します。例:

   - mypy $(find -type f -name "*.py" ! -path "**/.venv/**") --no-error-summary > mypy-out.txt || true  # "|| true" is used for preventing job failure when mypy find errors
   - mypy-gitlab-code-quality < mypy-out.txt > gl-code-quality-report.json

4. レポートファイルの場所を指すcodequalityレポートアーティファクトを宣言します。

MyPy CI/CDコンポーネントを使用または調整してスキャンを実行し、その出力をCode Qualityと統合することもできます。

Flake8

CI/CDパイプラインにすでにFlake8ジョブがある場合は、その出力をCode Qualityに送信するためにレポートを追加する必要があります。出力を統合するには、以下を実行します:

1. プロジェクトに依存関係としてflake8-gl-codeclimateをインストールします。
2. Flake8の実行に使用するコマンドに引数--format gl-codeclimate --output-file gl-code-quality-report.jsonを追加します。
3. レポートファイルの場所を指すcodequalityレポートアーティファクトを宣言します。

Flake8 CI/CDコンポーネントを使用または調整してスキャンを実行し、その出力をCode Qualityと統合することもできます。

Pylint

CI/CDパイプラインにすでにPylintジョブがある場合は、その出力をCode Qualityに送信するためにレポートを追加する必要があります。出力を統合するには、以下を実行します:

1. プロジェクトに依存関係としてpylint-gitlabをインストールします。
2. Pylintの実行に使用するコマンドに引数--output-format=pylint_gitlab.GitlabCodeClimateReporterを追加します。
3. pylintコマンドを変更して、その出力をファイルに送信します。
4. レポートファイルの場所を指すcodequalityレポートアーティファクトを宣言します。

Pylint CI/CDコンポーネントを使用または調整してスキャンを実行し、その出力をCode Qualityと統合することもできます。

Ruff

CI/CDパイプラインにすでにRuffジョブがある場合は、その出力をCode Qualityに送信するためにレポートを追加する必要があります。出力を統合するには、以下を実行します:

1. Ruffの実行に使用するコマンドに引数--output-format=gitlabを追加します。
2. ruff checkコマンドを変更して、その出力をファイルに送信します。
3. レポートファイルの場所を指すcodequalityレポートアーティファクトを宣言します。

ドキュメント化されたRuff GitLab CI/CDインテグレーションを使用または調整してスキャンを実行し、その出力をCode Qualityと統合することもできます。

golangci-lint

CI/CDパイプラインにすでにgolangci-lintジョブがある場合は、その出力をCode Qualityに送信するためにレポートを追加する必要があります。出力を統合するには、以下を実行します:

1. golangci-lintの実行に使用するコマンドに引数を追加します。

   • v1の場合は、--out-format code-climate:gl-code-quality-report.json,line-numberを追加します。
   • v2の場合は、--output.code-climate.path=gl-code-quality-report.jsonを追加します。

2. レポートファイルの場所を指すcodequalityレポートアーティファクトを宣言します。

golangci-lint CI/CDコンポーネントを使用または調整してスキャンを実行し、その出力をCode Qualityと統合することもできます。

PMD Copy/Paste Detector

PMD Copy/Paste Detector（CPD）は、デフォルトの出力が必要な形式に準拠していないため、追加の設定が必要です。

PMD CI/CDコンポーネントを使用または調整してスキャンを実行し、その出力をCode Qualityと統合できます。

SwiftLint

SwiftLintを使用する場合は、デフォルトの出力が必要な形式に準拠していないため、追加の設定が必要です。

Swiftlint CI/CDコンポーネントを使用または調整してスキャンを実行し、その出力をCode Qualityと統合できます。

RuboCop

RuboCopを使用するには、デフォルトの出力が必要な形式に準拠していないため、追加の設定が必要です。

RuboCop CI/CDコンポーネントを使用または調整してスキャンを実行し、その出力をCode Qualityと統合できます。

Roslynator

Roslynatorを使用する場合は、デフォルトの出力が必要な形式に準拠していないため、追加の設定が必要です。

Roslynator CI/CDコンポーネントを使用または調整してスキャンを実行し、その出力をCode Qualityと統合できます。

ドキュメントスキャンツール

Code Qualityを使用すると、コード以外でも、リポジトリに保存されている任意のファイルをスキャンできます。

Vale

CI/CDパイプラインにすでにValeジョブがある場合は、その出力をCode Qualityに送信するためにレポートを追加する必要があります。出力を統合するには、以下を実行します:

1. 必要な形式を定義するValeテンプレートファイルをリポジトリ内に作成します。
   • GitLabドキュメントのチェックに使用するオープンソースのテンプレートをコピーできます。
   • コミュニティのgitlab-ci-utils Valeプロジェクトで使用されているものなど、別のオープンソースバリアントを使用することもできます。このコミュニティプロジェクトでは、同じテンプレートを含む事前に作成されたコンテナイメージも提供しているため、パイプラインで直接使用できます。
2. Valeの実行に使用するコマンドに引数--output="$VALE_TEMPLATE_PATH" --no-exitを追加します。
3. valeコマンドを変更して、その出力をファイルに送信します。
4. レポートファイルの場所を指すcodequalityレポートアーティファクトを宣言します。

オープンソースのジョブ定義を使用または調整してスキャンを実行し、その出力をCode Qualityと統合することもできます。たとえば、次のようなジョブ定義があります:

• GitLabドキュメントのチェックに使用されるVale Lintのステップ。
• コミュニティのgitlab-ci-utils Valeプロジェクト。

markdownlint-cli2

CI/CDパイプラインにすでにmarkdownlint-cli2ジョブがある場合は、その出力をCode Qualityに送信するためにレポートを追加する必要があります。出力を統合するには、以下を実行します:

1. プロジェクトに開発依存関係としてmarkdownlint-cli2-formatter-codequalityを追加します。

2. まだない場合は、リポジトリの最上位に.markdownlint-cli2.jsoncファイルを作成します。

3. outputFormattersディレクティブを.markdownlint-cli2.jsoncに追加します:

   {
     "outputFormatters": [
       [ "markdownlint-cli2-formatter-codequality" ]
     ]
   }

4. レポートファイルの場所を指すcodequalityレポートアーティファクトを宣言します。デフォルトでは、レポートファイル名はmarkdownlint-cli2-codequality.jsonです。

   1. （推奨）レポートファイル名をリポジトリの.gitignoreファイルに追加します。

詳細およびCI/CDジョブ定義の例については、markdownlint-cli2-formatter-codequalityのドキュメントを参照してください。