# lockfile-lint-api

> Lint an npm or yarn lockfile to analyze and detect issues

Latest version **5.9.2** (published 2025-04-27) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install lockfile-lint-api
pnpm add lockfile-lint-api
yarn add lockfile-lint-api
bun add lockfile-lint-api
```

## Health

**Score 43/100 (D)** — status: stable.

Positive: has types package; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: stale.

## Facts

| | |
|---|---|
| Version | 5.9.2 |
| Published | 2025-04-27 |
| First published | 2019-06-11 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | separate (@types/lockfile-lint-api) |
| Module format | CommonJS |
| Node | >=16.0.0 |
| Dependencies | 3 |
| Unpacked size | 41.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 868 |
| Author | Liran Tal |
| Maintainers | lirantal, lirantal_bot |
| Keywords | lockfile, lock, file, lint, linter, parse, npm, yarn |

## Links

- npm: https://www.npmjs.com/package/lockfile-lint-api
- Repository: https://github.com/lirantal/lockfile-lint
- Issues: https://github.com/lirantal/lockfile-lint/issues
- npm.io page: https://npm.io/package/lockfile-lint-api

## Dependencies (3)

- [debug](https://npm.io/package/debug.md) ^4.3.4
- [object-hash](https://npm.io/package/object-hash.md) ^3.0.0
- [@yarnpkg/parsers](https://npm.io/package/@yarnpkg/parsers.md) ^3.0.0-rc.48.1

## Alternatives

- [eslint-plugin-sonarjs](https://npm.io/package/eslint-plugin-sonarjs.md) — 2.9M weekly downloads
- [eslint-config-expo](https://npm.io/package/eslint-config-expo.md) — 1.5M weekly downloads
- [@matter/protocol](https://npm.io/package/@matter/protocol.md) — 63.5K weekly downloads
- [@eventcatalog/linter](https://npm.io/package/@eventcatalog/linter.md) — 24.8K weekly downloads
- [@inrupt/eslint-config-base](https://npm.io/package/@inrupt/eslint-config-base.md) — 4.5K weekly downloads

## Recent versions

- 5.9.2 (latest) — 2025-04-27
- 5.9.1 — 2024-02-11
- 5.9.0 — 2024-02-11
- 5.8.0 — 2023-08-01
- 5.7.0 — 2023-07-28
- 5.6.0 — 2023-07-28
- 5.5.5 — 2023-05-24
- 5.5.4 — 2023-05-24
- 5.5.3 — 2023-05-24
- 5.5.2 — 2023-05-23
- 5.5.1 — 2023-02-13
- 5.5.0 — 2022-12-26
- 5.4.6 — 2022-10-08
- 5.4.5 — 2022-09-30
- 5.4.4 — 2022-09-27
- … 41 more at https://npm.io/package/lockfile-lint-api/versions

## README

<p align="center"><h1 align="center">
  lockfile-lint-api
</h1>

<p align="center">
  Lint an npm or yarn lockfile to analyze and detect issues
</p>

<p align="center">
  <a href="https://www.npmjs.org/package/lockfile-lint-api"><img src="https://badgen.net/npm/v/lockfile-lint-api" alt="npm version"/></a>
  <a href="https://www.npmjs.org/package/lockfile-lint-api"><img src="https://badgen.net/npm/license/lockfile-lint-api" alt="license"/></a>
  <a href="https://www.npmjs.org/package/lockfile-lint-api"><img src="https://badgen.net/npm/dt/lockfile-lint-api" alt="downloads"/></a>
  <a href="https://travis-ci.org/lirantal/lockfile-lint"><img src="https://badgen.net/travis/lirantal/lockfile-lint" alt="build"/></a>
  <a href="https://codecov.io/gh/lirantal/lockfile-lint"><img src="https://badgen.net/codecov/c/github/lirantal/lockfile-lint" alt="codecov"/></a>
<a href="https://snyk.io/test/npm/lockfile-lint-api"><img src="https://snyk.io/test/npm/lockfile-lint-api/badge.svg" alt="Known Vulnerabilities" data-canonical-src="https://snyk.io/test/npm/lockfile-lint-api" style="max-width:100%;"></a>
  <a href="https://github.com/nodejs/security-wg/blob/main/processes/responsible_disclosure_template.md"><img src="https://img.shields.io/badge/Security-Responsible%20Disclosure-yellow.svg" alt="Security Responsible Disclosure" /></a>
</p>

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

---
_Source: https://npm.io/package/lockfile-lint-api · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._