libyear · 
A Node.js implementation of libyear.
A simple measure of software dependency freshness. It is a single number telling you how up-to-date your dependencies are.
drift representing "dependency drift"; the time between the release of the currently used and latest (stable) available versions of a dependency. Measured in "libyears".pulse representing "pulse check", an indication of a dependency's activity; the time since the release of the latest available version of a dependency (including pre-release). Measured in "libyears".releases the number of stable releases between the currently used and latest (stable) available versions of a dependency.major the number of major releases between the currently used and latest (stable) available versions of a dependency.minor the number of minor releases between the currently used and latest (stable) available versions of a dependency.patch the number of patch releases between the currently used and latest (stable) available versions of a dependency.All metrics are calculated against dependencies both collectively and individually.
Dependency drift fitness function is a technique to introduce a specific evolutionary architecture fitness function to track dependencies over time, giving an indication of the possible work needed and whether a potential issue is getting better or worse.
Newer versions of dependencies may include bug fixes and security vulnerability patches. These fixes are often released in "patch" versions which are backwards-compatible.
Newer versions of dependencies may include performance improvements and new features/capabilities. These enhancements are often released in "minor" versions which are backwards-compatible.
The fixes and features released by dependency authors often filter down to the consumer packages.
A practice of regular dependency maintenance begets smaller changes and easier upgrades. Continual evolution of the code avoids rewrites. When using the most recent versions of a dependency there is better alignment with documentation.
It is difficult to find volunteers to maintain legacy code. Modern stacks attract developers.
libyearlibyear offers a package-manager-agnostic tool to measure dependency freshness for Node.js environments.
On top of the most commonly referenced "dependency drift" fitness function,
libyear tracks additional metrics like "pulse" and "releases".
"drift" is useful as a guideline to determine when dependencies should be updated.
"pulse" is useful for identifying dependencies that may no longer be maintained.
"releases" is an alternate measure of "drift" based on discrete versions rather than time.
"major", "minor", and "patch" provide more granular metrics for "releases".
Each metric can be configured with a threshold. If configured, a breach of the threshold will exit the process with a failure code. This may be used in CI as a quality gate, or as a cron job to trigger an alert when the debt gets too high.
If dependencies are already up-to-date, libyear tracks upcoming versions of dependencies, providing timely notice to prepare for stable releases.
npmnpx libyear
pnpmpnpx libyear
yarn@1 (yarn classic)yarn add --dev libyear
yarn libyear
yarn@2 (yarn berry)yarn dlx libyear
--config=<path>Path to a libyear configuration file. Default is automatically resolved by cosmiconfig. See configuration.
--package-managerAccepts berry, npm, pnpm, yarn.
Default is inferred.
--allInclude dependencies from the whole project.
Default false.
Note: This option is only supported when using berry or pnpm package managers.
--jsonOutputs the report to the console as valid JSON.
Default false.
--threshold-drift-collective=<libyears> (-D=<libyears>)Accepts a number.
Default null.
Throws an error if the total drift metric surpasses the threshold.
--threshold-drift-individual=<libyears> (-d=<libyears>)Accepts a number.
Default null.
Throws an error if any individual drift metric surpasses the threshold.
--threshold-pulse-collective=<libyears> (-P=<libyears>)Accepts a number.
Default null.
Throws an error if the total pulse metric surpasses the threshold.
--threshold-pulse-individual=<libyears> (-p=<libyears>)Accepts a number.
Default null.
Throws an error if any individual pulse metric surpasses the threshold.
--threshold-releases-collective=<count> (-R=<count>)Accepts an integer.
Default null.
Throws an error if the total stable releases metric surpasses the threshold.
--threshold-releases-individual=<count> (-r=<count>)Accepts an integer.
Default null.
Throws an error if any individual stable releases metric surpasses the threshold.
--threshold-major-collective=<count>Accepts an integer.
Default null.
Throws an error if the total major metric surpasses the threshold.
--threshold-major-individual=<count>Accepts an integer.
Default null.
Throws an error if any individual major metric surpasses the threshold.
--threshold-minor-collective=<count>Accepts an integer.
Default null.
Throws an error if the total minor metric surpasses the threshold.
--threshold-minor-individual=<count>Accepts an integer.
Default null.
Throws an error if any individual minor metric surpasses the threshold.
--threshold-patch-collective=<count>Accepts an integer.
Default null.
Throws an error if the total patch metric surpasses the threshold.
--threshold-patch-individual=<count>Accepts an integer.
Default null.
Throws an error if any individual patch metric surpasses the threshold.
libyear can be configured via cosmiconfig-supported formats.
package.json (under { "configs": { "libyear": { ... } } }).libyearrc.libyearrc.cjs.libyearrc.js.libyearrc.json.libyearrc.yaml.libyearrc.ymllibyear.config.cjslibyear.config.jsCustom configuration files can be provided via the --config CLI option.
Configuration is expected in the following structure.
{
overrides: {
"^@types/": {
defer: "2020-01-01", // string (ISO formatted Date)
drift: null, // number (default: null)
pulse: null, // number (default: null)
releases: null, // integer (default: null)
major: null, // integer (default: null)
minor: null, // integer (default: null)
patch: null, // integer (default: null)
},
},
threshold: {
drift: {
collective: null, // number (default: null)
individual: null, // number (default: null)
},
pulse: {
collective: null, // number (default: null)
individual: null, // number (default: null)
},
releases: {
collective: null, // integer (default: null)
individual: null, // integer (default: null)
},
major: {
collective: null, // integer (default: null)
individual: null, // integer (default: null)
},
minor: {
collective: null, // integer (default: null)
individual: null, // integer (default: null)
},
patch: {
collective: null, // integer (default: null)
individual: null, // integer (default: null)
},
},
}
Configuration files support an overrides property.
Each property in the object maps a regular expression to a collection of options.
defer - Defer enforcing any thresholds until the date specified for matching dependencies.drift - Override drift threshold for matching dependencies.pulse - Override pulse threshold for matching dependencies.releases - Override stable releases threshold for matching dependencies.major - Override major releases threshold for matching dependencies.minor - Override minor releases threshold for matching dependencies.patch - Override patch releases threshold for matching dependencies.To match a specific dependency, make sure to include the starts with (^) and ends with ($) anchors.
{
"overrides": {
"^libyear$": {}
}
}
There may be cases where matching many dependencies is desired. For instance, type definitions are often updated less regularly than source code. To cater for this case, we can set a more lenient pulse threshold.
{
"overrides": {
"^@types/": {
"pulse": null
}
}
}
libyear can be run via a GitHub Action (source code) courtesy of @s0.
Dependencies cannot be ignored from threshold checks by design. If a package cannot be upgraded at a particular point in time, then it should be re-reviewed at a later date. Packages can be temporarily excused from complying to thresholds by setting a date to "defer" enforcement until in the configuration file.
libyear is inspired by the package-manager-specific variants of libyear.
FAQs
A simple measure of software dependency freshness
We found that libyear demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.
Security News
The Ultralytics' PyPI Package was compromised four times in one weekend through GitHub Actions cache poisoning and failure to rotate previously compromised API tokens.