@pagopa/dx-savemoney 0.2.5 → 0.2.6

package/src/azure/resources/container-app.ts

@@ -13,6 +13,7 @@ import type { AnalysisResult, Thresholds } from "../../types.js";
 import { DEFAULT_THRESHOLDS } from "../../types.js";
 import {
   getMetric,
+  type MetricsCache,
   verboseLog,
   verboseLogAnalysisResult,
   verboseLogResourceStart,
@@ -35,6 +36,7 @@ export async function analyzeContainerApp(
   timespanDays: number,
   thresholds: Thresholds = DEFAULT_THRESHOLDS,
   verbose = false,
+  cache?: MetricsCache,
 ): Promise<AnalysisResult> {
   verboseLogResourceStart(
     verbose,
@@ -84,6 +86,7 @@ export async function analyzeContainerApp(
       thresholds,
       reason,
       verbose,
+      cache,
     );
     reason = await checkNetworkMetrics(
       resource,
@@ -92,6 +95,7 @@ export async function analyzeContainerApp(
       thresholds,
       reason,
       verbose,
+      cache,
     );
   } catch (error) {
     const logger = getLogger(["savemoney", "azure"]);
@@ -117,6 +121,7 @@ async function checkNetworkMetrics(
   thresholds: Thresholds,
   reason: string,
   verbose: boolean,
+  cache?: MetricsCache,
 ): Promise<string> {
   let newReason = reason;
 
@@ -132,6 +137,7 @@ async function checkNetworkMetrics(
     "RxBytes",
     "Average",
     timespanDays,
+    cache,
   );
 
   const networkOut = await getMetric(
@@ -140,6 +146,7 @@ async function checkNetworkMetrics(
     "TxBytes",
     "Average",
     timespanDays,
+    cache,
   );
 
   verboseLog(
@@ -172,6 +179,7 @@ async function checkResourceMetrics(
   thresholds: Thresholds,
   reason: string,
   verbose: boolean,
+  cache?: MetricsCache,
 ): Promise<string> {
   let newReason = reason;
 
@@ -187,6 +195,7 @@ async function checkResourceMetrics(
     "UsageNanoCores",
     "Average",
     timespanDays,
+    cache,
   );
 
   const memoryUsage = await getMetric(
@@ -195,6 +204,7 @@ async function checkResourceMetrics(
     "WorkingSetBytes",
     "Average",
     timespanDays,
+    cache,
   );
 
   verboseLog(

package/src/azure/resources/public-ip.ts

@@ -13,6 +13,7 @@ import type { AnalysisResult, Thresholds } from "../../types.js";
 import { DEFAULT_THRESHOLDS } from "../../types.js";
 import {
   getMetric,
+  type MetricsCache,
   verboseLog,
   verboseLogAnalysisResult,
   verboseLogResourceStart,
@@ -34,6 +35,7 @@ export async function analyzePublicIp(
   timespanDays: number,
   thresholds: Thresholds = DEFAULT_THRESHOLDS,
   verbose = false,
+  cache?: MetricsCache,
 ): Promise<AnalysisResult> {
   verboseLogResourceStart(
     verbose,
@@ -87,6 +89,7 @@ export async function analyzePublicIp(
       "BytesInDDoS",
       "Average",
       timespanDays,
+      cache,
     );
 
     if (bytesInDDoS !== null && bytesInDDoS < thresholds.publicIp.bytesInDDoS) {

package/src/azure/resources/static-web-app.ts

@@ -12,6 +12,7 @@ import type { AnalysisResult, Thresholds } from "../../types.js";
 import { DEFAULT_THRESHOLDS } from "../../types.js";
 import {
   getMetric,
+  type MetricsCache,
   verboseLog,
   verboseLogAnalysisResult,
   verboseLogResourceStart,
@@ -32,6 +33,7 @@ export async function analyzeStaticSite(
   timespanDays: number,
   thresholds: Thresholds = DEFAULT_THRESHOLDS,
   verbose = false,
+  cache?: MetricsCache,
 ): Promise<AnalysisResult> {
   verboseLogResourceStart(
     verbose,
@@ -63,6 +65,7 @@ export async function analyzeStaticSite(
       "SiteHits",
       "Total",
       timespanDays,
+      cache,
     );
 
     const bytesSent = await getMetric(
@@ -71,6 +74,7 @@ export async function analyzeStaticSite(
       "BytesSent",
       "Total",
       timespanDays,
+      cache,
     );
 
     verboseLog(

package/src/azure/resources/storage.ts

@@ -11,6 +11,7 @@ import type { AnalysisResult, Thresholds } from "../../types.js";
 import { DEFAULT_THRESHOLDS } from "../../types.js";
 import {
   getMetric,
+  type MetricsCache,
   verboseLog,
   verboseLogAnalysisResult,
   verboseLogResourceStart,
@@ -30,6 +31,7 @@ export async function analyzeStorageAccount(
   timespanDays: number,
   thresholds: Thresholds = DEFAULT_THRESHOLDS,
   verbose = false,
+  cache?: MetricsCache,
 ): Promise<AnalysisResult> {
   verboseLogResourceStart(
     verbose,
@@ -52,6 +54,7 @@ export async function analyzeStorageAccount(
     "Transactions",
     "Average",
     timespanDays,
+    cache,
   );
   if (
     transactions !== null &&

package/src/azure/resources/vm.ts

@@ -13,6 +13,7 @@ import type { AnalysisResult, Thresholds } from "../../types.js";
 import { DEFAULT_THRESHOLDS } from "../../types.js";
 import {
   getMetric,
+  type MetricsCache,
   verboseLog,
   verboseLogAnalysisResult,
   verboseLogResourceStart,
@@ -35,6 +36,7 @@ export async function analyzeVM(
   timespanDays: number,
   thresholds: Thresholds = DEFAULT_THRESHOLDS,
   verbose = false,
+  cache?: MetricsCache,
 ): Promise<AnalysisResult> {
   verboseLogResourceStart(
     verbose,
@@ -107,6 +109,7 @@ export async function analyzeVM(
     "Percentage CPU",
     "Average",
     timespanDays,
+    cache,
   );
   const networkIn = await getMetric(
     monitorClient,
@@ -114,6 +117,7 @@ export async function analyzeVM(
     "Network In Total",
     "Average",
     timespanDays,
+    cache,
   );
 
   if (cpuUsage !== null && cpuUsage < thresholds.vm.cpuPercent) {

package/src/azure/types.ts

@@ -15,6 +15,12 @@ import type {
  * Azure configuration extending base config
  */
 export type AzureConfig = BaseConfig & {
+  /**
+   * Maximum number of resources analyzed in parallel within a single
+   * subscription. Defaults to 8 when not provided. Set to 1 for a fully
+   * sequential run (useful for debugging or to be gentler on quotas).
+   */
+  concurrency?: number;
   /**
    * Only analyze resources that match ALL the given tag key-value pairs.
    * If omitted, all resources are analyzed.

package/src/azure/utils.ts

@@ -9,6 +9,19 @@ import { getLogger } from "@logtape/logtape";
 
 import type { AnalysisResult } from "../types.js";
 
+/** Per-run in-memory cache for Azure Monitor metric responses. */
+export type MetricsCache = Map<string, Promise<null | number>>;
+
+/**
+ * Minimal interface required by `getMetric` — only the `metrics.list` shape.
+ * Using a structural type instead of the full `MonitorClient` keeps tests
+ * strongly typed without unsafe casts and lets non-Azure callers supply a
+ * compatible mock.
+ */
+export type MonitorClientLike = {
+  metrics: Pick<MonitorClient["metrics"], "list">;
+};
+
 type MetricDataPoint = {
   average?: number;
   count?: number;
@@ -104,59 +117,61 @@ export function extractAggregatedValue(
 }
 
 /**
- * Fetches a specific metric for a resource from Azure Monitor.
+ * Module-scoped fallback cache. Used when callers of `getMetric` do not
+ * supply a run-scoped cache. Prefer passing an explicit `MetricsCache`
+ * instance through `AnalyzerContext` so concurrent runs stay isolated.
+ */
+const metricsCache: MetricsCache = new Map();
+
+/**
+ * @internal — exposed for tests only.
+ */
+export function _metricsCacheSize(): number {
+  return metricsCache.size;
+}
+
+/**
+ * Fetches a specific metric for a resource from Azure Monitor, with an
+ * in-memory cache to deduplicate concurrent and repeated lookups within
+ * the same run.
+ *
+ * Concurrent callers for the same `(resourceId, metricName, aggregation,
+ * timespanDays)` tuple share the same underlying request.
  *
- * @param monitorClient - The Azure Monitor client instance
+ * Pass an explicit `cache` (created per run in the orchestrator) to keep
+ * concurrent analysis runs isolated from each other. When omitted, the
+ * module-scoped fallback cache is used — safe for sequential runs.
+ *
+ * @param monitorClient - Azure Monitor client (or compatible mock)
  * @param resourceId - The Azure resource ID
  * @param metricName - The name of the metric to fetch (e.g., "Percentage CPU")
  * @param aggregation - The aggregation type (e.g., "Average", "Total")
  * @param timespanDays - Number of days to look back for metrics
+ * @param cache - Optional run-scoped cache; falls back to the module-scoped one
  * @returns The metric value or null if unavailable
  */
 export async function getMetric(
-  monitorClient: MonitorClient,
+  monitorClient: MonitorClientLike,
   resourceId: string,
   metricName: string,
   aggregation: string,
   timespanDays: number,
+  cache: MetricsCache = metricsCache,
 ): Promise<null | number> {
-  try {
-    const timespan = `P${timespanDays}D`;
-    const result = await monitorClient.metrics.list(resourceId, {
-      aggregation,
-      metricnames: metricName,
-      timespan,
-    });
-
-    if (result.value.length === 0) {
-      return null;
-    }
-
-    const metric = result.value[0];
-
-    if (!metric.timeseries || metric.timeseries.length === 0) {
-      return null;
-    }
-
-    const timeserie = metric.timeseries[0];
-
-    if (!timeserie.data || timeserie.data.length === 0) {
-      return null;
-    }
-
-    const aggregatedValue = aggregateDataPoints(
-      timeserie.data as MetricDataPoint[],
-      aggregation,
-    );
-
-    return aggregatedValue;
-  } catch (error) {
-    const logger = getLogger(["savemoney", "azure", "metrics"]);
-    logger.error(
-      `Failed to fetch metric ${metricName} for resource ${resourceId}: ${error instanceof Error ? error.message : String(error)}`,
-    );
-    return null;
+  const key = `${resourceId}|${metricName}|${aggregation}|${timespanDays}`;
+  const cached = cache.get(key);
+  if (cached !== undefined) {
+    return cached;
   }
+  const promise = fetchMetric(
+    monitorClient,
+    resourceId,
+    metricName,
+    aggregation,
+    timespanDays,
+  );
+  cache.set(key, promise);
+  return promise;
 }
 
 /**
@@ -179,6 +194,16 @@ export function matchesTags(
   );
 }
 
+/**
+ * Clears the module-scoped fallback metrics cache.
+ *
+ * Only needed when `getMetric` is called without an explicit `cache`
+ * argument. Prefer passing a run-scoped `MetricsCache` instead.
+ */
+export function resetMetricsCache(): void {
+  metricsCache.clear();
+}
+
 /**
  * Logs a verbose message, optionally with an object.
  *
@@ -243,3 +268,49 @@ export function verboseLogResourceStart(
     logger.debug("=".repeat(80));
   }
 }
+
+async function fetchMetric(
+  monitorClient: MonitorClientLike,
+  resourceId: string,
+  metricName: string,
+  aggregation: string,
+  timespanDays: number,
+): Promise<null | number> {
+  try {
+    const timespan = `P${timespanDays}D`;
+    const result = await monitorClient.metrics.list(resourceId, {
+      aggregation,
+      metricnames: metricName,
+      timespan,
+    });
+
+    if (result.value.length === 0) {
+      return null;
+    }
+
+    const metric = result.value[0];
+
+    if (!metric.timeseries || metric.timeseries.length === 0) {
+      return null;
+    }
+
+    const timeserie = metric.timeseries[0];
+
+    if (!timeserie.data || timeserie.data.length === 0) {
+      return null;
+    }
+
+    const aggregatedValue = aggregateDataPoints(
+      timeserie.data as MetricDataPoint[],
+      aggregation,
+    );
+
+    return aggregatedValue;
+  } catch (error) {
+    const logger = getLogger(["savemoney", "azure", "metrics"]);
+    logger.error(
+      `Failed to fetch metric ${metricName} for resource ${resourceId}: ${error instanceof Error ? error.message : String(error)}`,
+    );
+    return null;
+  }
+}

package/src/finding.ts

@@ -0,0 +1,152 @@
+/**
+ * Unified Finding model — the single representation of a cost-related
+ * observation, regardless of its source (custom analyzers, Azure Advisor,
+ * future AWS Trusted Advisor, …).
+ *
+ * Introduced in Phase 0 of the savemoney evolution roadmap. Existing
+ * `AnalysisResult`-based analyzers keep working untouched: an adapter
+ * (`findingsFromAnalysisResult`) splits the concatenated `reason` string
+ * into one `Finding` per sentence, so downstream consumers can already
+ * reason in terms of `Finding[]`.
+ */
+
+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)`.
+ */
+export type Finding = {
+  /**
+   * Cloud category. Today every custom finding is "cost"; Advisor may
+   * surface other categories that we currently ignore.
+   */
+  category: FindingCategory;
+  /**
+   * 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.
+   */
+  code: string;
+  /**
+   * Estimated monthly cost that could be recovered by acting on this
+   * finding. Populated by Advisor and (in later phases) by the Retail
+   * Prices integration. Absent when the analyzer cannot estimate it.
+   */
+  estimatedMonthlySavings?: Money;
+  /**
+   * Free-text, human-readable description. Backward compatible with the
+   * legacy `AnalysisResult.reason` field.
+   */
+  reason: string;
+  /**
+   * Optional, machine-friendly hint about how to remediate. For Advisor
+   * this typically maps to `shortDescription.solution`.
+   */
+  recommendedAction?: string;
+  /**
+   * Fully qualified Azure / cloud resource ID this finding refers to.
+   */
+  resourceId: string;
+  /**
+   * Cost risk classification. Maps Advisor's `impact` (High/Medium/Low)
+   * 1:1 onto the savemoney scale.
+   */
+  severity: CostRisk;
+  /**
+   * Provenance of the finding.
+   */
+  source: FindingSource;
+};
+
+/**
+ * Cloud category a finding belongs to. For now we focus on cost, but the
+ * model is open to future Advisor categories.
+ */
+export type FindingCategory =
+  | "cost"
+  | "operationalExcellence"
+  | "performance"
+  | "reliability"
+  | "security";
+
+/**
+ * Where the finding originated from.
+ *
+ * - `custom`  → emitted by a savemoney analyzer plugin
+ * - `advisor` → fetched from Azure Advisor recommendations
+ * - `aws`     → reserved for future AWS Trusted Advisor / Compute Optimizer
+ */
+export type FindingSource = "advisor" | "aws" | "custom";
+
+/**
+ * Monetary value associated with a finding, when known.
+ * Amounts use ISO 4217 currency codes (e.g. "EUR", "USD").
+ */
+export type Money = {
+  amount: number;
+  currency: string;
+};
+
+/**
+ * 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.
+ */
+export type ResourceReport<TResource = unknown> = {
+  findings: Finding[];
+  resource: TResource;
+};
+
+/**
+ * Adapter: converts a legacy `AnalysisResult` (single concatenated
+ * reason) into a list of `Finding`s, one per sentence.
+ *
+ * @param resourceId      Fully qualified resource ID
+ * @param severity        Cost risk classification produced by the analyzer
+ * @param reason          Concatenated reason string (sentences joined by ". ")
+ * @param source          Provenance (default: "custom")
+ * @param code            Optional stable identifier for the finding kind
+ *                        (e.g. `"vm.deallocated"`). Defaults to
+ *                        `"custom.unknown"` when omitted.
+ */
+export function findingsFromAnalysisResult(args: {
+  code?: string;
+  reason: string;
+  resourceId: string;
+  severity: CostRisk;
+  source?: FindingSource;
+}): Finding[] {
+  const { code, reason, resourceId, severity, source = "custom" } = args;
+  const sentences = splitReasonIntoSentences(reason);
+  if (sentences.length === 0) {
+    return [];
+  }
+  return sentences.map((sentence) => ({
+    category: "cost" as const,
+    code: code ?? "custom.unknown",
+    reason: sentence,
+    resourceId,
+    severity,
+    source,
+  }));
+}
+
+/**
+ * Splits a concatenated reason string (sentences joined by ". ") into
+ * individual non-empty sentences. Mirrors the logic already used by the
+ * lint reporter so behaviour stays consistent.
+ */
+function splitReasonIntoSentences(reason: string): string[] {
+  return reason
+    .split(/\.\s+|\.$/)
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0)
+    .map((s) => (s.endsWith(".") ? s : `${s}.`));
+}

package/src/index.ts

@@ -13,6 +13,13 @@
  * This tool does NOT modify, tag, or delete any resources.
  */
 
+export {
+  type Analyzer,
+  type AnalyzerContext,
+  type AzureClients,
+  createDefaultAnalyzers,
+} from "./azure/analyzers/index.js";
+
 // Export common types
 export type { AzureConfig } from "./azure/types.js";
 
@@ -20,6 +27,17 @@ export type { AzureConfig } from "./azure/types.js";
 import * as azureModule from "./azure/index.js";
 export const azure = azureModule;
 
+export { type MetricsCache, type MonitorClientLike } from "./azure/utils.js";
+
+// Phase 0: unified Finding model and analyzer plugin layer
+export {
+  type Finding,
+  type FindingCategory,
+  findingsFromAnalysisResult,
+  type FindingSource,
+  type Money,
+  type ResourceReport,
+} from "./finding.js";
 export * from "./types.js";
 
 import type { AzureConfig } from "./azure/types.js";

package/src/schema.ts

@@ -105,6 +105,11 @@ export const ThresholdsSchema = z
 
 const AzureSectionSchema = z
   .object({
+    /**
+     * Maximum number of resources analyzed in parallel within a single
+     * subscription. Defaults to 8 when not provided.
+     */
+    concurrency: z.number().int().positive().optional(),
     preferredLocation: z.string().default("italynorth"),
     subscriptionIds: z
       .array(z.string())