@code-pushup/js-packages-plugin 0.30.0-alpha → 0.35.0

package/CONTRIBUTING.md

@@ -2,9 +2,19 @@
 
 ## Adding new package managers
 
-In order to add a support for a new package manager, one needs to do the following.
+In order to add a support for a new package manager, one needs to do the following:
 
-1. Expand `packageManagerSchema` in `config.ts`.
-2. Expand `<command>Args` in `runner/<command>/constants.ts` with a set of arguments to be run for a given package manager command.
-3. Create a custom type in `runner/<command>/types.ts` with relevant properties based on expected command JSON output.
-4. Create a function in `runner/<command>/unify-type.ts` that will transform JSON output into a normalized type `OutdatedResult` or `AuditResult` and add it to `normalized<command>Mapper` in `runner/<command>/constants.ts`.
+1. Expand `packageManagerIdSchema` in `config.ts`.
+2. Create a new object of `PackageManager` type in `package-managers/<name>/<name>.ts` and fill it in with all relevant data. Following the current pattern of separate files for audit and outdated result and types is recommended.
+3. Extend `package-managers/package-managers.ts` record with the new package manager.
+
+> [!NOTE]
+> Should your package manager require specific behaviour, feel free to request a property addition or change.
+
+### Notable properties
+
+- `(audit|check).unifyResult()`: In order to process the results in a unified way, the expected type needs to be defined in `runner/(audit|check)/types.ts` and its transformation to normalised result implemented in `runner/(audit|check)/unify-type.ts`. This function is then referenced in the object to be called accordingly.
+- `audit.getCommandArgs(depGroup)`: The `audit` command is run for one dependency group. In order to filter out the other dependencies, the arguments are provided dynamically based on this function. One may include frequently used arguments from `COMMON_AUDIT_ARGS`.
+- `audit.ignoreExitCode`: Some package managers do not allow non-zero exit code override. To ignore non-zero exit code, set this property to `true`.
+- `audit.supportedDepGroups`: Some package managers do not support `audit` check for all types of dependencies (e.g. optional). In that case, please list a supported subset of dependencies in this property. By default, all dependency groups are considered supported.
+- `audit.postProcessResult()`: The `audit` check often does not offer exclusive result for all dependency groups. In order to filter out duplicates after the results are normalised, add a post-processing function here.

package/bin.js

@@ -832,17 +832,11 @@ var dependencyGroupToLong = {
   dev: "devDependencies",
   optional: "optionalDependencies"
 };
-var pkgManagerCommands = {
-  npm: "npm",
-  "yarn-classic": "yarn",
-  "yarn-modern": "yarn",
-  pnpm: "pnpm"
-};
 
 // packages/plugin-js-packages/src/lib/config.ts
 var dependencyGroups = ["prod", "dev", "optional"];
 var packageCommandSchema = z15.enum(["audit", "outdated"]);
