Peer Dependency Parser

The Peer Dependency Parser (or Dependency Parser) is a tool for dependency resolution and installation for peer dependencies of a project and all its dependencies. For that, the tool finds those peer dependencies and adds them as dependencies of the project, to assure the correct version throughout the project.

It is a project work of Christian Knauf at the Distributed Systems research group at the University of Kassel.

Current version: 0.1.0

Installation

To be able to use the Peer Dependency Parser on your system, you only have to:

1. Clone the repository
2. Run the build script (or just the command nx build && npm i -g ./dist/interactive)

After that, the CLI (interactive mode) can be used as described below. For usage of the GitHub Action (unattended mode) also refer to the description below.

Usage

The tool is divided into an interactive mode (CLI) for usage on your own system and an unattended mode (GitHub action) to use in CI workflows on GitHub. The usage of either mode is described here.

Interactive Mode

The first mode of the tool is the interactive mode. It can be invoked be one of these two commands:

1. Install command: dp install or dp i
   • This command uses additional arguments with the pattern name@version of the packages/dependencies that should be installed with peer dependencies in mind.
2. Update command: dp update or dp u
   • This command simply updates all packages of the project/repository to the newest version with peer dependencies in mind.

When running the commands, the user is asked some questions where he can adjust the parameters of the (peer) dependency resolution process. These parameters can also be provided by CLI options which can be added to the command. These options are described in the table below.

CLI Option	Shortcut	Description	Allowed value
--all-dependencies	-a	Resolve all dependencies of package.json (without asking)	true / false
--collect-metrics	-c	Collect performance metrics and save to file	true / false
--exclude		Packages to exclude from evaluation (patterns like @nx/* are allowed)	string(s)
--force	-f	Forcibly try every version combination	true / false
--include		Packages to take into account in evaluation (patterns like @nx/* are allowed)	string(s)
--install	-i	Install the resolved dependencies with package manager	true / false
--major-versions		Number of major versions allowed to downgrade	number
--minor-versions		Number of minor versions allowed to downgrade (per major version)	number
--migrate	-m	Run migrations generated by migration tools	true / false
--modify-json	-j	Modify the package.json file after resolution	true / false
--package-manager		The package manager used for installation	npm, pnpm, yarn
--path		Path of the package.json file	true / false
--keep-versions	-k	Keep the versions specified in package.json	true / false
--pre-release	-p	Allow dependencies with pre-release versions (e.g. beta versions)	true / false
--retry	-r	Retry after failed attempts	true / false
--skip-prompts	-s	Skip all user prompts	true / false

Unattended Mode

The second mode of the tool is the unattended mode. For this mode, the tool is also defined as a GitHub action to be used in CI workflows in GitHub runners.

This project provides an example workflow that shows the usage in CI workflows. It is found in the folder .github/workflows/example.yaml. The parameters of the execution have to be provided by GitHub action inputs. These inputs are the following for the Dependency Parser:

Input	Description	Default
package-json-path	The relative path of the package.json file of the project to update	.
allowed-major-versions	Number of major versions allowed to downgrade	2
allowed-minor-versions	Number of minor versions allowed per major version	10
allow-pre-releases	Allow dependencies with pre-release versions (e.g. beta versions)	false
exclude	Packages to exclude from evaluation, separated by spaces (patterns like @nx/* are allowed)	""
force	Forcibly try every version combination	false
include	Packages to take into account in evaluation, separated by spaces (patterns like @nx/* are allowed)	""
keep-versions	Keep the versions specified in package.json	false

Keep in mind, that the Dependency Parser GitHub action itself only executes the (peer) dependency resolution. The installation and creation of pull requests (for example) are made by other actions in the workflow.