sonarqube-issue-mcp 0.0.1

package/dist/sonarqube/api-types.d.ts

@@ -0,0 +1,339 @@
+import type { TextRange } from "../types.js";
+/**
+ * SonarQube 常见分页响应。
+ *
+ * @remarks
+ * `pageIndex/pageSize/total` 的语义在 issue 与 hotspot 接口中保持一致。
+ */
+export interface SonarPaging {
+    /** 当前页码，从 1 开始。 */
+    pageIndex: number;
+    /** 当前页大小。 */
+    pageSize: number;
+    /** 总记录数。 */
+    total: number;
+}
+/**
+ * SonarQube 中项目、文件、目录等组件的通用描述。
+ *
+ * @remarks
+ * 同一结构会出现在 `components/show`、issue 结果补充和 hotspot 详情里。
+ */
+export interface SonarProjectComponent {
+    /** 组件 key。 */
+    key: string;
+    /** 组件短名。 */
+    name: string;
+    /** 组件长名。 */
+    longName?: string;
+    /** 组件限定符，例如 `TRK` 或 `FIL`。 */
+    qualifier?: string;
+    /** 相对路径；文件组件常见。 */
+    path?: string;
+}
+/**
+ * `/api/components/show` 返回结构。
+ *
+ * @remarks
+ * 这里只声明当前服务实际用到的字段。
+ */
+export interface SonarComponentShowResponse {
+    /** 当前查询到的组件。 */
+    component: SonarProjectComponent;
+}
+/**
+ * SonarQube 新版 impacts 字段中的单条影响记录。
+ *
+ * @remarks
+ * 用于从新版质量模型中推导更贴近业务语义的严重级别。
+ */
+export interface SonarImpact {
+    /** 软件质量维度。 */
+    softwareQuality: string;
+    /** 严重程度。 */
+    severity: string;
+}
+/**
+ * issue 评论的最小结构。
+ *
+ * @remarks
+ * 不追求完整覆盖，只保留当前服务有机会透传给上层的字段。
+ */
+export interface SonarIssueComment {
+    /** 评论 key。 */
+    key?: string;
+    /** 评论作者登录名。 */
+    login?: string;
+    /** HTML 形式的评论内容。 */
+    htmlText?: string;
+    /** Markdown 形式的评论内容。 */
+    markdown?: string;
+    /** 当前用户是否可编辑。 */
+    updatable?: boolean;
+    /** 评论创建时间。 */
+    createdAt?: string;
+}
+/**
+ * `/api/issues/search` 中的单条 issue。
+ *
+ * @remarks
+ * 字段是按当前标准化需求裁剪过的，不是 Sonar 官方完整模型镜像。
+ */
+export interface SonarIssue {
+    /** issue key。 */
+    key: string;
+    /** 规则 key。 */
+    rule: string;
+    /** 旧版严重度字段。 */
+    severity?: string;
+    /** SonarQube 原始 issue 类型。 */
+    type?: string;
+    /** 组件 key，通常包含项目 key 和相对路径。 */
+    component: string;
+    /** 项目 key。 */
+    project?: string;
+    /** 所在行号。 */
+    line?: number;
+    /** 文本范围。 */
+    textRange?: TextRange;
+    /** 数据流或执行流信息。 */
+    flows?: unknown[];
+    /** 处理结果。 */
+    resolution?: string;
+    /** 当前状态。 */
+    status: string;
+    /** 问题消息。 */
+    message: string;
+    /** 富文本消息格式化信息。 */
+    messageFormattings?: unknown[];
+    /** 估算工作量。 */
+    effort?: string;
+    /** 技术债务字段。 */
+    debt?: string;
+    /** 问题作者。 */
+    author?: string;
+    /** 问题负责人。 */
+    assignee?: string;
+    /** 标签列表。 */
+    tags?: string[];
+    /** 创建时间。 */
+    creationDate: string;
+    /** 最后更新时间。 */
+    updateDate: string;
+    /** 关闭时间。 */
+    closeDate?: string;
+    /** Clean Code 属性。 */
+    cleanCodeAttribute?: string;
+    /** 新版质量影响列表。 */
+    impacts?: SonarImpact[];
+    /** 评论列表。 */
+    comments?: SonarIssueComment[];
+}
+/**
+ * issue search / rule show 中共用的规则摘要结构。
+ *
+ * @remarks
+ * 列表接口只会返回摘要，详情接口会补齐 `mdDesc/htmlDesc` 等字段。
+ */
+export interface SonarIssueRuleSummary {
+    /** 规则 key。 */
+    key: string;
+    /** 规则名称。 */
+    name: string;
+    /** 语言标识。 */
+    lang?: string;
+    /** 规则严重度。 */
+    severity?: string;
+    /** 规则类型。 */
+    type?: string;
+    /** HTML 规则描述。 */
+    htmlDesc?: string;
+    /** Markdown 规则描述。 */
+    mdDesc?: string;
+    /** Clean Code 属性。 */
+    cleanCodeAttribute?: string;
+    /** 标签。 */
+    tags?: string[];
+    /** 系统标签。 */
+    sysTags?: string[];
+}
+/**
+ * `/api/issues/search` 返回结构。
+ *
+ * @remarks
+ * `rules/components/users` 等补充块在不同 Sonar 版本中可能裁剪，但这里统一做可选处理。
+ */
+export interface SonarIssueSearchResponse {
+    /** 分页信息。 */
+    paging: SonarPaging;
+    /** issue 列表。 */
+    issues: SonarIssue[];
+    /** 规则摘要列表。 */
+    rules?: SonarIssueRuleSummary[];
+    /** 组件补充信息。 */
+    components?: SonarProjectComponent[];
+    /** 用户补充信息。 */
+    users?: unknown[];
+}
+/**
+ * `/api/issues/changelog` 中的单次变更记录。
+ *
+ * @remarks
+ * 变更明细字段比较松散，因此保留为最小兼容结构。
+ */
+export interface SonarIssueChangelogEntry {
+    /** 本次变更创建时间。 */
+    creationDate?: string;
+    /** 变更发起人。 */
+    user?: string;
+    /** 字段变更列表。 */
+    diffs?: Array<{
+        /** 变更字段名。 */
+        key?: string;
+        /** 变更后的值。 */
+        newValue?: string;
+        /** 变更前的值。 */
+        oldValue?: string;
+    }>;
+}
+/**
+ * `/api/issues/changelog` 返回结构。
+ *
+ * @remarks
+ * 当前只需要 `changelog` 数组本身。
+ */
+export interface SonarIssueChangelogResponse {
+    /** 全量 changelog 列表。 */
+    changelog: SonarIssueChangelogEntry[];
+}
+/**
+ * `/api/rules/show` 返回结构。
+ *
+ * @remarks
+ * 规则详情接口是列表结果补全描述、修复建议等信息的主要来源。
+ */
+export interface SonarRuleDetailsResponse {
+    /** 规则详情主体。 */
+    rule: SonarIssueRuleSummary & {
+        /** HTML 备注。 */
+        htmlNote?: string;
+        /** 备注作者。 */
+        noteLogin?: string;
+        /** 备注原始数据。 */
+        noteData?: string;
+        /** 技术债系数。 */
+        debtRemFnCoeff?: string;
+        /** 技术债函数类型。 */
+        debtRemFnType?: string;
+    };
+    /** 激活配置列表。 */
+    actives?: unknown[];
+}
+/**
+ * `/api/hotspots/search` 中的单条热点摘要。
+ *
+ * @remarks
+ * 列表接口不含完整规则说明，因此后续通常还会调用 `show` 补详情。
+ */
+export interface SonarHotspotSearchItem {
+    /** hotspot key。 */
+    key: string;
+    /** 规则 key。 */
+    ruleKey: string;
+    /** 组件 key。 */
+    component: string;
+    /** 项目 key。 */
+    project?: string;
+    /** 所在行号。 */
+    line?: number;
+    /** 问题消息。 */
+    message: string;
+    /** 当前状态。 */
+    status: string;
+    /** 当前结论。 */
+    resolution?: string;
+    /** 作者。 */
+    author?: string;
+    /** 负责人。 */
+    assignee?: string;
+    /** 创建时间。 */
+    creationDate: string;
+    /** 最后更新时间。 */
+    updateDate: string;
+    /** 风险概率。 */
+    vulnerabilityProbability?: string;
+}
+/**
+ * `/api/hotspots/search` 返回结构。
+ *
+ * @remarks
+ * 与 issue 列表一样采用分页返回。
+ */
+export interface SonarHotspotSearchResponse {
+    /** 分页信息。 */
+    paging: SonarPaging;
+    /** hotspot 列表。 */
+    hotspots: SonarHotspotSearchItem[];
+    /** 组件补充信息。 */
+    components?: SonarProjectComponent[];
+}
+/**
+ * hotspot 详情中携带的规则信息。
+ *
+ * @remarks
+ * 相比普通 rule summary，hotspot 规则更关注风险说明与修复建议。
+ */
+export interface SonarHotspotRule {
+    /** 规则 key。 */
+    key: string;
+    /** 规则名称。 */
+    name: string;
+    /** 风险说明。 */
+    riskDescription?: string;
+    /** 漏洞说明。 */
+    vulnerabilityDescription?: string;
+    /** 修复建议。 */
+    fixRecommendations?: string;
+}
+/**
+ * `/api/hotspots/show` 返回结构。
+ *
+ * @remarks
+ * 这是 Security Hotspot 详情接口的核心结构，后续会被标准化成统一 FindingSummary。
+ */
+export interface SonarHotspotShowResponse {
+    /** hotspot key。 */
+    key: string;
+    /** 所在行号。 */
+    line?: number;
+    /** 问题消息。 */
+    message: string;
+    /** 当前状态。 */
+    status: string;
+    /** 当前处理结论。 */
+    resolution?: string;
+    /** 作者。 */
+    author?: string;
+    /** 负责人。 */
+    assignee?: string;
+    /** 创建时间。 */
+    creationDate: string;
+    /** 最后更新时间。 */
+    updateDate: string;
+    /** 文本范围。 */
+    textRange?: TextRange;
+    /** 数据流/执行流。 */
+    flows?: unknown[];
+    /** 评论列表。 */
+    comment?: unknown[];
+    /** 变更记录。 */
+    changelog?: unknown[];
+    /** 文件组件信息。 */
+    component: SonarProjectComponent;
+    /** 项目信息。 */
+    project: SonarProjectComponent;
+    /** 规则详情。 */
+    rule: SonarHotspotRule;
+    /** 代码变体信息。 */
+    codeVariants?: string[];
+}

