@pagopa/dx-savemoney 0.2.5 → 0.3.0

package/README.md

@@ -75,6 +75,7 @@ yarn add @pagopa/dx-savemoney
 
 - **Multi-Subscription Analysis**: Scans multiple Azure subscriptions in a single command.
 - **Intelligent Detection**: Uses Azure Monitor metrics (e.g. CPU, network traffic, transactions) to scientifically identify inactive resources.
+- **Azure Advisor Integration**: Fetches Cost recommendations directly from Azure Advisor, including Reserved Instance and Savings Plan opportunities with estimated monthly savings.
 - **Orphaned Resource Identification**: Detects commonly "forgotten" resources like unattached disks, unassociated public IPs, and unused network interfaces.
 - **Flexible Reporting**: Offers multiple output formats:
   - `table`: A human-readable summary for the terminal.
@@ -89,17 +90,18 @@ yarn add @pagopa/dx-savemoney
 
 The tool analyzes the following Azure resource types with specific detection methods and risk levels:
 
-| Resource Type           | Detection Method        | Cost Risk | What's Checked                                                                                                      |
-| :---------------------- | :---------------------- | :-------: | :------------------------------------------------------------------------------------------------------------------ |
-| **Virtual Machines**    | Instance View + Metrics |  🔴 High  | Deallocated/stopped state, Low CPU usage (<1%), Low network traffic (<3MB per days)                                 |
-| **App Service Plans**   | API Details + Metrics   |  🔴 High  | No apps deployed, Very low CPU (<5%), Very low memory (<10%), Oversized Premium tier                                |
-| **Container Apps**      | API Details + Metrics   | 🟡 Medium | Not running state, Zero replicas configured, Low CPU (<0.001 cores), Low memory (<10MB), Low network traffic (<1MB) |
-| **Managed Disks**       | API Details             | 🟡 Medium | Unattached state, No `managedBy` property                                                                           |
-| **Public IP Addresses** | API Details + Metrics   | 🟡 Medium | Not associated with any resource, Static IP not in use, Very low network traffic (<~340KB per day)                  |
-| **Network Interfaces**  | API Details             | 🟡 Medium | Not attached to VM or Private Endpoint, No public IP assigned                                                       |
-| **Private Endpoints**   | API Details             | 🟡 Medium | No private link connections, Rejected/disconnected connections, No network interfaces                               |
-| **Storage Accounts**    | Metrics                 | 🟡 Medium | Very low transaction count (<10 per days in timespan)                                                               |
-| **Static Web Apps**     | Metrics                 |  🟢 Low   | No traffic data available, Very low site hits (<100 requests in 30 days), Very low data transfer (<1MB in 30 days)  |
+| Resource Type           | Detection Method        | Cost Risk | What's Checked                                                                                                                                              |
+| :---------------------- | :---------------------- | :-------: | :---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Virtual Machines**    | Instance View + Metrics |  🔴 High  | Deallocated/stopped state, Low CPU usage (<1%), Low network traffic (<3MB per days)                                                                         |
+| **App Service Plans**   | API Details + Metrics   |  🔴 High  | No apps deployed, Very low CPU (<5%), Very low memory (<10%), Oversized Premium tier                                                                        |
+| **Container Apps**      | API Details + Metrics   | 🟡 Medium | Not running state, Zero replicas configured, Low CPU (<0.001 cores), Low memory (<10MB), Low network traffic (<1MB)                                         |
+| **Managed Disks**       | API Details             | 🟡 Medium | Unattached state, No `managedBy` property                                                                                                                   |
+| **Public IP Addresses** | API Details + Metrics   | 🟡 Medium | Not associated with any resource, Static IP not in use, Very low network traffic (<~340KB per day)                                                          |
+| **Network Interfaces**  | API Details             | 🟡 Medium | Not attached to VM or Private Endpoint, No public IP assigned                                                                                               |
+| **Private Endpoints**   | API Details             | 🟡 Medium | No private link connections, Rejected/disconnected connections, No network interfaces                                                                       |
+| **Storage Accounts**    | Metrics                 | 🟡 Medium | Very low transaction count (<10 per days in timespan)                                                                                                       |
+| **Static Web Apps**     | Metrics                 |  🟢 Low   | No traffic data available, Very low site hits (<100 requests in 30 days), Very low data transfer (<1MB in 30 days)                                          |
+| **Azure Advisor**       | Advisor API             | ⚪ Varies | Reserved Instance and Savings Plan opportunities, right-sizing suggestions, and other Cost recommendations — with estimated monthly savings where available |
 
 #### Generic Checks
 
