@code-pushup/js-packages-plugin

@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+
• PNPM

Getting started

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

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

   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:

   import jsPackagesPlugin from '@code-pushup/js-packages-plugin';
   
   export default {
     // ...
     plugins: [
       // ...
       await jsPackagesPlugin({ packageManager: ['yarn'], checks: ['audit'] }),
     ],
   };
   

3. (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).

   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,
           },
           // ...
         ],
       },
       // ...
     ],
   };
   

4. 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.

     // ...
     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

Changelog

0.28.0 (2024-03-22)

Bug Fixes

• core: ensure output directory exists in compareReportFiles (cf309bc)
• utils: prevent mixed summary when some audit changed only value (20673fd)
• utils: use unicode arrows with wider OS support (271155e)

Features

• cli: include md format by default (65a08ea)
• core: create report-diff.md file if specified by persist.format (8c4e1e4)