Case · CLI tool · TypeScript

lockweigh: "weighs" a lock file

A TypeScript CLI with no runtime dependencies: it reads package-lock.json (v2, v3), pnpm-lock.yaml (v9) and yarn.lock (classic v1) and shows how many packages a project has, who pulls duplicate versions, which subtrees are heaviest, where install scripts are and which licences, plus why a package is in the project (why) and what changed between two lock files (diff). The parsers, including a YAML subset, are written from scratch. It works offline and executes nothing.

  • TypeScript
  • Node.js
  • esbuild
  • Node SEA
  • YAML parser
  • vitest
  • GitHub Actions
Code on request via Telegram

01 · How it looks

Screenshots

Screenshot of the project "lockweigh: "weighs" a lock file" at 1280 pixels wide
Desktop, 1280 px
Screenshot of the project "lockweigh: "weighs" a lock file" on a phone screen, 390 pixels wide
Phone, 390 px

02 · About

What it is and why

The task: quickly see what a project's dependency tree really consists of, without running anything from it and without a network.

The solution: TypeScript with no runtime dependencies. Parsers for package-lock.json (v2, v3), pnpm-lock.yaml (v9, with a YAML subset) and yarn.lock (v1) are written from scratch; one esbuild bundle and a single executable through Node SEA.

Limitations

Real npm lock files hold almost no package sizes, so the size ranking is usually unavailable and honestly marked.

package-lock v1, pnpm before v9, Yarn Berry and bun.lock are unsupported.

In graphs above 20,000 packages the subtree ranking covers only direct dependencies.

A learning project: not published to npm.

What is inside

  • A summary: package count, unique versions and names, direct dependencies, prod/dev/optional, graph depth by the shortest path
  • Duplicate versions with who pulls which; heavy subtrees; install scripts and "native" packages (a heuristic, marked as such)
  • The why command: every path from the root to a package with a step budget; the diff command for two lock files
  • A real run on the express fixture (npm install express cors morgan): 73 packages, depth 7, 2 duplicate versions (debug 2.6.9 and 4.4.3)
  • 77 vitest tests; exit codes for CI with thresholds on package count, duplicates and install scripts
  • CI runs npm audit and gitleaks; builds for Windows, Linux and macOS are uploaded as artifacts

03 · How to run

Run it locally

git clone <repository on request> lockweigh
cd lockweigh
npm ci && npm run build
node dist/lockweigh.cjs package-lock.json --top 5

04 · Code

The repository is private

The source is in a private repository. Message me on Telegram and I will open access.

Request the code