@pagopa/dx-cli 0.4.1

package/README.md

@@ -0,0 +1,85 @@
+# @pagopa/dx-cli
+
+<div align="center">
+
+<img src="../../assets/pagopa-logo.png" width="100" alt="PagoPA logo">
+
+# DX CLI
+
+<p align="center">
+  <i align="center">A CLI tool for managing DevEx (Developer Experience) guidelines and best practices 🚀</i>
+</p>
+
+</div>
+
+## 📖 Overview
+
+The DX CLI is a command-line tool designed to help developers manage and validate their development setup according to PagoPA's DevEx guidelines. It provides automated checks and validations to ensure repositories follow the established best practices and conventions.
+
+## ✨ Features
+
+- **Repository Validation**: Verify repository setup against DevEx guidelines
+- **Monorepo Script Checking**: Validate that required scripts are present in package.json
+- **Developer Experience Optimization**: Ensure consistent development practices across projects
+
+## 🚀 Installation
+
+> [!NOTE]
+> The CLI is currently only available locally and is not yet distributed through package managers.
+
+### From Source (Development)
+
+```bash
+# Clone the repository
+git clone https://github.com/pagopa/dx.git
+cd dx
+
+# Install dependencies
+yarn install
+
+# Build the CLI
+yarn build
+
+# Run the CLI
+node ./apps/cli/bin/index.js --help
+```
+
+## 🛠️ Usage
+
+### Available Commands
+
+#### `doctor`
+
+Verify the repository setup according to the DevEx guidelines.
+
+```bash
+dx doctor
+```
+
+This command will:
+
+- Check if you're in a valid Git repository
+- Validate that required monorepo scripts are present in package.json
+- Check that the `turbo.json` file exists
+- Verify that the installed `turbo` version meets the minimum requirements
+
+**Example output:**
+
+```bash
+$ dx doctor
+Checking monorepo scripts...
+✅ Monorepo scripts are correctly set up
+```
+
+### Global Options
+
+- `--version, -V`: Display version number
+- `--help, -h`: Display help information
+
+---
+
+<div align="center">
+
+Made with ❤️ by the PagoPA DevEx Team
+
+</div>

package/bin/index.js

