@pagopa/dx-savemoney 0.6.4 → 0.6.6

package/src/azure/__tests__/finding-code.test.ts

@@ -0,0 +1,128 @@
+/**
+ * Unit tests for stable per-sentence custom finding codes.
+ *
+ * These codes are what lets `foldDuplicateFinding` collapse two custom
+ * findings that describe the same problem on the same resource, so the tests
+ * focus on: known sentences get a stable identity, identical wording shared
+ * across resource types collapses onto one code, and anything the table
+ * doesn't recognise (or that already has an identity, or isn't "custom") is
+ * left untouched.
+ */
+
+import { describe, expect, it } from "vitest";
+
+import type { Finding } from "../../finding.js";
+
+import { assignCustomFindingCodes } from "../finding-code.js";
+
+const RESOURCE_ID =
+  "/subscriptions/sub1/resourceGroups/rg1/providers/Microsoft.Compute/disks/disk1";
+
+function customFinding(
+  reason: string,
+  overrides: Partial<Finding> = {},
+): Finding {
+  return {
+    category: "cost",
+    code: "custom.unknown",
+    reason,
+    resourceId: RESOURCE_ID,
+    severity: "low",
+    source: "custom",
+    ...overrides,
+  };
+}
+
+describe("assignCustomFindingCodes", () => {
+  it.each([
+    ["Disk is unattached.", "custom.disk.unattached"],
+    [
+      "NIC not attached to any VM or private endpoint.",
+      "custom.nic.unattached",
+    ],
+    ["No public IP assigned.", "custom.nic.no-public-ip"],
+    [
+      "Private Endpoint has no private link service connections configured.",
+      "custom.private-endpoint.no-connections",
+    ],
+    ["Container App is not running.", "custom.container-app.not-running"],
+    ["App Service Plan has no apps deployed.", "custom.app-service.no-apps"],
+    [
+      "Public IP not associated with any resource.",
+      "custom.public-ip.unassociated",
+    ],
+    ["Static IP not in use.", "custom.public-ip.static-unused"],
+    [
+      "Very low transaction count (2.00 avg/day).",
+      "custom.storage.low-transactions",
+    ],
+    ["VM is deallocated.", "custom.vm.deallocated"],
+    ["VM is stopped.", "custom.vm.stopped"],
+    ["Low CPU usage (avg 1.23%).", "custom.vm.low-cpu-usage"],
+    ["Low network traffic (0.50 MB/day avg).", "custom.vm.low-network-traffic"],
+    [
+      "No traffic data available in 30 days.",
+      "custom.static-site.no-traffic-data",
+    ],
+    [
+      "Very low site traffic (3 requests in 30 days).",
+      "custom.static-site.low-traffic",
+    ],
+    [
+      "Very low data transfer (0.01 MB in 30 days).",
+      "custom.static-site.low-data-transfer",
+    ],
+    ["Resource ID is missing.", "custom.missing-resource-id"],
+    ["Could not retrieve detailed NIC information.", "custom.lookup-failed"],
+    ["No tags found.", "custom.missing-tags"],
+  ])("assigns %j the stable code %j", (reason, expectedCode) => {
+    const [finding] = assignCustomFindingCodes([customFinding(reason)]);
+    expect(finding.code).toBe(expectedCode);
+    expect(finding.recommendationId).toBe(expectedCode);
+  });
+
+  it.each([
+    ["Very low CPU usage (12.34%).", "App Service Plan"],
+    ["Very low CPU usage (0.5000 cores).", "Container App"],
+  ])(
+    "shares one code across resource types for identical wording: %j (%s)",
+    (reason) => {
+      const [finding] = assignCustomFindingCodes([customFinding(reason)]);
+      expect(finding.recommendationId).toBe("custom.low-cpu-usage");
+    },
+  );
+
+  it("gives two different resources' identical sentences the same recommendationId, enabling a later fold within a resource but not across resources", () => {
+    const [a, b] = assignCustomFindingCodes([
+      customFinding("Very low network traffic (1.00 MB/day avg)."),
+      customFinding("Very low network traffic (2.00 MB/day avg)."),
+    ]);
+
+    expect(a.recommendationId).toBe("custom.low-network-traffic");
+    expect(b.recommendationId).toBe("custom.low-network-traffic");
+  });
+
+  it("leaves unrecognised sentences unchanged", () => {
+    const finding = customFinding("Something entirely unexpected happened.");
+
+    expect(assignCustomFindingCodes([finding])).toEqual([finding]);
+  });
+
+  it("leaves non-custom findings unchanged", () => {
+    const finding = customFinding("Disk is unattached.", {
+      code: "advisor.some-id",
+      recommendationId: "advisor.some-id",
+      source: "advisor",
+    });
+
+    expect(assignCustomFindingCodes([finding])).toEqual([finding]);
+  });
+
+  it("does not overwrite a finding that already has a recommendationId", () => {
+    const finding = customFinding("Disk is unattached.", {
+      recommendationId: "custom.already-set",
+    });
+
+    expect(assignCustomFindingCodes([finding])).toEqual([finding]);
+  });
+});

