@pagopa/dx-savemoney 0.6.4 → 0.6.6

package/src/azure/azqr.ts

@@ -23,9 +23,9 @@
  * resources — {@link isAzqrReportMasked} lets the orchestrator warn and advise
  * re-running with `azqr scan --mask=false`.
  *
- * Scope note (CES-2192 / Fase 1): only `impacted` rows are ingested, enriched
- * with `inventory` metadata when available. AZQR `advisor` rows are ignored to
- * avoid duplicating SaveMoney's own Azure Advisor cost query.
+ * Scope note: only `impacted` rows are ingested, enriched with `inventory`
+ * metadata when available. AZQR `advisor` rows are ignored to avoid
+ * duplicating SaveMoney's own Azure Advisor cost query.
  */
 
 import { readFile } from "node:fs/promises";
@@ -34,6 +34,7 @@ import { z } from "zod";
 import type { CostRisk } from "../types.js";
 
 import { type Finding } from "../finding.js";
+import { orphanRecommendationId } from "./finding-dedup.js";
 
 /** A single `impacted` row from an AZQR JSON report (fields we consume). */
 const azqrImpactedRowSchema = z.object({
@@ -140,6 +141,7 @@ export function azqrImpactedToFindings(report: AzqrReport): Finding[] {
         ? `azqr.${row.recommendationId}`
         : "azqr.impacted",
       reason: buildReason(row, inventory),
+      recommendationId: canonicalRecommendationId(row),
       recommendedAction: row.learn
         ? `${remediation} Learn more: ${row.learn}`
         : remediation,
@@ -172,7 +174,7 @@ export function classifyAzqrRow(
   if ((row.category ?? "").toLowerCase().includes("cost")) {
     return "cost";
   }
-  if ((row.source ?? "").toLowerCase() !== ORPHAN_CHECK_SOURCE) {
+  if (!isOrphanRow(row)) {
     return null;
   }
   const resourceType = (row.resourceType ?? "").toLowerCase();
@@ -254,6 +256,28 @@ function buildReason(
   return context.length > 0 ? `${sentence} (${context.join(", ")})` : sentence;
 }
 
+/**
+ * Canonical identity of the problem a row describes, used to deduplicate it
+ * against findings coming from other sources.
+ *
+ * Orphaned resources (AZQR's `AOR` check) map onto the shared
+ * `orphan.<resourceType>` vocabulary, so the same waste reported by Azure
+ * Advisor or by a custom analyzer collapses onto a single finding. Every other
+ * row keeps AZQR's own recommendation ID, namespaced so it can only ever match
+ * another AZQR row.
+ */
+function canonicalRecommendationId(row: AzqrImpactedRow): string | undefined {
+  if (isOrphanRow(row) && row.resourceType) {
+    return orphanRecommendationId(row.resourceType);
+  }
+  return row.recommendationId ? `azqr.${row.recommendationId}` : undefined;
+}
+
+/** Whether the row comes from AZQR's Azure Orphan Resources check. */
+function isOrphanRow(row: AzqrImpactedRow): boolean {
+  return (row.source ?? "").toLowerCase() === ORPHAN_CHECK_SOURCE;
+}
+
 /**
  * Maps AZQR/APRL `impact` (`High` | `Medium` | `Low`) onto the SaveMoney
  * `CostRisk` scale, defaulting to `low` for unknown values.

package/src/azure/finding-category.ts

@@ -0,0 +1,75 @@
+/**
+ * Categorisation of the reasons emitted by the custom (live-scan) Azure
+ * analyzers.
+ *
+ * The per-resource analyzers describe everything they observe in a single
+ * concatenated `reason` string, which `findingsFromAnalysisResult` then splits
+ * into one `Finding` per sentence. Historically every sentence was labelled
+ * `category: "cost"`, including governance and diagnostic observations such as
+ * missing tags or a failed detail lookup — statements that carry no billable
+ * waste and would suggest a "saving" that does not exist.
+ *
+ * This module separates the two: governance / diagnostic sentences are
+ * reported as `operationalExcellence`, leaving `cost` to mean "actual billable
+ * waste". The distinction is also what makes cross-source deduplication safe
+ * (see `finding-dedup.ts`): a resource flagged only for missing tags is not
+ * evidence that it is wasted, so it must not absorb the corresponding AZQR
+ * orphan row.
+ *
+ * The generic reason strings are defined here and consumed by `analyzer.ts`, so
+ * the classifier cannot drift from the text it has to recognise. `finding-code.ts`
+ * reuses the same constants to assign a stable per-sentence `recommendationId`,
+ * so both classifiers stay in sync with the actual analyzer output.
+ */
+
+import type { Finding, FindingCategory } from "../finding.js";
+
+/** Reason emitted when a resource carries no tags at all. */
+export const MISSING_TAGS_REASON = "No tags found.";
+
+/** Reason emitted when no analyzer plugin supports the resource type. */
+export const NO_ANALYZER_REASON =
+  "No specific analysis for this resource type.";
+
+/**
+ * Prefix of the diagnostic sentences emitted by the per-resource analyzers when
+ * an Azure detail lookup fails (e.g. "Could not retrieve detailed NIC
+ * information."). They report a gap in the scan, not a cost opportunity.
+ */
+export const DETAIL_LOOKUP_FAILURE_PREFIX = "could not retrieve detailed";
+
+/** Prefix of the reason emitted when a resource sits outside the target region. */
+export const UNPREFERRED_LOCATION_REASON = "Resource not in preferred location";
+
+/**
+ * Re-categorises the findings produced from a custom analyzer's `reason`
+ * string, so governance and diagnostic sentences stop being reported as cost
+ * opportunities.
+ */
+export function categorizeCustomFindings(findings: Finding[]): Finding[] {
+  return findings.map((finding) => ({
+    ...finding,
+    category: categorizeCustomReason(finding.reason),
+  }));
+}
+
+/** Builds the reason emitted when a resource sits outside the target region. */
+export function unpreferredLocationReason(preferredLocation: string): string {
+  return `${UNPREFERRED_LOCATION_REASON} (${preferredLocation}).`;
+}
+
+/**
+ * Classifies a single custom analyzer sentence.
+ *
+ * @returns `"operationalExcellence"` for governance / diagnostic statements,
+ *          `"cost"` for everything else (the analyzers' actual waste signals).
+ */
+function categorizeCustomReason(reason: string): FindingCategory {
+  const normalized = reason.trim().toLowerCase();
+  const isNonCost =
+    normalized.startsWith(MISSING_TAGS_REASON.toLowerCase()) ||
+    normalized.startsWith(NO_ANALYZER_REASON.toLowerCase()) ||
+    normalized.startsWith(UNPREFERRED_LOCATION_REASON.toLowerCase()) ||
+    normalized.startsWith(DETAIL_LOOKUP_FAILURE_PREFIX);
+  return isNonCost ? "operationalExcellence" : "cost";
+}

package/src/azure/finding-code.ts

@@ -0,0 +1,148 @@
+/**
+ * Stable per-sentence identity for custom (live-scan) analyzer findings.
+ *
+ * `Finding.recommendationId` powers cross-source dedup, but custom analyzer
+ * sentences were deliberately excluded from it: every sentence produced by
+ * `findingsFromAnalysisResult` shared the generic `code: "custom.unknown"`
+ * and had no stable identifier, so two different sentences could never be
+ * told apart safely.
+ *
+ * This module closes that gap for the sentences whose wording is known ahead
+ * of time: each per-resource analyzer in `azure/resources/` builds its
+ * `reason` string from a fixed set of templates (e.g. "Disk is unattached.",
+ * "VM is deallocated."). This module recognises those templates by a
+ * case-insensitive prefix match on the (already sentence-split) `reason` and
+ * assigns both `code` and `recommendationId` to a stable `custom.<id>` value,
+ * following the same convention as `advisor.<recommendationTypeId>` /
+ * `azqr.<recommendationId>`. That is what lets `foldDuplicateFinding`
+ * (`finding-dedup.ts`) — whose matching is already identity-based and
+ * source-agnostic — collapse two custom findings that describe the same
+ * problem on the same resource.
+ *
+ * A handful of sentences are worded identically by more than one resource
+ * type (e.g. App Service Plan and Container App both emit "Very low CPU usage
+ * (…)."). Those intentionally share one generic code: dedup only ever
+ * compares findings within the same `resourceId`, and a resource can't be two
+ * types at once, so the shared code cannot cause a false merge across
+ * unrelated resources.
+ *
+ * Sentences that don't match any known template are left untouched — they
+ * keep `code: "custom.unknown"` and no `recommendationId`, exactly like
+ * before, so genuinely unrecognised text is never merged on a guess.
+ */
+
+import type { Finding } from "../finding.js";
+
+import {
+  DETAIL_LOOKUP_FAILURE_PREFIX,
+  MISSING_TAGS_REASON,
+  NO_ANALYZER_REASON,
+  UNPREFERRED_LOCATION_REASON,
+} from "./finding-category.js";
+
+/** Shared prefix for every stable custom finding id, mirroring `advisor.<id>` / `azqr.<id>`. */
+const CODE_PREFIX = "custom.";
+
+/**
+ * Ordered `(normalized reason prefix, code suffix)` pairs. Evaluated
+ * top-to-bottom; the first match wins. Prefixes are matched against the
+ * trimmed, lower-cased `reason`, so the dynamic suffixes analyzers append
+ * (percentages, byte counts, durations, …) never break the match.
+ */
+const REASON_CODES: readonly (readonly [string, string])[] = [
+  // Generic — emitted by (almost) every per-resource analyzer.
+  ["resource id is missing.", "missing-resource-id"],
+  [DETAIL_LOOKUP_FAILURE_PREFIX, "lookup-failed"],
+  [MISSING_TAGS_REASON.toLowerCase(), "missing-tags"],
+  [NO_ANALYZER_REASON.toLowerCase(), "no-analyzer"],
+  [UNPREFERRED_LOCATION_REASON.toLowerCase(), "unpreferred-location"],
+
+  // Managed Disk (azure/resources/disk.ts)
+  ["disk is unattached.", "disk.unattached"],
+
+  // Network Interface (azure/resources/nic.ts)
+  ["nic not attached to any vm or private endpoint.", "nic.unattached"],
+  ["no public ip assigned.", "nic.no-public-ip"],
+
+  // Private Endpoint (azure/resources/private-endpoint.ts)
+  [
+    "private endpoint has no private link service connections configured.",
+    "private-endpoint.no-connections",
+  ],
+  [
+    "private endpoint has rejected or disconnected connections.",
+    "private-endpoint.rejected-connection",
+  ],
+  [
+    "private endpoint has no network interfaces attached.",
+    "private-endpoint.no-nics",
+  ],
+  [
+    "private endpoint is not associated with a subnet.",
+    "private-endpoint.no-subnet",
+  ],
+
+  // Container App (azure/resources/container-app.ts)
+  ["container app is not running.", "container-app.not-running"],
+  ["container app has 0 replicas configured.", "container-app.zero-replicas"],
+
+  // App Service Plan (azure/resources/app-service.ts)
+  ["app service plan has no apps deployed.", "app-service.no-apps"],
+  [
+    "premium tier with low resource utilization.",
+    "app-service.premium-underutilized",
+  ],
+
+  // Public IP (azure/resources/public-ip.ts)
+  ["public ip not associated with any resource.", "public-ip.unassociated"],
+  ["static ip not in use.", "public-ip.static-unused"],
+
+  // Storage Account (azure/resources/storage.ts)
+  ["very low transaction count (", "storage.low-transactions"],
+
+  // Virtual Machine (azure/resources/vm.ts) — worded distinctly ("Low ...",
+  // no "Very") from the shared "Very low ..." family below.
+  ["vm is deallocated.", "vm.deallocated"],
+  ["vm is stopped.", "vm.stopped"],
+  ["low cpu usage (avg", "vm.low-cpu-usage"],
+  ["low network traffic (", "vm.low-network-traffic"],
+
+  // Static Web App (azure/resources/static-web-app.ts)
+  ["no traffic data available in", "static-site.no-traffic-data"],
+  ["very low site traffic (", "static-site.low-traffic"],
+  ["very low data transfer (", "static-site.low-data-transfer"],
+
+  // Shared across resource types whose analyzers phrase the same signal with
+  // identical text — see module doc. App Service Plan + Container App for
+  // CPU/memory; Container App + Public IP for network traffic.
+  ["very low cpu usage (", "low-cpu-usage"],
+  ["very low memory usage (", "low-memory-usage"],
+  ["very low network traffic (", "low-network-traffic"],
+];
+
+/**
+ * Assigns a stable `code`/`recommendationId` to every custom finding whose
+ * `reason` matches a known sentence template, so equivalent sentences about
+ * the same resource collapse via `foldDuplicateFinding` instead of appearing
+ * as separate rows.
+ *
+ * Leaves untouched: non-`"custom"` findings, and findings that already carry
+ * a `recommendationId` (nothing to add) or whose `reason` matches no known
+ * template (stays `"custom.unknown"`, ungrouped — the same fallback behaviour
+ * as before this module existed).
+ */
+export function assignCustomFindingCodes(findings: Finding[]): Finding[] {
+  return findings.map((finding) => {
+    if (finding.source !== "custom" || finding.recommendationId) {
+      return finding;
+    }
+    const code = stableCodeFor(finding.reason);
+    return code ? { ...finding, code, recommendationId: code } : finding;
+  });
+}
+
+function stableCodeFor(reason: string): string | undefined {
+  const normalized = reason.trim().toLowerCase();
+  const match = REASON_CODES.find(([prefix]) => normalized.startsWith(prefix));
+  return match ? `${CODE_PREFIX}${match[1]}` : undefined;
+}

package/src/azure/finding-dedup.ts

@@ -0,0 +1,157 @@
+/**
+ * Cross-source deduplication of findings.
+ *
+ * SaveMoney observes the same subscription through three lenses: the custom
+ * live-scan analyzers, Azure Advisor, and an optional AZQR report. They
+ * overlap — an unattached disk is waste no matter who reports it — so the
+ * same resource could otherwise appear several times in the output, once per
+ * source. This also folds duplicate sentences emitted by the custom analyzers
+ * themselves (e.g. the same resource triggering the same "Very low CPU usage"
+ * template twice), since the matching below is source-agnostic.
+ *
+ * Findings are unified on the `resourceId + recommendationId` key. Sources
+ * normalise `recommendationId` onto a shared vocabulary whenever one exists:
+ * orphaned resources use {@link orphanRecommendationId} regardless of who
+ * detected them, which is what lets an AZQR `AOR` row collapse onto the
+ * Advisor or custom finding for the same resource. Custom analyzer sentences
+ * with a known template get a stable `custom.<id>` identity from
+ * `finding-code.ts`; sentences with no known template keep
+ * `code: "custom.unknown"` and no `recommendationId`, so they are never
+ * collapsed on guesswork. The surviving finding is the one carrying the
+ * monetary estimate (only Advisor and the pricing-enriched custom analyzers
+ * have one — AZQR reports no amounts at all), annotated with the
+ * corroborating source so the extra provenance is not lost.
+ */
+
+import type { Finding, FindingSource } from "../finding.js";
+import type { AzureDetailedResourceReport } from "./types.js";
+
+import { maxCostRisk } from "../types.js";
+
+/** Sources that observe the live subscription, as opposed to a static report. */
+const LIVE_SOURCES: ReadonlySet<FindingSource> = new Set(["advisor", "custom"]);
+
+/**
+ * Canonical identity prefix for "this resource is provisioned but unused".
+ * Shared by every source so orphan findings deduplicate across them.
+ */
+const ORPHAN_RECOMMENDATION_PREFIX = "orphan.";
+
+/**
+ * Folds `incoming` into an existing finding of `report` when both describe the
+ * same problem, so the resource is reported once instead of once per source.
+ *
+ * The surviving finding keeps the highest severity and the only available
+ * monetary estimate, and records the corroborating source both in its own
+ * reason and in the legacy per-resource `analysis` summary, so the `lint`,
+ * `json` and `table` formats all keep the provenance.
+ *
+ * @returns `true` when the finding was folded and must not be appended.
+ */
+export function foldDuplicateFinding(
+  incoming: Finding,
+  report: AzureDetailedResourceReport,
+): boolean {
+  const findings = report.findings;
+  if (!findings) {
+    return false;
+  }
+  const surviving = findDuplicateFinding(incoming, findings);
+  if (!surviving) {
+    return false;
+  }
+  const note = corroborationNote(surviving, incoming);
+  findings[findings.indexOf(surviving)] = {
+    ...surviving,
+    estimatedMonthlySavings:
+      surviving.estimatedMonthlySavings ?? incoming.estimatedMonthlySavings,
+    reason: note ? `${surviving.reason.trimEnd()} ${note}` : surviving.reason,
+    recommendationId: surviving.recommendationId ?? incoming.recommendationId,
+    severity: maxCostRisk(surviving.severity, incoming.severity),
+  };
+  report.analysis = {
+    ...report.analysis,
+    costRisk: maxCostRisk(report.analysis.costRisk, incoming.severity),
+    reason: note
+      ? `${report.analysis.reason.trimEnd()} ${note}`.trim()
+      : report.analysis.reason,
+  };
+  return true;
+}
+
+/**
+ * Builds the canonical identity of an orphaned resource of the given type,
+ * e.g. `orphan.microsoft.compute/disks`.
+ */
+export function orphanRecommendationId(resourceType: string): string {
+  return `${ORPHAN_RECOMMENDATION_PREFIX}${resourceType.toLowerCase()}`;
+}
+
+/**
+ * Short sentence appended to the surviving finding so the reader still sees
+ * that a second source flagged the same resource. Omitted for same-source
+ * duplicates, where there is no extra provenance to record, and when the same
+ * note is already there — repeated rows must corroborate, not accumulate.
+ */
+function corroborationNote(
+  surviving: Finding,
+  incoming: Finding,
+): string | undefined {
+  if (surviving.source === incoming.source) {
+    return undefined;
+  }
+  const note = isOrphanRecommendation(incoming.recommendationId)
+    ? `Also flagged by ${incoming.source} as an orphaned resource.`
+    : `Also flagged by ${incoming.source}.`;
+  return surviving.reason.includes(note) ? undefined : note;
+}
+
+/**
+ * Returns the already-collected finding that covers the same problem as
+ * `incoming`, or `undefined` when the incoming finding is genuinely new.
+ *
+ * Two findings describe the same problem when either:
+ *
+ * 1. they share the exact canonical identity (`recommendationId`) on the same
+ *    resource — a true duplicate, e.g. the same AZQR row ingested twice; or
+ * 2. `incoming` reports the resource as orphaned and a live source already
+ *    reported billable waste on it with no stronger identity of its own (e.g.
+ *    a sentence-level custom finding with no `recommendationId`). An orphaned
+ *    resource has a single cost problem — it exists — so the live finding,
+ *    which can carry a monetary estimate, supersedes the static one. A live
+ *    finding that already carries its own distinct `recommendationId` (e.g.
+ *    an Advisor right-sizing recommendation) is a different problem and is
+ *    never absorbed this way.
+ *
+ * Findings without a `recommendationId` never match: sentences whose text
+ * matches no known template (still `code: "custom.unknown"`, see
+ * `finding-code.ts`) must not be collapsed on guesswork.
+ */
+function findDuplicateFinding(
+  incoming: Finding,
+  existing: readonly Finding[],
+): Finding | undefined {
+  const identity = incoming.recommendationId?.toLowerCase();
+  if (!identity) {
+    return undefined;
+  }
+  const sameIdentity = existing.find(
+    (candidate) => candidate.recommendationId?.toLowerCase() === identity,
+  );
+  if (sameIdentity) {
+    return sameIdentity;
+  }
+  if (!isOrphanRecommendation(incoming.recommendationId)) {
+    return undefined;
+  }
+  return existing.find(
+    (candidate) =>
+      candidate.category === "cost" &&
+      LIVE_SOURCES.has(candidate.source) &&
+      !candidate.recommendationId,
+  );
+}
+
+function isOrphanRecommendation(recommendationId: string | undefined): boolean {
+  return (recommendationId ?? "").startsWith(ORPHAN_RECOMMENDATION_PREFIX);
+}

package/src/finding.ts

@@ -16,7 +16,8 @@ import type { CostRisk } from "./types.js";
  * A single, atomic observation about a resource.
  *
  * One resource can produce multiple findings (e.g. "no tags" + "low CPU").
- * Findings are designed to be deduplicated by `(resourceId, source, code)`.
+ * Findings are deduplicated on `(resourceId, recommendationId)` — see
+ * {@link Finding.recommendationId}.
  */
 export type Finding = {
   /**
@@ -27,8 +28,8 @@ export type Finding = {
   /**
    * Stable machine-readable identifier for the kind of finding, e.g.
    * `vm.deallocated`, `disk.unattached`, `advisor.right-size-vm`.
-   * Used for deduplication and grouping. Free-form for now to keep the
-   * adapter from existing analyzers cheap; can be tightened later.
+   * Free-form and source-specific: use `recommendationId` for
+   * deduplication across sources.
    */
   code: string;
   /**
@@ -42,6 +43,19 @@ export type Finding = {
    * legacy `AnalysisResult.reason` field.
    */
   reason: string;
+  /**
+   * Canonical, source-independent identity of the underlying problem.
+   * Together with `resourceId` it forms the deduplication key, so the same
+   * waste reported by different sources collapses into a single finding
+   * (see `azure/finding-dedup.ts`).
+   *
+   * Producers normalise it whenever a shared vocabulary exists — orphaned
+   * resources use `orphan.<resourceType>` regardless of the source that
+   * detected them — and fall back to their native recommendation ID
+   * otherwise. Left unset when the source has no stable identifier: such
+   * findings are never deduplicated.
+   */
+  recommendationId?: string;
   /**
    * Optional, machine-friendly hint about how to remediate. For Advisor
    * this typically maps to `shortDescription.solution`.
@@ -91,10 +105,8 @@ export type Money = {
 /**
  * Aggregate view: one resource with the list of findings emitted for it.
  *
- * This is the type future report generators should consume. The current
- * report layer still works on `AzureDetailedResourceReport`; a helper
- * (`legacyReportFromResourceReport`) bridges the two until the report
- * layer is migrated.
+ * This is the type future report generators should consume; the current
+ * report layer still works on `AzureDetailedResourceReport`.
  */
 export type ResourceReport<TResource = unknown> = {
   findings: Finding[];

package/src/types.ts

@@ -29,6 +29,13 @@ export type BaseConfig = {
 
 export type CostRisk = "high" | "low" | "medium";
 
+/** Cost risk ordering, from the most to the least severe. */
+export const COST_RISK_ORDER: Record<CostRisk, number> = {
+  high: 0,
+  low: 2,
+  medium: 1,
+};
+
 /**
  * Configurable thresholds used during resource analysis.
  * Derived from `ThresholdsSchema` — the schema is the single source of truth.
@@ -41,6 +48,15 @@ export type { Thresholds } from "./schema.js";
  */
 export const DEFAULT_THRESHOLDS = ThresholdsSchema.parse({});
 
+/**
+ * Returns the more severe of two cost risks. Used whenever two observations
+ * about the same resource (or the same problem seen by two sources) are
+ * combined, so severity never degrades silently.
+ */
+export function maxCostRisk(a: CostRisk, b: CostRisk): CostRisk {
+  return COST_RISK_ORDER[a] <= COST_RISK_ORDER[b] ? a : b;
+}
+
 /**
  * Merges analysis results, preserving existing reasons and combining suspectedUnused flags.
  */