eslint-plugin-lockfile

eslint-plugin-lockfile

An ESLint plugin to lint your npm ecosystem lockfiles for security and consistency issues.

This plugin supports lockfiles from npm, yarn, pnpm, bun, and vlt package managers.

Installation

npm install eslint-plugin-lockfile --save-dev

Configuration

Flat Config (ESLint 9+)

// eslint.config.js
import lockfile from 'eslint-plugin-lockfile';

export default [
	lockfile.configs.recommended,
];

Legacy Config (ESLint 8)

{
	"extends": ["plugin:lockfile/recommended-legacy"]
}

Manual Configuration

// eslint.config.js
import lockfile from 'eslint-plugin-lockfile';

export default [
	{
		files: ['**/package-lock.json', '**/yarn.lock', '**/pnpm-lock.yaml', '**/bun.lock', '**/bun.lockb', '**/vlt-lock.json'],
		plugins: { lockfile },
		rules: {
			'lockfile/flavor': ['error', 'npm'],
			'lockfile/version': 'error',
			'lockfile/integrity': 'error',
			'lockfile/registry': 'error',
			'lockfile/non-registry-specifiers': 'error',
			'lockfile/binary-conflicts': 'error',
		},
	},
];

Supported Package Managers

Package Manager	Lockfile(s)
npm	package-lock.json, npm-shrinkwrap.json
yarn	yarn.lock
pnpm	pnpm-lock.yaml
bun	bun.lock, bun.lockb
vlt	vlt-lock.json

Rules

Name	Description
binary-conflicts	Detect binary name conflicts between packages
flavor	Enforce allowed lockfile formats
integrity	Enforce integrity values in lockfiles
non-registry-specifiers	Warn on dependencies from non-registry sources
registry	Enforce allowed registries in lockfiles
version	Enforce lockfile version

lockfile/flavor

Enforces which lockfile formats are allowed in your project. This helps ensure your team uses a consistent package manager.

// Allow only npm lockfiles
'lockfile/flavor': ['error', 'npm']

// Allow npm or yarn
'lockfile/flavor': ['error', ['npm', 'yarn']]

// Allow specific lockfile variants
'lockfile/flavor': ['error', [{ name: 'npm', files: ['package-lock.json'] }]]

lockfile/version

Enforces lockfile versions to ensure consistency across environments.

// Default: latest versions for each package manager
'lockfile/version': 'error'

// Specific versions
'lockfile/version': ['error', { npm: 3, yarn: 2, pnpm: '9.0' }]

Valid versions:

• npm: 1, 2, 3
• yarn: 1, 2
• pnpm: '5.3', '5.4', '6.0', '6.1', '7.0', '9.0'
• bun: 0, 1
• vlt: 0

lockfile/integrity

Ensures all packages have integrity hashes and verifies they match the actual package tarballs. This protects against supply chain attacks.

// Default: allow all standard algorithms
'lockfile/integrity': 'error'

// Require specific algorithms
'lockfile/integrity': ['error', ['sha512', 'sha384']]

lockfile/registry

Enforces that all packages come from allowed registries. Useful for security policies and private registry enforcement.

// Default: uses npm config registry
'lockfile/registry': 'error'

// Single registry
'lockfile/registry': ['error', 'https://registry.npmjs.org']

// Multiple registries
'lockfile/registry': ['error', ['https://registry.npmjs.org', 'https://npm.pkg.github.com']]

// Per-package registry mapping
'lockfile/registry': ['error', {
	'https://registry.npmjs.org': true,  // Default for all packages
	'https://npm.pkg.github.com': ['@myorg/*'],  // Specific packages
}]

lockfile/non-registry-specifiers

Warns when packages are installed from non-registry sources like GitHub URLs, git URLs, or local file paths. These can bypass integrity checks.

// Warn on all non-registry specifiers
'lockfile/non-registry-specifiers': 'error'

// Ignore specific specifiers with explanation
'lockfile/non-registry-specifiers': ['error', {
	ignore: [
		{
			specifier: 'github:user/repo#commit',
			explanation: 'Required for unreleased bug fix',
		},
	],
}]

lockfile/binary-conflicts

Detects when multiple packages provide command-line binaries with the same name, which can cause non-deterministic behavior.

'lockfile/binary-conflicts': 'error'

CLI

For a standalone CLI that doesn't require ESLint configuration, see lintlock.

Tests

Clone the repo, npm install, and run npm test.

License

MIT