package/src/azure/__tests__/finding-dedup.test.ts

@@ -0,0 +1,269 @@
+/**
+ * Unit tests for cross-source finding deduplication.
+ *
+ * The same waste can be reported by AZQR, Azure Advisor and the custom
+ * analyzers at once. These tests pin down when the incoming finding collapses
+ * onto an existing one, and what the surviving finding is expected to carry.
+ */
+
+import { describe, expect, it } from "vitest";
+
+import type { Finding } from "../../finding.js";
+import type { AzureDetailedResourceReport } from "../types.js";
+
+import {
+  foldDuplicateFinding,
+  orphanRecommendationId,
+} from "../finding-dedup.js";
+
+const RESOURCE_ID =
+  "/subscriptions/sub1/resourceGroups/rg1/providers/Microsoft.Compute/disks/disk1";
+
+const ORPHAN_DISK = orphanRecommendationId("Microsoft.Compute/disks");
+
+function mkFinding(overrides: Partial<Finding> = {}): Finding {
+  return {
+    category: "cost",
+    code: "custom.unknown",
+    reason: "Disk is unattached.",
+    resourceId: RESOURCE_ID,
+    severity: "low",
+    source: "custom",
+    ...overrides,
+  };
+}
+
+function mkReport(findings: Finding[]): AzureDetailedResourceReport {
+  return {
+    analysis: {
+      costRisk: "low",
+      reason: findings.map((finding) => finding.reason).join(" "),
+      suspectedUnused: true,
+    },
+    findings,
+    resource: {
+      id: RESOURCE_ID,
+      name: "disk1",
+      type: "Microsoft.Compute/disks",
+    },
+  };
+}
+
+describe("orphanRecommendationId", () => {
+  it("normalises the resource type so sources share one identity", () => {
+    expect(ORPHAN_DISK).toBe("orphan.microsoft.compute/disks");
+  });
+});
+
+describe("foldDuplicateFinding", () => {
+  it("keeps findings without a recommendation id separate", () => {
+    const report = mkReport([mkFinding({ reason: "No tags found." })]);
+
+    expect(foldDuplicateFinding(mkFinding(), report)).toBe(false);
+    expect(report.findings).toHaveLength(1);
+  });
+
+  it("folds a finding sharing the same recommendation id", () => {
+    const report = mkReport([
+      mkFinding({ recommendationId: ORPHAN_DISK, source: "advisor" }),
+    ]);
+
+    const folded = foldDuplicateFinding(
+      mkFinding({
+        recommendationId: ORPHAN_DISK.toUpperCase(),
+        source: "azqr",
+      }),
+      report,
+    );
+
+    expect(folded).toBe(true);
+    expect(report.findings).toHaveLength(1);
+  });
+
+  it("folds an AZQR orphan row onto the live cost finding for the same resource", () => {
+    const report = mkReport([mkFinding()]);
+
+    const folded = foldDuplicateFinding(
+      mkFinding({
+        recommendationId: ORPHAN_DISK,
+        severity: "high",
+        source: "azqr",
+      }),
+      report,
+    );
+
+    expect(folded).toBe(true);
+    expect(report.findings?.[0]).toMatchObject({
+      reason:
+        "Disk is unattached. Also flagged by azqr as an orphaned resource.",
+      severity: "high",
+      source: "custom",
+    });
+  });
+
+  it("adopts the canonical identity of the finding it absorbs", () => {
+    const report = mkReport([mkFinding()]);
+
+    foldDuplicateFinding(
+      mkFinding({ recommendationId: ORPHAN_DISK, source: "azqr" }),
+      report,
+    );
+
+    expect(report.findings?.[0].recommendationId).toBe(ORPHAN_DISK);
+  });
+
+  it("records the corroborating source in the per-resource summary too", () => {
+    const report = mkReport([mkFinding()]);
+
+    foldDuplicateFinding(
+      mkFinding({
+        recommendationId: ORPHAN_DISK,
+        severity: "high",
+        source: "azqr",
+      }),
+      report,
+    );
+
+    expect(report.analysis).toMatchObject({
+      costRisk: "high",
+      reason:
+        "Disk is unattached. Also flagged by azqr as an orphaned resource.",
+    });
+  });
+
+  it("keeps the monetary estimate of whichever finding carries one", () => {
+    const report = mkReport([mkFinding({ recommendationId: ORPHAN_DISK })]);
+
+    foldDuplicateFinding(
+      mkFinding({
+        estimatedMonthlySavings: { amount: 12.5, currency: "EUR" },
+        recommendationId: ORPHAN_DISK,
+        source: "azqr",
+      }),
+      report,
+    );
+
+    expect(report.findings?.[0].estimatedMonthlySavings).toEqual({
+      amount: 12.5,
+      currency: "EUR",
+    });
+  });
+
+  it("does not fold an orphan row onto a governance-only finding", () => {
+    const report = mkReport([
+      mkFinding({
+        category: "operationalExcellence",
+        reason: "No tags found.",
+      }),
+    ]);
+
+    const folded = foldDuplicateFinding(
+      mkFinding({ recommendationId: ORPHAN_DISK, source: "azqr" }),
+      report,
+    );
+
+    expect(folded).toBe(false);
+    expect(report.analysis.reason).toBe("No tags found.");
+  });
+
+  it("does not fold an orphan row onto another static-report finding", () => {
+    const report = mkReport([
+      mkFinding({ recommendationId: "azqr.other", source: "azqr" }),
+    ]);
+
+    expect(
+      foldDuplicateFinding(
+        mkFinding({ recommendationId: ORPHAN_DISK, source: "azqr" }),
+        report,
+      ),
+    ).toBe(false);
+  });
+
+  it("does not fold an orphan row onto a live finding with its own distinct identity", () => {
+    const report = mkReport([
+      mkFinding({
+        recommendationId: "advisor.right-size-vm",
+        source: "advisor",
+      }),
+    ]);
+
+    expect(
+      foldDuplicateFinding(
+        mkFinding({ recommendationId: ORPHAN_DISK, source: "azqr" }),
+        report,
+      ),
+    ).toBe(false);
+    expect(report.findings).toHaveLength(1);
+  });
+});
+
+describe("foldDuplicateFinding - repeated and idempotent folds", () => {
+  it("does not annotate same-source duplicates", () => {
+    const report = mkReport([
+      mkFinding({ recommendationId: ORPHAN_DISK, source: "azqr" }),
+    ]);
+
+    foldDuplicateFinding(
+      mkFinding({ recommendationId: ORPHAN_DISK, source: "azqr" }),
+      report,
+    );
+
+    expect(report.findings?.[0].reason).toBe("Disk is unattached.");
+    expect(report.analysis.reason).toBe("Disk is unattached.");
+  });
+
+  it("does not annotate the same corroboration twice", () => {
+    const report = mkReport([mkFinding()]);
+    const azqrRow = () =>
+      mkFinding({ recommendationId: ORPHAN_DISK, source: "azqr" });
+
+    foldDuplicateFinding(azqrRow(), report);
+    const foldedAgain = foldDuplicateFinding(azqrRow(), report);
+
+    expect(foldedAgain).toBe(true);
+    expect(report.findings).toHaveLength(1);
+    expect(report.findings?.[0].reason).toBe(
+      "Disk is unattached. Also flagged by azqr as an orphaned resource.",
+    );
+    expect(report.analysis.reason).toBe(
+      "Disk is unattached. Also flagged by azqr as an orphaned resource.",
+    );
+  });
+
+  it("leaves reports without collected findings untouched", () => {
+    const report = mkReport([]);
+    delete report.findings;
+
+    expect(
+      foldDuplicateFinding(
+        mkFinding({ recommendationId: ORPHAN_DISK, source: "azqr" }),
+        report,
+      ),
+    ).toBe(false);
+  });
+
+  // Custom analyzer sentences with a known template carry a stable
+  // recommendationId too (see finding-code.ts), so two custom findings for
+  // the same problem must collapse just like a custom/advisor pair does.
+  it("folds two custom findings sharing a stable recommendation id", () => {
+    const report = mkReport([
+      mkFinding({
+        code: "custom.disk.unattached",
+        recommendationId: "custom.disk.unattached",
+      }),
+    ]);
+
+    const folded = foldDuplicateFinding(
+      mkFinding({
+        code: "custom.disk.unattached",
+        recommendationId: "custom.disk.unattached",
+      }),
+      report,
+    );
+
+    expect(folded).toBe(true);
+    expect(report.findings).toHaveLength(1);
+    // Same-source fold: no corroboration note is appended.
+    expect(report.findings?.[0].reason).toBe("Disk is unattached.");
+  });
+});

