コードインテリジェンス開発ガイドライン

GitLab 13.1で導入されました。

このドキュメントでは、Code Intelligenceの設計について説明します。

GitLab にビルトインされた Code Intelligence はLSIF を利用しており、CI ジョブでプロジェクトの LSIF ドキュメントを生成し、データを処理して CI アーティファクトとしてアップロードし、プロジェクト内のファイルの情報を表示します。

以下はLSIFアーティファクトをアップロードするためのシーケンス図です：

sequenceDiagram participant Runner participant Workhorse participant Rails participant Object Storage Runner->>+Workhorse: POST /v4/jobs/:id/artifacts Workhorse->>+Rails: POST /:id/artifacts/authorize Rails-->>-Workhorse: Respond with ProcessLsif header Note right of Workhorse: Process LSIF file Workhorse->>+Object Storage: Put file Object Storage-->>-Workhorse: request results Workhorse->>+Rails: POST /:id/artifacts Rails-->>-Workhorse: request results Workhorse-->>-Runner: request results

  1. CI/CDジョブは、プロジェクトの言語用のインデクサを使用して、LSIFフォーマット（通常はdump.lsif ）のドキュメントを生成します。このフォーマットは、メソッドや関数とその定義や参照との間の相互作用を記述します。このドキュメントは、LSIFレポートアーティファクトとして保存されるようにマークされます。

  2. アーティファクトの保存要求を受け取ると、WorkhorseはGitLab Railsにアップロードの承認を求めます。

  3. GitLab Railsはアーティファクトをアップロードできるかどうかを検証し、LSIFアーティファクトを処理できる場合はProcessLsif: true ヘッダを送信します。

  4. Workhorse は LSIF ドキュメントを一行ずつ読み込み、プロジェクト内の各ファイルのコードインテリジェンスデータを生成します。出力はプロジェクトの構造を模したJSONファイルのzipディレクトリです：

    プロジェクト

    app
  controllers
    application_controller.rb
  models
    application.rb

    生成されたデータ

    app
  controllers
    application_controller.rb.json
  models
    application.rb.json

  5. zip圧縮されたディレクトリはZIPアーティファクトとして保存されます。WorkhorseはオリジナルのLSIFドキュメントをZIPアーティファクト内のJSONファイルのセットに置き換え、メタデータを生成します。このメタデータにより、ファイル全体を解凍したり読み込んだりすることなく、ZIPファイル内の単一のファイルを表示できるようになります。これにより、1つのファイルのコード・インテリジェンス・データにアクセスできるようになります。

  6. GitLabアプリケーションでファイルが表示されると、フロントエンドはそのファイルのコードインテリジェンスデータをオブジェクトストレージから直接取得します。ファイルには、ファイル内のコードユニットに関する情報が含まれています。例えば

    [
    {
     "definition_path": "cmd/check/main.go#L4",
     "hover": [
         {
             "language": "go",
             "tokens": [
                 [
                     {
                         "class": "kn",
                         "value": "package"
                     },
                     {
                         "value": " "
                     },
                     {
                         "class": "s",
                         "value": "\"fmt\""
                     }
                 ]
             ]
         },
         {
             "value": "Package fmt implements formatted I/O with functions analogous to C's printf and scanf.  The format 'verbs' are derived from C's but are simpler. \n\n### hdr-PrintingPrinting\nThe verbs: \n\nGeneral: \n\n```\n%v\tthe value in a default format\n\twhen printing st..."
         }
     ],
     "start_char": 2,
     "start_line": 33
   }
   ...
 ]