@umbrella.zone/inventory
Lockfile readers of umbrella.zone, the self-hostable, open-source supply-chain security platform for the foss.global stack. It reads a pnpm or npm lockfile offline into an IInventory of @umbrella.zone/interfaces: every installed registry package version as a purl-identified component, with how it is reached, and every reference it could not resolve as a coverage gap.
Reading a lockfile never touches the network. No dependency list leaves the machine.
Issue Reporting and Security
For reporting bugs, issues, or security vulnerabilities, please visit community.foss.global/. This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a code.foss.global/ account to submit Pull Requests directly.
Install
pnpm add @umbrella.zone/inventory
Usage
import { LockfileError, readLockfile } from '@umbrella.zone/inventory';
try {
const inventory = await readLockfile('pnpm-lock.yaml');
console.log(inventory.subject.format, inventory.subject.digest);
for (const component of inventory.components) {
console.log(component.purl, component.scopes.join('+'), component.direct ? 'direct' : 'transitive');
}
for (const gap of inventory.coverage) {
console.log(gap.kind, gap.reason);
}
} catch (error) {
if (error instanceof LockfileError) console.error(error.code, error.message);
else throw error;
}
readLockfile also takes the content instead of a path, as text or bytes, with the path to record: readLockfile({ file: 'pnpm-lock.yaml', content }). parseLockfile({ file, content }) does the same synchronously. Both take { now } to fix createdAt.
Formats
The format is detected from the content, not the file name:
| Format | Files | subject.format |
|---|---|---|
| pnpm lockfile 9.0, one document (pnpm 9 and 10) or two (pnpm 11 and later: the environment, then the project) | pnpm-lock.yaml |
pnpm-lock@9 |
| npm lockfile 2 | package-lock.json, npm-shrinkwrap.json |
npm-lock@2 |
| npm lockfile 3 | package-lock.json, npm-shrinkwrap.json |
npm-lock@3 |
lockfileFileNames lists those names. Older lockfiles (pnpm before 9.0, npm lockfile 1) are refused with unsupported-version.
Components
- One component per registry package version, unique by purl and sorted by purl. pnpm peer variants (
react-dom@18.3.1(react@18.3.1)) and npm's nested copies are one component; annpm:alias is the package it installs. purlfollows the purl specification's npm type:pkg:npm/%40acme/logweave@5.0.0, scope and name lowercased, no qualifiers.namekeeps the registry's spelling.direct: some importer (the root.or a workspace member such aspackages/app) declares it.scopes: per path, the importer field it starts from (dependencies→prod,devDependencies→dev,optionalDependencies→optional; npm importers'peerDependencies→prodandpeer), plusoptionalwhen the path takes an optional edge andpeerwhen it takes a peer edge. A component lists the union over all its paths, in the orderprod,dev,optional,peer. pnpm itself and its platform binaries, as the environment document pins them, count asdev.paths: up to five shortest simple paths, shortest first, ties in code-unit order, each a list of purls ending at the component. A path starts at a component an importer declares. Git, tarball andfile:dependencies and links outside the workspace are crossed without being named. A component an importer reaches only through one of them starts a path of its own (directstaysfalse).locations: one per importer that reaches the component.resolvedis the tarball URL the lockfile records (npm records one per package; pnpm only for registries whose URLs it cannot derive), elsenull.integrityis the lockfile's.- An entry no importer reaches (npm's
extraneous) is listed with no paths, its scopes from npm's flags.
Coverage gaps
Each reference the reader cannot resolve to a registry package version is an ICoverageGap with stage: 'inventory', the reference as the lockfile writes it, the declared name, and its declarer (importer or dependentPurl; both are null when neither an importer nor a component declares it, for example a dependency of a git dependency):
| Kind | What |
|---|---|
git |
git URLs and git-hosted tarballs (codeload.github.com, gitHosted) |
https |
tarball URLs outside the registry |
file |
local tarballs, and file: directories that are no importer of the lockfile |
link |
link: directories that are no importer of the lockfile |
unsupported |
references and resolutions of a kind the reader does not resolve |
unparsed |
entries without a valid name and version, and declared dependencies missing from the lockfile |
A link to a workspace member and an injected workspace package are no gaps: their importer covers them. Missing optional and peer dependencies are no gaps either. The reasons are fixed sentences; they never quote lockfile text.
Errors
LockfileError has a code and the file as given:
unreadable: the file could not be read;unsupported-format: neither a pnpm nor an npm lockfile;unsupported-version: a lockfile version this package does not read;invalid: not valid UTF-8, JSON or YAML, or without the structure its format requires.
Messages quote lockfile values only escaped and truncated.
Data sources and licences
This package reads only the lockfile it is given. It holds no advisory data and fetches nothing.
Exports
readLockfile(path | { file, content }, { now? }):Promise<IInventory>.parseLockfile({ file, content }, { now? }):IInventory.lockfileFileNames:['pnpm-lock.yaml', 'package-lock.json', 'npm-shrinkwrap.json'].LockfileError,TLockfileErrorCode.npmPurl(name, version).- Types:
ILockfileInput,IReadLockfileOptions. The inventory types come from@umbrella.zone/interfaces.
Testing
pnpm test
pnpm exec tsrepo check 'test/**/*'
pnpm run build
License and Legal Information
This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the repository license file.
Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
Trademarks
This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.
Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.
Company Information
Task Venture Capital GmbH
Registered at District Court Bremen HRB 35230 HB, Germany
For any legal inquiries or further information, please contact us via email at hello@task.vc.
By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.