package/src/azure/analyzer.ts

@@ -37,8 +37,9 @@ import type { AzureConfig, AzureDetailedResourceReport } from "./types.js";
 import { findingsFromAnalysisResult } from "../finding.js";
 import {
   type AnalysisResult,
-  type CostRisk,
+  COST_RISK_ORDER,
   DEFAULT_THRESHOLDS,
+  maxCostRisk,
   mergeResults,
   type Thresholds,
 } from "../types.js";
@@ -55,13 +56,19 @@ import {
   isAzqrReportMasked,
   loadAzqrReport,
 } from "./azqr.js";
+import {
+  categorizeCustomFindings,
+  MISSING_TAGS_REASON,
+  NO_ANALYZER_REASON,
+  unpreferredLocationReason,
+} from "./finding-category.js";
+import { assignCustomFindingCodes } from "./finding-code.js";
+import { foldDuplicateFinding } from "./finding-dedup.js";
 import { PricingClient, PricingService } from "./pricing/index.js";
 import { matchesTags, type MetricsCache } from "./utils.js";
 
 const DEFAULT_CONCURRENCY = 8;
 
-const RISK_ORDER: Record<CostRisk, number> = { high: 0, low: 2, medium: 1 };
-
 /**
  * Analyzes resources in every configured Azure subscription and returns
  * the structured report.
@@ -195,7 +202,10 @@ export async function analyzeAzureResources(
     if (aSub !== bSub) return aSub ? 1 : -1;
     if (a.analysis.costRisk === b.analysis.costRisk)
       return (a.resource.name ?? "").localeCompare(b.resource.name ?? "");
-    return RISK_ORDER[a.analysis.costRisk] - RISK_ORDER[b.analysis.costRisk];
+    return (
+      COST_RISK_ORDER[a.analysis.costRisk] -
+      COST_RISK_ORDER[b.analysis.costRisk]
+    );
   });
 
   return allReports;
@@ -236,7 +246,7 @@ export async function analyzeResource(
   // Generic check: lack of tags is a common sign of unmanaged resources.
   if (!resource.tags || Object.keys(resource.tags).length === 0) {
     result.suspectedUnused = true;
-    result.reason += "No tags found. ";
+    result.reason += `${MISSING_TAGS_REASON} `;
   }
 
   const ctx: AnalyzerContext = {
@@ -261,7 +271,7 @@ export async function analyzeResource(
   }
 
   if (!matched) {
-    result.reason += "No specific analysis for this resource type. ";
+    result.reason += `${NO_ANALYZER_REASON} `;
   }
 
   // Generic check for location
@@ -269,7 +279,7 @@ export async function analyzeResource(
     resource.location &&
     !resource.location.toLowerCase().includes(preferredLocation.toLowerCase())
   ) {
-    result.reason += `Resource not in preferred location (${preferredLocation}). `;
+    result.reason += `${unpreferredLocationReason(preferredLocation)} `;
   }
 
   return { ...result, reason: result.reason.trim() };
@@ -294,10 +304,7 @@ export function mergeFinding(
     // don't produce "Sentence one.Sentence two." when the existing reason is
     // already trimmed (i.e. has no trailing separator space).
     existing.analysis = {
-      costRisk:
-        RISK_ORDER[existing.analysis.costRisk] <= RISK_ORDER[added.costRisk]
-          ? existing.analysis.costRisk
-          : added.costRisk,
+      costRisk: maxCostRisk(existing.analysis.costRisk, added.costRisk),
       estimatedMonthlySavings: existing.analysis.estimatedMonthlySavings,
       reason:
         existing.analysis.reason && added.reason
@@ -451,6 +458,11 @@ function hasTagFilter(filterTags: Map<string, string> | undefined): boolean {
  * report collected during the live scan so AZQR findings attach to their
  * resource when present or create a stub otherwise.
  *
+ * Findings that duplicate what a live source already reported for the same
+ * resource are folded into the existing finding instead of being appended, so
+ * an orphaned resource seen by both AZQR and Advisor/custom analyzers shows up
+ * once — on the entry that carries the monetary estimate.
+ *
  * When the report is still masked, findings cannot match live resource IDs, so
  * a warning advises re-running AZQR with `--mask=false`.
  */
