2026-11-18 13:29:39 +00:00
2026-11-18 13:29:39 +00:00
2026-11-18 13:12:05 +00:00
2026-11-18 13:12:05 +00:00
2026-11-18 13:29:39 +00:00
2026-11-18 13:12:05 +00:00
2026-11-18 13:29:39 +00:00
2026-11-18 13:12:05 +00:00
2026-11-18 13:12:05 +00:00
2026-11-18 13:12:05 +00:00

@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; an npm: alias is the package it installs.
  • purl follows the purl specification's npm type: pkg:npm/%40acme/logweave@5.0.0, scope and name lowercased, no qualifiers. name keeps the registry's spelling.
  • direct: some importer (the root . or a workspace member such as packages/app) declares it.
  • scopes: per path, the importer field it starts from (dependencies → prod, devDependencies → dev, optionalDependencies → optional; npm importers' peerDependencies → prod and peer), plus optional when the path takes an optional edge and peer when it takes a peer edge. A component lists the union over all its paths, in the order prod, dev, optional, peer. pnpm itself and its platform binaries, as the environment document pins them, count as dev.
  • 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 and file: 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 (direct stays false).
  • locations: one per importer that reaches the component.
  • resolved is the tarball URL the lockfile records (npm records one per package; pnpm only for registries whose URLs it cannot derive), else null. integrity is 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

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.

S
Description
Reads lockfiles (pnpm, npm) into umbrella.zone inventories with coverage gaps.
Readme MIT
147 KiB
0 Stars 3 Watchers 0 Forks
Languages
TypeScript 100%