Code Intelligence 开发指南

这份文档描述了 Code Intelligence 的设计理念。

GitLab 内置的 Code Intelligence 由 LSIF 驱动，其核心流程是：在 CI 作业中为项目生成 LSIF 文档，处理数据，将其作为 CI 工件上传，并在项目文件中显示这些信息。

以下是上传 LSIF 工件的时序图：

%%{init: { "fontFamily": "GitLab Sans" }}%%
sequenceDiagram
    accTitle: LSIF 工件上传时序图
    accDescr: Runner、Workhorse、Rails 和对象存储如何协同上传工件的过程。

    participant Runner
    participant Workhorse
    participant Rails
    participant Object Storage

    Runner->>+Workhorse: POST /v4/jobs/:id/artifacts
    Workhorse->>+Rails: POST /:id/artifacts/authorize
    Rails-->>-Workhorse: 响应 ProcessLsif 头部信息
    Note right of Workhorse: 处理 LSIF 文件
    Workhorse->>+Object Storage: 上传文件
    Object Storage-->>-Workhorse: 返回请求结果
    Workhorse->>+Rails: POST /:id/artifacts
    Rails-->>-Workhorse: 返回请求结果
    Workhorse-->>-Runner: 返回请求结果

1. CI/CD 作业使用项目语言的 索引器 生成 LSIF 格式的文档（通常是 dump.lsif）。该格式描述了方法或函数与其定义或引用之间的交互。该文档被标记为要存储为 LSIF 报告工件。

2. 在收到存储工件的请求后，Workhorse 请求 GitLab Rails 授权上传。

3. GitLab Rails 验证工件是否可以上传，如果 LSIF 工件可以处理，则发送 ProcessLsif: true 头部信息。

4. Workhorse 逐行读取 LSIF 文档，并为项目中的每个文件生成代码智能数据。输出是一个模仿项目结构的 JSON 文件压缩目录：

   项目：

   app
     controllers
       application_controller.rb
     models
       application.rb

   生成的数据：

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

5. 压缩目录作为 ZIP 工件存储。Workhorse 将原始 LSIF 文档替换为 ZIP 工件中的一组 JSON 文件，并为其生成元数据。元数据使得无需解压或加载整个文件即可查看 ZIP 文件中的单个文件。这样我们就可以访问单个文件的代码智能数据。

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
      }
      ...
    ]