@@ -472,11 +484,22 @@ async function ingestAzqrReport(
   const reportsById = new Map<string, AzureDetailedResourceReport>(
     reports.map((r) => [(r.resource.id ?? "").toLowerCase(), r]),
   );
+  let merged = 0;
+  let deduplicated = 0;
   for (const finding of findings) {
+    const existing = reportsById.get(finding.resourceId.toLowerCase());
+    if (existing && foldDuplicateFinding(finding, existing)) {
+      deduplicated++;
+      continue;
+    }
     mergeFinding(finding, reports, reportsById);
+    merged++;
   }
   logger.info(
-    `AZQR: merged ${findings.length} finding(s) from ${azqrReportPath}`,
+    `AZQR: merged ${merged} finding(s) from ${azqrReportPath}` +
+      (deduplicated > 0
+        ? `, ${deduplicated} deduplicated onto existing findings`
+        : ""),
   );
 }
 
@@ -569,16 +592,29 @@ async function runPerResourceAnalysis(args: {
 
       if (analysis.suspectedUnused) {
         const reason = analysis.reason || "No specific findings.";
+        const findings = assignCustomFindingCodes(
+          categorizeCustomFindings(
+            findingsFromAnalysisResult({
+              reason,
+              resourceId: resource.id ?? "",
+              severity: analysis.costRisk,
+              source: "custom",
+            }),
+          ),
+        );
         const report: AzureDetailedResourceReport = {
           analysis: { ...analysis, reason },
-          findings: findingsFromAnalysisResult({
-            reason,
-            resourceId: resource.id ?? "",
-            severity: analysis.costRisk,
-            source: "custom",
-          }),
+          findings: [],
           resource,
         };
+        // Fold sentences that share a stable recommendationId so e.g. two
+        // "Very low CPU usage" hits on the same resource collapse into one
+        // row instead of appearing as separate findings.
+        for (const finding of findings) {
+          if (!foldDuplicateFinding(finding, report)) {
+            report.findings?.push(finding);
+          }
+        }
         reports.push(report);
         const idKey = (resource.id ?? "").toLowerCase();
         if (idKey) reportsById.set(idKey, report);

package/src/azure/analyzers/__tests__/advisor.test.ts

@@ -365,3 +365,63 @@ describe("createAdvisorAnalyzer — filtering", () => {
     expect(findings[0].reason).toBe("Azure Advisor cost recommendation.");
   });
 });
+
+describe("createAdvisorAnalyzer — cross-source identity", () => {
+  it("namespaces the recommendation type id of resource-level findings", async () => {
+    const analyzer = createAdvisorAnalyzer({
+      build: () =>
+        makeFakeClient([
+          {
+            category: "Cost",
+            impact: "High",
+            recommendationTypeId: "right-size-vm",
+            resourceMetadata: { resourceId: RID1 },
+            shortDescription: { problem: "p" },
+          },
+        ]),
+    });
+
+    const findings = await analyzer.analyze(makeCtx());
+
+    expect(findings[0].recommendationId).toBe("advisor.right-size-vm");
+  });
+
+  it("namespaces the recommendation type id of subscription-level findings", async () => {
+    const SUB_URI = "/subscriptions/00000000-0000-0000-0000-000000000000";
+    const analyzer = createAdvisorAnalyzer({
+      build: () =>
+        makeFakeClient([
+          {
+            category: "Cost",
+            extendedProperties: { savingsAmount: "50", savingsCurrency: "EUR" },
+            impact: "High",
+            recommendationTypeId: "vm-ri",
+            resourceMetadata: { resourceId: SUB_URI },
+            shortDescription: { problem: "Buy VM reserved instance" },
+          },
+        ]),
+    });
+
+    const findings = await analyzer.analyze(makeCtx());
+
+    expect(findings[0].recommendationId).toBe("advisor.vm-ri");
+  });
+
+  it("leaves the recommendation id unset when Advisor reports no type", async () => {
+    const analyzer = createAdvisorAnalyzer({
+      build: () =>
+        makeFakeClient([
+          {
+            category: "Cost",
+            impact: "Low",
+            resourceMetadata: { resourceId: RID1 },
+            shortDescription: { problem: "p" },
+          },
+        ]),
+    });
+
+    const findings = await analyzer.analyze(makeCtx());
+
+    expect(findings[0].recommendationId).toBeUndefined();
+  });
+});

package/src/azure/analyzers/advisor.ts

@@ -153,6 +153,18 @@ function addToSubGroups(
   }
 }
 
