@pagopa/dx-savemoney 0.2.5 → 0.3.0

package/src/azure/analyzers/registry.ts

@@ -0,0 +1,196 @@
+/**
+ * Default registry of Azure analyzers.
+ *
+ * Each entry wraps an existing per-type analyzer function (kept in
+ * `../resources/`) and exposes it through the unified `Analyzer`
+ * interface. The orchestrator simply iterates the registry — no big
+ * `switch` statement, no risk of forgetting to wire a new analyzer
+ * into the orchestrator when the catalog grows.
+ *
+ * Adding a new analyzer is a single insertion here.
+ */
+
+import type { SubscriptionAnalyzer } from "./subscription.js";
+import type { Analyzer } from "./types.js";
+
+import {
+  analyzeAppServicePlan,
+  analyzeContainerApp,
+  analyzeDisk,
+  analyzeNic,
+  analyzePrivateEndpoint,
+  analyzePublicIp,
+  analyzeStaticSite,
+  analyzeStorageAccount,
+  analyzeVM,
+} from "../resources/index.js";
+import { createAdvisorAnalyzer } from "./advisor.js";
+
+/**
+ * Builds the default set of analyzers in the same order they were
+ * previously evaluated by the orchestrator's `switch` statement. The
+ * order is not behaviourally meaningful today (each resource is matched
+ * by exactly one analyzer) but is kept deterministic for predictable
+ * logging and to ease future debugging.
+ */
+export function createDefaultAnalyzers(): Analyzer[] {
+  return [
+    {
+      analyze: ({
+        clients,
+        metricsCache,
+        resource,
+        thresholds,
+        timespanDays,
+        verbose,
+      }) =>
+        analyzeContainerApp(
+          resource,
+          clients.containerApps,
+          clients.monitor,
+          timespanDays,
+          thresholds,
+          verbose,
+          metricsCache,
+        ),
+      id: "azure.container-app",
+      supports: (r) => r.type?.toLowerCase() === "microsoft.app/containerapps",
+    },
+    {
+      analyze: ({ clients, resource, verbose }) =>
+        analyzeDisk(resource, clients.compute, verbose),
+      id: "azure.disk",
+      supports: (r) => r.type?.toLowerCase() === "microsoft.compute/disks",
+    },
+    {
+      analyze: ({
+        clients,
+        metricsCache,
+        resource,
+        thresholds,
+        timespanDays,
+        verbose,
+      }) =>
+        analyzeVM(
+          resource,
+          clients.monitor,
+          clients.compute,
+          timespanDays,
+          thresholds,
+          verbose,
+          metricsCache,
+        ),
+      id: "azure.vm",
+      supports: (r) =>
+        r.type?.toLowerCase() === "microsoft.compute/virtualmachines",
+    },
+    {
+      analyze: ({ clients, resource, verbose }) =>
+        analyzeNic(resource, clients.network, verbose),
+      id: "azure.nic",
+      supports: (r) =>
+        r.type?.toLowerCase() === "microsoft.network/networkinterfaces",
+    },
+    {
+      analyze: ({ clients, resource, verbose }) =>
+        analyzePrivateEndpoint(resource, clients.network, verbose),
+      id: "azure.private-endpoint",
+      supports: (r) =>
+        r.type?.toLowerCase() === "microsoft.network/privateendpoints",
+    },
+    {
+      analyze: ({
+        clients,
+        metricsCache,
+        resource,
+        thresholds,
+        timespanDays,
+        verbose,
+      }) =>
+        analyzePublicIp(
+          resource,
+          clients.network,
+          clients.monitor,
+          timespanDays,
+          thresholds,
+          verbose,
+          metricsCache,
+        ),
+      id: "azure.public-ip",
+      supports: (r) =>
+        r.type?.toLowerCase() === "microsoft.network/publicipaddresses",
+    },
+    {
+      analyze: ({
+        clients,
+        metricsCache,
+        resource,
+        thresholds,
+        timespanDays,
+        verbose,
+      }) =>
+        analyzeStorageAccount(
+          resource,
+          clients.monitor,
+          timespanDays,
+          thresholds,
+          verbose,
+          metricsCache,
+        ),
+      id: "azure.storage-account",
+      supports: (r) =>
+        r.type?.toLowerCase() === "microsoft.storage/storageaccounts",
+    },
+    {
+      analyze: ({
+        clients,
+        metricsCache,
+        resource,
+        thresholds,
+        timespanDays,
+        verbose,
+      }) =>
+        analyzeAppServicePlan(
+          resource,
+          clients.webSite,
+          clients.monitor,
+          timespanDays,
+          thresholds,
+          verbose,
+          metricsCache,
+        ),
+      id: "azure.app-service-plan",
+      supports: (r) => r.type?.toLowerCase() === "microsoft.web/serverfarms",
+    },
+    {
+      analyze: ({
+        clients,
+        metricsCache,
+        resource,
+        thresholds,
+        timespanDays,
+        verbose,
+      }) =>
+        analyzeStaticSite(
+          resource,
+          clients.monitor,
+          timespanDays,
+          thresholds,
+          verbose,
+          metricsCache,
+        ),
+      id: "azure.static-web-app",
+      supports: (r) => r.type?.toLowerCase() === "microsoft.web/staticsites",
+    },
+  ];
+}
+
+/**
+ * Builds the default set of subscription-level analyzers.
+ *
+ * Today this is just Azure Advisor; Phase 4 will add a quota / usages
+ * analyzer here. Adding new sources is a single insertion.
+ */
+export function createDefaultSubscriptionAnalyzers(): SubscriptionAnalyzer[] {
+  return [createAdvisorAnalyzer()];
+}