@@ -0,0 +1,445 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import "core-js/actual/set/index.js";
+import { configure, getConsoleSink, getLogger as getLogger4 } from "@logtape/logtape";
+
+// src/adapters/commander/index.ts
+import { Command as Command4 } from "commander";
+
+// src/adapters/commander/commands/doctor.ts
+import { Command } from "commander";
+import * as process2 from "process";
+
+// src/domain/doctor.ts
+import { ResultAsync as ResultAsync3 } from "neverthrow";
+
+// src/domain/package-json.ts
+import { err, ok } from "neverthrow";
+import { z } from "zod/v4";
+var ScriptName = z.string().brand();
+var scriptSchema = z.object({
+  name: ScriptName,
+  script: z.string()
+});
+var DependencyName = z.string().brand();
+var dependencySchema = z.object({
+  name: DependencyName,
+  version: z.string()
+});
+var PackageName = z.string().min(1).brand();
+var scriptsSchema = z.record(ScriptName, z.string()).optional().transform(
+  (obj) => new Map(
+    obj ? Object.entries(obj).map(([name, script]) => [
+      ScriptName.parse(name),
+      script
+    ]) : []
+  )
+);
+var dependenciesSchema = z.record(DependencyName, z.string()).optional().transform(
+  (obj) => new Map(
+    obj ? Object.entries(obj).map(([name, version]) => [
+      DependencyName.parse(name),
+      version
+    ]) : []
+  )
+);
+var packageManagerSchema = z.enum(["npm", "pnpm", "yarn"]);
+var packageJsonSchema = z.object({
+  dependencies: dependenciesSchema,
+  devDependencies: dependenciesSchema,
+  name: PackageName,
+  packageManager: z.string().transform((str) => str.split("@")[0]).pipe(packageManagerSchema).optional(),
+  scripts: scriptsSchema
+});
+var findMissingScripts = (availableScripts, requiredScripts) => {
+  const availableScriptNames = new Set(availableScripts.keys());
+  const requiredScriptNames = new Set(requiredScripts.keys());
+  return requiredScriptNames.difference(availableScriptNames);
+};
+var checkMonorepoScripts = async (dependencies, config2) => {
+  const { packageJsonReader: packageJsonReader2 } = dependencies;
+  const checkName = "Monorepo Scripts";
+  const scriptsResult = await packageJsonReader2.getScripts(
+    config2.repository.root
+  );
+  if (scriptsResult.isErr()) {
+    return err(scriptsResult.error);
+  }
+  const requiredScriptsMap = packageJsonReader2.getRootRequiredScripts();
+  const missingScripts = findMissingScripts(
+    scriptsResult.value,
+    requiredScriptsMap
+  );
+  if (missingScripts.size === 0) {
+    return ok({
+      checkName,
+      isValid: true,
+      successMessage: "Monorepo scripts are correctly set up"
+    });
+  }
+  return ok({
+    checkName,
+    errorMessage: `Missing required scripts: ${Array.from(missingScripts).join(", ")}`,
+    isValid: false
+  });
+};
+
+// src/domain/repository.ts
+import { ok as ok2 } from "neverthrow";
+import fs from "path";
+import coerce from "semver/functions/coerce.js";
+import semverGte from "semver/functions/gte.js";
+var isVersionValid = (version, minVersion) => {
+  const minAcceptedSemVer = coerce(minVersion);
+  const dependencySemVer = coerce(version);
+  if (!minAcceptedSemVer || !dependencySemVer) {
+    return false;
+  }
+  return semverGte(dependencySemVer, minAcceptedSemVer);
+};
+var checkPreCommitConfig = async (dependencies, config2) => {
+  const { repositoryReader: repositoryReader2 } = dependencies;
+  const checkName = "Pre-commit Configuration";
+  const preCommitResult = await repositoryReader2.fileExists(
+    fs.join(config2.repository.root, ".pre-commit-config.yaml")
+  );
+  if (preCommitResult.isOk() && preCommitResult.value) {
+    return ok2({
+      checkName,
+      isValid: true,
+      successMessage: "Pre-commit configuration is present in the repository root"
+    });
+  }
+  const errorMessage = preCommitResult.isErr() ? preCommitResult.error.message : `Pre-commit configuration is not present in the repository root. Please add a .pre-commit-config.yaml file to the repository root.`;
+  return ok2({
+    checkName,
+    errorMessage,
+    isValid: false
+  });
+};
+var checkTurboConfig = async (dependencies, config2) => {
+  const { packageJsonReader: packageJsonReader2, repositoryReader: repositoryReader2 } = dependencies;
+  const checkName = "Turbo Configuration";
+  const repoRoot2 = config2.repository.root;
+  const turboResult = await repositoryReader2.fileExists(
+    fs.join(repoRoot2, "turbo.json")
+  );
+  if (turboResult.isErr()) {
+    return ok2({
+      checkName,
+      errorMessage: turboResult.error.message,
+      isValid: false
+    });
+  }
+  const dependenciesResult = await packageJsonReader2.getDependencies(
+    repoRoot2,
+    "dev"
+  );
+  if (dependenciesResult.isErr()) {
+    return ok2({
+      checkName,
+      errorMessage: dependenciesResult.error.message,
+      isValid: false
+    });
+  }
+  const turboVersion = dependenciesResult.value.get(
+    "turbo"
+  );
+  if (!turboVersion) {
+    return ok2({
+      checkName,
+      errorMessage: "Turbo dependency not found in devDependencies. Please add 'turbo' to your devDependencies.",
+      isValid: false
+    });
+  }
+  if (!isVersionValid(turboVersion, config2.minVersions.turbo)) {
+    return ok2({
+      checkName,
+      errorMessage: `Turbo version (${turboVersion}) is too low. Minimum required version is ${config2.minVersions.turbo}.`,
+      isValid: false
+    });
+  }
+  return ok2({
+    checkName,
+    isValid: true,
+    successMessage: "Turbo configuration is present in the monorepo root and turbo dependency is installed"
+  });
+};
+
+// src/domain/doctor.ts
+var runDoctor = (dependencies, config2) => {
+  const doctorChecks = [
+    ResultAsync3.fromPromise(
+      checkPreCommitConfig(dependencies, config2),
+      () => new Error("Error checking pre-commit configuration")
+    ),
+    ResultAsync3.fromPromise(
+      checkTurboConfig(dependencies, config2),
+      () => new Error("Error checking Turbo configuration")
+    ),
+    ResultAsync3.fromPromise(
+      checkMonorepoScripts(dependencies, config2),
+      () => new Error("Error checking monorepo scripts")
+    )
+  ];
+  return ResultAsync3.combine(doctorChecks).match(
+    toDoctorResult,
+    () => ({
+      checks: [],
+      hasErrors: true
+    })
+  );
+};
+var toDoctorResult = (validationCheckResults) => {
+  const checks = validationCheckResults.map((result) => {
+    if (result.isOk()) {
+      return result.value;
+    }
+    return {
+      checkName: "Unknown",
+      errorMessage: result.error.message,
+      isValid: false
+    };
+  });
+  const hasErrors = checks.some((check) => !check.isValid);
+  return {
+    checks,
+    hasErrors
+  };
+};
+var printDoctorResult = ({ validationReporter: validationReporter2 }, result) => result.checks.map(validationReporter2.reportCheckResult);
+
+// src/adapters/commander/commands/doctor.ts
+var makeDoctorCommand = (dependencies, config2) => new Command().name("doctor").description(
+  "Verify the repository setup according to the DevEx guidelines"
+).action(async () => {
+  const result = await runDoctor(dependencies, config2);
+  printDoctorResult(dependencies, result);
+  const exitCode = result.hasErrors ? 1 : 0;
+  process2.exit(exitCode);
+});
+
+// src/adapters/commander/commands/info.ts
+import { Command as Command2 } from "commander";
+
+// src/domain/info.ts
+import { getLogger } from "@logtape/logtape";
+import { join } from "path";
+var detectFromLockFile = async (dependencies, config2) => {
+  const { repositoryReader: repositoryReader2 } = dependencies;
+  const repoRoot2 = config2.repository.root;
+  const pnpmResult = await repositoryReader2.fileExists(
+    join(repoRoot2, "pnpm-lock.yaml")
+  );
+  if (pnpmResult.isOk() && pnpmResult.value) return "pnpm";
+  const yarnResult = await repositoryReader2.fileExists(
+    join(repoRoot2, "yarn.lock")
+  );
+  if (yarnResult.isOk() && yarnResult.value) return "yarn";
+  const npmResult = await repositoryReader2.fileExists(
+    join(repoRoot2, "package-lock.json")
+  );
+  if (npmResult.isOk() && npmResult.value) return "npm";
+  return void 0;
+};
+var detectPackageManager = async (dependencies, config2) => {
+  const packageManager = dependencies.packageJson.packageManager ?? await detectFromLockFile(dependencies, config2);
+  return packageManager ?? "npm";
+};
+var detectNodeVersion = async ({ repositoryReader: repositoryReader2 }, nodeVersionFilePath) => await repositoryReader2.readFile(nodeVersionFilePath).unwrapOr(void 0);
+var detectTerraformVersion = async ({ repositoryReader: repositoryReader2 }, terraformVersionFilePath) => await repositoryReader2.readFile(terraformVersionFilePath).map((tfVersion) => tfVersion.trim()).unwrapOr(void 0);
+var getInfo = async (dependencies, config2) => ({
+  node: await detectNodeVersion(
+    { repositoryReader: dependencies.repositoryReader },
+    `${config2.repository.root}/.node-version`
+  ),
+  packageManager: await detectPackageManager(dependencies, config2),
+  terraform: await detectTerraformVersion(
+    dependencies,
+    `${config2.repository.root}/.terraform-version`
+  )
+});
+var printInfo = (result) => {
+  const logger2 = getLogger("json");
+  logger2.info(JSON.stringify(result));
+};
+
+// src/adapters/commander/commands/info.ts
+var makeInfoCommand = (dependencies, config2) => new Command2().name("info").description("Display information about the project").action(async () => {
+  const result = await getInfo(dependencies, config2);
+  printInfo(result);
+});
+
+// src/adapters/commander/commands/version.ts
+import { Command as Command3 } from "commander";
+
+// src/domain/version.ts
+import { getLogger as getLogger2 } from "@logtape/logtape";
+function printVersion() {
+  const logger2 = getLogger2(["dx-cli", "version"]);
+  logger2.info(`dx CLI version: ${"0.4.1"}`);
+}
+
+// src/adapters/commander/commands/version.ts
+var makeVersionCommand = () => new Command3().name("version").alias("v").action(() => printVersion());
+
+// src/adapters/commander/index.ts
+var makeCli = (deps2, config2) => {
+  const program2 = new Command4();
+  program2.name("dx").description("The CLI for DX-Platform").version("0.4.1");
+  program2.addCommand(makeDoctorCommand(deps2, config2));
+  program2.addCommand(makeVersionCommand());
+  program2.addCommand(makeInfoCommand(deps2, config2));
+  return program2;
+};
+
+// src/adapters/logtape/validation-reporter.ts
+import { getLogger as getLogger3 } from "@logtape/logtape";
+var makeValidationReporter = () => {
+  const logger2 = getLogger3(["dx-cli", "validation"]);
+  return {
+    reportCheckResult(result) {
+      if (result.isValid) {
+        logger2.info(`\u2705 ${result.successMessage}`);
+      } else {
+        logger2.error(`\u274C ${result.errorMessage}`);
+      }
+    },
+    reportValidationResult(result) {
+      if (result.isOk()) {
+        const validation = result.value;
+        if (validation.isValid) {
+          logger2.info(`\u2705 ${validation.successMessage}`);
+        } else {
+          logger2.error(`\u274C ${validation.errorMessage}`);
+        }
+      } else {
+        logger2.error(`\u274C ${result.error.message}`);
+      }
+    }
+  };
+};
+
+// src/adapters/node/package-json.ts
+import { join as join2 } from "path";
+import * as process3 from "process";
+
+// src/adapters/node/fs/file-reader.ts
+import { Result, ResultAsync as ResultAsync4 } from "neverthrow";
+import fs2 from "fs/promises";
+var readFile = (filePath) => ResultAsync4.fromPromise(
+  fs2.readFile(filePath, "utf-8"),
+  (cause) => new Error(`Failed to read file: ${filePath}`, { cause })
+);
+var readFileAndDecode = (filePath, schema) => {
+  const decode = ResultAsync4.fromThrowable(
+    schema.parseAsync,
+    () => new Error("File content is not valid for the given schema")
+  );
+  const toJSON = Result.fromThrowable(
+    JSON.parse,
+    () => new Error("Failed to parse JSON")
+  );
+  return readFile(filePath).andThen(toJSON).andThen(decode);
+};
+var fileExists = (path) => ResultAsync4.fromPromise(
+  fs2.stat(path),
+  () => new Error(`${path} not found.`)
+).map(() => true);
+
+// src/adapters/node/package-json.ts
+var makePackageJsonReader = () => ({
+  getDependencies: (cwd2 = process3.cwd(), type) => {
+    const packageJsonPath = join2(cwd2, "package.json");
+    return readFileAndDecode(packageJsonPath, packageJsonSchema).map(
+      (packageJson2) => {
+        const key = type === "dev" ? "devDependencies" : "dependencies";
+        return packageJson2[key];
+      }
+    );
+  },
+  getRootRequiredScripts: () => (/* @__PURE__ */ new Map()).set("code-review", "eslint ."),
+  getScripts: (cwd2 = process3.cwd()) => {
+    const packageJsonPath = join2(cwd2, "package.json");
+    return readFileAndDecode(packageJsonPath, packageJsonSchema).map(
+      ({ scripts }) => scripts
+    );
+  },
+  readPackageJson: (cwd2 = process3.cwd()) => {
+    const packageJsonPath = join2(cwd2, "package.json");
+    return readFileAndDecode(packageJsonPath, packageJsonSchema);
+  }
+});
+
+// src/adapters/node/repository.ts
+import { join as join3 } from "path";
+var findRepositoryRoot = (dir = process.cwd()) => {
+  const gitPath = join3(dir, ".git");
+  return fileExists(gitPath).mapErr(
+    () => new Error(
+      "Could not find repository root. Make sure to have the repo initialized."
+    )
+  ).map(() => dir);
+};
+var makeRepositoryReader = () => ({
+  fileExists,
+  findRepositoryRoot,
+  readFile
+});
+
+// src/config.ts
+var getConfig = (repositoryRoot2) => ({
+  minVersions: {
+    turbo: "2"
+  },
+  repository: {
+    root: repositoryRoot2
+  }
+});
+
+// src/index.ts
+await configure({
+  loggers: [
+    { category: ["dx-cli"], lowestLevel: "info", sinks: ["console"] },
+    { category: ["json"], lowestLevel: "info", sinks: ["rawJson"] },
+    {
+      category: ["logtape", "meta"],
+      lowestLevel: "warning",
+      sinks: ["console"]
+    }
+  ],
+  sinks: {
+    console: getConsoleSink(),
+    rawJson(record) {
+      console.log(record.rawMessage);
+    }
+  }
+});
+var logger = getLogger4(["dx-cli"]);
+var repositoryReader = makeRepositoryReader();
+var packageJsonReader = makePackageJsonReader();
+var validationReporter = makeValidationReporter();
+var repoRoot = await repositoryReader.findRepositoryRoot(process.cwd());
+if (repoRoot.isErr()) {
+  logger.error(
+    "Could not find repository root. Make sure to have the repo initialized."
+  );
+  process.exit(1);
+}
+var repositoryRoot = repoRoot.value;
+var repoPackageJson = await packageJsonReader.readPackageJson(repositoryRoot);
+if (repoPackageJson.isErr()) {
+  logger.error("Repository does not contain a package.json file");
+  process.exit(1);
+}
+var packageJson = repoPackageJson.value;
+var deps = {
+  packageJson,
+  packageJsonReader,
+  repositoryReader,
+  validationReporter
+};
+var config = getConfig(repositoryRoot);
+var program = makeCli(deps, config);
+program.parse();

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@pagopa/dx-cli",
+  "version": "0.4.1",
+  "type": "module",
+  "description": "A CLI useful to manage DX tools.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pagopa/dx.git",
+    "directory": "apps/cli"
+  },
+  "keywords": [
+    "DX",
+    "CLI"
+  ],
+  "files": [
+    "bin"
+  ],
+  "bin": {
+    "dx": "./bin/index.js"
+  },
+  "dependencies": {
+    "@logtape/logtape": "^1.0.0",
+    "commander": "^14.0.0",
+    "core-js": "^3.44.0",
+    "neverthrow": "^8.2.0",
+    "semver": "^7.7.2",
+    "zod": "^3.25.28"
+  },
+  "devDependencies": {
+    "@tsconfig/node22": "22.0.2",
+    "@types/node": "^22.16.2",
+    "@types/semver": "^7.7.0",
+    "@vitest/coverage-v8": "^3.2.4",
+    "eslint": "^9.31.0",
+    "prettier": "3.6.2",
+    "tsup": "^8.5.0",
+    "typescript": "~5.8.3",
+    "vitest": "^3.2.4",
+    "vitest-mock-extended": "^3.1.0",
+    "@pagopa/eslint-config": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "lint": "eslint --fix src",
+    "lint:check": "eslint src",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:coverage": "vitest --coverage"
+  }
+}