+/**
+ * Namespaced canonical identity of an Advisor recommendation. Combined with the
+ * resource ID it is the deduplication key that lets the same problem reported
+ * by another source collapse onto this finding. Left unset when Advisor does
+ * not report a type ID, so unrelated recommendations are never merged.
+ */
+function advisorRecommendationId(
+  recommendationTypeId: string | undefined,
+): string | undefined {
+  return recommendationTypeId ? `advisor.${recommendationTypeId}` : undefined;
+}
+
 function buildResourceFinding(
   rec: RecommendationInfo,
   savings: undefined | { amount: number; currency: string },
@@ -168,6 +180,7 @@ function buildResourceFinding(
     code: `advisor.${rec.recommendationTypeId ?? "unknown"}`,
     estimatedMonthlySavings: savings,
     reason: enrichReason(problem, props),
+    recommendationId: advisorRecommendationId(rec.recommendationTypeId),
     recommendedAction: rec.shortDescription?.solution,
     resourceId: rawResourceId,
     severity: mapImpact(rec.impact),
@@ -202,6 +215,7 @@ function createSubGroup(
       category: "cost",
       code: `advisor.${typeKey}`,
       reason,
+      recommendationId: advisorRecommendationId(rec.recommendationTypeId),
       recommendedAction: rec.shortDescription?.solution,
       resourceId,
       severity: mapImpact(rec.impact),