package/src/azure/analyzers/subscription.ts

@@ -0,0 +1,56 @@
+/**
+ * Subscription-level analyzer plugin contract.
+ *
+ * Some data sources are not naturally per-resource. Azure Advisor, for
+ * example, returns a flat list of recommendations for an entire
+ * subscription in a single call; future quota / `Microsoft.Capacity/usages`
+ * analyzers will follow the same shape.
+ *
+ * A `SubscriptionAnalyzer` is invoked once per subscription. It returns a
+ * flat list of `Finding`s carrying the `resourceId` they refer to; the
+ * orchestrator merges those findings into the per-resource reports.
+ *
+ * This interface is intentionally additive: per-resource `Analyzer`s
+ * (see `./types.ts`) keep working untouched. Sources written against the
+ * two interfaces can coexist in the same run.
+ */
+
+import type { TokenCredential } from "@azure/identity";
+
+import type { Finding } from "../../finding.js";
+
+/**
+ * Contract every subscription-level analyzer must satisfy.
+ */
+export type SubscriptionAnalyzer = {
+  /**
+   * Runs the analyzer for the given subscription. Implementations should
+   * be resilient: a failure here must not abort the whole run, the
+   * orchestrator logs and continues with the remaining analyzers.
+   */
+  analyze(ctx: SubscriptionContext): Promise<Finding[]>;
+  /**
+   * Stable identifier of the analyzer (e.g. `azure.advisor`,
+   * `azure.quota`). Used for logging and future deduplication logic.
+   */
+  readonly id: string;
+};
+
+/**
+ * Context passed to every subscription-level analyzer.
+ */
+export type SubscriptionContext = {
+  /**
+   * Azure credential to instantiate management clients. The orchestrator
+   * builds it once and reuses it across analyzers.
+   */
+  credential: TokenCredential;
+  /**
+   * Subscription ID to analyze.
+   */
+  subscriptionId: string;
+  /**
+   * Whether verbose logging is enabled.
+   */
+  verbose: boolean;
+};

package/src/azure/analyzers/types.ts