@@ -128,8 +130,9 @@ import { azure, loadConfig } from "@pagopa/dx-savemoney";
 // Load configuration (from file, env vars, or interactive prompt)
 const config = await loadConfig("./config.yaml");
 
-// Run analysis and generate report
-await azure.analyzeAzureResources(config, "table");
+// Run analysis, then generate report
+const reports = await azure.analyzeAzureResources(config);
+await azure.generateReport(reports, "table");
 ```
 
 #### Configuration Inputs
@@ -141,6 +144,7 @@ The tool requires the following configuration:
 | `subscriptionIds`   | `string[]`               |    ✅    | -            | Array of Azure subscription IDs to analyze                                |
 | `preferredLocation` | `string`                 |    ❌    | `italynorth` | Preferred Azure region (resources elsewhere will be flagged)              |
 | `timespanDays`      | `number`                 |    ❌    | `30`         | Number of days to look back for metrics analysis                          |
+| `sources`           | `FindingSource[]`        |    ❌    | all sources  | Restrict analysis to specific sources: `"advisor"`, `"custom"`, or both   |
 | `verbose`           | `boolean`                |    ❌    | `false`      | Enable detailed logging for each resource analyzed                        |
 | `filterTags`        | `Record<string, string>` |    ❌    | -            | Only analyze resources matching **all** the specified tag key-value pairs |
 | `thresholds`        | `Thresholds`             |    ❌    | see below    | Override the default numeric thresholds used during analysis              |
@@ -250,16 +254,14 @@ import { azure, loadConfig } from "@pagopa/dx-savemoney";
 
 const config = await loadConfig("./config.yaml");
 // Analyze only resources tagged with environment=prod AND team=platform
-await azure.analyzeAzureResources(
-  {
-    ...config,
-    filterTags: new Map([
-      ["environment", "prod"],
-      ["team", "platform"],
-    ]),
-  },
-  "lint",
-);
+const reports = await azure.analyzeAzureResources({
+  ...config,
+  filterTags: new Map([
+    ["environment", "prod"],
+    ["team", "platform"],
+  ]),
+});
+await azure.generateReport(reports, "lint");
 ```
 
 ##### Basic Usage
@@ -269,7 +271,8 @@ import { azure, loadConfig } from "@pagopa/dx-savemoney";
 
 // Load from config file
 const config = await loadConfig("./config.yaml");
-await azure.analyzeAzureResources(config, "table");
+const reports = await azure.analyzeAzureResources(config);
+await azure.generateReport(reports, "table");
 ```
 
 ##### Custom Configuration
@@ -285,7 +288,8 @@ const config: AzureConfig = {
   verbose: true,
 };
 
-await azure.analyzeAzureResources(config, "json");
+const reports = await azure.analyzeAzureResources(config);
+await azure.generateReport(reports, "json");
 ```
 
 ##### Generate Detailed Report
@@ -295,7 +299,8 @@ import { azure, loadConfig } from "@pagopa/dx-savemoney";
 
 const config = await loadConfig();
 // Generate detailed JSON with full resource metadata
-await azure.analyzeAzureResources(config, "detailed-json");
+const reports = await azure.analyzeAzureResources(config);
+await azure.generateReport(reports, "detailed-json");
 ```
 
 ##### Using Environment Variables
@@ -307,7 +312,8 @@ import { loadConfig, azure } from "@pagopa/dx-savemoney";
 // ARM_SUBSCRIPTION_ID=sub1,sub2
 
 const config = await loadConfig(); // Will read from env vars
-await azure.analyzeAzureResources(config, "json");
+const reports = await azure.analyzeAzureResources(config);
+await azure.generateReport(reports, "json");
 ```
 
 ## AWS (Coming Soon)

