@antongolub/lockfile

lockfile

Read, write, and convert npm (v1, v2) and yarn (classic and berry) lockfiles in any directions with reasonable losses.

Motivation

Every package manager brings its own philosophy of how to describe, store and control projects dependencies. This is awesome for developers, but literally becomes a pain in *** *** headache for isec, devops and release engineers. This lib is a naive attempt to build a pm-independent, generic, extensible and reliable deps representation.

The package manifest contains its own deps requirements, the lockfile defines the deps resolution snapshot^*, so both of them are required to build a dependency graph. We can convert this data into a normalized representation for further analysis and processing (for example, to fix vulnerabilities). And then, if necessary, convert back to the original format.

Status

⚠️ Initial draft. Alpha-version

Getting started

Install

yarn add @antongolub/lockfile

Usage

import { parse, format } from '@antongolub/lockfile'

const parsed = parse({
  lockfile: './yarn.lock',
  workspaces: {'': './package.json', 'foo': './packages/foo/package.json'},
})

// output
{
  entries: {
    '@babel/code-frame@7.10.4': {
      name: '@babel/code-frame',
      version: '7.10.4',
      scope: 'prod/dev/peer/opt',
      integrities: {
        sha512: 'hashsum',
        sha256: '...',
        sha1: '...',
        md5: '...'
      },
      reference: {
        sourceType: 'npm/git/file/workspace'
        source: 'uri://remote/address',
        linkType: 'hard/soft',
        link: '<root>path/to/package'
      },
      dependencies: {
        '@babel/highlight': '^7.10.4'
      }
    },
    ...
  },
  meta: {
    lockfile: {
      type: 'yarn',
      version: '5', // metadata format version
    },
    packageJson: {...},
    workspaces: {
      patterns: ['./packages/*'],
      packages: {
        '@qiwi/pijma-core': '<root>/packages/core/package.json'
      }
    }
  },
}

const data = format({
  ...parsed,
  lockfileType: 'yarn-2'
})
// output
`
# This file is generated by running "yarn install" inside your project.
# Manual changes might be lost - proceed with caution!

__metadata:
  version: 5
  cacheKey: 8

"@babel/code-frame@npm:7.10.4":
  version: 7.10.4
  resolution: "@babel/code-frame@npm:7.10.4"
...
`

Lockfile (meta) versions

Package manager	Meta format	Supported
npm <7	1	x
npm >=7	2
yarn 1 (classic)	1	x
yarn 3	5, 6	x
yarn 4	6, 7

Caveats

• Only npm links are supported for now
• npm1: optional: true label is not supported by lockfile formatter

Inspired by

• synp
• snyk-nodejs-lockfile-parser

License

MIT