@pagopa/dx-savemoney 0.2.6 → 0.3.1

package/src/azure/analyzers/registry.ts

@@ -10,6 +10,7 @@
  * Adding a new analyzer is a single insertion here.
  */
 
+import type { SubscriptionAnalyzer } from "./subscription.js";
 import type { Analyzer } from "./types.js";
 
 import {
@@ -23,6 +24,7 @@ import {
   analyzeStorageAccount,
   analyzeVM,
 } from "../resources/index.js";
+import { createAdvisorAnalyzer } from "./advisor.js";
 
 /**
  * Builds the default set of analyzers in the same order they were
@@ -182,3 +184,13 @@ export function createDefaultAnalyzers(): Analyzer[] {
     },
   ];
 }
+
+/**
+ * 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/config.ts

@@ -44,6 +44,7 @@ export async function loadAzureConfig(
       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/types.ts

@@ -4,6 +4,7 @@
 
 import type * as armResources from "@azure/arm-resources";
 
+import type { Finding } from "../finding.js";
 import type {
   AnalysisResult,
   BaseConfig,
@@ -26,6 +27,14 @@ export type AzureConfig = BaseConfig & {
    * If omitted, all resources are analyzed.
    */
   filterTags?: Map<string, string>;
+  /**
+   * Which finding sources to include in the run.
+   * - `"custom"`  → enables the per-resource analyzer plugins
+   * - `"advisor"` → enables the Azure Advisor subscription-level analyzer
+   *
+   * Defaults to `["advisor", "custom"]` when omitted (i.e. all sources).
+   */
+  sources?: AzureSource[];
   subscriptionIds: string[];
   /**
    * Analysis thresholds. Defaults from DEFAULT_THRESHOLDS are used when not provided.
@@ -35,10 +44,22 @@ export type AzureConfig = BaseConfig & {
 };
 
 /**
- * Detailed report for a single Azure resource with full resource object
+ * Detailed report for a single Azure resource with full resource object.
+ *
+ * Phase 1 introduces the optional `findings` field carrying the unified
+ * `Finding[]` model alongside the legacy `analysis` summary. The two are
+ * kept in sync by the orchestrator so existing report formats keep
+ * working untouched while new consumers (GUI, JSON exports, Phase 2
+ * pricing aggregation) can read structured findings directly.
  */
 export type AzureDetailedResourceReport = {
   analysis: AnalysisResult;
+  /**
+   * Structured findings attached to the resource. Always populated by the
+   * orchestrator (possibly empty). Optional only for backward compatibility
+   * with serialised payloads produced before Phase 1.
+   */
+  findings?: Finding[];
   resource: armResources.GenericResource;
 };
 
@@ -55,3 +76,10 @@ export type AzureResourceReport = {
   suspectedUnused: boolean;
   type: string;
 };
+
+/**
+ * Finding sources that are valid for Azure analysis.
+ * Narrowed from `FindingSource` to exclude "aws", which is not a valid
+ * filter for Azure runs and would silently produce an empty report.
+ */
+export type AzureSource = "advisor" | "custom";

package/src/index.ts

@@ -21,7 +21,7 @@ export {
 } from "./azure/analyzers/index.js";
 
 // Export common types
-export type { AzureConfig } from "./azure/types.js";
+export type { AzureConfig, AzureSource } from "./azure/types.js";
 
 // Export Azure module
 import * as azureModule from "./azure/index.js";

package/src/schema.ts

@@ -111,6 +111,15 @@ const AzureSectionSchema = z
      */
     concurrency: z.number().int().positive().optional(),
     preferredLocation: z.string().default("italynorth"),
+    /**
+     * Which finding sources to include. Defaults to all known sources.
+     * Authors can narrow the run to e.g. `["advisor"]` to fetch only
+     * Azure Advisor recommendations, or `["custom"]` to skip Advisor.
+     */
+    sources: z
+      .array(z.enum(["advisor", "custom"]))
+      .nonempty()
+      .default(["advisor", "custom"]),
     subscriptionIds: z
       .array(z.string())
       .min(