sonarqube-issue-mcp 0.0.1

package/dist/sonarqube/client.js

@@ -0,0 +1,411 @@
+import { Buffer } from "node:buffer";
+import { ProxyAgent } from "undici";
+import { SonarQubeMcpError } from "../errors.js";
+import { withProjectContext } from "../project-ref.js";
+/**
+ * 按代理地址缓存 `ProxyAgent`，避免重复构造连接器。
+ *
+ * @remarks
+ * 同一个进程内多个项目查询可复用同一代理配置。
+ */
+const proxyAgentCache = new Map();
+/**
+ * SonarQube Web API 访问层。
+ *
+ * @remarks
+ * 这一层只做“请求、分页、鉴权、错误映射、轻量缓存”，不承担业务标准化职责。
+ */
+export class SonarQubeClient {
+    projectRef;
+    options;
+    /** 规则详情缓存，避免列表和详情阶段重复拉取同一 rule。 */
+    ruleCache = new Map();
+    dispatcher;
+    constructor(projectRef, options) {
+        this.projectRef = projectRef;
+        this.options = options;
+        this.dispatcher = getDispatcher(options.httpProxy);
+    }
+    /**
+     * 获取 SonarQube 服务版本，用于预检和调试输出。
+     *
+     * @returns SonarQube 版本字符串。
+     * @throws {SonarQubeMcpError} 当请求失败时抛出。
+     */
+    async getServerVersion() {
+        return this.requestText("/api/server/version");
+    }
+    /**
+     * 校验并读取项目组件基础信息。
+     *
+     * @returns 项目组件信息。
+     * @throws {SonarQubeMcpError} 当项目不存在或无法访问时抛出。
+     */
+    async getProjectComponent() {
+        const searchParams = withProjectContext(new URLSearchParams({
+            component: this.projectRef.projectKey
+        }), this.projectRef);
+        const response = await this.requestJson("/api/components/show", searchParams);
+        return response.component;
+    }
+    /**
+     * 拉取指定 issue 类型的全部“当前未解决”问题。
+     *
+     * @param type - issue 类型，仅支持 `BUG` 和 `VULNERABILITY`。
+     * @returns 问题列表以及列表接口内嵌的规则摘要缓存。
+     *
+     * @remarks
+     * 当前 MCP 口径固定为：
+     * - Security: `VULNERABILITY + resolved=false`
+     * - Reliability: `BUG + resolved=false`
+     *
+     * @throws {SonarQubeMcpError} 当请求失败或响应异常时抛出。
+     */
+    async searchOpenIssues(type) {
+        const issues = [];
+        const embeddedRules = new Map();
+        let page = 1;
+        while (true) {
+            const searchParams = withProjectContext(new URLSearchParams({
+                components: this.projectRef.projectKey,
+                types: type,
+                resolved: "false",
+                additionalFields: "_all",
+                ps: "500",
+                p: String(page)
+            }), this.projectRef);
+            const response = await this.requestJson("/api/issues/search", searchParams);
+            issues.push(...response.issues);
+            // 列表接口会内嵌一部分 rule 摘要，先缓存起来，后续如缺详细描述再补全。
+            for (const rule of response.rules ?? []) {
+                embeddedRules.set(rule.key, rule);
+                this.ruleCache.set(rule.key, rule);
+            }
+            if (issues.length >= response.paging.total) {
+                break;
+            }
+            page += 1;
+        }
+        return { issues, embeddedRules };
+    }
+    /**
+     * 通过 issue key 获取单条 issue。
+     *
+     * @param issueKey - SonarQube issue key。
+     * @returns 单条 issue 及其可能内嵌的规则摘要。
+     * @throws {SonarQubeMcpError} 当 issue 不存在或请求失败时抛出。
+     */
+    async getIssueByKey(issueKey) {
+        const searchParams = withProjectContext(new URLSearchParams({
+            issues: issueKey,
+            additionalFields: "_all"
+        }), this.projectRef);
+        const response = await this.requestJson("/api/issues/search", searchParams);
+        const issue = response.issues[0];
+        if (!issue) {
+            throw new SonarQubeMcpError("NOT_FOUND", `未找到 issue: ${issueKey}`, {
+                status: 404
+            });
+        }
+        const embeddedRule = response.rules?.find((rule) => rule.key === issue.rule) ?? null;
+        if (embeddedRule) {
+            this.ruleCache.set(embeddedRule.key, embeddedRule);
+        }
+        return { issue, embeddedRule };
+    }
+    /**
+     * 获取单条 issue 的 changelog。
+     *
+     * @param issueKey - SonarQube issue key。
+     * @returns changelog 数组。
+     * @throws {SonarQubeMcpError} 当请求失败时抛出。
+     */
+    async getIssueChangelog(issueKey) {
+        const response = await this.requestJson("/api/issues/changelog", new URLSearchParams({ issue: issueKey }));
+        return response.changelog;
+    }
+    /**
+     * 拉取全部待复核的 Security Hotspots。
+     *
+     * @returns hotspot 摘要列表。
+     * @throws {SonarQubeMcpError} 当请求失败或响应异常时抛出。
+     */
+    async searchOpenHotspots() {
+        const hotspots = [];
+        let page = 1;
+        while (true) {
+            const searchParams = withProjectContext(new URLSearchParams({
+                project: this.projectRef.projectKey,
+                status: "TO_REVIEW",
+                ps: "500",
+                p: String(page)
+            }), this.projectRef);
+            const response = await this.requestJson("/api/hotspots/search", searchParams);
+            hotspots.push(...response.hotspots);
+            if (hotspots.length >= response.paging.total) {
+                break;
+            }
+            page += 1;
+        }
+        return hotspots;
+    }
+    /**
+     * 按 key 获取单条 hotspot 详情。
+     *
+     * @param hotspotKey - SonarQube hotspot key。
+     * @returns hotspot 详情。
+     * @throws {SonarQubeMcpError} 当请求失败时抛出。
+     */
+    async getHotspotDetail(hotspotKey) {
+        return this.requestJson("/api/hotspots/show", new URLSearchParams({ hotspot: hotspotKey }));
+    }
+    /**
+     * 获取规则详情。
+     *
+     * @param ruleKey - SonarQube 规则 key。
+     * @returns 规则详情或合并后的完整规则摘要。
+     *
+     * @remarks
+     * 如果缓存里已有完整描述，则直接复用；否则继续调用 `/api/rules/show` 补全。
+     *
+     * @throws {SonarQubeMcpError} 当请求失败时抛出。
+     */
+    async getRule(ruleKey) {
+        const cached = this.ruleCache.get(ruleKey);
+        if (cached?.name && (cached.mdDesc || cached.htmlDesc)) {
+            return cached;
+        }
+        const response = await this.requestJson("/api/rules/show", new URLSearchParams({ key: ruleKey }));
+        const mergedRule = {
+            ...cached,
+            ...response.rule
+        };
+        this.ruleCache.set(ruleKey, mergedRule);
+        return mergedRule;
+    }
+    /**
+     * 请求 JSON 接口并完成解析。
+     *
+     * @param path - API 路径。
+     * @param searchParams - 可选查询参数。
+     * @returns 解析后的 JSON 结构。
+     */
+    async requestJson(path, searchParams) {
+        const response = await this.request(path, searchParams);
+        return this.parseJson(response, path);
+    }
+    /**
+     * 请求纯文本接口。
+     *
+     * @param path - API 路径。
+     * @param searchParams - 可选查询参数。
+     * @returns 去首尾空白后的文本响应。
+     */
+    async requestText(path, searchParams) {
+        const response = await this.request(path, searchParams);
+        return (await response.text()).trim();
+    }
+    /**
+     * 底层 HTTP 请求封装。
+     *
+     * @param path - API 路径。
+     * @param searchParams - 可选查询参数。
+     * @returns 成功的原始 `Response` 对象。
+     *
+     * @remarks
+     * 这里统一处理：
+     * - Basic token 鉴权
+     * - 可选 HTTP 代理
+     * - 超时控制
+     * - 可重试状态码
+     * - SonarQube 错误映射
+     *
+     * @throws {SonarQubeMcpError} 当请求最终失败时抛出。
+     */
+    async request(path, searchParams) {
+        const url = new URL(path, this.projectRef.origin);
+        if (searchParams) {
+            url.search = searchParams.toString();
+        }
+        let attempt = 0;
+        while (true) {
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), this.options.requestTimeoutMs);
+            try {
+                const requestInit = {
+                    method: "GET",
+                    headers: {
+                        Accept: "application/json",
+                        Authorization: `Basic ${Buffer.from(`${this.options.token}:`).toString("base64")}`
+                    },
+                    signal: controller.signal
+                };
+                // Node 内置 fetch 的 dispatcher 类型与直接引入的 undici 类型并不完全一致，
+                // 这里在调用点做收口，避免把类型耦合扩散到外部代码。
+                const response = await fetch(url, (this.dispatcher
+                    ? {
+                        ...requestInit,
+                        dispatcher: this.dispatcher
+                    }
+                    : requestInit));
+                clearTimeout(timeout);
+                if (response.ok) {
+                    return response;
+                }
+                const error = await this.buildHttpError(response, url.toString());
+                if (this.shouldRetry(response.status, attempt)) {
+                    attempt += 1;
+                    continue;
+                }
+                throw error;
+            }
+            catch (error) {
+                clearTimeout(timeout);
+                if (error instanceof SonarQubeMcpError) {
+                    throw error;
+                }
+                if (this.shouldRetryForException(error, attempt)) {
+                    attempt += 1;
+                    continue;
+                }
+                throw new SonarQubeMcpError("NETWORK", `请求 SonarQube 失败: ${url}`, {
+                    cause: error
+                });
+            }
+        }
+    }
+    /**
+     * 判断当前 HTTP 状态是否值得重试。
+     *
+     * @param status - HTTP 状态码。
+     * @param attempt - 当前已重试次数。
+     * @returns 是否继续重试。
+     */
+    shouldRetry(status, attempt) {
+        if (attempt >= this.options.retryCount) {
+            return false;
+        }
+        return status === 408 || status === 429 || status === 502 || status === 504;
+    }
+    /**
+     * 判断当前异常是否属于可重试的网络层失败。
+     *
+     * @param error - 原始异常。
+     * @param attempt - 当前已重试次数。
+     * @returns 是否继续重试。
+     */
+    shouldRetryForException(error, attempt) {
+        if (attempt >= this.options.retryCount) {
+            return false;
+        }
+        return error instanceof Error && error.name !== "AbortError";
+    }
+    /**
+     * 将 HTTP 错误响应映射为统一的 MCP 错误类型。
+     *
+     * @param response - 失败的 HTTP 响应。
+     * @param requestUrl - 便于排查的完整请求地址。
+     * @returns 统一错误对象。
+     */
+    async buildHttpError(response, requestUrl) {
+        const payload = await this.parseErrorPayload(response);
+        const message = payload.message || `SonarQube 返回了错误响应: ${response.status}`;
+        if (response.status === 401) {
+            return new SonarQubeMcpError("AUTH", message, {
+                status: response.status,
+                details: payload.details
+            });
+        }
+        if (response.status === 403) {
+            return new SonarQubeMcpError("FORBIDDEN", message, {
+                status: response.status,
+                details: payload.details
+            });
+        }
+        if (response.status === 404) {
+            return new SonarQubeMcpError("NOT_FOUND", message, {
+                status: response.status,
+                details: payload.details
+            });
+        }
+        if (response.status === 503) {
+            return new SonarQubeMcpError("INDEXING", `SonarQube 当前不可用或仍在重建索引，请稍后重试。请求地址: ${requestUrl}`, {
+                status: response.status,
+                details: payload.details
+            });
+        }
+        return new SonarQubeMcpError("REMOTE", message, {
+            status: response.status,
+            details: payload.details
+        });
+    }
+    /**
+     * 解析 SonarQube JSON 响应，并在结构不合法时抛出统一错误。
+     *
+     * @param response - 原始 HTTP 响应。
+     * @param path - 当前请求路径，仅用于错误提示。
+     * @returns 解析后的 JSON 结构。
+     * @throws {SonarQubeMcpError} 当响应不是合法 JSON 时抛出。
+     */
+    async parseJson(response, path) {
+        try {
+            return (await response.json());
+        }
+        catch (error) {
+            throw new SonarQubeMcpError("REMOTE", `SonarQube 返回了无法解析的 JSON: ${path}`, {
+                cause: error
+            });
+        }
+    }
+    /**
+     * 尽量把 SonarQube 的错误体提炼成稳定 message + details 结构。
+     *
+     * @param response - 原始 HTTP 响应。
+     * @returns 规范化后的错误 message 与 details。
+     */
+    async parseErrorPayload(response) {
+        const contentType = response.headers.get("content-type") ?? "";
+        if (contentType.includes("application/json")) {
+            try {
+                const json = (await response.json());
+                const message = json.errors?.map((item) => item.msg).filter(Boolean).join("; ") ||
+                    response.statusText ||
+                    "请求失败";
+                return {
+                    message,
+                    details: json
+                };
+            }
+            catch {
+                return {
+                    message: response.statusText || "请求失败",
+                    details: null
+                };
+            }
+        }
+        const text = (await response.text()).trim();
+        return {
+            message: text || response.statusText || "请求失败",
+            details: text || null
+        };
+    }
+}
+/**
+ * 复用同一代理地址的 ProxyAgent，减少连接开销。
+ *
+ * @param httpProxy - 代理地址。
+ * @returns 对应的 `ProxyAgent`；如果未配置代理则返回 `null`。
+ */
+function getDispatcher(httpProxy) {
+    if (!httpProxy) {
+        return null;
+    }
+    const cached = proxyAgentCache.get(httpProxy);
+    if (cached) {
+        return cached;
+    }
+    const dispatcher = new ProxyAgent(httpProxy);
+    proxyAgentCache.set(httpProxy, dispatcher);
+    return dispatcher;
+}
+//# sourceMappingURL=client.js.map