package/dist/azure/analyzer.d.ts

@@ -1,34 +1,62 @@
 /**
  * Azure resource analyzer - Main orchestration logic
+ *
+ * Iterates every resource in every configured subscription, dispatches it
+ * to the registered analyzers (see `./analyzers/registry.ts`), and feeds
+ * the resulting findings into the report generator.
+ *
+ * Phase 0 refactor:
+ *  - Resources are dispatched through a plugin-style `Analyzer` registry
+ *    instead of a hard-coded `switch` statement.
+ *  - Per-subscription resources are analyzed in parallel via a small
+ *    in-process limiter (default concurrency 8, configurable via
+ *    `AzureConfig.concurrency`).
+ *  - Azure Monitor metric calls are memoized for the duration of a run via
+ *    a per-run `MetricsCache` passed through `AnalyzerContext`, so concurrent
+ *    calls to `analyzeAzureResources` stay fully isolated.
+ *
+ * The output schema (`AzureDetailedResourceReport`) is unchanged so the
+ * existing report formats keep working untouched.
  */
-import { ContainerAppsAPIClient } from "@azure/arm-appcontainers";
-import { WebSiteManagementClient } from "@azure/arm-appservice";
-import { ComputeManagementClient } from "@azure/arm-compute";
-import { MonitorClient } from "@azure/arm-monitor";
-import { NetworkManagementClient } from "@azure/arm-network";
 import * as armResources from "@azure/arm-resources";
-import type { AzureConfig } from "./types.js";
+import type { Finding } from "../finding.js";
+import type { AzureConfig, AzureDetailedResourceReport } from "./types.js";
 import { type AnalysisResult, type Thresholds } from "../types.js";
+import { type Analyzer, type AzureClients } from "./analyzers/index.js";
+import { type MetricsCache } from "./utils.js";
 /**
- * Analyzes resources in multiple Azure subscriptions and generates a report.
+ * Analyzes resources in every configured Azure subscription and returns
+ * the structured report.
+ *
+ * Phase 1 change: this function no longer emits a report to stdout. The
+ * orchestrator returns `AzureDetailedResourceReport[]` and the caller
+ * (the CLI today, future GUI / API consumers tomorrow) chooses how to
+ * render it via `generateReport`.
+ *
+ * Each entry carries both the legacy `analysis` summary and the unified
+ * `findings: Finding[]` so consumers can pick the level of detail they
+ * need. Azure Advisor recommendations and per-resource analyzer outputs
+ * are merged into the same entry when they refer to the same resource.
  *
- * @param config - Azure configuration with subscription IDs and settings
- * @param format - Output format (table, json, detailed-json, or lint)
+ * @param config - Azure configuration with subscription IDs and settings.
+ *                 `config.sources` controls which analyzers run.
  */
-export declare function analyzeAzureResources(config: AzureConfig, format: "detailed-json" | "json" | "lint" | "table"): Promise<void>;
+export declare function analyzeAzureResources(config: AzureConfig): Promise<AzureDetailedResourceReport[]>;
 /**
- * Analyzes a single Azure resource based on its type.
+ * Analyzes a single Azure resource by dispatching it to every registered
+ * analyzer that supports it. Generic checks (missing tags, location
+ * mismatch) are applied around the analyzer-specific logic.
  *
- * @param resource - The Azure resource to analyze
- * @param monitorClient - Azure Monitor client for metrics
- * @param computeClient - Azure Compute client
- * @param networkClient - Azure Network client
- * @param webSiteClient - Azure Web Site client
- * @param containerAppsClient - Azure Container Apps client
- * @param preferredLocation - Preferred Azure location
- * @param timespanDays - Number of days to analyze metrics
- * @param verbose - Whether verbose logging is enabled
+ * @param resource          The Azure resource to analyze
+ * @param analyzers         Registered analyzers (typically `createDefaultAnalyzers()`)
+ * @param clients           Bundle of Azure SDK clients shared across analyzers
+ * @param metricsCache      Run-scoped metrics cache to pass through to analyzers
+ * @param preferredLocation Preferred Azure region (resources elsewhere are flagged)
+ * @param timespanDays      Look-back window for Azure Monitor metrics
+ * @param thresholds        Numeric thresholds used during analysis
+ * @param verbose           Whether verbose logging is enabled
  * @returns Analysis result with cost risk and reason
  */
