@pagopa/dx-cli 0.22.3 → 0.23.0

package/README.md

@@ -185,6 +185,7 @@ dx savemoney [options]
 | `--days`     | `-d`  | Metric analysis period in days (overrides config file).                                                                                      | `30`         |
 | `--location` | `-l`  | Preferred Azure location for resources (overrides config file).                                                                              | `italynorth` |
 | `--tags`     | `-t`  | Filter resources by tags (`key=value key2=value2`). Only resources matching **all** specified tags are analyzed (variadic: space-separated). | N/A          |
+| `--source`   | `-s`  | Restrict findings to a specific source: `advisor`, `custom`, or `all`.                                                                       | `all`        |
 
 > `--verbose` / `-v` is inherited from the root command. See [Global Options](#global-options).
 
@@ -240,6 +241,7 @@ azure:
 - **Private Endpoints**: Unused or misconfigured endpoints
 - **Container Apps**: Not running, zero replicas, low resource usage
 - **Static Web Apps**: No traffic or very low usage patterns
+- **Azure Advisor recommendations**: Reserved Instance and Savings Plan opportunities, right-sizing suggestions, and other cost recommendations surfaced directly from Azure Advisor — with estimated monthly savings where available
 
 > [!NOTE]
 > Currently only Azure is supported. Support for additional cloud providers (AWS) is planned for future releases.
@@ -259,6 +261,22 @@ These options are available on every subcommand:
 dx --verbose init project
 ```
 
+## 🧪 Development
+
+Run the CLI test suite from the repository root with:
+
+```bash
+pnpm nx test @pagopa/dx-cli
+```
+
+Some integration tests assert generated file contents with Vitest snapshots. When a generator change intentionally updates those files, refresh the snapshots with:
+
+```bash
+pnpm nx test @pagopa/dx-cli -- --update
+```
+
+Review the updated `__snapshots__` files before committing them.
+
 ---
 
 <div align="center">

package/dist/adapters/commander/__tests__/spec.test.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Tests for the Commander spec adapter.
+ *
+ * Verifies that `extractCliSpec` correctly maps Commander's internal command
+ * tree to the `CliSpec` domain type, covering options, arguments, and nested
+ * subcommands.
+ */
+export {};

package/dist/adapters/commander/__tests__/spec.test.js

@@ -0,0 +1,264 @@
+/**
+ * Tests for the Commander spec adapter.
+ *
+ * Verifies that `extractCliSpec` correctly maps Commander's internal command
+ * tree to the `CliSpec` domain type, covering options, arguments, and nested
+ * subcommands.
+ */
+import { Argument, Command, Option } from "commander";
+import { describe, expect, it } from "vitest";
+import { extractCliSpec } from "../spec.js";
+const buildRoot = () => new Command("dx")
+    .description("The CLI for DX-Platform")
+    .version("1.2.3")
+    .addOption(new Option("-v, --verbose", "Enable verbose output").default(false))
+    .addOption(new Option("--output <mode>", "Output mode")
+    .choices(["text", "json"])
+    .default("text"));
+const registerRootMetadataAndGlobalOptionTests = () => {
+    describe("root metadata and global options", () => {
+        it("maps the root command name, description and version", () => {
+            const root = buildRoot();
+            const spec = extractCliSpec(root, "1.2.3");
+            expect(spec).toMatchObject({
+                description: "The CLI for DX-Platform",
+                name: "dx",
+                specVersion: "1",
+                version: "1.2.3",
+            });
+        });
+        it("maps global options from the root command", () => {
+            const root = buildRoot();
+            const spec = extractCliSpec(root, "1.2.3");
+            expect(spec.globalOptions.find((o) => o.long === "--verbose")).toStrictEqual({
+                choices: [],
+                defaultValue: false,
+                description: "Enable verbose output",
+                flags: "-v, --verbose",
+                long: "--verbose",
+                optional: false,
+                required: false,
+                short: "-v",
+            });
+            expect(spec.globalOptions.find((o) => o.long === "--output")).toStrictEqual({
+                choices: ["text", "json"],
+                defaultValue: "text",
+                description: "Output mode",
+                flags: "--output <mode>",
+                long: "--output",
+                optional: false,
+                required: true,
+                short: undefined,
+            });
+        });
+        it("excludes help and version options from globalOptions", () => {
+            const root = buildRoot();
+            const spec = extractCliSpec(root, "1.2.3");
+            const flags = spec.globalOptions.map((o) => o.long);
+            expect(flags).not.toContain("--help");
+            expect(flags).not.toContain("--version");
+        });
+    });
+};
+const registerCommandListTests = () => {
+    describe("command lists", () => {
+        it("maps a flat subcommand with options and no arguments", () => {
+            const root = buildRoot();
+            root.addCommand(new Command("doctor")
+                .description("Run health checks")
+                .addOption(new Option("--fix", "Auto-fix issues").default(false)));
+            const spec = extractCliSpec(root, "1.2.3");
+            expect(spec.commands).toStrictEqual([
+                {
+                    arguments: [],
+                    commands: [],
+                    description: "Run health checks",
+                    name: "doctor",
+                    options: [
+                        {
+                            choices: [],
+                            defaultValue: false,
+                            description: "Auto-fix issues",
+                            flags: "--fix",
+                            long: "--fix",
+                            optional: false,
+                            required: false,
+                            short: undefined,
+                        },
+                    ],
+                },
+            ]);
+        });
+        it("maps a subcommand argument (required)", () => {
+            const root = buildRoot();
+            root.addCommand(new Command("apply")
+                .description("Apply something")
+                .addArgument(new Argument("<id>", "The id of the item to apply")));
+            const spec = extractCliSpec(root, "1.2.3");
+            expect(spec.commands).toStrictEqual([
+                {
+                    arguments: [
+                        {
+                            choices: [],
+                            defaultValue: undefined,
+                            description: "The id of the item to apply",
+                            name: "id",
+                            required: true,
+                            variadic: false,
+                        },
+                    ],
+                    commands: [],
+                    description: "Apply something",
+                    name: "apply",
+                    options: [],
+                },
+            ]);
+        });
+        it("maps a variadic optional argument", () => {
+            const root = buildRoot();
+            root.addCommand(new Command("run")
+                .description("Run scripts")
+                .addArgument(new Argument("[scripts...]", "Scripts to run")));
+            const spec = extractCliSpec(root, "1.2.3");
+            expect(spec.commands).toStrictEqual([
+                {
+                    arguments: [
+                        {
+                            choices: [],
+                            defaultValue: undefined,
+                            description: "Scripts to run",
+                            name: "scripts",
+                            required: false,
+                            variadic: true,
+                        },
+                    ],
+                    commands: [],
+                    description: "Run scripts",
+                    name: "run",
+                    options: [],
+                },
+            ]);
+        });
+        it("includes commands registered with { hidden: true }", () => {
+            const root = buildRoot();
+            const visible = new Command("visible").description("Visible");
+            const hidden = new Command("internal").description("Internal");
+            root.addCommand(visible);
+            root.addCommand(hidden, { hidden: true });
+            const spec = extractCliSpec(root, "1.2.3");
+            expect(spec.commands).toStrictEqual([
+                {
+                    arguments: [],
+                    commands: [],
+                    description: "Visible",
+                    name: "visible",
+                    options: [],
+                },
+                {
+                    arguments: [],
+                    commands: [],
+                    description: "Internal",
+                    name: "internal",
+                    options: [],
+                },
+            ]);
+        });
+        it("excludes the spec command from the extracted command list", () => {
+            const root = buildRoot();
+            root.addCommand(new Command("doctor").description("Run health checks"));
+            root.addCommand(new Command("spec").description("Print the CLI spec"));
+            const spec = extractCliSpec(root, "1.2.3");
+            expect(spec.commands).toStrictEqual([
+                {
+                    arguments: [],
+                    commands: [],
+                    description: "Run health checks",
+                    name: "doctor",
+                    options: [],
+                },
+            ]);
+        });
+        it("returns empty commands array when root has no subcommands", () => {
+            const root = buildRoot();
+            const spec = extractCliSpec(root, "1.2.3");
+            expect(spec.commands).toEqual([]);
+        });
+        it("maps an argument with choices", () => {
+            const root = buildRoot();
+            root.addCommand(new Command("format")
+                .description("Format output")
+                .addArgument(new Argument("<style>", "Output style").choices(["json", "table"])));
+            const spec = extractCliSpec(root, "1.2.3");
+            expect(spec.commands).toStrictEqual([
+                {
+                    arguments: [
+                        {
+                            choices: ["json", "table"],
+                            defaultValue: undefined,
+                            description: "Output style",
+                            name: "style",
+                            required: true,
+                            variadic: false,
+                        },
+                    ],
+                    commands: [],
+                    description: "Format output",
+                    name: "format",
+                    options: [],
+                },
+            ]);
+        });
+    });
+};
+const registerNestedCommandTests = () => {
+    describe("nested commands", () => {
+        it("recursively maps nested subcommands", () => {
+            const root = buildRoot();
+            const codemod = new Command("codemod").description("Manage codemods");
+            codemod.addCommand(new Command("list").description("List available codemods"));
+            codemod.addCommand(new Command("apply")
+                .description("Apply a codemod")
+                .addArgument(new Argument("<id>", "Codemod id")));
+            root.addCommand(codemod);
+            const spec = extractCliSpec(root, "1.2.3");
+            expect(spec.commands).toStrictEqual([
+                {
+                    arguments: [],
+                    commands: [
+                        {
+                            arguments: [],
+                            commands: [],
+                            description: "List available codemods",
+                            name: "list",
+                            options: [],
+                        },
+                        {
+                            arguments: [
+                                {
+                                    choices: [],
+                                    defaultValue: undefined,
+                                    description: "Codemod id",
+                                    name: "id",
+                                    required: true,
+                                    variadic: false,
+                                },
+                            ],
+                            commands: [],
+                            description: "Apply a codemod",
+                            name: "apply",
+                            options: [],
+                        },
+                    ],
+                    description: "Manage codemods",
+                    name: "codemod",
+                    options: [],
+                },
+            ]);
+        });
+    });
+};
+describe("extractCliSpec", () => {
+    registerRootMetadataAndGlobalOptionTests();
+    registerCommandListTests();
+    registerNestedCommandTests();
+});

package/dist/adapters/commander/commands/__tests__/init-command.test.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Tests for the init Commander command workflow.
+ */
+export {};

package/dist/adapters/commander/commands/__tests__/init-command.test.js

@@ -0,0 +1,44 @@
+/**
+ * Tests for the init Commander command workflow.
+ */
+import { Command } from "commander";
+import { okAsync } from "neverthrow";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { mock } from "vitest-mock-extended";
+const { tfMock } = vi.hoisted(() => ({
+    tfMock: vi.fn(),
+}));
+vi.mock("ora", () => ({
+    oraPromise: (promise) => promise,
+}));
+vi.mock("../../../execa/terraform.js", () => ({
+    tf$: tfMock,
+}));
+import { makeInitCommand } from "../init.js";
+const makeRoot = (command) => new Command()
+    .exitOverride()
+    .addCommand(command)
+    .configureOutput({
+    writeErr: () => {
+        /* silence stderr in tests */
+    },
+    writeOut: () => {
+        /* silence stdout in tests */
+    },
+});
+describe("makeInitCommand", () => {
+    afterEach(() => {
+        tfMock.mockReset();
+    });
+    it("checks local preconditions before requiring GitHub auth", async () => {
+        tfMock.mockRejectedValueOnce(new Error("Terraform not installed"));
+        const requireGitHubAuthSpy = vi.fn(() => okAsync({
+            authorizationService: mock(),
+            gitHubService: mock(),
+        }));
+        const requireGitHubAuth = requireGitHubAuthSpy;
+        const root = makeRoot(makeInitCommand(requireGitHubAuth));
+        await expect(root.parseAsync(["init"], { from: "user" })).rejects.toBeTruthy();
+        expect(requireGitHubAuthSpy).not.toHaveBeenCalled();
+    });
+});

package/dist/adapters/commander/commands/__tests__/savemoney.test.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Unit tests for the pure helper functions in the savemoney command.
+ *
+ * The full command action (Azure API calls, spinner) is not exercised here
+ * because it requires live credentials. These tests cover the stateless
+ * parsing helpers that can be validated without any I/O.
+ */
+export {};

package/dist/adapters/commander/commands/__tests__/savemoney.test.js

@@ -0,0 +1,60 @@
+/**
+ * Unit tests for the pure helper functions in the savemoney command.
+ *
+ * The full command action (Azure API calls, spinner) is not exercised here
+ * because it requires live credentials. These tests cover the stateless
+ * parsing helpers that can be validated without any I/O.
+ */
+import { InvalidArgumentError } from "commander";
+import { describe, expect, it } from "vitest";
+import { makeSavemoneyCommand, parseSourceOption, parseTagsOption, } from "../savemoney.js";
+describe("parseSourceOption", () => {
+    it("accepts 'advisor'", () => {
+        expect(parseSourceOption("advisor")).toBe("advisor");
+    });
+    it("accepts 'custom'", () => {
+        expect(parseSourceOption("custom")).toBe("custom");
+    });
+    it("accepts 'all'", () => {
+        expect(parseSourceOption("all")).toBe("all");
+    });
+    it("throws InvalidArgumentError for an unknown value", () => {
+        expect(() => parseSourceOption("aws")).toThrow(InvalidArgumentError);
+    });
+    it("throws InvalidArgumentError for an empty string", () => {
+        expect(() => parseSourceOption("")).toThrow(InvalidArgumentError);
+    });
+});
+describe("parseTagsOption", () => {
+    it("returns an empty Map when tagsOption is undefined", () => {
+        expect(parseTagsOption(undefined)).toEqual(new Map());
+    });
+    it("returns an empty Map when tagsOption is an empty array", () => {
+        expect(parseTagsOption([])).toEqual(new Map());
+    });
+    it("parses a single key=value pair", () => {
+        expect(parseTagsOption(["env=dev"])).toEqual(new Map([["env", "dev"]]));
+    });
+    it("parses multiple key=value pairs", () => {
+        expect(parseTagsOption(["env=dev", "team=platform"])).toEqual(new Map([
+            ["env", "dev"],
+            ["team", "platform"],
+        ]));
+    });
+    it("handles values that contain '='", () => {
+        expect(parseTagsOption(["url=https://example.com/path=1"])).toEqual(new Map([["url", "https://example.com/path=1"]]));
+    });
+    it("ignores entries without a '=' separator", () => {
+        expect(parseTagsOption(["noequalssign"])).toEqual(new Map());
+    });
+    it("trims whitespace from keys and values", () => {
+        expect(parseTagsOption([" env = dev "])).toEqual(new Map([["env", "dev"]]));
+    });
+});
+describe("makeSavemoneyCommand", () => {
+    it("documents that --tags does not filter subscription-level Advisor findings", () => {
+        const command = makeSavemoneyCommand();
+        const tagsOption = command.options.find((option) => option.flags.includes("--tags"));
+        expect(tagsOption?.description).toContain("Advisor subscription-level findings remain global.");
+    });
+});

package/dist/adapters/commander/commands/__tests__/spec.test.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Tests for the `spec` Commander command.
+ *
+ * Verifies that `makeSpecCommand` calls the `getSpec` callback and writes the
+ * resulting CliSpec as pretty-printed JSON to stdout.
+ */
+export {};

package/dist/adapters/commander/commands/__tests__/spec.test.js

@@ -0,0 +1,85 @@
+/**
+ * Tests for the `spec` Commander command.
+ *
+ * Verifies that `makeSpecCommand` calls the `getSpec` callback and writes the
+ * resulting CliSpec as pretty-printed JSON to stdout.
+ */
+import { Command } from "commander";
+import { afterEach, beforeEach, describe, expect, it, vi, } from "vitest";
+import { makeSpecCommand } from "../spec.js";
+const makeMinimalSpec = () => ({
+    commands: [],
+    description: "The CLI for DX-Platform",
+    globalOptions: [],
+    name: "dx",
+    specVersion: "1",
+    version: "0.0.0",
+});
+describe("makeSpecCommand", () => {
+    let stdoutSpy;
+    beforeEach(() => {
+        stdoutSpy = vi
+            .spyOn(process.stdout, "write")
+            .mockImplementation(() => true);
+    });
+    afterEach(() => {
+        stdoutSpy.mockRestore();
+    });
+    it("is registered as the 'spec' subcommand", () => {
+        const cmd = makeSpecCommand(() => makeMinimalSpec());
+        expect(cmd.name()).toBe("spec");
+    });
+    it("calls getSpec and writes JSON to stdout when invoked", async () => {
+        const spec = makeMinimalSpec();
+        const getSpec = vi.fn().mockReturnValue(spec);
+        const cmd = makeSpecCommand(getSpec);
+        // Parse with an isolated parent so Commander doesn't exit
+        const root = new Command().exitOverride().addCommand(cmd);
+        root.configureOutput({
+            writeErr: () => {
+                /* silence */
+            },
+            writeOut: () => {
+                /* silence */
+            },
+        });
+        await root.parseAsync(["spec"], { from: "user" });
+        expect(getSpec).toHaveBeenCalledOnce();
+        const written = stdoutSpy.mock.calls.map((c) => c[0]).join("");
+        expect(JSON.parse(written)).toEqual(spec);
+    });
+    it("outputs valid pretty-printed JSON (indented)", async () => {
+        const spec = makeMinimalSpec();
+        const cmd = makeSpecCommand(() => spec);
+        const root = new Command().exitOverride().addCommand(cmd);
+        root.configureOutput({
+            writeErr: () => {
+                /* silence */
+            },
+            writeOut: () => {
+                /* silence */
+            },
+        });
+        await root.parseAsync(["spec"], { from: "user" });
+        const written = stdoutSpy.mock.calls.map((c) => c[0]).join("");
+        // Pretty-printed JSON has newlines
+        expect(written).toContain("\n");
+        expect(written).toContain("  ");
+    });
+    it("includes specVersion '1' in the output", async () => {
+        const cmd = makeSpecCommand(() => makeMinimalSpec());
+        const root = new Command().exitOverride().addCommand(cmd);
+        root.configureOutput({
+            writeErr: () => {
+                /* silence */
+            },
+            writeOut: () => {
+                /* silence */
+            },
+        });
+        await root.parseAsync(["spec"], { from: "user" });
+        const written = stdoutSpy.mock.calls.map((c) => c[0]).join("");
+        const parsed = JSON.parse(written);
+        expect(parsed.specVersion).toBe("1");
+    });
+});

package/dist/adapters/commander/commands/add.d.ts

@@ -11,13 +11,9 @@ import { Command } from "commander";
 import { ResultAsync } from "neverthrow";
 import type { Payload as EnvironmentPayload } from "../../plop/generators/environment/index.js";
 import { AuthorizationResult, AuthorizationService } from "../../../domain/authorization.js";
-import { type GitHubService } from "../../../domain/github.js";
+import { GitHubAuthFactory } from "../../../domain/dependencies.js";
 /**
  * Authorize a Cloud Account (Azure Subscription, AWS Account, ...), creating a Pull Request for each account that requires authorization.
  */
 export declare const authorizeCloudAccounts: (authorizationService: AuthorizationService) => (envPayload: EnvironmentPayload) => ResultAsync<AuthorizationResult[], never>;
-export type AddCommandDependencies = {
-    authorizationService: AuthorizationService;
-    gitHubService: GitHubService;
-};
-export declare const makeAddCommand: (deps: AddCommandDependencies) => Command;
+export declare const makeAddCommand: (requireGitHubAuth: GitHubAuthFactory) => Command;

package/dist/adapters/commander/commands/add.js

@@ -81,17 +81,13 @@ const addEnvironmentAction = (authorizationService, gitHubService) => checkAddEn
     .andThen((payload) => authorizeCloudAccounts(authorizationService)(payload).map((authorizationPrs) => ({
     authorizationPrs,
 })));
-export const makeAddCommand = (deps) => new Command()
+export const makeAddCommand = (requireGitHubAuth) => new Command()
     .name("add")
     .description("Add a new component to your workspace")
     .addCommand(new Command("environment")
     .description("Add a new deployment environment")
     .action(async function () {
-    const result = await addEnvironmentAction(deps.authorizationService, deps.gitHubService);
-    if (result.isErr()) {
-        exitWithError(this)(result.error);
-    }
-    else {
-        displaySummary(result.value);
-    }
+    await requireGitHubAuth()
+        .andThen(({ authorizationService, gitHubService }) => addEnvironmentAction(authorizationService, gitHubService))
+        .match(displaySummary, exitWithError(this));
 }));

package/dist/adapters/commander/commands/init.d.ts

@@ -1,6 +1,6 @@
 import { Command } from "commander";
 import { ResultAsync } from "neverthrow";
-import { GitHubService } from "../../../domain/github.js";
+import { GitHubAuthFactory } from "../../../domain/dependencies.js";
 import { Payload as MonorepoPayload } from "../../plop/generators/monorepo/index.js";
 export declare const checkInitPreconditions: () => ResultAsync<import("execa").Result<{
     environment: {
@@ -19,8 +19,4 @@ export declare const checkAddEnvironmentPreconditions: () => ResultAsync<import(
     shell: true;
 }>, Error>;
 export declare const confirmGitHubRepoCreation: (payload: MonorepoPayload) => ResultAsync<boolean, Error>;
-type InitCommandDependencies = {
-    gitHubService: GitHubService;
-};
-export declare const makeInitCommand: ({ gitHubService, }: InitCommandDependencies) => Command;
-export {};
+export declare const makeInitCommand: (requireGitHubAuth: GitHubAuthFactory) => Command;

package/dist/adapters/commander/commands/init.js

@@ -142,18 +142,19 @@ export const confirmGitHubRepoCreation = (payload) => ResultAsync.fromPromise(in
     type: "confirm",
 })
     .then(({ confirm }) => confirm), (cause) => new Error("Failed to read GitHub publish confirmation", { cause }));
-export const makeInitCommand = ({ gitHubService, }) => new Command()
+export const makeInitCommand = (requireGitHubAuth) => new Command()
     .name("init")
     .description("Initialize a new DX workspace")
     .action(async function () {
     await checkInitPreconditions()
-        .andThen(() => ResultAsync.fromPromise(getPlopInstance(), (cause) => new Error("Failed to initialize plop", { cause })))
-        .andThen((plop) => ResultAsync.fromPromise(runMonorepoGenerator(plop, gitHubService), handleGeneratorError))
+        .andThen(() => requireGitHubAuth())
+        .andThen((auth) => ResultAsync.fromPromise(getPlopInstance(), (cause) => new Error("Failed to initialize plop", { cause }))
+        .andThen((plop) => ResultAsync.fromPromise(runMonorepoGenerator(plop, auth.gitHubService), handleGeneratorError))
         .andTee((payload) => {
         process.chdir(payload.repoName);
     })
         .andThen((payload) => confirmGitHubRepoCreation(payload).andThen((confirmed) => confirmed
-        ? handleNewGitHubRepository(gitHubService)(payload)
-        : okAsync({ gitHubRepoCreationSkipped: true, payload })))
+        ? handleNewGitHubRepository(auth.gitHubService)(payload)
+        : okAsync({ gitHubRepoCreationSkipped: true, payload }))))
         .match(displaySummary, exitWithError(this));
 });

package/dist/adapters/commander/commands/savemoney.d.ts

@@ -1,2 +1,13 @@
 import { Command } from "commander";
 export declare const makeSavemoneyCommand: () => Command;
+/**
+ * Parses the `--source` option via a zod enum, accepting `all`, `advisor`,
+ * or `custom` and rejecting any other value with a Commander-friendly error.
+ */
+export declare function parseSourceOption(value: string): string;
+/**
+ * Parses an array of "key=value" strings (from commander variadic option) into a Map<string, string>.
+ * Returns an empty Map when the option is not provided or empty.
+ * Supports values that contain "=" (only the first "=" is treated as separator).
+ */
+export declare function parseTagsOption(tagsOption: string[] | undefined): Map<string, string>;