@code-pushup/js-packages-plugin

📦 Code PushUp plugin for JavaScript packages. 🛡️
This plugin checks for known vulnerabilities and outdated dependencies. It supports the following package managers:

• NPM
• Yarn v1
• Yarn v2+

- In order to check outdated dependencies for Yarn v2+, you need to install yarn-plugin-outdated.

• PNPM

!NOTE As of now, Yarn v2 does not support security audit of optional dependencies. Only production and dev dependencies audits will be included in the report.

Getting started

1. If you haven't already, install @code-pushup/cli and create a configuration file.

1. Install as a dev dependency with your package manager:

```sh
npm install --save-dev @code-pushup/js-packages-plugin
```

```sh
yarn add --dev @code-pushup/js-packages-plugin
```

```sh
pnpm add --save-dev @code-pushup/js-packages-plugin
```

1. Insert plugin configuration with your package manager. By default, both audit and outdated checks will be run. The result should look as follows:

```js
import jsPackagesPlugin from '@code-pushup/js-packages-plugin';

export default {
  // ...
  plugins: [
    // ...
    await jsPackagesPlugin({ packageManager: 'npm' }), // replace with your package manager
  ],
};
```

You may run this plugin with a custom configuration for any supported package manager or command. A custom configuration will look similarly to the following:

```js
import jsPackagesPlugin from '@code-pushup/js-packages-plugin';

export default {
  // ...
  plugins: [
    // ...
    await jsPackagesPlugin({ packageManager: ['yarn'], checks: ['audit'] }),
  ],
};
```

1. (Optional) Reference individual audits or the provided plugin groups which you wish to include in custom categories (use npx code-pushup print-config to list audits and groups).

💡 Assign weights based on what influence each command should have on the overall category score (assign weight 0 to only include as extra info, without influencing category score).

```js
export default {
  // ...
  categories: [
    {
      slug: 'security',
      title: 'Security',
      refs: [
        {
          type: 'group',
          plugin: 'npm-audit', // replace prefix with your package manager
          slug: 'js-packages',
          weight: 1,
        },
      ],
    },
    {
      slug: 'up-to-date',
      title: 'Up-to-date tools',
      refs: [
        {
          type: 'group',
          plugin: 'npm-outdated', // replace prefix with your package manager
          slug: 'js-packages',
          weight: 1,
        },
        // ...
      ],
    },
    // ...
  ],
};
```

1. Run the CLI with npx code-pushup collect and view or upload report (refer to CLI docs).

Plugin architecture

Plugin configuration specification

The plugin accepts the following parameters:

• packageManager: The package manager you are using. Supported values: npm, yarn-classic (v1), yarn-modern (v2+), pnpm.
• (optional) checks: Array of checks to be run. Supported commands: audit, outdated. Both are configured by default.
• (optional) auditLevelMapping: If you wish to set a custom level of issue severity based on audit vulnerability level, you may do so here. Any omitted values will be filled in by defaults. Audit levels are: critical, high, moderate, low and info. Issue severities are: error, warn and info. By default the mapping is as follows: critical and high → error; moderate and low → warning; info → info.

Audits and group

This plugin provides a group per check for a convenient declaration in your config. Each group contains audits for all supported groups of dependencies (prod, dev and optional).

// ...
categories: [
  {
    slug: 'dependencies',
    title: 'Package dependencies',
    refs: [
      {
        type: 'group',
        plugin: 'js-packages',
        slug: 'npm-audit', // replace prefix with your package manager
        weight: 1,
      },
      {
        type: 'group',
        plugin: 'js-packages',
        slug: 'npm-outdated', // replace prefix with your package manager
        weight: 1,
      },
      // ...
    ],
  },
  // ...
],

Each dependency group has its own audit. If you want to check only a subset of dependencies (e.g. run audit and outdated for production dependencies) or assign different weights to them, you can do so in the following way:

// ...
categories: [
  {
    slug: 'dependencies',
    title: 'Package dependencies',
    refs: [
      {
        type: 'audit',
        plugin: 'js-packages',
        slug: 'npm-audit-prod', // replace prefix with your package manager
        weight: 2,
      },
                 {
        type: 'audit',
        plugin: 'js-packages',
        slug: 'npm-audit-dev', // replace prefix with your package manager
        weight: 1,
      },
      {
        type: 'audit',
        plugin: 'js-packages',
        slug: 'npm-outdated-prod', // replace prefix with your package manager
        weight: 2,
      },
      // ...
    ],
  },
  // ...
],

Score calculation

Audit output score is a numeric value in the range 0-1.

Security audit

The score for security audit is decreased for each vulnerability found based on its severity.
The mapping is as follows:

• Critical vulnerabilities set score to 0.
• High-severity vulnerabilities reduce score by 0.1.
• Moderate vulnerabilities reduce score by 0.05.
• Low-severity vulnerabilities reduce score by 0.02.
• Information-level vulnerabilities reduce score by 0.01.

Examples:

• 1+ critical vulnerabilities → score will be 0
• 1 high and 2 low vulnerabilities → score will be 1 - 0.1 - 2\*0.02 = 0.86

Outdated dependencies

In order for this audit not to drastically lower the score, the current logic is such that only dependencies with major outdated version lower the score by a proportional amount to the total amount of dependencies on your project.
Examples:

• 5 dependencies out of which 1 has an outdated major version → score will be (5 - 1) / 5 = 0.8
• 2 dependencies out of which 1 has an outdated minor version and one is up-to-date → score stay 1