tessl/npm-conventional-recommended-bump

Get a recommended version bump based on conventional commits.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Command-Line Interface

Name: tessl/npm-conventional-recommended-bump
Author: tessl

The conventional-recommended-bump CLI provides a command-line interface for integrating version bump recommendations into scripts, CI/CD pipelines, and automated release workflows.

Capabilities

Basic Command

Execute version bump analysis from the command line.

conventional-recommended-bump [options]

Basic Usage:

# Basic usage (requires preset or config)
conventional-recommended-bump --preset angular

# With verbose output
conventional-recommended-bump --preset angular --verbose

# Using configuration file
conventional-recommended-bump --config ./bump-config.js

Output:

Success: Prints the recommended release type (major, minor, or patch)
No recommendation: No output (exit code 0)
With --verbose: Also prints the reason for the recommendation

Preset Configuration

Specify a conventional commit preset to use for analysis.

--preset, -p <preset-name>

Usage Examples:

# Use Angular preset
conventional-recommended-bump --preset angular

# Use Atom preset  
conventional-recommended-bump --preset atom

# Use ESLint preset
conventional-recommended-bump --preset eslint

Supported Presets:

angular - Angular conventional commit format
atom - Atom editor conventional commit format
codemirror - CodeMirror conventional commit format
ember - Ember.js conventional commit format
eslint - ESLint conventional commit format
express - Express.js conventional commit format
jquery - jQuery conventional commit format

Configuration File

Load configuration from a JavaScript or JSON file.

--config, -g <filepath>

Usage Examples:

# Load from JavaScript file
conventional-recommended-bump --config ./bump-config.js

# Load from JSON file
conventional-recommended-bump --config ./bump-config.json

Configuration File Format:

// bump-config.js
export default {
  whatBump: (commits) => {
    // Custom bump logic
    const hasBreaking = commits.some(c => c.notes.some(n => n.title === 'BREAKING CHANGE'));
    if (hasBreaking) return { level: 0, reason: 'Breaking changes detected' };
    
    const hasFeature = commits.some(c => c.type === 'feat');
    if (hasFeature) return { level: 1, reason: 'New features added' };
    
    return { level: 2, reason: 'Bug fixes and improvements' };
  },
  tags: {
    prefix: 'v',
    skipUnstable: true
  },
  commits: {
    path: './src'
  },
  parser: {
    headerPattern: /^(\w*)(?:\((.*)\))?: (.*)$/,
    headerCorrespondence: ['type', 'scope', 'subject']
  }
};

Tag Options

Configure how git tags are analyzed for version determination.

--tag-prefix, -t <prefix>        # Tag prefix to consider
--lerna-package, -l <package>    # Lerna package name for scoped analysis  
--skip-unstable                  # Skip unstable tags (e.g., alpha, beta, rc)

Usage Examples:

# Use 'v' prefix for tags
conventional-recommended-bump --preset angular --tag-prefix v

# Analyze specific Lerna package
conventional-recommended-bump --preset angular --lerna-package my-package

# Skip unstable versions
conventional-recommended-bump --preset angular --skip-unstable

# Combine tag options
conventional-recommended-bump --preset angular --tag-prefix v --skip-unstable

Commit Options

Configure which commits to analyze for version bump determination.

--commit-path <path>             # Analyze commits affecting specific directory

Usage Examples:

# Analyze commits affecting specific directory
conventional-recommended-bump --preset angular --commit-path ./src

# Analyze commits affecting multiple paths (use multiple flags)
conventional-recommended-bump --preset angular --commit-path ./src --commit-path ./lib

Parser Options

Customize conventional commit message parsing with regex patterns and field mappings.

--header-pattern, -h <pattern>           # Regex to match commit header
--header-correspondence, -c <fields>     # Comma-separated field mapping
--reference-actions, -r <actions>        # Comma-separated reference keywords
--issue-prefixes, -i <prefixes>          # Comma-separated issue prefixes
--note-keywords, -n <keywords>           # Comma-separated note keywords  
--field-pattern, -f <pattern>            # Regex to match other fields
--revert-pattern <pattern>               # Regex pattern for revert commits
--revert-correspondence <fields>         # Comma-separated revert field mapping
--merge-pattern <pattern>                # Regex pattern for merge commits

Usage Examples:

# Custom header pattern
conventional-recommended-bump --preset angular \
  --header-pattern "^(\w*)(?:\((.*)\))?: (.*)$" \
  --header-correspondence "type,scope,subject"

# Custom reference actions
conventional-recommended-bump --preset angular \
  --reference-actions "close,closes,closed,fix,fixes,fixed,resolve,resolves,resolved"

# Custom issue prefixes
conventional-recommended-bump --preset angular \
  --issue-prefixes "#,gh-"

# Custom note keywords
conventional-recommended-bump --preset angular \
  --note-keywords "BREAKING CHANGE,BREAKING CHANGES,DEPRECATED"

Output Options

Control CLI output verbosity and format.

--verbose, -v                    # Enable verbose output with reasons

Usage Examples:

# Basic output (release type only)
conventional-recommended-bump --preset angular
# Output: patch

# Verbose output (includes reason)
conventional-recommended-bump --preset angular --verbose
# Output: 
# patch
# Reason: Bug fixes and improvements detected

Complete CLI Examples

CI/CD Integration

#!/bin/bash
# release.sh - Automated release script

# Get recommended bump
BUMP=$(conventional-recommended-bump --preset angular --tag-prefix v)

if [ -n "$BUMP" ]; then
  echo "Recommended bump: $BUMP"
  
  # Update version using npm
  npm version $BUMP --git-tag-version=false
  
  # Create git tag
  NEW_VERSION=$(node -p "require('./package.json').version")
  git tag "v$NEW_VERSION"
  
  echo "Released version v$NEW_VERSION"
else
  echo "No version bump recommended"
fi

Monorepo Package Analysis

# Analyze specific package in monorepo
conventional-recommended-bump \
  --preset angular \
  --lerna-package my-ui-components \
  --commit-path packages/ui-components \
  --verbose

Custom Parsing Configuration

# Use custom commit format parsing
conventional-recommended-bump \
  --preset angular \
  --header-pattern "^\[(\w+)\]\s*(.*)$" \
  --header-correspondence "type,subject" \
  --note-keywords "BREAKING,DEPRECATED" \
  --verbose

Exit Codes

0 - Success (with or without bump recommendation)
1 - Error (invalid configuration, git errors, etc.)

Integration Tips

CI/CD Pipelines: Use in GitHub Actions, GitLab CI, or other CI systems to automate version bumping
Release Scripts: Integrate with npm version, git tag, and changelog generation tools
Monorepos: Use --lerna-package and --commit-path for package-specific analysis
Custom Formats: Use parser options to support non-standard commit message formats