Neo's Personal Matrix

    lockfile-lint-api
    DefinitelyTyped icon, indicating that this package has TypeScript declarations provided by the separate @types/lockfile-lint-api package

    5.3.0 • Public • Published

    lockfile-lint-api

    Lint an npm or yarn lockfile to analyze and detect issues

    npm version license downloads build codecov Known Vulnerabilities Security Responsible Disclosure

    About

    Lints an npm or yarn lockfile to analyze and detect issues

    Install

    npm install --save lockfile-lint-api

    Usage

    lockfile-lint-api exposes a set of validator APIs that can be used for programmatic use-cases, such as being employed by other tools and programs if needed.

    Validators

    The following lockfile validators are supported

    Validator API description implemented
    ValidateHttps validates the use of HTTPS as protocol schema for all resources
    ValidateHost validates a whitelist of allowed hosts to be used for resources in the lockfile
    ValidatePackageNames validates that the resolved URL matches the package name
    ValidateScheme validates a whitelist of allowed URI schemes to be used for hosts

    NOTE: package entries without a resolved field (for example, those installed from the local filesystem) will automatically pass all url-based validators.

    Success and failures

    When validators encounter errors they will throw an exception, and on either success or failure in validating data they will always return a descriptive object for the validation task.

    Successful validation

    When validation is successful the following object will be returned from the validating function:

    {
      "type": "success",
      "errors": []
    }

    Failed validation

    When validation has failed the following object will be returned from the validating function:

    {
      "type": "error",
      "errors": [
        {
          "package": "@babel/cli",
          "message": "detected invalid origin for package: @babel/cli"
        }
      ]
    }

    Notes about the returned object:

    • An errors object will always return an array of errors metadata, even if there's only one error associated with the validation being performed
    • All errors should always have a message
    • The availability of the package property and other metadata depends on the specific validators being used

    Example

    const validator = new ValidateHost({packages: lockfile.object})
    let result
    try {
      result = validator.validate(['npm'])
    } catch (error) {
      // something bad happened during validation and the validation
      // process couldn't take place
    }
    
    console.log(result)
    /* prints
    {
      "type": "error",
      "errors": [
        {
          "message": "detected invalid origin for package: meow",
          "package": "meow"
        }
      ]
    }
    */

    Example

    const {ValidateHost, ParseLockfile} = require('lockfile-lint-api')
    
    // path to the lockfile
    const yarnLockfilePath = '/path/to/my/yarn.lock'
    const options = {
      lockfilePath: yarnLockfilePath
    }
    
    // instantiate a new parser with options object
    const parser = new ParseLockfile(options)
    
    // read the file synchronously and parses it
    // providing back an object that is compatible
    // with the @yarn/lockfile library which has
    // all the packages listed in `lockfile.object`
    const lockfile = parser.parseSync()
    
    // now instantiate a validator object with those
    // list of packages
    const validator = new ValidateHost({packages: lockfile.object})
    let result
    try {
      // validation is synchronous and is being called
      // with 'npm' as a shortcut for the npm registry
      // host to validate all lockfile resources are
      // whitelisted to the npm host
      result = validator.validate(['npm'])
    } catch (error) {
      // couldn't process the validation
    }
    
    if (result.type === 'success') {
      // validation succeeded
    }

    Contributing

    Please consult CONTRIBUTING for guidelines on contributing to this project.

    Author

    lockfile-lint-api © Liran Tal, Released under the Apache-2.0 License.

    Install

    npm i lockfile-lint-api

    DownloadsWeekly Downloads

    77,740

    Version

    5.3.0

    License

    Apache-2.0

    Unpacked Size

    50.6 kB

    Total Files

    13

    Last publish

    Collaborators

    • lirantal
    • lirantal_bot