Jimmo910/edt-sonarq-plugin

# SonarQ in EDT [](https://github.com/Jimmo910/edt-sonarq-plugin/actions/workflows/ci.yml) [](https://github.com/Jimmo910/edt-sonarq-plugin/releases) [](LICENSE) [](#要求) [](#要求) [English](README.en.md) | **Русский** 用于 **1C:Enterprise Development Tools (EDT)** 的插件，可直接在 IDE 中显示针对 BSL 代码的 **SonarQube** 问题。 主要模式通过 Web API 从服务器读取分析结果，并在服务器版本支持的情况下考虑分支（商业版本）； 同时，该插件也兼容 SonarQube Community Edition（不支持分支）。此外，还提供无需服务器的本地模式—— 直接根据项目源码运行 **BSL Language Server**。 ## 功能 - **“SonarQube 问题”窗口** —— 以树状结构显示当前项目的问题，支持按文件或规则分组， 提供按严重程度和类型的过滤器以及文本搜索。 - **跳转到代码** —— 双击问题可在对应行打开模块； 单击则会在底部面板显示规则描述。 - **自动检测 git 分支** —— 窗口会自动确定当前项目的分支，并专门请求该分支的问题 （适用于服务器商业版本）。 - **项目绑定** —— 每个项目都与 SonarQube 的项目密钥关联，支持可选的固定分支和仓库路径前缀。 - **代码中的直接标记** —— 在标准的 Problems 窗口中显示瞬时标记，并在编辑器中添加下划线提示。 - **从窗口启动分析** —— 通过按钮启动（本地 scanner 或 CI 触发器）。 - **无服务器的本地模式** —— 直接根据源码使用 BSL Language Server 进行分析，无需 SonarQube，也无需安装 Java。 - **配置应用的检查** —— “BSL 检查”页面支持按类型或标签（基于 BSL Language Server 自身的分类）分组，并提供“应用推荐配置”按钮。 - **本地模式的分析范围** —— 项目级别：基础分支（仅显示相对于该分支发生更改的行上的问题）以及子系统过滤器。 - **快速抑制误报** —— 在问题窗口中右键单击，或在 Problems 窗口使用 Quick Fix，工具会自动在代码行周围插入 BSL Language Server 的抑制注释。 ## 要求 - 1C:Enterprise Development Tools **2026.1**（构建的 target 平台）。 - Java 17 —— 即 EDT 当前运行所用的 Java（无需单独安装）。 - 对于服务器模式 —— 需要已分析过 BSL 项目的 SonarQube 服务器（例如通过 CI 配合 [sonar-bsl-plugin-community](https://github.com/1c-syntax/sonar-bsl-plugin-community) 插件进行分析）。 - 对于本地模式 —— 首次分析时需要连接互联网，以便自动下载 BSL Language Server 的原生构建版本（除非已指定本地文件）。 ## 安装 **从 p2 更新归档安装**（推荐）： 1. 从项目的 **Releases** 页面下载 zip 更新归档 `ru.jimmo.edt.sonarq.repository`（或自行构建——参见 [从源码构建](#сборка-из-исходников)）。 2. 在 EDT 中：`Help` → `Install New Software…` → `Add…` → `Archive…`，选择下载的 zip 文件， 选中 **SonarQ in EDT** 功能并完成向导。 3. 根据提示重启 EDT。 **从命令行安装**（p2 director）—— 适用于脚本化/自动化安装： ``` <каталог-EDT>/1cedtc.exe -nosplash -application org.eclipse.equinox.p2.director ^ -repository file:/<путь-к-распакованному-репозиторию> ^ -installIU ru.jimmo.edt.sonarq.feature.feature.group ^ -vm <путь-к-jdk17>/bin/javaw.exe ``` ## 如何打开窗口 **窗口(Window)** → **显示视图(Show View)** → **其他(Other…)…** → **SonarQube** 类别 → **SonarQube Issues** ## 问题窗口 窗口顶部是工具栏，下方是问题树，接着是规则描述面板，最底部是状态栏。工具栏按钮仅显示图标而不显示文字标签 —— 按钮的名称和功能会在鼠标悬停时的工具提示中显示。 | 元素 | 功能 | |---|---| | **刷新** | 重新读取问题。在服务器模式下，从服务器获取；在本地模式下，重新运行本地分析。 | | **运行分支分析** | 在服务器模式下 —— 使用配置的方式（本地 scanner 或 CI 触发器）分析当前工作副本的状态。尝试覆盖已分析的分支时会弹出确认对话框。在本地模式下，功能与 **刷新** 相同。 | | **项目** | 如果工作空间有多个项目，用于选择项目。 | | **严重程度** | 多选严重程度：BLOCKER, CRITICAL, MAJOR, MINOR, INFO。 | | **类型** | 按类型过滤：BUG, VULNERABILITY, CODE_SMELL。 | | **按规则或消息过滤** 字段 | 根据规则密钥和消息文本进行文本过滤。 | | **按文件** / **按规则** / **按严重程度分组** | 切换树状结构。用于分组的列会自动隐藏（避免与组标题重复）。 | 窗口中的其他功能： - 底部的 **状态栏** 显示问题数量、分支和上次更新的时间，并显示已加载但 **未在 Problems 窗口中显示** 的问题数量：这些问题的路径无法与项目中的任何文件匹配，或者即使匹配但在项目结构刷新后磁盘上仍不存在该文件； 这是问题窗口相对于标准 Problems 的核心价值之一，在标准 Problems 中这些问题是完全不可见的。 - 发生错误时，状态栏会显示简短的错误标题（如身份验证或网络错误）；将鼠标悬停在状态栏上可在工具提示中查看完整的错误信息，旁边的 **“详情”** 按钮会在对话框中将其完整显示。 本地模式下的内存不足错误会直接指向“BSL LS 最大内存”设置（参见上文的 [“本地模式配置”](#настройка-локального-режима-без-сервера)）。 - 在本地模式下，状态栏会显示其自身的进度 —— 显示后台任务的特定名称和阶段（包括首次运行时下载 BSL Language Server 引擎，约 170 MB），而不是显示关于下载的服务器端表述； 每次重新运行（**刷新** 或切换项目）时，状态和错误文本都会重新清除，不会显示上次运行的过时结果。 - **双击** 问题可在对应行打开相关模块；**单击** 则将规则描述加载到底部面板。 - **本地找不到文件** 的问题会显示为灰色；工具提示会解释无法跳转的原因。 - 如果当前的 git 分支尚未在服务器上进行分析，树状图上方会出现 **“分支 … 尚未在服务器上分析”** 的提示横幅，并带有 **“发送分支进行分析”** 链接（仅在服务器模式且 SonarQube 为商业版本时可用）。 ## 服务器模式配置 ### 1. 连接到服务器 **设置(Preferences)** → **SonarQube**: - **模式** —— 选择 **“SonarQube 服务器”**。 - **服务器 URL** —— SonarQube 服务器的地址。 - **令牌** —— 用户令牌。创建方法：在 SonarQube 的 Web 界面中，打开 **My Account → Security → Generate Tokens** 并创建一个 **User Token** 类型的令牌。 要使用分析启动按钮，该令牌还需要具有 **Execute Analysis** 权限。 令牌存储在 **Eclipse Secure Storage** 中，而不是保存在常规设置中。 - **超时时间（秒）** —— HTTP 请求的超时时间。 - **测试连接** 按钮用于验证 URL 和令牌，并显示服务器版本。 ### 2. 项目绑定 **右键点击项目** → **属性** → **SonarQube**: - **项目名称** —— SonarQube 中的项目密钥 (project key)。**“填充”** 按钮会根据 EDT 项目名称自动匹配（提示会直接显示在输入框中）。 - **固定分支** —— 如果留空，则自动从 git 确定分支。 - **仓库路径前缀** —— 仅当 EDT 项目位于 CI 分析的 git 仓库的子目录中时才需要填写；否则留空。 ### 3. 加载问题 打开 **“SonarQube 问题”** 窗口并点击 **刷新**。 ### 4. 启动分析（可选） 设置页面上的 **“分析启动”** 组用于定义 **“运行分支分析”** 按钮的工作方式。**启动方式**： - **本地 scanner（自动下载）** —— 插件会自动下载 sonar-scanner CLI。 - **本地 scanner（指定路径）** —— 使用通过 **Scanner 路径** 指定的 scanner。 - **CI 触发器 (URL)** —— 向 CI 的 webhook 发送 POST 请求。需设置带有 `{branch}` 占位符（自动替换为当前分支）的 **CI 触发器 URL**，以及可选的 **CI 密钥**（作为 `Authorization` 标头发送，存储在 Secure Storage 中）。 **“Scanner 附加参数”** 字段会为两种 scanner 模式追加参数。 GitLab pipeline trigger 的 URL 示例： ``` https://gitlab.example.com/api/v4/projects//trigger/pipeline?token=&ref={branch} ``` ### 5. 分支 在 SonarQube 商业版本中，窗口会显示与项目当前 git 分支相对应的分支。在 SonarQube Community Edition 中不支持分支 —— 将显示主分支， 并且启动分析时总是会发送到默认的唯一分支中（在覆盖已分析的分支之前会弹出确认对话框）。 ## 本地模式（无服务器）配置 **设置(Preferences)** → **SonarQube** → **模式** → **“本地分析 (BSL Language Server)”**。 - **来源**: - **“自动下载（从互联网，一次性约 170 MB）”** —— 默认选项；插件会在首次分析时将 BSL Language Server 的原生构建版本下载到其专属目录中。此过程不需要 Java。 - **“指定本地文件”** —— 手动设置 **BSL Language Server 路径**（提供 **“浏览…”** 和 **“检查”** 按钮；**“检查”** 会通过 `--version` 运行该文件）。 - **“BSL LS 最大内存 (GB)”**（默认为 4）—— 插件在每次本地分析前写入到已下载引擎中的 JVM 最大堆大小。如果在处理大型配置时分析因内存不足而崩溃，请增加此值（问题窗口中的错误消息会直接指向此设置）。 仅对管理的已下载引擎有效 —— 对手动指定的可执行文件（**“指定本地文件”**）不起作用，在这种情况下该字段是不可用的。 - **“分析引擎”** 部分显示已下载的 BSL Language Server 是否已安装（**“已安装”** / **“未安装”**），**“删除已下载的引擎”** 按钮将其删除 —— 例如，为了强制重新下载；在下一次本地分析时将自动下载。 - 每次点击 **“刷新”** 都会启动全新的本地分析。 - 具体应用哪些检查是单独配置的，参见下文的 [“选择应用的检查”](#выбор-применяемых-проверок)；默认情况下，BSL Language Server 内置的所有检查均已启用。 - 在此模式下，分支、分析启动按钮和 CI 设置均不起作用 —— 将对整个项目进行分析。 ### 选择应用的检查 本地分析应用的检查列表在单独的页面 **设置(Preferences)** → **SonarQube** → **BSL 检查** 中进行配置（类 `BslChecksPreferencePage`）。 - 检查项以树状图显示（列为 **密钥** 和 **名称**），其结构由树上方的 **“分组依据”** 下拉列表控制：**“按类型”**（默认值）—— 按 BSL Language Server 中检查自身类型的分组（Code smell、Error、Vulnerability、Security Hotspot）；**“按标签”** —— 按 BSL Language Server 的标签分组（`standard`、`badpractice`、`performance`、`sql`、`brainoverload` 等；具有多个标签的检查会显示在各自的每个分组中）；**“不分组”** —— 平铺列表。每项检查的类型和标签也会在其所在行的工具提示中显示。每个分组都有各自的复选框（可一键切换其中的所有检查；如果部分检查开启而部分关闭，则显示为半选状态）和各自的 **“已禁用 N 项，共 M 项”** 计数器。开启的检查（勾选复选框）将被应用，关闭的则被忽略。默认情况下启用所有检查。 - **“应用推荐配置”** 按钮和“与 EDT 检查重复：...”工具提示与所选的树状分组方式无关 —— 它们使用插件内置的独立原因分类（EDT 验证器重复项、需要项目级配置的检查、不适用于 EDT 的检查、其他检查），只需点击一下即可禁用推荐的集合 —— EDT 验证器重复项 + 需要项目级配置的 + 不适用于 EDT 的检查（该按钮不会处理“其他”类别）。 这是用户有意识的操作（opt-in）：在按下该按钮之前，一切都不会改变 —— 依然像以前一样启用所有检查。 - 该原因分类是插件内置的第一个明确尚未完善的切入点；社区可以通过 Pull Request 对其进行细化（参见 [issue #3](https://github.com/Jimmo910/edt-sonarq-plugin/issues/3)）。 - 过滤字段支持按密钥或名称搜索；**“启用全部”** / **“禁用全部”** 按钮可无视当前过滤器和分类，直接切换所有检查。树下方的 **“已禁用 N 项，共 M 项”** 行显示已禁用检查的总数。 - 包含 186 项已知检查的完整目录已内置到插件中，因此即使在首次本地分析或点击获取列表按钮之前，树状图也会立即显示所有类别。内置目录会由缓存进行补充（而非替换），该缓存在每次成功的本地分析后会自动填充，或者通过 **“获取检查列表”** 按钮手动填充：它会分析一个空临时文件夹，从而在不产生任何实际问题的情况下获取完整的检查列表。如果尚未下载 BSL Language Server，首次使用该按钮（就像首次本地分析一样）将触发下载 —— 大小约为 170 MB，需要互联网连接。 - 从该页面所做的选择 —— 无论是手动勾选还是通过点击“应用推荐配置” —— 其应用和存储方式与以往相同：通过生成的 BSL Language Server 配置文件，并使用 `--configuration` 标志传递给分析器。如果项目中已有自己的 `.bsl-language-server.json` 文件（位于项目根目录或 `src/` 目录中），它始终具有优先权：分析器将使用该文件代替生成的文件，并且对于此类项目，设置页面上的选择将被忽略。 ### 分析范围 在 **项目属性 → SonarQube** 页面（参见上文的 [“项目绑定”](#2-привязка-проекта)）中，有一个 **“分析范围（本地模式）”** 组，包含两个独立的过滤器。两者都仅在本地分析模式下生效，且默认均为空 —— 这意味着像以前一样“分析所有内容”（不会失去向后兼容性）。 - **“基础分支”** —— 可编辑的下拉列表，预填充了项目本地 git 分支的名称。如果设置了值，则仅显示相对于该基础（基础分支或与工作副本（包括未提交的更改）进行比较的提交）发生更改的行上的问题 —— 这与在 EDT 本身中隐藏基础分支错误的理念相同。如果无法解析该值（项目不在 git 仓库中，或者指定的分支/提交不存在），则过滤器将被禁用并显示所有问题 —— 不会静默隐藏。 - **“子系统”** —— 带有复选框的树状图，从项目的 `src/Subsystems` 目录中读取（嵌套子系统会递归读取）。如果未做任何选择（未勾选任何复选框）—— 将分析整个项目；勾选一个或多个子系统即可将分析范围限制在这些子系统内 —— 勾选某个子系统会自动包含嵌套在其中的所有子系统（这是由 BSL Language Server 自身通过诊断参数 `subsystemsFilter` 实现的）。**“刷新”** 按钮可从磁盘重新读取树状图（例如在添加了新子系统之后），且不会重置当前的选择。 如果项目中已有自己的 `.bsl-language-server.json` 文件，它将优先于生成的检查配置，并且与禁用的检查选择一样，对于此类项目，子系统过滤器也不适用。而基于基础分支的逐行过滤器独立于检查配置，在这种情况下仍会继续应用。 ## 编辑器中的标记 设置页面上的 **“编辑器中的标记”** 组： - **在标准“问题”面板中显示问题**（默认开启） —— 问题会进入标准的 **Eclipse Problems** 窗口并在编辑器中显示为下划线。严重程度对应关系：BLOCKER/CRITICAL → 错误，MAJOR → 警告，其他 → 信息。取消勾选后，问题将仅在插件自有的“SonarQube 问题”窗口中可见。 - **“在后台自动刷新”** + **“间隔时间（分钟）”** —— 即使窗口关闭，也会定期在后台刷新问题和标记（仅在服务器模式下生效）。 标记是 **瞬时** 的：它们在每次刷新时重新创建，重启 EDT 后，在首次刷新之前，Problems 窗口是空的。 ## 快速抑制误报 如果某个具体问题是误报，可以直接从 EDT 中将其抑制，无需手动修改代码： - 在 **“SonarQube 问题”** 窗口中 **右键点击** 该问题 → **“抑制问题”**； - 或者在 Problems 窗口中对相应问题的标记使用 **Quick Fix**。 该操作会在标记行的周围插入一对 BSL Language Server 注释： 在上一行添加 `// BSLLS:<规则密钥>-off`，在下一行添加 `// BSLLS:<规则密钥>-on`。BSL Language Server 本身（本地模式）和服务器端的 `sonar-bsl-plugin-community`（使用相同的诊断引擎）都能识别这对注释 —— 两者都会停止报告标记行上的该规则；无需手动复制注释。 如果文件已在编辑器中打开，修改将直接应用到打开的文档中并且可以撤销；否则，修改内容将直接保存到磁盘上的文件中。 ## 工作原理 **服务器模式。** 插件充当 SonarQube Web API 的读取器：它根据项目密钥和分支加载问题（带分页的 `/api/issues/search`）、规则描述（`/api/rules/show`），并检测服务器版本以确定是否支持分支。 此外，**“运行分支分析”** 按钮也可以自行启动分析 —— 通过本地 scanner（自动下载或指定路径）或通过 CI 触发器 —— 并等待服务器处理完报告，随后窗口将自动刷新。 **本地模式。** 插件以 `--analyze` 模式针对项目源码运行原生构建的 BSL Language Server，获取 **SARIF** 格式的报告，并基于此构建同样的问题树、过滤器和标记。此过程不需要 SonarQube 服务器和 Java。 ## 从源码构建 需要 **JDK 17** 和 **Maven 3.9.4 或更高版本**（通过构建验证；不包含 Maven wrapper）。 ``` $env:JAVA_HOME = '<путь-к-jdk-17>' mvn clean verify ``` 构建好的 p2 repository 将生成在 `repositories/ru.jimmo.edt.sonarq.repository/target/repository/`（此外还会生成包含相同内容的 zip 归档）。 ## 已知限制 - 服务器最多返回 **10,000 个问题**（SonarQube Web API 的限制）；如果超出，请在服务器端缩小过滤范围。 - 仅在 SonarQube 商业版本中支持分支；在 Community Edition 中，仅显示唯一的主分支。 - 在本地模式下，分析的是项目的 `src/` 目录（1C 配置的标准布局），如果不存在该目录，则分析项目根目录。 - 用于推荐配置的原因分类（“BSL 检查”）是插件内置的第一个明确尚未完善的切入点；社区可通过 Pull Request 进行细化（参见 [issue #3](https://github.com/Jimmo910/edt-sonarq-plugin/issues/3)）。 - 子系统过滤器按子系统名称进行匹配（这是由 BSL Language Server 自身实现的方式），因此位于不同父节点下的同名子系统会被一同过滤。 ## 反馈 如有疑问、Bug 或建议，请通过 GitHub 上项目仓库的 **Issues** 部分提交。 ## 许可证 本项目基于 [Eclipse Public License 2.0](LICENSE) 许可证发布。

标签：1C:EDT, BSL, IDE插件, SonarQube, 云安全监控, 域名枚举, 网络安全研究, 静态分析