📦 oss-matryoshka

Who brought this dependency? Visualize how dependencies were introduced via dependency chains (OSS Matryoshka).

oss-matryoshka is a CLI tool that explains why a dependency exists in your Node.js project by visualizing dependency chains as readable trees.

📥 Installation

npm install -g oss-matryoshka

or

npx oss-matryoshka graph

🚀 Quick Start

oss-matryoshka graph --targets stackback

This generates Markdown files showing how stackback was pulled into your project, using the auto-detected lock file.

Options

All options are optional. If omitted, sensible defaults are applied.

| Option | Required? | Description | | --------------------------- | :-------: | ------------------------------------------------------------------- | | --lock <path> | No | Explicit lock file path. Overrides auto-detection. | | --targets <pkg,...> | No | Target packages to focus on. If omitted, all packages are included. | | --out <path> | No | Output file path. If omitted, a default filename is generated. | | --roots <prod\|dev\|both> | No | Dependency roots to analyze (default: both). | | --format <md\|txt\|json> | No | Output format (default: md). | | --max-depth <n> | No | Maximum tree depth (default: unlimited). | | --max-nodes <n> | No | Maximum number of nodes (default: unlimited). |

🔍 Lock File Detection

If --lock is not specified, oss-matryoshka looks for package-lock.json in the current directory. If none is found, it returns an error.

📄 Default Output Naming

When --out is omitted, files are generated in the current directory.

Format -> Extension

| Format | Extension | | -------------- | --------- | | md (default) | .md | | txt | .txt | | json | .json |

🔹 Without targets

| Lock file | Output | | ----------------- | ------------------------------ | | package-lock.json | oss-matryoshka.{ext} |

🔹 With targets

oss-matryoshka-{targets}.{ext}

Examples:

oss-matryoshka-stackback.md
oss-matryoshka-foo_bar.md

• Scoped packages (@scope/pkg) are normalized to scope-pkg
• Multiple targets are joined with _
• For long names, use --out

📜 Output Example (Markdown)

Markdown format lists each root package and shows its dependency tree in a fenced block.

- vitest
  ```
  vitest
  └─ why-is-node-running
     └─ stackback
  ```

Why oss-matryoshka

• Explains why a dependency exists
• Produces review-ready Markdown
• Avoids noisy full listings
• Ideal for license / security / audit explanations

🚫 Non-Goals

• License or legal judgment
• Dependency removal
• Build artifact inspection
• Automated decisions

🧪 Supported Environments

• Node.js projects with package-lock.json (npm)
• SPA / SSG / SSR / libraries