@@ -0,0 +1,66 @@
+/**
+ * Plugin architecture for Azure resource analyzers.
+ *
+ * Each `Analyzer` is a self-contained unit that:
+ *  1. declares the resource types it can handle (`supports`)
+ *  2. produces an `AnalysisResult` for a given resource (`analyze`)
+ *
+ * The orchestrator in `analyzer.ts` walks the registered analyzers for
+ * every resource it encounters. New sources (Azure Advisor, custom
+ * checks, pricing-enriched analyzers, …) can be added by implementing
+ * the interface and registering them in `registry.ts` without touching
+ * the orchestrator.
+ */
+
+import type { ContainerAppsAPIClient } from "@azure/arm-appcontainers";
+import type { WebSiteManagementClient } from "@azure/arm-appservice";
+import type { ComputeManagementClient } from "@azure/arm-compute";
+import type { MonitorClient } from "@azure/arm-monitor";
+import type { NetworkManagementClient } from "@azure/arm-network";
+import type * as armResources from "@azure/arm-resources";
+
+import type { AnalysisResult, Thresholds } from "../../types.js";
+import type { MetricsCache } from "../utils.js";
+
+/**
+ * Contract every analyzer must satisfy.
+ */
+export type Analyzer = {
+  analyze(ctx: AnalyzerContext): Promise<AnalysisResult>;
+  /**
+   * Stable identifier of the analyzer (e.g. `azure.vm`, `azure.advisor`).
+   * Used for logging, telemetry and future deduplication logic.
+   */
+  readonly id: string;
+  supports(resource: armResources.GenericResource): boolean;
+};
+
+/**
+ * Per-resource analysis context handed to every analyzer.
+ */
+export type AnalyzerContext = {
+  clients: AzureClients;
+  /**
+   * Run-scoped metrics cache. Pass through to `getMetric` calls so that
+   * concurrent `analyzeAzureResources` invocations stay isolated.
+   */
+  metricsCache: MetricsCache;
+  preferredLocation: string;
+  resource: armResources.GenericResource;
+  thresholds: Thresholds;
+  timespanDays: number;
+  verbose: boolean;
+};
+
+/**
+ * Bundle of Azure SDK clients an analyzer might need. The orchestrator
+ * builds them once per subscription and passes the same instances to
+ * every analyzer.
+ */
+export type AzureClients = {
+  compute: ComputeManagementClient;
+  containerApps: ContainerAppsAPIClient;
+  monitor: MonitorClient;
+  network: NetworkManagementClient;
+  webSite: WebSiteManagementClient;
+};

package/src/azure/config.ts

