advocate v2.2.0

Advocate

Your advocate doesn't let you down. He analyzes the licenses of all installed npm modules of your project and their transitive dependencies and compares them to a given whitelist.

This package works with yarn.

Installation

npm install advocate --save-dev

Usage

Advocate can be used as part of your project's automated tests. That way, you ensure to only use modules with whitelisted licenses.

advocate({licenses: ['MIT']})
    .then(function(moduleInformation) {
        for (module of moduleInformation.violatingModules) {
            console.log(`
                I advise you to not use ${module.name}@${module.version}
                because of the license ${module.license}.
            `);
        }
    });

Output:

I advise you to not use spdx-exceptions@1.0.4
because of the license CC-BY-3.0.

API

advocate(whitelist?: Whitelist, options?: Options): Promise<ModuleInformation>

Determines modules whose license descriptions do not satisfy the given whitelist. In order to determine the license of a module, advocate respects the package.json but also tries to guess the license using text files such as README or LICENSE.

type ModuleInformation

{
    allModules: Array<Module>
    violatingModules: Array<Module>
}

type Module

Example:

{
  "module1@1.0.0": {
    "name": "module1",
    "version": "1.0.0",
    "license": "MIT"
  }
}

type Whitelist

{
    licenses: Array<LicenseString>,
    licenseExceptions: Array<LicenseException>,
    modules: Array<WhitelistedModule>
}

type WhitelistedModule

{
    name: string
    license: LicenseString
    version: string
}

type LicenseString

Either a SPDX expression or a simple license identifier

type LicenseException

string

type Options

{
    path?: string // default: cwd
    dev?: boolean, // default: false
}

path

Specifies the directory of the npm module whose dependencies will be analyzed by advocate.

Defaults to the current working directory.

dev

Specifies whether to analyze production or development dependencies.

A value of false means advocate only respects your production dependencies and their transitive ones.

A value of true means advocate will only respect your devDependencies and their transitive production dependencies. advocate will never respect transitive devDependencies.

Defaults to false.