-export declare function analyzeResource(resource: armResources.GenericResource, monitorClient: MonitorClient, computeClient: ComputeManagementClient, networkClient: NetworkManagementClient, webSiteClient: WebSiteManagementClient, containerAppsClient: ContainerAppsAPIClient, preferredLocation: string, timespanDays: number, thresholds: Thresholds, verbose?: boolean): Promise<AnalysisResult>;
+export declare function analyzeResource(resource: armResources.GenericResource, analyzers: Analyzer[], clients: AzureClients, metricsCache: MetricsCache | undefined, preferredLocation: string, timespanDays: number, thresholds: Thresholds, verbose?: boolean): Promise<AnalysisResult>;
+export declare function shouldIncludeAdvisorFindingForTags(finding: Finding, taggedResourceIds: ReadonlySet<string>, tagFilterActive: boolean): boolean;
 //# sourceMappingURL=analyzer.d.ts.map

package/dist/azure/analyzer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"analyzer.d.ts","sourceRoot":"","sources":["../../src/azure/analyzer.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAC7D,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAC7D,OAAO,KAAK,YAAY,MAAM,sBAAsB,CAAC;AAIrD,OAAO,KAAK,EAAE,WAAW,EAA+B,MAAM,YAAY,CAAC;AAE3E,OAAO,EACL,KAAK,cAAc,EAGnB,KAAK,UAAU,EAChB,MAAM,aAAa,CAAC;AAerB;;;;;GAKG;AACH,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,eAAe,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,iBA2EpD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,YAAY,CAAC,eAAe,EACtC,aAAa,EAAE,aAAa,EAC5B,aAAa,EAAE,uBAAuB,EACtC,aAAa,EAAE,uBAAuB,EACtC,aAAa,EAAE,uBAAuB,EACtC,mBAAmB,EAAE,sBAAsB,EAC3C,iBAAiB,EAAE,MAAM,EACzB,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,UAAU,EACtB,OAAO,UAAQ,GACd,OAAO,CAAC,cAAc,CAAC,CAuHzB"}
+{"version":3,"file":"analyzer.d.ts","sourceRoot":"","sources":["../../src/azure/analyzer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AASH,OAAO,KAAK,YAAY,MAAM,sBAAsB,CAAC;AAKrD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,KAAK,EACV,WAAW,EACX,2BAA2B,EAE5B,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,KAAK,cAAc,EAInB,KAAK,UAAU,EAChB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,KAAK,QAAQ,EAEb,KAAK,YAAY,EAIlB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAe,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AAO5D;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,2BAA2B,EAAE,CAAC,CA4GxC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,YAAY,CAAC,eAAe,EACtC,SAAS,EAAE,QAAQ,EAAE,EACrB,OAAO,EAAE,YAAY,EACrB,YAAY,EAAE,YAAY,YAAY,EACtC,iBAAiB,EAAE,MAAM,EACzB,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,UAAU,EACtB,OAAO,UAAQ,GACd,OAAO,CAAC,cAAc,CAAC,CA8CzB;AAED,wBAAgB,kCAAkC,CAChD,OAAO,EAAE,OAAO,EAChB,iBAAiB,EAAE,WAAW,CAAC,MAAM,CAAC,EACtC,eAAe,EAAE,OAAO,GACvB,OAAO,CAYT"}