lockfile-lint-api
Lint an npm or yarn lockfile to analyze and detect issues
# About
Lints an npm or yarn lockfile to analyze and detect issues
# Install
```bash
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 | ✅ |
| ValidateIntegrity | validates that the integrity hash type is sha512 | ✅ |
**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:
```json
{
"type": "success",
"errors": []
}
```
### Failed validation
When validation has failed the following object will be returned from the validating function:
```json
{
"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
```js
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
```js
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](../../CONTRIBUTING.md) for guidelines on contributing to this project.
# Author
**lockfile-lint-api** © [Liran Tal](https://github.com/lirantal), Released under the [Apache-2.0](./LICENSE) License.