A simple measure of software dependency freshness
npm install @bagaar/libyearlibyear ·   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) 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 version of a dependency (including pre-release). Measured in "libyears".
- releases the number of stable releases between the currently used and latest (stable) versions of a dependency.
- major the number of major releases between the currently used and latest (stable) versions of a dependency.
- minor the number of minor releases between the currently used and latest (stable) versions of a dependency.
- patch the number of patch releases between the currently used and latest (stable) 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.
libyear 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 limit.
If configured, a breach of the limit 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.
``sh`
npx libyear
`sh`
pnpx libyear
`sh`
yarn add --dev libyear
yarn libyear
`sh`
yarn dlx libyear
Include dependencies from the whole project.
Default false.
_Note: This option is only supported when using berry or pnpm package managers._
Path to a libyear configuration file.
Default is automatically resolved by cosmiconfig.
See configuration.
Include dev dependencies.
Default true.--no-dev
Can be disabled with .
_Note: Disabling this option is only supported when using npm or pnpm package managers._
Show help.
Default false.
Outputs the report to the console as valid JSON.
Default false.
Accepts a number.
Default null.
Throws an error if the total drift metric surpasses the limit.
Accepts a number.
Default null.
Throws an error if any individual drift metric surpasses the limit.
Accepts a number.
Default null.
Throws an error if the total pulse metric surpasses the limit.
Accepts a number.
Default null.
Throws an error if any individual pulse metric surpasses the limit.
Accepts an integer.
Default null.
Throws an error if the total stable releases metric surpasses the limit.
Accepts an integer.
Default null.
Throws an error if any individual stable releases metric surpasses the limit.
Accepts an integer.
Default null.
Throws an error if the total major metric surpasses the limit.
Accepts an integer.
Default null.
Throws an error if any individual major metric surpasses the limit.
Accepts an integer.
Default null.
Throws an error if the total minor metric surpasses the limit.
Accepts an integer.
Default null.
Throws an error if any individual minor metric surpasses the limit.
Accepts an integer.
Default null.
Throws an error if the total patch metric surpasses the limit.
Accepts an integer.
Default null.
Throws an error if any individual patch metric surpasses the limit.
Accepts berry, npm, pnpm, yarn.
Default is inferred.
Include pre-releases in latest versions.
Can be disabled with --no-pre-releases.true
Default .
Exclude up-to-date dependencies from results.
Default false.
Column to sort individual results by.
Default null.
libyear can be configured via cosmiconfig-supported formats.
- package.json (under { "configs": { "libyear": { ... } } }).libyearrc
-
-
-
-
-
-
-
-
-
-
-
-
Custom configuration files can be provided via the --config CLI option.
Configuration is expected in the following structure.
`json5`
{
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)
},
},
limit: {
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 limits until the date specified for matching dependencies.drift
- - Override drift limit for matching dependencies.pulse
- - Override pulse limit for matching dependencies.releases
- - Override stable releases limit for matching dependencies.major
- - Override major releases limit for matching dependencies.minor
- - Override minor releases limit for matching dependencies.patch
- - Override patch releases limit for matching dependencies.
To match a specific dependency, make sure to include the starts with (^) and ends with ($) anchors.
`json`
{
"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 limit.
`json`
{
"overrides": {
"^@types/": {
"pulse": null
}
}
}
libyear can be run via a GitHub Action (source code) courtesy of @s0.
Dependencies cannot be ignored from limit 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 limits by setting a date to "defer" enforcement until in the configuration file.
- enforce deprecations
- ci semantic release
- support npm workspaces
- audit vulnerabilities
- include collective metrics in JSON report
- include violations in JSON report
`sh`
corepack enable
yarn install
libyear` is inspired by the package-manager-specific variants of libyear.
- libyear-npm by @jaredbeck
- libyear-yarn by @sbleon