-var packageManagerSchema = z15.enum([
+var packageManagerIdSchema = z15.enum([
   "npm",
   "yarn-classic",
   "yarn-modern",
@@ -869,7 +863,9 @@ var jsPackagesPluginConfigSchema = z15.object({
   checks: z15.array(packageCommandSchema, {
     description: "Package manager commands to be run. Defaults to both audit and outdated."
   }).min(1).default(["audit", "outdated"]),
-  packageManager: packageManagerSchema.describe("Package manager to be used."),
+  packageManager: packageManagerIdSchema.describe(
+    "Package manager to be used."
+  ),
   auditLevelMapping: z15.record(packageAuditLevelSchema, issueSeveritySchema, {
     description: "Mapping of audit levels to issue severity. Custom mapping or overrides may be entered manually, otherwise has a default preset."
   }).default(defaultAuditLevelMapping).transform(fillAuditLevelMapping)
@@ -907,7 +903,11 @@ function filterAuditResult(result, key, referenceResult) {
   };
 }
 
-// packages/plugin-js-packages/src/lib/runner/audit/unify-type.ts
+// packages/plugin-js-packages/src/lib/package-managers/constants.ts
+var COMMON_AUDIT_ARGS = ["audit", "--json"];
+var COMMON_OUTDATED_ARGS = ["outdated", "--json"];
+
+// packages/plugin-js-packages/src/lib/package-managers/npm/audit-result.ts
 function npmToAuditResult(output) {
   const npmAudit = JSON.parse(output);
   const vulnerabilities = objectToEntries(npmAudit.vulnerabilities).map(
@@ -964,6 +964,159 @@ function npmToAdvisory(name, vulnerabilities, prevNodes = /* @__PURE__ */ new Se
   }
   return null;
 }
+
+// packages/plugin-js-packages/src/lib/package-managers/npm/outdated-result.ts
+function npmToOutdatedResult(output) {
+  const npmOutdated = JSON.parse(output);
+  return objectToEntries(npmOutdated).filter(
+    (entry) => entry[1].current != null
+  ).map(([name, overview]) => ({
+    name,
+    current: overview.current,
+    latest: overview.latest,
+    type: overview.type,
+    ...overview.homepage != null && { url: overview.homepage }
+  }));
+}
+
+// packages/plugin-js-packages/src/lib/package-managers/npm/npm.ts
+var npmDependencyOptions = {
+  prod: ["--omit=dev", "--omit=optional"],
+  dev: ["--include=dev", "--omit=optional"],
+  optional: ["--include=optional", "--omit=dev"]
+};
+var npmPackageManager = {
+  slug: "npm",
+  name: "NPM",
+  command: "npm",
+  icon: "npm",
+  docs: {
+    homepage: "https://docs.npmjs.com/",
+    audit: "https://docs.npmjs.com/cli/commands/npm-audit",
+    outdated: "https://docs.npmjs.com/cli/commands/npm-outdated"
+  },
+  audit: {
+    getCommandArgs: (groupDep) => [
+      ...COMMON_AUDIT_ARGS,
+      ...npmDependencyOptions[groupDep],
+      "--audit-level=none"
+    ],
+    unifyResult: npmToAuditResult,
+    // prod dependencies need to be filtered out manually since v10
+    postProcessResult: (results) => ({
+      prod: results.prod,
+      dev: filterAuditResult(results.dev, "name", results.prod),
+      optional: filterAuditResult(results.optional, "name", results.prod)
+    })
+  },
+  outdated: {
+    commandArgs: [...COMMON_OUTDATED_ARGS, "--long"],
+    unifyResult: npmToOutdatedResult
+  }
+};
+
+// packages/plugin-js-packages/src/lib/runner/audit/utils.ts
+function getVulnerabilitiesTotal(summary) {
+  return Object.values(summary).reduce((acc, value) => acc + value, 0);
+}
+
+// packages/plugin-js-packages/src/lib/package-managers/pnpm/audit-result.ts
+function pnpmToAuditResult(output) {
+  const pnpmResult = JSON.parse(output);
+  const vulnerabilities = Object.values(pnpmResult.advisories).map(
+    ({
+      module_name: name,
+      id,
+      title,
+      url,
+      severity,
+      vulnerable_versions: versionRange,
+      recommendation: fixInformation,
+      findings
+    }) => {
+      const path = findings[0]?.paths[0];
+      return {
+        name,
+        id,
+        title,
+        url,
+        severity,
+        versionRange,
+        directDependency: path == null ? true : pnpmToDirectDependency(path),
+        fixInformation
+      };
+    }
+  );
+  return {
+    vulnerabilities,
+    summary: {
+      ...pnpmResult.metadata.vulnerabilities,
+      total: getVulnerabilitiesTotal(pnpmResult.metadata.vulnerabilities)
+    }
+  };
+}
+function pnpmToDirectDependency(path) {
+  const deps = path.split(" > ").slice(1);
+  if (deps.length <= 1) {
+    return true;
+  }
+  return deps[0]?.split("@")[0] ?? true;
+}
+
+// packages/plugin-js-packages/src/lib/package-managers/pnpm/outdated-result.ts
+function pnpmToOutdatedResult(output) {
+  const pnpmOutdated = JSON.parse(output);
+  return objectToEntries(pnpmOutdated).map(
+    ([name, { current, latest, dependencyType: type }]) => ({
+      name,
+      current,
+      latest,
+      type
+    })
+  );
+}
+
+// packages/plugin-js-packages/src/lib/package-managers/pnpm/pnpm.ts
+var pnpmDependencyOptions = {
+  prod: ["--prod", "--no-optional"],
+  dev: ["--dev", "--no-optional"],
+  optional: []
+};
+var pnpmPackageManager = {
+  slug: "pnpm",
+  name: "pnpm",
+  command: "pnpm",
+  icon: "pnpm",
+  docs: {
+    homepage: "https://pnpm.io/pnpm-cli",
+    audit: "https://pnpm.io/cli/audit/",
+    outdated: "https://pnpm.io/cli/outdated"
+  },
+  audit: {
+    getCommandArgs: (groupDep) => [
+      ...COMMON_AUDIT_ARGS,
+      ...pnpmDependencyOptions[groupDep]
+    ],
+    ignoreExitCode: true,
+    unifyResult: pnpmToAuditResult,
+    // optional dependencies don't have an exclusive option so they need duplicates filtered out
+    postProcessResult: (results) => ({
+      prod: results.prod,
+      dev: results.dev,
+      optional: filterAuditResult(
+        filterAuditResult(results.optional, "id", results.prod),
+        "id",
+        results.dev
+      )
+    })
+  },
+  outdated: {
+    commandArgs: COMMON_OUTDATED_ARGS,
+    unifyResult: pnpmToOutdatedResult
+  }
+};
+
+// packages/plugin-js-packages/src/lib/package-managers/yarn-classic/audit-result.ts
 function yarnv1ToAuditResult(output) {
   const yarnv1Result = fromJsonLines(output);
   const [yarnv1Advisory, yarnv1Summary] = validateYarnv1Result(yarnv1Result);
@@ -1010,6 +1163,47 @@ function validateYarnv1Result(result) {
   );
   return [vulnerabilities, summary];
 }
+
+// packages/plugin-js-packages/src/lib/package-managers/yarn-classic/outdated-result.ts
+function yarnv1ToOutdatedResult(output) {
+  const yarnv1Outdated = fromJsonLines(output);
+  const dependencies = yarnv1Outdated[1].data.body;
+  return dependencies.map(([name, current, _, latest, __, type, url]) => ({
+    name,
+    current,
+    latest,
+    type,
+    url
+  }));
+}
+
+// packages/plugin-js-packages/src/lib/package-managers/yarn-classic/yarn-classic.ts
+var yarnv1PackageManager = {
+  slug: "yarn-classic",
+  name: "Yarn v1",
+  command: "yarn",
+  icon: "yarn",
+  docs: {
+    homepage: "https://classic.yarnpkg.com/docs/",
+    audit: "https://classic.yarnpkg.com/docs/cli/audit",
+    outdated: "https://classic.yarnpkg.com/docs/cli/outdated/"
+  },
+  audit: {
+    getCommandArgs: (groupDep) => [
+      ...COMMON_AUDIT_ARGS,
+      "--groups",
+      dependencyGroupToLong[groupDep]
+    ],
+    ignoreExitCode: true,
+    unifyResult: yarnv1ToAuditResult
+  },
+  outdated: {
+    commandArgs: COMMON_OUTDATED_ARGS,
+    unifyResult: yarnv1ToOutdatedResult
+  }
+};
+
+// packages/plugin-js-packages/src/lib/package-managers/yarn-modern/audit-result.ts
 function yarnv2ToAuditResult(output) {
   const yarnv2Audit = JSON.parse(output);
   const vulnerabilities = Object.values(yarnv2Audit.advisories).map(
@@ -1034,14 +1228,67 @@ function yarnv2ToAuditResult(output) {
       };
     }
   );
-  const total = Object.values(yarnv2Audit.metadata.vulnerabilities).reduce(
-    (acc, value) => acc + value,
-    0
-  );
-  const summary = { ...yarnv2Audit.metadata.vulnerabilities, total };
-  return { vulnerabilities, summary };
+  return {
+    vulnerabilities,
+    summary: {
+      ...yarnv2Audit.metadata.vulnerabilities,
+      total: getVulnerabilitiesTotal(yarnv2Audit.metadata.vulnerabilities)
+    }
+  };
 }
 
+// packages/plugin-js-packages/src/lib/package-managers/yarn-modern/outdated-result.ts
+function yarnv2ToOutdatedResult(output) {
+  const npmOutdated = JSON.parse(output);
+  return npmOutdated.map(({ name, current, latest, type }) => ({
+    name,
+    current,
+    latest,
+    type
+  }));
+}
+
+// packages/plugin-js-packages/src/lib/package-managers/yarn-modern/yarn-modern.ts
+var yarnv2EnvironmentOptions = {
+  prod: "production",
+  dev: "development",
+  optional: ""
+};
+var yarnv2PackageManager = {
+  slug: "yarn-modern",
+  name: "yarn-modern",
+  command: "yarn",
+  icon: "yarn",
+  docs: {
+    homepage: "https://yarnpkg.com/getting-started",
+    audit: "https://yarnpkg.com/cli/npm/audit",
+    outdated: "https://github.com/mskelton/yarn-plugin-outdated"
+  },
+  audit: {
+    getCommandArgs: (groupDep) => [
+      "npm",
+      ...COMMON_AUDIT_ARGS,
+      "--environment",
+      yarnv2EnvironmentOptions[groupDep]
+    ],
+    supportedDepGroups: ["prod", "dev"],
+    // Yarn v2 does not support audit for optional dependencies
+    unifyResult: yarnv2ToAuditResult
+  },
+  outdated: {
+    commandArgs: COMMON_OUTDATED_ARGS,
+    unifyResult: yarnv2ToOutdatedResult
+  }
+};
+
+// packages/plugin-js-packages/src/lib/package-managers/package-managers.ts
+var packageManagers = {
+  npm: npmPackageManager,
+  "yarn-classic": yarnv1PackageManager,
+  "yarn-modern": yarnv2PackageManager,
+  pnpm: pnpmPackageManager
+};
+
 // packages/plugin-js-packages/src/lib/runner/audit/constants.ts
 var auditScoreModifiers = {
   critical: 1,
@@ -1050,44 +1297,15 @@ var auditScoreModifiers = {
   low: 0.02,
   info: 0.01
 };
-var normalizeAuditMapper = {
-  npm: npmToAuditResult,
-  "yarn-classic": yarnv1ToAuditResult,
-  "yarn-modern": yarnv2ToAuditResult,
-  pnpm: () => {
-    throw new Error("PNPM audit is not supported yet.");
-  }
-};
-var npmDependencyOptions = {
-  prod: ["--omit=dev", "--omit=optional"],
-  dev: ["--include=dev", "--omit=optional"],
-  optional: ["--include=optional", "--omit=dev"]
-};
-var yarnv2EnvironmentOptions = {
-  prod: "production",
-  dev: "development",
-  optional: ""
-};
-var auditArgs = (groupDep) => ({
-  npm: [...npmDependencyOptions[groupDep], "--json", "--audit-level=none"],
-  "yarn-classic": ["--json", "--groups", dependencyGroupToLong[groupDep]],
-  "yarn-modern": [
-    "--json",
-    "--environment",
-    yarnv2EnvironmentOptions[groupDep]
-  ],
-  // TODO: Add once PNPM is supported.
-  pnpm: []
-});
 
 // packages/plugin-js-packages/src/lib/runner/audit/transform.ts
-function auditResultToAuditOutput(result, packageManager, dependenciesType, auditLevelMapping) {
+function auditResultToAuditOutput(result, id, depGroup, auditLevelMapping) {
   const issues = vulnerabilitiesToIssues(
     result.vulnerabilities,
     auditLevelMapping
   );
   return {
-    slug: `${packageManager}-audit-${dependenciesType}`,
+    slug: `${id}-audit-${depGroup}`,
     score: calculateAuditScore(result.summary),
     value: result.summary.total,
     displayValue: summaryToDisplayValue(result.summary),
@@ -1144,66 +1362,20 @@ var PLUGIN_CONFIG_PATH = join2(
   "plugin-config.json"
 );
 
-// packages/plugin-js-packages/src/lib/runner/outdated/unify-type.ts
-function npmToOutdatedResult(output) {
-  const npmOutdated = JSON.parse(output);
-  return objectToEntries(npmOutdated).filter(
-    (entry) => entry[1].current != null
-  ).map(([name, overview]) => ({
-    name,
-    current: overview.current,
-    latest: overview.latest,
-    type: overview.type,
-    ...overview.homepage != null && { url: overview.homepage }
-  }));
-}
-function yarnv1ToOutdatedResult(output) {
-  const yarnv1Outdated = fromJsonLines(output);
-  const dependencies = yarnv1Outdated[1].data.body;
-  return dependencies.map(([name, current, _, latest, __, type, url]) => ({
-    name,
-    current,
-    latest,
-    type,
-    url
-  }));
-}
-function yarnv2ToOutdatedResult(output) {
-  const npmOutdated = JSON.parse(output);
-  return npmOutdated.map(({ name, current, latest, type }) => ({
-    name,
-    current,
-    latest,
-    type
-  }));
-}
-
 // packages/plugin-js-packages/src/lib/runner/outdated/constants.ts
 var outdatedSeverity = {
   major: "error",
   minor: "warning",
   patch: "info"
 };
-var outdatedArgs = {
-  npm: ["--json", "--long"],
-  "yarn-classic": ["--json"],
-  "yarn-modern": ["--json"],
-  pnpm: []
-};
-var normalizeOutdatedMapper = {
-  npm: npmToOutdatedResult,
-  "yarn-classic": yarnv1ToOutdatedResult,
-  "yarn-modern": yarnv2ToOutdatedResult,
-  pnpm: (_) => []
-};
 
 // packages/plugin-js-packages/src/lib/runner/outdated/types.ts
 var versionType = ["major", "minor", "patch"];
 
 // packages/plugin-js-packages/src/lib/runner/outdated/transform.ts
-function outdatedResultToAuditOutput(result, packageManager, dependencyGroup) {
+function outdatedResultToAuditOutput(result, packageManager, depGroup) {
   const relevantDependencies = result.filter(
-    (dep) => dep.type === dependencyGroupToLong[dependencyGroup]
+    (dep) => dep.type === dependencyGroupToLong[depGroup]
   );
   const outdatedDependencies = relevantDependencies.filter(
     (dep) => dep.current !== dep.latest
@@ -1217,7 +1389,7 @@ function outdatedResultToAuditOutput(result, packageManager, dependencyGroup) {
   );
   const issues = outdatedDependencies.length === 0 ? [] : outdatedToIssues(outdatedDependencies);
   return {
-    slug: `${packageManager}-outdated-${dependencyGroup}`,
+    slug: `${packageManager}-outdated-${depGroup}`,
     score: calculateOutdatedScore(
       outdatedStats.major,
       relevantDependencies.length
@@ -1288,32 +1460,33 @@ async function executeRunner() {
   await ensureDirectoryExists(dirname(RUNNER_OUTPUT_PATH));
   await writeFile(RUNNER_OUTPUT_PATH, JSON.stringify(checkResults));
 }
-async function processOutdated(packageManager) {
+async function processOutdated(id) {
+  const pm = packageManagers[id];
   const { stdout } = await executeProcess({
-    command: pkgManagerCommands[packageManager],
-    args: ["outdated", ...outdatedArgs[packageManager]],
+    command: pm.command,
+    args: pm.outdated.commandArgs,
     cwd: process.cwd(),
     ignoreExitCode: true
-    // npm outdated returns exit code 1 when outdated dependencies are found
+    // outdated returns exit code 1 when outdated dependencies are found
   });
-  const normalizedResult = normalizeOutdatedMapper[packageManager](stdout);
+  const normalizedResult = pm.outdated.unifyResult(stdout);
   return dependencyGroups.map(
-    (dep) => outdatedResultToAuditOutput(normalizedResult, packageManager, dep)
+    (depGroup) => outdatedResultToAuditOutput(normalizedResult, id, depGroup)
   );
 }
-async function processAudit(packageManager, auditLevelMapping) {
-  const supportedDepGroups = packageManager === "yarn-modern" ? dependencyGroups.filter((dep) => dep !== "optional") : dependencyGroups;
+async function processAudit(id, auditLevelMapping) {
+  const pm = packageManagers[id];
+  const supportedDepGroups = pm.audit.supportedDepGroups ?? dependencyGroups;
   const auditResults = await Promise.allSettled(
     supportedDepGroups.map(
-      async (dep) => {
+      async (depGroup) => {
         const { stdout } = await executeProcess({
-          command: pkgManagerCommands[packageManager],
-          args: getAuditCommandArgs(packageManager, dep),
+          command: pm.command,
+          args: pm.audit.getCommandArgs(depGroup),
           cwd: process.cwd(),
-          ignoreExitCode: packageManager === "yarn-classic"
-          // yarn v1 does not have exit code configuration
+          ignoreExitCode: pm.audit.ignoreExitCode
         });
-        return [dep, normalizeAuditMapper[packageManager](stdout)];
+        return [depGroup, pm.audit.unifyResult(stdout)];
       }
     )
   );
@@ -1322,37 +1495,21 @@ async function processAudit(packageManager, auditLevelMapping) {
     rejected.map((result) => {
       console.error(result.reason);
     });
-    throw new Error(
-      `JS Packages plugin: Running ${pkgManagerCommands[packageManager]} audit failed.`
-    );
+    throw new Error(`JS Packages plugin: Running ${pm.name} audit failed.`);
   }
   const fulfilled = objectFromEntries(
     auditResults.filter(isPromiseFulfilledResult).map((x) => x.value)
   );
-  const uniqueResults = packageManager === "npm" ? filterNpmAuditResults(fulfilled) : fulfilled;
+  const uniqueResults = pm.audit.postProcessResult?.(fulfilled) ?? fulfilled;
   return supportedDepGroups.map(
-    (group) => auditResultToAuditOutput(
-      uniqueResults[group],
-      packageManager,
-      group,
+    (depGroup) => auditResultToAuditOutput(
+      uniqueResults[depGroup],
+      id,
+      depGroup,
       auditLevelMapping
     )
   );
 }
-function getAuditCommandArgs(packageManager, group) {
-  return [
-    ...packageManager === "yarn-modern" ? ["npm"] : [],
-    "audit",
-    ...auditArgs(group)[packageManager]
-  ];
-}
-function filterNpmAuditResults(results) {
-  return {
-    prod: results.prod,
-    dev: filterAuditResult(results.dev, "name", results.prod),
-    optional: filterAuditResult(results.optional, "name", results.prod)
-  };
-}
 
 // packages/plugin-js-packages/src/bin.ts
 await executeRunner();