@@ -42,7 +42,9 @@ export async function loadAzureConfig(
       const rawYaml = yaml.load(raw);
       const parsed = ConfigSchema.parse(rawYaml);
       return {
+        concurrency: parsed.azure.concurrency,
         preferredLocation: parsed.azure.preferredLocation,
+        sources: parsed.azure.sources,
         subscriptionIds: parsed.azure.subscriptionIds,
         thresholds: parsed.azure.thresholds,
         timespanDays: parsed.azure.timespanDays,

package/src/azure/index.ts

@@ -6,4 +6,5 @@
 
 export * from "./analyzer.js";
 export * from "./config.js";
+export * from "./report.js";
 export * from "./types.js";

package/src/azure/report.ts

@@ -2,16 +2,25 @@
  * Azure report generation
  */
 
+import Table from "cli-table3";
+
+import type { Money } from "../finding.js";
 import type {
   AzureDetailedResourceReport,
   AzureResourceReport,
 } from "./types.js";
 
+// Fixed column widths — keeps the Reason column within a readable width
+// while allowing cli-table3 to word-wrap long content across multiple lines.
+const COL_WIDTHS = [30, 35, 25, 8, 55] as const;
+
 // ANSI color codes — only applied when stdout is a TTY to avoid cluttering redirected output
 const isTTY = process.stdout.isTTY ?? false;
 const RED = isTTY ? "\x1b[31m" : "";
 const YELLOW = isTTY ? "\x1b[33m" : "";
 const BLUE = isTTY ? "\x1b[34m" : "";
+const GREEN = isTTY ? "\x1b[32m" : "";
+const CYAN = isTTY ? "\x1b[36m" : "";
 const BOLD = isTTY ? "\x1b[1m" : "";
 const RESET = isTTY ? "\x1b[0m" : "";
 const DIM = isTTY ? "\x1b[2m" : "";
@@ -28,6 +37,12 @@ const RISK_COLOR = {
   medium: YELLOW,
 } as const;
 
+type Summary = {
+  counts: { high: number; low: number; medium: number };
+  savingsByCurrency: Map<string, number>;
+  sourceCounts: Record<string, number>;
+};
+
 /**
  * Generates a report from Azure resource analysis in the specified format.
  *
@@ -43,77 +58,233 @@ export async function generateReport(
     return;
   }
 
-  // For other formats, we extract the summary data.
-  const summaryReport: AzureResourceReport[] = report.map((r) => ({
-    costRisk: r.analysis.costRisk,
-    location: r.resource.location ?? "",
-    name: r.resource.name ?? "unknown",
-    reason: r.analysis.reason,
-    resourceGroup: r.resource.id?.split("/")[4],
-    subscriptionId: r.resource.id?.split("/")[2] ?? "unknown",
-    suspectedUnused: r.analysis.suspectedUnused,
-    type: r.resource.type ?? "unknown",
-  }));
-
   if (format === "json") {
+    const summaryReport: AzureResourceReport[] = report.map((r) => ({
+      costRisk: r.analysis.costRisk,
+      location: r.resource.location ?? "",
+      name: r.resource.name ?? "unknown",
+      reason: r.analysis.reason,
+      resourceGroup: r.resource.id?.split("/")[4],
+      subscriptionId: r.resource.id?.split("/")[2] ?? "unknown",
+      suspectedUnused: r.analysis.suspectedUnused,
+      type: r.resource.type ?? "unknown",
+    }));
     console.log(JSON.stringify(summaryReport, null, 2));
   } else if (format === "lint") {
     generateLintReport(report);
   } else {
-    console.table(
-      summaryReport.map((r) => ({
-        Name: r.name,
-        Reason: r.reason,
-        "Resource Group": r.resourceGroup || "N/A",
-        Risk: r.costRisk,
-        Type: r.type,
-      })),
-      ["Name", "Type", "Resource Group", "Risk", "Reason"],
-    );
+    const summaryReport: AzureResourceReport[] = report.map((r) => ({
+      costRisk: r.analysis.costRisk,
+      location: r.resource.location ?? "",
+      name: r.resource.name ?? "unknown",
+      reason: r.analysis.reason,
+      resourceGroup: r.resource.id?.split("/")[4],
+      subscriptionId: r.resource.id?.split("/")[2] ?? "unknown",
+      suspectedUnused: r.analysis.suspectedUnused,
+      type: r.resource.type ?? "unknown",
+    }));
+    const table = new Table({
+      colWidths: [...COL_WIDTHS],
+      head: ["Name", "Type", "Resource Group", "Risk", "Reason"],
+      wordWrap: true,
+    });
+    for (const r of summaryReport) {
+      table.push([
+        r.name,
+        r.type,
+        r.resourceGroup || "N/A",
+        r.costRisk,
+        r.reason,
+      ]);
+    }
+    console.log(table.toString());
+    // Same summary block the lint format prints, so the table view also
+    // surfaces totals, source breakdown and estimated savings at a glance.
+    printSummary(computeSummary(report));
+  }
+}
+
+/**
+ * Walks the report once to compute totals, source breakdown and savings
+ * per currency without mutating it. Used by the table format, which has
+ * no per-line walk of its own.
+ */
+function computeSummary(report: AzureDetailedResourceReport[]): Summary {
+  const summary: Summary = {
+    counts: { high: 0, low: 0, medium: 0 },
+    savingsByCurrency: new Map(),
+    sourceCounts: {},
+  };
+  for (const entry of report) {
+    const lines = entry.findings?.length
+      ? entry.findings.map((f) => ({
+          savings: f.estimatedMonthlySavings,
+          severity: f.severity,
+          source: f.source,
+        }))
+      : splitReasons(entry.analysis.reason).map(() => ({
+          savings: undefined,
+          severity: entry.analysis.costRisk,
+          source: "custom" as const,
+        }));
+    for (const line of lines) {
+      summary.counts[line.severity]++;
+      summary.sourceCounts[line.source] =
+        (summary.sourceCounts[line.source] ?? 0) + 1;
+      if (line.savings) {
+        summary.savingsByCurrency.set(
+          line.savings.currency,
+          (summary.savingsByCurrency.get(line.savings.currency) ?? 0) +
+            line.savings.amount,
+        );
+      }
+    }
+  }
+  return summary;
+}
+
+/**
+ * Formats a monetary amount with an ISO 4217 currency code, falling back
+ * to the raw code prefix when the runtime locale data lacks the currency
+ * symbol.
+ */
+function formatAmount(amount: number, currency: string): string {
+  try {
+    return new Intl.NumberFormat("en-US", {
+      currency,
+      maximumFractionDigits: 2,
+      minimumFractionDigits: 2,
+      style: "currency",
+    }).format(amount);
+  } catch {
+    return `${currency} ${amount.toFixed(2)}`;
   }
 }
 
+/**
+ * Renders an estimated monthly savings value as the short "(€ 12.50/mo)"
+ * label that ships next to each lint line. Returns an empty string when
+ * the analyzer didn't provide an estimate.
+ */
+function formatSavings(savings: Money | undefined): string {
+  if (!savings) return "";
+  return `(${formatAmount(savings.amount, savings.currency)}/mo)`;
+}
+
 /**
  * Renders a linter-style report to stdout, grouping findings by resource.
  *
+ * When `Finding[]` is attached to a report (Phase 1+), each finding is
+ * rendered with its `source` badge (e.g. `[advisor]`) and the estimated
+ * monthly savings, when known. For older payloads without `findings` we
+ * fall back to splitting `analysis.reason` like before so the format stays
+ * backward compatible.
+ *
  * Example output:
  *
  *   /subscriptions/.../virtualMachines/my-vm
- *     ✖ HIGH    VM is deallocated.
- *     ✖ HIGH    No tags found.
+ *     ✖ HIGH    [advisor] Right-size your VM. (€ 12.50/mo)
+ *     ✖ HIGH    [custom]  No tags found.
  *
  *   Summary: 3 issues found  (2 high, 0 medium, 1 low)
+ *   Estimated monthly savings: € 12.50
  */
 function generateLintReport(report: AzureDetailedResourceReport[]): void {
-  const counts = { high: 0, low: 0, medium: 0 };
+  const summary = {
+    counts: { high: 0, low: 0, medium: 0 },
+    savingsByCurrency: new Map<string, number>(),
+    sourceCounts: {} as Record<string, number>,
+  };
 
   for (const entry of report) {
     const resourceId =
       entry.resource.id ?? `unknown/${entry.resource.name ?? "unknown"}`;
-    const risk = entry.analysis.costRisk;
-    const findings = splitReasons(entry.analysis.reason);
-
     console.log(`${BOLD}${resourceId}${RESET}`);
 
-    for (const finding of findings) {
-      const icon = RISK_ICON[risk];
-      const color = RISK_COLOR[risk];
-      const label = `${color}${risk.toUpperCase().padEnd(6)}${RESET}`;
-      console.log(`  ${icon} ${label}  ${DIM}${finding}${RESET}`);
-      counts[risk]++;
+    const lines = entry.findings?.length
+      ? entry.findings.map((f) => ({
+          extra: formatSavings(f.estimatedMonthlySavings),
+          severity: f.severity,
+          source: f.source,
+          text: f.reason,
+        }))
+      : splitReasons(entry.analysis.reason).map((text) => ({
+          extra: "",
+          severity: entry.analysis.costRisk,
+          source: "custom" as const,
+          text,
+        }));
+
+    for (const line of lines) {
+      const icon = RISK_ICON[line.severity];
+      const color = RISK_COLOR[line.severity];
+      const label = `${color}${line.severity.toUpperCase().padEnd(6)}${RESET}`;
+      const sourceBadge = `${CYAN}[${line.source}]${RESET}`;
+      const extra = line.extra ? ` ${GREEN}${line.extra}${RESET}` : "";
+      console.log(
+        `  ${icon} ${label}  ${sourceBadge} ${DIM}${line.text}${RESET}${extra}`,
+      );
+      summary.counts[line.severity]++;
+      summary.sourceCounts[line.source] =
+        (summary.sourceCounts[line.source] ?? 0) + 1;
+    }
+
+    if (entry.findings) {
+      for (const f of entry.findings) {
+        if (f.estimatedMonthlySavings) {
+          const { amount, currency } = f.estimatedMonthlySavings;
+          summary.savingsByCurrency.set(
+            currency,
+            (summary.savingsByCurrency.get(currency) ?? 0) + amount,
+          );
+        }
+      }
     }
 
     console.log();
   }
 
+  printSummary(summary);
+}
+
+/**
+ * Prints the shared trailer (issues, sources, estimated savings) used by
+ * both the lint and the table format.
+ *
+ * Savings are kept grouped by currency intentionally: Azure Advisor
+ * returns each recommendation in the subscription's native billing
+ * currency, so the same report can carry EUR and USD figures at the
+ * same time when subscriptions are billed in different regions. We do
+ * NOT convert across currencies — the rates would be both volatile and
+ * out of scope for this tool.
+ */
+function printSummary(summary: Summary): void {
+  const { counts, savingsByCurrency, sourceCounts } = summary;
   const total = counts.high + counts.medium + counts.low;
   const summaryLine =
     `${BOLD}Summary:${RESET} ${total} issue${total !== 1 ? "s" : ""} found` +
     `  ${RED}(${counts.high} high${RESET}` +
     `, ${YELLOW}${counts.medium} medium${RESET}` +
     `, ${BLUE}${counts.low} low${RESET})`;
-
   console.log(summaryLine);
+
+  const sourceBreakdown = Object.entries(sourceCounts)
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([source, n]) => `${n} ${source}`)
+    .join(", ");
+  if (sourceBreakdown) {
+    console.log(`${BOLD}Sources:${RESET} ${sourceBreakdown}`);
+  }
+
+  if (savingsByCurrency.size > 0) {
+    const parts = [...savingsByCurrency.entries()].map(
+      ([currency, amount]) =>
+        `${GREEN}${formatAmount(amount, currency)}${RESET}`,
+    );
+    console.log(
+      `${BOLD}Estimated monthly savings:${RESET} ${parts.join(", ")}`,
+    );
+  }
 }
 
 /**

package/src/azure/resources/app-service.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 analyzeAppServicePlan(
   timespanDays: number,
   thresholds: Thresholds = DEFAULT_THRESHOLDS,
   verbose = false,
+  cache?: MetricsCache,
 ): Promise<AnalysisResult> {
   verboseLogResourceStart(
     verbose,
@@ -79,6 +81,7 @@ export async function analyzeAppServicePlan(
       "CpuPercentage",
       "Average",
       timespanDays,
+      cache,
     );
 
     const memoryPercentage = await getMetric(
@@ -87,6 +90,7 @@ export async function analyzeAppServicePlan(
       "MemoryPercentage",
       "Average",
       timespanDays,
+      cache,
     );
 
     if (