package/dist/sonarqube/api-types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=api-types.js.map

package/dist/sonarqube/api-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-types.js","sourceRoot":"","sources":["../../src/sonarqube/api-types.ts"],"names":[],"mappings":""}

package/dist/sonarqube/client.d.ts

@@ -0,0 +1,183 @@
+import type { ProjectRef } from "../types.js";
+import type { SonarComponentShowResponse, SonarHotspotSearchResponse, SonarHotspotShowResponse, SonarIssue, SonarIssueRuleSummary } from "./api-types.js";
+/**
+ * SonarQube HTTP client 的运行参数。
+ *
+ * @remarks
+ * 这里仅包含请求层所需配置，不引入任何业务语义字段。
+ */
+export interface SonarQubeClientOptions {
+    /** SonarQube Basic Auth 使用的 token。 */
+    token: string;
+    /** 单次请求超时时间，单位毫秒。 */
+    requestTimeoutMs: number;
+    /** 最大重试次数。 */
+    retryCount: number;
+    /** 当前项目请求使用的可选代理。 */
+    httpProxy: string | null;
+}
+/**
+ * SonarQube Web API 访问层。
+ *
+ * @remarks
+ * 这一层只做“请求、分页、鉴权、错误映射、轻量缓存”，不承担业务标准化职责。
+ */
+export declare class SonarQubeClient {
+    private readonly projectRef;
+    private readonly options;
+    /** 规则详情缓存，避免列表和详情阶段重复拉取同一 rule。 */
+    private readonly ruleCache;
+    private readonly dispatcher;
+    constructor(projectRef: ProjectRef, options: SonarQubeClientOptions);
+    /**
+     * 获取 SonarQube 服务版本，用于预检和调试输出。
+     *
+     * @returns SonarQube 版本字符串。
+     * @throws {SonarQubeMcpError} 当请求失败时抛出。
+     */
+    getServerVersion(): Promise<string>;
+    /**
+     * 校验并读取项目组件基础信息。
+     *
+     * @returns 项目组件信息。
+     * @throws {SonarQubeMcpError} 当项目不存在或无法访问时抛出。
+     */
+    getProjectComponent(): Promise<SonarComponentShowResponse["component"]>;
+    /**
+     * 拉取指定 issue 类型的全部“当前未解决”问题。
+     *
+     * @param type - issue 类型，仅支持 `BUG` 和 `VULNERABILITY`。
+     * @returns 问题列表以及列表接口内嵌的规则摘要缓存。
+     *
+     * @remarks
+     * 当前 MCP 口径固定为：
+     * - Security: `VULNERABILITY + resolved=false`
+     * - Reliability: `BUG + resolved=false`
+     *
+     * @throws {SonarQubeMcpError} 当请求失败或响应异常时抛出。
+     */
+    searchOpenIssues(type: "BUG" | "VULNERABILITY"): Promise<{
+        issues: SonarIssue[];
+        embeddedRules: Map<string, SonarIssueRuleSummary>;
+    }>;
+    /**
+     * 通过 issue key 获取单条 issue。
+     *
+     * @param issueKey - SonarQube issue key。
+     * @returns 单条 issue 及其可能内嵌的规则摘要。
+     * @throws {SonarQubeMcpError} 当 issue 不存在或请求失败时抛出。
+     */
+    getIssueByKey(issueKey: string): Promise<{
+        issue: SonarIssue;
+        embeddedRule: SonarIssueRuleSummary | null;
+    }>;
+    /**
+     * 获取单条 issue 的 changelog。
+     *
+     * @param issueKey - SonarQube issue key。
+     * @returns changelog 数组。
+     * @throws {SonarQubeMcpError} 当请求失败时抛出。
+     */
+    getIssueChangelog(issueKey: string): Promise<unknown[]>;
+    /**
+     * 拉取全部待复核的 Security Hotspots。
+     *
+     * @returns hotspot 摘要列表。
+     * @throws {SonarQubeMcpError} 当请求失败或响应异常时抛出。
+     */
+    searchOpenHotspots(): Promise<SonarHotspotSearchResponse["hotspots"]>;
+    /**
+     * 按 key 获取单条 hotspot 详情。
+     *
+     * @param hotspotKey - SonarQube hotspot key。
+     * @returns hotspot 详情。
+     * @throws {SonarQubeMcpError} 当请求失败时抛出。
+     */
+    getHotspotDetail(hotspotKey: string): Promise<SonarHotspotShowResponse>;
+    /**
+     * 获取规则详情。
+     *
+     * @param ruleKey - SonarQube 规则 key。
+     * @returns 规则详情或合并后的完整规则摘要。
+     *
+     * @remarks
+     * 如果缓存里已有完整描述，则直接复用；否则继续调用 `/api/rules/show` 补全。
+     *
+     * @throws {SonarQubeMcpError} 当请求失败时抛出。
+     */
+    getRule(ruleKey: string): Promise<SonarIssueRuleSummary>;
+    /**
+     * 请求 JSON 接口并完成解析。
+     *
+     * @param path - API 路径。
+     * @param searchParams - 可选查询参数。
+     * @returns 解析后的 JSON 结构。
+     */
+    private requestJson;
+    /**
+     * 请求纯文本接口。
+     *
+     * @param path - API 路径。
+     * @param searchParams - 可选查询参数。
+     * @returns 去首尾空白后的文本响应。
+     */
+    private requestText;
+    /**
+     * 底层 HTTP 请求封装。
+     *
+     * @param path - API 路径。
+     * @param searchParams - 可选查询参数。
+     * @returns 成功的原始 `Response` 对象。
+     *
+     * @remarks
+     * 这里统一处理：
+     * - Basic token 鉴权
+     * - 可选 HTTP 代理
+     * - 超时控制
+     * - 可重试状态码
+     * - SonarQube 错误映射
+     *
+     * @throws {SonarQubeMcpError} 当请求最终失败时抛出。
+     */
+    private request;
+    /**
+     * 判断当前 HTTP 状态是否值得重试。
+     *
+     * @param status - HTTP 状态码。
+     * @param attempt - 当前已重试次数。
+     * @returns 是否继续重试。
+     */
+    private shouldRetry;
+    /**
+     * 判断当前异常是否属于可重试的网络层失败。
+     *
+     * @param error - 原始异常。
+     * @param attempt - 当前已重试次数。
+     * @returns 是否继续重试。
+     */
+    private shouldRetryForException;
+    /**
+     * 将 HTTP 错误响应映射为统一的 MCP 错误类型。
+     *
+     * @param response - 失败的 HTTP 响应。
+     * @param requestUrl - 便于排查的完整请求地址。
+     * @returns 统一错误对象。
+     */
+    private buildHttpError;
+    /**
+     * 解析 SonarQube JSON 响应，并在结构不合法时抛出统一错误。
+     *
+     * @param response - 原始 HTTP 响应。
+     * @param path - 当前请求路径，仅用于错误提示。
+     * @returns 解析后的 JSON 结构。
+     * @throws {SonarQubeMcpError} 当响应不是合法 JSON 时抛出。
+     */
+    private parseJson;
+    /**
+     * 尽量把 SonarQube 的错误体提炼成稳定 message + details 结构。
+     *
+     * @param response - 原始 HTTP 响应。
+     * @returns 规范化后的错误 message 与 details。
+     */
+    private parseErrorPayload;
+}