package/dist/sonarqube/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/sonarqube/client.ts"],"names":[],"mappings":"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"}

package/dist/sonarqube/service.d.ts

@@ -0,0 +1,106 @@
+import type { AppConfig } from "../config.js";
+import type { DetailLevel, FindingDetail, ProjectFindingsResult } from "../types.js";
+/**
+ * SonarQube 业务服务层。
+ *
+ * @remarks
+ * 这一层负责把原始 SonarQube API 数据重新组装为 MCP 对外返回结构，
+ * 包括查询口径、规则补全、排序规则、详情标准化和项目归属校验。
+ */
+export declare class SonarQubeFindingService {
+    private readonly config;
+    constructor(config: AppConfig);
+    /**
+     * 获取项目级三类问题汇总。
+     *
+     * @param projectUrl - SonarQube 项目 dashboard URL。
+     * @param detailLevel - 返回详情级别，默认 `standard`。
+     * @returns 已标准化并排序的项目问题汇总。
+     *
+     * @remarks
+     * 这里会并行完成版本检查、项目检查、issue 列表与 hotspot 列表拉取，
+     * 然后统一做规则补充和结果标准化。
+     *
+     * @throws {SonarQubeMcpError} 当 URL 非法、项目不可访问或任一 API 请求失败时抛出。
+     */
+    getProjectFindings(projectUrl: string, detailLevel?: DetailLevel): Promise<ProjectFindingsResult>;
+    /**
+     * 获取单条问题详情。
+     *
+     * @param projectUrl - SonarQube 项目 dashboard URL。
+     * @param kind - 详情类型，`issue` 或 `hotspot`。
+     * @param key - SonarQube 侧的问题 key。
+     * @returns 单条问题的标准化详情。
+     *
+     * @remarks
+     * 详情接口会再次校验问题是否属于当前项目，避免误传别的项目 key 时串数据。
+     *
+     * @throws {SonarQubeMcpError}
+     * 当项目不匹配、问题类型不在支持范围内或底层请求失败时抛出。
+     */
+    getFindingDetail(projectUrl: string, kind: "issue" | "hotspot", key: string): Promise<FindingDetail>;
+    /**
+     * 基于全局配置为当前项目创建隔离的 SonarQube client。
+     *
+     * @param projectRef - 当前项目上下文。
+     * @returns 已绑定项目上下文的 SonarQube client。
+     */
+    private createClient;
+    /**
+     * 组装对外暴露的项目基础信息。
+     *
+     * @param projectRef - 当前项目上下文。
+     * @param projectName - SonarQube 返回的项目名。
+     * @param qualifier - SonarQube 组件限定符。
+     * @param serverVersion - SonarQube 服务版本。
+     * @returns 对外返回的项目基础信息。
+     */
+    private buildProjectInfo;
+    /**
+     * 批量获取并缓存规则详情。
+     *
+     * @param client - SonarQube client。
+     * @param keys - 待查询的规则 key 列表。
+     * @returns 规则 key 到规则详情的映射。
+     */
+    private getRulesByKey;
+    /**
+     * 规则详情补充失败时，尽量回落到列表接口内嵌的规则摘要。
+     *
+     * @param client - SonarQube client。
+     * @param ruleKey - 规则 key。
+     * @param embeddedRule - 列表接口中已拿到的规则摘要。
+     * @returns 完整规则详情或回退摘要。
+     */
+    private getRuleOrFallback;
+    /**
+     * 将 SonarQube issue 标准化为统一 `FindingSummary`。
+     *
+     * @param issue - 原始 issue。
+     * @param rule - 已补全的规则信息。
+     * @param projectRef - 当前项目上下文。
+     * @param category - 目标分类。
+     * @param detailLevel - 返回详情级别。
+     * @returns 统一结构的问题摘要。
+     */
+    private normalizeIssue;
+    /**
+     * 将 hotspot 列表/详情合并后标准化为统一 `FindingSummary`。
+     *
+     * @param hotspotDetail - hotspot 详情；如果调用方尚未获取详情则可为 `null`。
+     * @param hotspotSearch - hotspot 列表摘要；如果调用方只持有详情则可为 `null`。
+     * @param rule - 已补全的规则信息。
+     * @param projectRef - 当前项目上下文。
+     * @param detailLevel - 返回详情级别。
+     * @returns 统一结构的热点摘要。
+     * @throws {SonarQubeMcpError} 当关键字段缺失时抛出。
+     */
+    private normalizeHotspot;
+    /**
+     * issue 优先使用 impacts 推导的业务严重度，没有时再回退到旧 severity。
+     *
+     * @param issue - 原始 issue。
+     * @returns 统一后的严重度字符串。
+     */
+    private pickIssueSeverity;
+}