git-repo-analyzer-test 1.0.0

package/src/analyzers/sonarcloud.js

@@ -0,0 +1,928 @@
+/**
+ * SonarCloud Code Quality Analyzer (free plan compatible).
+ *
+ * SonarCloud free plan does NOT provide a single "Overall Code" API. We use only:
+ *   - api/qualitygates/project_status → overall PASS/FAIL + conditions
+ *   - api/measures/component → individual metrics (free-tier keys)
+ *   - api/issues/search → issues list (optional)
+ * We combine these into our own "Overall Summary" for the UI.
+ *
+ * When project is not on SonarCloud (404), can optionally clone and run SonarScanner
+ * (set SONAR_RUN_SCANNER_IF_MISSING=true).
+ */
+
+import { config } from '../config.js';
+import { SonarCloudClient, FREE_TIER_METRIC_KEYS } from '../sonarcloud/client.js';
+import { cloneAndScan } from '../sonarcloud/scanner.js';
+
+/** Free-tier safe metrics (documented as accessible on free plan). Use first for reliable fetch. */
+const CORE_METRIC_KEYS = [...FREE_TIER_METRIC_KEYS];
+/** Extended metrics to request when available (may not all be returned on free plan). */
+const DEFAULT_METRIC_KEYS = [
+  ...CORE_METRIC_KEYS,
+  'security_hotspots',
+  'security_hotspots_reviewed',
+  'sqale_rating',
+  'reliability_rating',
+  'security_rating',
+  'quality_gate_status',
+  'complexity',
+  'cognitive_complexity',
+  'duplicated_blocks',
+  'lines',
+];
+
+export class SonarCloudAnalyzer {
+  constructor() {
+    this.client = new SonarCloudClient();
+  }
+
+  /**
+   * Analyze repository using SonarCloud API.
+   * Returns metrics, quality gate status, and issues for UI display.
+   * If token is missing or project not found, returns a graceful "not available" result.
+   */
+  async analyzeWithSonarCloud(owner, repo) {
+    try {
+      if (!this.client.token) {
+        return this.getUnavailableResult(owner, repo, 'SONAR_TOKEN not set in .env');
+      }
+
+      // 1) Derive project key from SONAR_ORGANIZATION + repo URL (no SONAR_PROJECT_KEY needed). Try fetch first.
+      const derivedKey = this.getScanProjectKey(owner, repo);
+      const initialResult = await this.fetchFullAnalysisData(derivedKey);
+      if (initialResult) {
+        this.logFetchedSonarCloudData(initialResult);
+        return initialResult;
+      }
+
+      // Run latest analysis every time user hits Analyze: use cached clone (clone if not, pull latest), run scanner, then wait for metrics.
+      const alwaysRunScan = (process.env.SONAR_ALWAYS_RUN_SCAN ?? 'true').toString().trim().toLowerCase();
+      const runScanFirst = alwaysRunScan !== 'false' && alwaysRunScan !== '0' && alwaysRunScan !== 'no';
+      if (runScanFirst) {
+        try {
+          console.warn(`📦 SonarCloud: running latest analysis (cached clone, pull, scan) for ${owner}/${repo}...`);
+          await this.runLatestScanOnly(owner, repo);
+          console.warn(`⏳ SonarCloud: scan uploaded. Waiting for metrics (poll up to ~3 min)...`);
+          const afterScan = await this.waitForMeasuresAfterScan(owner, repo);
+          if (afterScan?.component?.measures?.length) {
+            const keyToUse = afterScan.projectKey;
+            const [qualityGateData, issuesData] = await Promise.all([
+              this.client.getQualityGateStatus(keyToUse).catch(() => null),
+              this.client.getIssues(keyToUse, { ps: 100 }).catch(() => ({ issues: [], total: 0 })),
+            ]);
+            const metrics = this.parseMeasures(afterScan.component.measures);
+            const qualityGate = this.parseQualityGate(qualityGateData);
+            const issues = this.parseIssues(issuesData?.issues || [], issuesData?.total ?? 0);
+            const score = this.calculateScore(metrics, qualityGate, issues);
+            const rating = this.getRating(score);
+            const result = this.buildSonarResult(keyToUse, metrics, qualityGate, issues, score, rating);
+            this.logFetchedSonarCloudData(result);
+            return result;
+          }
+        } catch (err) {
+          console.warn('SonarCloud run-latest-scan:', err.message);
+        }
+      }
+
+      // If we ran scan but waitForMeasuresAfterScan returned null, check again after a short delay (first-time scan may have just become ready)
+      if (runScanFirst) {
+        const scanKeyRetry = this.getScanProjectKey(owner, repo);
+        const branches = ['master', 'main', null];
+        const retryDelaysMs = [10000, 20000];
+        for (let i = 0; i < retryDelaysMs.length; i++) {
+          if (i > 0) await new Promise((r) => setTimeout(r, retryDelaysMs[i - 1]));
+          for (const branch of branches) {
+            for (const useBasic of [false, true]) {
+              try {
+                const data = await this.client.getMeasuresWithAuth(scanKeyRetry, DEFAULT_METRIC_KEYS, useBasic, branch);
+                if (data?.component?.measures?.length) {
+                  const keyToUse = scanKeyRetry;
+                  const [qualityGateData, issuesData] = await Promise.all([
+                    this.client.getQualityGateStatus(keyToUse).catch(() => null),
+                    this.client.getIssues(keyToUse, { ps: 100 }).catch(() => ({ issues: [], total: 0 })),
+                  ]);
+                  const metrics = this.parseMeasures(data.component.measures);
+                  const qualityGate = this.parseQualityGate(qualityGateData);
+                  const issues = this.parseIssues(issuesData?.issues || [], issuesData?.total ?? 0);
+                  const score = this.calculateScore(metrics, qualityGate, issues);
+                  const rating = this.getRating(score);
+                  const result = this.buildSonarResult(keyToUse, metrics, qualityGate, issues, score, rating);
+                  this.logFetchedSonarCloudData(result);
+                  return result;
+                }
+              } catch (_) {}
+            }
+          }
+        }
+      }
+
+      // Project key is always derived from SONAR_ORGANIZATION + repo (getScanProjectKey / resolveProjectKey).
+      const scanKey = this.getScanProjectKey(owner, repo);
+      const projectKey = runScanFirst ? scanKey : await this.client.resolveProjectKey(owner, repo);
+      const candidatesTried = this.client.getProjectKeyCandidates(owner, repo);
+      const explicitKey = (config.sonarProjectKey || '').trim() && !/^[a-f0-9]{32,64}$/i.test((config.sonarProjectKey || '').trim())
+        ? (config.sonarProjectKey || '').replace(/^["']|["']$/g, '').trim()
+        : null;
+
+      const captureError = (e) => ({ component: null, error: e?.message || String(e), status: e?.responseStatus ?? e?.response?.status });
+
+      // 2) Try integrated full analysis (measures + quality gate + issues + score) for resolved project key
+      const fullResult = await this.fetchFullAnalysisData(projectKey);
+      if (fullResult) {
+        this.logFetchedSonarCloudData(fullResult);
+        return fullResult;
+      }
+      // Try each candidate key if main projectKey did not return data
+      for (const key of candidatesTried) {
+        if (key === projectKey) continue;
+        const candidateResult = await this.fetchFullAnalysisData(key);
+        if (candidateResult) {
+          this.logFetchedSonarCloudData(candidateResult);
+          return candidateResult;
+        }
+      }
+
+      let measuresData = await this.client.getMeasures(projectKey, DEFAULT_METRIC_KEYS).catch(captureError);
+      let component = measuresData?.component;
+
+      // If we got 404, try with branch (main/master) and without auth (public projects)
+      if (measuresData?.status === 404) {
+        for (const branch of ['master', 'main', null]) {
+          for (const useBasic of [false, true]) {
+            try {
+              const data = await this.client.getMeasuresWithAuth(projectKey, DEFAULT_METRIC_KEYS, useBasic, branch);
+              if (data?.component?.measures?.length) {
+                measuresData = { component: data.component };
+                component = data.component;
+                break;
+              }
+            } catch (_) {}
+          }
+          if (component?.measures?.length) break;
+        }
+        if (!component?.measures?.length) {
+          for (const branch of ['master', 'main', null]) {
+            try {
+              const data = await this.client.getMeasuresWithoutAuth(projectKey, DEFAULT_METRIC_KEYS, branch);
+              if (data?.component?.measures?.length) {
+                measuresData = { component: data.component };
+                component = data.component;
+                break;
+              }
+            } catch (_) {}
+          }
+        }
+      }
+      // If still 404 and we just ran a scan, SonarCloud may still be indexing — retry with longer delays (2–4 min total)
+      if (measuresData?.status === 404 && runScanFirst && projectKey === scanKey) {
+        const retryDelays = [15000, 30000, 45000, 60000]; // 15s, 30s, 45s, 60s — SonarCloud often needs 2–4 min after upload
+        for (let r = 0; r < retryDelays.length; r++) {
+          console.warn(`⏳ SonarCloud: project not ready (404), retrying in ${retryDelays[r] / 1000}s (${r + 1}/${retryDelays.length})...`);
+          await new Promise((res) => setTimeout(res, retryDelays[r]));
+          for (const branch of ['master', 'main', null]) {
+            try {
+              const data = await this.client.getMeasures(scanKey, DEFAULT_METRIC_KEYS, branch);
+              if (data?.component?.measures?.length) {
+                measuresData = { component: data.component };
+                component = data.component;
+                break;
+              }
+            } catch (_) {}
+            for (const useBasic of [false, true]) {
+              try {
+                const data = await this.client.getMeasuresWithAuth(scanKey, DEFAULT_METRIC_KEYS, useBasic, branch);
+                if (data?.component?.measures?.length) {
+                  measuresData = { component: data.component };
+                  component = data.component;
+                  break;
+                }
+              } catch (_) {}
+            }
+            if (component?.measures?.length) break;
+          }
+          if (component?.measures?.length) break;
+          measuresData = await this.client.getMeasures(scanKey, DEFAULT_METRIC_KEYS).catch(captureError);
+          component = measuresData?.component;
+          if (component?.measures?.length) break;
+        }
+      }
+
+      if (component && !component?.measures?.length) {
+        for (let r = 0; r < 6; r++) {
+          await new Promise((res) => setTimeout(res, 30000));
+          measuresData = await this.client.getMeasures(projectKey, DEFAULT_METRIC_KEYS).catch(captureError);
+          component = measuresData?.component;
+          if (component?.measures?.length) break;
+        }
+      }
+      const keyForFetch = component?.key || projectKey;
+      let qualityGateData = await this.client.getQualityGateStatus(keyForFetch).catch(() => null);
+      let issuesData = await this.client.getIssues(keyForFetch, { ps: 100 }).catch(() => ({ issues: [], total: 0 }));
+
+      if (measuresData?.error && !measuresData?.component) {
+        const errMsg = measuresData.error || '';
+        const status = measuresData.status;
+        const is401 = status === 401 || errMsg.includes('401');
+        const is404 = status === 404 || errMsg.includes('404');
+        if (is401) {
+          return this.getUnavailableResult(
+            owner,
+            repo,
+            'SonarCloud returned 401 Unauthorized. Generate a new token at https://sonarcloud.io/account/security and set SONAR_TOKEN in .env (no quotes). Tokens can expire or be revoked.'
+          );
+        }
+        // Scenario B: Analysis visible on SonarCloud but API returns 404 — try project search, then measures with auth + branch.
+        if (is404 && explicitKey) {
+          const orgForSearch = (config.sonarOrgKey || owner).replace(/^["'\s]+|["'\s]+$/g, '').trim().toLowerCase();
+          const projects = await this.client.searchProjects(orgForSearch);
+          const match = projects.find((p) => p.key === explicitKey || p.key.toLowerCase() === explicitKey.toLowerCase() || (p.key.includes(repo) || (p.name && p.name.toLowerCase().includes(repo.toLowerCase()))));
+          const keyToTry = match ? match.key : explicitKey;
+          const branchesToTry = ['master', 'main', null];
+          for (const branch of branchesToTry) {
+            for (const useBasic of [false, true]) {
+              try {
+                const retryMeasures = await this.client.getMeasuresWithAuth(keyToTry, DEFAULT_METRIC_KEYS, useBasic, branch);
+              if (retryMeasures?.component?.measures?.length) {
+                const comp = retryMeasures.component;
+                const [qg, iss] = await Promise.all([
+                  this.client.getQualityGateStatus(keyToTry, branch).catch(() => null),
+                  this.client.getIssues(keyToTry, { ps: 100, branch }).catch(() => ({ issues: [], total: 0 })),
+                ]);
+                const metrics = this.parseMeasures(comp.measures);
+                const qualityGate = this.parseQualityGate(qg);
+                const issues = this.parseIssues(iss?.issues || [], iss?.total ?? 0);
+                const score = this.calculateScore(metrics, qualityGate, issues);
+                const rating = this.getRating(score);
+                const result = this.buildSonarResult(keyToTry, metrics, qualityGate, issues, score, rating);
+                this.logFetchedSonarCloudData(result);
+                return result;
+              }
+            } catch (_) {}
+          }
+          }
+          // One more attempt with integrated fetch (master/main first) before returning empty
+          const lastTry = await this.fetchFullAnalysisData(explicitKey);
+          if (lastTry) {
+            this.logFetchedSonarCloudData(lastTry);
+            return lastTry;
+          }
+          const link = `https://sonarcloud.io/project/overview?id=${encodeURIComponent(explicitKey)}`;
+          const partialResult = {
+            source: 'SONARCLOUD',
+            available: true,
+            projectKey: explicitKey,
+            score: null,
+            rating: null,
+            qualityGate: { status: null, conditions: [] },
+            metrics: {},
+            issues: { total: 0, items: [] },
+            recommendations: [],
+            viewOnSonarCloud: link,
+          };
+          this.logFetchedSonarCloudData(partialResult);
+          return partialResult;
+        }
+        const runScannerEnv = (process.env.SONAR_RUN_SCANNER_IF_MISSING || '').toString().trim().toLowerCase();
+        const runScanner = runScannerEnv === 'true' || runScannerEnv === '1' || runScannerEnv === 'yes';
+        let scannerAttempted = false;
+        let scannerError = null;
+        if (is404 && runScanner) {
+          scannerAttempted = true;
+          const { result: scanResult, error: scanErr } = await this.runScannerAndFetch(owner, repo, candidatesTried[0]);
+          if (scanErr) scannerError = scanErr;
+          if (scanResult) return scanResult;
+        }
+        let hint;
+        if (is404 && scannerAttempted && scannerError) {
+          if (scannerError.includes('No organization with key')) {
+            hint = `SonarCloud: no organization with that key. Set SONAR_ORGANIZATION in .env to your exact org key from https://sonarcloud.io/organizations (sign in → open your org → copy the key from the URL). Use lowercase.`;
+          } else {
+            hint = `Scanner ran but failed. ${scannerError}`;
+          }
+        } else if (is404 && scannerAttempted) {
+          hint = `Scanner ran but failed (timed out). Check server console.`;
+        } else if (is404) {
+          hint = `Project not found (tried: ${candidatesTried.join(', ')}). Add this repo at sonarcloud.io, or set SONAR_RUN_SCANNER_IF_MISSING=true in .env to clone and scan automatically.`;
+        } else {
+          hint = measuresData.error;
+        }
+        for (const keyToTry of [scanKey, projectKey].filter(Boolean)) {
+          try {
+            const fallback = await this.fetchReportByProjectKey(keyToTry);
+            if (fallback?.available && fallback?.metrics && (fallback.metrics.ncloc != null || fallback.metrics.lines != null)) return fallback;
+          } catch (_) {}
+        }
+        const unavail = this.getUnavailableResult(owner, repo, hint);
+        if (scanKey) unavail.viewOnSonarCloud = `https://sonarcloud.io/project/overview?id=${encodeURIComponent(scanKey)}`;
+        return unavail;
+      }
+
+      if (!component?.measures?.length) {
+        for (const keyToTry of [scanKey, keyForFetch || projectKey].filter(Boolean)) {
+          try {
+            const fallback = await this.fetchReportByProjectKey(keyToTry);
+            if (fallback?.available && fallback?.metrics && (fallback.metrics.ncloc != null || fallback.metrics.lines != null)) return fallback;
+          } catch (_) {}
+        }
+        const unavail = this.getUnavailableResult(owner, repo, 'No measures returned for this project. If the project was just scanned, wait 1–2 min and run the analysis again.');
+        if (scanKey) unavail.viewOnSonarCloud = `https://sonarcloud.io/project/overview?id=${encodeURIComponent(scanKey)}`;
+        return unavail;
+      }
+
+      const metrics = this.parseMeasures(component.measures);
+      const qualityGate = this.parseQualityGate(qualityGateData);
+      const issues = this.parseIssues(issuesData?.issues || [], issuesData?.total ?? 0);
+      const score = this.calculateScore(metrics, qualityGate, issues);
+      const rating = this.getRating(score);
+
+      const result = this.buildSonarResult(keyForFetch, metrics, qualityGate, issues, score, rating);
+      this.logFetchedSonarCloudData(result);
+      return result;
+    } catch (error) {
+      console.warn('SonarCloud analysis error:', error.message);
+      return this.getUnavailableResult(owner, repo, error.message);
+    }
+  }
+
+  parseMeasures(measures) {
+    const map = {};
+    for (const m of measures || []) {
+      map[m.metric] = m.value ?? m.period?.value ?? null;
+    }
+    return {
+      ncloc: parseInt(map.ncloc, 10) || 0,
+      lines: parseInt(map.lines, 10) || 0,
+      bugs: parseInt(map.bugs, 10) || 0,
+      vulnerabilities: parseInt(map.vulnerabilities, 10) || 0,
+      codeSmells: parseInt(map.code_smells, 10) || 0,
+      securityHotspots: parseInt(map.security_hotspots, 10) || 0,
+      securityHotspotsReviewed: parseFloat(map.security_hotspots_reviewed) != null ? parseFloat(map.security_hotspots_reviewed) : null,
+      duplicatedLinesDensity: parseFloat(map.duplicated_lines_density) || 0,
+      coverage: parseFloat(map.coverage) != null ? parseFloat(map.coverage) : null,
+      complexity: parseInt(map.complexity, 10) || 0,
+      cognitiveComplexity: parseInt(map.cognitive_complexity, 10) || 0,
+      duplicatedBlocks: parseInt(map.duplicated_blocks, 10) || 0,
+      // A=1, B=2, C=3, D=4, E=5
+      sqaleRating: map.sqale_rating || null,
+      reliabilityRating: map.reliability_rating || null,
+      securityRating: map.security_rating || null,
+      qualityGateStatus: map.quality_gate_status || null,
+    };
+  }
+
+  parseQualityGate(data) {
+    if (!data?.projectStatus) return { status: null, conditions: [] };
+    const status = data.projectStatus.status; // OK, ERROR, NONE
+    const conditions = (data.projectStatus.conditions || []).map((c) => ({
+      metricKey: c.metricKey,
+      status: c.status,
+      operator: c.operator,
+      value: c.value,
+      errorThreshold: c.errorThreshold,
+    }));
+    return { status, conditions };
+  }
+
+  parseIssues(issues, total, maxItems = 100) {
+    return {
+      total,
+      items: (issues || []).slice(0, maxItems).map((i) => ({
+        key: i.key,
+        type: i.type,
+        severity: i.severity,
+        message: i.message,
+        component: i.component,
+        line: i.line,
+        rule: i.rule,
+        effort: i.effort,
+      })),
+    };
+  }
+
+  getRating(score) {
+    if (score >= 9) return 'A+';
+    if (score >= 8) return 'A';
+    if (score >= 7) return 'B+';
+    if (score >= 6) return 'B';
+    if (score >= 5) return 'C+';
+    if (score >= 4) return 'C';
+    return 'F';
+  }
+
+  /**
+   * Fetch full SonarCloud analysis: measures, quality gate, issues; compute score/rating and recommendations.
+   * Tries with and without branch (main, master). Use this for "overall" analysis and to avoid duplicated fetch logic.
+   * @param {string} projectKey - SonarCloud project key
+   * @param {{ issuesPageSize?: number }} [options] - issuesPageSize default 100
+   * @returns {Promise<object|null>} Full result object or null if no measures
+   */
+  async fetchFullAnalysisData(projectKey, options = {}) {
+    const issuesPageSize = options.issuesPageSize ?? 100;
+    const branches = ['master', 'main', null];
+
+    for (const branch of branches) {
+      // 1) Free-plan path: only qualitygates/project_status + measures/component (core metrics)
+      const freeTier = await this.client.fetchQualityGateAndMeasures(projectKey, branch);
+      if (freeTier.measures?.length) {
+        const metrics = this.parseMeasures(freeTier.measures);
+        const qualityGate = this.parseQualityGate(freeTier.qualityGate);
+        const issuesData = await this.client.getIssues(projectKey, { ps: issuesPageSize, branch }).catch(() => ({ issues: [], total: 0 }));
+        const issues = this.parseIssues(issuesData?.issues || [], issuesData?.total ?? 0, issuesPageSize);
+        const score = this.calculateScore(metrics, qualityGate, issues);
+        const rating = this.getRating(score);
+        const result = this.buildSonarResult(projectKey, metrics, qualityGate, issues, score, rating);
+        return result;
+      }
+
+      // 2) Fallback: full measures API (may include extra metrics when available)
+      let component = null;
+      try {
+        const data = await this.client.getMeasures(projectKey, CORE_METRIC_KEYS, branch);
+        if (data?.component?.measures?.length) component = data.component;
+      } catch (_) {}
+      if (!component) {
+        try {
+          const data = await this.client.getMeasures(projectKey, DEFAULT_METRIC_KEYS, branch);
+          if (data?.component?.measures?.length) component = data.component;
+        } catch (_) {}
+      }
+      if (!component) {
+        for (const useBasic of [false, true]) {
+          try {
+            const data = await this.client.getMeasuresWithAuth(projectKey, CORE_METRIC_KEYS, useBasic, branch);
+            if (data?.component?.measures?.length) { component = data.component; break; }
+          } catch (_) {}
+        }
+      }
+      if (!component) {
+        for (const useBasic of [false, true]) {
+          try {
+            const data = await this.client.getMeasuresWithAuth(projectKey, DEFAULT_METRIC_KEYS, useBasic, branch);
+            if (data?.component?.measures?.length) { component = data.component; break; }
+          } catch (_) {}
+        }
+      }
+      if (!component) {
+        try {
+          const data = await this.client.getMeasuresWithoutAuth(projectKey, CORE_METRIC_KEYS, branch);
+          if (data?.component?.measures?.length) component = data.component;
+        } catch (_) {}
+      }
+      if (!component?.measures?.length) continue;
+
+      const keyUsed = component.key || projectKey;
+      const [qualityGateData, issuesData] = await Promise.all([
+        this.client.getQualityGateStatus(keyUsed, branch).catch(() => null),
+        this.client.getIssues(keyUsed, { ps: issuesPageSize, branch }).catch(() => ({ issues: [], total: 0 })),
+      ]);
+      const metrics = this.parseMeasures(component.measures);
+      const qualityGate = this.parseQualityGate(qualityGateData);
+      const issues = this.parseIssues(issuesData?.issues || [], issuesData?.total ?? 0, issuesPageSize);
+      const score = this.calculateScore(metrics, qualityGate, issues);
+      const rating = this.getRating(score);
+      const result = this.buildSonarResult(keyUsed, metrics, qualityGate, issues, score, rating);
+      return result;
+    }
+    return null;
+  }
+
+  /**
+   * Build the SonarCloud result object for the final analysis result.
+   * Structures the response in an "analysis" way: summary, metrics, qualityGate, issues, recommendations.
+   * Free plan: we combine quality gate status + individual metrics; no single "Overall Code" API.
+   */
+  buildSonarResult(projectKey, metrics, qualityGate, issues, score, rating) {
+    const status = qualityGate?.status === 'OK' ? 'Passed' : qualityGate?.status === 'ERROR' ? 'Failed' : 'Unknown';
+    const recommendations = this.generateRecommendations(metrics, qualityGate, issues);
+    const viewOnSonarCloud = `https://sonarcloud.io/project/overview?id=${encodeURIComponent(projectKey)}`;
+    const overallSummary = {
+      status,
+      metrics: {
+        bugs: metrics.bugs ?? 0,
+        vulnerabilities: metrics.vulnerabilities ?? 0,
+        codeSmells: metrics.codeSmells ?? 0,
+        coverage: metrics.coverage != null ? metrics.coverage : null,
+        duplicatedLinesDensity: metrics.duplicatedLinesDensity ?? 0,
+        ncloc: metrics.ncloc ?? metrics.lines ?? 0,
+      },
+    };
+    return {
+      source: 'SONARCLOUD',
+      available: true,
+      projectKey,
+      score,
+      rating,
+      qualityGate,
+      metrics,
+      issues,
+      recommendations,
+      viewOnSonarCloud,
+      overallSummary,
+      /** Analysis-style structure for final result (summary → details → recommendations) */
+      analysis: {
+        summary: {
+          score,
+          rating,
+          qualityGateStatus: qualityGate?.status ?? null,
+          overallStatus: status,
+          projectKey,
+          viewOnSonarCloud,
+        },
+        metrics,
+        qualityGate,
+        issues,
+        recommendations,
+        overallSummary,
+      },
+    };
+  }
+
+  /**
+   * Log a summary of data fetched from SonarCloud to the console.
+   * Call when we have successfully retrieved metrics, quality gate, or issues.
+   */
+  logFetchedSonarCloudData(result) {
+    if (!result || result.source !== 'SONARCLOUD') return;
+    const prefix = '\n📊 SonarCloud data fetched';
+    console.log(prefix + ' — project:', result.projectKey || '—');
+    if (result.qualityGate) {
+      console.log('   Quality gate:', result.qualityGate.status || '—', result.qualityGate.conditions?.length ? `(${result.qualityGate.conditions.length} conditions)` : '');
+    }
+    if (result.metrics && Object.keys(result.metrics).length) {
+      const m = result.metrics;
+      const parts = [];
+      if (m.ncloc != null) parts.push(`lines of code: ${m.ncloc}`);
+      if (m.bugs != null) parts.push(`bugs: ${m.bugs}`);
+      if (m.vulnerabilities != null) parts.push(`vulnerabilities: ${m.vulnerabilities}`);
+      if (m.codeSmells != null) parts.push(`code smells: ${m.codeSmells}`);
+      if (m.coverage != null) parts.push(`coverage: ${m.coverage}%`);
+      if (m.duplicatedLinesDensity != null) parts.push(`duplication: ${m.duplicatedLinesDensity}%`);
+      if (parts.length) console.log('   Metrics:', parts.join(' | '));
+    }
+    if (result.issues && (result.issues.total > 0 || (result.issues.items && result.issues.items.length))) {
+      console.log('   Issues:', result.issues.total ?? result.issues.items?.length ?? 0, 'total (showing up to 50)');
+    }
+    if (result.score != null) console.log('   Score:', result.score, '| Rating:', result.rating || '—');
+    if (result.viewOnSonarCloud) console.log('   View:', result.viewOnSonarCloud);
+    console.log('');
+  }
+
+  calculateScore(metrics, qualityGate, issues) {
+    let score = 10;
+    // Deduct for bugs
+    score -= Math.min(2, (metrics.bugs || 0) * 0.5);
+    // Deduct for vulnerabilities
+    score -= Math.min(3, (metrics.vulnerabilities || 0) * 1);
+    // Deduct for code smells (capped)
+    score -= Math.min(1.5, (metrics.codeSmells || 0) / 500);
+    // Quality gate failed
+    if (qualityGate.status === 'ERROR') score -= 2;
+    // Reliability/security ratings (1=A, 5=E)
+    const rel = parseInt(metrics.reliabilityRating, 10) || 1;
+    const sec = parseInt(metrics.securityRating, 10) || 1;
+    score -= (rel - 1) * 0.3 + (sec - 1) * 0.5;
+    // Coverage bonus (if present)
+    if (metrics.coverage != null && metrics.coverage >= 80) score = Math.min(10, score + 0.5);
+    return Math.max(0, Math.min(10, Math.round(score * 10) / 10));
+  }
+
+  generateRecommendations(metrics, qualityGate, issues) {
+    const recs = [];
+    if (qualityGate.status === 'ERROR') {
+      recs.push({ priority: 'HIGH', category: 'Quality Gate', action: 'Fix failing quality gate conditions on SonarCloud to improve code quality.' });
+    }
+    if ((metrics.bugs || 0) > 0) {
+      recs.push({ priority: 'HIGH', category: 'Bugs', action: `Address ${metrics.bugs} bug(s) reported by SonarCloud.` });
+    }
+    if ((metrics.vulnerabilities || 0) > 0) {
+      recs.push({ priority: 'HIGH', category: 'Security', action: `Remediate ${metrics.vulnerabilities} vulnerability(ies) reported by SonarCloud.` });
+    }
+    if ((metrics.codeSmells || 0) > 50) {
+      recs.push({ priority: 'MEDIUM', category: 'Maintainability', action: `Reduce code smells (${metrics.codeSmells}) to improve maintainability.` });
+    }
+    if (metrics.coverage != null && metrics.coverage < 80) {
+      recs.push({ priority: 'MEDIUM', category: 'Coverage', action: `Increase test coverage from ${metrics.coverage}% toward 80% or higher.` });
+    }
+    if ((metrics.duplicatedLinesDensity || 0) > 5) {
+      recs.push({ priority: 'LOW', category: 'Duplication', action: `Reduce duplicated lines (${metrics.duplicatedLinesDensity}%) to improve clarity.` });
+    }
+    return recs;
+  }
+
+  /** Project key used by the scanner (must match when fetching after a fresh scan). */
+  getScanProjectKey(owner, repo) {
+    const orgRaw = (config.sonarOrgKey && !/^[a-f0-9]{32,64}$/i.test(config.sonarOrgKey))
+      ? config.sonarOrgKey
+      : owner;
+    const organization = orgRaw.trim().toLowerCase();
+    return `${organization}_${repo}`.replace(/\//g, '-');
+  }
+
+  /**
+   * Run latest SonarCloud analysis only: create project if needed, get-or-clone repo, pull latest, run scanner.
+   * Used when SONAR_ALWAYS_RUN_SCAN=true so every Analyze runs latest analysis then fetch.
+   */
+  async runLatestScanOnly(owner, repo, options = {}) {
+    const repoUrl = `https://github.com/${owner}/${repo}`;
+    const orgRaw = (config.sonarOrgKey && !/^[a-f0-9]{32,64}$/i.test(config.sonarOrgKey))
+      ? config.sonarOrgKey
+      : owner;
+    const organization = orgRaw.trim().toLowerCase();
+    const projectKey = `${organization}_${repo}`.replace(/\//g, '-');
+    const projectName = `${owner}/${repo}`;
+    await this.client.createProject(projectKey, projectName, organization);
+    await cloneAndScan(repoUrl, projectKey, projectName, organization, this.client.token);
+    await new Promise((r) => setTimeout(r, 5000));
+    if (options.makePublic !== false) {
+      await this.client.updateProjectVisibility(projectKey, 'public');
+    }
+  }
+
+  /**
+   * After a fresh scan, SonarCloud can take several minutes to process. Poll for measures with the exact scan
+   * project key (and branches). First-time scans: poll more frequently for the first 2 minutes so results
+   * appear as soon as SonarCloud is ready; then use the configured interval.
+   * Configure: SONAR_METRICS_WAIT_MAX_MINUTES (default 5, min 3), SONAR_METRICS_WAIT_INTERVAL_SEC (default 30),
+   * SONAR_METRICS_WAIT_FAST_SEC (default 12) — interval for the first 2 minutes.
+   * @returns {Promise<{component: object, projectKey: string} | null>}
+   */
+  async waitForMeasuresAfterScan(owner, repo) {
+    const scanKey = this.getScanProjectKey(owner, repo);
+    const branches = ['master', 'main', null];
+    const rawMinutes = parseInt(process.env.SONAR_METRICS_WAIT_MAX_MINUTES || '5', 10) || 5;
+    const maxMinutes = Math.min(15, Math.max(3, rawMinutes));
+    const intervalSec = Math.min(120, Math.max(15, parseInt(process.env.SONAR_METRICS_WAIT_INTERVAL_SEC || '30', 10) || 30));
+    const fastSec = Math.min(20, Math.max(8, parseInt(process.env.SONAR_METRICS_WAIT_FAST_SEC || '12', 10) || 12));
+    const fastPhaseMinutes = 2;
+    const fastPhaseAttempts = Math.max(4, Math.ceil((fastPhaseMinutes * 60) / fastSec));
+    const slowPhaseTotalSec = Math.max(0, (maxMinutes - fastPhaseMinutes) * 60);
+    const slowAttempts = Math.max(2, Math.floor(slowPhaseTotalSec / intervalSec));
+    const maxAttempts = fastPhaseAttempts + slowAttempts;
+    const getWaitMs = (attempt) => {
+      if (attempt <= 0) return 0;
+      return (attempt <= fastPhaseAttempts ? fastSec : intervalSec) * 1000;
+    };
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+      if (attempt > 0) {
+        const waitSec = attempt <= fastPhaseAttempts ? fastSec : intervalSec;
+        console.warn(`⏳ SonarCloud: checking again for metrics (attempt ${attempt + 1}/${maxAttempts}, next in ${waitSec}s, up to ${maxMinutes} min)...`);
+        await new Promise((r) => setTimeout(r, getWaitMs(attempt)));
+      }
+      for (const branch of branches) {
+        try {
+          const freeTier = await this.client.fetchQualityGateAndMeasures(scanKey, branch);
+          if (freeTier?.measures?.length) {
+            const component = { key: scanKey, measures: freeTier.measures };
+            return { component, projectKey: scanKey };
+          }
+        } catch (_) {}
+        try {
+          const data = await this.client.getMeasures(scanKey, DEFAULT_METRIC_KEYS, branch);
+          if (data?.component?.measures?.length) return { component: data.component, projectKey: scanKey };
+        } catch (_) {}
+        for (const useBasic of [false, true]) {
+          try {
+            const data = await this.client.getMeasuresWithAuth(scanKey, DEFAULT_METRIC_KEYS, useBasic, branch);
+            if (data?.component?.measures?.length) return { component: data.component, projectKey: scanKey };
+          } catch (_) {}
+        }
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Get-or-clone repo (cache), run SonarScanner, wait for SonarCloud to process, then fetch and return results.
+   * Returns null on failure so caller can show unavailable message.
+   */
+  async runScannerAndFetch(owner, repo, _candidateKey) {
+    const repoUrl = `https://github.com/${owner}/${repo}`;
+    const orgRaw = (process.env.SONAR_ORGANIZATION && !/^[a-f0-9]{32,64}$/i.test(process.env.SONAR_ORGANIZATION))
+      ? process.env.SONAR_ORGANIZATION
+      : owner;
+    const organization = orgRaw.trim().toLowerCase();
+    const projectKey = `${organization}_${repo}`.replace(/\//g, '-');
+    const projectName = `${owner}/${repo}`;
+    try {
+      console.warn(`📦 SonarCloud: project not found. Using cached clone or cloning ${repoUrl}, running SonarScanner (org: ${organization})...`);
+      await cloneAndScan(repoUrl, projectKey, projectName, organization, this.client.token);
+      await new Promise((r) => setTimeout(r, 5000));
+      await this.client.updateProjectVisibility(projectKey, 'public');
+      console.warn(`⏳ SonarCloud: scan uploaded. Waiting for processing (up to ~3 min)...`);
+      await this.waitForProject(projectKey);
+      let resolvedKey = projectKey;
+      const projects = await this.client.searchProjects(organization);
+      const match = projects.find(
+        (p) => p.key === projectKey || p.key.toLowerCase().endsWith(repo.toLowerCase()) || p.key.includes(repo)
+      );
+      if (match && match.key !== projectKey) {
+        resolvedKey = match.key;
+        console.warn(`📊 SonarCloud: using project key ${resolvedKey}`);
+      }
+      let measuresData = await this.client.getMeasures(resolvedKey, DEFAULT_METRIC_KEYS).catch((e) => ({ component: null, error: e.message }));
+      let component = measuresData?.component;
+      const retryDelays = [90000, 90000, 120000];
+      for (let i = 0; i < retryDelays.length && (!component?.measures?.length); i++) {
+        console.warn(`⏳ SonarCloud: measures not ready, retrying in ${retryDelays[i] / 1000}s...`);
+        await new Promise((r) => setTimeout(r, retryDelays[i]));
+        measuresData = await this.client.getMeasures(resolvedKey, DEFAULT_METRIC_KEYS).catch((e) => ({ component: null, error: e.message }));
+        component = measuresData?.component;
+      }
+      if (!component?.measures?.length) {
+        const link = `https://sonarcloud.io/project/overview?id=${encodeURIComponent(resolvedKey)}`;
+        return {
+          result: null,
+          error: `Measures not ready after retries. (1) Wait 2–3 min. (2) Run the same analysis again (same repo, click Analyze). (3) Ensure SONAR_ORGANIZATION in .env matches your SonarCloud org so project key ${resolvedKey} is correct. Project: ${link}`,
+        };
+      }
+      const [qualityGateData, issuesData] = await Promise.all([
+        this.client.getQualityGateStatus(resolvedKey).catch(() => null),
+        this.client.getIssues(resolvedKey, { ps: 100 }).catch(() => ({ issues: [], total: 0 })),
+      ]);
+      const metrics = this.parseMeasures(component.measures);
+      const qualityGate = this.parseQualityGate(qualityGateData);
+      const issues = this.parseIssues(issuesData?.issues || [], issuesData?.total ?? 0);
+      const score = this.calculateScore(metrics, qualityGate, issues);
+      const rating = this.getRating(score);
+      const scanResult = this.buildSonarResult(resolvedKey, metrics, qualityGate, issues, score, rating);
+      this.logFetchedSonarCloudData(scanResult);
+      return {
+        result: scanResult,
+        error: null,
+      };
+    } catch (err) {
+      console.warn('SonarCloud scanner error:', err.message);
+      return { result: null, error: err.message };
+    }
+  }
+ma
+  /** Poll SonarCloud API until project has measures or timeout (~5 min). */
+  async waitForProject(projectKey) {
+    const delays = [0, 5000, 10000, 15000, 20000, 25000, 30000, 30000, 30000, 30000, 30000];
+    for (let i = 0; i < delays.length; i++) {
+      if (delays[i] > 0) await new Promise((r) => setTimeout(r, delays[i]));
+      try {
+        const data = await this.client.getMeasures(projectKey, ['ncloc']);
+        if (data?.component?.measures?.length) return;
+      } catch (_) {}
+    }
+  }
+
+  /** @param {string} [projectKey] - Optional project key so UI can offer "Load report" even when unavailable */
+  getUnavailableResult(owner, repo, reason, projectKey = null) {
+    const scanKey = projectKey ?? this.getScanProjectKey(owner, repo);
+    const viewOnSonarCloud = scanKey ? `https://sonarcloud.io/project/overview?id=${encodeURIComponent(scanKey)}` : undefined;
+    const qualityGate = { status: null, conditions: [] };
+    const issues = { total: 0, items: [] };
+    const recommendations = [];
+    return {
+      source: 'SONARCLOUD',
+      available: false,
+      projectKey: scanKey,
+      score: null,
+      rating: null,
+      qualityGate,
+      metrics: {},
+      issues,
+      recommendations,
+      unavailableReason: reason,
+      viewOnSonarCloud,
+      analysis: {
+        summary: {
+          score: null,
+          rating: null,
+          qualityGateStatus: null,
+          overallStatus: 'Unavailable',
+          projectKey: scanKey,
+          viewOnSonarCloud,
+          unavailableReason: reason,
+        },
+        metrics: {},
+        qualityGate,
+        issues,
+        recommendations,
+        overallSummary: null,
+      },
+    };
+  }
+
+  /**
+   * Fetch full report data by project key only (for public projects or when analysis didn't return metrics).
+   * Tries with token, then without (public), and with branches main/master.
+   */
+  async fetchReportByProjectKey(projectKey) {
+    const branches = ['master', 'main', null];
+    let component = null;
+    let keyUsed = projectKey;
+
+    const tryMeasures = async (withAuth, useBasic, branch) => {
+      if (withAuth && this.client.token) {
+        try {
+          return await this.client.getMeasuresWithAuth(projectKey, DEFAULT_METRIC_KEYS, useBasic, branch);
+        } catch (_) {
+          return null;
+        }
+      }
+      try {
+        return await this.client.getMeasuresWithoutAuth(projectKey, DEFAULT_METRIC_KEYS, branch);
+      } catch (_) {
+        return null;
+      }
+    };
+
+    for (const branch of branches) {
+      if (component?.measures?.length) break;
+      try {
+        const data = await this.client.getMeasures(projectKey, DEFAULT_METRIC_KEYS);
+        if (data?.component?.measures?.length) {
+          component = data.component;
+          keyUsed = data.component.key || projectKey;
+          break;
+        }
+      } catch (_) {}
+    }
+    for (const branch of branches) {
+      if (component?.measures?.length) break;
+      for (const useBasic of [false, true]) {
+        const data = await tryMeasures(true, useBasic, branch);
+        if (data?.component?.measures?.length) {
+          component = data.component;
+          keyUsed = data.component.key || projectKey;
+          break;
+        }
+      }
+    }
+    for (const branch of branches) {
+      if (component?.measures?.length) break;
+      const data = await tryMeasures(false, false, branch);
+      if (data?.component?.measures?.length) {
+        component = data.component;
+        keyUsed = data.component.key || projectKey;
+        break;
+      }
+    }
+
+    if (!component?.measures?.length && this.client.token) {
+      const orgFromKey = projectKey.includes('_') ? projectKey.split('_')[0] : (projectKey.includes('-') ? projectKey.split('-')[0] : null);
+      const org = (config.sonarOrgKey && config.sonarOrgKey.trim()) ? config.sonarOrgKey.trim().toLowerCase() : (orgFromKey || '').toLowerCase();
+      const repoPart = projectKey.includes('_') ? projectKey.replace(/^[^_]+_/, '') : (projectKey.includes('-') ? projectKey.split('-').slice(1).join('-') : projectKey);
+      if (org) {
+        try {
+          const projects = await this.client.searchProjects(org);
+          for (const p of projects || []) {
+            const key = p.key || p.name;
+            if (!key || key === projectKey) continue;
+            const keyLower = key.toLowerCase();
+            const match = keyLower.includes(repoPart.toLowerCase().replace(/-/g, '_')) || keyLower.includes(repoPart.toLowerCase().replace(/_/g, '-')) || (p.name && p.name.toLowerCase().includes(repoPart.toLowerCase()));
+            if (!match) continue;
+            for (const branch of branches) {
+              try {
+                const data = await this.client.getMeasuresWithAuth(key, DEFAULT_METRIC_KEYS, false, branch);
+                if (data?.component?.measures?.length) {
+                  component = data.component;
+                  keyUsed = data.component.key || key;
+                  break;
+                }
+              } catch (_) {}
+              if (component?.measures?.length) break;
+            }
+            if (component?.measures?.length) break;
+          }
+        } catch (_) {}
+      }
+    }
+
+    if (!component?.measures?.length) {
+      const viewLink = `https://sonarcloud.io/project/overview?id=${encodeURIComponent(projectKey)}`;
+      return {
+        source: 'SONARCLOUD',
+        available: false,
+        projectKey,
+        score: null,
+        rating: null,
+        qualityGate: { status: null, conditions: [] },
+        metrics: {},
+        issues: { total: 0, items: [] },
+        recommendations: [],
+        unavailableReason: `Could not load measures for key "${projectKey}". Ensure SONAR_ORGANIZATION in .env matches your SonarCloud org (project key is derived as org_repo). Optionally set SONAR_PROJECT_KEY to the exact key from SonarCloud (?id=...) if it differs.`,
+        viewOnSonarCloud: viewLink,
+      };
+    }
+
+    const [qualityGateData, issuesData] = await Promise.all([
+      this.client.getQualityGateStatus(keyUsed).catch(() => null),
+      this.client.getIssues(keyUsed, { ps: 100 }).catch(() => ({ issues: [], total: 0 })),
+    ]);
+    const metrics = this.parseMeasures(component.measures);
+    const qualityGate = this.parseQualityGate(qualityGateData);
+    const issues = this.parseIssues(issuesData?.issues || [], issuesData?.total ?? 0, 100);
+    const score = this.calculateScore(metrics, qualityGate, issues);
+    const rating = this.getRating(score);
+    const result = this.buildSonarResult(keyUsed, metrics, qualityGate, issues, score, rating);
+    this.logFetchedSonarCloudData(result);
+    return result;
+  }
+}
+
+export default SonarCloudAnalyzer;